import { clampInt, trimString } from './lib/client.ts' import { ATTENTION_REASONS, type AttentionPr, type AttentionReason, type ClassifyOptions, type SuggestedAction, classifySession, compareScanOrder, decodeCursor, encodeCursor, findCommitInJson, isActivelyWorking, isAfterKey, sameCommit, sessionPrs, } from './lib/attention.ts' import { DEFAULT_GITHUB_ACCOUNT, commitIncludedIn, fetchAllMessages, fetchGithubPr, mapConcurrent, withRetry, } from './lib/attention-runtime.ts' import { listSessions, type Session } from './sessions.ts' export { ATTENTION_REASONS, classifySession, type AttentionReason, type SuggestedAction, } from './lib/attention.ts' export type NeedsAttentionParams = ClassifyOptions & { orgId?: string /** ISO date-time; only sessions updated at or after it. Default: 30 days ago. */ updatedSince?: string /** Include archived sessions (default false). Archived sessions are never `stale`. */ includeArchived?: boolean /** Max sessions to scan in this call; the rest come back through `nextCursor`. */ limit?: number /** `nextCursor` from a previous call. Pass the same other inputs again. */ cursor?: string /** Wall-clock budget for this call in ms (default 20000, 5000 to 280000). */ timeBudgetMs?: number /** Parallel Devin message reads (default 16, max 32). */ concurrency?: number /** GitHub account alias for `@kentcdodds/github/request` (default `kent`). */ githubAccount?: string /** Also read merge commits for merged PRs on non-stale flagged sessions (default false; deploy_stuck always gets them). */ resolveMergeCommits?: boolean /** Only return these reasons in `sessions` (summary counts still cover every reason). */ reasons?: AttentionReason[] /** Include `lastDevinMessage`, `questions`, and status fields on stale sessions (default false, keeps output small). */ includeStaleMessages?: boolean /** Max stale sessions listed in `sessions` (default 100, max 1000). Every stale id is still in `byReason.stale`. */ maxStaleSessions?: number /** Commit the live deployment serves; enables `includedInLive` on deploy_stuck sessions. */ liveCommit?: string /** URL whose JSON includes the live commit (for example a /health endpoint). Used when `liveCommit` is not given. */ healthUrl?: string } export type AttentionSession = { devinId: string title: string | null url: string | null /** Omitted on compact stale entries. */ status?: string | null statusDetail?: string | null reason: AttentionReason uiOnly?: boolean detection?: 'status' | 'message' /** Sentence that triggered a message-based reason. */ evidence?: string ageHours: number | null /** Omitted on compact stale entries. */ lastDevinMessage?: string | null questions?: string[] prs: AttentionPr[] suggestedAction: SuggestedAction includedInLive?: boolean | null } export type NeedsAttentionResult = { sessions: AttentionSession[] byReason: Record summary: { counts: Record flagged: number totalScanned: number scannedThisCall: number remaining: number elapsedMs: number liveCommit?: string | null } nextCursor?: string warnings?: string[] errors?: Array<{ devinId: string; message: string }> } function emptyByReason(make: () => T): Record { return Object.fromEntries(ATTENTION_REASONS.map((r) => [r, make()])) as Record< AttentionReason, T > } function parseSince(value: unknown): number { const text = trimString(value) if (!text) return Math.floor(Date.now() / 1000) - 30 * 86400 const ms = Date.parse(text) if (!Number.isFinite(ms)) throw new Error('updatedSince must be an ISO date-time string.') return Math.floor(ms / 1000) } async function listAllInWindow(params: { orgId?: string since: number includeArchived: boolean }): Promise { const items: Session[] = [] let after: string | undefined for (let page = 0; page < 25; page++) { const result = await withRetry(() => listSessions({ orgId: params.orgId, first: 200, after, updatedAfter: params.since, isArchived: params.includeArchived ? undefined : false, }), ) items.push(...(result.items ?? [])) if (!result.has_next_page || !result.end_cursor) break after = result.end_cursor } return items } async function resolveLiveCommit( params: NeedsAttentionParams, warnings: string[], ): Promise { const explicit = trimString(params.liveCommit) if (explicit) return explicit.toLowerCase() const healthUrl = trimString(params.healthUrl) if (!healthUrl) return null try { const response = await fetch(healthUrl, { headers: { Accept: 'application/json' }, signal: AbortSignal.timeout(6000), }) const body = await response.json() const commit = findCommitInJson(body) if (!commit) warnings.push('healthUrl JSON had no commit-like field; includedInLive skipped.') return commit } catch (error) { warnings.push(`healthUrl read failed (${(error as Error).message}); includedInLive skipped.`) return null } } /** * Find Devin sessions that need a human: blocked on a reply, a UI-only * approval card, a product/owner decision, a deploy check after merge, or * finished with merged/closed PRs (stale, archivable). * * Read-only. Handles pagination internally, reads messages concurrently, and * stops at `timeBudgetMs`; when it stops early it returns what it has plus * `nextCursor`. Pass that back as `cursor` (with the same other inputs) to * continue. * * Detection notes: `approval_pending` is reliable only for * `status_detail: 'waiting_for_approval'`. UI-only suggestion cards (for * example environment or repo setup suggestions) are not exposed by the * Devin API, so they are only caught when Devin's own message mentions them * (`detection: 'message'`). * * @example * import listSessionsNeedingAttention from 'kody:@kentcdodds/devin/sessions/needs-attention' * const result = await listSessionsNeedingAttention({ ownerNames: ['Sam'] }) * // => { sessions: [...], byReason: {...}, summary: { counts, totalScanned }, nextCursor? } */ export async function listSessionsNeedingAttention( params: NeedsAttentionParams = {}, ): Promise { const started = Date.now() const budget = clampInt(params.timeBudgetMs, 5000, 280000, 20000) const reserve = Math.min(5000, Math.floor(budget * 0.25)) const scanDeadline = started + budget - reserve const hardDeadline = started + budget - 1000 const concurrency = clampInt(params.concurrency, 1, 32, 16) const account = trimString(params.githubAccount) || DEFAULT_GITHUB_ACCOUNT const warnings: string[] = [] const errors: Array<{ devinId: string; message: string }> = [] const cursor = decodeCursor(params.cursor) const since = cursor?.since ?? parseSince(params.updatedSince) const includeArchived = cursor?.includeArchived ?? params.includeArchived === true const listed = await listAllInWindow({ orgId: params.orgId, since, includeArchived }) listed.sort(compareScanOrder) const pending = cursor ? listed.filter((s) => isAfterKey(s, cursor.after)) : listed const limit = params.limit === undefined ? pending.length : clampInt(params.limit, 1, 5000, pending.length) const batch = pending.slice(0, limit) type Row = { session: Session; classification: ReturnType } const { results, started: startedCount } = await mapConcurrent( batch, concurrency, async (session): Promise => { try { let prs = sessionPrs(session) if (isActivelyWorking(session) && session.status_detail !== 'waiting_for_approval') { return { session, classification: classifySession(session, [], { ...params, prs }) } } const messages = await fetchAllMessages(session.session_id, params.orgId) if (prs.some((pr) => pr.state === 'unknown')) { prs = await Promise.all( prs.map((pr) => pr.state === 'unknown' ? fetchGithubPr(pr, account).catch(() => pr) : pr, ), ) } return { session, classification: classifySession(session, messages, { ...params, prs }) } } catch (error) { errors.push({ devinId: session.session_id, message: (error as Error).message }) return undefined } }, () => Date.now() < scanDeadline, ) const scannedThisCall = startedCount const flagged: AttentionSession[] = [] for (const row of results.slice(0, startedCount)) { if (!row || !row.classification.reason) continue const { session, classification: c } = row const reason = c.reason as AttentionReason const slim = reason === 'stale' && params.includeStaleMessages !== true if (slim) { flagged.push({ devinId: session.session_id, title: session.title ?? null, url: session.url ?? null, reason, ageHours: c.ageHours, prs: c.prs, suggestedAction: c.suggestedAction, }) continue } flagged.push({ devinId: session.session_id, title: session.title ?? null, url: session.url ?? null, status: session.status ?? null, statusDetail: session.status_detail ?? null, reason, ...(c.uiOnly ? { uiOnly: true } : {}), ...(c.detection ? { detection: c.detection } : {}), ...(c.evidence ? { evidence: c.evidence } : {}), ageHours: c.ageHours, lastDevinMessage: c.lastDevinMessage, questions: c.questions, prs: c.prs, suggestedAction: c.suggestedAction, }) } // Merge commits (always for deploy_stuck, optional for other non-stale items). const needCommits = flagged.filter( (s) => s.reason === 'deploy_stuck' || (params.resolveMergeCommits === true && s.reason !== 'stale'), ) let skippedCommits = 0 await mapConcurrent( needCommits, Math.min(concurrency, 8), async (item) => { item.prs = await Promise.all( item.prs.map(async (pr) => { if (pr.state !== 'merged' || pr.mergeCommit) return pr try { return await fetchGithubPr(pr, account) } catch (error) { warnings.push(`Merge commit read failed for ${pr.url}: ${(error as Error).message}`) return pr } }), ) }, () => { const ok = Date.now() < hardDeadline if (!ok) skippedCommits += 1 return ok }, ) if (skippedCommits) warnings.push('Ran out of time before reading every merge commit.') const liveCommit = flagged.some((s) => s.reason === 'deploy_stuck') ? await resolveLiveCommit(params, warnings) : null if (liveCommit) { for (const item of flagged.filter((s) => s.reason === 'deploy_stuck')) { const merged = item.prs.filter((pr) => pr.state === 'merged' && pr.mergeCommit) if (!merged.length || Date.now() >= hardDeadline) { item.includedInLive = null continue } const checks = await Promise.all( merged.map((pr) => sameCommit(pr.mergeCommit!, liveCommit) ? Promise.resolve(true) : commitIncludedIn(pr.url, pr.mergeCommit!, liveCommit, account).catch(() => null), ), ) item.includedInLive = checks.every((c) => c === true) ? true : checks.some((c) => c === false) ? false : null if (item.includedInLive === true) item.suggestedAction = 'archive' } } const wanted = Array.isArray(params.reasons) && params.reasons.length ? new Set(params.reasons) : null const order = new Map(ATTENTION_REASONS.map((r, i) => [r, i])) flagged.sort( (a, b) => order.get(a.reason)! - order.get(b.reason)! || Number(a.ageHours ?? 0) - Number(b.ageHours ?? 0), ) const byReason = emptyByReason(() => []) const counts = emptyByReason(() => 0) for (const item of flagged) { if (!wanted || wanted.has(item.reason)) byReason[item.reason].push(item.devinId) counts[item.reason] += 1 } const totalScanned = (cursor?.scanned ?? 0) + scannedThisCall const remaining = pending.length - scannedThisCall const maxStale = clampInt(params.maxStaleSessions, 0, 1000, 100) let staleListed = 0 const listedSessions = flagged.filter((s) => { if (wanted && !wanted.has(s.reason)) return false if (s.reason !== 'stale') return true staleListed += 1 return staleListed <= maxStale }) if (staleListed > maxStale) { warnings.push( `Listed ${maxStale} of ${staleListed} stale sessions; every stale id is in byReason.stale (raise maxStaleSessions to list more).`, ) } const result: NeedsAttentionResult = { sessions: listedSessions, byReason, summary: { counts, flagged: flagged.length, totalScanned, scannedThisCall, remaining, elapsedMs: Date.now() - started, ...(liveCommit ? { liveCommit } : {}), }, } if (remaining > 0 && scannedThisCall > 0) { const lastSession = batch[scannedThisCall - 1]! result.nextCursor = encodeCursor({ v: 1, since, includeArchived, after: [Number(lastSession.created_at ?? 0), lastSession.session_id], scanned: totalScanned, }) } else if (remaining > 0) { warnings.push('No sessions scanned in this call; raise timeBudgetMs.') } if (warnings.length) result.warnings = [...new Set(warnings)] if (errors.length) result.errors = errors return result } export default listSessionsNeedingAttention