klyro 0.1.62 → 1.0.0

package/dist/agent/runtime.d.ts

@@ -87,6 +87,26 @@ export interface RunOptions {
         store?: import('../persistence/store.js').SessionStore;
         sessionId?: string;
     };
+    /**
+     * Orchestration context (P0). Present for any agent that is itself managed
+     * by an AgentOrchestrator — so a child knows who its parent is, how deep the
+     * call stack is, which tools it may use, and which task/session it belongs to.
+     */
+    parentContext?: {
+        taskId?: string;
+        parentTaskId?: string;
+        sessionId: string;
+        depth: number;
+        maxDepth: number;
+        allowedTools?: ReadonlySet<string>;
+        model?: string;
+    };
+    /**
+     * Delegation bridge (P0). Present on the root run so the model can call
+     * spawn_agent / task_list / task_get. The tool layer reads it from the
+     * ToolContext.
+     */
+    agentBridge?: import('./orchestrator.js').AgentSpawnBridge;
 }
 /** A single plan step emitted by the agent. */
 export interface PlanStep {
@@ -139,6 +159,7 @@ export type RuntimeEvent = {
     kind: 'usage';
     input: number;
     output: number;
+    estimated?: boolean;
 } | {
     kind: 'final_text';
     text: string;
@@ -171,7 +192,7 @@ export type RuntimeEvent = {
     sessionId: string;
 };
 export interface RunResult {
-    status: 'complete' | 'max_steps' | 'aborted' | 'no_final' | 'verify_failed' | 'limit' | 'blocked';
+    status: 'complete' | 'max_steps' | 'aborted' | 'no_final' | 'verify_failed' | 'limit' | 'blocked' | 'stuck';
     steps: number;
     toolCalls: number;
     finalText: string;
@@ -181,6 +202,7 @@ export interface RunResult {
     usage: {
         input: number;
         output: number;
+        estimated?: boolean;
     };
     /** Number of policy-driven user prompts the user accepted. */
     repairs?: number;

package/dist/agent/runtime.js

@@ -16,6 +16,7 @@
  */
 import { text, toolUse, toolResult as mkToolResult } from './message.js';
 import { redact } from '../policy/secret-redactor.js';
+import { patternForCall } from '../policy/patterns.js';
 import { RuntimeTelemetry, emptyTelemetryBlock, summarizeToolCall } from '../context/level7.js';
 import * as path from 'node:path';
 import { verify, diagnosticForModel } from '../verification/engine.js';
@@ -173,6 +174,8 @@ export async function run(opts, deps) {
     // 5.2 — stuck detection state
     const callHistory = [];
     const fileEditCounts = new Map();
+    let stuckTriggers = 0;
+    let stuckAbort = false;
     outer: while (steps < maxSteps) {
         // 5.1 limits: max-cost, max-time
         if (maxCost !== undefined) {
@@ -226,7 +229,7 @@ export async function run(opts, deps) {
                 emitKlyro({ type: 'context.compacted', ts: Date.now(), sessionId: sessionId ?? 'ephemeral', dropped: c.dropped });
         }
         const req = {
-            model: opts.model,
+            model: opts.parentContext?.model ?? opts.model,
             system: reqSystem,
             messages: reqMessages,
             tools: toolDefinitions(deps.registry),
@@ -273,6 +276,17 @@ export async function run(opts, deps) {
                     telemetry.recordUsage(ev.usage.input, ev.usage.output);
                     emit?.({ kind: 'usage', input: usage.input, output: usage.output });
                 }
+                else {
+                    // Providers that omit usage (Ollama, vLLM, proxies): estimate from
+                    // the actual request + generated output so cost accounting never
+                    // silently records zero. Marked estimated for the UI/debugging.
+                    const est = estimateTurnUsage(reqSystem, reqMessages, textBuf, pendingToolCalls);
+                    usage.input += est.input;
+                    usage.output += est.output;
+                    usage.estimated = true;
+                    telemetry.recordUsage(est.input, est.output);
+                    emit?.({ kind: 'usage', input: usage.input, output: usage.output, estimated: true });
+                }
             }
             else if (ev.kind === 'error') {
                 telemetry.recordError(`stream_error: ${ev.code}`);
@@ -296,22 +310,47 @@ export async function run(opts, deps) {
                 };
             }
         }
-        // Build the assistant message.
+        // Build the assistant message. Tool calls are finalized here: JSON is
+        // parsed and schema-validated BEFORE policy/execution. Malformed calls
+        // become structured MALFORMED_TOOL_CALL results — garbage arguments must
+        // never reach a real tool.
         const assistantContent = [];
         if (textBuf)
             assistantContent.push(text(textBuf));
         const finalizedCalls = [];
+        let hadInvalidTool = false;
         for (const tc of pendingToolCalls.values()) {
-            let input = {};
-            try {
-                input = JSON.parse(tc.argsJson || '{}');
-            }
-            catch {
-                input = { _parse_error: true, raw: tc.argsJson };
+            const validated = validateFinalizedCall(deps.registry, tc.id, tc.name, tc.argsJson);
+            if (!validated.ok) {
+                hadInvalidTool = true;
+                // Record the model's tool_use (empty input — safe to replay to any
+                // provider) and answer it immediately with a structured error.
+                assistantContent.push(toolUse(tc.id, tc.name, {}));
+                emit?.({ kind: 'tool_call_end', id: tc.id, name: tc.name, input: {} });
+                const errMsg = {
+                    role: 'tool',
+                    content: [mkToolResult(tc.id, tc.name, validated.output, true)],
+                };
+                transcript.push(errMsg);
+                await checkpoint(errMsg, {
+                    toolCallId: tc.id, toolName: tc.name,
+                    input: { raw: redact(tc.argsJson).slice(0, 500) }, output: validated.output, isError: true,
+                });
+                let attempted = {};
+                try {
+                    attempted = JSON.parse(tc.argsJson);
+                }
+                catch {
+                    attempted = {};
+                }
+                telemetry.recordToolError(toolUse(tc.id, tc.name, attempted), validated.code);
+                emitKlyro({ type: 'tool.result', ts: Date.now(), sessionId: sessionId ?? 'ephemeral', callId: tc.id, name: tc.name, output: validated.output, isError: true, latencyMs: 0 });
+                emit?.({ kind: 'tool_result', id: tc.id, name: tc.name, output: validated.output, isError: true, latencyMs: 0 });
+                continue;
             }
-            finalizedCalls.push(toolUse(tc.id, tc.name, input));
-            assistantContent.push(toolUse(tc.id, tc.name, input));
-            emit?.({ kind: 'tool_call_end', id: tc.id, name: tc.name, input });
+            finalizedCalls.push(toolUse(tc.id, tc.name, validated.input));
+            assistantContent.push(toolUse(tc.id, tc.name, validated.input));
+            emit?.({ kind: 'tool_call_end', id: tc.id, name: tc.name, input: validated.input });
         }
         const assistantMsg = { role: 'assistant', content: assistantContent };
         transcript.push(assistantMsg);
@@ -332,6 +371,14 @@ export async function run(opts, deps) {
             return { status: 'aborted', steps, toolCalls: toolCallCount, finalText, transcript, hasEdits, usage, repairs, verification: hasEdits ? { ok: false, attempts: verificationAttempts } : undefined };
         }
         if (finalizedCalls.length === 0) {
+            if (hadInvalidTool) {
+                // The model attempted a tool call that failed validation; the error is
+                // already a tool_result in the transcript — loop so the model can
+                // repair next turn instead of treating an answerable error as a
+                // completion. Bounded by maxSteps and stuck detection (P0-3).
+                emit?.({ kind: 'step_end', step: steps });
+                continue;
+            }
             finalText = textBuf;
             // Level 8 — Verification + Autonomous Repair (gated on hasEdits below — pure analysis skips verify)
             const verifyEnabled = opts.verify?.enabled !== false;
@@ -526,10 +573,21 @@ export async function run(opts, deps) {
             signal: opts.signal,
             nonInteractive: opts.nonInteractive,
             sessionId,
+            ...(opts.agentBridge ? { agentBridge: opts.agentBridge } : {}),
+            ...(opts.parentContext?.taskId
+                ? { parentTaskId: opts.parentContext.parentTaskId ?? opts.parentContext.taskId }
+                : {}),
+            agentDepth: opts.parentContext?.depth ?? 0,
+            agentMaxDepth: opts.parentContext?.maxDepth ?? 1,
+            ...(opts.parentContext?.allowedTools ? { agentAllowedTools: opts.parentContext.allowedTools } : {}),
+            ...(opts.parentContext?.model ?? opts.model ? { agentModel: opts.parentContext?.model ?? opts.model } : {}),
         };
         const allSafe = finalizedCalls.length > 1 && finalizedCalls.every((c) => deps.registry.get(c.name)?.isConcurrencySafe !== false);
-        const runOne = async (call) => {
-            // Use per-call handling without continue (runOne is not a loop)
+        // Gate phase: policy decision + approval prompt for one call. Runs
+        // sequentially (approval UI is one-modal-at-a-time). Commits deny/user-deny
+        // results immediately — gate runs in call order so these stay ordered.
+        // Returns true when the call is approved for execution.
+        const gateCall = async (call) => {
             const decision = await deps.policy.evaluate({ name: call.name, input: call.input }, { cwd: opts.cwd, nonInteractive: opts.nonInteractive });
             emit?.({ kind: 'policy_decision', id: call.id, name: call.name, action: decision.action, ...(decision.action !== 'allow' ? { reason: decision.reason } : {}) });
             // Mirror to KlyroEvent bus
@@ -546,7 +604,7 @@ export async function run(opts, deps) {
                 emitKlyro({ type: 'tool.result', ts: Date.now(), sessionId: sessionId ?? 'ephemeral', callId: call.id, name: call.name, output: { error: 'POLICY_DENIED' }, isError: true, latencyMs: 0 });
                 telemetry.recordToolError(call, 'policy_denied');
                 emit?.({ kind: 'tool_result', id: call.id, name: call.name, output: { error: 'POLICY_DENIED', reason: decision.reason }, isError: true, latencyMs: 0 });
-                return;
+                return false;
             }
             if (decision.action === 'ask') {
                 emitKlyro({ type: 'permission.ask', ts: Date.now(), sessionId: sessionId ?? 'ephemeral', callId: call.id, name: call.name, reason: decision.reason });
@@ -554,6 +612,8 @@ export async function run(opts, deps) {
                     toolName: call.name,
                     reason: decision.reason,
                     summary: summarizeToolCall(call),
+                    input: call.input,
+                    pattern: patternForCall(call.name, call.input),
                 });
                 // Approval UI in TUI handles y/a/A/n/e/? — e edits input, ? explains
                 if (choice === 'deny') {
@@ -567,15 +627,49 @@ export async function run(opts, deps) {
                     await checkpoint(denyMsg2, { toolCallId: call.id, toolName: call.name, input: call.input, output: { error: 'POLICY_DENIED', reason: 'user denied' }, isError: true });
                     telemetry.recordToolError(call, 'user_denied');
                     emit?.({ kind: 'tool_result', id: call.id, name: call.name, output: { error: 'POLICY_DENIED', reason: 'user denied' }, isError: true, latencyMs: 0 });
-                    return;
+                    return false;
                 }
                 // Handle 'edit' choice: for now treat as allow with edited input (future: re-prompt)
                 repairs++;
             }
+            return true;
+        };
+        // Execute phase: run the tool with no transcript writes, so concurrent
+        // executions can't interleave. A throw here becomes a tool error (an
+        // executor crash must never kill the step).
+        const execTool = async (call) => {
             const t0 = Date.now();
             emitKlyro({ type: 'tool.call', ts: Date.now(), sessionId: sessionId ?? 'ephemeral', callId: call.id, name: call.name, input: call.input });
-            const obs = await deps.registry.execute(call.name, call.input, toolCtx);
+            let obs;
+            try {
+                obs = await deps.registry.execute(call.name, call.input, toolCtx);
+            }
+            catch (err) {
+                obs = { ok: false, error: { code: 'EXEC_CRASH', message: err instanceof Error ? err.message : String(err) } };
+            }
             const latencyMs = Date.now() - t0;
+            return { obs, latencyMs };
+        };
+        // 5.2 stuck termination (P0-3): the FIRST detection injects one
+        // "change approach" synthetic message for the next model turn; the SECOND
+        // detection aborts the automated loop with a `stuck` status so a repeated
+        // tool loop never burns unbounded tokens. Covers both signals: identical
+        // call ×3 and same-file edited >8×.
+        const markStuck = async (msg) => {
+            stuckTriggers++;
+            emitKlyro({ type: 'error', ts: Date.now(), sessionId: sessionId ?? 'ephemeral', code: 'stuck', message: msg });
+            if (stuckTriggers === 1) {
+                const note = { role: 'user', content: [text(`[system note] Stuck detected: ${msg}. Stop repeating the same action; change approach.`)] };
+                transcript.push(note);
+                await checkpoint(note);
+            }
+            else {
+                stuckAbort = true;
+            }
+        };
+        // Commit phase: fold one execution result into the transcript, in original
+        // call order. The only writer — call sequentially, never concurrently.
+        const commitResult = async (call, obs, latencyMs) => {
             const output = obs.ok ? redactOutput(obs.value) : redactOutput({ error: obs.error });
             const toolMsg = {
                 role: 'tool',
@@ -620,7 +714,7 @@ export async function run(opts, deps) {
                     const cnt = (fileEditCounts.get(fileChanged.path) ?? 0) + 1;
                     fileEditCounts.set(fileChanged.path, cnt);
                     if (cnt > 8) {
-                        emitKlyro({ type: 'error', ts: Date.now(), sessionId: sessionId ?? 'ephemeral', code: 'stuck', message: `same file edited >8×: ${fileChanged.path}` });
+                        await markStuck(`same file edited >8×: ${fileChanged.path}`);
                     }
                 }
             }
@@ -631,23 +725,42 @@ export async function run(opts, deps) {
                 callHistory.shift();
             const last3 = callHistory.slice(-3);
             if (last3.length === 3 && last3[0] === last3[1] && last3[1] === last3[2]) {
-                emitKlyro({ type: 'error', ts: Date.now(), sessionId: sessionId ?? 'ephemeral', code: 'stuck', message: `identical call ×3: ${sig}` });
-                // Inject system note for next turn
-                const note = { role: 'user', content: [text(`[system note] Stuck detected: identical call ×3: ${sig}. Try a different approach.`)] };
-                transcript.push(note);
-                await checkpoint(note);
+                await markStuck(`identical call ×3: ${sig}`);
             }
         };
-        // 3.5 — parallel if all concurrencySafe, sequential otherwise
-        // BUG-002: preserve call order — run sequentially even when allSafe to avoid out-of-order transcript
-        // Parallel execution previously pushed tool_results out of order via Promise.all
+        // Sequential path: gate → execute → commit per call, in order.
+        const runOne = async (call) => {
+            if (!(await gateCall(call)))
+                return;
+            const { obs, latencyMs } = await execTool(call);
+            await commitResult(call, obs, latencyMs);
+        };
+        // 3.5 — parallel when every call is concurrencySafe, sequential otherwise.
+        // Gate runs sequentially in both paths (approval UI is one-at-a-time).
+        // Parallel path executes concurrently but commits in original call order,
+        // so the transcript reads exactly as if the calls ran in order (this is
+        // what the old BUG-002 sequential fallback was protecting).
         if (allSafe) {
+            const approved = [];
             for (const call of finalizedCalls) {
                 toolCallCount++;
-                await runOne(call);
+                if (await gateCall(call))
+                    approved.push(call);
                 if (opts.signal?.aborted)
                     break;
             }
+            if (approved.length > 0 && !opts.signal?.aborted) {
+                const settled = await Promise.allSettled(approved.map((c) => execTool(c)));
+                for (let i = 0; i < approved.length; i++) {
+                    const s = settled[i];
+                    if (s.status === 'fulfilled') {
+                        await commitResult(approved[i], s.value.obs, s.value.latencyMs);
+                    }
+                    else {
+                        await commitResult(approved[i], { ok: false, error: { code: 'EXEC_CRASH', message: String(s.reason) } }, 0);
+                    }
+                }
+            }
         }
         else {
             for (const call of finalizedCalls) {
@@ -666,6 +779,9 @@ export async function run(opts, deps) {
             }
             catch { /* ignore */ }
         }
+        // 5.2 — terminate the automated loop once stuck recurs after the note
+        if (stuckAbort)
+            break;
     }
     if (opts.signal?.aborted) {
         emit?.({ kind: 'aborted' });
@@ -678,6 +794,18 @@ export async function run(opts, deps) {
         await closeTracer();
         return { status: 'aborted', steps, toolCalls: toolCallCount, finalText, transcript, hasEdits, usage, repairs, verification: hasEdits ? { ok: false, attempts: verificationAttempts } : undefined };
     }
+    // 5.2 — stuck termination (P0-3): bounded stop instead of unbounded token burn.
+    if (stuckAbort) {
+        emit?.({ kind: 'final_text', text: finalText });
+        if (store && sessionId) {
+            try {
+                await store.setStatus(sessionId, 'stuck', finalText);
+            }
+            catch { /* ignore */ }
+        }
+        await closeTracer();
+        return { status: 'stuck', steps, toolCalls: toolCallCount, finalText, transcript, hasEdits, usage, repairs, verification: hasEdits ? { ok: false, attempts: verificationAttempts } : undefined };
+    }
     emit?.({ kind: 'final_text', text: finalText });
     if (store && sessionId) {
         try {
@@ -688,6 +816,88 @@ export async function run(opts, deps) {
     await closeTracer();
     return { status: 'max_steps', steps, toolCalls: toolCallCount, finalText, transcript, hasEdits, usage, repairs, verification: hasEdits ? { ok: false, attempts: verificationAttempts } : undefined };
 }
+/**
+ * Estimate usage for a turn whose provider omitted it (Ollama, vLLM,
+ * proxies). Input is measured from the actual request via the tokenizer;
+ * output is a chars/4 heuristic over generated text + tool arguments.
+ */
+function estimateTurnUsage(system, messages, textOut, toolCalls) {
+    let argsChars = 0;
+    for (const tc of toolCalls.values())
+        argsChars += tc.argsJson.length;
+    return {
+        input: totalTokens(system, messages),
+        output: Math.max(1, Math.ceil((textOut.length + argsChars) / 4)),
+    };
+}
+/**
+ * Validate one assembled tool call before it reaches policy or execution.
+ * Returns the parsed+schema-validated input, or a structured error output
+ * (MALFORMED_TOOL_CALL / UNKNOWN_TOOL) that the runtime records as a tool
+ * result without executing anything.
+ */
+function validateFinalizedCall(registry, id, name, argsJson) {
+    void id;
+    let parsed = {};
+    if (argsJson.trim()) {
+        try {
+            parsed = JSON.parse(argsJson);
+        }
+        catch {
+            return {
+                ok: false,
+                code: 'MALFORMED_TOOL_CALL',
+                output: {
+                    code: 'MALFORMED_TOOL_CALL',
+                    tool: name,
+                    message: 'Tool arguments were incomplete or invalid JSON. Re-issue the call with complete arguments.',
+                    retryable: true,
+                },
+            };
+        }
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return {
+            ok: false,
+            code: 'MALFORMED_TOOL_CALL',
+            output: {
+                code: 'MALFORMED_TOOL_CALL',
+                tool: name,
+                message: 'Tool arguments must be a JSON object. Re-issue the call with complete arguments.',
+                retryable: true,
+            },
+        };
+    }
+    const tool = registry.get(name);
+    if (!tool) {
+        return {
+            ok: false,
+            code: 'UNKNOWN_TOOL',
+            output: {
+                code: 'MALFORMED_TOOL_CALL',
+                tool: name,
+                message: `Unknown tool "${name}". Use one of the available tools.`,
+                retryable: true,
+            },
+        };
+    }
+    const checked = tool.inputSchema.safeParse(parsed);
+    if (!checked.success) {
+        const first = checked.error.issues[0];
+        const detail = first ? ` (${first.path.join('.') || 'input'}: ${first.message})` : '';
+        return {
+            ok: false,
+            code: 'MALFORMED_TOOL_CALL',
+            output: {
+                code: 'MALFORMED_TOOL_CALL',
+                tool: name,
+                message: `Tool arguments failed validation${detail}. Re-issue the call with correct arguments.`,
+                retryable: true,
+            },
+        };
+    }
+    return { ok: true, input: parsed };
+}
 function redactOutput(v) {
     if (typeof v === 'string')
         return redact(v);

package/dist/agent/scoped-registry.d.ts

@@ -0,0 +1,22 @@
+/**
+ * ScopedRegistry — a `ToolRegistry` that narrows the surface to a resolved
+ * capability set.
+ *
+ * Both surfaces the runtime relies on (`toolDefinitions(deps.registry)`
+ * and `deps.registry.execute(...)`) go through `list()` / `execute()`, so
+ * wrapping the child's registry in this class enforces the tool allow-set
+ * end-to-end without touching the runtime loop: the model only sees the
+ * allowed tools, and any call to a disallowed tool returns `UNKNOWN_TOOL`.
+ */
+import type { Tool, ToolContext, ToolResult } from '../tools/types.js';
+import { ToolRegistry } from '../tools/registry.js';
+export declare class ScopedRegistry extends ToolRegistry {
+    private readonly parent;
+    private readonly allowed;
+    constructor(parent: ToolRegistry, allowed: ReadonlySet<string>);
+    get(name: string): Tool<unknown, unknown> | undefined;
+    list(): Tool<unknown, unknown>[];
+    /** Which tools this scope permits, by name (for diagnostics/tests). */
+    names(): string[];
+    execute(name: string, rawInput: unknown, ctx: ToolContext): Promise<ToolResult<unknown>>;
+}

package/dist/agent/scoped-registry.js

@@ -0,0 +1,42 @@
+/**
+ * ScopedRegistry — a `ToolRegistry` that narrows the surface to a resolved
+ * capability set.
+ *
+ * Both surfaces the runtime relies on (`toolDefinitions(deps.registry)`
+ * and `deps.registry.execute(...)`) go through `list()` / `execute()`, so
+ * wrapping the child's registry in this class enforces the tool allow-set
+ * end-to-end without touching the runtime loop: the model only sees the
+ * allowed tools, and any call to a disallowed tool returns `UNKNOWN_TOOL`.
+ */
+import { ToolRegistry } from '../tools/registry.js';
+export class ScopedRegistry extends ToolRegistry {
+    parent;
+    allowed;
+    constructor(parent, allowed) {
+        super();
+        this.parent = parent;
+        this.allowed = allowed;
+    }
+    get(name) {
+        return this.allowed.has(name) ? this.parent.get(name) : undefined;
+    }
+    list() {
+        return this.parent.list().filter((t) => this.allowed.has(t.name));
+    }
+    /** Which tools this scope permits, by name (for diagnostics/tests). */
+    names() {
+        return [...this.allowed].sort();
+    }
+    async execute(name, rawInput, ctx) {
+        if (!this.allowed.has(name)) {
+            return {
+                ok: false,
+                error: {
+                    code: 'UNKNOWN_TOOL',
+                    message: `Tool not available in this agent context: ${name}`,
+                },
+            };
+        }
+        return this.parent.execute(name, rawInput, ctx);
+    }
+}

package/dist/agent/task-manager.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Task manager — tracks the lifecycle of a (possibly nested) agent run.
+ *
+ * Each `spawn_agent` call creates a `TaskRecord` in a `TaskManager`.
+ * The manager owns an `AbortController` per task so that the parent (or
+ * the user) can cancel a running child without tearing down the entire
+ * process. It enforces a recursion / depth cap and emits `subtask.*`
+ * events so the event bus and trace writer can see the task tree.
+ *
+ * Exactly one task manager exists per session, wired into the orchestrator
+ * (src/agent/orchestrator.ts), which the runtime reaches via
+ * `parentContext`.
+ */
+import { type EventBus } from '../events/bus.js';
+export type TaskStatus = 'queued' | 'running' | 'succeeded' | 'failed' | 'cancelled' | 'timed_out' | 'blocked';
+export interface TaskError {
+    code: string;
+    message: string;
+    details?: unknown;
+}
+/**
+ * The full runtime record for one task. `summary` is a free-form progress
+ * log; `done` resolves to this very record once the task reaches a terminal
+ * status, so `await rec.done` yields the record with its final status.
+ */
+export interface TaskRecord {
+    id: string;
+    parentTaskId?: string;
+    sessionId: string;
+    agentName: string;
+    status: TaskStatus;
+    cwd: string;
+    depth: number;
+    maxDepth: number;
+    model?: string;
+    startedAt: number;
+    finishedAt?: number;
+    summary: string[];
+    error?: TaskError;
+    abortController: AbortController;
+    done: Promise<TaskRecord>;
+    /** Internal — resolves `done`. Do not call outside TaskManager. */
+    _resolveDone: (r: TaskRecord) => void;
+    /** Internal cleanup handles, not part of the stable contract. */
+    _cleanupParentAbort?: () => void;
+    timeoutHandle?: NodeJS.Timeout;
+}
+/** Serialisable, stable subset of a task for logs, tools, and the trace. */
+export interface TaskSummary {
+    id: string;
+    parentTaskId?: string;
+    agentName: string;
+    sessionId: string;
+    status: TaskStatus;
+    cwd: string;
+    depth: number;
+    model?: string;
+    durationMs?: number;
+}
+export interface CreateTaskOpts {
+    agentName: string;
+    cwd: string;
+    depth: number;
+    maxDepth: number;
+    parentTaskId?: string;
+    model?: string;
+    timeoutMs?: number;
+    /** Abort this task when the given signal fires. */
+    abortOnParent?: AbortSignal;
+    /** Defaults to true. When false, the task starts in 'queued'. */
+    autoStart?: boolean;
+}
+export declare class TaskManager {
+    private readonly tasks;
+    private readonly watchers;
+    private counter;
+    private readonly sessionId;
+    private readonly bus;
+    constructor(opts: {
+        sessionId: string;
+        bus?: EventBus;
+    });
+    /** Create a task. Blocks instead of running when the recursion cap is exceeded. */
+    create(opts: CreateTaskOpts): TaskRecord;
+    /** Look up a live record. */
+    get(id: string): TaskRecord | undefined;
+    /** List tasks, optionally filtered by parent and/or status. Returns summaries. */
+    list(filter?: {
+        parentTaskId?: string;
+        status?: TaskStatus;
+    }): TaskSummary[];
+    /** Transition a task to a terminal status and resolve its `done`. */
+    finish(id: string, status: 'succeeded' | 'failed' | 'cancelled' | 'timed_out' | 'blocked', patch?: {
+        summary?: string[];
+        error?: TaskError;
+    }): TaskRecord;
+    /** Cancel a live task: abort, mark cancelled/timed_out, resolve done. */
+    cancel(id: string, reason?: string, finalStatus?: 'cancelled' | 'timed_out'): TaskRecord;
+    /** Confirm a task that policy/depth prevented from running. */
+    block(id: string, reason: string): TaskRecord;
+    /** Cancel `id` and every transitive descendant. */
+    cancelTree(id: string, reason?: string): Promise<void>;
+    /** Subscribe to status transitions for one task. Delivers the current status immediately. */
+    subscribe(id: string, listener: (r: TaskRecord) => void): () => void;
+    /** Cancel every live task (used on shutdown / ctrl-c). */
+    shutdown(): Promise<void>;
+    /** Compact serialisable summary. */
+    toSummary(r: TaskRecord): TaskSummary;
+    /** Resolve a record's `done` (idempotent). */
+    private resolve;
+    private _resolveOnce;
+    /** Deliver a transition to the task's own watchers, then each ancestor's. */
+    private emit;
+    private notify;
+}