Skip to content
← Public packages

@kentcdodds/devin

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

FollowFork

Files

attention.ts

484 lines · 17.5 KB · TypeScript
/**
 * Pure classification helpers for `./sessions/needs-attention` and
 * `./sessions/archive-stale`. No network and no `kody:` imports, so the
 * logic is testable with fixtures.
 */

export type AttentionReason =
	| 'approval_pending'
	| 'needs_human_decision'
	| 'awaiting_user'
	| 'deploy_stuck'
	| 'stale'

export const ATTENTION_REASONS: AttentionReason[] = [
	'approval_pending',
	'needs_human_decision',
	'awaiting_user',
	'deploy_stuck',
	'stale',
]

export type SuggestedAction =
	| 'reply'
	| 'check_deploy'
	| 'archive'
	| 'none'
	| string

export type PrState = 'open' | 'merged' | 'closed' | 'unknown'

export type AttentionPr = {
	url: string
	state: PrState
	mergeCommit: string | null
}

export type AttentionMessage = {
	source?: string | null
	message?: string | null
	created_at?: number | null
}

export type AttentionSessionInput = {
	session_id: string
	title?: string | null
	url?: string | null
	status?: string | null
	status_detail?: string | null
	is_archived?: boolean | null
	updated_at?: number | null
	created_at?: number | null
	pull_requests?: Array<{
		pr_url?: string | null
		url?: string | null
		pr_state?: string | null
		state?: string | null
	}> | null
}

export type ClassifyOptions = {
	/** Extra plain-text phrases (case-insensitive) that mean "needs a human decision". */
	decisionKeywords?: string[]
	/**
	 * Names of the people who make owner decisions. Each adds phrases like
	 * "needs <name>", "needs-<name>", "decision for <name>", "<name>'s call",
	 * and "waiting on <name>".
	 */
	ownerNames?: string[]
	/** Include the `stale` reason (default true). */
	includeStale?: boolean
	/** Value used for `suggestedAction` on decision and UI approval items (default `ping_owner`). */
	decisionAction?: string
	/** Max characters for `lastDevinMessage` (default 600). */
	messageChars?: number
	/** Current time in ms (tests). */
	now?: number
}

export type Classification = {
	reason: AttentionReason | null
	suggestedAction: SuggestedAction
	uiOnly?: boolean
	/** How the reason was detected: an API status field or message text. */
	detection?: 'status' | 'message'
	/** The sentence that triggered a message-based reason (trimmed). */
	evidence?: string
	questions: string[]
	lastDevinMessage: string | null
	lastActivityAt: number | null
	ageHours: number | null
	prs: AttentionPr[]
	activelyWorking: boolean
}

const ATTACHMENT_LINE = /^\s*ATTACHMENT:\s*\{.*\}\s*$/gm

/** Strip attachment markers Devin appends to messages and trim. */
export function cleanMessage(text: unknown): string {
	if (typeof text !== 'string') return ''
	return text.replace(ATTACHMENT_LINE, '').replace(/\n{3,}/g, '\n\n').trim()
}

/** Keep the start and the end (where the ask usually is) of long text. */
export function trimMiddle(text: string, max = 600): string {
	if (text.length <= max) return text
	const head = Math.floor(max / 3)
	const tail = max - head - 3
	return `${text.slice(0, head).trimEnd()} … ${text.slice(-tail).trimStart()}`
}

function stripMarkdown(text: string): string {
	return text
		.replace(/```[\s\S]*?```/g, ' ')
		.replace(/`([^`]*)`/g, '$1')
		.replace(/\*\*([^*]+)\*\*/g, '$1')
		.replace(/\[([^\]]+)\]\([^)]+\)/g, '$1')
}

/** Split text into sentence-ish chunks (lines, then sentence ends). */
export function splitSentences(text: string): string[] {
	const out: string[] = []
	for (const rawLine of stripMarkdown(text).split(/\n+/)) {
		const line = rawLine.replace(/^\s*(?:[-*>]|\d+[.)])\s+/, '').trim()
		if (!line) continue
		for (const part of line.split(/(?<=[.!?])\s+(?=[A-Z0-9"'(])/)) {
			const sentence = part.trim()
			if (sentence) out.push(sentence)
		}
	}
	return out
}

const NEGATED =
	/\b(nothing|nobody|no one)\b[^.?!;,]{0,25}\b(needs?|requires?|waiting|pending|left)\b|\bno (\w+ )?(decision|action|input|reply)s? (is |are |was |were )?(needed|required|pending)\b|\b(no|without|\d+) needs?-\w+|\b(records?|recorded|made|followed|per|as|matches|took|applied) (your|the owner'?s?) (call|decision)\b|\b(doesn'?t|does not|don'?t|do not) need (you|a decision|input)\b/i

/** Conditional or hypothetical phrasing ("if anything needs ...", "would have been a decision"). */
const CONDITIONAL =
	/\bif (anything|something|it|this|that|they|[\w-]+)? ?(still )?needs?\b|\bonly (flag|come back|ping|escalate)\b|\bwould(n'?t| not)? (have )?(been|needed|need)\b|^\s*\|/i

const BOILERPLATE_QUESTION =
	/^(is there )?anything else\b|^any (other |more )?questions\b|^(does|did) (that|this) (help|make sense|work)\b|^(want|would you like) me to (do anything else|continue)\b|^shall i (continue|proceed)\?$/i

function escapeRegex(value: string): string {
	return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
}

const DEFAULT_DECISION_PATTERNS: RegExp[] = [
	/\bneeds?[- ]owner\b/i,
	/\b(owner|product) decision\b/i,
	/\bdecisions? (for|from) (you|the owner)\b/i,
	/\bneeds? (a|your) decision\b/i,
	/\b(decision|input) needed\b/i,
	/\byour (decision|call)\b/i,
	/\bcall on you\b/i,
	/\bwhich (would|do) you prefer\b/i,
	/\bwhich (one|option|approach|way) (would|do|should)\b/i,
	/\bplease (decide|choose|pick)\b/i,
	/\b(you|owner) (can|could|should|need to|needs to) (decide|choose)\b/i,
]

function ownerPatterns(names: string[]): RegExp[] {
	const out: RegExp[] = []
	for (const raw of names) {
		const name = escapeRegex(String(raw ?? '').trim())
		if (!name) continue
		out.push(
			new RegExp(`\\bneeds?[- ]${name}\\b`, 'i'),
			new RegExp(`\\bdecisions? (for|from) ${name}\\b`, 'i'),
			new RegExp(`\\b${name}'?s (decision|call|answers?|input)\\b`, 'i'),
			new RegExp(`\\b(waiting|wait|waits) (for|on) ${name}\\b`, 'i'),
			new RegExp(`\\bfor ${name} to (decide|choose|confirm)\\b`, 'i'),
		)
	}
	return out
}

/** Sentences in `text` that ask for a product or owner decision. */
export function findDecisionSentences(
	text: string,
	options: Pick<ClassifyOptions, 'decisionKeywords' | 'ownerNames'> = {},
): string[] {
	const patterns = [
		...DEFAULT_DECISION_PATTERNS,
		...ownerPatterns(options.ownerNames ?? []),
	]
	const keywords = (options.decisionKeywords ?? [])
		.map((k) => String(k ?? '').trim().toLowerCase())
		.filter(Boolean)
	const sentences = splitSentences(text)
	const matched = sentences.filter((sentence) => {
		if (NEGATED.test(sentence) || CONDITIONAL.test(sentence)) return false
		const lower = sentence.toLowerCase()
		if (keywords.some((k) => lower.includes(k))) return true
		return patterns.some((p) => p.test(sentence))
	})
	if (matched.length) return matched
	// "Option A ... Option B": only when two or more distinct options are offered.
	const letters = new Set(
		[...text.matchAll(/\boption ([A-D1-4])\b/gi)].map((m) => m[1]!.toUpperCase()),
	)
	if (letters.size >= 2) {
		return sentences.filter((s) => /\boption [A-D1-4]\b/i.test(s)).slice(0, 1)
	}
	return []
}

const ASK_PATTERNS: RegExp[] = [
	/\b(please|can you|could you|would you) (confirm|reply|respond|provide|share|send|let me know|clarify|answer|decide|choose)\b/i,
	/\blet me know (whether|which|how|what|when|if you want me to|if i should)\b/i,
	/\b(waiting|wait) (for|on) [\w' ]{0,30}?(answers?|repl(y|ies)|input|response|go-?ahead|confirmation|decision|approval|instructions)\b/i,
	/\bonce you (confirm|reply|decide|answer|approve)\b/i,
	/\bi need (you|your) to\b/i,
	/\bneed (your|an?) (answer|reply|input|confirmation|go-?ahead)\b/i,
]

/** Questions Devin is asking (sentences ending in `?`, minus boilerplate). */
export function extractQuestions(text: string, max = 5): string[] {
	const questions: string[] = []
	for (const sentence of splitSentences(text)) {
		if (!sentence.endsWith('?')) continue
		if (BOILERPLATE_QUESTION.test(sentence)) continue
		questions.push(sentence.length > 300 ? `${sentence.slice(0, 297)}...` : sentence)
		if (questions.length >= max) break
	}
	return questions
}

/** Sentences that explicitly ask the user for something. */
export function findAskSentences(text: string): string[] {
	return splitSentences(text).filter(
		(s) => !NEGATED.test(s) && ASK_PATTERNS.some((p) => p.test(s)),
	)
}

/** True when the text explicitly asks the user for something. */
export function hasAsk(text: string): boolean {
	return findAskSentences(text).length > 0
}

function evidence(sentences: string[]): string {
	const first = sentences[0] ?? ''
	return first.length > 200 ? `${first.slice(0, 197)}...` : first
}

const DEPLOY_WAIT_PATTERNS: RegExp[] = [
	/\b(waiting|wait|waits) (for|on|until) [^.?!]{0,40}\b(deploy\w*|health ?checks?|\/health|ship\w*|rollout|production|release)\b/i,
	/\b(deploy\w*|rollout|ship(-pr)? (run|check|step|tick)|health ?checks?)\b[^.?!]{0,30}\b(still (running|pending|in progress|queued)|(is|are) (pending|queued|in progress)|not (yet )?(finished|done|complete|green|live)|has(n'?t| not) (finished|completed|started|run|gone out)|stuck|blocked|timed out)\b/i,
	/\b(production|prod|\/health|health ?check)\b[^.?!]{0,20}\bstill (shows|showed|serves|served|reports|reported|returns|returned)\b/i,
	/\b(not (yet )?(live|deployed)|has(n'?t| not) (been )?deployed( yet)?)\b/i,
]

/** Sentences saying the session is still waiting on a deploy/health/ship check. */
export function findDeployWaitSentences(text: string): string[] {
	return splitSentences(text).filter(
		(s) =>
			!NEGATED.test(s) &&
			!CONDITIONAL.test(s) &&
			DEPLOY_WAIT_PATTERNS.some((p) => p.test(s)),
	)
}

const APPROVAL_PATTERNS: RegExp[] = [
	/\b(approve|accept)\b[^.?!]{0,80}\b(suggestion|suggested|card|reminder|environment|repo setup|machine setup|snapshot)\b/i,
	/\b(suggestion|card)\b[^.?!]{0,60}\b(approve|accept|approval|in the (ui|web app|session))\b/i,
	/\b(environment|repo|machine|snapshot)\s+setup\b[^.?!]{0,80}\b(suggest\w*|approv\w*|pending)\b/i,
	/\bsuggested (an? )?(environment|setup|repo setup|machine setup|reminder)\b/i,
]

/** Sentences that point at a UI-only approval or suggestion card. */
export function findApprovalSentences(text: string): string[] {
	return splitSentences(text).filter(
		(s) => !NEGATED.test(s) && APPROVAL_PATTERNS.some((p) => p.test(s)),
	)
}

/** Normalize Devin `pr_state` (or a GitHub state) to open/merged/closed/unknown. */
export function normalizePrState(value: unknown): PrState {
	const state = String(value ?? '').trim().toLowerCase()
	if (!state) return 'unknown'
	if (state === 'merged') return 'merged'
	if (state === 'closed') return 'closed'
	if (state === 'open' || state === 'draft' || state === 'opened') return 'open'
	return 'unknown'
}

export function sessionPrs(session: AttentionSessionInput): AttentionPr[] {
	const out: AttentionPr[] = []
	for (const pr of session.pull_requests ?? []) {
		const url = String(pr?.pr_url ?? pr?.url ?? '').trim()
		if (!url) continue
		out.push({
			url,
			state: normalizePrState(pr?.pr_state ?? pr?.state),
			mergeCommit: null,
		})
	}
	return out
}

/** `{ owner, repo, number }` for a github.com pull request URL, else null. */
export function parsePrUrl(
	url: string,
): { owner: string; repo: string; number: number } | null {
	const match = /github\.com\/([^/]+)\/([^/]+)\/pull\/(\d+)/i.exec(url)
	if (!match) return null
	return { owner: match[1]!, repo: match[2]!, number: Number(match[3]) }
}

export function isActivelyWorking(session: AttentionSessionInput): boolean {
	const status = String(session.status ?? '').toLowerCase()
	const detail = String(session.status_detail ?? '').toLowerCase()
	if (['new', 'claimed', 'resuming'].includes(status)) return true
	return status === 'running' && (detail === 'working' || detail === '')
}

/**
 * Classify one session from its list/get record, its messages (chronological),
 * and PR states (Devin's `pr_state`, optionally refreshed from GitHub).
 *
 * Priority: approval_pending, needs_human_decision, awaiting_user,
 * deploy_stuck, stale.
 */
export function classifySession(
	session: AttentionSessionInput,
	messages: AttentionMessage[],
	options: ClassifyOptions & { prs?: AttentionPr[] } = {},
): Classification {
	const now = options.now ?? Date.now()
	const decisionAction = String(options.decisionAction ?? '').trim() || 'ping_owner'
	const prs = options.prs ?? sessionPrs(session)
	const sorted = [...messages].sort(
		(a, b) => Number(a.created_at ?? 0) - Number(b.created_at ?? 0),
	)
	const last = sorted[sorted.length - 1]
	const lastUserIndex = sorted.map((m) => m.source).lastIndexOf('user')
	const finalTurn = sorted
		.slice(lastUserIndex + 1)
		.filter((m) => m.source === 'devin')
		.map((m) => cleanMessage(m.message))
		.filter(Boolean)
	const lastDevin = [...sorted].reverse().find((m) => m.source === 'devin')
	const lastDevinText = cleanMessage(lastDevin?.message)
	const devinSpokeLast = last?.source === 'devin'
	const turnText = devinSpokeLast ? finalTurn.join('\n\n') : ''
	const finalMessageText = devinSpokeLast ? (finalTurn[finalTurn.length - 1] ?? '') : ''

	const lastActivityAt =
		Number(last?.created_at ?? 0) || Number(session.updated_at ?? 0) || null
	const ageHours =
		lastActivityAt === null
			? null
			: Math.max(0, Math.round(((now / 1000 - lastActivityAt) / 3600) * 10) / 10)

	const questions = extractQuestions(finalMessageText)
	const activelyWorking = isActivelyWorking(session)
	const detail = String(session.status_detail ?? '').toLowerCase()

	const base = {
		questions,
		lastDevinMessage: lastDevinText
			? trimMiddle(lastDevinText, options.messageChars ?? 600)
			: null,
		lastActivityAt,
		ageHours,
		prs,
		activelyWorking,
	}

	if (detail === 'waiting_for_approval') {
		return { ...base, reason: 'approval_pending', suggestedAction: decisionAction, uiOnly: true, detection: 'status' }
	}
	if (activelyWorking) {
		return { ...base, reason: null, suggestedAction: 'none' }
	}
	const approval = turnText ? findApprovalSentences(turnText) : []
	if (approval.length) {
		return { ...base, reason: 'approval_pending', suggestedAction: decisionAction, uiOnly: true, detection: 'message', evidence: evidence(approval) }
	}
	const decision = finalMessageText ? findDecisionSentences(finalMessageText, options) : []
	if (decision.length) {
		return { ...base, reason: 'needs_human_decision', suggestedAction: decisionAction, detection: 'message', evidence: evidence(decision) }
	}
	if (detail === 'waiting_for_user') {
		return { ...base, reason: 'awaiting_user', suggestedAction: 'reply', detection: 'status' }
	}
	const asks = finalMessageText ? [...questions, ...findAskSentences(finalMessageText)] : []
	if (asks.length) {
		return { ...base, reason: 'awaiting_user', suggestedAction: 'reply', detection: 'message', evidence: evidence(asks) }
	}
	const hasMerged = prs.some((pr) => pr.state === 'merged')
	const deployWait =
		hasMerged && finalMessageText ? findDeployWaitSentences(finalMessageText) : []
	if (deployWait.length) {
		return { ...base, reason: 'deploy_stuck', suggestedAction: 'check_deploy', detection: 'message', evidence: evidence(deployWait) }
	}
	const allDone =
		prs.length > 0 && prs.every((pr) => pr.state === 'merged' || pr.state === 'closed')
	if (options.includeStale !== false && allDone && !session.is_archived) {
		return { ...base, reason: 'stale', suggestedAction: 'archive', detection: 'status' }
	}
	return { ...base, reason: null, suggestedAction: 'none' }
}

/** Pull a commit sha out of a health/version JSON payload. */
export function findCommitInJson(value: unknown, depth = 0): string | null {
	if (depth > 4 || value === null || value === undefined) return null
	if (typeof value !== 'object') return null
	const entries = Object.entries(value as Record<string, unknown>)
	for (const [key, entry] of entries) {
		if (
			typeof entry === 'string' &&
			/commit|sha|revision|git|version|build/i.test(key) &&
			/^[0-9a-f]{7,40}$/i.test(entry.trim())
		) {
			return entry.trim().toLowerCase()
		}
	}
	for (const [, entry] of entries) {
		const found = findCommitInJson(entry, depth + 1)
		if (found) return found
	}
	return null
}

export function sameCommit(a: string, b: string): boolean {
	const x = a.trim().toLowerCase()
	const y = b.trim().toLowerCase()
	if (x.length < 7 || y.length < 7) return false
	return x.startsWith(y) || y.startsWith(x)
}

export type AttentionCursor = {
	v: 1
	/** updatedSince in unix seconds. */
	since: number
	includeArchived: boolean
	/** Last processed session key: [created_at, session_id]. */
	after: [number, string]
	/** Sessions scanned by earlier calls in this run. */
	scanned: number
}

export function encodeCursor(cursor: AttentionCursor): string {
	const json = JSON.stringify(cursor)
	const b64 =
		typeof btoa === 'function'
			? btoa(unescape(encodeURIComponent(json)))
			: Buffer.from(json, 'utf8').toString('base64')
	return b64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
}

export function decodeCursor(value: unknown): AttentionCursor | null {
	if (typeof value !== 'string' || !value.trim()) return null
	try {
		const b64 = value.trim().replace(/-/g, '+').replace(/_/g, '/')
		const json =
			typeof atob === 'function'
				? decodeURIComponent(escape(atob(b64)))
				: Buffer.from(b64, 'base64').toString('utf8')
		const parsed = JSON.parse(json) as AttentionCursor
		if (parsed?.v !== 1 || !Array.isArray(parsed.after)) throw new Error('bad cursor')
		return parsed
	} catch {
		throw new Error('Invalid cursor. Pass nextCursor exactly as returned.')
	}
}

/** Stable scan order: newest created first, ties by session id. */
export function compareScanOrder(
	a: { created_at?: number | null; session_id: string },
	b: { created_at?: number | null; session_id: string },
): number {
	const diff = Number(b.created_at ?? 0) - Number(a.created_at ?? 0)
	if (diff !== 0) return diff
	return a.session_id < b.session_id ? 1 : a.session_id > b.session_id ? -1 : 0
}

/** True when `session` comes after the cursor key in scan order. */
export function isAfterKey(
	session: { created_at?: number | null; session_id: string },
	key: [number, string],
): boolean {
	return compareScanOrder({ created_at: key[0], session_id: key[1] }, session) < 0
}