← Public packages
@kentcdodds/devin
Start, monitor, and manage Devin sessions, knowledge, playbooks, and schedules via the Devin v3 API
Files
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<AttentionReason, string[]>
summary: {
counts: Record<AttentionReason, number>
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<T>(make: () => T): Record<AttentionReason, T> {
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<Session[]> {
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<string | null> {
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<NeedsAttentionResult> {
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<typeof classifySession> }
const { results, started: startedCount } = await mapConcurrent(
batch,
concurrency,
async (session): Promise<Row | undefined> => {
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<string[]>(() => [])
const counts = emptyByReason<number>(() => 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