@tangle-network/agent-runtime 0.105.0 → 0.106.0

package/dist/coordination-BZZSVYpZ.d.ts

@@ -1,2570 +0,0 @@
-import { R as Runtime, E as ExecutorFactory, U as UsageEvent, k as ExecutorProgress, T as TraceSource, g as Spend, i as ExecutorRegistry, A as Agent, S as Scope, b as ResultBlobStore, B as Budget } from './types-CvNwMzQt.js';
-import { StreamingDetector, DetectorSignal, ToolSpan, AgentEvalError } from '@tangle-network/agent-eval';
-import { AgentProfile as AgentProfile$1 } from '@tangle-network/agent-interface';
-import { a as UiLens, U as UiFinding, C as CoderTask } from './substrate-Dyiqmd3o.js';
-import { a as SandboxClient, E as ExecCtx, t as LoopTraceEmitter, c as LoopTraceEvent, A as AgentRunSpec } from './types-BCoemcXU.js';
-import { AgentProfile, BackendType, SandboxEvent, SandboxInstance } from '@tangle-network/sandbox';
-import { b as ToolSpec, c as RuntimeTelemetryOptions, R as RouterConfig } from './sanitize-DEbPNtyI.js';
-import { R as RuntimeStreamEvent } from './types-BwoZWq-i.js';
-import { G as GitRunner, a as WorktreeCheckRunner, D as DeliverableSpec } from './completion-gate-BMy5LGoP.js';
-import { L as LocalHarness } from './local-harness-BDNcl6jI.js';
-import { ProviderExecutorOptions, AgentEnvironmentProviderRegistry } from './environment-provider.js';
-import { AgentEnvironmentProvider } from '@tangle-network/agent-interface/environment-provider';
-
-/**
- *
- * `piExecutor` — pi wrapped behind `Executor`, NOT forked.
- *
- * pi already implements everything a steerable worker needs, and implements it well: a queued
- * steering channel delivered between turns, follow-ups, abort, compaction, session persistence
- * with fork/branch, and an out-of-process line-delimited JSON protocol over stdin/stdout
- * (`pi --mode rpc`). Reimplementing any of that here would mean owning a turn loop someone else
- * already maintains. So this module is a thin protocol adapter, and every capability maps onto a
- * verb pi already has:
- *
- *   `execute`        → `prompt`, draining pi's event stream until `agent_end`
- *   `deliver`        → `prompt` with `streamingBehavior` — pi owns the queue, we do not
- *   `teardown`       → `abort`, then close stdin and reap the process
- *   `progress`       → pi's `tool_execution_start`/`_end` + `turn_end` events, plus `get_state`'s
- *                      `pendingMessageCount` mirrored locally so the read stays synchronous
- *   `traceSource`    → the same tool events decoded into the shared `ToolSpan` currency
- *   `resultArtifact` → the last assistant text collected off the stream
- *
- * It is registered through the DOCUMENTED extension point (`ExecutorRegistry.register('pi', …)`),
- * so nothing in the resolver switches on it and a consumer can replace it wholesale.
- *
- * agent-runtime does NOT take a dependency on pi. The wire shapes (`RpcCommand`, `AgentEvent`)
- * are read structurally off JSON lines, so a pi that adds commands stays compatible and a pi that
- * is not installed simply fails loud at spawn instead of at import.
- *
- * Usage accounting: pi reports token usage on its assistant messages when the provider supplies
- * it. Nothing is fabricated — a turn whose usage pi does not report contributes an `iteration`
- * event and zero tokens, exactly like the other honest executors.
- *
- * @experimental
- */
-
-/** The runtime name `piExecutor` registers under. */
-declare const PI_RUNTIME: Runtime;
-/** Seam key the registry threads a `PiSeam` through (`ExecutorContext.seams['pi']`). */
-declare const piSeamKey = "pi";
-/** How to launch pi in its out-of-process RPC mode, and how long to wait on it. */
-interface PiSeam {
-    /** The pi executable (default `'pi'`). Anything on PATH or an absolute path. */
-    bin?: string;
-    /** Extra args appended after `--mode rpc`. `--provider` / `--model` are added from `model`. */
-    args?: ReadonlyArray<string>;
-    /** `provider/model` or just `model` — split on the first `/` into pi's two flags. */
-    model?: string;
-    cwd?: string;
-    env?: Record<string, string>;
-    /** Wall-clock ceiling for one `prompt` (the wait for `agent_end`). Omit = no timeout. */
-    turnTimeoutMs?: number;
-    /** Newest-last activity window `progress()` reports. Default 12. */
-    activityWindow?: number;
-}
-/** Build the `Executor` for one pi worker. Registered as runtime `'pi'`. */
-declare const piExecutor: ExecutorFactory<unknown>;
-
-/**
- *
- * The worker-side receive end of the down-leg: a per-worker inbox an executor exposes as
- * `Executor.deliver`. The driver's `steer_agent` / `answer_question` land here,
- * and the worker's agent loop drains them at two points (Drew's two delivery modes):
- *
- *   - QUEUED (default): the message accumulates and is FLUSHED at the next step boundary — folded
- *     into the conversation before the next think. A worker is also forced to flush BEFORE it may
- *     settle, so it can never finish while a steer/answer it never read is still pending.
- *   - FORCEFUL (`interrupt: true`): trips `freshInterrupt()`'s signal so the loop can abort its
- *     in-flight turn immediately, then re-plan with the message folded in — breaking the worker out
- *     of a wrong path mid-task instead of waiting for it to finish the step.
- *
- * `deliver` never throws — a malformed message is ignored, per the `Executor.deliver` contract.
- *
- * @experimental
- */
-interface InboxMessage {
-    readonly kind: 'steer' | 'answer';
-    readonly text: string;
-    /** Forceful messages abort the in-flight turn; queued ones wait for the boundary flush. */
-    readonly interrupt: boolean;
-    /** Present for an `answer` — the question id it resolves. */
-    readonly questionId?: string;
-}
-interface Inbox {
-    /** The `Executor.deliver` implementation — accept a raw down-message from `Scope.send`. */
-    deliver(msg: unknown): void;
-    /** Remove and return all pending messages (the flush). */
-    drain(): InboxMessage[];
-    pending(): number;
-    /** Open a fresh per-turn interrupt signal; a later forceful `deliver` aborts it. The loop links
-     *  this into the signal it passes to its inference call, then re-plans when it fires. */
-    freshInterrupt(): AbortSignal;
-    /** Render drained messages as ONE operator turn to fold into the worker's conversation. */
-    fold(messages: ReadonlyArray<InboxMessage>): string;
-}
-/** Create the worker-side inbox for the down-leg: the driver's `steer_agent` / `answer_question` messages queue here and the worker's loop drains them at step boundaries and before settle. */
-declare function createInbox(): Inbox;
-
-/**
- *
- * The STEERABLE sandbox worker: one box, one server-side session, MANY turns — so a message
- * from the driver has a boundary to be folded into.
- *
- * The default cloud worker was built on `singleShotDriver`: one `runAgentRounds` shot, no turn
- * boundary, and no `Executor.deliver`. `Scope.send` therefore returned `false` for it and
- * `steer_agent` reported `delivered:false` on every call — steering the DEFAULT worker was
- * mechanically impossible, not merely unused. This module is the missing continuation loop.
- *
- * Structure deliberately mirrors `streamBridgeSession` (the cli-bridge equivalent that already
- * works) so both steerable runtimes have ONE shape:
- *
- *   - turn 0 sends the task through `SandboxLineage.start` (fresh box, minted session id);
- *   - each later turn fires ONLY when the inbox has a steer/answer to fold, and goes through
- *     `SandboxLineage.continue` — the SAME box and the SAME server-side session, so the prompt
- *     carries only the new instruction and the worker keeps everything it had already learned;
- *   - a worker may not settle while a delivered steer is unread: the loop drains once more
- *     before breaking, which is what makes `steer_agent` a promise rather than a hint;
- *   - a forceful (`interrupt:true`) steer aborts the in-flight turn so the worker re-plans
- *     immediately instead of finishing a path the supervisor already rejected.
- *
- * It also produces the LIVE signal a supervisor steers FROM: every sandbox event stamps
- * activity, tool parts are decoded into the shared `ToolSpan` currency for the online detector
- * panel, and `progress()` answers turn / tool / idle / pending-steer questions synchronously.
- *
- * Reports REAL usage only — token and cost numbers come from the sandbox events themselves.
- *
- * @experimental
- */
-
-/** Ceiling on continuation turns. Turn 0 is the task; every later turn is a folded steer, so
- *  this bounds how many times a supervisor may redirect ONE worker before it must respawn. */
-declare const DEFAULT_SANDBOX_STEERING_MAX_TURNS = 24;
-/** Opt-in configuration for the steerable sandbox worker (`SandboxSeam.steering`). Absent, the
- *  sandbox executor keeps its historical single-shot `runAgentRounds` composition verbatim. */
-interface SandboxSteeringOptions {
-    /** Max turns for one worker (turn 0 + folded steers). Default {@link DEFAULT_SANDBOX_STEERING_MAX_TURNS}. */
-    readonly maxTurns?: number;
-    /** How many recent tool/turn notes `progress()` reports. Default 12. */
-    readonly activityWindow?: number;
-    /** Per-turn wall-clock ceiling; the turn's stream is aborted when it elapses. */
-    readonly turnTimeoutMs?: number;
-}
-/** What the steerable session exposes to its executor: the usage stream plus the live reads. */
-interface SteerableSandboxSession {
-    /** Drive the worker to settlement. `signal` is the spawn-scoped abort handed to `execute`. */
-    stream(task: unknown, signal: AbortSignal): AsyncIterable<UsageEvent>;
-    progress(): ExecutorProgress;
-    traceSource(): TraceSource;
-    artifact(): {
-        outRef: string;
-        out: unknown;
-        spent: Spend;
-    } | undefined;
-    teardown(): Promise<void>;
-}
-interface SteerableSandboxArgs {
-    readonly controller: AbortController;
-    readonly profile: AgentProfile;
-    readonly harness: BackendType;
-    readonly sandboxClient: SandboxClient;
-    readonly inbox: Inbox;
-    readonly taskToPrompt: (task: unknown) => string;
-    readonly options?: SandboxSteeringOptions;
-    readonly loopCtx?: Partial<Omit<ExecCtx, 'sandboxClient' | 'signal'>>;
-    readonly contentRef: (prefix: string, value: unknown) => string;
-    readonly now?: () => number;
-}
-/** One steerable sandbox worker. The returned session is inert until `stream()` is drained. */
-declare function createSteerableSandboxSession(args: SteerableSandboxArgs): SteerableSandboxSession;
-
-/**
- *
- * 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 `runAgentRounds` 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`; `runAgentRounds`/`acquireSandbox` are runtime kernels
- * from this package. No per-vendor adapters live here.
- *
- * @experimental
- */
-
-/**
- * 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 `runAgentRounds` creates
- * boxes through, plus the optional trace/run/lineage wiring forwarded into the
- * loop. `lineage` is opaque here (PR #150's `RunAgentRoundsOptions.lineage`): forwarded
- * forward-compatibly, never inspected — this executor does NOT reinvent
- * checkpoint/fork.
- */
-interface SandboxSeam {
-    sandboxClient: SandboxClient;
-    /** Forwarded into the composed `runAgentRounds`'s `ctx` (trace emitter, run handle, etc.). */
-    loopCtx?: Partial<Omit<ExecCtx, 'sandboxClient' | 'signal'>>;
-    /** PR #150 `RunAgentRoundsOptions.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;
-    /**
-     * OPT-IN: run this worker as a multi-turn, STEERABLE session instead of the historical
-     * single-shot `runAgentRounds` composition. Setting it gives the sandbox worker an `Executor.deliver`
-     * inbox (so `Scope.send` / `steer_agent` actually reach it), a live tool-activity trace, and a
-     * `progress()` read — turning the default cloud worker from something a supervisor can only
-     * wait on into something it can watch and correct.
-     *
-     * Absent, nothing changes: the same `runAgentRounds` leaf, no inbox, `steer_agent` still reports
-     * `delivered:false`. Opt-in because a steerable worker holds ONE box across several turns,
-     * which is a different resource profile from a fire-and-forget shot.
-     */
-    steering?: SandboxSteeringOptions;
-}
-/** 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;
-    /** Local CLI harness transport. Omit when `bridge` is set. */
-    harness?: LocalHarness;
-    taskPrompt: string;
-    runId?: string;
-    baseRef?: string;
-    harnessTimeoutMs?: number;
-    /** Isolated, network-off Codex execution with terminal JSONL usage capture. */
-    codexReproducible?: boolean;
-    /** Absolute host paths denied to reproducible Codex. */
-    codexReadDeniedPaths?: ReadonlyArray<string>;
-    testCmd?: string;
-    typecheckCmd?: string;
-    checkTimeoutMs?: number;
-    checkOutputCap?: number;
-    budgetExempt?: boolean;
-    /** Live cli-bridge transport inside the worktree. When set, the worktree leaf accepts
-     *  `deliver()` messages and resumes the same bridge session in this worktree cwd. */
-    bridge?: CliWorktreeBridgeSeam;
-    /** Test seam — forwarded to worktree helpers. */
-    runGit?: GitRunner;
-    /** Test seam — forwarded to verification checks. */
-    runCommand?: WorktreeCheckRunner;
-}
-interface CliWorktreeBridgeSeam {
-    bridgeUrl: string;
-    bridgeBearer: string;
-    /** Bridge model/harness id. Defaults to the profile's model hint when omitted. */
-    model?: string;
-    agentProfile?: Record<string, unknown>;
-    timeoutMs?: number;
-    /** Stable cli-bridge session id. Defaults to `bridge-worktree-${runId}`. */
-    sessionId?: string;
-    maxTurns?: 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;
-    /** Optional working directory forwarded to cli-bridge and persisted with the session. */
-    cwd?: 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;
-}
-/** Generic environment provider executor config. External packages implement
- *  `AgentEnvironmentProvider`; this built-in wrapper lets `createExecutor`
- *  consume them as backend data while preserving the existing usage channel. */
-interface ProviderSeam extends ProviderExecutorOptions {
-    provider: AgentEnvironmentProvider | string;
-    registry?: AgentEnvironmentProviderRegistry;
-}
-/**
- * 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: 'provider';
-} & ProviderSeam) | ({
-    backend: 'pi';
-} & PiSeam) | ({
-    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;
-
-/**
- *
- * The ONLINE analyst: watch a `TraceSource` and fold each tool span through agent-eval's published
- * streaming detector kernel (`repeatedActionDetector`/`errorStreakDetector` — the SAME kernel the
- * control loop folds), firing `onSignal` the moment a worker loops or error-storms. Substrate-
- * agnostic: it consumes spans from any source (owned router/bridge loop OR a sandbox box session),
- * never the raw tool seam. Detection logic + the failure taxonomy live in agent-eval; not reimplemented.
- *
- * @experimental
- */
-
-interface WatchTraceOptions {
-    /** The detectors to run online. Defaults to a stuck-loop + error-streak panel. */
-    readonly detectors?: ReadonlyArray<StreamingDetector>;
-    /** Fired for each signal a detector raises — the seam that raises a `finding` on the bus. */
-    readonly onSignal?: (signal: DetectorSignal, span: ToolSpan) => void | Promise<void>;
-}
-/** The default online panel for a tool-call pipe: a worker repeating the same call, or hammering
- *  consecutive errors. (No-progress needs a domain progress-probe, so it is opt-in, not default.)
- *
- *  Coverage note: `repeated-action` works for EVERY harness (it needs only tool name + args, which
- *  every adapter provides). `error-streak` needs per-call status — opencode carries it inline
- *  (`state.status`, VALIDATED live), but claude-code/codex tool-call parts do NOT (their errors live
- *  in separate result blocks not yet decoded), so error-streak is silent for those until result-block
- *  decoding is added + live-validated. It is in the panel because it is correct where status exists. */
-declare function defaultToolDetectors(): StreamingDetector[];
-/** Subscribe to a `TraceSource` and run the streaming detectors over its live spans. Returns an
- *  unsubscribe. A defensive `argHash` failure (circular args) never throws out of the side-channel. */
-declare function watchTrace(source: TraceSource, opts?: WatchTraceOptions): () => void;
-
-/**
- *
- * 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.
- *
- * @experimental
- */
-/** 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;
-}
-/** Create the child→parent coordination bus: one typed pipe for settled outputs, questions, and analyst findings, with a priority-ordered pull queue and a pass-through subscribe lane. */
-declare function createEventBus<E extends BusEvent>(now?: () => number): EventBus<E>;
-
-/**
- *
- * Sandbox-session coder decode layer. The sandbox-session delegate (`./delegates`) and the
- * cross-restart resume driver run the in-box harness over a `SandboxClient` and need to
- * (a) build an `AgentRunSpec` from the caller-authored (or minimal model-only default) worker
- * profile, (b) decode the harness event stream into a structured `CoderOutput`, and (c) gate it with
- * the shared mechanical checks. This sandbox-session path is kept separate from the generic recursive
- * path: `worktreeFanout` instead settles the raw `WorktreePatchArtifact` and gates via
- * `patchDelivered`. Prefer `worktreeFanout` / `worktreeLoopRunner` for NEW local-repo coding.
- *
- * The decode tolerates two `result`-event shapes:
- *   1. the in-process executor's raw worktree-harness result (`{ branch, patch, stats, checks }`),
- *      projected onto `CoderOutput`; and
- *   2. an LLM-emitted JSON block (`{ branch, patch, testResult, typecheckResult, diffStats }`),
- *      lifted onto `data.result` or scanned out of the assistant transcript (any harness shape).
- *
- * @experimental
- */
-
-/** @experimental The structured coder result the sandbox-session path decodes + gates. */
-interface CoderOutput {
-    /** Branch the agent wrote the patch on. */
-    branch: string;
-    /** Unified diff (`git diff <base>..HEAD`). */
-    patch: string;
-    testResult: {
-        passed: boolean;
-        output: string;
-    };
-    typecheckResult: {
-        passed: boolean;
-        output: string;
-    };
-    diffStats: {
-        filesChanged: number;
-        insertions: number;
-        deletions: number;
-    };
-    /** Optional reviewer commentary surfaced by the agent. */
-    reviewerNotes?: string;
-}
-
-/**
- *
- * Persistence port for the MCP delegation queue.
- *
- * `DelegationTaskQueue` keeps its working set in memory (status/history
- * reads stay synchronous) and journals every record mutation through a
- * `DelegationStore`. `DelegationTaskQueue.restore({ store })` is the load
- * path: it reads the full record set once at construction and rehydrates
- * the queue from it. After that the store only sees writes.
- *
- * Records MUST be JSON-safe — `FileDelegationStore` round-trips them
- * through `JSON.stringify`/`JSON.parse`, so a `Date`, `Map`, or function
- * smuggled into `args`/`result` would corrupt the journal.
- *
- * @experimental
- */
-
-/** @experimental */
-interface DelegationStore {
-    /**
-     * Read every persisted record. Called once, by
-     * `DelegationTaskQueue.restore`, before any write. A missing backing
-     * file is an empty store; an unparseable one throws
-     * `DelegationStateCorruptError`.
-     */
-    loadAll(): Promise<DelegationRecord[]>;
-    /** Insert or replace the record keyed by `record.taskId`. */
-    upsert(record: DelegationRecord): Promise<void>;
-    /**
-     * Resolve an idempotency key to the taskId that claimed it, if any.
-     * The queue serves submit-time dedupe from its rehydrated in-memory
-     * index; this read exists for consumers that share a store across
-     * processes without holding the full record set.
-     */
-    lookupIdempotencyKey(key: string): Promise<string | undefined>;
-    /** Delete the named records — the retention-cap eviction path. */
-    remove(taskIds: readonly string[]): Promise<void>;
-}
-/**
- * The persisted delegation state exists but cannot be parsed into
- * records. Fail loud: silently starting empty over a corrupt journal
- * would erase delegation history and re-run idempotent work. Opt into
- * recovery explicitly via `FileDelegationStoreOptions.recoverCorrupt`
- * (the bin maps `AGENT_RUNTIME_DELEGATION_STATE_RECOVER=1` onto it),
- * which archives the corrupt file and starts fresh.
- *
- * @experimental
- */
-declare class DelegationStateCorruptError extends AgentEvalError {
-    constructor(message: string, options?: {
-        cause?: unknown;
-    });
-}
-/**
- * A delegation-store read or write failed (filesystem error, store
- * called before `loadAll`, ...). Once the queue observes one, it stops
- * accepting new submissions — accepting work it cannot journal would
- * silently demote durable mode to in-memory mode.
- *
- * @experimental
- */
-declare class DelegationPersistenceError extends AgentEvalError {
-    constructor(message: string, options?: {
-        cause?: unknown;
-    });
-}
-/** In-memory `DelegationStore` — suitable for single-process use and tests. @experimental */
-declare class InMemoryDelegationStore implements DelegationStore {
-    private readonly records;
-    loadAll(): Promise<DelegationRecord[]>;
-    upsert(record: DelegationRecord): Promise<void>;
-    lookupIdempotencyKey(key: string): Promise<string | undefined>;
-    remove(taskIds: readonly string[]): Promise<void>;
-}
-/** @experimental */
-interface FileDelegationStoreOptions {
-    /** Absolute path of the JSON state file. Parent directories are created on first write. */
-    filePath: string;
-    /**
-     * When the state file exists but cannot be parsed, archive it to
-     * `<filePath>.corrupt-<timestamp>` and start empty instead of
-     * throwing `DelegationStateCorruptError`. Default false.
-     */
-    recoverCorrupt?: boolean;
-}
-/**
- * JSON-file persistence for the delegation queue. Each write serializes
- * the full record set and lands it atomically (write to a sibling tmp
- * file, then `rename`), so readers never observe a torn file — a crash
- * mid-write leaves the previous snapshot intact. Writes are serialized
- * internally; concurrent `upsert`/`remove` calls cannot interleave.
- *
- * Built for the MCP server's scale (one stdio process, hundreds of
- * records): full-snapshot writes keep the format trivially inspectable
- * and corruption-detectable without a database dependency.
- *
- * @experimental
- */
-declare class FileDelegationStore implements DelegationStore {
-    private readonly filePath;
-    private readonly recoverCorrupt;
-    private readonly records;
-    private loaded;
-    private writeTail;
-    private tmpSeq;
-    constructor(options: FileDelegationStoreOptions);
-    loadAll(): Promise<DelegationRecord[]>;
-    upsert(record: DelegationRecord): Promise<void>;
-    lookupIdempotencyKey(key: string): Promise<string | undefined>;
-    remove(taskIds: readonly string[]): Promise<void>;
-    private assertLoaded;
-    private enqueueWrite;
-    private writeSnapshot;
-}
-
-/**
- *
- * Compact loop-trace tee for the delegation journal.
- *
- * The OTEL exporter ({@link createPropagatingTraceEmitter}) is a no-op
- * without `OTEL_EXPORTER_OTLP_ENDPOINT`, which leaves delegated work streams
- * dark in practice. This module derives the same loop → round → branch span
- * tree (via the shared {@link buildLoopSpanNodes} builder) into a small,
- * JSON-safe shape persisted directly on the `DelegationRecord` — observable
- * through `delegation_status` with no collector infrastructure. Both sinks
- * coexist: the OTEL export path is unchanged.
- *
- * Payload discipline: a record's trace is hard-capped (spans + serialized
- * bytes). Past the cap the OLDEST spans are dropped and the record carries a
- * `traceTruncated: true` marker — truncation is never silent.
- *
- * @experimental
- */
-
-/**
- * One span of a delegation's compact trace. Flat (parent linkage by id), all
- * values JSON-safe scalars — `FileDelegationStore` round-trips records
- * through `JSON.stringify`. `meta` carries the span's attributes (GenAI
- * semconv keys + `tangle.loop.*` extensions) exactly as the OTEL sink emits
- * them, so a consumer can re-export journal traces losslessly.
- *
- * @experimental
- */
-interface DelegationTraceSpan {
-    spanId: string;
-    /** Absent on the tree root. */
-    parentSpanId?: string;
-    /** `'loop'` | `'loop.round'` | `'loop.iteration'` (or a sink-specific name). */
-    name: string;
-    /** Topology level: loop root, plan round, or iteration branch. */
-    kind: 'loop' | 'round' | 'branch';
-    startMs: number;
-    endMs: number;
-    meta?: Record<string, string | number | boolean>;
-}
-/** Default cap on spans retained per delegation record. @experimental */
-declare const DELEGATION_TRACE_MAX_SPANS = 512;
-/** Default cap on the serialized trace payload per record, in bytes. @experimental */
-declare const DELEGATION_TRACE_MAX_BYTES: number;
-/** @experimental */
-interface DelegationTraceCaps {
-    /** Default {@link DELEGATION_TRACE_MAX_SPANS}. */
-    maxSpans?: number;
-    /** Default {@link DELEGATION_TRACE_MAX_BYTES}. Approximate — measured as the
-     *  sum of per-span `JSON.stringify` lengths. */
-    maxBytes?: number;
-}
-/** @experimental */
-interface CappedDelegationTrace {
-    trace: DelegationTraceSpan[];
-    /** True when oldest spans were dropped to honor the caps. */
-    truncated: boolean;
-}
-/**
- * Derive the compact span tree for ONE loop run from its buffered
- * `LoopTraceEvent` stream. Same reconstruction as the OTEL exporter
- * ({@link buildLoopSpanNodes}); tolerates partial streams.
- *
- * @experimental
- */
-declare function buildDelegationTraceSpans(events: ReadonlyArray<LoopTraceEvent>): DelegationTraceSpan[];
-/**
- * Enforce the trace caps over an ordered (oldest-first) span list. Drops the
- * OLDEST spans first and reports `truncated: true` when anything was dropped;
- * the newest span always survives, so a non-empty input never caps to empty.
- * Dropping a parent may orphan surviving children's `parentSpanId` references
- * — acceptable for the flat journal shape; consumers treat unresolved parents
- * as roots.
- *
- * @experimental
- */
-declare function capDelegationTrace(spans: ReadonlyArray<DelegationTraceSpan>, caps?: DelegationTraceCaps): CappedDelegationTrace;
-/**
- * Per-delegation trace collector. Buffers `LoopTraceEvent`s per runId
- * (mirroring the OTEL emitter's buffering) and hands the derived compact
- * spans to `onSpans` when a run reaches `loop.ended`. `settle()` drains runs
- * that never ended — a hard-aborted loop still leaves its partial tree in the
- * journal, unlike the OTEL path which drops it.
- *
- * @experimental
- */
-interface DelegationTraceCollector {
-    emitter: LoopTraceEmitter;
-    /** Flush buffered events of runs that never reached `loop.ended`. */
-    settle(): void;
-}
-/** Build a `DelegationTraceCollector` that buffers loop-trace events and converts them to spans on settle. @experimental */
-declare function createDelegationTraceCollector(onSpans: (spans: DelegationTraceSpan[]) => void): DelegationTraceCollector;
-/**
- * Fan one `LoopTraceEvent` stream into several emitters — e.g. the
- * process-wide OTEL exporter AND the per-delegation journal collector.
- * `undefined` entries are skipped; returns `undefined` when nothing is left
- * so callers keep the kernel's "no emitter, no events" fast path.
- *
- * @experimental
- */
-declare function composeLoopTraceEmitters(...emitters: ReadonlyArray<LoopTraceEmitter | undefined>): LoopTraceEmitter | undefined;
-
-/**
- * OTEL span exporter — streams LoopTraceEvents to an OTLP/HTTP collector.
- *
- * Reads OTEL_EXPORTER_OTLP_ENDPOINT + OTEL_EXPORTER_OTLP_HEADERS from env
- * when no explicit config is given. Keeps the runtime dep-free from
- * @opentelemetry/sdk-trace-base — minimal OTLP/JSON serializer.
- *
- * The exporter accepts both raw OtelSpan objects and LoopTraceEvents
- * (which get converted to OTLP spans automatically).
- */
-
-interface OtelExportConfig {
-    /** OTLP endpoint. Reads OTEL_EXPORTER_OTLP_ENDPOINT env by default. */
-    endpoint?: string;
-    /** OTLP headers. Reads OTEL_EXPORTER_OTLP_HEADERS env by default. */
-    headers?: Record<string, string>;
-    /** Batch size before flush. Default 64. */
-    batchSize?: number;
-    /** Flush interval ms. Default 5000. */
-    flushIntervalMs?: number;
-    /** Resource attributes stamped on every export. */
-    resourceAttributes?: Record<string, string | number | boolean>;
-    /** Service name. Default 'agent-runtime'. */
-    serviceName?: string;
-}
-interface OtelExporter {
-    /** Export a span. */
-    exportSpan(span: OtelSpan): void;
-    /** Force flush pending spans. */
-    flush(): Promise<void>;
-    /** Shutdown cleanly. */
-    shutdown(): Promise<void>;
-}
-interface OtelSpan {
-    traceId: string;
-    spanId: string;
-    parentSpanId?: string;
-    name: string;
-    kind?: number;
-    startTimeUnixNano: string;
-    endTimeUnixNano: string;
-    attributes?: OtelAttribute[];
-    status?: {
-        code: number;
-        message?: string;
-    };
-}
-interface OtelAttribute {
-    key: string;
-    value: {
-        stringValue?: string;
-        intValue?: string;
-        doubleValue?: number;
-        boolValue?: boolean;
-    };
-}
-/**
- * Create an OTEL exporter. Returns undefined when no endpoint is configured.
- */
-declare function createOtelExporter(config?: OtelExportConfig): OtelExporter | undefined;
-/**
- * Convert a LoopTraceEvent into an OtelSpan for export.
- */
-declare function loopEventToOtelSpan(event: {
-    kind: string;
-    runId: string;
-    timestamp: number;
-    payload: object;
-}, traceId: string, parentSpanId?: string): OtelSpan;
-interface RuntimeEventOtelOptions extends RuntimeTelemetryOptions {
-    /** Final customer redactor applied after the schema-aware runtime sanitizer. */
-    redact?: (value: unknown) => unknown;
-}
-/** Convert normalized runtime events into lossless, redacted child spans. */
-declare function buildRuntimeEventOtelSpans(events: ReadonlyArray<RuntimeStreamEvent>, traceId: string, parentSpanId?: string, options?: RuntimeEventOtelOptions): OtelSpan[];
-/**
- * Sink-neutral node in a reconstructed loop span tree. The root node's
- * `parentSpanId` is `undefined` — sinks decide how to parent it (the OTEL
- * mapper attaches the inherited delegation span; the delegation journal
- * leaves it as the tree root).
- */
-interface LoopSpanNode {
-    spanId: string;
-    parentSpanId?: string;
-    /** `'loop'` | `'loop.round'` | `'loop.iteration'`. */
-    name: string;
-    /** Topology level: loop root, plan round, or iteration branch. */
-    kind: 'loop' | 'round' | 'branch';
-    startMs: number;
-    endMs: number;
-    attrs: Record<string, string | number | boolean>;
-    /** True when the iteration carried an error — maps to OTEL status code 2. */
-    error: boolean;
-}
-/**
- * Build a nested, real-duration OTLP span tree for ONE loop run from its full
- * ordered `LoopTraceEvent` stream. Unlike `loopEventToOtelSpan` (one flat,
- * zero-duration span per event), this reconstructs the topology hierarchy a
- * GenAI trace viewer renders natively:
- *
- *   loop (invoke_workflow)
- *     └─ loop.round[k] (invoke_workflow)   ← tangle.loop.move.{kind,width,rationale}
- *          ├─ loop.iteration[i] (invoke_agent)  ← gen_ai.agent.name + usage + verdict + placement
- *          └─ …
- *
- * Attributes follow the current GenAI semconv (`gen_ai.*`) where they apply and
- * a namespaced `tangle.loop.*` / `tangle.cost.usd` extension for topology /
- * verdict / placement / cost (not yet standardized). Pure: feed it a buffered
- * per-runId event array (e.g. flushed on `loop.ended`) and export the result.
- */
-declare function buildLoopOtelSpans(events: ReadonlyArray<{
-    kind: string;
-    runId: string;
-    timestamp: number;
-    payload: object;
-}>, traceId: string, rootParentSpanId?: string): OtelSpan[];
-/**
- * Sink-neutral core behind {@link buildLoopOtelSpans}: reconstruct the
- * loop → round → branch span tree from one run's ordered `LoopTraceEvent`
- * stream. Consumed by the OTEL mapper above and by the MCP delegation
- * journal's compact trace tee — one topology reconstruction, two sinks.
- * Tolerates partial streams (a run that never reached `loop.ended` closes
- * at the last observed event's timestamp).
- */
-declare function buildLoopSpanNodes(events: ReadonlyArray<{
-    kind: string;
-    runId: string;
-    timestamp: number;
-    payload: object;
-}>): LoopSpanNode[];
-/** Wire version the eval-runs ingest enforces (X-Tangle-Wire-Version + body). */
-declare const INTELLIGENCE_WIRE_VERSION = "2026-05-26.v1";
-interface EvalRunGeneration {
-    /** 0-based ordinal of this generation within the run (required by ingest). */
-    index: number;
-    /** Identity of the proposed surface change (content-addressed hash). */
-    surfaceHash: string;
-    /** Arbitrary provenance for this generation (rationale, evidence, source). */
-    surface?: unknown;
-    /** Per-scenario results; empty until the generation is measured. */
-    cells?: unknown[];
-    /** Mean composite score (0 when unmeasured — pair with labels.measured). */
-    compositeMean: number;
-    costUsd: number;
-    durationMs: number;
-}
-interface EvalRunEvent {
-    runId: string;
-    runDir: string;
-    /** ISO timestamp. */
-    timestamp: string;
-    status: 'started' | 'baseline-complete' | 'generation-complete' | 'gate-decided' | 'finished' | 'errored';
-    labels?: Record<string, string>;
-    baseline?: EvalRunGeneration;
-    generations?: EvalRunGeneration[];
-    gateDecision?: 'ship' | 'hold' | 'need_more_work' | 'model_ceiling' | 'arch_ceiling';
-    holdoutLift?: number;
-    totalCostUsd: number;
-    totalDurationMs: number;
-    errorMessage?: string;
-}
-interface EvalRunsExportConfig {
-    /** Bearer key — tenant is resolved server-side from it. Reads TANGLE_API_KEY. */
-    apiKey?: string;
-    /** Intelligence base. Reads TANGLE_INTELLIGENCE_URL env, else prod. */
-    base?: string;
-    /** Idempotency-Key header (e.g. the runId) — safe retries + upsert. */
-    idempotencyKey?: string;
-}
-interface EvalRunsExportResult {
-    ok: boolean;
-    status: number;
-    accepted: number;
-    rejected: Array<{
-        index: number;
-        reason: string;
-    }>;
-}
-/**
- * Ship self-improvement eval-run events to Tangle Intelligence. Unlike the
- * best-effort span exporter, this RESOLVES with the ingest verdict (accepted /
- * rejected per event) so a consumer's loop can assert its provenance landed.
- * Throws only on a missing key or network failure.
- */
-declare function exportEvalRuns(events: EvalRunEvent[], config?: EvalRunsExportConfig): Promise<EvalRunsExportResult>;
-
-/**
- *
- * Trace context propagation for MCP subprocess.
- *
- * When the MCP server is launched as a child process by a sandbox harness,
- * the parent passes trace context via environment variables:
- *
- *   TRACE_ID=<current-run-trace-id>
- *   PARENT_SPAN_ID=<span-that-dispatched-the-delegation>
- *
- * The MCP server reads these at startup and uses them as the root of its
- * internal trace tree. All spans emitted by `runAgentRounds` invocations inside
- * the MCP are children of the parent's delegation span.
- *
- * When these env vars are absent, the MCP generates a fresh trace root —
- * the server operates standalone without trace joining.
- *
- * @experimental
- */
-
-interface TraceContext {
-    /** Trace id inherited from the parent process, or a fresh one. */
-    traceId: string;
-    /** Parent span id from the delegation that launched this MCP server. */
-    parentSpanId?: string;
-}
-/**
- * Read trace context from the process environment.
- * Returns a context with inherited ids or a freshly generated root.
- */
-declare function readTraceContextFromEnv(): TraceContext;
-/**
- * Create a LoopTraceEmitter that:
- *   1. Parents all spans under the inherited PARENT_SPAN_ID.
- *   2. Exports spans to OTEL when OTEL_EXPORTER_OTLP_ENDPOINT is set.
- *
- * Returns both the emitter and the optional exporter handle for shutdown.
- */
-declare function createPropagatingTraceEmitter(ctx: TraceContext): {
-    emitter: LoopTraceEmitter;
-    exporter: OtelExporter | undefined;
-    context: TraceContext;
-};
-/**
- * Build env vars to pass to a child MCP subprocess so it inherits the
- * current trace context.
- */
-declare function traceContextToEnv(ctx: TraceContext): Record<string, string>;
-
-/**
- *
- * MCP delegation tool surface — the typed inputs/outputs the product agent
- * sees over the wire. These types are the contract; the JSON schemas under
- * `tools/*` mirror them for the MCP `tools/list` advertisement.
- *
- * Async semantics: `delegate_ui_audit` returns a `taskId` immediately. The
- * product agent polls `delegation_status` until the task transitions to
- * `completed` | `failed` | `cancelled`. `delegate_feedback` +
- * `delegation_history` are synchronous reads / writes against the local
- * task queue + feedback store.
- *
- * @experimental
- */
-
-/** @experimental */
-type DelegationProfile = 'coder' | 'researcher' | 'ui-auditor';
-/** @experimental */
-type DelegationStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
-/**
- * Minimal `CoderTask` overrides exposed over the MCP wire. The full
- * `CoderTask` carries fields the kernel synthesizes from `goal` +
- * `repoRoot` — the agent only edits the few that materially gate
- * validator behavior.
- *
- * @experimental
- */
-interface DelegateCodeConfig {
-    testCmd?: string;
-    typecheckCmd?: string;
-    forbiddenPaths?: string[];
-    maxDiffLines?: number;
-}
-/** @experimental */
-interface DelegateCodeArgs {
-    /** Natural-language description of what the coder must accomplish. */
-    goal: string;
-    /** Absolute path inside the sandbox where the repo lives. */
-    repoRoot: string;
-    /** Optional free-form context the agent surfaces in the prompt prelude. */
-    contextHint?: string;
-    /**
-     * When > 1, dispatches `multiHarnessCoderFanout` across N harnesses
-     * (claude-code, codex, opencode-glm) and picks the highest-scoring
-     * passing patch. Default 1.
-     */
-    variants?: number;
-    /** Validator + prompt overrides the agent knows for this repo. */
-    config?: DelegateCodeConfig;
-    /** Multi-tenant scope (customer-id, workspace-id). */
-    namespace?: string;
-}
-/** @experimental */
-interface DelegateCodeResult {
-    taskId: string;
-    /** Best-effort hint — coder loops can take minutes-to-hours. */
-    estimatedDurationMs?: number;
-}
-/** @experimental */
-type ResearchSource = 'web' | 'corpus' | 'twitter' | 'github' | 'docs';
-/** @experimental */
-interface DelegateResearchConfig {
-    recencyWindow?: {
-        since?: string;
-        until?: string;
-    };
-    maxItems?: number;
-    minConfidence?: number;
-}
-/** @experimental */
-interface DelegateResearchArgs {
-    question: string;
-    namespace: string;
-    scope?: string;
-    sources?: ResearchSource[];
-    variants?: number;
-    config?: DelegateResearchConfig;
-}
-/** @experimental */
-interface DelegateResearchResult {
-    taskId: string;
-    estimatedDurationMs?: number;
-}
-/** @experimental */
-interface FeedbackRefersTo {
-    kind: 'delegation' | 'artifact' | 'outcome';
-    /** For `'delegation'`, this is the taskId. */
-    ref: string;
-}
-/** @experimental */
-interface FeedbackRating {
-    /** [0, 1]. */
-    score: number;
-    label?: 'good' | 'bad' | 'neutral' | 'mixed';
-    notes: string;
-}
-/** @experimental */
-interface DelegateFeedbackArgs {
-    refersTo: FeedbackRefersTo;
-    rating: FeedbackRating;
-    by: 'agent' | 'user' | 'downstream-judge';
-    /** ISO timestamp; defaults to server clock when omitted. */
-    capturedAt?: string;
-    namespace?: string;
-}
-/** @experimental */
-interface DelegateFeedbackResult {
-    recorded: true;
-    id: string;
-}
-/** @experimental */
-interface DelegationStatusArgs {
-    taskId: string;
-    /**
-     * Return the delegation's compact loop-trace span tree alongside the
-     * status. Default false — status polls stay light; opt in when you need
-     * the topology (which iterations ran, where they were placed, what each
-     * cost) rather than just the state machine.
-     */
-    includeTrace?: boolean;
-}
-/** @experimental */
-interface DelegationProgress {
-    iteration: number;
-    phase: string;
-}
-/** @experimental */
-interface DelegationError {
-    message: string;
-    kind: string;
-}
-/**
- * Polymorphic `result` field: `CoderOutput` when the underlying profile
- * is `'coder'`, a structurally-typed research output when `'researcher'`.
- * The MCP wire carries it as JSON either way.
- *
- * @experimental
- */
-type DelegationResultPayload = {
-    profile: 'coder';
-    output: CoderOutput;
-} | {
-    profile: 'researcher';
-    output: ResearchOutputShape;
-} | {
-    profile: 'ui-auditor';
-    output: UiAuditorDelegationOutput;
-};
-/**
- * Wire-shape of a completed UI-audit delegation. The `findings` array
- * contains every finding persisted to the workspace during the run,
- * already enriched with `id` and `createdAt` by the writer. `workspaceDir`
- * is the absolute path to the workspace; `indexFile` is the workspace-
- * relative path to the regenerated index.md.
- *
- * @experimental
- */
-interface UiAuditorDelegationOutput {
-    workspaceDir: string;
-    indexFile: string;
-    findings: UiFinding[];
-    /** Total iterations the loop ran for this delegation. */
-    iterations: number;
-}
-/** @experimental */
-type UiAuditLensFilter = readonly UiLens[];
-/** Optional per-route capture spec the agent surfaces over the wire. */
-interface DelegateUiAuditRoute {
-    /** Stable route name (used in screenshot filenames + finding metadata). */
-    name: string;
-    /** Fully-qualified URL. */
-    url: string;
-    /** Viewports to capture at. Defaults to `[{ width: 1280, height: 800 }]`. */
-    viewports?: readonly {
-        width: number;
-        height: number;
-    }[];
-    /** Default false. Full-page captures for the broad lenses. */
-    fullPage?: boolean;
-    /** Selector to wait for before capture. */
-    waitFor?: string;
-}
-/** @experimental */
-interface DelegateUiAuditConfig {
-    /**
-     * Lenses to iterate. Default: every lens except `'other'`. Order is
-     * preserved — the driver iterates lens-by-lens.
-     */
-    lenses?: UiAuditLensFilter;
-    /** Maximum total iterations across all (lens × route) pairs. Default 33 (11 lenses × 3 routes). */
-    maxIterations?: number;
-    /** Maximum concurrent iterations within a single plan() round. Default 2. */
-    maxConcurrency?: number;
-    /** Free-form product context surfaced to the judge. */
-    productContext?: string;
-}
-/** @experimental */
-interface DelegateUiAuditArgs {
-    /** Workspace root for the audit (absolute path). */
-    workspaceDir: string;
-    /** Routes to audit. Must be non-empty. */
-    routes: readonly DelegateUiAuditRoute[];
-    /** Multi-tenant scope. */
-    namespace?: string;
-    config?: DelegateUiAuditConfig;
-}
-/** @experimental */
-interface DelegateUiAuditResult {
-    taskId: string;
-    estimatedDurationMs?: number;
-}
-/**
- * Provider-neutral research output carried over the MCP boundary. The MCP
- * layer accepts this structural shape instead of coupling its wire contract to
- * one research implementation.
- *
- * @experimental
- */
-interface ResearchOutputShape {
-    items: unknown[];
-    citations: unknown[];
-    proposedWrites: unknown[];
-    gaps?: string[];
-    notes?: string;
-    [key: string]: unknown;
-}
-/** @experimental */
-interface DelegationStatusResult {
-    taskId: string;
-    profile: DelegationProfile;
-    status: DelegationStatus;
-    progress?: DelegationProgress;
-    result?: DelegationResultPayload;
-    error?: DelegationError;
-    costUsd?: number;
-    startedAt: string;
-    completedAt?: string;
-    /** Compact loop-trace span tree; present only when `includeTrace: true` was passed and spans were recorded. */
-    trace?: DelegationTraceSpan[];
-    /** Present when oldest trace spans were dropped to honor the trace caps. */
-    traceTruncated?: true;
-    /** Inherited trace identity recorded at submit — join key into the caller's trace. */
-    traceId?: string;
-    /** Caller span that dispatched the delegation, when one was inherited. */
-    parentSpanId?: string;
-}
-/** @experimental */
-interface DelegationHistoryArgs {
-    namespace?: string;
-    profile?: DelegationProfile;
-    /** ISO date — only delegations started at-or-after `since` are returned. */
-    since?: string;
-    /** Default 50. Hard cap 500. */
-    limit?: number;
-}
-/** @experimental */
-interface DelegationFeedbackSnapshot {
-    id: string;
-    score: number;
-    label?: FeedbackRating['label'];
-    by: DelegateFeedbackArgs['by'];
-    notes: string;
-    capturedAt: string;
-}
-/** @experimental */
-interface DelegationHistoryEntry {
-    taskId: string;
-    profile: DelegationProfile;
-    namespace?: string;
-    args: DelegateCodeArgs | DelegateResearchArgs | DelegateUiAuditArgs;
-    status: DelegationStatus;
-    feedback?: DelegationFeedbackSnapshot[];
-    costUsd?: number;
-    startedAt: string;
-    completedAt?: string;
-    /**
-     * True when the record carries a journaled loop trace. History stays
-     * light by design — fetch the spans via
-     * `delegation_status { taskId, includeTrace: true }`.
-     */
-    hasTrace: boolean;
-    /** Inherited trace identity recorded at submit — join key into the caller's trace. */
-    traceId?: string;
-}
-/** @experimental */
-interface DelegationHistoryResult {
-    delegations: DelegationHistoryEntry[];
-}
-
-/**
- *
- * State machine for async MCP delegations:
- *
- *   pending → running → completed | failed
- *           ↘ cancelled (from any non-terminal state via cancel())
- *
- * Each `submit` returns a `taskId` immediately and kicks the work off in the
- * background. The work function receives an `AbortSignal` the queue fires
- * when `cancel(taskId)` is called. The queue does NOT supervise runtime
- * timeouts — the underlying `runAgentRounds` driver / sandbox imposes those.
- *
- * Idempotency: callers may supply an `idempotencyKey` (hash of the input).
- * A duplicate `submit` with a known key returns the existing task instead of
- * starting a new one. Mutated input → different key → different task.
- *
- * Durability: the working set lives in memory (reads stay synchronous) and
- * every record mutation is journaled through a `DelegationStore`. The default
- * `InMemoryDelegationStore` keeps today's semantics — a process restart drops
- * all state. Construct via `DelegationTaskQueue.restore({ store })` with a
- * `FileDelegationStore` to reload prior records on startup: terminal records
- * stay queryable, in-flight records either re-attach through the
- * `resumeDelegate` seam (when they carry a `detachedSessionRef`) or fail
- * loud with a driver-restart error so `delegation_status` tells the truth.
- *
- * @experimental
- */
-
-type AnyDelegateArgs = DelegateCodeArgs | DelegateResearchArgs | DelegateUiAuditArgs;
-/**
- * Must be JSON-safe end to end (`args`, `result`, `error`, `feedback`) —
- * persistent stores round-trip records through `JSON.stringify`.
- *
- * @experimental
- */
-interface DelegationRecord {
-    taskId: string;
-    profile: DelegationProfile;
-    namespace?: string;
-    args: AnyDelegateArgs;
-    status: DelegationStatus;
-    progress?: DelegationProgress;
-    result?: DelegationResultPayload;
-    error?: DelegationError;
-    costUsd?: number;
-    startedAt: string;
-    completedAt?: string;
-    /** Sha-prefix hash of the canonical input — used for idempotency lookup. */
-    idempotencyKey?: string;
-    /**
-     * Caller-generated deterministic id of a detached run (e.g. the sandbox
-     * session id a single-tick driver resumes by). Presence is what makes a
-     * restored in-flight record resumable via `resumeDelegate`; without it a
-     * restart settles the record as failed.
-     */
-    detachedSessionRef?: string;
-    /** Feedback events keyed by this delegation's taskId. */
-    feedback: DelegationFeedbackSnapshot[];
-    /**
-     * Compact loop-trace span tree teed from the delegation's run, oldest
-     * spans first. Appended when a delegated loop reaches `loop.ended` and
-     * settled (partial buffers included) at the terminal transition. Capped
-     * via `capDelegationTrace` — see `traceTruncated`.
-     */
-    trace?: DelegationTraceSpan[];
-    /** Present when oldest trace spans were dropped to honor the trace caps. */
-    traceTruncated?: true;
-    /**
-     * Inherited trace identity (the queue's `traceContext` at submit time —
-     * typically `readTraceContextFromEnv()`), distinct from the span payload:
-     * a journal consumer joins records into the parent trace by these ids
-     * without parsing spans. Restored records keep their persisted identity.
-     */
-    traceId?: string;
-    /** Caller span that dispatched the delegation, when one was inherited. */
-    parentSpanId?: string;
-}
-/** @experimental */
-interface SubmitInput<Args extends AnyDelegateArgs> {
-    profile: DelegationProfile;
-    args: Args;
-    namespace?: string;
-    idempotencyKey?: string;
-    /**
-     * Records the detached-run resume key on the new record. The submitted
-     * `run` function still executes in-process exactly as without it — the
-     * ref only matters after a restart, when `DelegationTaskQueue.restore`
-     * hands it to the `resumeDelegate` seam instead of failing the record.
-     */
-    detachedSessionRef?: string;
-    /**
-     * Runs the underlying delegation. The queue passes a fresh `AbortSignal`
-     * and a `report` channel for incremental progress updates. The function
-     * MUST resolve with the typed `DelegationResultPayload['output']`; the
-     * queue wraps it with the profile tag.
-     */
-    run: (ctx: DelegationRunContext) => Promise<DelegationResultPayload['output']>;
-}
-/** @experimental Context handed to a `SubmitInput.run` function. */
-interface DelegationRunContext {
-    signal: AbortSignal;
-    report(progress: DelegationProgress): void;
-    /** The `detachedSessionRef` recorded at submit, when one was supplied. */
-    detachedSessionRef?: string;
-    /**
-     * Replace the record's detached-run resume key — the detached dispatch path
-     * calls this once the sandbox id is known so the persisted ref names a
-     * resolvable box. Ignored after the record settles (a cancel racing the
-     * rebind is legitimate; the ref no longer matters then). Throws on an empty
-     * ref — erasing the resume key would silently make the record unresumable.
-     */
-    updateDetachedSessionRef(ref: string): void;
-    /**
-     * Per-delegation loop-trace sink, always provided by the queue. Events
-     * emitted here are journaled onto the record as a compact span tree
-     * (`record.trace`) when each loop run ends and at the delegation's
-     * terminal transition. Delegates forward it into their `runAgentRounds` ctx,
-     * composed with any process-wide OTEL emitter
-     * (`composeLoopTraceEmitters`). Optional in the type so consumer-built
-     * contexts stay source-compatible.
-     */
-    traceEmitter?: LoopTraceEmitter;
-}
-/** @experimental */
-interface SubmitOutput {
-    taskId: string;
-    /** True when a prior matching `idempotencyKey` returned an existing record. */
-    reused: boolean;
-}
-/**
- * One observation of a detached run, mapped 1:1 from a single-tick driver
- * (e.g. the sandbox SDK's `driveTurn`, which reports
- * completed | running | failed per pass). `running` schedules another tick
- * after `intervalMs`; `completed` / `failed` settle the record.
- *
- * @experimental
- */
-type DelegationResumeTick = {
-    state: 'running';
-} | {
-    state: 'completed';
-    output: DelegationResultPayload['output'];
-    costUsd?: number;
-} | {
-    state: 'failed';
-    error: DelegationError;
-};
-/** @experimental */
-interface DelegationResumeContext {
-    /** Fired by `cancel(taskId)`; the driver should stop the remote run when it can. */
-    signal: AbortSignal;
-    report(progress: DelegationProgress): void;
-}
-/**
- * Re-attaches restored in-flight records to their detached runs. The queue
- * calls `tick` repeatedly — it never awaits a whole run — so the driver can
- * be a thin wrapper over a one-pass primitive: resolve the run named by
- * `detachedSessionRef`, advance/poll it once, report where it stands. A
- * thrown error settles the record as failed; `failed` ticks are treated as
- * terminal and are not retried.
- *
- * @experimental
- */
-interface DelegationResumeDriver {
-    tick(task: {
-        record: DelegationRecord;
-        detachedSessionRef: string;
-    }, ctx: DelegationResumeContext): Promise<DelegationResumeTick>;
-    /** Delay between `running` ticks, in milliseconds. Default 5000. */
-    intervalMs?: number;
-}
-/** @experimental */
-interface DelegationTaskQueueOptions {
-    /** ID generator override; default `randomTaskId`. */
-    generateId?: () => string;
-    /** Clock override; default `() => new Date().toISOString()`. */
-    now?: () => string;
-    /**
-     * Journal for record mutations and the `restore()` load source. Default
-     * `InMemoryDelegationStore` — observably identical to an unjournaled
-     * queue. Pass a `FileDelegationStore` through
-     * `DelegationTaskQueue.restore` for state that survives a restart;
-     * constructing with `new` never loads prior state.
-     */
-    store?: DelegationStore;
-    /** Resume seam for restored in-flight records that carry a `detachedSessionRef`. */
-    resumeDelegate?: DelegationResumeDriver;
-    /**
-     * Maximum number of terminal (completed | failed | cancelled) records
-     * retained; the oldest (by `completedAt`) are evicted from memory and
-     * store once the cap is exceeded. Default unbounded.
-     */
-    maxTerminalRecords?: number;
-    /**
-     * Observes the first store failure. After it fires, the queue refuses
-     * new submissions and `flush()` rejects with the same error. Default:
-     * rethrow on a microtask — an unhandled crash — because silently
-     * degrading durable mode to memory-only would lie to the caller.
-     */
-    onPersistError?: (error: DelegationPersistenceError) => void;
-    /**
-     * Inherited trace identity stamped on every submitted record
-     * (`traceId` / `parentSpanId`). The bin passes
-     * `readTraceContextFromEnv()` so journal consumers can join delegation
-     * records into the caller's trace. Restored records keep the identity
-     * they were persisted with.
-     */
-    traceContext?: TraceContext;
-}
-/** In-process queue for async delegation tasks — submit, cancel, poll status, and read history. @experimental */
-declare class DelegationTaskQueue {
-    private readonly records;
-    private readonly controllers;
-    private readonly byIdempotencyKey;
-    private readonly generateId;
-    private readonly now;
-    private readonly store;
-    private readonly resumeDelegate?;
-    private readonly maxTerminalRecords;
-    private readonly onPersistError;
-    private readonly traceContext;
-    private persistTail;
-    private persistFailure;
-    constructor(options?: DelegationTaskQueueOptions);
-    /**
-     * Construct a queue from previously-persisted state. Loads every record
-     * from `options.store`, rebuilds the idempotency index (so a re-submitted
-     * identical task returns the prior taskId and its terminal state), then:
-     *
-     *   - terminal records stay queryable via `status()` / `history()`
-     *   - in-flight records with a `detachedSessionRef` re-attach through
-     *     `options.resumeDelegate` and report `running`
-     *   - other in-flight records settle as failed — their driver died with
-     *     the previous process and the result is unrecoverable
-     *
-     * The retention cap applies to the loaded set as well.
-     */
-    static restore(options?: DelegationTaskQueueOptions): Promise<DelegationTaskQueue>;
-    /**
-     * Kick off a delegation in the background. Returns immediately. The
-     * `taskId` is queryable via `status` once this method returns. Throws
-     * the recorded `DelegationPersistenceError` once the store has failed —
-     * the queue does not accept work it cannot journal.
-     */
-    submit<Args extends AnyDelegateArgs>(input: SubmitInput<Args>): SubmitOutput;
-    /**
-     * Snapshot the current state of a delegation. Returns `undefined` for
-     * unknown ids so callers can distinguish missing from terminal.
-     * `includeTrace` attaches the journaled loop-trace span tree — off by
-     * default so status polls stay light.
-     */
-    status(taskId: string, opts?: {
-        includeTrace?: boolean;
-    }): DelegationStatusResult | undefined;
-    /**
-     * Abort an in-flight delegation. Returns `false` if the task is unknown
-     * or already terminal. The underlying `run` function MUST honor the
-     * abort signal for the cancel to take effect; the queue marks the
-     * record `cancelled` regardless so a misbehaving runner cannot pin the
-     * UI on `running` forever.
-     */
-    cancel(taskId: string): boolean;
-    /**
-     * Append a feedback event to the matching delegation. Returns `false`
-     * when `ref` does not name a known taskId — the caller should still
-     * record the feedback through a different surface (artifact/outcome
-     * kinds are not queue-bound).
-     */
-    attachFeedback(taskId: string, snapshot: DelegationFeedbackSnapshot): boolean;
-    /**
-     * Query the recorded delegations. Returns entries newest-first (by
-     * `startedAt`), truncated to `limit`.
-     */
-    history(args?: DelegationHistoryArgs): DelegationHistoryEntry[];
-    /**
-     * Await every journal write issued so far. Rejects with the recorded
-     * `DelegationPersistenceError` when any of them failed. Call before
-     * handing the store's backing file to another process.
-     */
-    flush(): Promise<void>;
-    /** Test-only — number of in-flight (non-terminal) records. */
-    inflightCount(): number;
-    private execute;
-    private appendTrace;
-    private rehydrate;
-    private startResume;
-    private driveResume;
-    /**
-     * Journal the resumed segment of a detached run as one compact span. The
-     * resume driver re-attaches after a process restart, so the original
-     * process's loop events are gone — this span records the post-restart
-     * observation window (re-attach → terminal tick) under the
-     * `'detached-resume'` driver tag, keeping restored delegations observable
-     * in the journal alongside trace-carrying live runs.
-     */
-    private appendResumeSpan;
-    private persist;
-    private persistRemoval;
-    private failPersistence;
-    private enforceRetention;
-}
-/**
- * Best-effort stable hash for use as `idempotencyKey`. Not cryptographic;
- * collisions only affect dedupe, never correctness.
- *
- * @experimental
- */
-declare function hashIdempotencyInput(value: unknown): string;
-
-/**
- *
- * Detached delegation turns over the sandbox SDK's `driveTurn` primitive.
- *
- * Two halves of one story:
- *
- *   - {@link runDetachedTurn} — the dispatch side. A single-session delegate
- *     (single-variant coder / researcher) acquires a box, binds the sandbox id
- *     into the record's `detachedSessionRef`, then advances the turn with
- *     repeated `driveTurn` ticks instead of holding a live SSE stream. The
- *     session id is deterministic and supplied at submit time, so a process
- *     crash between ticks loses nothing — the turn keeps running in the box.
- *
- *   - {@link createDetachedTurnResumeDriver} — the resume side. A
- *     `DelegationResumeDriver` that re-attaches restored in-flight records to
- *     their detached runs: parse the record's ref, resolve the box, advance the
- *     turn one `driveTurn` pass per `tick()`, and map the SDK's three states
- *     (`completed | running | failed`) onto `DelegationResumeTick`.
- *
- * Both sides type the box structurally ({@link DriveTurnCapableBox}) so tests
- * inject fakes and the module never requires the sandbox SDK at runtime — the
- * SDK stays an optional peer, exactly like the executors' `SandboxClient` seam.
- *
- * Tradeoffs of detached mode (why it is opt-in, not the default): a detached
- * turn yields one terminal payload instead of a live event stream, so kernel
- * token/cost aggregation is not produced for that turn. The trace sinks still
- * observe detached work — `runDetachedTurn` synthesizes a single-iteration
- * loop event stream (see `RunDetachedTurnOptions.traceEmitter`) so the span
- * topology joins the inherited trace context, with cost/tokens reported as 0
- * under the `'detached-turn'` driver tag. Multi-variant fanout stays on the
- * streaming `runAgentRounds` path — N concurrent sessions cannot be expressed as one
- * resume key, and winner selection needs every candidate.
- *
- * @experimental
- */
-
-/**
- * Structural mirror of the sandbox SDK's `TurnDriveResult` (>= 0.6).
- * Discriminated on `state`; `failed` is terminal and deterministic per the
- * SDK contract — re-invoking with the same ids returns the same outcome.
- *
- * @experimental
- */
-type DriveTurnTick = {
-    state: 'completed';
-    text: string;
-    result: Record<string, unknown>;
-} | {
-    state: 'running';
-    startedAt?: Date;
-    elapsedMs?: number;
-} | {
-    state: 'failed';
-    error: string;
-};
-/**
- * The box surface detached turns need. `SandboxInstance`
- * (`@tangle-network/sandbox` >= 0.6) satisfies it structurally; tests pass
- * in-memory fakes. `_sessionCancel` is the SDK's remote-cancellation surface —
- * optional here because older SDKs / fakes may not expose it; when present it
- * is invoked on abort so the remote run actually stops.
- *
- * @experimental
- */
-interface DriveTurnCapableBox {
-    driveTurn(message: string, opts: {
-        sessionId: string;
-        turnId?: string;
-        wallCapMs?: number;
-    }): Promise<DriveTurnTick>;
-    _sessionCancel?(id: string): Promise<void>;
-}
-/**
- * Decoded `DelegationRecord.detachedSessionRef`. `sandboxId` is absent between
- * submit and box acquisition — a record restored in that window is not
- * resumable (there is no box to resume on) and the resume driver fails it
- * loud rather than dispatching onto a guessed box.
- *
- * @experimental
- */
-interface DetachedSessionRefParts {
-    sessionId: string;
-    sandboxId?: string;
-}
-/**
- * Encode ref parts into the JSON-safe string stored on the record:
- * `session=<id>` before the box exists, `sandbox=<id>;session=<id>` once
- * bound. Ids must not contain the `;`/`=` delimiters.
- *
- * @experimental
- */
-declare function formatDetachedSessionRef(parts: DetachedSessionRefParts): string;
-/** Parse a `detachedSessionRef` string back to parts; throws `ValidationError` on malformed input. @experimental */
-declare function parseDetachedSessionRef(raw: string): DetachedSessionRefParts;
-/** @experimental The terminal payload of a finished detached turn. */
-interface DetachedTurn {
-    /** Final assistant text. */
-    text: string;
-    /** The SDK's cached AgentExecutionResult-shape record for the turn. */
-    result: Record<string, unknown>;
-}
-/**
- * Synthesize the terminal event array a detached turn settles through. Shaped
- * so the existing event-stream output adapters (coder, researcher) parse it:
- * `data.result` for adapters that read a structured terminal record, `data.text`
- * for adapters that scan assistant text for the fenced result block.
- *
- * @experimental
- */
-declare function detachedTurnEvents(sessionId: string, turn: DetachedTurn): SandboxEvent[];
-/** @experimental */
-interface RunDetachedTurnOptions {
-    /** Sandbox client used to acquire the box (the delegate's executor client). */
-    client: SandboxClient;
-    /** Profile + overrides for box acquisition — same spec the streaming path uses. */
-    spec: AgentRunSpec<unknown>;
-    /** The full turn prompt; consumed by `driveTurn`'s dispatch leg. */
-    prompt: string;
-    /** Deterministic resume key, minted at submit time (`parseDetachedSessionRef(ref).sessionId`). */
-    sessionId: string;
-    /**
-     * Called once the box exists, with its sandbox id. Callers persist
-     * `formatDetachedSessionRef({ sandboxId, sessionId })` onto the record here so
-     * a restart can resolve the box again.
-     */
-    bindSandbox(sandboxId: string): void;
-    signal: AbortSignal;
-    report(progress: DelegationProgress): void;
-    /** Delay between `running` ticks (ms). Default 5000. */
-    tickIntervalMs?: number;
-    /** Wall-clock cap forwarded to `driveTurn` — the SDK cancels and fails a session past it. */
-    wallCapMs?: number;
-    /**
-     * Loop-trace sink. When set, the detached turn synthesizes a
-     * single-iteration loop span tree (`runId` = `sessionId`, driver
-     * `'detached-turn'`) so trace-context inheritance survives the detached
-     * path — the same events the streaming `runAgentRounds` path would emit, minus
-     * per-token telemetry: `driveTurn` yields one terminal payload, so token
-     * and cost figures are structurally unavailable and reported as 0 under
-     * this driver tag.
-     */
-    traceEmitter?: LoopTraceEmitter;
-    /** Physical placement stamped on the synthesized dispatch event. Default `'sibling'`. */
-    placement?: 'sibling' | 'fleet';
-}
-/**
- * Dispatch one detached turn and advance it to a terminal state with
- * `driveTurn` ticks. The first tick dispatches (idempotent on `sessionId`);
- * subsequent ticks poll. On abort the remote session is cancelled via
- * `_sessionCancel` when the box exposes it. The box is torn down on every
- * in-process exit path (success, failure, abort) — only a process death skips
- * teardown, which is exactly the case the resume driver re-attaches to.
- *
- * @experimental
- */
-declare function runDetachedTurn(options: RunDetachedTurnOptions): Promise<DetachedTurn>;
-/** @experimental */
-interface DetachedTurnResumeDriverOptions {
-    /**
-     * Resolve the live box owning a detached session. The bin wires this to the
-     * sandbox client's `get(sandboxId)`; throw when the box no longer exists —
-     * a thrown tick settles the record as failed, which is the truth.
-     */
-    resolveSandbox(sandboxId: string): Promise<DriveTurnCapableBox>;
-    /**
-     * Rebuild the turn prompt from the persisted record. Only consumed by
-     * `driveTurn`'s dispatch leg — i.e. when the previous process died after
-     * binding the box but before the session was dispatched. Must reproduce the
-     * prompt the delegate would have sent.
-     */
-    buildMessage(record: DelegationRecord): string;
-    /**
-     * Map a completed turn onto the delegation's typed output payload (parse +
-     * validate per profile). Throw when the resumed result does not pass the
-     * profile's gate — the queue settles the record as failed with that error.
-     */
-    settleOutput(turn: DetachedTurn, record: DelegationRecord, ctx: {
-        signal: AbortSignal;
-    }): Promise<DelegationResultPayload['output']> | DelegationResultPayload['output'];
-    /** Delay between `running` ticks (ms). Default 5000. */
-    intervalMs?: number;
-    /** Wall-clock cap forwarded to `driveTurn` on every tick. */
-    wallCapMs?: number;
-}
-/**
- * Build the `driveTurn`-backed {@link DelegationResumeDriver}. Each `tick()`
- * is one settle/poll/dispatch pass:
- *
- *   - ref without a sandbox binding → `failed` (`DetachedSessionUnboundError`):
- *     the previous process died before a box existed; there is nothing to resume.
- *   - `driveTurn` `completed` → `settleOutput` → `completed` tick.
- *   - `running` → progress via `ctx.report`, `running` tick (queue re-ticks
- *     after `intervalMs`).
- *   - `failed` → `failed` tick (`DetachedTurnFailedError`) — terminal per the
- *     SDK's deterministic-failure contract.
- *
- * Abort: the queue stops ticking once `cancel()` flips the record, so remote
- * cancellation is hooked onto `ctx.signal` (once per task) and fires
- * `_sessionCancel` when the SDK surface exposes it. The driver never deletes
- * boxes — it cannot know whether `sandboxId` is a disposable sibling or a
- * fleet machine, and destroying a fleet machine would be unrecoverable.
- *
- * @experimental
- */
-declare function createDetachedTurnResumeDriver(options: DetachedTurnResumeDriverOptions): DelegationResumeDriver;
-
-/**
- *
- * Delegation executors — the layer between MCP delegates and the sandbox
- * substrate. Each executor exposes a {@link SandboxClient} the kernel
- * consumes plus a placement tag so the trace pipeline can correlate workers
- * with their physical placement.
- *
- * Two implementations ship in-box:
- *
- * - {@link createSiblingSandboxExecutor} — every delegation spawns a fresh
- *   sandbox sibling to the caller. Default when the MCP server runs as a
- *   standalone CLI mounted outside a fleet.
- *
- * - {@link createFleetWorkspaceExecutor} — delegations dispatch onto machines
- *   in the caller's existing fleet so worker diffs land directly on the
- *   caller's filesystem (the fleet's shared workspace). Selected when the
- *   parent sandbox passes `TANGLE_FLEET_ID` into the MCP server's env.
- *
- * @experimental
- */
-
-/** @experimental */
-interface DelegationExecutor {
-    /** Sandbox client the kernel calls. Returned with `describePlacement` set. */
-    readonly client: SandboxClient;
-    /** Best-effort one-liner used in stderr boot logs and diagnostics. */
-    describe(): string;
-    /**
-     * Where delegated work physically runs. `sibling` and `fleet` placements are
-     * session-backed (boxes expose `driveTurn`, so detached dispatch + resume
-     * apply); `in-process` spawns local harness CLIs with no sandbox session to
-     * detach. Optional so consumer-implemented executors stay source-compatible;
-     * absent means "unknown" and detached dispatch is not enabled for it.
-     */
-    readonly placement?: 'sibling' | 'fleet' | 'in-process';
-}
-/** @experimental */
-interface SiblingSandboxExecutorOptions {
-    client: SandboxClient;
-}
-/**
- * Wrap a raw sandbox SDK client so the kernel emits
- * `loop.iteration.dispatch` events with `{ placement: 'sibling', sandboxId }`.
- *
- * The returned client `.create()` delegates to the underlying client; the
- * only added behavior is a `describePlacement` tag the kernel reads.
- *
- * @experimental
- */
-declare function createSiblingSandboxExecutor(options: SiblingSandboxExecutorOptions): DelegationExecutor;
-/**
- * Minimal `SandboxFleet` surface the fleet executor calls. Declared
- * structurally so tests can pass an in-memory stub without instantiating the
- * sandbox SDK.
- *
- * @experimental
- */
-interface FleetHandle {
-    readonly fleetId: string;
-    /** Machine ids in dispatch-eligible order. The executor round-robins. */
-    readonly ids: ReadonlyArray<string>;
-    /** Resolve a machine id to its `SandboxInstance` — that machine is mounted
-     * on the fleet's shared workspace, so any diff the worker writes lands on
-     * every other fleet machine's filesystem too. */
-    sandbox(machineId: string): Promise<SandboxInstance>;
-}
-/** @experimental */
-interface FleetWorkspaceExecutorOptions {
-    fleet: FleetHandle;
-    /**
-     * Override the machine-selection policy. Default = round-robin across
-     * `fleet.ids`, skipping the optional `excludeMachineIds` set (typically the
-     * coordinator machine the MCP server is running on).
-     */
-    selectMachine?: (call: {
-        callIndex: number;
-        ids: ReadonlyArray<string>;
-    }) => string;
-    /**
-     * Machine ids to skip during default round-robin. Set to the caller's own
-     * machineId so workers don't compete with the orchestrator on the same VM.
-     */
-    excludeMachineIds?: ReadonlyArray<string>;
-}
-/**
- * Build an executor that resolves each delegated iteration to an existing
- * machine in `fleet`. The fleet's shared-workspace policy means the worker
- * machine sees the caller's filesystem — diffs land in-place with no
- * cross-sandbox copy step.
- *
- * @experimental
- */
-declare function createFleetWorkspaceExecutor(options: FleetWorkspaceExecutorOptions): DelegationExecutor;
-
-/**
- *
- * `detachedSessionDelegate` — the sandbox-session coder delegate: a closure that drives `runAgentRounds`
- * against a `SandboxClient` + a caller-supplied (or minimal model-only default) worker profile, to a
- * mechanically-validated `CoderOutput`. The caller invokes the returned delegate directly with its
- * coder args; when wired into a durable queue it also settles cross-restart-resumed records.
- *
- * Delegation vs COORDINATION (`../runtime/supervise/coordination-mcp.ts`): this delegate runs a
- * coding task INSIDE the agent's OWN sandbox environment — a sibling box on its own `SandboxClient`,
- * fresh branch on its repo. It is NOT backend-pluggable. To instead SPAWN + live-drive workers in a
- * CHOSEN backend (sandbox OR cli-bridge, via `createExecutor({ backend })`) with observe/steer/resume
- * + recursion, use `delegate()` / the coordination MCP.
- *
- * The worker profile is a parameter the caller supplies (§1.5: the system authors profiles). When
- * none is passed, a minimal model-only default profile is materialized in `./detached-coder` — no
- * hardcoded skills or tools. For NEW local-repo coding use `worktreeFanout` / `worktreeLoopRunner`
- * (author one `AgentProfile` per harness → `createWorktreeCliExecutor` leaves → `gateOnDeliverable`).
- *
- * @experimental
- */
-
-/** @experimental */
-interface DelegateRunCtx {
-    signal: AbortSignal;
-    report(progress: DelegationProgress): void;
-    /**
-     * Detached-run resume key recorded on the queue record at submit time
-     * (`formatDetachedSessionRef`). Present only when the submit path requested
-     * detached dispatch — its presence is what routes a session-backed delegate
-     * onto the `driveTurn` tick path instead of holding a stream.
-     */
-    detachedSessionRef?: string;
-    /** Rebind the record's resume key (e.g. once the sandbox id is known). */
-    updateDetachedSessionRef?(ref: string): void;
-    /**
-     * Per-delegation trace sink supplied by the queue — loop events emitted
-     * here land on the delegation record as a compact span tree. Delegates
-     * compose it with their configured OTEL emitter so both sinks observe
-     * the same stream.
-     */
-    traceEmitter?: LoopTraceEmitter;
-}
-/** @experimental The coder delegate closure — given the coder args + run context, drives the
- *  sandbox-session coder path to a validated `CoderOutput`. `detachedSessionDelegate` is the
- *  built-in implementation; the queue invokes one of these per coder delegation. */
-type CoderDelegate = (args: DelegateCodeArgs, ctx: DelegateRunCtx) => Promise<CoderOutput>;
-/**
- * UI-auditor delegate — fully consumer-injected. agent-runtime ships no
- * default factory because the inputs are workspace path + judge function
- * + (optionally) a `SandboxClient`, and the judge is the consumer's
- * model seam. See `createInProcessUiAuditClient` + `uiAuditorProfile` in
- * `@tangle-network/agent-runtime/profiles` for the canonical wiring.
- *
- * @experimental
- */
-type UiAuditorDelegate = (args: DelegateUiAuditArgs, ctx: DelegateRunCtx) => Promise<UiAuditorDelegationOutput>;
-/** @experimental Structured review verdict over a coder candidate. */
-interface CoderReview {
-    /** Gate: only approved candidates are eligible to win. */
-    approved: boolean;
-    /** Reviewer's recommendation — surfaced in traces. */
-    recommendation: 'ship' | 'approve-with-nits' | 'changes-requested' | 'reject';
-    /** Readiness 0..1, used by the `highest-readiness` winner-selection strategy. */
-    readiness: number;
-    notes?: string;
-}
-/**
- *
- * Optional adversarial reviewer over a coder candidate that already passed
- * mechanical validation (tests/typecheck/forbidden/diff/no-op/secrets). Folded
- * from the ai-trading-blueprint delegation MCP: a candidate is only eligible to
- * win if the reviewer approves it. The reviewer is the consumer's seam — an LLM
- * judge, a `pnpm review` command, anything returning a `CoderReview`.
- *
- * @experimental
- */
-type CoderReviewer = (output: CoderOutput, task: CoderTask, ctx: {
-    signal: AbortSignal;
-}) => Promise<CoderReview> | CoderReview;
-/**
- * @experimental Winner-selection strategy among validated (+ reviewed) candidates on the
- * sandbox-session path. The base strategies (`highest-score` / `smallest-diff` /
- * `first-approved`) delegate to the shared `selectValidWinner`; `highest-readiness` is the
- * reviewer-only strategy this path keeps that the generic selector does not express. Default
- * `highest-score`.
- */
-type DetachedWinnerSelection = 'highest-score' | 'smallest-diff' | 'highest-readiness' | 'first-approved';
-/** @experimental */
-interface DetachedSessionDelegateOptions {
-    /**
-     * Execution placement. Pass a {@link DelegationExecutor} (sibling or fleet)
-     * to control where worker iterations land. `sandboxClient` is a
-     * convenience shorthand that wraps the client in a sibling executor — pass
-     * one or the other, not both.
-     */
-    executor?: DelegationExecutor;
-    /**
-     * Convenience shorthand for sibling placement. Equivalent to
-     * `executor: createSiblingSandboxExecutor({ client: sandboxClient })`.
-     */
-    sandboxClient?: SandboxClient;
-    /**
-     * The worker's authored `AgentProfile` (§1.5: the system authors profiles). Spread onto the
-     * sandbox-session run spec → `runAgentRounds` → the executor's `harnessInvocation`, so the harness runs
-     * under the caller's stance. Omit to use a minimal model-only default (no hardcoded skills/tools);
-     * `harness` / `model` / `systemPrompt` below are convenience overrides layered onto whichever
-     * profile is used.
-     */
-    workerProfile?: AgentProfile$1;
-    /** Backend harness for the single-coder path (sets `metadata.backendType`). Default `claude-code`. */
-    harness?: string;
-    /** Model override for the single-coder path. */
-    model?: string;
-    /**
-     * The worker's authored system prompt (§1.5). Flows onto the run spec's
-     * `profile.prompt.systemPrompt` → through `runAgentRounds` → the executor's `harnessInvocation`, so the
-     * harness runs under this stance. Omit to keep the profile's own prompt.
-     */
-    systemPrompt?: string;
-    /** Default `['claude-code', 'codex', 'opencode/zai-coding-plan/glm-5.1']` when variants > 1. */
-    fanoutHarnesses?: string[];
-    /** Optional per-harness model override for `variants > 1`. */
-    fanoutModels?: (string | undefined)[];
-    /** Hard cap on the kernel's per-batch concurrency. Default 4. */
-    maxConcurrency?: number;
-    /**
-     * Optional adversarial reviewer. When set, a candidate must pass mechanical
-     * validation AND `reviewer.approved` to be eligible to win — empty/secret/
-     * test-failing patches are already gone; this catches the "compiles + passes
-     * but wrong/unsafe" class the deterministic validator can't see.
-     */
-    reviewer?: CoderReviewer;
-    /** Winner-selection strategy among eligible candidates. Default `highest-score`. */
-    winnerSelection?: DetachedWinnerSelection;
-    /**
-     * Loop trace emitter forwarded into every delegated `runAgentRounds`. Wire
-     * `createPropagatingTraceEmitter(readTraceContextFromEnv())` here (the bin
-     * does) so delegated build-loops export their topology spans to the OTLP /
-     * Tangle Intelligence sink when `OTEL_EXPORTER_OTLP_ENDPOINT` is set — and
-     * are a cheap no-op when it isn't. Configurable by construction.
-     *
-     * Detached single-variant turns (taken when `ctx.detachedSessionRef` is set)
-     * bypass `runAgentRounds`; `runDetachedTurn` synthesizes a single-iteration loop
-     * event stream for them so this emitter observes detached work too.
-     */
-    traceEmitter?: LoopTraceEmitter;
-    /** Tick cadence (ms) for the detached single-variant path. Default 5000. */
-    detachedTickIntervalMs?: number;
-    /** Wall-clock cap (ms) forwarded to `driveTurn` for detached turns. */
-    detachedWallCapMs?: number;
-}
-/**
- * Build the sandbox-session coder delegate. It drives `runAgentRounds` against the project's
- * sandbox client + coder profile; when `args.variants > 1` it switches to the multi-harness fanout
- * topology.
- *
- * This is the SANDBOX-SESSION coder path: workers run the in-box harness via the
- * `SandboxClient`'s `streamPrompt`, and single-variant turns can dispatch DETACHED
- * (driveTurn ticks) so a durable queue resumes them across an MCP restart — a substrate
- * the recursive worktree-CLI leaf does not yet have a journal-replay equivalent for.
- *
- * For NEW local-repo coding use `worktreeFanout` / `worktreeLoopRunner` (author an `AgentProfile`
- * per harness → `createWorktreeCliExecutor` leaves → `gateOnDeliverable`). This delegate runs
- * held-stream by default and only its OPTIONAL cross-restart resume (the `driveTurn` tick) is opt-in
- * behind `MCP_ENABLE_DETACHED_RESUME`.
- *
- * @experimental
- */
-declare function detachedSessionDelegate(options: DetachedSessionDelegateOptions): CoderDelegate;
-/**
- * Canonical `DelegateCodeArgs` → `CoderTask` mapping — the single source for
- * the delegate's live dispatch AND the resume driver's settle/message
- * rebuilding, so a resumed record reproduces exactly the task the original
- * process dispatched.
- *
- * @experimental
- */
-declare function coderTaskFromArgs(args: DelegateCodeArgs): CoderTask;
-/** @experimental */
-interface SettleDetachedCoderTurnOptions {
-    task: CoderTask;
-    /** Session id of the detached turn — used as the synthesized event id. */
-    sessionId: string;
-    signal: AbortSignal;
-    harness?: string;
-    model?: string;
-    /** Same gate as the streaming path: an unapproved candidate cannot win. */
-    reviewer?: CoderReviewer;
-}
-/**
- * Settle a completed detached coder turn through the same gate the streaming
- * path applies: parse the terminal payload with the coder output adapter,
- * run the mechanical validator (tests/typecheck/forbidden/diff/no-op/secrets),
- * then the optional reviewer. Throws when nothing survives — a resumed or
- * detached run must not return an unvalidated patch.
- *
- * SCOPE NOTE (detached/resume): the detached `driveTurn`-tick + cross-restart resume path is
- * bound to the `runAgentRounds` + sandbox-session substrate. The recursive `Scope`/worktree-CLI leaf has
- * journal→replay but no driveTurn-over-a-detached-sandbox-session equivalent yet, so resume is NOT
- * advertised on the generic `worktreeFanout` path. This helper (with `coderTaskFromArgs` and
- * `createDetachedTurnResumeDriver`) stays as the resume seam `bin.ts` wires for in-flight records.
- *
- * @experimental
- */
-declare function settleDetachedCoderTurn(turn: DetachedTurn, options: SettleDetachedCoderTurnOptions): Promise<CoderOutput>;
-
-/**
- *
- * Feedback persistence surface for the MCP layer.
- *
- * Feedback storage is product policy, so the MCP layer depends on this narrow
- * interface instead of choosing a knowledge store. The default implementation
- * is in-memory; consumers wire their own durable adapter 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
- */
-
-/** @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[]>;
-}
-/** In-memory `FeedbackStore` — suitable for single-process use and tests. @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;
-
-/**
- *
- * `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, so one verb covers code, research, and anything else.
- *
- * `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`), so the caller always learns what the delegation actually spent.
- *
- * The supervisor's substrate (its brain `router`, the worker `backend`, the completion `deliverable`)
- * is INJECTED at server construction — never an agent-supplied arg. The agent supplies only the
- * intent (+ an optional per-call `model` / `runId`).
- *
- * @experimental
- */
-
-/** MCP tool name for the `delegate` generic-delegation tool. @experimental */
-declare const DELEGATE_TOOL_NAME = "delegate";
-/** Human-readable description of the `delegate` MCP tool, injected into the tool manifest. @experimental */
-declare const DELEGATE_DESCRIPTION: string;
-/** JSON Schema for `delegate` tool arguments (`intent` + optional `model` and `runId`). @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;
-}
-/** Parse and validate raw MCP tool input into typed `DelegateArgs`; throws `TypeError` on bad input. @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>;
-
-/**
- *
- * Stdio JSON-RPC MCP server exposing the delegation tools to sandbox
- * coding-harness agents (claude-code, codex, opencode, ...): the generic
- * `delegate` verb plus the queue-bound `delegate_feedback`,
- * `delegation_status`, and `delegation_history`. `delegate_ui_audit` is served
- * when a `uiAuditorDelegate` is wired.
- *
- * The server is transport-bound but topology-free: tool execution is
- * delegated to handler functions composed from a queue, a feedback
- * store, and the wired run delegates. Consumers wire those at
- * construction time. The `agent-runtime-mcp` bin serves the generic
- * `delegate` verb over a real sandbox client when `MCP_ENABLE_DELEGATE=1`.
- *
- * 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
- */
-
-/** @experimental */
-interface McpServerOptions {
-    /**
-     * Required to enable `delegate` — the ONE generic delegation verb. 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_ui_audit. Wire one that closes over your
-     * `runAgentRounds` + `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;
-    /**
-     * 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;
-    };
-}
-/**
- * Stdio JSON-RPC MCP server exposing the delegation tools (`delegate`, `delegate_feedback`, `delegation_status`, `delegation_history`, optional `delegate_ui_audit`) to sandbox coding-harness agents.
- *
- * @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[]>;
-};
-
-/**
- *
- * 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.
- *
- * @experimental
- */
-
-/** 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;
-    /** Epoch ms the ledger recorded this settlement — the resolution a progress-based stop rule
-     *  needs to answer "how long since anything landed?" without inventing a timestamp at read
-     *  time. Stamped when the cursor yields the settlement, not when a reader first looks. */
-    readonly settledAt?: number;
-}
-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>;
-    /** Hard cap on how many workers may be LIVE (spawned but not yet settled) at once. `spawn_agent`
-     *  counts the scope's non-terminal nodes and fails closed (`error: 'max-live-workers'`) BEFORE
-     *  reserving from the pool when the cap is already met — a concurrency fence on top of the
-     *  conserved-budget fence (the pool bounds total work; this bounds simultaneous work, e.g. live
-     *  sandboxes/boxes). Omit or `<= 0` = no cap (the prior behavior; the pool stays the only fence). */
-    readonly maxLiveWorkers?: number;
-    /** Max wall-clock ms a single `await_event` call may block waiting on a live worker to settle
-     *  before it returns a non-error `{ pending: true, live }` snapshot and lets the caller re-poll.
-     *  The underlying `scope.next()` blocks for the WHOLE (multi-minute) worker run; over a remote MCP
-     *  transport that block outlives the client's per-request timeout, so an unbounded await surfaces
-     *  to the supervisor as a hard tool ERROR on every call — the exact failure that leaves it flying
-     *  blind. Bounding the wait converts that error into a re-pollable liveness signal. The background
-     *  drain keeps running, so a settlement that lands after the bound is published to the bus and
-     *  pulled by the next call — nothing is lost. Omit = {@link DEFAULT_AWAIT_EVENT_TIMEOUT_MS}; `<= 0`
-     *  restores the prior UNBOUNDED block (only safe for in-process drivers with no transport timeout). */
-    readonly awaitTimeoutMs?: number;
-    /**
-     * OPT-IN: run the ONLINE detector panel over each spawned worker's live tool trace and raise a
-     * `finding` on the bus the moment a detector fires — so the driver learns "this worker is
-     * looping" mid-run, from `await_event`, instead of at settle.
-     *
-     * This closes the `watchTrace` → `raiseFinding` wire whose own docstring already described it
-     * ("the seam an ONLINE detector uses to tell the driver 'this worker is looping/erroring' the
-     * moment it happens") but which nothing connected. Workers whose executor exposes no
-     * `traceSource` are simply not watched; nothing fails.
-     *
-     * Omit = no online watching (the settle-time analysts are unaffected).
-     */
-    readonly watchWorkers?: WorkerWatchOptions;
-    /**
-     * How long a worker may go without metered activity before `observe_agent` reports it as
-     * `stalled`. A derived read at observation time, never a background watchdog — nothing is
-     * killed or retried. Omit = the runtime default.
-     */
-    readonly stallAfterMs?: number;
-}
-/** Online-detector wiring for spawned workers (`CoordinationToolsOptions.watchWorkers`). */
-interface WorkerWatchOptions {
-    /** Detector panel; omit for the default stuck-loop + error-streak pair. */
-    readonly detectors?: WatchTraceOptions['detectors'];
-    /** Raise at most this many findings per worker, so one pathological worker cannot flood the
-     *  driver's inbox with the same signal every span. Default 3; `<= 0` = unlimited. */
-    readonly maxFindingsPerWorker?: number;
-}
-/**
- * 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>;
-    /**
-     * Post-loop drain: pull every ALREADY-settled, unpulled child into the ledger (publishing each
-     * as a `settled` bus event for the audit trail) WITHOUT awaiting live children. The driver
-     * calls this once its brain loop ends, so a delivered child the brain never awaited still
-     * reaches `finalizeBestDelivered` — a gate-verified delivery must never be lost to the
-     * driver's pull discipline. Analyst-on-settle hooks do NOT fire here (the driver has stopped;
-     * nobody is left to read a finding, and analysts spend real compute). Returns the count.
-     */
-    drainResolved(): Promise<number>;
-}
-/** Build the driver's MCP tools over a live scope. */
-declare function createCoordinationTools(opts: CoordinationToolsOptions): CoordinationTools;
-
-export { DelegationStateCorruptError as $, type AnalystRegistry as A, type DelegateResearchArgs as B, type CappedDelegationTrace as C, type DelegationExecutor as D, type ExecutorConfig as E, type FleetHandle as F, type DelegateResearchConfig as G, type DelegateResearchResult as H, type DelegateResult as I, type DelegateRunCtx as J, type DelegateUiAuditConfig as K, type DelegateUiAuditRoute as L, type MakeWorkerAgent as M, type DelegationError as N, type DelegationFeedbackSnapshot as O, type DelegationHistoryEntry as P, DelegationPersistenceError as Q, type DelegationProfile as R, type DelegationProgress as S, type DelegationRecord as T, type UiAuditorDelegate as U, type DelegationResultPayload as V, type WorkerWatchOptions as W, type DelegationResumeContext as X, type DelegationResumeDriver as Y, type DelegationResumeTick as Z, type DelegationRunContext as _, DelegationTaskQueue as a, traceContextToEnv as a$, type DelegationStatus as a0, type DelegationStore as a1, type DelegationTaskQueueOptions as a2, type DelegationTraceCaps as a3, type DelegationTraceCollector as a4, type DelegationTraceSpan as a5, type DetachedSessionDelegateOptions as a6, type DetachedSessionRefParts as a7, type DetachedTurn as a8, type DetachedTurnResumeDriverOptions as a9, type SiblingSandboxExecutorOptions as aA, type SubmitInput as aB, type SubmitOutput as aC, type TraceContext as aD, type UiAuditorDelegationOutput as aE, buildDelegationTraceSpans as aF, capDelegationTrace as aG, coderTaskFromArgs as aH, composeLoopTraceEmitters as aI, createCoordinationTools as aJ, createDelegateHandler as aK, createDelegationTraceCollector as aL, createDetachedTurnResumeDriver as aM, createFleetWorkspaceExecutor as aN, createInProcessTransport as aO, createMcpServer as aP, createPropagatingTraceEmitter as aQ, createSiblingSandboxExecutor as aR, detachedSessionDelegate as aS, detachedTurnEvents as aT, eventToSnapshot as aU, formatDetachedSessionRef as aV, hashIdempotencyInput as aW, parseDetachedSessionRef as aX, readTraceContextFromEnv as aY, runDetachedTurn as aZ, settleDetachedCoderTurn as a_, type DetachedWinnerSelection as aa, type DriveTurnCapableBox as ab, type DriveTurnTick as ac, type FeedbackEvent as ad, type FeedbackRating as ae, type FeedbackRefersTo as af, FileDelegationStore as ag, type FileDelegationStoreOptions as ah, type FleetWorkspaceExecutorOptions as ai, InMemoryDelegationStore as aj, InMemoryFeedbackStore as ak, type JsonRpcMessage as al, type JsonRpcResponse as am, type McpServer as an, type McpServerOptions as ao, type McpToolDescriptor as ap, type McpTransport as aq, type Question as ar, type QuestionDecision as as, type QuestionPolicy as at, type QuestionRecord as au, type ResearchOutputShape as av, type ResearchSource as aw, type RunDetachedTurnOptions as ax, type SettleDetachedCoderTurnOptions as ay, type SettledWorker as az, type FeedbackStore as b, validateDelegateArgs as b0, type EvalRunEvent as b1, type EvalRunGeneration as b2, type EvalRunsExportConfig as b3, type EvalRunsExportResult as b4, INTELLIGENCE_WIRE_VERSION as b5, type LoopSpanNode as b6, type OtelAttribute as b7, type OtelExportConfig as b8, type OtelExporter as b9, createInbox as bA, createSteerableSandboxSession as bB, defaultToolDetectors as bC, piExecutor as bD, piSeamKey as bE, watchTrace as bF, type OtelSpan as ba, type RuntimeEventOtelOptions as bb, buildLoopOtelSpans as bc, buildLoopSpanNodes as bd, buildRuntimeEventOtelSpans as be, createOtelExporter as bf, exportEvalRuns as bg, loopEventToOtelSpan as bh, type BusEvent as bi, type BusRecord as bj, type BusStats as bk, DEFAULT_SANDBOX_STEERING_MAX_TURNS as bl, type EventBus as bm, type Inbox as bn, type InboxMessage as bo, PI_RUNTIME as bp, type PiSeam as bq, type ProviderSeam as br, type PublishOptions as bs, type SandboxSteeringOptions as bt, type SteerableSandboxSession as bu, type WatchTraceOptions as bv, cliWorktreeExecutor as bw, createEventBus as bx, createExecutor as by, createExecutorRegistry as bz, type DelegateFeedbackResult as c, type DelegateFeedbackArgs as d, type DelegateUiAuditArgs as e, type DelegateUiAuditResult as f, type DelegationHistoryResult as g, type DelegationHistoryArgs as h, type DelegationStatusResult as i, type DelegationStatusArgs as j, type CoderDelegate as k, type CoderReview as l, type CoderReviewer as m, type CoordinationEvent as n, type CoordinationTools as o, type CoordinationToolsOptions as p, DELEGATE_DESCRIPTION as q, DELEGATE_INPUT_SCHEMA as r, DELEGATE_TOOL_NAME as s, DELEGATION_TRACE_MAX_BYTES as t, DELEGATION_TRACE_MAX_SPANS as u, type DelegateArgs as v, type DelegateCodeArgs as w, type DelegateCodeConfig as x, type DelegateCodeResult as y, type DelegateHandlerOptions as z };