klyro 0.1.63 → 1.0.1

package/dist/agent/orchestrator.js

@@ -0,0 +1,589 @@
+/**
+ * AgentOrchestrator — spawns child agents and turns them into tasks.
+ *
+ * The lowest-level way to run Klyro is `run(options, deps)` (one agent,
+ * one loop). Orchestration layers on top of that: a parent agent calls
+ * `spawn_agent`, which resolves the target `AgentDefinition`, computes its
+ * effective capabilities (via `resolveCapabilities`), creates a
+ * `TaskRecord`, and runs a *scoped* child loop. The child runs in-process
+ * with a `ScopedRegistry` (narrowed tool set), an optional model override,
+ * a depth cap, and an AbortController wired to the parent's signal.
+ *
+ * The compact result is a `ChildSummary` — a `ToolResult` the parent model
+ * can act on — never the full child transcript.
+ */
+import { run, resolveSystemPrompt } from './runtime.js';
+import { ScopedRegistry } from './scoped-registry.js';
+import { globalBus } from '../events/bus.js';
+import { TaskManager } from './task-manager.js';
+import { WorkerSpawner } from './worker-spawner.js';
+import { resolveCapabilities, DEFAULT_WRITE_TOOLS, DEFAULT_SPAWN_TOOLS, DEFAULT_DENIED_TOOLS, } from './capabilities.js';
+import { forkChild, workerEntryPath } from './child-worker.js';
+import { resolveAndFollowSymlinks } from '../policy/path-guard.js';
+import { ensureGitRepo, createWorktree, mergeWorktree, removeWorktree, deleteBranch, } from './worktree-manager.js';
+/** Concurrency budgets enforced in `spawnAgent` (CONCURRENCY_LIMIT on exceed). */
+export const MAX_CONCURRENT_TASKS = 4;
+export const MAX_TASKS_PER_PARENT = 8;
+export const MAX_TOTAL_TASKS_PER_SESSION = 32;
+/** Default agents a model can delegate to. */
+export const BUILTIN_AGENTS = [
+    {
+        id: 'explorer',
+        description: 'Read-only reconnaissance: map the repo, find symbols and tests.',
+        readonly: true,
+        canSpawn: false,
+        allowedTools: ['read_file', 'list_directory', 'glob', 'grep', 'search_files', 'repo_map', 'find_symbol', 'git_status', 'git_log', 'git_diff', 'recent_files', 'imports_of', 'importers_of'],
+    },
+    {
+        id: 'implementer',
+        description: 'Write-capable worker for concrete, well-scoped coding tasks.',
+        canSpawn: false,
+        allowedTools: ['read_file', 'list_directory', 'glob', 'grep', 'search_files', 'write_file', 'edit_file', 'multi_edit', 'apply_patch', 'shell_exec', 'git_status', 'git_log', 'git_diff', 'run_verify', 'todo_write'],
+        maxSteps: 60,
+    },
+    {
+        id: 'tester',
+        description: 'Runs verification and tests, reports failures with diagnostics.',
+        canSpawn: false,
+        allowedTools: ['read_file', 'list_directory', 'glob', 'grep', 'shell_exec', 'run_verify', 'git_status', 'git_log', 'git_diff'],
+        maxTimeMs: 120_000,
+    },
+    {
+        id: 'reviewer',
+        description: 'Read-only review of a diff or change set for bugs.',
+        readonly: true,
+        canSpawn: false,
+        allowedTools: ['read_file', 'list_directory', 'glob', 'grep', 'search_files', 'git_status', 'git_diff', 'git_log', 'imports_of', 'importers_of', 'find_symbol'],
+    },
+    {
+        id: 'debugger',
+        description: 'Read-only diagnosis: inspect failures, traces, and code paths without modifying files.',
+        readonly: true,
+        canSpawn: false,
+        allowedTools: ['read_file', 'list_directory', 'glob', 'grep', 'search_files', 'repo_map', 'find_symbol', 'imports_of', 'importers_of', 'git_status', 'git_log', 'git_diff', 'recent_files', 'run_verify'],
+    },
+    {
+        id: 'docs',
+        description: 'Read-only documentation lookup: find and summarise docs, READMEs, and code structure.',
+        readonly: true,
+        canSpawn: false,
+        allowedTools: ['read_file', 'list_directory', 'glob', 'grep', 'search_files', 'repo_map', 'recent_files'],
+    },
+];
+/** Map a runtime `RunResult.status` to a task status. */
+function mapResultStatus(status) {
+    switch (status) {
+        case 'complete':
+            return 'succeeded';
+        case 'aborted':
+            return 'cancelled';
+        case 'blocked':
+            return 'blocked';
+        case 'max_steps':
+        case 'no_final':
+        case 'verify_failed':
+        case 'limit':
+        case 'stuck':
+            return 'failed';
+    }
+}
+export class AgentOrchestrator {
+    sessionId;
+    deps;
+    taskManager;
+    workerSpawner;
+    isTui;
+    /** Per-task spawn metadata: capability drops + worktree placement. */
+    taskMeta = new Map();
+    /** Finished summaries not yet drained via `drainCompletions`. */
+    undrained = new Map();
+    constructor(opts) {
+        this.sessionId = opts.sessionId;
+        this.deps = opts.deps;
+        this.taskManager = opts.taskManager ?? new TaskManager({ sessionId: opts.sessionId });
+        this.workerSpawner = opts.workerSpawner ?? new WorkerSpawner();
+        this.isTui = opts.isTui ?? false;
+    }
+    listAgents() {
+        return [...BUILTIN_AGENTS];
+    }
+    getAgent(id) {
+        return BUILTIN_AGENTS.find((a) => a.id === id);
+    }
+    /** Build the bridge the parent's runtime hands to tools. */
+    bridgeFor(parent) {
+        return {
+            parent,
+            listAgents: () => this.listAgents(),
+            getAgent: (id) => this.getAgent(id),
+            spawnAgent: (input) => this.spawnAgent(input, parent),
+            listTasks: (filter) => this.taskManager.list(filter),
+            getTask: (id) => {
+                const r = this.taskManager.get(id);
+                if (!r)
+                    return undefined;
+                const s = this.taskManager.toSummary(r);
+                return r.error ? { ...s, error: { code: r.error.code, message: r.error.message } } : s;
+            },
+            drainCompletions: () => this.drainCompletions(),
+            waitForTasks: (taskIds, timeoutMs) => this.waitForTasks(taskIds, timeoutMs),
+            cancelTask: (taskId) => this.cancelTask(taskId),
+            applyTask: (taskId) => this.applyTask(taskId),
+        };
+    }
+    /** Compute a child's effective capabilities from the parent's own. */
+    resolveChild(def, parent, registryTools) {
+        const input = {
+            parentTools: parent.allowedTools,
+            agent: def,
+            policyAllowed: registryTools,
+            registryTools,
+            writeTools: DEFAULT_WRITE_TOOLS,
+            spawnTools: DEFAULT_SPAWN_TOOLS,
+            denied: DEFAULT_DENIED_TOOLS,
+        };
+        const resolved = resolveCapabilities({ ...input, maxDepth: parent.maxDepth, parentAllowedPaths: parent.allowedPaths });
+        return resolved;
+    }
+    /**
+     * Spawn a child agent asynchronously: start the child worker and return
+     * IMMEDIATELY with `{ status: 'running' }`. Completion/failure bus emits
+     * and `taskManager.finish` happen in the worker closure; the parent
+     * observes them via `task_wait` / `task_get` / `drainCompletions`.
+     */
+    async spawnAgent(input, parent) {
+        const def = this.getAgent(input.agent);
+        if (!def) {
+            return {
+                ok: false,
+                error: { code: 'UNKNOWN_AGENT', message: `Unknown agent: ${input.agent}` },
+            };
+        }
+        // Depth guard — block before creating a (running) task.
+        const childDepth = parent.depth + 1;
+        const maxDepth = def.maxDepth ?? parent.maxDepth;
+        if (childDepth > maxDepth) {
+            return {
+                ok: false,
+                error: {
+                    code: 'RECURSION_LIMIT',
+                    message: `maxDepth exceeded for agent "${def.id}": cannot spawn at depth ${childDepth} (cap ${maxDepth})`,
+                },
+            };
+        }
+        // Concurrency budgets — enforced before creating the task.
+        const all = this.taskManager.list();
+        const runningCount = all.filter((t) => t.status === 'running').length;
+        if (runningCount >= MAX_CONCURRENT_TASKS) {
+            return {
+                ok: false,
+                error: { code: 'CONCURRENCY_LIMIT', message: `maxConcurrentTasks (${MAX_CONCURRENT_TASKS}) reached` },
+            };
+        }
+        const perParentCount = all.filter((t) => t.parentTaskId === parent.taskId).length;
+        if (perParentCount >= MAX_TASKS_PER_PARENT) {
+            return {
+                ok: false,
+                error: { code: 'CONCURRENCY_LIMIT', message: `maxTasksPerParent (${MAX_TASKS_PER_PARENT}) reached` },
+            };
+        }
+        if (all.length >= MAX_TOTAL_TASKS_PER_SESSION) {
+            return {
+                ok: false,
+                error: { code: 'CONCURRENCY_LIMIT', message: `maxTotalTasksPerSession (${MAX_TOTAL_TASKS_PER_SESSION}) reached` },
+            };
+        }
+        // Spawn cwd containment (S6): an explicit cwd must stay inside the parent.
+        let baseCwd = parent.cwd;
+        if (input.cwd) {
+            try {
+                baseCwd = (await resolveAndFollowSymlinks(parent.cwd, input.cwd)).resolved;
+            }
+            catch (err) {
+                return {
+                    ok: false,
+                    error: {
+                        code: 'PATH_ESCAPE',
+                        message: err instanceof Error ? err.message : `cwd escapes parent: ${input.cwd}`,
+                    },
+                };
+            }
+        }
+        const registryTools = new Set(this.deps.registry.list().map((t) => t.name));
+        const resolved = this.resolveChild(def, parent, registryTools);
+        const childModel = input.model ?? resolved.model ?? parent.model;
+        // Worktree isolation: write-capable children without an explicit cwd get
+        // their own worktree; readonly agents keep the parent cwd. A
+        // write-capable spawn outside a git repo is rejected outright.
+        const writeCapable = [...resolved.allowed].some((t) => DEFAULT_WRITE_TOOLS.has(t));
+        let childCwd = baseCwd;
+        let worktree;
+        let repoCwd;
+        if (!resolved.readonly && writeCapable && !input.cwd) {
+            const isRepo = await ensureGitRepo(baseCwd).catch(() => false);
+            if (!isRepo) {
+                return {
+                    ok: false,
+                    error: { code: 'WRITES_REQUIRE_GIT', message: 'parallel write agents require a git repository for worktree isolation' },
+                };
+            }
+            repoCwd = baseCwd;
+        }
+        const createOpts = {
+            agentName: def.id,
+            cwd: childCwd,
+            depth: childDepth,
+            maxDepth,
+            model: childModel,
+            parentTaskId: parent.taskId,
+            timeoutMs: input.timeoutMs ?? def.maxTimeMs,
+            abortOnParent: undefined, // wired below via the parent signal
+        };
+        const record = this.taskManager.create(createOpts);
+        // Worktree creation needs the task id (branch `klyro/<taskId>`), so it
+        // happens after `create`. On failure the task is marked failed and the
+        // spawn returns the error.
+        if (repoCwd !== undefined) {
+            try {
+                worktree = await createWorktree({ repoCwd, taskId: record.id });
+                childCwd = worktree.worktreePath;
+                record.cwd = childCwd;
+            }
+            catch (err) {
+                this.taskManager.finish(record.id, 'failed', {
+                    error: { code: 'WORKTREE_FAILED', message: err instanceof Error ? err.message : String(err) },
+                });
+                const failed = this.taskManager.get(record.id);
+                this.stashSummary(failed, def, resolved.dropped);
+                this.taskMeta.set(record.id, { def, dropped: resolved.dropped });
+                return {
+                    ok: false,
+                    error: { code: 'WORKTREE_FAILED', message: err instanceof Error ? err.message : String(err) },
+                };
+            }
+        }
+        this.taskMeta.set(record.id, worktree ? { def, dropped: resolved.dropped, worktree, repoCwd } : { def, dropped: resolved.dropped });
+        const childRegistry = new ScopedRegistry(this.deps.registry, resolved.allowed);
+        const childDeps = { ...this.deps, registry: childRegistry };
+        const childRef = {
+            taskId: record.id,
+            ...(parent.taskId !== undefined ? { parentTaskId: parent.taskId } : {}),
+            sessionId: this.sessionId,
+            cwd: childCwd,
+            depth: childDepth,
+            maxDepth,
+            allowedTools: resolved.allowed,
+            ...(childModel !== undefined ? { model: childModel } : {}),
+            ...(resolved.allowedPaths !== undefined ? { allowedPaths: resolved.allowedPaths } : {}),
+        };
+        const childOptions = {
+            task: input.task,
+            cwd: childCwd,
+            model: childModel ?? 'inherit', // model override must reach the adapter (see runtime)
+            maxSteps: def.maxSteps,
+            maxCost: def.maxCost,
+            maxTimeMs: def.maxTimeMs ?? input.timeoutMs,
+            signal: record.abortController.signal,
+            nonInteractive: true,
+            // Grandchildren: only children that canSpawn receive the bridge —
+            // otherwise tools see NO_ORCHESTRATOR as before.
+            ...(resolved.canSpawn ? { agentBridge: this.bridgeFor(childRef) } : {}),
+            ...(def.maxTokens !== undefined ? { maxTokens: def.maxTokens } : {}),
+        };
+        // Lifecycle events on the shared bus (mirror TaskManager transitions).
+        globalBus.emit({
+            type: 'subtask.started',
+            ts: Date.now(),
+            sessionId: this.sessionId,
+            taskId: record.id,
+            ...(record.parentTaskId ? { parentTaskId: record.parentTaskId } : {}),
+            agentName: def.id,
+            depth: childDepth,
+            ...(typeof childModel === 'string' ? { model: childModel } : {}),
+        });
+        // G2 — process isolation for headless sub-agents. In-process is the
+        // fallback (and mandatory for TUI children — see OrchestratorOpts.isTui),
+        // and opt-out via KLYRO_WORKER=0 for tests/dev.
+        const useProcessIsolation = !this.isTui && process.env.KLYRO_WORKER !== '0';
+        this.workerSpawner.spawn(async (signal) => {
+            // Both the in-process path and the forked child resolve to the same
+            // minimal outcome shape the settle tail needs.
+            let childOutcome;
+            try {
+                if (useProcessIsolation) {
+                    const sysPrompt = resolveSystemPrompt(this.deps.systemPrompt, { cwd: childCwd });
+                    // Splice the volatile telemetry suffix into the stable prefix so the
+                    // child's provider sees one system string. Telemetry is best-effort
+                    // inside the child (it re-emits); the goal here is parity, not
+                    // perfect replay.
+                    const systemPrompt = sysPrompt.suffix ? `${sysPrompt.system}\n${sysPrompt.suffix}` : sysPrompt.system;
+                    const payload = {
+                        cwd: childCwd,
+                        task: input.task,
+                        // A concrete provider model must reach the child — 'inherit' only
+                        // exists to defer resolution inside the parent's run().
+                        model: (childModel ?? parent.model),
+                        systemPrompt,
+                        agentId: def.id,
+                        maxSteps: def.maxSteps,
+                        maxCost: def.maxCost,
+                        maxTimeMs: def.maxTimeMs ?? input.timeoutMs,
+                        ...(def.maxTokens !== undefined ? { maxTokens: def.maxTokens } : {}),
+                    };
+                    const cr = await forkChild(workerEntryPath(), payload, { signal });
+                    childOutcome = cr; // ChildResult is the minimal settle shape
+                }
+                else {
+                    const r = await run(childOptions, childDeps);
+                    childOutcome = { status: r.status, steps: r.steps, toolCalls: r.toolCalls, finalText: r.finalText };
+                }
+            }
+            catch (err) {
+                const isCrash = err instanceof Error && err.name === 'ChildCrashError';
+                const crashErr = isCrash ? err : undefined;
+                this.settleChild(record.id, 'failed', {
+                    error: {
+                        code: 'CHILD_CRASH',
+                        message: isCrash
+                            ? `child process isolated failure (${crashErr?.likelyCause ?? 'exit'}): ${crashErr?.message ?? ''}`.trim()
+                            : err instanceof Error ? err.message : String(err),
+                    },
+                }, { steps: 0, toolCalls: 0 });
+                return;
+            }
+            const status = mapResultStatus(childOutcome.status);
+            this.settleChild(record.id, status, {
+                summary: [`status: ${status}`, `steps: ${childOutcome.steps}`, `toolCalls: ${childOutcome.toolCalls}`],
+                error: status === 'failed'
+                    ? { code: mapFailureCode(childOutcome.status), message: childOutcome.finalText?.slice(0, 300) ?? 'child failed' }
+                    : undefined,
+            }, { steps: childOutcome.steps, toolCalls: childOutcome.toolCalls });
+        }, { label: `agent:${def.id}` });
+        // Async contract: return immediately with the running summary. The final
+        // text is omitted while running; observe via task_wait / drainCompletions.
+        return {
+            ok: true,
+            value: { taskId: record.id, agentName: def.id, status: 'running', durationMs: 0, changedFiles: [] },
+        };
+    }
+    /**
+     * Settle a child in the worker closure: finish the task (idempotent —
+     * a TaskManager timeout/cancel that fired first wins), emit the terminal
+     * bus event, stash the summary for `drainCompletions`, and best-effort
+     * remove the worktree unless the child succeeded (merge happens later in
+     * `task_apply`).
+     */
+    settleChild(taskId, status, patch, counts) {
+        const existing = this.taskManager.get(taskId);
+        if (!existing)
+            return;
+        let finalStatus = status;
+        if (existing.status === 'queued' || existing.status === 'running') {
+            this.taskManager.finish(taskId, status, patch);
+        }
+        else {
+            // Already terminal (timeout/cancel raced the run) — preserve it.
+            finalStatus = existing.status;
+        }
+        const final = this.taskManager.get(taskId);
+        this.stashSummary(final);
+        const durationMs = final.finishedAt ? final.finishedAt - final.startedAt : 0;
+        const error = final.error ? { code: final.error.code, message: final.error.message } : undefined;
+        const steps = counts?.steps ?? 0;
+        const toolCalls = counts?.toolCalls ?? 0;
+        if (finalStatus === 'succeeded') {
+            globalBus.emit({
+                type: 'subtask.completed',
+                ts: Date.now(),
+                sessionId: this.sessionId,
+                taskId,
+                status: 'succeeded',
+                durationMs,
+                steps,
+                toolCalls,
+            });
+        }
+        else if (finalStatus === 'cancelled') {
+            globalBus.emit({
+                type: 'subtask.cancelled',
+                ts: Date.now(),
+                sessionId: this.sessionId,
+                taskId,
+                status: 'cancelled',
+                durationMs,
+                ...(error ? { error } : {}),
+            });
+        }
+        else if (finalStatus === 'timed_out') {
+            globalBus.emit({
+                type: 'subtask.timed_out',
+                ts: Date.now(),
+                sessionId: this.sessionId,
+                taskId,
+                status: 'timed_out',
+                durationMs,
+                ...(error ? { error } : {}),
+            });
+        }
+        else {
+            globalBus.emit({
+                type: 'subtask.failed',
+                ts: Date.now(),
+                sessionId: this.sessionId,
+                taskId,
+                status: finalStatus,
+                durationMs,
+                ...(error ? { error } : {}),
+            });
+        }
+        // Non-success terminal states never merge — drop the worktree.
+        const meta = this.taskMeta.get(taskId);
+        if (meta?.worktree && meta.repoCwd && finalStatus !== 'succeeded') {
+            const { worktree, repoCwd } = meta;
+            void removeWorktree({ repoCwd, worktreePath: worktree.worktreePath, force: true }).catch(() => undefined);
+        }
+    }
+    /** Build and stash the finished summary for `drainCompletions`. */
+    stashSummary(r, def, dropped) {
+        const meta = this.taskMeta.get(r.id);
+        const d = def ?? meta?.def;
+        if (!d)
+            return;
+        this.undrained.set(r.id, this.toChildSummary(r, d, dropped ?? meta?.dropped ?? []));
+    }
+    /** Completed-then-undrained child summaries; each drained exactly once. */
+    drainCompletions() {
+        const out = [...this.undrained.values()];
+        this.undrained.clear();
+        return out;
+    }
+    /**
+     * Await each task's `done` up to `timeoutMs` per task. Unsettled entries
+     * come back with status `'running'` and a running summary — the underlying
+     * task is NOT cancelled.
+     */
+    async waitForTasks(taskIds, timeoutMs) {
+        const tasks = await Promise.all(taskIds.map(async (taskId) => {
+            const rec = this.taskManager.get(taskId);
+            if (!rec) {
+                return { taskId, status: 'failed', error: { code: 'NOT_FOUND', message: `Unknown task: ${taskId}` } };
+            }
+            const meta = this.taskMeta.get(taskId);
+            const settled = await this.awaitDone(rec, timeoutMs);
+            const summary = meta ? this.toChildSummary(settled, meta.def, meta.dropped) : undefined;
+            const entry = { taskId, status: settled.status };
+            if (summary)
+                entry.summary = summary;
+            if (settled.error)
+                entry.error = { code: settled.error.code, message: settled.error.message };
+            return entry;
+        }));
+        return { tasks };
+    }
+    async awaitDone(rec, timeoutMs) {
+        if (timeoutMs === undefined)
+            return rec.done;
+        let timer;
+        try {
+            return await Promise.race([
+                rec.done,
+                new Promise((resolve) => {
+                    timer = setTimeout(() => resolve(this.taskManager.get(rec.id)), timeoutMs);
+                }),
+            ]);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
+    /** Signal abort for a live task via `taskManager.cancel` (in-process workers; no subprocesses yet). Idempotent on terminal tasks. */
+    cancelTask(taskId) {
+        const rec = this.taskManager.get(taskId);
+        if (!rec) {
+            return { ok: false, error: { code: 'NOT_FOUND', message: `Unknown task: ${taskId}` } };
+        }
+        this.taskManager.cancel(taskId, 'stopped via task_stop');
+        const final = this.taskManager.get(taskId);
+        return { ok: true, value: { taskId, status: final.status } };
+    }
+    /**
+     * Apply a succeeded task: merge its worktree branch into the parent tree
+     * (or acknowledge a shared-cwd task whose edits already landed) and emit
+     * `subtask.merged`. Non-succeeded tasks error with NOT_READY; merge
+     * conflicts error with MERGE_CONFLICT (merge already aborted, branch kept).
+     */
+    async applyTask(taskId) {
+        const rec = this.taskManager.get(taskId);
+        if (!rec) {
+            return { ok: false, error: { code: 'NOT_FOUND', message: `Unknown task: ${taskId}` } };
+        }
+        if (rec.status !== 'succeeded') {
+            return {
+                ok: false,
+                error: { code: 'NOT_READY', message: `task ${taskId} is ${rec.status}, not succeeded` },
+            };
+        }
+        const meta = this.taskMeta.get(taskId);
+        const summary = meta ? this.toChildSummary(rec, meta.def, meta.dropped) : this.toChildSummary(rec, this.getAgent(rec.agentName) ?? { id: rec.agentName, description: '' }, []);
+        // merged=true only when a real worktree branch merge ran; shared-cwd
+        // tasks (edits already in the parent tree) are an acknowledgement.
+        let didMerge = false;
+        if (meta?.worktree && meta.repoCwd) {
+            const merged = await mergeWorktree({ repoCwd: meta.repoCwd, branch: meta.worktree.branch });
+            if (!merged.merged) {
+                return {
+                    ok: false,
+                    error: {
+                        code: 'MERGE_CONFLICT',
+                        message: `merge of ${meta.worktree.branch} conflicted`,
+                        details: { conflictFiles: merged.conflictFiles },
+                    },
+                };
+            }
+            await removeWorktree({ repoCwd: meta.repoCwd, worktreePath: meta.worktree.worktreePath }).catch(() => undefined);
+            await deleteBranch({ repoCwd: meta.repoCwd, branch: meta.worktree.branch });
+            didMerge = true;
+        }
+        globalBus.emit({
+            type: 'subtask.merged',
+            ts: Date.now(),
+            sessionId: this.sessionId,
+            taskId,
+            changedFiles: summary.changedFiles,
+            merged: didMerge,
+        });
+        return { ok: true, value: summary };
+    }
+    /** Compact summary for a task record (also used by task_wait). */
+    toChildSummary(r, def, dropped) {
+        const s = this.taskManager.toSummary(r);
+        return {
+            taskId: s.id,
+            agentName: s.agentName,
+            status: s.status,
+            durationMs: s.durationMs ?? 0,
+            ...(def.model ? { model: def.model } : {}),
+            changedFiles: r.summary.filter((line) => line.startsWith('changed: ')).map((line) => line.slice('changed: '.length)),
+            droppedTools: dropped.length ? dropped : undefined,
+            error: r.error ? { code: r.error.code, message: r.error.message } : undefined,
+        };
+    }
+}
+function mapFailureCode(status) {
+    switch (status) {
+        case 'max_steps':
+            return 'MAX_STEPS';
+        case 'verify_failed':
+            return 'VERIFY_FAILED';
+        case 'limit':
+            return 'LIMIT';
+        case 'stuck':
+            return 'STUCK';
+        case 'no_final':
+        default:
+            return 'NO_FINAL';
+    }
+}
+/** Module-scoped holder the orchestrator sets so children inherit the parent's signal. */
+export const parentAbortSignalRef = { current: null };

package/dist/agent/provider-adapter.d.ts

@@ -28,6 +28,8 @@ export type StreamEvent = {
     usage?: {
         input: number;
         output: number;
+        cacheRead?: number;
+        cacheWrite?: number;
     };
 } | {
     kind: 'tool_call_start';
@@ -45,6 +47,8 @@ export type StreamEvent = {
     code: string;
     message: string;
     retryable: boolean;
+    status?: string;
+    retryAfterMs?: number;
 };
 export interface ToolDefinition {
     name: string;
@@ -54,6 +58,12 @@ export interface ToolDefinition {
 export interface CallRequest {
     model: string;
     system?: string;
+    /**
+     * Volatile prompt suffix (Level-7 runtime telemetry). Adapters keep it
+     * out of the cacheable prefix: Anthropic sends the array system form
+     * (breakpoint on the stable part), OpenAI appends it with a separator.
+     */
+    systemSuffix?: string;
     messages: Message[];
     tools: ToolDefinition[];
     maxTokens?: number;
@@ -72,6 +82,13 @@ export interface HttpAdapterOptions {
     /** Override fetch (e.g. for tests). */
     fetchImpl?: typeof fetch;
 }
+/**
+ * Parse a `Retry-After` response header value into milliseconds.
+ * Returns undefined when absent or unparseable. Handles both forms:
+ * delay-seconds ("120") and HTTP-date ("Wed, 21 Oct 2015 07:28:00 GMT",
+ * clamped at 0 when the date is in the past).
+ */
+export declare function parseRetryAfterMs(value: string | null | undefined): number | undefined;
 /** Convert a Zod schema to a permissive JSON Schema object for tool defs. */
 export declare function zodToJsonSchema(schema: z.ZodType<unknown>): Record<string, unknown>;
 interface ChatCompletionsRequest {