klyro 0.1.62 → 1.0.0

package/dist/agent/orchestrator.d.ts

@@ -0,0 +1,131 @@
+/**
+ * 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 type { RuntimeDeps } from './runtime.js';
+import type { ToolResult } from '../tools/types.js';
+import { TaskManager, type TaskStatus, type TaskSummary } from './task-manager.js';
+import { WorkerSpawner } from './worker-spawner.js';
+import { type DropReason } from './capabilities.js';
+/** An agent a model can delegate to via `spawn_agent`. */
+export interface AgentDefinition {
+    id: string;
+    description: string;
+    /** Explicit allow-list. Undefined means "inherit every tool the parent has". */
+    allowedTools?: string[];
+    readonly?: boolean;
+    /** Children cannot spawn further agents unless explicitly enabled. */
+    canSpawn?: boolean;
+    /** Per-agent model override. Must be honoured (or surfaced as an error). */
+    model?: string;
+    maxDepth?: number;
+    maxSteps?: number;
+    maxCost?: number;
+    maxTimeMs?: number;
+}
+/** Default agents a model can delegate to. */
+export declare const BUILTIN_AGENTS: readonly AgentDefinition[];
+/** Compact summary returned to the parent — the child's transcript stays separate. */
+export interface ChildSummary {
+    taskId: string;
+    agentName: string;
+    status: TaskStatus;
+    durationMs: number;
+    finalText?: string;
+    changedFiles: string[];
+    usage?: {
+        input: number;
+        output: number;
+        estimated?: boolean;
+    };
+    error?: {
+        code: string;
+        message: string;
+    };
+    /** Tool drops from capability resolution, surfaced for parent visibility. */
+    droppedTools?: {
+        tool: string;
+        reason: DropReason;
+    }[];
+}
+/** Capability context the bridge passes when the parent calls spawn_agent. */
+export interface ParentContextRef {
+    taskId?: string;
+    parentTaskId?: string;
+    sessionId: string;
+    cwd: string;
+    depth: number;
+    maxDepth: number;
+    allowedTools: ReadonlySet<string> | null;
+    model?: string;
+}
+/** Interface exposed to the runtime/tools for a child spawn request. */
+export interface AgentSpawnBridge {
+    parent: ParentContextRef;
+    spawnAgent(input: {
+        agent: string;
+        task: string;
+        cwd?: string;
+        model?: string;
+        timeoutMs?: number;
+    }): Promise<ToolResult<ChildSummary>>;
+    listAgents(): AgentDefinition[];
+    getAgent(id: string): AgentDefinition | undefined;
+    listTasks(filter?: {
+        parentTaskId?: string;
+        status?: TaskStatus;
+    }): TaskSummary[];
+    getTask(id: string): TaskSummary & {
+        error?: {
+            code: string;
+            message: string;
+        };
+    } | undefined;
+}
+/** Constructor options for the orchestrator — the parent runtime's deps. */
+export interface OrchestratorOpts {
+    sessionId: string;
+    deps: RuntimeDeps;
+    taskManager?: TaskManager;
+    workerSpawner?: WorkerSpawner;
+}
+export declare class AgentOrchestrator {
+    readonly sessionId: string;
+    readonly deps: RuntimeDeps;
+    readonly taskManager: TaskManager;
+    readonly workerSpawner: WorkerSpawner;
+    constructor(opts: OrchestratorOpts);
+    listAgents(): AgentDefinition[];
+    getAgent(id: string): AgentDefinition | undefined;
+    /** Build the bridge the parent's runtime hands to tools. */
+    bridgeFor(parent: ParentContextRef): AgentSpawnBridge;
+    /** Compute a child's effective capabilities from the parent's own. */
+    private resolveChild;
+    /**
+     * Spawn a child agent for a given capability context, await its run, and
+     * return a compact summary. Blocks until the child settles (P0 scope;
+     * async task_wait arrives in a later slice).
+     */
+    spawnAgent(input: {
+        agent: string;
+        task: string;
+        cwd?: string;
+        model?: string;
+        timeoutMs?: number;
+    }, parent: ParentContextRef): Promise<ToolResult<ChildSummary>>;
+    private toChildSummary;
+}
+/** Module-scoped holder the orchestrator sets so children inherit the parent's signal. */
+export declare const parentAbortSignalRef: {
+    current: AbortSignal | null;
+};

package/dist/agent/orchestrator.js

@@ -0,0 +1,269 @@
+/**
+ * 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 } 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';
+/** 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_dir', '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_dir', '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_dir', '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_dir', 'glob', 'grep', 'search_files', 'git_status', 'git_diff', 'git_log', 'imports_of', 'importers_of', 'find_symbol'],
+    },
+];
+/** 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;
+    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();
+    }
+    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;
+            },
+        };
+    }
+    /** 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 });
+        return resolved;
+    }
+    /**
+     * Spawn a child agent for a given capability context, await its run, and
+     * return a compact summary. Blocks until the child settles (P0 scope;
+     * async task_wait arrives in a later slice).
+     */
+    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})`,
+                },
+            };
+        }
+        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;
+        const childCwd = input.cwd ?? parent.cwd;
+        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);
+        const childRegistry = new ScopedRegistry(this.deps.registry, resolved.allowed);
+        const childDeps = { ...this.deps, registry: childRegistry };
+        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,
+        };
+        // 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 } : {}),
+        });
+        const handle = this.workerSpawner.spawn(async () => {
+            let result;
+            try {
+                result = await run(childOptions, childDeps);
+            }
+            catch (err) {
+                this.taskManager.finish(record.id, 'failed', {
+                    error: { code: 'CHILD_CRASH', message: err instanceof Error ? err.message : String(err) },
+                });
+                return;
+            }
+            const status = mapResultStatus(result.status);
+            if (status === 'cancelled') {
+                this.taskManager.cancel(record.id, 'parent aborted');
+            }
+            else {
+                this.taskManager.finish(record.id, status, {
+                    summary: [`status: ${status}`, `steps: ${result.steps}`, `toolCalls: ${result.toolCalls}`],
+                    error: status === 'failed'
+                        ? { code: mapFailureCode(result.status), message: result.finalText?.slice(0, 300) ?? 'child failed' }
+                        : undefined,
+                });
+            }
+            const final = this.taskManager.get(record.id);
+            const durationMs = final.finishedAt ? final.finishedAt - final.startedAt : 0;
+            if (status === 'succeeded') {
+                globalBus.emit({
+                    type: 'subtask.completed',
+                    ts: Date.now(),
+                    sessionId: this.sessionId,
+                    taskId: record.id,
+                    status: 'succeeded',
+                    durationMs,
+                    steps: result?.steps ?? 0,
+                    toolCalls: result?.toolCalls ?? 0,
+                });
+            }
+            else {
+                globalBus.emit({
+                    type: 'subtask.failed',
+                    ts: Date.now(),
+                    sessionId: this.sessionId,
+                    taskId: record.id,
+                    status: status,
+                    durationMs,
+                    error: final.error ? { code: final.error.code, message: final.error.message } : undefined,
+                });
+            }
+        }, { label: `agent:${def.id}` });
+        await handle.done.catch(() => undefined);
+        const finalRecord = this.taskManager.get(record.id);
+        if (!finalRecord) {
+            return {
+                ok: false,
+                error: { code: 'INTERNAL', message: `task ${record.id} missing after child run` },
+            };
+        }
+        return { ok: true, value: this.toChildSummary(finalRecord, def, resolved.dropped) };
+    }
+    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

@@ -45,6 +45,8 @@ export type StreamEvent = {
     code: string;
     message: string;
     retryable: boolean;
+    status?: string;
+    retryAfterMs?: number;
 };
 export interface ToolDefinition {
     name: string;
@@ -72,6 +74,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 {

package/dist/agent/provider-adapter.js

@@ -12,6 +12,25 @@
  */
 import { redact } from '../policy/secret-redactor.js';
 const DEFAULT_TIMEOUT_MS = 120_000;
+/**
+ * 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 function parseRetryAfterMs(value) {
+    if (value == null)
+        return undefined;
+    const v = value.trim();
+    if (!v)
+        return undefined;
+    if (/^\d+$/.test(v))
+        return Number(v) * 1000;
+    const t = Date.parse(v);
+    if (!Number.isNaN(t))
+        return Math.max(0, t - Date.now());
+    return undefined;
+}
 /** Convert a Zod schema to a permissive JSON Schema object for tool defs. */
 export function zodToJsonSchema(schema) {
     // We keep this simple: zod's own _def is enough to give the model a
@@ -183,11 +202,15 @@ async function* streamChatCompletions(url, opts, req, fetchImpl) {
         req.signal?.removeEventListener('abort', onAbort);
         const rawErr = await res.text().catch(() => '');
         const errText = redact(rawErr).slice(0, 500);
+        const retryable = res.status >= 500 || res.status === 429;
+        const retryAfterMs = retryable ? parseRetryAfterMs(res.headers?.get('retry-after')) : undefined;
         yield {
             kind: 'error',
             code: `HTTP_${res.status}`,
             message: `provider returned ${res.status}: ${errText}`,
-            retryable: res.status >= 500 || res.status === 429,
+            retryable,
+            status: String(res.status),
+            ...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
         };
         return;
     }
@@ -195,10 +218,41 @@ async function* streamChatCompletions(url, opts, req, fetchImpl) {
     const reader = res.body.getReader();
     const decoder = new TextDecoder();
     let buf = '';
-    // Track per-tool-call id by index.
-    const toolIds = new Map();
-    const toolNames = new Map();
+    const blocks = new Map();
     let pendingUsage;
+    // Canonical contract: exactly one terminal event per stream.
+    let terminalEmitted = false;
+    function* emitTerminal(finishReason, usage) {
+        if (terminalEmitted)
+            return;
+        terminalEmitted = true;
+        for (const b of blocks.values()) {
+            if (b.started && !b.ended && b.id) {
+                b.ended = true;
+                yield { kind: 'tool_call_end', id: b.id };
+            }
+        }
+        // Fragments that never gained an identity are surfaced as incomplete
+        // calls (the runtime turns them into structured errors) — never dropped.
+        let incomplete = 0;
+        for (const b of blocks.values()) {
+            if (!b.started && (b.argsJson || b.id || b.name)) {
+                const id = b.id ?? `incomplete_${incomplete++}`;
+                yield { kind: 'tool_call_start', id, name: b.name ?? 'unknown' };
+                if (b.argsJson)
+                    yield { kind: 'tool_call_delta', id, argsJson: b.argsJson };
+                yield { kind: 'tool_call_end', id };
+                b.started = true;
+                b.ended = true;
+            }
+        }
+        const end = { kind: 'message_end' };
+        if (finishReason)
+            end.finishReason = finishReason;
+        if (usage)
+            end.usage = usage;
+        yield end;
+    }
     try {
         while (true) {
             const { value, done } = await reader.read();
@@ -215,7 +269,7 @@ async function* streamChatCompletions(url, opts, req, fetchImpl) {
                         continue;
                     const data = line.slice(5).trim();
                     if (data === '[DONE]') {
-                        yield { kind: 'message_end' };
+                        yield* emitTerminal(undefined, pendingUsage);
                         return;
                     }
                     let chunk;
@@ -248,17 +302,28 @@ async function* streamChatCompletions(url, opts, req, fetchImpl) {
                             yield { kind: 'thinking_delta', text: thinking };
                         }
                         for (const tc of choice.delta.tool_calls ?? []) {
-                            if (tc.id && tc.function?.name) {
-                                toolIds.set(tc.index, tc.id);
-                                toolNames.set(tc.index, tc.function.name);
-                                yield { kind: 'tool_call_start', id: tc.id, name: tc.function.name };
+                            let b = blocks.get(tc.index);
+                            if (!b) {
+                                b = { argsJson: '', started: false, ended: false };
+                                blocks.set(tc.index, b);
                             }
-                            else if (tc.id) {
-                                toolIds.set(tc.index, tc.id);
+                            if (tc.id)
+                                b.id = tc.id;
+                            if (tc.function?.name)
+                                b.name = tc.function.name;
+                            const newArgs = tc.function?.arguments;
+                            if (newArgs)
+                                b.argsJson += newArgs;
+                            if (b.id && b.name && !b.started) {
+                                // Identity arrived (possibly after earlier fragments). Emit
+                                // start, then flush any accumulated args as one delta.
+                                b.started = true;
+                                yield { kind: 'tool_call_start', id: b.id, name: b.name };
+                                if (b.argsJson)
+                                    yield { kind: 'tool_call_delta', id: b.id, argsJson: b.argsJson };
                             }
-                            if (tc.function?.arguments) {
-                                const id = toolIds.get(tc.index) ?? `call_${tc.index}_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 6)}`;
-                                yield { kind: 'tool_call_delta', id, argsJson: tc.function.arguments };
+                            else if (b.started && b.id && newArgs) {
+                                yield { kind: 'tool_call_delta', id: b.id, argsJson: newArgs };
                             }
                         }
                         if (choice.finish_reason) {
@@ -266,38 +331,19 @@ async function* streamChatCompletions(url, opts, req, fetchImpl) {
                                 ? { input: chunk.usage.prompt_tokens, output: chunk.usage.completion_tokens }
                                 : undefined);
                             pendingUsage = undefined;
-                            // Clear tool tracking per message to avoid stale ids on next turn
-                            const ids = [...toolIds.values()];
-                            toolIds.clear();
-                            toolNames.clear();
-                            for (const id of ids)
-                                yield { kind: 'tool_call_end', id };
-                            yield { kind: 'message_end', finishReason: choice.finish_reason, usage };
+                            yield* emitTerminal(choice.finish_reason, usage);
                         }
                     }
                 }
             }
         }
-        if (toolIds.size) {
-            for (const id of toolIds.values())
-                yield { kind: 'tool_call_end', id };
-            if (pendingUsage) {
-                yield { kind: 'message_end', usage: pendingUsage };
-            }
-            else {
-                yield { kind: 'message_end' };
-            }
-        }
-        else if (pendingUsage) {
-            yield { kind: 'message_end', usage: pendingUsage };
-        }
-        else {
-            yield { kind: 'message_end' };
-        }
+        yield* emitTerminal(undefined, pendingUsage);
     }
     catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        yield { kind: 'error', code: 'STREAM', message: msg, retryable: true };
+        if (!terminalEmitted) {
+            const msg = err instanceof Error ? err.message : String(err);
+            yield { kind: 'error', code: 'STREAM', message: msg, retryable: true };
+        }
     }
     finally {
         clearTimeout(timer);

package/dist/agent/registry.d.ts

@@ -39,4 +39,5 @@ export declare function buildProviderFromCli(args: {
     baseUrl?: string;
     apiKey?: string;
     timeoutMs?: number;
+    retry?: Partial<RetryOptions> | false;
 }): ProviderAdapter;

package/dist/agent/registry.js

@@ -190,5 +190,6 @@ export function buildProviderFromCli(args) {
         baseURL: args.baseUrl,
         apiKey: args.apiKey,
         timeoutMs: args.timeoutMs,
+        ...(args.retry !== undefined ? { retry: args.retry } : {}),
     });
 }

package/dist/agent/retry.d.ts

@@ -28,8 +28,19 @@ export interface RetryOptions {
     sleep?: (ms: number) => Promise<void>;
     /** Test hook: called once per attempt with 0-indexed attempt number. */
     onAttempt?: (attempt: number) => void;
+    /**
+     * Retry telemetry hook (operator-visible; the model stays blind).
+     * Called each time a retryable error is buffered and another attempt
+     * will follow (NOT on the terminal failure). `attempt` is the
+     * 1-indexed retry number (1 = first retry after the initial failure).
+     */
+    onRetry?: (info: {
+        attempt: number;
+        status: string;
+        retryAfterMs?: number;
+    }) => void;
 }
-export declare const DEFAULT_RETRY: Required<Omit<RetryOptions, 'signal' | 'onAttempt'>>;
+export declare const DEFAULT_RETRY: Required<Omit<RetryOptions, 'signal' | 'onAttempt' | 'onRetry'>>;
 /**
  * Sleep that resolves early when `signal` aborts (never rejects — callers
  * check `signal.aborted` themselves after waking).

package/dist/agent/retry.js

@@ -152,7 +152,25 @@ export function retryingAdapter(inner, opts = {}) {
                         yield lastError;
                     return;
                 }
-                const delay = computeBackoff(attempt, cfg.baseMs, cfg.maxMs);
+                // Telemetry for the operator: a retryable error was buffered and
+                // another attempt will follow. The consumer stream never sees the
+                // buffered error, so the model stays blind.
+                const errRec = lastError;
+                const statusRaw = errRec?.['status'];
+                const codeRaw = errRec?.['code'];
+                const status = typeof statusRaw === 'string' && statusRaw.length > 0
+                    ? statusRaw
+                    : typeof codeRaw === 'string' && codeRaw.length > 0
+                        ? codeRaw
+                        : 'retryable';
+                const retryAfterRaw = errRec?.['retryAfterMs'];
+                const retryAfterMs = typeof retryAfterRaw === 'number' && Number.isFinite(retryAfterRaw) && retryAfterRaw >= 0
+                    ? retryAfterRaw
+                    : undefined;
+                opts.onRetry?.({ attempt: attempt + 1, status, ...(retryAfterMs !== undefined ? { retryAfterMs } : {}) });
+                // Honor a server-provided Retry-After delay when present; otherwise
+                // fall back to exponential backoff with jitter.
+                const delay = retryAfterMs ?? computeBackoff(attempt, cfg.baseMs, cfg.maxMs);
                 // Abort-aware backoff: Ctrl+C during the sleep must stop promptly
                 // instead of stalling up to maxMs before noticing.
                 if (delay > 0)