klyro 0.1.63 → 1.0.0

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;
     }

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)

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 {

package/dist/agent/runtime.js

@@ -229,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),
@@ -573,6 +573,14 @@ 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);
         // Gate phase: policy decision + approval prompt for one call. Runs

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;
+}