← Public packages
@kentcdodds/devin
Start, monitor, and manage Devin sessions, knowledge, playbooks, and schedules via the Devin v3 API
Files
/**
* 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
}