@adecore/agents 0.0.1 → 0.17.0-beta.1

package/dist/chat/request-summary.d.ts

@@ -0,0 +1,3 @@
+import { type ChatApprovalItem, type ChatQuestionItem, type ChatRequestApproval, type ChatRequestSummary } from '@adecore/agent-contracts';
+export declare function approvalSummary(item: ChatApprovalItem): ChatRequestApproval;
+export declare function requestSummaries(pending: ReadonlyArray<ChatApprovalItem | ChatQuestionItem>): ChatRequestSummary[];

package/dist/chat/request-summary.js

@@ -0,0 +1,143 @@
+import { CHAT_REQUEST_LIMITS } from '@adecore/agent-contracts';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function str(value) {
+    return typeof value === 'string' ? value : null;
+}
+// The keys a tool's input names its subject under, in the order a person would look for one.
+const SUBJECT_KEYS = ['file_path', 'notebook_path', 'path', 'url', 'query', 'pattern', 'skill', 'description'];
+/* Cuts text at `max` code units, never between the halves of a surrogate pair. */
+function cut(text, max) {
+    if (text.length <= max) {
+        return text;
+    }
+    const end = /[\uD800-\uDBFF]/.test(text[max - 1] ?? '') ? max - 1 : max;
+    return text.slice(0, end);
+}
+function clip(text, max) {
+    return text.length <= max ? text : `${cut(text, max - 1)}…`;
+}
+/* Keeps the end of a path, where its file name is. */
+function clipPath(path, max) {
+    if (path.length <= max) {
+        return path;
+    }
+    const start = path.length - (max - 1);
+    return `…${path.slice(/[\uDC00-\uDFFF]/.test(path[start] ?? '') ? start + 1 : start)}`;
+}
+function firstLine(text) {
+    return text.trim().split('\n', 1)[0] ?? '';
+}
+/* At most `maxLines` lines and `maxLength` code units, cut at a line; a first line longer than that is cut in itself. */
+function clipLines(lines, maxLines, maxLength) {
+    const kept = [];
+    let length = 0;
+    for (const line of lines) {
+        if (kept.length === maxLines || length + line.length + (kept.length > 0 ? 1 : 0) > maxLength) {
+            if (kept.length === 0) {
+                return { text: cut(line, maxLength), truncated: true };
+            }
+            return { text: kept.join('\n'), truncated: true };
+        }
+        length += line.length + (kept.length > 0 ? 1 : 0);
+        kept.push(line);
+    }
+    return { text: kept.join('\n'), truncated: false };
+}
+function splitLines(text) {
+    return text === '' ? [] : text.replace(/\n$/, '').split('\n');
+}
+/* The lines a replacement takes out and puts in; a provider's edit is a fragment, so there is no context to show. */
+function replacementLines(before, after) {
+    return [...splitLines(before).map((line) => `-${line}`), ...splitLines(after).map((line) => `+${line}`)];
+}
+/* Only what a unified diff changes: its headers and context lines stay in the thread. */
+function changedLines(diff) {
+    return splitLines(diff).filter((line) => (line.startsWith('-') && !line.startsWith('---')) || (line.startsWith('+') && !line.startsWith('+++')));
+}
+/* The first file a call changes, as Codex's patch or Claude's edit and write tools carry it; null for any other call. */
+function fileChange(toolName, input) {
+    const patches = Array.isArray(input.changes)
+        ? input.changes.filter((change) => isRecord(change) && typeof change.path === 'string' && typeof change.diff === 'string')
+        : [];
+    if (patches.length > 0) {
+        return { path: patches[0].path, files: patches.length, lines: changedLines(patches[0].diff) };
+    }
+    const path = str(input.file_path);
+    if (path === null) {
+        return null;
+    }
+    if (toolName === 'Edit') {
+        return { path, files: 1, lines: replacementLines(str(input.old_string) ?? '', str(input.new_string) ?? '') };
+    }
+    if (toolName === 'Write') {
+        return { path, files: 1, lines: replacementLines('', str(input.content) ?? '') };
+    }
+    if (toolName === 'MultiEdit' && Array.isArray(input.edits)) {
+        return {
+            path,
+            files: 1,
+            lines: input.edits.filter(isRecord).flatMap((edit) => replacementLines(str(edit.old_string) ?? '', str(edit.new_string) ?? ''))
+        };
+    }
+    return null;
+}
+function subjectOf(input) {
+    const named = SUBJECT_KEYS.map((key) => str(input[key])).find((value) => value !== null && value.trim() !== '');
+    const first = named ?? Object.values(input).find((value) => typeof value === 'string' && value.trim() !== '') ?? '';
+    return clip(firstLine(first), CHAT_REQUEST_LIMITS.subject);
+}
+export function approvalSummary(item) {
+    const input = isRecord(item.input) ? item.input : {};
+    const change = fileChange(item.toolName, input);
+    const command = change === null ? str(input.command) : null;
+    const diff = change === null ? null : clipLines(change.lines, CHAT_REQUEST_LIMITS.diffLines, CHAT_REQUEST_LIMITS.diff);
+    const shell = command === null ? null : clipLines(splitLines(command), CHAT_REQUEST_LIMITS.commandLines, CHAT_REQUEST_LIMITS.command);
+    const truncated = diff?.truncated === true || shell?.truncated === true;
+    return {
+        toolName: clip(item.toolName, CHAT_REQUEST_LIMITS.subject),
+        subject: change !== null
+            ? clipPath(change.path, CHAT_REQUEST_LIMITS.subject)
+            : command !== null
+                ? clip(firstLine(command), CHAT_REQUEST_LIMITS.subject)
+                : subjectOf(input),
+        description: item.description === null ? null : clip(item.description, CHAT_REQUEST_LIMITS.description),
+        ...(change === null ? {} : { path: clipPath(change.path, CHAT_REQUEST_LIMITS.subject) }),
+        ...(change !== null && change.files > 1 ? { files: change.files } : {}),
+        ...(diff === null || diff.text === '' ? {} : { diff: diff.text }),
+        ...(shell === null ? {} : { command: shell.text }),
+        ...(truncated ? { truncated: true } : {}),
+        canAllowAlways: item.canAllowAlways,
+        ...(item.allowAlways
+            ? {
+                allowAlways: {
+                    label: clip(item.allowAlways.label, CHAT_REQUEST_LIMITS.header),
+                    description: clip(item.allowAlways.description, CHAT_REQUEST_LIMITS.description)
+                }
+            }
+            : {})
+    };
+}
+function questionSummary(item) {
+    return {
+        questions: item.questions.map((question) => ({
+            id: question.id,
+            header: clip(question.header, CHAT_REQUEST_LIMITS.header),
+            question: clip(question.question, CHAT_REQUEST_LIMITS.question),
+            choices: question.choices.map((choice) => ({ label: choice.label, description: clip(choice.description, CHAT_REQUEST_LIMITS.choiceDescription) })),
+            multiSelect: question.multiSelect
+        })),
+        ...(item.async === undefined ? {} : { async: item.async })
+    };
+}
+/* What a chat waits on, oldest first, as `ChatInfo.requests` carries it. */
+export function requestSummaries(pending) {
+    return pending.slice(0, CHAT_REQUEST_LIMITS.perChat).map((item) => ({
+        requestId: item.requestId,
+        itemId: item.id,
+        kind: item.kind,
+        createdAt: item.createdAt,
+        ...(item.kind === 'approval' ? { approval: approvalSummary(item) } : { question: questionSummary(item) })
+    }));
+}

package/dist/chat/subagent-projection.d.ts

@@ -0,0 +1,8 @@
+import type { ChatItem } from '@adecore/agent-contracts';
+import { ThreadProjector } from './projector.ts';
+import { ChatThread } from './thread.ts';
+export declare function readingThread(providerName: string, now: () => number): {
+    thread: ChatThread;
+    projector: ThreadProjector;
+};
+export declare function settledReading(item: ChatItem): ChatItem;

package/dist/chat/subagent-projection.js

@@ -0,0 +1,40 @@
+import { ThreadProjector } from './projector.js';
+import { ChatThread } from './thread.js';
+// A subagent's conversation has no turns of its own; the projector is kept inside this one so it never opens any.
+const READING_TURN = 'subagent-reading';
+/* The info a thread needs to exist. Nothing reads it: a subagent's conversation is only ever its items. */
+function readingInfo() {
+    return {
+        chatId: 'subagent',
+        provider: 'claude',
+        cwd: '',
+        agentSessionId: null,
+        model: null,
+        selection: { model: '', options: {} },
+        runtimeMode: 'full-access',
+        status: 'running',
+        running: true,
+        activeTurnId: READING_TURN,
+        slashCommands: [],
+        usage: { contextTokens: 0, contextWindow: 0, costUsd: 0, turns: 0 },
+        createdAt: 0
+    };
+}
+/* A thread and the projector that writes it, for a conversation read back rather than streamed. */
+export function readingThread(providerName, now) {
+    const thread = new ChatThread(readingInfo());
+    return { thread, projector: new ThreadProjector(thread, { providerName, now }) };
+}
+/*
+ * An item as a reader of a finished record sees it: nothing streams any more and nothing belongs to a
+ * turn, so the timeline draws the whole conversation flat instead of folding it behind a turn it never had.
+ */
+export function settledReading(item) {
+    if (item.kind === 'assistant') {
+        return { ...item, turnId: null, streaming: false };
+    }
+    if (item.kind === 'thinking') {
+        return { ...item, turnId: null, streaming: false, endedAt: item.endedAt ?? item.createdAt };
+    }
+    return { ...item, turnId: null };
+}

package/dist/chat/subagent-reader.d.ts

@@ -0,0 +1,66 @@
+import { type ChatInfo, type ChatItem, type ChatSubagentChangedEvent, type ChatSubagentResult } from '@adecore/agent-contracts';
+import { type WatchSeams } from '../watch-seam.ts';
+import { type CodexProcessSpec, type ThreadItemsParams } from './codex-thread.ts';
+import { type SubagentSettlement } from './subagent-settlement.ts';
+export interface SubagentChat {
+    info: ChatInfo;
+    running: boolean;
+    items(): ChatItem[];
+    listThreadItems(params: ThreadItemsParams): Promise<unknown> | null;
+    noteNative(toolUseId: string, native: {
+        agentId?: string;
+        threadId?: string;
+    }): void;
+}
+export interface SubagentReaderOptions {
+    chat(chatId: string): SubagentChat | null;
+    chatInfo?(chatId: string): Promise<ChatInfo | null>;
+    claudeProjectsDir: string;
+    claudeProjectsDirOf?(info: ChatInfo): string;
+    codexProcess(info: ChatInfo): CodexProcessSpec;
+    notify(clientId: string, event: ChatSubagentChangedEvent): void;
+    seams?: WatchSeams;
+    now?(): number;
+    listOnce?(spec: CodexProcessSpec, params: ThreadItemsParams): Promise<unknown>;
+}
+export declare class SubagentReader {
+    private readonly options;
+    private readonly seams;
+    private readonly now;
+    private readonly listOnce;
+    private readonly claudeFiles;
+    private readonly projections;
+    private readonly codexRows;
+    private readonly codexCache;
+    private readonly codexSeen;
+    private readonly holds;
+    private readonly dirWatches;
+    private readonly changed;
+    private cancelSettle;
+    constructor(options: SubagentReaderOptions);
+    read(chatId: string, toolUseId: string, cursor?: string, limit?: number): Promise<ChatSubagentResult>;
+    readAll(chatId: string, toolUseId: string): Promise<ChatItem[]>;
+    claudeSettlement(chatId: string, toolUseId: string): Promise<SubagentSettlement | null>;
+    hold(clientId: string, chatId: string, toolUseId: string): void;
+    release(clientId: string, chatId: string, toolUseId: string): void;
+    releaseClient(clientId: string): void;
+    releaseChat(chatId: string): void;
+    get holdCount(): number;
+    private require;
+    private drop;
+    private live;
+    private readClaude;
+    private claudeProjection;
+    private claudeFile;
+    private trimProjections;
+    private claudeSubagentOf;
+    private readCodex;
+    private codexThreadOf;
+    private codexThread;
+    private codexPage;
+    private watchClaude;
+    private onClaudeChange;
+    private pollCodex;
+    private markChanged;
+    private flushChanged;
+}

package/dist/chat/subagent-reader.js

@@ -0,0 +1,396 @@
+import { dirname } from 'node:path';
+import { workflowAgentIdOf } from '@adecore/agent-contracts';
+import { SYSTEM_WATCH } from '../watch-seam.js';
+import { findSubagentsDir, findWorkflowAgent, readSubagentMetas, TranscriptProjection } from './claude-transcript.js';
+import { listThreadItemsOnce, parseThreadItemsPage, projectCodexItems } from './codex-thread.js';
+import { ChatError } from './errors.js';
+import { readSubagentSettlement } from './subagent-settlement.js';
+const DEFAULT_PAGE = 60;
+// How often an open panel asks a running Codex for the newest items of the thread it follows.
+const CODEX_POLL_MS = 2000;
+// A page asked of a process started for the question is kept this long, so paging back costs one process.
+const CODEX_CACHE_MS = 5000;
+// What a poll compares: enough of the newest end to see an item land or settle.
+const CODEX_POLL_ITEMS = 10;
+// Lines land in bursts; a panel is told once per burst, not once per line.
+const CHANGE_SETTLE_MS = 150;
+// Transcripts kept read, beyond the ones a client holds open.
+const MAX_IDLE_PROJECTIONS = 8;
+const CODEX_CURSOR = 'codex:';
+function holdKey(chatId, toolUseId) {
+    return `${chatId}\n${toolUseId}`;
+}
+function findSubagent(items, toolUseId) {
+    return items.find((item) => item.kind === 'subagent' && item.toolUseId === toolUseId);
+}
+// A workflow's agent works while its Workflow row runs and its last report has it running.
+function workflowAgentRunning(items, agentId) {
+    return items.some((item) => item.kind === 'tool' &&
+        item.state === 'running' &&
+        item.workflow?.agents.some((agent) => agent.agentId === agentId && agent.status === 'running') === true);
+}
+/*
+ * The whole conversation of a subagent, which the chat's own thread only keeps the beginning of:
+ * Claude's transcript beside the session, or the thread Codex keeps per agent. A client that holds a
+ * conversation is told when it grows (a counted watch on Claude's folder, a poll of the running Codex)
+ * for as long as it holds it, and the event carries nothing but that there is more.
+ */
+export class SubagentReader {
+    options;
+    seams;
+    now;
+    listOnce;
+    claudeFiles = new Map();
+    // Keyed on the transcript path, with the chat it was read for so a grandchild's status can be found.
+    projections = new Map();
+    // The subagents seen inside a Codex conversation, so a row of a grandchild knows its thread.
+    codexRows = new Map();
+    codexCache = new Map();
+    // The newest end of every Codex thread as a reader last saw it, which is what a poll compares against.
+    codexSeen = new Map();
+    holds = new Map();
+    dirWatches = new Map();
+    changed = new Set();
+    cancelSettle = null;
+    constructor(options) {
+        this.options = options;
+        this.seams = options.seams ?? SYSTEM_WATCH;
+        this.now = options.now ?? Date.now;
+        this.listOnce = options.listOnce ?? listThreadItemsOnce;
+    }
+    async read(chatId, toolUseId, cursor, limit = DEFAULT_PAGE) {
+        const chat = this.require(chatId);
+        return chat.info.provider === 'codex' ? this.readCodex(chat, toolUseId, cursor, limit) : this.readClaude(chat, toolUseId, cursor, limit);
+    }
+    /* Every item, for an agent reading the conversation as text; a Codex thread is paged through to its start. */
+    async readAll(chatId, toolUseId) {
+        const chat = this.require(chatId);
+        if (chat.info.provider !== 'codex') {
+            return (await this.claudeProjection(chat, toolUseId)).items();
+        }
+        const pages = [];
+        let cursor;
+        do {
+            const page = await this.readCodex(chat, toolUseId, cursor, 100);
+            pages.unshift(page.items);
+            cursor = page.history.cursor ?? undefined;
+        } while (cursor !== undefined);
+        return pages.flat();
+    }
+    /*
+     * What a Claude subagent's own transcript says about how it ended, for a row whose CLI is gone and
+     * so will never send the notification; null when there is no transcript or it does not show an end.
+     */
+    async claudeSettlement(chatId, toolUseId) {
+        const chat = this.options.chat(chatId);
+        if (!chat || chat.info.provider !== 'claude') {
+            return null;
+        }
+        try {
+            return await readSubagentSettlement((await this.claudeFile(chat, toolUseId)).path);
+        }
+        catch {
+            return null;
+        }
+    }
+    /* Keeps `clientId` told about this conversation until it lets go, closes its socket or the chat goes. */
+    hold(clientId, chatId, toolUseId) {
+        const key = holdKey(chatId, toolUseId);
+        const existing = this.holds.get(key);
+        if (existing) {
+            existing.clients.add(clientId);
+            return;
+        }
+        const chat = this.options.chat(chatId);
+        if (!chat) {
+            return;
+        }
+        const stop = chat.info.provider === 'codex' ? this.pollCodex(key, chatId, toolUseId) : this.watchClaude(key);
+        this.holds.set(key, { chatId, toolUseId, clients: new Set([clientId]), stop });
+    }
+    release(clientId, chatId, toolUseId) {
+        const key = holdKey(chatId, toolUseId);
+        const hold = this.holds.get(key);
+        if (!hold) {
+            return;
+        }
+        hold.clients.delete(clientId);
+        if (hold.clients.size === 0) {
+            this.drop(key, hold);
+        }
+    }
+    releaseClient(clientId) {
+        for (const hold of [...this.holds.values()]) {
+            this.release(clientId, hold.chatId, hold.toolUseId);
+        }
+    }
+    /* Forgets everything about a chat that is gone. */
+    releaseChat(chatId) {
+        const ofChat = (key) => key.startsWith(`${chatId}\n`);
+        for (const [key, hold] of [...this.holds]) {
+            if (ofChat(key)) {
+                this.drop(key, hold);
+            }
+        }
+        for (const [key, file] of [...this.claudeFiles]) {
+            if (ofChat(key)) {
+                this.claudeFiles.delete(key);
+                this.projections.delete(file.path);
+            }
+        }
+        for (const map of [this.codexRows, this.codexSeen]) {
+            for (const key of [...map.keys()]) {
+                if (ofChat(key)) {
+                    map.delete(key);
+                }
+            }
+        }
+    }
+    /* How many clients hold something, for a test that checks a socket let go of everything. */
+    get holdCount() {
+        return this.holds.size;
+    }
+    require(chatId) {
+        const chat = this.options.chat(chatId);
+        if (!chat) {
+            throw new ChatError('chat-not-found', `No chat ${chatId}`);
+        }
+        return chat;
+    }
+    drop(key, hold) {
+        this.holds.delete(key);
+        this.changed.delete(key);
+        hold.stop();
+    }
+    /* Running while its row says so, whether that row is in the chat's thread or in a conversation read before. */
+    live(chat, toolUseId, inside) {
+        const workflowAgent = workflowAgentIdOf(toolUseId);
+        if (workflowAgent !== null) {
+            return workflowAgentRunning(chat.items(), workflowAgent);
+        }
+        const row = findSubagent(chat.items(), toolUseId) ?? findSubagent(inside, toolUseId);
+        return row?.kind === 'subagent' && row.status === 'running';
+    }
+    async readClaude(chat, toolUseId, cursor, limit) {
+        const projection = await this.claudeProjection(chat, toolUseId);
+        const page = projection.page(limit, cursor);
+        const seen = [...this.projections.values()].filter((entry) => entry.chatId === chat.info.chatId).flatMap((entry) => entry.projection.items());
+        return {
+            items: page.items,
+            history: page.history,
+            source: 'claude-transcript',
+            context: { provider: 'claude', cwd: chat.info.cwd },
+            live: this.live(chat, toolUseId, seen)
+        };
+    }
+    async claudeProjection(chat, toolUseId) {
+        const file = await this.claudeFile(chat, toolUseId);
+        let entry = this.projections.get(file.path);
+        if (!entry) {
+            entry = { chatId: chat.info.chatId, projection: new TranscriptProjection(file.path) };
+            this.projections.set(file.path, entry);
+            this.trimProjections();
+        }
+        if (!(await entry.projection.refresh())) {
+            throw new ChatError('subagent-not-found', 'Claude has not written a transcript for this subagent');
+        }
+        return entry.projection;
+    }
+    async claudeFile(chat, toolUseId) {
+        const key = holdKey(chat.info.chatId, toolUseId);
+        const known = this.claudeFiles.get(key);
+        if (known) {
+            return known;
+        }
+        const found = await this.claudeSubagentOf(chat.info, toolUseId);
+        if (found === null) {
+            throw new ChatError('subagent-not-found', 'Claude has not written a transcript for this subagent');
+        }
+        const { dir, meta } = found;
+        const file = { dir, path: meta.transcript };
+        this.claudeFiles.set(key, file);
+        chat.noteNative(toolUseId, { agentId: meta.agentId });
+        return file;
+    }
+    /* The transcripts nobody holds are only a cache: past a handful, the oldest is read again when asked. */
+    trimProjections() {
+        const held = new Set([...this.holds.values()].map((hold) => this.claudeFiles.get(holdKey(hold.chatId, hold.toolUseId))?.path));
+        const idle = [...this.projections.keys()].filter((path) => !held.has(path));
+        for (const path of idle.slice(0, Math.max(0, idle.length - MAX_IDLE_PROJECTIONS))) {
+            this.projections.delete(path);
+        }
+    }
+    /*
+     * The folder and meta of a subagent, in the chat's own session or, for a row a fork copied, in the
+     * session of the chat it was forked from: the CLI keeps subagents beside the session that ran them,
+     * and a fork's transcript is a new session with none. One step per fork, so a fork of a fork works too.
+     */
+    async claudeSubagentOf(info, toolUseId) {
+        const seen = new Set();
+        let current = info;
+        while (current !== null && !seen.has(current.chatId)) {
+            seen.add(current.chatId);
+            const sessionId = current.agentSessionId;
+            const dir = sessionId === null
+                ? null
+                : await findSubagentsDir(this.options.claudeProjectsDirOf?.(current) ?? this.options.claudeProjectsDir, current.cwd, sessionId);
+            const workflowAgent = workflowAgentIdOf(toolUseId);
+            if (dir !== null && workflowAgent !== null) {
+                const meta = await findWorkflowAgent(dir, workflowAgent);
+                if (meta !== null) {
+                    return { dir: dirname(meta.transcript), meta };
+                }
+            }
+            // A grandchild has a file of its own in the same folder, found by the call that opened it like any other.
+            const meta = dir === null ? undefined : (await readSubagentMetas(dir)).find((candidate) => candidate.toolUseId === toolUseId);
+            if (dir !== null && meta !== undefined) {
+                return { dir, meta };
+            }
+            const origin = current.forkOf?.chatId;
+            current = origin === undefined || !this.options.chatInfo ? null : await this.options.chatInfo(origin);
+        }
+        return null;
+    }
+    async readCodex(chat, toolUseId, cursor, limit) {
+        const threadId = this.codexThread(chat, toolUseId);
+        if (cursor !== undefined && !cursor.startsWith(CODEX_CURSOR)) {
+            throw new ChatError('history-expired', 'The conversation changed. Reload its history.');
+        }
+        const params = {
+            threadId,
+            limit,
+            sortDirection: 'desc',
+            ...(cursor === undefined ? {} : { cursor: cursor.slice(CODEX_CURSOR.length) })
+        };
+        const { entries, nextCursor } = parseThreadItemsPage(await this.codexPage(chat, params));
+        if (cursor === undefined) {
+            // What a poll that starts after this read compares against, so a change in between is not lost.
+            this.codexSeen.set(holdKey(chat.info.chatId, toolUseId), JSON.stringify(entries.slice(0, CODEX_POLL_ITEMS)));
+        }
+        const items = projectCodexItems([...entries].reverse(), this.now());
+        for (const item of items) {
+            if (item.kind === 'subagent') {
+                this.codexRows.set(holdKey(chat.info.chatId, item.toolUseId), item);
+            }
+        }
+        return {
+            items,
+            history: { cursor: nextCursor === null ? null : `${CODEX_CURSOR}${nextCursor}` },
+            source: 'codex-thread',
+            context: { provider: 'codex', cwd: chat.info.cwd },
+            live: chat.running && this.live(chat, toolUseId, [...this.codexRows.values()])
+        };
+    }
+    codexThreadOf(chat, toolUseId) {
+        const row = findSubagent(chat.items(), toolUseId) ?? this.codexRows.get(holdKey(chat.info.chatId, toolUseId));
+        return row?.kind === 'subagent' ? (row.native?.threadId ?? null) : null;
+    }
+    codexThread(chat, toolUseId) {
+        const threadId = this.codexThreadOf(chat, toolUseId);
+        if (threadId === null) {
+            throw new ChatError('subagent-not-found', 'Codex has not said which thread this subagent works in');
+        }
+        return threadId;
+    }
+    async codexPage(chat, params) {
+        const running = chat.listThreadItems(params);
+        if (running !== null) {
+            return running;
+        }
+        const key = JSON.stringify(params);
+        const now = this.now();
+        const cached = this.codexCache.get(key);
+        if (cached && now - cached.at < CODEX_CACHE_MS) {
+            return cached.result;
+        }
+        const result = await this.listOnce(this.options.codexProcess(chat.info), params);
+        for (const [stale, entry] of [...this.codexCache]) {
+            if (now - entry.at >= CODEX_CACHE_MS) {
+                this.codexCache.delete(stale);
+            }
+        }
+        this.codexCache.set(key, { at: now, result });
+        return result;
+    }
+    /* One watch per subagents folder, however many of its transcripts are held. */
+    watchClaude(key) {
+        const file = this.claudeFiles.get(key);
+        if (!file) {
+            return () => undefined;
+        }
+        let shared = this.dirWatches.get(file.dir);
+        if (!shared) {
+            const watcher = this.seams.watch(file.dir, { recursive: false }, (_event, filename) => this.onClaudeChange(file.dir, filename));
+            // A folder that disappears ends the growing, not the host.
+            watcher.on('error', () => undefined);
+            shared = { watcher, keys: new Set() };
+            this.dirWatches.set(file.dir, shared);
+        }
+        shared.keys.add(key);
+        return () => {
+            const current = this.dirWatches.get(file.dir);
+            current?.keys.delete(key);
+            if (current && current.keys.size === 0) {
+                current.watcher.close();
+                this.dirWatches.delete(file.dir);
+            }
+        };
+    }
+    onClaudeChange(dir, filename) {
+        for (const key of this.dirWatches.get(dir)?.keys ?? []) {
+            const path = this.claudeFiles.get(key)?.path;
+            // A platform that names no file could mean any of them.
+            if (filename === null || (path !== undefined && path.endsWith(`/${filename}`))) {
+                this.markChanged(key);
+            }
+        }
+    }
+    pollCodex(key, chatId, toolUseId) {
+        let cancel = null;
+        let stopped = false;
+        const tick = async () => {
+            cancel = null;
+            const chat = this.options.chat(chatId);
+            const threadId = chat ? this.codexThreadOf(chat, toolUseId) : null;
+            const asked = chat && threadId ? chat.listThreadItems({ threadId, limit: CODEX_POLL_ITEMS, sortDirection: 'desc' }) : null;
+            if (asked !== null) {
+                try {
+                    const seen = JSON.stringify(parseThreadItemsPage(await asked).entries);
+                    if (!stopped && this.codexSeen.get(key) !== seen) {
+                        this.codexSeen.set(key, seen);
+                        this.markChanged(key);
+                    }
+                }
+                catch {
+                    // The process went between the question and the answer; the next tick asks again.
+                }
+            }
+            if (!stopped) {
+                cancel = this.seams.schedule(() => tick(), CODEX_POLL_MS);
+            }
+        };
+        cancel = this.seams.schedule(() => tick(), CODEX_POLL_MS);
+        return () => {
+            stopped = true;
+            cancel?.();
+        };
+    }
+    markChanged(key) {
+        this.changed.add(key);
+        if (this.cancelSettle !== null) {
+            return;
+        }
+        this.cancelSettle = this.seams.schedule(() => this.flushChanged(), CHANGE_SETTLE_MS);
+    }
+    flushChanged() {
+        this.cancelSettle = null;
+        const keys = [...this.changed];
+        this.changed.clear();
+        for (const key of keys) {
+            const hold = this.holds.get(key);
+            for (const clientId of hold?.clients ?? []) {
+                this.options.notify(clientId, { chatId: hold.chatId, toolUseId: hold.toolUseId });
+            }
+        }
+    }
+}

package/dist/chat/subagent-settlement.d.ts

@@ -0,0 +1,6 @@
+export interface SubagentSettlement {
+    finishedAt: number | null;
+    report: string | null;
+}
+export declare function settlementOf(text: string): SubagentSettlement | null;
+export declare function readSubagentSettlement(path: string): Promise<SubagentSettlement | null>;