Skip to content
← Public packages

@kentcdodds/devin

Start, monitor, and manage Devin sessions, knowledge, playbooks, and schedules via the Devin v3 API

FollowFork

Files

sessions-needs-attention.ts

391 lines · 12.7 KB · TypeScript
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