@tangle-network/agent-runtime 0.71.1 → 0.73.0

package/dist/coordination-BPQmuwv8.d.ts

@@ -1,666 +0,0 @@
-import { c as DelegateFeedbackArgs, d as DelegationFeedbackSnapshot, L as LocalHarness, E as ExecutorFactory, e as ExecutorRegistry, f as DeliverableSpec, S as Spend, g as DelegationTaskQueue, h as CoderDelegate, R as ResearcherDelegate, U as UiAuditorDelegate, T as TraceContext, A as Agent, i as Scope, j as ResultBlobStore, B as Budget } from './delegates-CsXJPZDH.js';
-import { T as ToolSpec, R as RouterConfig } from './router-client-C7kp_ECN.js';
-import { BackendType } from '@tangle-network/sandbox';
-import { S as SandboxClient, E as ExecCtx } from './types-CdnEAE3U.js';
-
-/**
- * @experimental
- *
- * The child→parent message bus: the ONE pipe carrying every message a worker, sub-driver, or
- * analyst sends up to the driver — settled outputs, questions, and trace-analyst findings. It
- * unifies channels that were ad-hoc before (the settled-worker cursor, the ask-parent question
- * channel, and analyst results) into a single typed primitive with two lanes:
- *
- *   - PASS-THROUGH (`subscribe`): every published event reaches subscribers immediately — the
- *     express lane for online steering and live observation (a UI, a hook, the parent's box).
- *   - STANDBY (`pull`): events also queue so the driver consumes them on its own cadence. The queue
- *     is PRIORITY-ordered: a higher-`priority` event (a blocking question) is bumped ahead of
- *     queued settles/findings so the driver sees it first; ties resolve FIFO by publish order.
- *
- * Observability is first-class (A++): every event is stamped with a monotonic `seq` and wall-clock
- * `at`, the full ordered `history()` is retained as an audit/replay trail, and `stats()` exposes
- * published/pulled counts by kind. Subscribers receive the stamped record, not a bare event.
- *
- * The interface is transport-agnostic on purpose. Same box → this in-process queue. Cross box →
- * the SAME publish/pull/subscribe surface backed by a durable mailbox on the parent's box (children
- * POST events with at-least-once retry; payloads are blob refs so the event stays small). Consumers
- * depend only on this interface, so distribution is a transport swap, never an architecture change.
- */
-/** Every bus event is a discriminated union member keyed by `type`. */
-interface BusEvent {
-    readonly type: string;
-}
-/** A published event stamped for ordering and observability. `seq` is the monotonic publish index;
- *  `priority` drives pull order (higher = bumped ahead); `at` is the wall-clock publish time (ms). */
-interface BusRecord<E extends BusEvent> {
-    readonly seq: number;
-    readonly at: number;
-    readonly priority: number;
-    readonly event: E;
-}
-interface PublishOptions {
-    /** Higher = pulled ahead of lower-priority queued events (default 0). A blocking question sets
-     *  this so it bumps to the front of the driver's inbox. */
-    readonly priority?: number;
-    /** Whether the event enters the pull queue (default true). Set `false` for record-only events —
-     *  the parent→child down-leg (steer / answer / resume): they belong in `history()` and reach
-     *  `subscribe` observers, but the parent must never `pull` its own outbound message back. */
-    readonly queue?: boolean;
-}
-interface BusStats {
-    readonly published: number;
-    readonly pulled: number;
-    /** Count published per event `type`. */
-    readonly byKind: Readonly<Record<string, number>>;
-}
-interface EventBus<E extends BusEvent> {
-    /** Stamp + queue the event, then deliver the stamped record to every subscriber in order.
-     *  Returns the stamped record. */
-    publish(event: E, opts?: PublishOptions): Promise<BusRecord<E>>;
-    /** Remove and return the highest-priority QUEUED event whose type is in `kinds` (any if omitted),
-     *  ties broken FIFO by `seq`; `undefined` when nothing matches. */
-    pull(kinds?: ReadonlyArray<E['type']>): E | undefined;
-    /** Register a pass-through handler; it receives the stamped record of every event published after
-     *  registration. Returns an unsubscribe fn. */
-    subscribe(handler: (record: BusRecord<E>) => void | Promise<void>): () => void;
-    /** Count of queued, not-yet-pulled events (filtered by `kinds` when given). */
-    pending(kinds?: ReadonlyArray<E['type']>): number;
-    /** The full ordered log of every event ever published (the audit/replay trail). */
-    history(): ReadonlyArray<BusRecord<E>>;
-    /** Throughput counters for observability dashboards. */
-    stats(): BusStats;
-}
-declare function createEventBus<E extends BusEvent>(now?: () => number): EventBus<E>;
-
-/**
- * @experimental
- *
- * Feedback persistence surface for the MCP layer.
- *
- * The substrate cannot import `@tangle-network/agent-knowledge` (it would
- * induce a dependency cycle), so the store is an abstract interface. The
- * default implementation is in-memory; consumers wire their own adapter
- * (a real KbStore-backed sink, an HTTP relay to gtm-agent's knowledge
- * service, etc.) via `createMcpServer({ feedbackStore })`.
- *
- * Feedback events are append-only: every rating is a new event with a
- * fresh id, even when the same delegation is rated multiple times. The
- * caller decides how to roll up scores downstream.
- */
-
-/** @experimental */
-interface FeedbackEvent {
-    id: string;
-    refersTo: DelegateFeedbackArgs['refersTo'];
-    rating: DelegateFeedbackArgs['rating'];
-    by: DelegateFeedbackArgs['by'];
-    capturedAt: string;
-    namespace?: string;
-}
-/** @experimental */
-interface FeedbackStore {
-    /** Append a new event. Never dedupes — every rating is its own event. */
-    put(event: FeedbackEvent): Promise<void>;
-    /**
-     * List events filtered by `namespace`. When `namespace` is omitted, list
-     * across all namespaces. Returns events in insertion order.
-     */
-    list(filter?: {
-        namespace?: string;
-        refersToRef?: string;
-    }): Promise<FeedbackEvent[]>;
-}
-/** @experimental */
-declare class InMemoryFeedbackStore implements FeedbackStore {
-    private readonly events;
-    put(event: FeedbackEvent): Promise<void>;
-    list(filter?: {
-        namespace?: string;
-        refersToRef?: string;
-    }): Promise<FeedbackEvent[]>;
-}
-/**
- * Project a `FeedbackEvent` down to the snapshot shape carried on
- * `delegation_history` entries.
- *
- * @experimental
- */
-declare function eventToSnapshot(event: FeedbackEvent): DelegationFeedbackSnapshot;
-
-/**
- * @experimental
- *
- * The leaf runtime — the built-in `Executor` IMPLEMENTATIONS behind the ONE
- * open interface frozen in `./types`, plus the open resolver/registry that maps
- * an `AgentSpec` to one of them OR accepts a bring-your-own executor verbatim.
- *
- * The interface is the extension point, not a closed `inline|sandbox|cli` union:
- *   - router/inline : a direct OpenAI-compatible Router call, no box (one-shot).
- *   - sandbox       : COMPOSES the existing `runLoop` kernel as a single-task
- *                     leaf and surfaces its token/cost usage as `UsageEvent`s;
- *                     forwards PR #150's optional `lineage` passthrough WITHOUT
- *                     reinventing checkpoint/fork (streaming).
- *   - cli           : a Halo/RLM subprocess; `budgetExempt` (no token accounting),
- *                     excluded from the equal-k arms by construction (streaming).
- * Every metered runtime reports through the SAME normalized `UsageEvent` channel
- * so the conserved budget pool meters them identically. A user's own agent is
- * first-class the moment it implements `Executor` — register it by name or
- * pass it as `AgentSpec.executor`.
- *
- * Layering: `estimateCost`/`isModelPriced` are substrate primitives from
- * `@tangle-network/agent-eval`; `runLoop`/`acquireSandbox` are runtime kernels
- * from this package. No per-vendor adapters live here.
- */
-
-/**
- * Router/inline connection seam. A direct OpenAI-compatible Router endpoint —
- * the cheapest leaf, no box, no tools. `model` overrides the profile's model
- * hint when present; otherwise the profile's `model.default` is required.
- */
-interface RouterSeam {
-    routerBaseUrl: string;
-    routerKey: string;
-    model?: string;
-}
-/**
- * Sandbox executor seam. The `sandboxClient` the composed `runLoop` creates
- * boxes through, plus the optional trace/run/lineage wiring forwarded into the
- * loop. `lineage` is opaque here (PR #150's `RunLoopOptions.lineage`): forwarded
- * forward-compatibly, never inspected — this executor does NOT reinvent
- * checkpoint/fork.
- */
-interface SandboxSeam {
-    sandboxClient: SandboxClient;
-    /** Forwarded into the composed `runLoop`'s `ctx` (trace emitter, run handle, etc.). */
-    loopCtx?: Partial<Omit<ExecCtx, 'sandboxClient' | 'signal'>>;
-    /** PR #150 `RunLoopOptions.lineage` passthrough — opaque; forwarded, not parsed. */
-    lineage?: unknown;
-    /** Hard cap on the composed loop's iterations. The budget pool reserves against
-     *  the spawn `Budget.maxIterations`; this is the leaf's own ceiling. Default 1. */
-    maxIterations?: number;
-}
-/** CLI subprocess seam. `bin` + `args` describe the Halo/RLM process to spawn. */
-interface CliSeam {
-    bin: string;
-    args?: string[];
-    /** Extra environment for the subprocess (merged over `process.env`). */
-    env?: Record<string, string>;
-    /** Working directory for the subprocess. */
-    cwd?: string;
-}
-/**
- * cli-worktree seam. A supervisor-authored `AgentProfile` driving a local coding-harness CLI
- * (claude / codex / opencode) on its own git worktree — the leaf `createWorktreeCliExecutor`
- * named as data. `harness` + `repoRoot` + `taskPrompt` are required; the authored
- * `profile.prompt.systemPrompt` + `profile.model.default` reach the harness via the §1.5
- * `harnessInvocation` mapper. Everything else mirrors `WorktreeCliExecutorOptions`.
- */
-interface CliWorktreeSeam {
-    repoRoot: string;
-    harness: LocalHarness;
-    taskPrompt: string;
-    runId?: string;
-    baseRef?: string;
-    harnessTimeoutMs?: number;
-}
-/**
- * cli-bridge seam. A local OpenAI-compatible bridge that fronts harness CLIs
- * (claude-code / opencode / kimi / pi) behind one HTTP surface; `model` doubles
- * as the harness selector (e.g. `claude-code/sonnet`, `opencode/<provider>/<model>`).
- * `agentProfile` is the bridge-dialect profile (metadata.disallowedTools, mcp)
- * forwarded verbatim per request — how an arm disables native tools or injects
- * a provider search MCP.
- *
- * The executor opens a RESUMABLE cli-bridge session — structurally identical to the
- * sandbox executor's persistent box, just local. `sessionId` is the stable
- * caller-owned id cli-bridge maps to the harness's internal conversation id; a
- * follow-up steer/resume on the SAME id continues the SAME harness session (opencode
- * `-s`, claude `--resume`, …). Omit it and the executor mints a stable one per spawn.
- */
-interface BridgeSeam {
-    bridgeUrl: string;
-    bridgeBearer: string;
-    model: string;
-    agentProfile?: Record<string, unknown>;
-    timeoutMs?: number;
-    /** Stable, caller-owned cli-bridge session id for harness-side resume. Defaults
-     *  to a freshly minted per-spawn id so each worker is its own resumable session. */
-    sessionId?: string;
-    /** Per-resume-turn inference cap before the worker settles on its last output.
-     *  Mirrors `routerToolsInlineExecutor.maxTurns`; default 200 (runaway backstop). */
-    maxTurns?: number;
-}
-/**
- * Router seam WITH tool use — the tool-using router backend. Same direct
- * OpenAI-compatible endpoint as `RouterSeam`, but each turn passes `tools`; when
- * the model emits tool_calls they run via `executeToolCall` ON THIS HOST and the
- * results fold back as `tool` messages, repeating until the model answers without
- * a tool or `maxTurns` is hit. A real agentic loop, OFF-BOX — no sandbox, so it
- * is unaffected by a box's egress allowlist. One turn = one completion = the
- * equal-compute unit. `executeToolCall` receives the task so per-task tool
- * surfaces (e.g. a gym keyed by task) can dispatch correctly.
- */
-interface RouterToolsSeam {
-    routerBaseUrl: string;
-    routerKey: string;
-    model?: string;
-    tools: ReadonlyArray<ToolSpec>;
-    executeToolCall: (name: string, args: Record<string, unknown>, task: unknown) => Promise<string>;
-    /** Online observer of each tool step — the seam a `DetectorMonitor` taps to watch the live pipe
-     *  (raise a `finding` when the worker loops/errors). Called after every tool call resolves, with
-     *  real per-call wall-clock (`startedAt`/`endedAt`/`durationMs`) so a push `TraceSource` can carry
-     *  non-zero span durations onto the unified timeline. */
-    onToolStep?: (step: {
-        toolName: string;
-        args: Record<string, unknown>;
-        status: 'ok' | 'error';
-        startedAt?: number;
-        endedAt?: number;
-        durationMs?: number;
-    }) => void;
-    /** Max inference turns. Default 200 (runaway backstop — set far above any
-     *  legitimate workflow). For tighter per-workflow limits use a cost budget
-     *  or wall-clock deadline at the call site. */
-    maxTurns?: number;
-}
-/**
- * The leaf `createWorktreeCliExecutor` as a backend-as-data factory: a supervisor-authored
- * `AgentProfile` driving claude / codex / opencode on its own worktree. `budgetExempt` like
- * the other CLI leaves; the authored systemPrompt + model reach the harness via §1.5.
- */
-declare const cliWorktreeExecutor: ExecutorFactory<unknown>;
-/**
- * Config for {@link createExecutor}: the backend is DATA — the cost dial a profile,
- * an experiment config, or a replay journal can name — not an import choice. Each
- * variant carries its backend's seam (router/router-tools/bridge/cli/cli-worktree/sandbox).
- */
-type ExecutorConfig = ({
-    backend: 'router';
-} & RouterSeam) | ({
-    backend: 'router-tools';
-} & RouterToolsSeam) | ({
-    backend: 'bridge';
-} & BridgeSeam) | ({
-    backend: 'cli';
-} & CliSeam) | ({
-    backend: 'cli-worktree';
-} & CliWorktreeSeam) | ({
-    backend: 'sandbox';
-    harness?: BackendType;
-} & SandboxSeam);
-/**
- * The single built-in executor factory. Picks a leaf backend by data (`config.backend`),
- * injects the matching seam, and delegates to that backend's built-in implementation.
- * The `Executor` port stays OPEN: bring-your-own agents implement `Executor` directly
- * and never pass through here. Use this (or `createExecutorRegistry`) instead of a
- * per-vendor adapter or a closed `inline|sandbox|cli` switch — those bypass the
- * `UsageEvent` reporting channel.
- */
-declare function createExecutor(config: ExecutorConfig): ExecutorFactory<unknown>;
-/**
- * The open resolver/registry. Pre-registers the three built-ins under their
- * runtime tags (`'router'`, `'sandbox'`, `'cli'`) and accepts `register(name,
- * factory)` for any additional runtime — and a BYO `AgentSpec.executor` resolves
- * without touching the registry at all. NOT a closed switch; registration + BYO
- * ARE the extension points.
- *
- * `resolve` precedence (frozen in `ExecutorRegistry`): a BYO `spec.executor` →
- * `harness === null` → the `'router'` factory; else a registered factory for the
- * harness-derived runtime (`'sandbox'` for any `BackendType`); else fail loud.
- */
-declare function createExecutorRegistry(): ExecutorRegistry;
-
-/**
- * @experimental
- *
- * `delegate` MCP tool — the ONE generic delegation verb, the agent-facing front door to
- * `delegate()` / `supervise()`. The agent hands it an INTENT (what it wants done); a default
- * authoring supervisor decomposes the intent and AUTHORS the worker profile it needs — there is no
- * hardcoded coder/researcher profile. It is the generic replacement for `delegate_code` /
- * `delegate_research`.
- *
- * Unlike those async, queue-backed tools (kick off → return a taskId → poll `delegation_status`),
- * `delegate` is SYNCHRONOUS: it awaits the full supervised run and returns the delivered output
- * TOGETHER WITH `spentTotal` — the conserved cost of the whole delegation (`iterations` / `tokens` /
- * `usd` / `ms`). Returning the real spend is the whole reason `delegate` beats `delegate_code`,
- * which has no cost channel.
- *
- * The supervisor's substrate (its brain `router`, the worker `backend`, the completion `deliverable`)
- * is INJECTED at server construction — never an agent-supplied arg — exactly as `delegate_code`
- * injects its `CoderDelegate`. The agent supplies only the intent (+ an optional per-call `model` /
- * `runId`).
- */
-
-/** @experimental */
-declare const DELEGATE_TOOL_NAME = "delegate";
-/** @experimental */
-declare const DELEGATE_DESCRIPTION: string;
-/** @experimental */
-declare const DELEGATE_INPUT_SCHEMA: {
-    readonly type: "object";
-    readonly properties: {
-        readonly intent: {
-            readonly type: "string";
-            readonly description: "What you want accomplished, as an outcome. The supervisor authors the worker.";
-        };
-        readonly model: {
-            readonly type: "string";
-            readonly description: "Optional per-call override for the supervisor brain model.";
-        };
-        readonly runId: {
-            readonly type: "string";
-            readonly description: "Optional trace-correlation id for this delegation.";
-        };
-    };
-    readonly required: readonly ["intent"];
-    readonly additionalProperties: false;
-};
-/** Parsed `delegate` tool arguments. */
-interface DelegateArgs {
-    intent: string;
-    model?: string;
-    runId?: string;
-}
-/** @experimental */
-declare function validateDelegateArgs(raw: unknown): DelegateArgs;
-/** The synchronous result the `delegate` tool returns to the calling agent: the delivered output (or
- *  the no-winner reason) PLUS the conserved spend of the whole delegation. */
-type DelegateResult = {
-    status: 'winner';
-    out: unknown;
-    outRef: string;
-    spentTotal: Spend;
-} | {
-    status: 'no-winner';
-    reason: string;
-    spentTotal: Spend;
-};
-/** @experimental */
-interface DelegateHandlerOptions {
-    /** The supervisor brain's router substrate (REQUIRED — the default supervisor is router-brained). */
-    router: RouterConfig;
-    /** WHERE the authored workers run. Required for `supervise()` to spawn anything. */
-    backend: ExecutorConfig;
-    /** The completion oracle the authored workers settle against (settled ⟺ delivered). */
-    deliverable?: DeliverableSpec;
-    /** Default supervisor brain model when a call omits `model`. */
-    model?: string;
-    /** Restrict the run to this subset of models. */
-    allowedModels?: readonly string[];
-}
-/**
- * Build the `delegate` tool handler. Closes over the injected supervisor substrate (`router` /
- * `backend` / `deliverable`); each call routes the agent's intent to `delegate()` and returns the
- * delivered output with its conserved cost.
- */
-declare function createDelegateHandler(options: DelegateHandlerOptions): (raw: unknown) => Promise<DelegateResult>;
-
-/**
- * @experimental
- *
- * Stdio JSON-RPC MCP server exposing the 5 delegation tools to sandbox
- * coding-harness agents (claude-code, codex, opencode, ...).
- *
- * The server is transport-bound but topology-free: tool execution is
- * delegated to handler functions composed from a queue, a feedback
- * store, and per-profile run delegates. Consumers wire those at
- * construction time. The `agent-runtime-mcp` bin spins up a default
- * configuration for the common case (real sandbox client + coder).
- *
- * Wire protocol: line-delimited JSON-RPC 2.0 over stdio. Each line is
- * one request; each response is one line. `tools/list` and `tools/call`
- * mirror the MCP 2024-11-05 spec; we do not pull in
- * `@modelcontextprotocol/sdk` to keep the dependency footprint zero.
- */
-
-/** @experimental */
-interface McpServerOptions {
-    /**
-     * Required to enable `delegate` — the ONE generic delegation verb (the replacement for
-     * delegate_code / delegate_research). Inject the supervisor substrate: its brain `router`, the
-     * worker `backend`, and the completion `deliverable`. The supervisor AUTHORS its own worker from
-     * the agent's intent, so there is no worker profile to wire here.
-     */
-    delegateSupervisor?: DelegateHandlerOptions;
-    /** Required to enable delegate_code. */
-    coderDelegate?: CoderDelegate;
-    /**
-     * Required to enable delegate_research. The substrate cannot ship a
-     * default — wire one that closes over your `runLoop` + a
-     * researcher profile (typically `@tangle-network/agent-knowledge`'s
-     * `researcherProfile` / `multiHarnessResearcherFanout`).
-     */
-    researcherDelegate?: ResearcherDelegate;
-    /**
-     * Required to enable delegate_ui_audit. Wire one that closes over your
-     * `runLoop` + `uiAuditorProfile` + a `SandboxClient` (the
-     * canonical in-process choice is `createInProcessUiAuditClient` from
-     * `@tangle-network/agent-runtime/profiles`) + your vision judge.
-     */
-    uiAuditorDelegate?: UiAuditorDelegate;
-    /** Override the default in-memory feedback store. */
-    feedbackStore?: FeedbackStore;
-    /** Override the default in-memory task queue. */
-    queue?: DelegationTaskQueue;
-    /**
-     * Record deterministic detached-session resume keys on single-variant
-     * coder/researcher submissions so a durable queue can resume them after a
-     * restart. Enable only when the wired delegates dispatch via sandbox
-     * sessions (`driveTurn`) AND `queue` persists records — the keys are inert
-     * otherwise. The bin turns this on alongside the durable store for
-     * session-backed (sibling/fleet) placements.
-     */
-    detachedDispatch?: boolean;
-    /**
-     * Extra tools to serve alongside the delegation tools, for example
-     * `createCoordinationTools(...).tools`. Registered after the built-ins; a
-     * duplicate name throws so delegation tools cannot be shadowed silently.
-     */
-    extraTools?: McpToolDescriptor[];
-    /**
-     * Inherited trace identity (`readTraceContextFromEnv()`) stamped on every
-     * record the DEFAULT queue creates. Ignored when `queue` is supplied —
-     * pass `traceContext` to that queue's constructor instead.
-     */
-    traceContext?: TraceContext;
-    /** Server display name surfaced via `initialize`. Default `'agent-runtime-mcp'`. */
-    serverName?: string;
-    /** Server version surfaced via `initialize`. Default = the package version baked at build time. */
-    serverVersion?: string;
-}
-/** @experimental */
-interface McpToolDescriptor {
-    name: string;
-    description: string;
-    inputSchema: Record<string, unknown>;
-    handler: (raw: unknown) => Promise<unknown>;
-}
-/** @experimental */
-interface McpServer {
-    /** Tools currently registered (depend on which delegates were wired). */
-    readonly tools: ReadonlyMap<string, McpToolDescriptor>;
-    /** The underlying queue — exposed so tests can introspect it. */
-    readonly queue: DelegationTaskQueue;
-    /** The feedback store — exposed for the same reason. */
-    readonly feedbackStore: FeedbackStore;
-    /** Handle a single parsed JSON-RPC message. Returns the response object (or `null` for notifications). */
-    handle(message: JsonRpcMessage): Promise<JsonRpcResponse | null>;
-    /** Drive the server on a stdio-shaped transport until `stop()` is called. */
-    serve(transport?: McpTransport): Promise<void>;
-    /** Stop a `serve` call. Subsequent requests are rejected. */
-    stop(): void;
-}
-/** @experimental */
-interface McpTransport {
-    input: NodeJS.ReadableStream;
-    output: NodeJS.WritableStream;
-}
-/** @experimental */
-interface JsonRpcMessage {
-    jsonrpc: '2.0';
-    id?: number | string | null;
-    method: string;
-    params?: unknown;
-}
-/** @experimental */
-interface JsonRpcResponse {
-    jsonrpc: '2.0';
-    id: number | string | null;
-    result?: unknown;
-    error?: {
-        code: number;
-        message: string;
-        data?: unknown;
-    };
-}
-/** @experimental */
-declare function createMcpServer(options?: McpServerOptions): McpServer;
-/**
- * In-process pair of `Readable` + `Writable` streams suitable for driving
- * `server.serve(...)` from a test. Returns the agent-side stream (the
- * client writes to it) and the server-side stream (the test reads from it).
- *
- * @experimental
- */
-declare function createInProcessTransport(): {
-    transport: McpTransport;
-    clientWrite(line: string): void;
-    clientClose(): void;
-    readServer(): Promise<JsonRpcResponse[]>;
-};
-
-/**
- * @experimental
- *
- * MCP binding for a live `Scope`. A sandbox driver gets the same small verbs
- * the in-process driver has: spawn, observe, await, steer, ask/answer, analyze,
- * and stop. Settled outputs remain Scope artifacts; product code can project
- * them into any UI/report envelope it needs.
- */
-
-/** A worker the driver has drained via `await_event`. */
-interface SettledWorker {
-    readonly id: string;
-    readonly status: 'done' | 'down';
-    readonly score?: number;
-    readonly valid?: boolean;
-    readonly outRef?: string;
-    readonly reason?: string;
-}
-type QuestionLevel = 'worker' | 'driver' | 'loop';
-type QuestionUrgency = 'continue-without' | 'blocks-step' | 'blocks-run';
-interface QuestionOption {
-    readonly label: string;
-    readonly tradeoff: string;
-}
-interface Question {
-    readonly id: string;
-    readonly from: string;
-    readonly level: QuestionLevel;
-    readonly question: string;
-    readonly reason: string;
-    readonly urgency: QuestionUrgency;
-    readonly options?: ReadonlyArray<QuestionOption>;
-}
-type QuestionDecision = {
-    readonly kind: 'answer';
-    readonly answer: string;
-    readonly by: string;
-} | {
-    readonly kind: 'defer';
-    readonly reason: string;
-} | {
-    readonly kind: 'escalate';
-    readonly to: 'parent' | 'user' | string;
-    readonly reason: string;
-};
-interface QuestionRecord extends Question {
-    readonly status: 'open' | 'answered' | 'deferred' | 'escalated';
-    readonly decision?: QuestionDecision;
-    readonly openedAt: number;
-}
-type QuestionPolicy = 'auto' | 'mustDecide' | 'bubble' | 'failClosed';
-interface AnalystRegistry {
-    readonly kinds: ReadonlyArray<{
-        id: string;
-        description: string;
-        area: string;
-    }>;
-    readonly run: (kindId: string, trace: unknown) => Promise<unknown>;
-}
-/** A trace-analyst result re-entered as a message on the bus (the `finding` event kind). */
-interface AnalystFindingEvent {
-    readonly fromWorker: string;
-    readonly analyst: string;
-    readonly findings: unknown;
-}
-/** A parent→child message (the down-leg): recorded for observability, delivered via the child inbox,
- *  never pulled back by the parent. `delivered` mirrors whether the live child accepted it. */
-interface DownMessageEvent {
-    readonly toWorker: string;
-    readonly instruction: string;
-    readonly delivered: boolean;
-}
-/** Every message on the one typed pipe. UP (child→parent): question / settled / finding — queued for
- *  the driver to `pull`. DOWN (parent→child): steer / answer — record-only (history + subscribers),
- *  routed to the child inbox. New kinds are additive. */
-type CoordinationEvent = {
-    readonly type: 'question';
-    readonly question: QuestionRecord;
-} | {
-    readonly type: 'settled';
-    readonly worker: SettledWorker;
-} | {
-    readonly type: 'finding';
-    readonly finding: AnalystFindingEvent;
-} | {
-    readonly type: 'steer';
-    readonly down: DownMessageEvent;
-} | {
-    readonly type: 'answer';
-    readonly down: DownMessageEvent;
-    readonly questionId: string;
-};
-type MakeWorkerAgent = (profile: unknown) => Agent<unknown, unknown>;
-interface CoordinationToolsOptions {
-    readonly scope: Scope<unknown>;
-    readonly blobs: ResultBlobStore;
-    readonly makeWorkerAgent: MakeWorkerAgent;
-    readonly perWorker: Budget;
-    readonly analysts?: AnalystRegistry;
-    readonly onEvent?: (event: CoordinationEvent) => void | Promise<void>;
-    readonly questionPolicy?: QuestionPolicy;
-    /** Analyst kind ids to run AUTOMATICALLY when a worker settles `done` (the analyst-on-settle
-     *  hook). Each result is published as a `finding` event on the bus — pass-through to subscribers
-     *  and queued for the driver to pull via `await_event`. Omit/empty = no auto-analysis (default;
-     *  the driver can still run lenses on demand via `run_analyst`). Requires `analysts`. */
-    readonly analyzeOnSettle?: ReadonlyArray<string>;
-}
-/**
- * The supervisor-side toolbox returned by {@link createCoordinationTools}: the MCP tool
- * descriptors a driver `AgentProfile` calls to spawn, steer, observe, and settle workers
- * over a live `Scope`, plus the typed accessors (`settled`/`questions`/`history`/`stats`/
- * `raiseFinding`) for the bidirectional coordination bus. This is the live, backend-of-your-
- * choice, steerable counterpart to the one-shot own-sandbox delegation MCP.
- */
-interface CoordinationTools {
-    readonly tools: McpToolDescriptor[];
-    isStopped(): boolean;
-    stopReason(): string | undefined;
-    settled(): ReadonlyArray<SettledWorker>;
-    questions(): ReadonlyArray<QuestionRecord>;
-    /** The full ordered log of every bus event — UP (settled / question / finding) and DOWN
-     *  (steer / answer) — the observability audit + replay trail. Each record carries seq,
-     *  timestamp, and priority. */
-    history(): ReadonlyArray<BusRecord<CoordinationEvent>>;
-    /** Bus throughput counters (published / pulled / by-kind) for live dashboards. */
-    stats(): BusStats;
-    /** Raise a `finding` on the bus from outside the settle hook — the seam an ONLINE detector
-     *  (mid-run, on the worker pipe) uses to tell the driver "this worker is looping/erroring" the
-     *  moment it happens, instead of only at settle. Queued for `await_event` + pass-through. */
-    raiseFinding(finding: AnalystFindingEvent): Promise<void>;
-}
-/** Build the driver's MCP tools over a live scope. */
-declare function createCoordinationTools(opts: CoordinationToolsOptions): CoordinationTools;
-
-export { type AnalystRegistry as A, type BusEvent as B, type CoordinationEvent as C, DELEGATE_DESCRIPTION as D, type ExecutorConfig as E, type FeedbackStore as F, createEventBus as G, createExecutor as H, InMemoryFeedbackStore as I, type JsonRpcMessage as J, createExecutorRegistry as K, type MakeWorkerAgent as M, type PublishOptions as P, type Question as Q, type SettledWorker as S, type CoordinationTools as a, type CoordinationToolsOptions as b, DELEGATE_INPUT_SCHEMA as c, DELEGATE_TOOL_NAME as d, type DelegateArgs as e, type DelegateHandlerOptions as f, type DelegateResult as g, type FeedbackEvent as h, type JsonRpcResponse as i, type McpServer as j, type McpServerOptions as k, type McpToolDescriptor as l, type McpTransport as m, type QuestionDecision as n, type QuestionPolicy as o, type QuestionRecord as p, createCoordinationTools as q, createDelegateHandler as r, createInProcessTransport as s, createMcpServer as t, eventToSnapshot as u, validateDelegateArgs as v, type BusRecord as w, type BusStats as x, type EventBus as y, cliWorktreeExecutor as z };