@adecore/agents 0.23.0 → 0.24.0

package/src/chat/claude-backend.ts

@@ -2,10 +2,14 @@ import { randomUUID } from 'node:crypto';
 import { errorText } from '../error-text.ts';
 import { claudeArgs, claudeEnv, promptPrefix } from '../providers/claude.ts';
 import type { ApprovalDecision, BackendHost, BackendLaunch, ChatBackend, TurnInput } from './backend.ts';
-import { ChatChild } from './chat-process.ts';
+import { ChatChild, MAX_LINE_LENGTH, readStreamLines } from './chat-process.ts';
 import { ClaudeProtocol } from './claude-protocol.ts';
 import { buildUserMessage } from './input.ts';
 
+// Claude may echo a steer only once a slow tool returns, so a running turn sets no deadline; after the turn ended, a message
+// it still holds opens the next turn at once or never arrives.
+const STEER_GRACE_MS = 30_000;
+
 export interface ClaudeBackendOptions {
     // Tools the CLI runs without asking, in every mode, as `--allowedTools` patterns (`Bash(git status)`).
     allowedTools?: readonly string[];
@@ -22,18 +26,20 @@ export class ClaudeBackend implements ChatBackend {
     private readonly launch: BackendLaunch;
     private readonly host: BackendHost;
     private readonly allowedTools: readonly string[];
-    private readonly protocol = new ClaudeProtocol();
+    private readonly protocol: ClaudeProtocol;
     private child: ChatChild | null = null;
     private stdinClosed = false;
     // The person asked to stop; the result frame that follows closes the turn as aborted.
     private interrupted = false;
     private readonly steers = new Map<string, { resolve(accepted: boolean): void; reject(reason: Error): void }>();
+    private steerTimer: ReturnType<typeof setTimeout> | null = null;
     private active = false;
 
     constructor(launch: BackendLaunch, host: BackendHost, options: ClaudeBackendOptions = {}) {
         this.launch = launch;
         this.host = host;
         this.allowedTools = options.allowedTools ?? [];
+        this.protocol = new ClaudeProtocol(launch.goal ?? null);
     }
 
     get running(): boolean {
@@ -62,7 +68,7 @@ export class ClaudeBackend implements ChatBackend {
             cwd: this.launch.cwd,
             env: { ...this.launch.env, ...claudeEnv(selection) },
             ...(this.launch.spawn ? { spawn: this.launch.spawn } : {}),
-            onError: (error) => this.failed(error),
+            onError: (error) => this.broken(error),
             onExit: (exitCode, stderr) => this.handleExit(child, exitCode, stderr)
         });
         this.child = child;
@@ -101,6 +107,7 @@ export class ClaudeBackend implements ChatBackend {
 
     interrupt(): void {
         this.interrupted = true;
+        this.protocol.noteInterrupt();
         this.write({ type: 'control_request', request_id: `interrupt-${Date.now()}`, request: { subtype: 'interrupt' } });
     }
 
@@ -151,32 +158,20 @@ export class ClaudeBackend implements ChatBackend {
     }
 
     private async readLines(child: ChatChild): Promise<void> {
-        const reader = child.process.stdout.getReader();
-        const decoder = new TextDecoder();
-        let buffered = '';
         try {
-            while (true) {
-                const { value, done } = await reader.read();
-                if (done) {
-                    break;
-                }
-                buffered += decoder.decode(value, { stream: true });
-                let newline = buffered.indexOf('\n');
-                while (newline >= 0) {
-                    this.readLine(child, buffered.slice(0, newline));
-                    buffered = buffered.slice(newline + 1);
-                    newline = buffered.indexOf('\n');
+            await readStreamLines(
+                child.process.stdout,
+                (line) => this.readLine(child, line),
+                () => {
+                    if (this.child === child) {
+                        this.failed(new Error(`Claude wrote a frame of more than ${MAX_LINE_LENGTH / 1_000_000} million characters, which was dropped`));
+                    }
                 }
-            }
-            if (buffered.trim() !== '') {
-                this.readLine(child, buffered);
-            }
+            );
         } catch (error) {
             if (this.child === child) {
-                this.failed(error);
+                this.broken(error);
             }
-        } finally {
-            reader.releaseLock();
         }
     }
 
@@ -194,10 +189,14 @@ export class ClaudeBackend implements ChatBackend {
         if (echoed?.type === 'user' && typeof echoed.uuid === 'string' && echoed.parent_tool_use_id == null) {
             this.steers.get(echoed.uuid)?.resolve(true);
             this.steers.delete(echoed.uuid);
+            if (this.steers.size === 0) {
+                this.clearSteerTimer();
+            }
         }
         for (const event of this.protocol.handle(frame)) {
             if (event.type === 'turn.done') {
                 this.active = false;
+                this.awaitSteers();
             }
             if (event.type === 'turn.done' && this.interrupted) {
                 this.interrupted = false;
@@ -216,14 +215,42 @@ export class ClaudeBackend implements ChatBackend {
         }
     }
 
+    private awaitSteers(): void {
+        if (this.steers.size === 0 || this.steerTimer !== null) {
+            return;
+        }
+        this.steerTimer = setTimeout(() => {
+            this.steerTimer = null;
+            for (const pending of this.steers.values()) {
+                pending.reject(new Error('Claude ended its turn without taking your message'));
+            }
+            this.steers.clear();
+        }, STEER_GRACE_MS);
+        this.steerTimer.unref?.();
+    }
+
+    private clearSteerTimer(): void {
+        if (this.steerTimer !== null) {
+            clearTimeout(this.steerTimer);
+            this.steerTimer = null;
+        }
+    }
+
     private rejectSteers(reason: string): void {
         this.active = false;
+        this.clearSteerTimer();
         for (const pending of this.steers.values()) {
             pending.reject(new Error(reason));
         }
         this.steers.clear();
     }
 
+    /* A pipe that failed takes no more writes; a frame a consumer choked on leaves it as it was. */
+    private broken(error: unknown): void {
+        this.stdinClosed = true;
+        this.failed(error);
+    }
+
     private failed(error: unknown): void {
         this.rejectSteers(`Claude transport failed: ${errorText(error)}`);
         this.protocol.forgetPending();
@@ -250,8 +277,13 @@ export class ClaudeBackend implements ChatBackend {
         if (!child || this.stdinClosed) {
             throw new Error('Claude stdin is closed');
         }
-        child.process.stdin.write(`${JSON.stringify(frame)}\n`);
-        child.process.stdin.flush();
+        try {
+            child.process.stdin.write(`${JSON.stringify(frame)}\n`);
+            child.process.stdin.flush();
+        } catch (error) {
+            this.stdinClosed = true;
+            throw error;
+        }
     }
 
     private closeStdin(): void {

package/src/chat/claude-protocol.ts

@@ -1,4 +1,5 @@
 import type {
+    ChatGoal,
     ChatQuestion,
     ChatSubagentStatus,
     ChatSubagentUsage,
@@ -7,16 +8,13 @@ import type {
     ChatWorkflowAgent,
     ChatWorkflowPhase
 } from '@adecore/agent-contracts';
+import { isRecord } from '@adecore/agent-contracts';
 import { readClaudeEvent } from '../usage/limits/normalize.ts';
 import { claudeRuntimeMode } from '../providers/claude.ts';
 import type { ApprovalDecision, BackendEvent } from './backend.ts';
 
 type Frame = Record<string, unknown>;
 
-function isRecord(value: unknown): value is Frame {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-
 function str(value: unknown): string | null {
     return typeof value === 'string' ? value : null;
 }
@@ -118,6 +116,70 @@ type Pending =
     | { type: 'approval'; toolUseId: string | null; input: unknown; suggestions: unknown[] }
     | { type: 'question'; toolUseId: string | null; input: unknown };
 
+/*
+ * What Claude Code 2.1.296 answers a `/goal` with, as a `<synthetic>` assistant message of its own: the goal
+ * it set, the one it cleared, or the one that is active with how many turns its check sent back. Undefined
+ * for any other text, null where no goal is left.
+ */
+const GOAL_SET = 'Goal set: ';
+const GOAL_ACTIVE = /^Goal active: ([\s\S]+?) \(([^)]*)\)(?:\nLast check: ([\s\S]*))?$/;
+const GOAL_GONE = ['Goal cleared: ', 'Goal cleared after ', 'No goal set'];
+
+export function claudeGoalFromCommand(text: string, current: ChatGoal | null): ChatGoal | null | undefined {
+    const said = text.trim();
+    if (said.startsWith(GOAL_SET)) {
+        const objective = said.slice(GOAL_SET.length).trim();
+        return objective === '' ? undefined : { objective, status: 'active', checks: 0 };
+    }
+    if (GOAL_GONE.some((prefix) => said.startsWith(prefix))) {
+        return null;
+    }
+    const active = GOAL_ACTIVE.exec(said);
+    if (!active) {
+        return undefined;
+    }
+    const objective = active[1]!;
+    const checks = /\d+/.exec(active[2]!)?.[0];
+    const lastCheck = active[3]?.trim();
+    return {
+        ...(current?.objective === objective ? current : {}),
+        objective,
+        status: 'active',
+        checks: checks === undefined ? 0 : Number(checks),
+        ...(lastCheck ? { lastCheck } : {})
+    };
+}
+
+// The messages whose blocks are still counted. The frames of one message come close together, so only the newest can still grow.
+const COUNTED_MESSAGES = 256;
+
+/* The ordinal of the next block of `messageId`; a count moves to the back on every block and the oldest goes. */
+function nextOrdinal(counts: Map<string, number>, messageId: string): number {
+    const ordinal = counts.get(messageId) ?? 0;
+    counts.delete(messageId);
+    counts.set(messageId, ordinal + 1);
+    if (counts.size > COUNTED_MESSAGES) {
+        counts.delete(counts.keys().next().value!);
+    }
+    return ordinal;
+}
+
+/*
+ * One check of the goal's Stop hook that found it not met yet: a synthetic user message the CLI feeds the
+ * agent before it goes on, which names the objective in brackets. Undefined for any other message.
+ */
+export function claudeGoalCheck(text: string, current: ChatGoal | null): ChatGoal | undefined {
+    if (current === null) {
+        return undefined;
+    }
+    const prefix = `Stop hook feedback:\n[${current.objective}]: `;
+    if (!text.startsWith(prefix)) {
+        return undefined;
+    }
+    const lastCheck = text.slice(prefix.length).trim();
+    return { ...current, status: 'active', checks: (current.checks ?? 0) + 1, ...(lastCheck === '' ? {} : { lastCheck }) };
+}
+
 /*
  * Claude Code's stream-json frames, in and out. Text is keyed by message id plus the ordinal of the
  * text block inside that message, because the streaming events and the final `assistant` frames
@@ -151,6 +213,28 @@ export class ClaudeProtocol {
     private readonly stopRequests = new Map<string, string>();
 
     private readonly steerIds = new Set<string>();
+    // The goal this process works toward, which `--resume` takes up from the transcript; a model answer since it was
+    // set or last checked is what lets a turn that ends normally count as its check passing.
+    private goal: ChatGoal | null;
+    private goalAnswered = false;
+    private interrupting = false;
+    // Background subagents still at work; Claude Code holds a goal's check until they report.
+    private readonly backgroundAgents = new Set<string>();
+
+    constructor(goal: ChatGoal | null = null) {
+        this.goal = goal;
+    }
+
+    /* A stop is on its way; the turn it ends leaves the goal set but nobody working on it. */
+    noteInterrupt(): void {
+        this.interrupting = true;
+    }
+
+    private setGoal(goal: ChatGoal | null, events: BackendEvent[]): void {
+        this.goal = goal;
+        this.goalAnswered = false;
+        events.push({ type: 'goal', goal });
+    }
 
     beginSteer(promptId: string): void {
         this.steerIds.add(promptId);
@@ -347,6 +431,7 @@ export class ClaudeProtocol {
             if (taskId) {
                 this.endBackground(taskId, events);
                 this.workflows.delete(taskId);
+                this.backgroundAgents.delete(taskId);
             }
             // The CLI wakes the main agent itself when a background task settles; this frame is the only
             // thing that says what it was about, and it arrives before the turn nobody asked for.
@@ -369,6 +454,10 @@ export class ClaudeProtocol {
     private handleTaskStarted(frame: Frame, events: BackendEvent[]): void {
         const ref = str(frame.tool_use_id);
         if (frame.task_type === 'local_agent') {
+            const agentTask = str(frame.task_id);
+            if (agentTask && frame.is_backgrounded === true) {
+                this.backgroundAgents.add(agentTask);
+            }
             if (ref) {
                 events.push({
                     type: 'task.started',
@@ -417,6 +506,7 @@ export class ClaudeProtocol {
         const status = str(patch.status);
         if (status !== null && ENDED_TASK_STATUSES.has(status)) {
             this.foregroundShells.delete(taskId);
+            this.backgroundAgents.delete(taskId);
             this.endBackground(taskId, events);
             this.endWorkflow(taskId, null, status === 'completed', events);
         }
@@ -525,6 +615,9 @@ export class ClaudeProtocol {
             this.apiError = frame.error;
         }
         const model = str(message.model);
+        if (!parentRef) {
+            this.trackGoal(model, content, events);
+        }
         // The CLI answers some frames itself and names them `<synthetic>`; no model wrote those.
         if (parentRef && model && model !== '<synthetic>' && this.subagentModels.get(parentRef) !== model) {
             this.subagentModels.set(parentRef, model);
@@ -535,13 +628,11 @@ export class ClaudeProtocol {
                 continue;
             }
             if (block.type === 'text') {
-                const ordinal = this.frameTextCount.get(messageId) ?? 0;
-                this.frameTextCount.set(messageId, ordinal + 1);
+                const ordinal = nextOrdinal(this.frameTextCount, messageId);
                 // A subagent's text is its own report, not the thread's answer; the parent says whose row it is.
                 events.push({ type: 'text.done', ref: this.textRef(messageId, ordinal), text: str(block.text) ?? '', ...(parentRef ? { parentRef } : {}) });
             } else if (block.type === 'thinking' && !parentRef) {
-                const ordinal = this.frameThinkingCount.get(messageId) ?? 0;
-                this.frameThinkingCount.set(messageId, ordinal + 1);
+                const ordinal = nextOrdinal(this.frameThinkingCount, messageId);
                 events.push({ type: 'thinking.done', ref: this.thinkingRef(messageId, ordinal), text: str(block.thinking) ?? '' });
             } else if (block.type === 'tool_use') {
                 events.push({
@@ -563,6 +654,45 @@ export class ClaudeProtocol {
         }
     }
 
+    private trackGoal(model: string | null, content: unknown[], events: BackendEvent[]): void {
+        if (model === '<synthetic>') {
+            const next = claudeGoalFromCommand(resultText(content), this.goal);
+            if (next !== undefined) {
+                this.setGoal(next, events);
+            }
+            return;
+        }
+        if (this.goal === null) {
+            return;
+        }
+        this.goalAnswered = true;
+        // A message after a stop takes the goal up again; its hook never went away.
+        if (this.goal.status === 'paused') {
+            this.goal = { ...this.goal, status: 'active' };
+            events.push({ type: 'goal', goal: this.goal });
+        }
+    }
+
+    /*
+     * Where a turn leaves the goal. Claude Code ends a turn on its own only once the goal's check passed, so
+     * a turn that ends normally after the model answered met it; Claude Code 2.1.296 says nothing more
+     * about it in stream-json. A check it defers while background work runs leaves the goal active, and a
+     * stopped or failed turn leaves it set with nobody working on it.
+     */
+    private settleGoal(failed: boolean, events: BackendEvent[]): void {
+        const goal = this.goal;
+        const interrupted = this.interrupting;
+        this.interrupting = false;
+        if (goal?.status !== 'active') {
+            return;
+        }
+        if (failed || interrupted) {
+            this.setGoal({ ...goal, status: 'paused' }, events);
+        } else if (this.goalAnswered && this.backgroundTasks.size === 0 && this.workflows.size === 0 && this.backgroundAgents.size === 0) {
+            this.setGoal({ ...goal, status: 'complete' }, events);
+        }
+    }
+
     /*
      * `tool_progress` carries how long the call has run (once per 30 s for a Bash under the CLI's
      * remote gate, or a heartbeat for a slow MCP tool); the start is kept so the client can count on.
@@ -583,6 +713,13 @@ export class ClaudeProtocol {
         }
         const message = isRecord(frame.message) ? frame.message : {};
         const content = Array.isArray(message.content) ? message.content : [];
+        if (frame.isSynthetic === true && !str(frame.parent_tool_use_id)) {
+            const checked = claudeGoalCheck(resultText(message.content), this.goal);
+            if (checked !== undefined) {
+                this.setGoal(checked, events);
+                events.push({ type: 'note', level: 'info', text: `Goal not met yet: ${checked.lastCheck ?? checked.objective}` });
+            }
+        }
         for (const block of content) {
             if (!isRecord(block) || block.type !== 'tool_result') {
                 continue;
@@ -630,6 +767,8 @@ export class ClaudeProtocol {
         const limit = failed ? this.limit() : null;
         this.apiError = null;
         this.refusedWindows.clear();
+        // Before the turn ends, so whoever settles work on that end already reads where the goal stands.
+        this.settleGoal(failed, events);
         events.push({
             type: 'turn.done',
             ...(promptId === null ? {} : { promptId }),

package/src/chat/claude-title.ts

@@ -1,8 +1,8 @@
-import { existsSync } from 'node:fs';
-import { readdir, stat } from 'node:fs/promises';
-import { join } from 'node:path';
+import { stat } from 'node:fs/promises';
+import { isRecord } from '@adecore/agent-contracts';
 import { cleanTitle, readLines } from '../title-file.ts';
 import { usageRoots } from '../usage/roots.ts';
+import { findClaudeSession } from './claude-transcript.ts';
 
 interface Progress {
     offset: number;
@@ -22,7 +22,6 @@ const MARKERS = ['"ai-title"', '"custom-title"'];
  */
 export class ClaudeTitleReader {
     private readonly progress = new Map<string, Progress>();
-    private readonly found = new Map<string, string>();
     private readonly projectsDir: string;
     private readonly chunkBytes: number;
 
@@ -31,9 +30,9 @@ export class ClaudeTitleReader {
         this.chunkBytes = chunkBytes;
     }
 
-    /* The title of a session found by its id, for a chat, which knows no transcript path; in the projects of its account. */
-    async forSession(agentSessionId: string, projectsDir: string = this.projectsDir): Promise<string | null> {
-        const path = await this.locate(agentSessionId, projectsDir);
+    /* The title of a session found by its id, for a chat, which knows no transcript path; in the projects of its account, its own folder first. */
+    async forSession(agentSessionId: string, projectsDir: string = this.projectsDir, cwd?: string): Promise<string | null> {
+        const path = await findClaudeSession(projectsDir, agentSessionId, cwd);
         return path === null ? null : await this.forTranscript(path);
     }
 
@@ -67,40 +66,13 @@ export class ClaudeTitleReader {
         } catch {
             return;
         }
-        if (typeof record !== 'object' || record === null) {
+        if (!isRecord(record)) {
             return;
         }
-        const entry = record as Record<string, unknown>;
-        if (entry.type === 'ai-title') {
-            progress.aiTitle = cleanTitle(entry.aiTitle) ?? progress.aiTitle;
-        } else if (entry.type === 'custom-title') {
-            progress.customTitle = cleanTitle(entry.customTitle) ?? progress.customTitle;
+        if (record.type === 'ai-title') {
+            progress.aiTitle = cleanTitle(record.aiTitle) ?? progress.aiTitle;
+        } else if (record.type === 'custom-title') {
+            progress.customTitle = cleanTitle(record.customTitle) ?? progress.customTitle;
         }
     }
-
-    /* The folder a transcript sits in is named after the working directory, so the file name is the only key a session id gives. */
-    private async locate(agentSessionId: string, projectsDir: string): Promise<string | null> {
-        const known = this.found.get(agentSessionId);
-        if (known !== undefined && existsSync(known)) {
-            return known;
-        }
-        if (projectsDir === '' || agentSessionId.includes('/')) {
-            return null;
-        }
-        let dirs: string[];
-        try {
-            dirs = await readdir(projectsDir);
-        } catch {
-            return null;
-        }
-        const file = `${agentSessionId}.jsonl`;
-        for (const dir of dirs) {
-            const path = join(projectsDir, dir, file);
-            if (existsSync(path)) {
-                this.found.set(agentSessionId, path);
-                return path;
-            }
-        }
-        return null;
-    }
 }

package/src/chat/claude-transcript.ts

@@ -1,7 +1,9 @@
 import { existsSync } from 'node:fs';
 import { readdir, readFile, stat } from 'node:fs/promises';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
 import type { ChatHistoryResult, ChatItem } from '@adecore/agent-contracts';
+import { isRecord } from '@adecore/agent-contracts';
+import { fileExists } from '../fs.ts';
 import { readLines } from '../title-file.ts';
 import { ClaudeProtocol } from './claude-protocol.ts';
 import { readingThread, settledReading } from './subagent-projection.ts';
@@ -10,10 +12,6 @@ import type { ChatThread } from './thread.ts';
 
 const CHUNK_BYTES = 4 * 1024 * 1024;
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-
 function str(value: unknown): string | null {
     return typeof value === 'string' && value !== '' ? value : null;
 }
@@ -45,32 +43,54 @@ export function claudeProjectSlug(cwd: string): string {
     return cwd.replace(/[^a-zA-Z0-9]/g, '-');
 }
 
+// Where each session was found last, by projects folder and session id; a path whose file went is searched for again.
+const sessionPaths = new Map<string, string>();
+
 /*
- * Where the subagents of a session keep their transcripts. The folder of the chat's own directory
- * first; a slug the CLI wrote differently (or a session resumed from somewhere else) is found by the
- * session id alone, which is unique across every project.
+ * The transcript Claude Code keeps of a session, found by its id: in the folder of `cwd` first, then
+ * where it was found before, then in every project folder, since the id is unique across all of them
+ * and a slug the CLI wrote differently (or a session resumed from elsewhere) sits in another folder.
+ * Null when no folder holds it, and for an id that would reach outside the projects folder.
  */
-export async function findSubagentsDir(projectsDir: string, cwd: string, sessionId: string): Promise<string | null> {
-    if (projectsDir === '' || sessionId.includes('/') || sessionId.includes('..')) {
+export async function findClaudeSession(projectsDir: string, sessionId: string, cwd?: string): Promise<string | null> {
+    if (projectsDir === '' || sessionId === '' || /[/\\]|\.\./.test(sessionId)) {
         return null;
     }
-    const own = join(projectsDir, claudeProjectSlug(cwd), sessionId, 'subagents');
-    if (existsSync(own)) {
+    const file = `${sessionId}.jsonl`;
+    const key = `${projectsDir}\n${sessionId}`;
+    const own = cwd === undefined ? null : join(projectsDir, claudeProjectSlug(cwd), file);
+    if (own !== null && (await fileExists(own))) {
+        sessionPaths.set(key, own);
         return own;
     }
+    const known = sessionPaths.get(key);
+    if (known !== undefined && known !== own && (await fileExists(known))) {
+        return known;
+    }
+    sessionPaths.delete(key);
     let dirs: string[];
     try {
         dirs = await readdir(projectsDir);
     } catch {
         return null;
     }
-    for (const dir of dirs) {
-        const candidate = join(projectsDir, dir, sessionId, 'subagents');
-        if (existsSync(candidate)) {
-            return candidate;
-        }
+    const candidates = dirs.map((dir) => join(projectsDir, dir, file)).filter((candidate) => candidate !== own);
+    const present = await Promise.all(candidates.map(fileExists));
+    const found = candidates.find((_candidate, i) => present[i]) ?? null;
+    if (found !== null) {
+        sessionPaths.set(key, found);
     }
-    return null;
+    return found;
+}
+
+/* Where the subagents of a session keep their transcripts: the folder beside its own transcript, once the CLI made it. */
+export async function findSubagentsDir(projectsDir: string, cwd: string, sessionId: string): Promise<string | null> {
+    const transcript = await findClaudeSession(projectsDir, sessionId, cwd);
+    if (transcript === null) {
+        return null;
+    }
+    const dir = join(dirname(transcript), sessionId, 'subagents');
+    return (await fileExists(dir)) ? dir : null;
 }
 
 /* Every meta file in a subagents folder that says which agent it is about; one that does not parse is left out. */