/** * 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 ", "needs-", "decision for ", "'s call", * and "waiting on ". */ 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 = {}, ): 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) 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 }