@tangle-network/agent-runtime 0.60.0 → 0.61.0

package/dist/{delegates-C94qchkz.d.ts → delegates-CWMv_rKL.d.ts}

@@ -1,9 +1,489 @@
-import { C as CoderOutput, d as CoderTask } from './coder-CybltHEm.js';
-import { g as LoopTraceEmitter, d as LoopTraceEvent, S as SandboxClient, A as AgentRunSpec } from './types-CUzjRFZ3.js';
-import { SandboxEvent, SandboxInstance } from '@tangle-network/sandbox';
-import { AgentEvalError } from '@tangle-network/agent-eval';
+import { DefaultVerdict, AgentEvalError } from '@tangle-network/agent-eval';
+import { AgentProfile, BackendType, SandboxEvent, SandboxInstance } from '@tangle-network/sandbox';
+import { R as RuntimeHooks } from './runtime-hooks-C7JwKb9E.js';
+import { f as LoopTokenUsage, g as LoopTraceEmitter, d as LoopTraceEvent, S as SandboxClient, A as AgentRunSpec } from './types-Crxftafi.js';
+import { C as CoderTask } from './coder-DD5J5Onk.js';
 import { a as UiLens, U as UiFinding } from './substrate-CUgk7F7s.js';
 
+/**
+ * @experimental
+ *
+ * Recursive execution atom — the FROZEN type surface (the keystone contract).
+ *
+ * One self-similar `Agent` atom runs inside a budget-conserving reactive `Scope`,
+ * orchestrated by a `Supervisor` over an event-sourced `SpawnJournal`. A leaf is an
+ * `Agent` that never calls `scope.spawn`; a driver is an `Agent` that spawns and runs
+ * a policy over its children's streaming results.
+ *
+ * Two invariants the surface exists to make enforceable:
+ *  - Budget is an atomically-reserved CONSERVED pool, so `Σk(treatment) ≡ Σk(blind)` by
+ *    construction (reserve-on-spawn, refund-unspent-on-settle, fail-closed admission).
+ *  - The journal records a content-addressed `outRef` per child result, so replay
+ *    rehydrates the exact `Settled` the driver branched on (the replay invariant below).
+ *
+ * The leaf RUNTIME is one OPEN `Executor` interface, not a closed `inline|sandbox|cli`
+ * union the call site switches on. The built-ins (router/inline, sandbox, cli) are the
+ * initial IMPLEMENTATIONS; any user agent is first-class the moment it implements the
+ * interface. The interface IS the extension point — no per-vendor adapters live here.
+ *
+ * Layering: substrate types (`DefaultVerdict`) come from `@tangle-network/agent-eval`;
+ * runtime-shaped types (everything else) live here. Pure types/interfaces only — this
+ * module typechecks standalone and is imported by every keystone impl.
+ */
+
+/**
+ * One self-similar atom. A leaf is an `Agent` that never calls `scope.spawn`; a driver
+ * is an `Agent` whose `act` spawns children and reacts to them via `scope.next()`. An
+ * analyst is an `Agent` whose task is "read these traces → findings" — `where` it runs
+ * is its executor, not a separate type.
+ *
+ * `act` MUST be replay-safe: it may read `verdict`, `spent`, and `out` (rehydrated by
+ * `outRef`) off each `Settled`; it MUST NOT read `Date.now`, `Math.random`, or any
+ * unordered collection. `scope.next()` delivers strictly in recorded `seq` order.
+ */
+interface Agent<Task, Out> {
+    readonly name: string;
+    act(task: Task, scope: Scope<Out>): Promise<Out>;
+}
+/**
+ * The leaf runtime — ONE open interface, not a closed union. `execute` returns a
+ * `Promise<ExecutorResult>` for one-shot executors OR an `AsyncIterable<UsageEvent>` for
+ * streaming ones; a streaming executor reports incremental normalized usage as it runs
+ * (the budget pool reconciles against it) and exposes its terminal artifact via
+ * `resultArtifact()`. Both shapes normalize usage to `UsageEvent` so the conserved pool
+ * meters every runtime identically.
+ *
+ * Built-in implementations (in `runtime.ts`, NOT variants here): router/inline (a direct
+ * Router/HTTP inference call, no box), sandbox (COMPOSES `runLoop` as a leaf, forwarding
+ * PR #150's optional `lineage` passthrough — does NOT reinvent checkpoint/fork), cli
+ * (Halo/RLM subprocess; `budgetExempt`, excluded from equal-k by construction). A user's
+ * own agent (mastra/agno/raw HTTP/anything) is first-class by implementing this interface.
+ */
+interface Executor<Out> {
+    /** Stable runtime tag for traces + the equal-k exemption check. */
+    readonly runtime: Runtime;
+    /**
+     * When true, this executor's spend is NOT metered against the conserved pool and its
+     * iterations are excluded from the equal-k assertion (a `cli` subprocess without
+     * token accounting). Fail-loud everywhere else: a metered executor MUST report usage.
+     */
+    readonly budgetExempt?: boolean;
+    /**
+     * One-shot → resolves a `ExecutorResult`; streaming → yields incremental `UsageEvent`s and
+     * the terminal artifact is read from `resultArtifact()` after the stream drains.
+     * `signal` is the spawn-scoped abort (chains the acquire lifecycle for sandbox).
+     */
+    execute(task: unknown, signal: AbortSignal): Promise<ExecutorResult<Out>> | AsyncIterable<UsageEvent>;
+    /**
+     * Optional inbox: receive an out-of-band message from the driver mid-run (the `send`/`steer_worker`
+     * verb). A streaming executor drains pending messages between turns and folds them into the next
+     * step (a steer / interrupt / resume). A one-shot executor that can't be steered mid-flight omits
+     * this; `Scope.send` then returns `false` for it. Never throws — a malformed message is the
+     * executor's to ignore.
+     */
+    deliver?(msg: unknown): void;
+    /**
+     * Tear the executor's resources down. `grace` mirrors the OTP shutdown spec
+     * (`'brutalKill'` = immediate, a number = ms grace, `'infinity'` = await clean exit).
+     */
+    teardown(grace: number | 'brutalKill' | 'infinity'): Promise<{
+        destroyed: boolean;
+    }>;
+    /**
+     * The replay source (B1): the content-addressed `outRef` + the materialized output the
+     * driver branched on, its verdict, and the conserved spend. Read once, after settle.
+     */
+    resultArtifact(): {
+        outRef: string;
+        out: Out;
+        verdict?: DefaultVerdict;
+        spent: Spend;
+    };
+    /**
+     * A driver-executor's OWN-inference subtree total (rolled up from its nested tree's `metered`
+     * events) — the parent scope journals it as a `metered` event for this node on settle, on BOTH
+     * the done AND the down/crash paths, so a crashed sub-driver's partial inference still re-homes
+     * (the pool already debited it via `observe`; the journal must match). NOT reconciled, so it never
+     * trips the reservation clamp. Read on settle, valid after `execute` resolves OR throws. Leaf
+     * executors omit it (returns `undefined`).
+     */
+    metered?(): Spend | undefined;
+}
+/** Terminal artifact of a one-shot `Executor.execute`. */
+interface ExecutorResult<Out> {
+    outRef: string;
+    out: Out;
+    verdict?: DefaultVerdict;
+    spent: Spend;
+}
+/**
+ * Normalized usage event — the single channel every executor reports through, so the
+ * conserved pool meters all runtimes identically. `tokens` carries `LoopTokenUsage`'s
+ * `{ input, output }`; `usd` is a SEPARATE channel (never folded into tokens).
+ */
+type UsageEvent = {
+    kind: 'tokens';
+    input: number;
+    output: number;
+} | {
+    kind: 'cost';
+    usd: number;
+} | {
+    kind: 'iteration';
+};
+/** The runtime tag of a `Executor` impl. Open by intent — `string` so a BYO executor
+ *  names its own runtime; the built-ins use these literals. */
+type Runtime = 'router' | 'inline' | 'sandbox' | 'cli' | (string & {});
+/**
+ * `AgentProfile` does NOT carry a `harness`/backend field — `harness` lives on the
+ * sandbox SDK's `BackendConfig`, not the portable profile. So an agent is mapped to its
+ * executor through this MINIMAL wrapper, never by fabricating a field onto `AgentProfile`.
+ *
+ * Resolution (in `runtime.ts`):
+ *  - `executor` present        → BYO: use it verbatim (a user's own `Executor`).
+ *  - `harness === null`        → router/inline: a direct Router call, no box.
+ *  - `harness` is a `BackendType` → sandbox: compose `runLoop` against `profile` on that backend.
+ * Fail loud on an unresolvable spec (no executor and an unknown harness).
+ */
+interface AgentSpec {
+    readonly profile: AgentProfile;
+    /** `null` selects router/inline; a `BackendType` selects the sandboxed harness. */
+    readonly harness: BackendType | null;
+    /** Bring-your-own executor: when set, overrides harness-based resolution entirely. */
+    readonly executor?: Executor<unknown>;
+}
+/**
+ * Builds a fresh `Executor` for one spawn from the resolved spec. Per-spawn (not
+ * shared) so each child owns its own box/abort/teardown lifecycle. A BYO factory lets a
+ * user supply construction args without pre-instantiating.
+ */
+type ExecutorFactory<Out> = (spec: AgentSpec, ctx: ExecutorContext) => Executor<Out>;
+/** Construction context handed to a `ExecutorFactory` — the seams a built-in needs
+ *  (sandbox client for the sandbox executor, router config for router/inline) without
+ *  the factory reaching into module globals. */
+interface ExecutorContext {
+    readonly signal: AbortSignal;
+    /** Opaque seams the registry threads through; a built-in narrows what it needs. */
+    readonly seams: Readonly<Record<string, unknown>>;
+}
+/**
+ * The OPEN resolver: maps an `AgentSpec` to a `ExecutorFactory`. The default
+ * registry resolves the three built-ins AND accepts a BYO `executor`/factory; callers
+ * register more runtimes by name. NOT a closed switch — registration is the extension
+ * point, mirroring the open `Executor` interface.
+ */
+interface ExecutorRegistry {
+    /** Register a factory for a named runtime. Throws on a duplicate name (fail loud). */
+    register<Out>(runtime: Runtime, factory: ExecutorFactory<Out>): void;
+    /**
+     * Resolve a spec to a factory. Precedence: a BYO `spec.executor` → a trivial factory
+     * returning it; else `harness === null` → the `'router'` factory; else a registered
+     * factory for the harness-derived runtime. Returns a typed outcome — the caller
+     * inspects `succeeded` before `value` (no silent fallback).
+     */
+    resolve<Out>(spec: AgentSpec): {
+        succeeded: true;
+        value: ExecutorFactory<Out>;
+    } | {
+        succeeded: false;
+        error: string;
+    };
+}
+/** A budget envelope on a spawn or the root. All ceilings; the pool reserves against them. */
+interface Budget {
+    readonly maxIterations: number;
+    readonly maxTokens: number;
+    readonly maxUsd?: number;
+    readonly deadlineMs?: number;
+}
+/** Conserved spend, reconciled from the normalized `UsageEvent` stream. Tokens and usd
+ *  are separate channels (never folded). */
+interface Spend {
+    iterations: number;
+    tokens: LoopTokenUsage;
+    usd: number;
+    ms: number;
+}
+/** OTP child-spec restart class. */
+type Restart = 'temporary' | 'transient' | 'permanent';
+/** `'acquiring'` is first-class (M1): a node spends real time + reaps an orphan box
+ *  during sandbox acquire BEFORE it is `running`, so abort must be defined over it. */
+type NodeStatus = 'pending' | 'acquiring' | 'running' | 'done' | 'failed' | 'cancelled';
+/** Deterministic node id — `${parent}:s${seq}` from the cursor order, never wall-clock. */
+type NodeId = string;
+interface SpawnOpts {
+    readonly budget: Budget;
+    readonly label: string;
+    readonly restart?: Restart;
+    /** Teardown grace handed to the executor when this node is reaped. */
+    readonly shutdown?: number | 'brutalKill' | 'infinity';
+}
+/**
+ * A live child handle. `abort()` is defined over the ACQUIRE lifecycle: it chains into
+ * the `acquireSandbox` signal and reaps a find-by-name orphan box, so a node aborted
+ * mid-acquire never leaks (M1).
+ */
+interface Handle<Out> {
+    readonly id: NodeId;
+    readonly label: string;
+    readonly status: NodeStatus;
+    abort(reason?: string): void;
+    /** Phantom: binds the handle to the child's output type so `spawn<C>` returns a
+     *  `Handle<C>` distinct from a `Handle<other>`. Type-only — never present at runtime. */
+    readonly __out?: Out;
+}
+/**
+ * A settled child, delivered by `scope.next()`. `seq` is the monotonic cursor order
+ * `next()` yielded this settlement (B2) — NOT wall-clock — and replay delivers strictly
+ * in `seq` order. `outRef` rehydrates `out` from the `ResultBlobStore` on replay.
+ */
+type Settled<Out> = {
+    kind: 'done';
+    handle: Handle<Out>;
+    out: Out;
+    outRef: string;
+    verdict?: DefaultVerdict;
+    spent: Spend;
+    seq: number;
+} | {
+    kind: 'down';
+    handle: Handle<Out>;
+    reason: string;
+    /** True = infrastructure failure (excluded from merge `n` / equal-k), not a bad result. */
+    infra: boolean;
+    restartCount: number;
+    seq: number;
+};
+/**
+ * The budget-conserving reactive scope an `Agent.act` runs inside. `spawn` reserves
+ * budget atomically from the shared pool and fails closed when the pool cannot cover it.
+ * `next()` waits for one settlement from this scope's live set; `view` reads live state,
+ * not the replay log.
+ */
+interface Scope<Out> {
+    /**
+     * Spawn a child. Reserves `opts.budget` from the conserved pool atomically; refunds the
+     * unspent remainder on settle. Returns a typed outcome — fail-closed on an exhausted
+     * pool or an exceeded depth ceiling (the caller inspects `ok` before `handle`).
+     */
+    spawn<C extends Out>(agent: Agent<unknown, C>, task: unknown, opts: SpawnOpts): {
+        ok: true;
+        handle: Handle<C>;
+    } | {
+        ok: false;
+        reason: 'budget-exhausted' | 'depth-exceeded';
+    };
+    /** ray.wait n=1 over this scope's in-memory live set; resolves as each child settles;
+     *  `null` when the live set is empty. */
+    next(): Promise<Settled<Out> | null>;
+    /**
+     * Steer a RUNNING child out-of-band — deliver a message to its executor's inbox (the driver's
+     * `send` verb: next-instruction, interrupt, or resume). Returns `true` if the message was
+     * delivered to a live child whose executor accepts delivery, `false` otherwise (unknown id,
+     * already settled, or an executor with no inbox). The executor drains its inbox between turns;
+     * a leaf that does not implement `deliver` simply cannot be steered mid-flight. In-process this
+     * is a direct call; the sandbox/Agent-Bus transports surface the SAME verb as an MCP tool.
+     */
+    send(nodeId: NodeId, msg: unknown): boolean;
+    /** This scope's abort signal — aborted when the run is cancelled, a breaker trips, the pool
+     *  is exhausted, or a parent scope cascades. A long-running driver `act` over this scope reads
+     *  it to break promptly (the conserved pool + driver-stop are the other bounds). A nested
+     *  scope carries its own signal, chained off its driver child's abort. */
+    readonly signal: AbortSignal;
+    /**
+     * Meter the driver's OWN compute against the conserved pool — its inference turns, which are
+     * real tokens/usd but not a spawned child (no reserve/reconcile). A direct `free → committed`
+     * debit, so equal-k counts the driver's tokens AND the in-loop budget guard (`budget.tokensLeft`)
+     * halts a driver that thinks the pool dry. `detail` rides an `agent.turn` trace event for live
+     * observability (turn index, tool calls, cumulative spend). It also journals a `metered` event —
+     * the durable twin of the pool debit (as `settled` is the twin of `reconcile`) — so every
+     * journal-based cost reader (`spentFromJournal`, `trajectoryReport`) sums driver inference
+     * automatically. A leaf never calls this; a driver meters each chat turn and awaits it (the
+     * metered event is cost-critical, so it lands before the join-barrier roll-up).
+     */
+    meter(spend: Spend, detail?: Record<string, unknown>): Promise<void>;
+    /** The live tree — reads the in-memory nursery, not the journal. */
+    readonly view: TreeView;
+    /** Conserved-pool readouts (post-reservation). */
+    readonly budget: Readonly<{
+        tokensLeft: number;
+        usdLeft: number;
+        usdCapped: boolean;
+        deadlineMs: number;
+        reservedTokens: number;
+    }>;
+}
+interface NodeSnapshot {
+    readonly id: NodeId;
+    readonly parent?: NodeId;
+    readonly label: string;
+    readonly status: NodeStatus;
+    readonly runtime: Runtime;
+    readonly budget: Budget;
+    /** Conserved spend so far for this node. */
+    readonly spent: Spend;
+    /** `outRef` once the node is `done` (the replay/result pointer). */
+    readonly outRef?: string;
+}
+/** The live tree — what `scope.view` / `RootHandle.view()` materialize for a viewer. */
+interface TreeView {
+    readonly root: NodeId;
+    readonly nodes: ReadonlyArray<NodeSnapshot>;
+    /** Count of nodes in `running` or `acquiring` — the "what's in flow?" answer. */
+    readonly inFlight: number;
+}
+/** Journaled spawn-tree events (B1/B2). `seq` is the cursor order; `at` is an ISO
+ *  timestamp for human inspection only (NOT a replay input). */
+type SpawnEvent = {
+    kind: 'spawned';
+    id: NodeId;
+    parent?: NodeId;
+    label: string;
+    budget: Budget;
+    runtime: Runtime;
+    seq: number;
+    at: string;
+} | {
+    kind: 'settled';
+    id: NodeId;
+    status: 'done' | 'down';
+    /** Content-addressed result pointer; rehydrates `out` from `ResultBlobStore`. */
+    outRef?: string;
+    verdict?: DefaultVerdict;
+    spent: Spend;
+    infra?: boolean;
+    seq: number;
+    at: string;
+} | {
+    kind: 'cancelled';
+    id: NodeId;
+    reason: string;
+    seq: number;
+    at: string;
+} | {
+    /** A driver's OWN inference spend, journaled separately from spawned-child work — the journal
+     *  TWIN of `BudgetPool.observe`, exactly as `settled` is the twin of `reconcile`. So every
+     *  journal-based cost reader sums it automatically — the journal is the single cost ledger.
+     *  It carries spend only and is NOT a settlement: replay + `materializeTreeView` skip it for
+     *  structure, and its `seq` lives outside the cursor-uniqueness namespace. A
+     *  driver re-homes its nested subtree's metered total up to its parent (like settled spend),
+     *  so summing any sub-tree root yields that sub-tree's true driver-inference cost. */
+    kind: 'metered';
+    id: NodeId;
+    spend: Spend;
+    seq: number;
+    at: string;
+};
+/**
+ * The spawn-tree event source (mirrors `ConversationJournal`'s begin/append/load shape).
+ * `loadTree` replays the full ordered event list for resume/replay; `appendEvent` is
+ * called only AFTER the event is observed-committed (never speculative).
+ */
+interface SpawnJournal {
+    loadTree(root: NodeId): Promise<SpawnEvent[] | undefined>;
+    beginTree(root: NodeId, at: string): Promise<void>;
+    appendEvent(root: NodeId, ev: SpawnEvent): Promise<void>;
+}
+/** Content-addressed result blobs (the `outRef` → artifact map) backing the replay
+ *  invariant. Split from the journal so the journal stays small (decisions) and the
+ *  payloads (evidence) live where a viewer/replayer rehydrates them. */
+interface ResultBlobStore {
+    put(outRef: string, artifact: unknown): Promise<void>;
+    get(outRef: string): Promise<unknown | undefined>;
+}
+/**
+ * Owns the conserved pool, the spawn log, the abort cascade, the OTP intensity breaker,
+ * and the root handle. `run` executes the root `Agent` to completion; `attach` wires a
+ * live `RootHandle` (the Q2 substrate the chat/pi-viz client later consumes).
+ */
+interface Supervisor<Task, Out> {
+    run(root: Agent<Task, Out>, task: Task, opts: SupervisorOpts): Promise<SupervisedResult<Out>>;
+    attach(h: RootHandle<Out>): void;
+}
+interface SupervisorOpts {
+    /** The root conserved-pool ceiling (tokens + usd + iterations + deadline). */
+    readonly budget: Budget;
+    /** Trace-correlation root + the journal/blob root key. */
+    readonly runId: NodeId;
+    /** Event source — defaults to the in-memory journal in the impl; pass JSONL/FS for durability. */
+    readonly journal: SpawnJournal;
+    /** Result payload store backing `outRef` rehydration. */
+    readonly blobs: ResultBlobStore;
+    /** Executor resolution — the open registry mapping `AgentSpec` → `Executor`. */
+    readonly executors: ExecutorRegistry;
+    /** Runtime recursion-depth ceiling (paired with the conserved pool per R3). */
+    readonly maxDepth?: number;
+    /**
+     * OTP intensity breaker: more than `maxRestarts` child restarts within `withinMs`
+     * trips the supervisor to `no-winner` rather than restarting forever.
+     */
+    readonly maxRestarts?: number;
+    readonly withinMs?: number;
+    readonly now?: () => number;
+    readonly signal?: AbortSignal;
+    /** Lifecycle stream sink, threaded into the root `Scope` so every `spawn`/settle emits on the
+     *  same `agent.spawn`/`agent.child` stream `runLoop` feeds — one observable recursive tree. */
+    readonly hooks?: RuntimeHooks;
+}
+/** Typed terminal result (M2) — a no-winner is NEVER coerced to a best-effort output. */
+type SupervisedResult<Out> = {
+    kind: 'winner';
+    out: Out;
+    outRef: string;
+    verdict?: DefaultVerdict;
+    tree: TreeView;
+    spentTotal: Spend;
+    /** Where `spentTotal` went: `driverInference` = the drivers' own chat turns (metered via
+     *  `Scope.meter`); `childWork` = every spawned child's reconciled spend (the journal sum).
+     *  `driverInference + childWork === spentTotal`. Present whenever any driver metered. */
+    spentBreakdown?: {
+        driverInference: Spend;
+        childWork: Spend;
+    };
+} | {
+    kind: 'no-winner';
+    reason: 'all-children-down' | 'budget-exhausted' | 'aborted';
+    tree: TreeView;
+    downCount: number;
+};
+/** Live root handle — the substrate a chat/pi-viz client attaches to (Q2). `signal`
+ *  delivers an out-of-band message to the running root; `view()` materializes the tree. */
+interface RootHandle<Out> {
+    view(): TreeView;
+    signal(msg: RootSignal): void;
+    abort(reason?: string): void;
+    /** Phantom: binds the handle to the supervised run's output type. Type-only — never
+     *  present at runtime; lets `attach(h: RootHandle<Out>)` stay output-typed. */
+    readonly __out?: Out;
+}
+/** Out-of-band message to a running root. Open by intent — a client extends it. */
+type RootSignal = {
+    kind: 'pause';
+} | {
+    kind: 'resume';
+} | {
+    kind: 'cancel';
+    reason?: string;
+} | {
+    kind: 'ask';
+    question: string;
+};
+/**
+ * The progressive-widening gate (MCTS-PW). Decides whether a settled child is
+ * `promising` enough to spawn another under the remaining pool. DEFAULTS TO FLAT
+ * (`shouldWiden` always false) so a gate run never widens and the selector≠judge
+ * firewall conflict (R2) stays dormant. When widening IS enabled, `promising` MUST be
+ * derived from TRACE findings (`analyses`), never raw `verdict` — or the gate carries
+ * an explicit, argued `judgeExempt: true` (the documented escape hatch, off by default).
+ */
+interface WidenGate<Out> {
+    /** Default impl returns false for every settlement (flat — never widens). */
+    shouldWiden(settled: Settled<Out>, budget: Scope<Out>['budget']): boolean;
+    /** When true, widening may read `verdict` directly (collides with the steer firewall —
+     *  must be explicitly argued per cell, never defaulted on). */
+    readonly judgeExempt?: boolean;
+}
+
 /**
  * @experimental
  *
@@ -106,6 +586,49 @@ declare function createDelegationTraceCollector(onSpans: (spans: DelegationTrace
  */
 declare function composeLoopTraceEmitters(...emitters: ReadonlyArray<LoopTraceEmitter | undefined>): LoopTraceEmitter | undefined;
 
+/**
+ * @experimental
+ *
+ * Sandbox-session coder decode layer. The sandbox-session delegate (`./delegates`) and the
+ * cross-restart resume driver (`./bin`) run the in-box harness over a `SandboxClient` and need to
+ * (a) build an `AgentRunSpec` from the authored coder profile, (b) decode the harness event stream
+ * into a structured `CoderOutput`, and (c) gate it with the shared mechanical checks. This is the
+ * MCP server's built-in `delegate_code` path — it is the live default delegate, NOT dormant — and is
+ * kept separate from the generic recursive path: `worktreeFanout` instead settles the raw
+ * `WorktreePatchArtifact` and gates via `patchDelivered`. Only the OPTIONAL cross-restart resume
+ * (the `driveTurn` tick) is opt-in (`MCP_ENABLE_DETACHED_RESUME`); the held-stream delegate is
+ * always live. 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 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;
+}
+
 /**
  * @experimental
  *
@@ -1043,6 +1566,86 @@ declare class DelegationTaskQueue {
  */
 declare function hashIdempotencyInput(value: unknown): string;
 
+/**
+ * @experimental
+ *
+ * Git worktree helpers for the in-process delegation executor. Each
+ * delegation runs in its own worktree so multiple parallel harness
+ * subprocesses (claude / codex / opencode in a 3-way fanout) don't clobber
+ * each other's edits on the shared workspace.
+ *
+ * Worktrees live under `<repoRoot>/.agent-worktrees/<runId>/`. After the
+ * harness exits + the diff is captured, the worktree is removed.
+ *
+ * All operations spawn `git` via `child_process.spawn` synchronously
+ * (via a `runGit` helper). Stays narrow on purpose: no commits, no rebases.
+ * Diff capture stages all changes (`git add -A`) into the ephemeral worktree's
+ * index so created (untracked) files appear in the `--cached` diff.
+ */
+/** @experimental */
+interface WorktreeHandle {
+    /** Absolute path to the worktree directory. */
+    path: string;
+    /** SHA the worktree was created at. */
+    baseSha: string;
+    /** Branch name created for this worktree (typically `delegate/<runId>`). */
+    branch: string;
+}
+/** @experimental */
+interface CreateWorktreeOptions {
+    /** Absolute path to the main git checkout. */
+    repoRoot: string;
+    /** Unique id for the worktree path + branch. Use the delegation run id. */
+    runId: string;
+    /** Parent directory the worktree lives under. Defaults to `.agent-worktrees`. */
+    variantsDir?: string;
+    /** Override the base ref (default `HEAD`). */
+    baseRef?: string;
+    /** Test seam — inject a custom git runner. */
+    runGit?: GitRunner;
+}
+/** @experimental */
+interface DiffOptions {
+    /** Worktree to diff. */
+    worktree: WorktreeHandle;
+    /** What to compare against. Default `worktree.baseSha`. */
+    baseRef?: string;
+    /** Test seam. */
+    runGit?: GitRunner;
+}
+/** @experimental */
+interface DiffResult {
+    patch: string;
+    stats: {
+        filesChanged: number;
+        insertions: number;
+        deletions: number;
+    };
+}
+/** @experimental */
+interface RemoveWorktreeOptions {
+    worktree: WorktreeHandle;
+    repoRoot: string;
+    /** Force removal even if dirty (default true; the loser of a fanout has uncommitted changes). */
+    force?: boolean;
+    /** Test seam. */
+    runGit?: GitRunner;
+}
+/** Pluggable git runner (sync) — replaceable in tests. */
+type GitRunner = (args: ReadonlyArray<string>, opts: {
+    cwd: string;
+}) => {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+};
+/** @experimental */
+declare function createWorktree(options: CreateWorktreeOptions): Promise<WorktreeHandle>;
+/** @experimental */
+declare function captureWorktreeDiff(options: DiffOptions): Promise<DiffResult>;
+/** @experimental */
+declare function removeWorktree(options: RemoveWorktreeOptions): Promise<void>;
+
 /**
  * @experimental
  *
@@ -1341,6 +1944,28 @@ interface FleetWorkspaceExecutorOptions {
  */
 declare function createFleetWorkspaceExecutor(options: FleetWorkspaceExecutorOptions): DelegationExecutor;
 
+/**
+ * @experimental
+ *
+ * Delegate factories — the layer between MCP tool handlers and the
+ * underlying `runLoop` runners.
+ *
+ * The MCP server is profile-agnostic: it owns the task queue + feedback
+ * store + transport. Each `*Delegate` is the closure that the queue
+ * invokes when a task runs. Consumers can override either delegate to
+ * inject custom drivers, mocks, fleet-aware dispatchers, etc.
+ *
+ * The `detachedSessionDelegate` here is the built-in SANDBOX-SESSION coder path — the live default
+ * `delegate_code` delegate: workers run the in-box harness over a `SandboxClient`. By default it
+ * holds the stream; single-variant turns can OPTIONALLY dispatch DETACHED (`driveTurn` ticks) so a
+ * durable queue resumes them across an MCP restart — that resume tick is the only part gated behind
+ * `MCP_ENABLE_DETACHED_RESUME` (default off) in `bin.ts`, a capability the recursive
+ * `Scope`/worktree-CLI leaf has no durable equivalent for yet. For NEW local-repo coding use
+ * `worktreeFanout` / `worktreeLoopRunner`. The default researcher delegate is **not** wired in this
+ * file — `agent-knowledge` cannot be imported from `agent-runtime` without inducing a cycle.
+ * Consumers pass `researcherDelegate` explicitly.
+ */
+
 /** @experimental */
 interface DelegateRunCtx {
     signal: AbortSignal;
@@ -1362,7 +1987,8 @@ interface DelegateRunCtx {
      */
     traceEmitter?: LoopTraceEmitter;
 }
-/** @experimental */
+/** @experimental The server's coder-profile delegate slot — the closure the queue invokes for a
+ *  `delegate_code` task. `detachedSessionDelegate` is the built-in implementation. */
 type CoderDelegate = (args: DelegateCodeArgs, ctx: DelegateRunCtx) => Promise<CoderOutput>;
 /** @experimental */
 type ResearcherDelegate = (args: DelegateResearchArgs, ctx: DelegateRunCtx) => Promise<ResearchOutputShape>;
@@ -1399,13 +2025,15 @@ type CoderReviewer = (output: CoderOutput, task: CoderTask, ctx: {
     signal: AbortSignal;
 }) => Promise<CoderReview> | CoderReview;
 /**
- * @experimental Winner-selection strategy among validated (+ reviewed)
- * candidates. `highest-readiness` requires a `reviewer`. Default `highest-score`
- * (the kernel's behavior — preserves backward compatibility).
+ * @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 CoderWinnerSelection = 'highest-score' | 'smallest-diff' | 'highest-readiness' | 'first-approved';
+type DetachedWinnerSelection = 'highest-score' | 'smallest-diff' | 'highest-readiness' | 'first-approved';
 /** @experimental */
-interface CreateDefaultCoderDelegateOptions {
+interface DetachedSessionDelegateOptions {
     /**
      * Execution placement. Pass a {@link DelegationExecutor} (sibling or fleet)
      * to control where worker iterations land. `sandboxClient` is a
@@ -1442,7 +2070,7 @@ interface CreateDefaultCoderDelegateOptions {
      */
     reviewer?: CoderReviewer;
     /** Winner-selection strategy among eligible candidates. Default `highest-score`. */
-    winnerSelection?: CoderWinnerSelection;
+    winnerSelection?: DetachedWinnerSelection;
     /**
      * Loop trace emitter forwarded into every delegated `runLoop`. Wire
      * `createPropagatingTraceEmitter(readTraceContextFromEnv())` here (the bin
@@ -1461,23 +2089,23 @@ interface CreateDefaultCoderDelegateOptions {
     detachedWallCapMs?: number;
 }
 /**
- * Build a coder delegate that drives `runLoop` against the project's
- * sandbox client + coder profile. When `args.variants > 1` it switches
- * to the multi-harness fanout topology.
+ * Build the sandbox-session coder delegate. It drives `runLoop` 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, `worktreeCoderFanout` is a generic alternative (author an
- * `AgentProfile` per harness → `createWorktreeCliExecutor` leaves → `gateOnDeliverable`). This
- * factory remains first-class: it owns the sandbox-session + detached-resume substrate that the
- * worktree-CLI leaf does not yet replicate.
+ * For NEW local-repo coding use `worktreeFanout` / `worktreeLoopRunner` (author an `AgentProfile`
+ * per harness → `createWorktreeCliExecutor` leaves → `gateOnDeliverable`). This delegate stays as the
+ * MCP server's built-in `delegate_code` path; it 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 createDefaultCoderDelegate(options: CreateDefaultCoderDelegateOptions): CoderDelegate;
+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
@@ -1508,11 +2136,11 @@ interface SettleDetachedCoderTurnOptions {
  * SCOPE NOTE (detached/resume): the detached `driveTurn`-tick + cross-restart resume path is
  * bound to the `runLoop` + 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 `worktreeCoderFanout` path. This helper (with `coderTaskFromArgs` and
+ * advertised on the generic `worktreeFanout` path. This helper (with `coderTaskFromArgs` and
  * `createDriveTurnResumeDriver`) stays as the resume seam `bin.ts` wires for in-flight records.
  *
  * @experimental
  */
 declare function settleDetachedCoderTurn(turn: DetachedTurn, options: SettleDetachedCoderTurnOptions): Promise<CoderOutput>;
 
-export { type DriveTurnCapableBox as $, type DelegateUiAuditRoute as A, type DelegationError as B, type CoderReviewer as C, type DelegateCodeArgs as D, type DelegationHistoryEntry as E, type FleetHandle as F, DelegationPersistenceError as G, type DelegationProfile as H, type DelegationProgress as I, type DelegationRecord as J, type DelegationResultPayload as K, type DelegationResumeContext as L, type DelegationResumeDriver as M, type DelegationResumeTick as N, type DelegationRunContext as O, DelegationStateCorruptError as P, type DelegationStatus as Q, type ResearcherDelegate as R, type DelegationStore as S, type TraceContext as T, type UiAuditorDelegate as U, type DelegationTaskQueueOptions as V, type DelegationTraceCaps as W, type DelegationTraceCollector as X, type DelegationTraceSpan as Y, type DetachedSessionRefParts as Z, type DetachedTurn as _, type CoderWinnerSelection as a, type DriveTurnResumeDriverOptions as a0, type DriveTurnTick as a1, type FeedbackRating as a2, type FeedbackRefersTo as a3, FileDelegationStore as a4, type FileDelegationStoreOptions as a5, type FleetWorkspaceExecutorOptions as a6, InMemoryDelegationStore as a7, type ResearchOutputShape as a8, type RunDetachedTurnOptions as a9, type EvalRunsExportResult as aA, INTELLIGENCE_WIRE_VERSION as aB, type LoopSpanNode as aC, type OtelAttribute as aD, type OtelExportConfig as aE, type OtelExporter as aF, type OtelSpan as aG, buildLoopOtelSpans as aH, buildLoopSpanNodes as aI, createOtelExporter as aJ, exportEvalRuns as aK, loopEventToOtelSpan as aL, type SettleDetachedCoderTurnOptions as aa, type SiblingSandboxExecutorOptions as ab, type SubmitInput as ac, type SubmitOutput as ad, type UiAuditorDelegationOutput as ae, buildDelegationTraceSpans as af, capDelegationTrace as ag, coderTaskFromArgs as ah, composeLoopTraceEmitters as ai, createDefaultCoderDelegate as aj, createDelegationTraceCollector as ak, createDriveTurnResumeDriver as al, createFleetWorkspaceExecutor as am, createPropagatingTraceEmitter as an, createSiblingSandboxExecutor as ao, detachedTurnEvents as ap, formatDetachedSessionRef as aq, hashIdempotencyInput as ar, parseDetachedSessionRef as as, readTraceContextFromEnv as at, runDetachedTurn as au, settleDetachedCoderTurn as av, traceContextToEnv as aw, type EvalRunEvent as ax, type EvalRunGeneration as ay, type EvalRunsExportConfig as az, type DelegateFeedbackArgs as b, type DelegationFeedbackSnapshot as c, DelegationTaskQueue as d, type CoderDelegate as e, type DelegationExecutor as f, type DelegateCodeResult as g, type DelegateFeedbackResult as h, type ResearchSource as i, type DelegateResearchArgs as j, type DelegateResearchResult as k, type DelegateUiAuditArgs as l, type DelegateUiAuditResult as m, type DelegationHistoryResult as n, type DelegationHistoryArgs as o, type DelegationStatusResult as p, type DelegationStatusArgs as q, type CappedDelegationTrace as r, type CoderReview as s, type CreateDefaultCoderDelegateOptions as t, DELEGATION_TRACE_MAX_BYTES as u, DELEGATION_TRACE_MAX_SPANS as v, type DelegateCodeConfig as w, type DelegateResearchConfig as x, type DelegateRunCtx as y, type DelegateUiAuditConfig as z };
+export { type DelegationRecord as $, type Agent as A, type Budget as B, type CoderReviewer as C, type DelegateCodeArgs as D, type ExecutorRegistry as E, type FleetHandle as F, type GitRunner as G, type CappedDelegationTrace as H, type CoderReview as I, type CreateWorktreeOptions as J, DELEGATION_TRACE_MAX_BYTES as K, DELEGATION_TRACE_MAX_SPANS as L, type DelegateCodeConfig as M, type NodeId as N, type DelegateResearchConfig as O, type DelegateRunCtx as P, type DelegateUiAuditConfig as Q, type ResearcherDelegate as R, type Scope as S, type TraceContext as T, type UiAuditorDelegate as U, type DelegateUiAuditRoute as V, type DelegationError as W, type DelegationHistoryEntry as X, DelegationPersistenceError as Y, type DelegationProfile as Z, type DelegationProgress as _, type DetachedWinnerSelection as a, type OtelExportConfig as a$, type DelegationResultPayload as a0, type DelegationResumeContext as a1, type DelegationResumeDriver as a2, type DelegationResumeTick as a3, type DelegationRunContext as a4, DelegationStateCorruptError as a5, type DelegationStatus as a6, type DelegationStore as a7, type DelegationTaskQueueOptions as a8, type DelegationTraceCaps as a9, capDelegationTrace as aA, captureWorktreeDiff as aB, coderTaskFromArgs as aC, composeLoopTraceEmitters as aD, createDelegationTraceCollector as aE, createDriveTurnResumeDriver as aF, createFleetWorkspaceExecutor as aG, createPropagatingTraceEmitter as aH, createSiblingSandboxExecutor as aI, createWorktree as aJ, detachedSessionDelegate as aK, detachedTurnEvents as aL, formatDetachedSessionRef as aM, hashIdempotencyInput as aN, parseDetachedSessionRef as aO, readTraceContextFromEnv as aP, removeWorktree as aQ, runDetachedTurn as aR, settleDetachedCoderTurn as aS, traceContextToEnv as aT, type EvalRunEvent as aU, type EvalRunGeneration as aV, type EvalRunsExportConfig as aW, type EvalRunsExportResult as aX, INTELLIGENCE_WIRE_VERSION as aY, type LoopSpanNode as aZ, type OtelAttribute as a_, type DelegationTraceCollector as aa, type DelegationTraceSpan as ab, type DetachedSessionDelegateOptions as ac, type DetachedSessionRefParts as ad, type DetachedTurn as ae, type DiffOptions as af, type DiffResult as ag, type DriveTurnCapableBox as ah, type DriveTurnResumeDriverOptions as ai, type DriveTurnTick as aj, type FeedbackRating as ak, type FeedbackRefersTo as al, FileDelegationStore as am, type FileDelegationStoreOptions as an, type FleetWorkspaceExecutorOptions as ao, InMemoryDelegationStore as ap, type RemoveWorktreeOptions as aq, type ResearchOutputShape as ar, type RunDetachedTurnOptions as as, type SettleDetachedCoderTurnOptions as at, type SiblingSandboxExecutorOptions as au, type SubmitInput as av, type SubmitOutput as aw, type UiAuditorDelegationOutput as ax, type WorktreeHandle as ay, buildDelegationTraceSpans as az, type CoderOutput as b, type OtelExporter as b0, type OtelSpan as b1, buildLoopOtelSpans as b2, buildLoopSpanNodes as b3, createOtelExporter as b4, exportEvalRuns as b5, loopEventToOtelSpan as b6, type SpawnEvent as b7, type TreeView as b8, type ExecutorFactory as b9, type UsageEvent as ba, type Supervisor as bb, type ExecutorContext as bc, type ExecutorResult as bd, type Handle as be, type NodeSnapshot as bf, type NodeStatus as bg, type Restart as bh, type RootSignal as bi, type Runtime as bj, type SpawnOpts as bk, type SupervisorOpts as bl, type WidenGate as bm, type DelegateFeedbackArgs as c, type DelegationFeedbackSnapshot as d, DelegationTaskQueue as e, type CoderDelegate as f, type ResultBlobStore as g, type AgentSpec as h, type SpawnJournal as i, type RootHandle as j, type SupervisedResult as k, type Settled as l, type Spend as m, type Executor as n, type DelegationExecutor as o, type DelegateCodeResult as p, type DelegateFeedbackResult as q, type ResearchSource as r, type DelegateResearchArgs as s, type DelegateResearchResult as t, type DelegateUiAuditArgs as u, type DelegateUiAuditResult as v, type DelegationHistoryResult as w, type DelegationHistoryArgs as x, type DelegationStatusResult as y, type DelegationStatusArgs as z };