@tangle-network/agent-runtime 0.56.1 → 0.58.0

package/dist/runtime.d.ts

@@ -1,21 +1,22 @@
 import { AgentProfile, BackendType, CreateSandboxOptions, SandboxInstance, SandboxEvent } from '@tangle-network/sandbox';
 export { AgentProfile, CreateSandboxOptions, SandboxEvent, SandboxInstance } from '@tangle-network/sandbox';
-import { u as ResultBlobStore, v as SpawnJournal, N as NodeId, w as SpawnEvent, T as TreeView, x as Settled, y as AgentSpec, E as ExecutorRegistry, B as Budget, z as Agent, H as RootHandle, K as SupervisedResult, L as Spend, O as Scope, P as ExecutorFactory, U as Executor, V as UsageEvent, G as GitRunner, M as MakeWorkerAgent, X as Supervisor } from './coordination-DWNGqygr.js';
-export { Y as ExecutorContext, Z as ExecutorResult, _ as Handle, $ as NodeSnapshot, a0 as NodeStatus, a1 as Restart, a2 as RootSignal, a3 as Runtime, a4 as SpawnOpts, a5 as SupervisorOpts, a6 as WidenGate } from './coordination-DWNGqygr.js';
+import { u as ResultBlobStore, v as SpawnJournal, N as NodeId, w as SpawnEvent, T as TreeView, x as Settled, y as AgentSpec, E as ExecutorRegistry, B as Budget, z as Agent, H as RootHandle, K as SupervisedResult, L as Spend, O as Scope, P as ExecutorFactory, U as Executor, V as UsageEvent, G as GitRunner, M as MakeWorkerAgent, a as CoordinationTools, A as AnalystRegistry, C as CoordinationEvent, l as QuestionPolicy, X as Supervisor } from './coordination-BydGBQCZ.js';
+export { Y as BusEvent, Z as BusRecord, _ as BusStats, $ as EventBus, a0 as ExecutorContext, a1 as ExecutorResult, a2 as Handle, a3 as NodeSnapshot, a4 as NodeStatus, a5 as PublishOptions, a6 as Restart, a7 as RootSignal, a8 as Runtime, a9 as SpawnOpts, aa as SupervisorOpts, ab as WidenGate, ac as createEventBus } from './coordination-BydGBQCZ.js';
 import { R as RuntimeHooks } from './runtime-hooks-C7JwKb9E.js';
-import { ChatClient, AnalystFinding, DefaultVerdict, AgentProfile as AgentProfile$1, AnalystRunInputs } from '@tangle-network/agent-eval';
+import { ChatClient, AnalystFinding, DefaultVerdict, AgentProfile as AgentProfile$1, AnalystRunInputs, ToolSpan, StreamingDetector, DetectorSignal, buildTrajectory } from '@tangle-network/agent-eval';
 export { DefaultVerdict } from '@tangle-network/agent-eval';
-import { I as Iteration, S as SandboxClient, b as LoopResult, d as LoopTokenUsage, R as RuntimeStreamEvent, A as AgentRunSpec, E as ExecCtx } from './types-C8rNlxfV.js';
-export { D as Driver, F as LoopDecisionPayload, G as LoopEndedPayload, H as LoopIterationDispatchPayload, J as LoopIterationEndedPayload, M as LoopIterationStartedPayload, a as LoopLineageOptions, N as LoopPlanDescription, P as LoopPlanPayload, f as LoopSandboxPlacement, Q as LoopStartedPayload, T as LoopTeardownFailedPayload, g as LoopTraceEmitter, e as LoopTraceEvent, L as LoopWinner, O as OutputAdapter, U as ValidationCtx, V as Validator } from './types-C8rNlxfV.js';
+import { I as Iteration, S as SandboxClient, b as LoopResult, e as LoopTokenUsage, R as RuntimeStreamEvent, A as AgentRunSpec, E as ExecCtx } from './types-CUzjRFZ3.js';
+export { D as Driver, F as LoopDecisionPayload, G as LoopEndedPayload, H as LoopIterationDispatchPayload, J as LoopIterationEndedPayload, M as LoopIterationStartedPayload, a as LoopLineageOptions, N as LoopPlanDescription, P as LoopPlanPayload, f as LoopSandboxPlacement, Q as LoopStartedPayload, T as LoopTeardownFailedPayload, g as LoopTraceEmitter, d as LoopTraceEvent, L as LoopWinner, O as OutputAdapter, U as ValidationCtx, V as Validator } from './types-CUzjRFZ3.js';
 import { Scenario, ProfileDispatchFn } from '@tangle-network/agent-eval/campaign';
-import { R as RunLoopOptions } from './run-loop-DluzfJ2h.js';
-export { c as createSandboxForSpec, d as defaultSelectWinner, r as runLoop } from './run-loop-DluzfJ2h.js';
+import { R as RunLoopOptions } from './run-loop-CcqfR_gy.js';
+export { c as createSandboxForSpec, d as defaultSelectWinner, r as runLoop } from './run-loop-CcqfR_gy.js';
 import { b as AnalystRegistryLike } from './types-p8dWBIXL.js';
 import { R as RouterConfig, T as ToolSpec } from './router-client-30Y_pca8.js';
 export { a as RouterChatResult, b as RouterChatToolsResult, c as RouterToolCall, d as RouterToolLoopResult, r as routerChatWithTools, e as routerChatWithUsage, f as routerToolLoop } from './router-client-30Y_pca8.js';
-import { a as CoderCheckConstraints } from './coder-COuOK8h8.js';
+import { a as CoderCheckConstraints } from './coder-CybltHEm.js';
 import { L as LocalHarness, r as runLocalHarness } from './local-harness-BE_h8szs.js';
-import './delegates-D9o5_VFj.js';
+import { stuckLoopView, toolWasteView } from '@tangle-network/agent-eval/pipelines';
+import './delegates-C94qchkz.js';
 import './substrate-CUgk7F7s.js';
 import 'node:child_process';
 
@@ -115,7 +116,8 @@ declare class FileSpawnJournal implements SpawnJournal {
 declare function replaySpawnTree(journal: SpawnJournal, blobs: ResultBlobStore, root: NodeId): Promise<Settled<unknown>[]>;
 /**
  * Materialize the live tree (`TreeView`) from a journaled event list for resume. Folds
- * `spawned`/`settled`/`cancelled` into a per-node snapshot in `seq` order so the
+ * `spawned`/`settled`/`cancelled` into a per-node snapshot in `seq` order, then adds each
+ * `metered` event's driver-inference spend onto its node in a separate additive pass — so the
  * resumed view matches what `scope.view` showed at the recorded cursor position.
  */
 declare function materializeTreeView(events: SpawnEvent[]): TreeView;
@@ -2928,10 +2930,13 @@ interface ReservationTicket {
 }
 /** Post-reservation pool readout — the shape `Scope.budget` exposes. `tokensLeft`,
  *  `usdLeft`, and `reservedTokens` reflect committed-but-unsettled reservations;
- *  `deadlineMs` is the ABSOLUTE wall-clock deadline (0 when the root set none). */
+ *  `deadlineMs` is the ABSOLUTE wall-clock deadline (0 when the root set none).
+ *  `usdCapped` distinguishes a real `usdLeft <= 0` exhaustion from an uncapped pool (which always
+ *  reads `usdLeft: 0`) — the in-loop guard needs it to bound a usd-capped driver. */
 type BudgetReadout = Readonly<{
     tokensLeft: number;
     usdLeft: number;
+    usdCapped: boolean;
     deadlineMs: number;
     reservedTokens: number;
 }>;
@@ -2960,6 +2965,17 @@ interface BudgetPool {
     spendFrom(events: AsyncIterable<UsageEvent> | UsageEvent[]): Promise<Spend>;
     /** The current readout, reflecting all outstanding reservations. */
     readout(): BudgetReadout;
+    /**
+     * Record OBSERVED spend that did NOT go through reserve/reconcile — the driver's OWN inference
+     * (its chat turns), which is real compute but not a spawned child. A direct `free → committed`
+     * debit, so `total ≡ free + reserved + committed` is preserved: equal-k counts the driver's
+     * tokens and the in-loop budget guard (`readout().tokensLeft`) sees them. `free` may go negative
+     * when a run overspends — that is honest (the readout then signals exhaustion). It never throws:
+     * the spend already happened, so accounting records reality; the in-loop guard prevents MORE.
+     * The DURABLE record is the journal's `metered` event (written by `Scope.meter`); this debit
+     * only makes the live `readout()` reflect driver inference for the in-loop guard.
+     */
+    observe(spend: Spend): void;
     /** Fail loud if any reservation is still open — the conserved-pool leak detector. Called at the
      *  supervisor's join barrier: once every child has settled, no ticket may remain (a leaked
      *  reservation would silently break `total ≡ free + reserved + committed`). */
@@ -2980,46 +2996,37 @@ declare function createBudgetPool(root: Budget, now?: () => number): BudgetPool;
 /**
  * @experimental
  *
- * The worktree-CLI leaf executor — a supervisor-authored `AgentProfile` driving a local
- * coding-harness CLI (claude / codex / opencode) on its OWN git worktree, surfaced as the
- * open `Executor<Out>` port (`./types`). It is a LEAF executor, not a `DelegationExecutor`:
- * it plugs straight into the `Scope`/`Supervisor` recursion and `gateOnDeliverable`, so it
- * IS the canonical recursive path (no `runLoop`/virtual-SandboxInstance shim in between).
- *
- * The §1.5 payload reaches the harness: `harnessInvocation` (mcp/local-harness) maps the
- * authored `profile.prompt.systemPrompt` into the prompt channel and `profile.model.default`
- * into the harness's `-m` selector — the prompt-only `buildArgs(taskPrompt)` path dropped
- * both. The subprocess runs through `runLocalHarness` (the stdin-CLOSED spawn shape — the
- * #308 fix that keeps a non-TTY `opencode run` from blocking on input forever).
+ * The ONE worktree-harness execution core. The physical act — run a supervisor-authored
+ * `AgentProfile` on a local coding-harness CLI (claude / codex / opencode) against a fresh git
+ * worktree off `repoRoot`, capture the diff, derive the test/typecheck PASS signals, then clean
+ * up — lives here ONCE. Two executors adapt it to two ports without re-implementing it:
+ *   - `createWorktreeCliExecutor` — the `Scope`/`Supervisor` leaf `Executor`.
+ *   - `createInProcessExecutor`   — the `runLoop` `SandboxClient` / coder-delegate path.
  *
- * Lifecycle per spawn (fresh executor — one box/abort/teardown each):
- *   1. `createWorktree` — `git worktree add` off `repoRoot` at `baseRef`.
- *   2. `runLocalHarness` — spawn the harness, fed the profile-aware invocation.
- *   3. `captureWorktreeDiff` — `git diff` the worktree → the patch artifact.
- *   4. `removeWorktree` — on `teardown` (always; the loser of a fanout is dirty).
+ * §1.5 by construction: the authored `profile.prompt.systemPrompt` + `profile.model.default`
+ * reach the harness through `harnessInvocation` HERE, so neither port can drop them — the exact
+ * bug that existed while the in-process path called `runLocalHarness` with only the task prompt.
  *
- * Reuse, not duplication: `createWorktree` / `captureWorktreeDiff` / `removeWorktree` come
- * straight from `mcp/worktree`; `runLocalHarness` + `LocalHarness` from `mcp/local-harness`.
- * Nothing here reimplements a worktree, a spawn, or a diff.
- *
- * Token accounting: a harness CLI does not surface usage, so this executor is
- * `budgetExempt: true` — its spend is NOT metered against the conserved pool and its
- * iterations are EXCLUDED from the equal-k arms by construction (mirrors `cliExecutor`).
+ * Lifecycle: `createWorktree` → `harnessInvocation` + `runLocalHarness` → `captureWorktreeDiff`
+ * (BEFORE checks, so the patch is the harness's output, not polluted by files a test run writes)
+ * → the configured test/typecheck commands in the live worktree → return the result + a `cleanup`
+ * the caller invokes at its own teardown point. A throw cleans up before propagating, so a failed
+ * run never leaks a worktree.
  */
 
 /** Outcome of one verification command run in the worktree (test or typecheck). */
 interface WorktreeCommandResult {
     /** The shell command line that was run. */
     command: string;
-    /** Did the command exit 0? The PASS signal the coder deliverable gates on. */
+    /** Did the command exit 0? The PASS signal a deliverable gate / coder output reads. */
     passed: boolean;
     /** OS exit code, or `null` when killed before exit. */
     exitCode: number | null;
     /** Combined stdout+stderr (capped) — surfaced in traces for diagnosis. */
     output: string;
 }
-/** Terminal artifact of one worktree-CLI run: the captured diff + the harness's run record. */
-interface WorktreePatchArtifact {
+/** The canonical result of one worktree-harness run, projected by each port to its own shape. */
+interface WorktreeHarnessResult {
     /** The branch the worktree was cut on (`delegate/<runId>`). */
     branch: string;
     /** `git diff` of the worktree against its base — the unified patch the harness produced. */
@@ -3030,7 +3037,7 @@ interface WorktreePatchArtifact {
         insertions: number;
         deletions: number;
     };
-    /** The harness subprocess outcome (exit code, captured streams, timing). */
+    /** The harness subprocess outcome. */
     harness: {
         name: LocalHarness;
         exitCode: number | null;
@@ -3040,17 +3047,46 @@ interface WorktreePatchArtifact {
         stdout: string;
         stderr: string;
     };
-    /**
-     * Verification signals DERIVED in the live worktree, after the harness ran and before
-     * teardown — the PASS signals the old sandbox `CoderOutput` carried, re-derived here by
-     * running the configured commands. Present only when `testCmd`/`typecheckCmd` were supplied.
-     * The coder deliverable (`coderDeliverable`) reads these to gate the patch.
-     */
+    /** Verification signals derived in the live worktree (present only when commands were given). */
     checks?: {
         tests?: WorktreeCommandResult;
         typecheck?: WorktreeCommandResult;
     };
 }
+/** The single shell-command-in-worktree runner seam (replaces the per-executor copies). */
+type WorktreeCheckRunner = (opts: {
+    command: string;
+    cwd: string;
+    timeoutMs: number;
+    signal?: AbortSignal;
+}) => Promise<{
+    exitCode: number | null;
+    output: string;
+}>;
+
+/**
+ * @experimental
+ *
+ * The worktree-CLI leaf executor — a supervisor-authored `AgentProfile` driving a local
+ * coding-harness CLI (claude / codex / opencode) on its OWN git worktree, surfaced as the open
+ * `Executor<Out>` port (`./types`). It is a LEAF executor: it plugs straight into the
+ * `Scope`/`Supervisor` recursion and `gateOnDeliverable`, so it IS the canonical recursive path
+ * (no `runLoop`/virtual-SandboxInstance shim in between).
+ *
+ * This is a THIN adapter: the physical act (worktree → profile-aware harness invocation → diff →
+ * checks → cleanup) lives ONCE in `runWorktreeHarness` (`../../mcp/worktree-harness`), shared with
+ * the `runLoop`/coder-delegate `createInProcessExecutor`. This executor only projects that core's
+ * result onto the `Executor` port (artifact + spend) and owns the teardown point. The §1.5 payload
+ * (authored systemPrompt + model) reaches the harness inside the core, not here.
+ *
+ * Token accounting: a harness CLI does not surface usage, so this executor is `budgetExempt: true`
+ * — its spend is NOT metered against the conserved pool and its iterations are EXCLUDED from the
+ * equal-k arms by construction (mirrors `cliExecutor`).
+ */
+
+/** Terminal artifact of one worktree-CLI run — the canonical worktree-harness result (the captured
+ *  diff + the harness's run record + the derived checks). */
+type WorktreePatchArtifact = WorktreeHarnessResult;
 /** @experimental */
 interface WorktreeCliExecutorOptions {
     /** Absolute path to the git checkout the worktree is cut from. */
@@ -3080,26 +3116,16 @@ interface WorktreeCliExecutorOptions {
     runGit?: GitRunner;
     /** Test seam — inject the harness runner so unit tests script a `LocalHarnessResult`. */
     runHarness?: typeof runLocalHarness;
-    /**
-     * Test seam — inject the verification-command runner so unit tests script test/typecheck
-     * outcomes without spawning a real shell. Defaults to a `/bin/sh -c` spawn in the worktree.
-     */
-    runCommand?: (opts: {
-        command: string;
-        cwd: string;
-        timeoutMs: number;
-        signal?: AbortSignal;
-    }) => Promise<{
-        exitCode: number | null;
-        output: string;
-    }>;
+    /** Test seam — inject the verification-command runner so unit tests script test/typecheck
+     *  outcomes without spawning a real shell. Defaults to a `/bin/sh -c` spawn in the worktree. */
+    runCommand?: WorktreeCheckRunner;
 }
 /**
- * Build a worktree-CLI leaf `Executor`. Per-spawn (a fresh worktree + abort + teardown each),
- * so a fanout of N profiles = N parallel worktrees that never clobber each other.
+ * Build a worktree-CLI leaf `Executor`. Per-spawn (a fresh worktree + abort + teardown each), so a
+ * fanout of N profiles = N parallel worktrees that never clobber each other.
  *
- * Fail-loud: an empty `repoRoot`/`harness`/`taskPrompt` throws at construction (no silent
- * default for a required boundary). `resultArtifact()` before `execute()` resolves throws.
+ * Fail-loud: an empty `repoRoot`/`harness`/`taskPrompt` throws at construction. `resultArtifact()`
+ * before `execute()` resolves throws.
  *
  * @experimental
  */
@@ -3252,6 +3278,15 @@ interface DriverTurn {
     readonly toolCalls?: ReadonlyArray<DriverToolCall>;
     /** The driver's natural-language output — the answer when there are no tool calls. */
     readonly content?: string;
+    /** The driver LLM's OWN token usage for THIS turn — metered against the conserved pool so the
+     *  driver's inference counts toward equal-k AND the in-loop budget guard. Omit for a scripted/
+     *  mock turn (no real inference); production `routerDriverChat` forwards it from the router. */
+    readonly usage?: {
+        readonly input: number;
+        readonly output: number;
+    };
+    /** The turn's inference cost (usd), when the provider priced it. */
+    readonly costUsd?: number;
 }
 /** The injected driver-LLM seam: one turn over the conversation + the coordination tool specs. */
 interface DriverChat {
@@ -3278,8 +3313,14 @@ interface CoordinationDriverOptions {
     /** The driver's stance — a string, or built from the task (the worker-driver prompt /
      *  the generator). INJECTED so the prompt is a pluggable, optimizable role. */
     readonly systemPrompt: string | ((task: unknown) => string);
-    /** Max driver turns before the loop force-finalizes on the best settled child. Default 16. */
+    /** Max driver turns before the loop force-finalizes on the best settled child. Default 16.
+     *  `0` lifts the turn-COUNT cap: the loop is bounded instead by the conserved budget pool,
+     *  an absolute deadline, the driver's own stop, and abort (checked in-loop). A finite
+     *  anti-runaway tripwire still guards a degenerate driver that loops on a no-spawn tool. */
     readonly maxTurns?: number;
+    /** Injected clock for the in-loop absolute-deadline guard — keeps the deadline check
+     *  deterministic in tests. Defaults to `Date.now`. */
+    readonly now?: () => number;
 }
 /**
  * Build the intelligent recursive driver. Its `act` is the LLM tool-loop; spawn it as a
@@ -3290,7 +3331,7 @@ declare function coordinationDriverAgent(opts: CoordinationDriverOptions): Agent
 /**
  * @experimental
  *
- * Serve the coordination verbs (spawn_worker / await_next / observe_worker / steer_worker / stop)
+ * Serve the coordination verbs (spawn_worker / await_event / observe_worker / steer_worker / stop)
  * as a real HTTP MCP server over a LIVE `Scope`. This is the keystone that lets a coding-harness
  * agent (opencode via the cli-bridge, claude-code, codex) BE the supervisor: it mounts this MCP
  * (`mcp.mcpServers.coordination`) and calls `spawn_worker` as a native tool, which lands on
@@ -3313,6 +3354,12 @@ interface CoordinationMcpHandle {
         outRef?: string;
     }>;
     isStopped(): boolean;
+    /** The full ordered bus-event log — observability audit + replay trail. */
+    history: CoordinationTools['history'];
+    /** Bus throughput counters for live dashboards. */
+    stats: CoordinationTools['stats'];
+    /** Raise a `finding` on the bus from an online detector watching a worker's live pipe. */
+    raiseFinding: CoordinationTools['raiseFinding'];
     close(): Promise<void>;
 }
 /** Stand up the coordination MCP over a live scope. The HOST address is `127.0.0.1` (the bridge runs
@@ -3324,8 +3371,150 @@ declare function serveCoordinationMcp(opts: {
     perWorker: Budget;
     port?: number;
     host?: string;
+    /** Trace-analyst lenses the driver can run (`run_analyst`) or auto-fire on settle. */
+    analysts?: AnalystRegistry;
+    /** Analyst kinds to auto-run when a worker settles `done` — findings flow up the bus. */
+    analyzeOnSettle?: ReadonlyArray<string>;
+    /** Pass-through subscriber for every bus event (settled / question / finding). */
+    onEvent?: (event: CoordinationEvent) => void | Promise<void>;
+    questionPolicy?: QuestionPolicy;
 }): Promise<CoordinationMcpHandle>;
 
+/**
+ * @experimental
+ *
+ * `TraceSource` — the ONE substrate-agnostic source of a worker's tool-call trace. The online
+ * detectors and the settle-time analyzers consume agent-eval `ToolSpan`s from here, regardless of
+ * whether the worker is:
+ *   - an OWNED tool loop (router-tools, cli-bridge tool dispatch) → push spans as we dispatch them;
+ *   - a SANDBOX / fleet box → read the harness's tool calls off the session (`streamPrompt` parts
+ *     live, `session.messages()` / `findCompletedTurn` at settle).
+ *
+ * The common currency is agent-eval's `ToolSpan` (so the same detectors + `buildTrajectory`/
+ * `stuckLoopView`/`toolWasteView` run over any source). A source exposes two lanes:
+ *   - `onSpan` — live spans for ONLINE detection (best-effort; a black-box box may only collect).
+ *   - `collect` — the full span set at settle for the BATCH analyzers (always available).
+ *
+ * This module imports NO substrate SDK — it decodes generic message parts / OpenAI tool-call shapes.
+ * The sandbox wiring (`sandboxSessionTraceSource`) is the thin adapter that feeds box session parts in.
+ */
+
+interface ToolStepInput {
+    readonly toolName: string;
+    readonly args: unknown;
+    readonly status?: 'ok' | 'error';
+    readonly result?: unknown;
+    /** Stable id of the tool call — used to de-duplicate the repeated state transitions a harness
+     *  streams for one call (opencode emits pending→running→completed, plus a `raw`-wrapped copy). */
+    readonly callId?: string;
+}
+interface TraceSource {
+    /** Subscribe to tool spans as they are produced (ONLINE). Returns an unsubscribe. A source that
+     *  only exposes its trace at the end registers nothing and returns a no-op. */
+    onSpan(handler: (span: ToolSpan) => void): () => void;
+    /** The full set of tool spans for the run (SETTLE / batch). Always available. */
+    collect(): Promise<ToolSpan[]>;
+}
+/** Project a normalized tool step into the canonical agent-eval `ToolSpan`. */
+declare function toToolSpan(input: ToolStepInput, runId: string, seq: number, at: number): ToolSpan;
+/** Decode one harness message part into a tool step, or `undefined` if it is not a (completed) tool
+ *  call. ONE adapter per harness family — each owns its real wire shape; the flow downstream is
+ *  identical. Add a harness = add a decoder + register it; no other code changes. */
+type ToolPartDecoder = (part: Record<string, unknown>) => ToolStepInput | undefined;
+/** opencode (VALIDATED LIVE): `{ type:'tool', tool:'<name>', callID, state:{ status, input } }`.
+ *  The same call streams pending→running→completed/error — only the terminal state decodes. */
+declare const decodeOpencodePart: ToolPartDecoder;
+/** Anthropic / claude-code (also kimi's tool_use variant): a `{ type:'tool_use', id|tool_use_id,
+ *  name|tool, input }` content block. CONFIRMED against the cli-bridge's authoritative parsers
+ *  (claude.ts reads `block.type==='tool_use', block.id, block.name, block.input`; kimi.ts adds the
+ *  `tool_use_id`/`tool` fallbacks) — the canonical readers of these harnesses' real native output. */
+declare const decodeAnthropicPart: ToolPartDecoder;
+/** OpenAI-compatible (router / kimi's top-level form / glm): `{ type:'function'|'tool_call', id,
+ *  function:{ name, arguments:<JSON string> } }`. CONFIRMED against the cli-bridge (kimi.ts surfaces
+ *  kimi's top-level `tool_calls:[{type:'function', id, function:{name,arguments}}]` exactly this way).
+ *  NOTE: codex does NOT emit structured tool calls (the bridge's codex.ts never yields `tool_calls` —
+ *  it runs shell internally and surfaces only text), so per-tool detection is unavailable for codex
+ *  from any path — a harness property, not a decoder gap. */
+declare const decodeOpenAiPart: ToolPartDecoder;
+/** The harness → decoder registry. Add a harness by adding one entry. */
+declare const toolPartDecoders: Record<string, ToolPartDecoder>;
+/** Decode a part with a specific harness's adapter when known, else try every registered adapter
+ *  (the composite — robust to mixed/unknown streams). Never throws. */
+declare function decodeToolPart(part: unknown, harness?: string): ToolStepInput | undefined;
+/** A push source for OWNED tool loops (router-tools / cli-bridge tool dispatch): the loop calls
+ *  `record(step)` for each tool call; it becomes a span, fan-out to live subscribers + buffered for
+ *  `collect`. */
+declare function createPushTraceSource(opts?: {
+    runId?: string;
+    now?: () => number;
+}): {
+    source: TraceSource;
+    record: (input: ToolStepInput) => ToolSpan;
+};
+/** A source backed by harness message PARTS (sandbox session, cli-bridge). `collect` reads the full
+ *  part list and decodes the tool calls; `subscribe`, when given, streams parts live for online
+ *  detection. The caller supplies how to get parts (e.g. `box.session(id).messages()` flat-mapped to
+ *  parts) — keeping this module free of any substrate SDK. */
+declare function createPartsTraceSource(opts: {
+    collectParts: () => Promise<ReadonlyArray<unknown>>;
+    subscribeParts?: (onPart: (part: unknown) => void) => () => void;
+    /** The harness whose decoder to use (e.g. 'opencode'); omit to try every registered adapter. */
+    harness?: string;
+    runId?: string;
+    now?: () => number;
+}): TraceSource;
+/** A harness session message carrying parts (the shape `box.messages()` returns). Structurally typed
+ *  so this works with the real `@tangle-network/sandbox` box AND a test double, no SDK import. */
+interface SessionMessageLike {
+    readonly parts?: ReadonlyArray<unknown>;
+}
+/** The minimal box surface this needs: list a session's messages (incl. mid-turn partials). */
+interface SessionTraceBox {
+    messages(opts: {
+        sessionId: string;
+    }): Promise<ReadonlyArray<SessionMessageLike>>;
+}
+/** The SANDBOX / fleet trace source: read a box session's message parts and decode the harness's tool
+ *  calls into spans. `collect` (settle) is the solid path — `box.messages({sessionId})` → parts → spans;
+ *  black-box harnesses aren't mid-step interruptible, so online steering is the owned-loop's job and a
+ *  live `subscribe` is opt-in (pass `subscribeParts` from `streamPrompt` when the harness streams parts). */
+declare function sandboxSessionTraceSource(box: SessionTraceBox, sessionId: string, opts?: {
+    /** The box's harness (e.g. 'opencode', 'claude-code') → selects its decoder adapter. */
+    harness?: string;
+    subscribeParts?: (onPart: (part: unknown) => void) => () => void;
+    runId?: string;
+    now?: () => number;
+}): TraceSource;
+
+/**
+ * @experimental
+ *
+ * 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.
+ */
+
+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;
+
 /**
  * @experimental
  *
@@ -3407,6 +3596,56 @@ declare const driverExecutorFactory: ExecutorFactory<unknown>;
  */
 declare function withDriverExecutor(base: ExecutorRegistry): ExecutorRegistry;
 
+/**
+ * @experimental
+ *
+ * The worker-side receive end of the down-leg: a per-worker inbox an executor exposes as
+ * `Executor.deliver`. The driver's `steer_worker` / `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.
+ */
+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;
+}
+declare function createInbox(): Inbox;
+
+/**
+ * The router-backed driver-LLM seam: adapt the OpenAI-compatible router's tool-calling chat
+ * to the `DriverChat` port a `coordinationDriverAgent` drives. Tests script a mock `DriverChat`;
+ * production passes `routerDriverChat(cfg)` so the driver's spawn/observe/steer/await/stop turns
+ * are real router tool-calls. This is the one turnkey piece a consumer needs to run an in-process
+ * supervisor (the driver brain) — everything else is `createSupervisor().run(...)`.
+ */
+
+declare function routerDriverChat(c: RouterConfig, opts?: {
+    temperature?: number;
+}): DriverChat;
+
 /**
  * @experimental
  *
@@ -3514,6 +3753,13 @@ interface RouterToolsSeam {
     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. */
+    onToolStep?: (step: {
+        toolName: string;
+        args: Record<string, unknown>;
+        status: 'ok' | 'error';
+    }) => 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. */
@@ -3687,9 +3933,9 @@ declare function settledToIteration<Out>(settled: Settled<Out>): Iteration<unkno
  *    no-winner; it does not restart anything.
  *
  * Selection lives in the driver, not here (selector≠judge): `act` returns the synthesized
- * winner `Out`. The supervisor content-addresses that `Out` for its replay `outRef`,
- * reads `spentTotal` off the conserved pool, and wraps it as a typed `winner` — it does
- * not re-rank children behind the driver's back.
+ * winner `Out`. The supervisor content-addresses that `Out` for its replay `outRef`, reads
+ * `spentTotal` off the journal (`settled` child work + `metered` driver inference), and wraps
+ * it as a typed `winner` — it does not re-rank children behind the driver's back.
  */
 
 declare function createSupervisor<Task, Out>(): Supervisor<Task, Out>;
@@ -3702,6 +3948,29 @@ declare function createSupervisor<Task, Out>(): Supervisor<Task, Out>;
  */
 declare function createRootHandle<Out>(): RootHandle<Out>;
 
+/**
+ * @experimental
+ *
+ * The SETTLE-time analyst: when a worker finishes, collect its tool spans from a `TraceSource` and run
+ * agent-eval's PUBLISHED batch analyzers over them — `buildTrajectory` (structured run summary),
+ * `stuckLoopView` (full-run repeated-call view, complementing the online consecutive detector), and
+ * `toolWasteView`. Substrate-agnostic: the spans come from any source (an owned loop's buffer OR a
+ * sandbox box session). No analysis reimplemented — this is the thin bridge into agent-eval's analyzers.
+ */
+
+interface TrajectoryAnalysis {
+    /** Structured run summary (tool-call count, step order). Steps carry a single timestamp, so per-span
+     *  duration is 0; loop/waste detection keys on call PATTERNS + cross-span windows, not durations. */
+    readonly trajectory: Awaited<ReturnType<typeof buildTrajectory>>;
+    /** Full-run repeated-call view (total occurrences + window) — catches a loop the online consecutive
+     *  detector interleaves past. */
+    readonly stuckLoop: Awaited<ReturnType<typeof stuckLoopView>>;
+    /** Wasted-vs-total tool-call ratio for the run. */
+    readonly toolWaste: Awaited<ReturnType<typeof toolWasteView>>;
+}
+/** Collect the source's spans and run the agent-eval batch analyzers over them under one `runId`. */
+declare function analyzeTrace(source: TraceSource, runId?: string): Promise<TrajectoryAnalysis>;
+
 /**
  * createVerifierEnvironment — ANY checkable task as an `Environment`, no tool surface
  * required. The generalization piece: EOPS/commit0-style domains have tools that mutate
@@ -3797,4 +4066,4 @@ declare function runInWorkspace<T>(ws: Workspace, body: (cwd: string) => Promise
     commitOnInvalid?: boolean;
 }): Promise<WorkspaceRun<T>>;
 
-export { Agent, AgentRunSpec, AgentSpec, type AgenticOptions, type AgenticRunResult, type AgenticSurface, type AgenticTask, type AgenticTool, type AnytimeReport, type AnytimeStrategySummary, type AnytimeTaskCurve, type ArtifactHandle, type AssertTraceDerivedFindings, type AuditIntentInput, type AuditIntentOptions, type AuthorStrategyOptions, type AuthoredCoderHarness, type AuthoredProfile, type AuthoredStrategy, type BenchmarkCell, type BenchmarkConfig, type BenchmarkLift, type BenchmarkReport, type BenchmarkStrategySummary, type BenchmarkTaskRow, type BridgeSeam, Budget, type BudgetPool, type BudgetReadout, type ChampionPick, type ChampionPolicy, type CheckpointCapableBox, type CliSeam, type CliWorktreeSeam, type CoderDeliverableOptions, type CoderWinnerStrategy, type CombinatorShape, type CompletionAnalyst, type CompletionEvidence, type CompletionPolicy, type CompletionVerdict, type CoordinationDriverOptions, type CoordinationMcpHandle, type Corpus, type CorpusFilter, type CorpusRecord, type CreateScopeAnalystOptions, type CriuCapableClient, type DefinePersona, type DefinePersonaInput, type Deliverable, type DeliverableSpec, type DriverChat, type DriverMessage, type DriverToolCall, type DriverTurn, type Environment, type EqualKArm, type EqualKOnCost, type EqualKOnCostOptions, type EqualKVerdict, type EvolutionArchiveNode, type EvolutionAuthor, type EvolutionBandInfo, type EvolutionCandidate, type EvolutionGeneration, type EvolutionReport, ExecCtx, Executor, type ExecutorConfig, ExecutorFactory, ExecutorRegistry, type Fanout, type FanoutOptions, type FanoutSynthesis, type FanoutWinnerSelector, FileCorpus, FileResultBlobStore, FileSpawnJournal, type FlatWidenGate, type ForkCapableBox, type GitWorkspaceOptions, type HarvestCorpusOptions, type HarvestFailure, type HarvestReport, InMemoryCorpus, InMemoryResultBlobStore, InMemorySpawnJournal, type IntentAudit, Iteration, type LoopDispatchOptions, type LoopOptionsForDispatch, LoopResult, type LoopShape, LoopTokenUsage, type LoopUntil, type LoopUntilSpec, type LoopUntilState, type McpEndpoint, type McpEnvironmentOptions, type NestedScopeSeam, NodeId, type Observation, type ObserveInput, type ObserveOptions, type OpenSandboxRunOptions, type Outcome, type Panel, type PanelJudge, type PanelSpec, type PanelVerdict, type Persona, type PersonaContext, type PersonaExecutors, type Pipeline, type PipelineStage, type PromotionGateOptions, type PromotionVerdict, type RegistryAnalyzeProjection, type RenderCorpusToInstructions, type RenderCorpusToInstructionsOptions, type ReservationTicket, ResultBlobStore, RootHandle, RouterConfig, type RouterSeam, type RouterToolsSeam, type RunAgenticOptions, RunLoopOptions, type RunPersonified, type RunPersonifiedOptions, type SandboxCapabilities, SandboxClient, type SandboxLineage, type SandboxLineageHandle, type SandboxRun, type SandboxSeam, Scope, type ScopeAnalyst, type ScopeAnalyzeInput, type ScopeWidenGate, type SessionCapableBox, Settled, type ShapeBudget, type ShapeContext, type ShapeRegistry, type Shell, type ShotPersona, type ShotSpec, SpawnEvent, SpawnJournal, Spend, type SteerContext, type Strategy, type StrategyCtx, type StrategyEvolutionConfig, type StrategyResult, SupervisedResult, Supervisor, type SurfaceScore, ToolSpec, type TrajectoryNode, type TrajectoryReport, type TrajectoryReportFn, type TrajectoryReportOptions, TreeView, type TurnResult, UsageEvent, type UsageSink, type VerifierEnvironmentOptions, type Verify, type VerifySpec, type WaterfallCollector, type WaterfallReport, type WaterfallSpan, type Widen, type WidenDecision, type WidenLineage, type WidenSpec, type Workspace, type WorkspaceCommit, type WorkspaceRun, type WorktreeCliExecutorOptions, type WorktreeCoderFanoutOptions, type WorktreeCommandResult, type WorktreePatchArtifact, acquireSandbox, adaptiveRefine, anytimeReport, asAuthoredProfile, assertStrategyContract, assertTraceDerivedFindings, auditIntent, authorStrategy, authoredWorker, breadthDriver, buildSteerContext, builtinShapes, cliWorktreeExecutor, coderDeliverable, completionAuthorizes, contentAddress, coordinationDriverAgent, createBudgetPool, createExecutor, createExecutorRegistry, createMcpEnvironment, createRootHandle, createSandboxLineage, createScope, createScopeAnalyst, createShapeRegistry, createSupervisor, createVerifierEnvironment, createWaterfallCollector, createWorktreeCliExecutor, defaultAnalystInstruction, defaultAuditorInstruction, definePersona, defineStrategy, depthDriver, deterministicCompletion, discriminatingMeans, driverChild, driverExecutorFactory, driverRuntime, equalKOnCost, extractLlmCallEvent, fanout, flatWidenGate, gateOnDeliverable, gitWorkspace, harvestCorpus, inlineSandboxClient, isDriverSpec, jjWorkspace, localShell, loopDispatch, loopUntil, mapSandboxEvent, materializeTreeView, nestedScopeSeamKey, observe, openSandboxRun, panel, pickChampion, pipeline, printBenchmarkReport, probeSandboxCapabilities, promotionGate, refine, registerShape, registryScopeAnalyst, renderAnytimeTable, renderCorpusToInstructions, renderReport, replaySpawnTree, reportLoopUsage, runAgentic, runBenchmark, runInWorkspace, runPersonified, runStrategyEvolution, sample, sampleThenRefine, selectChampion, sentinelCompletion, serveCoordinationMcp, settledToIteration, spendFromUsageEvents, stopSentinel, strategyAuthorContract, supervisorSkill, trajectoryReport, verify, widen, withDriverExecutor, worktreeCoderFanout };
+export { Agent, AgentRunSpec, AgentSpec, type AgenticOptions, type AgenticRunResult, type AgenticSurface, type AgenticTask, type AgenticTool, type AnytimeReport, type AnytimeStrategySummary, type AnytimeTaskCurve, type ArtifactHandle, type AssertTraceDerivedFindings, type AuditIntentInput, type AuditIntentOptions, type AuthorStrategyOptions, type AuthoredCoderHarness, type AuthoredProfile, type AuthoredStrategy, type BenchmarkCell, type BenchmarkConfig, type BenchmarkLift, type BenchmarkReport, type BenchmarkStrategySummary, type BenchmarkTaskRow, type BridgeSeam, Budget, type BudgetPool, type BudgetReadout, type ChampionPick, type ChampionPolicy, type CheckpointCapableBox, type CliSeam, type CliWorktreeSeam, type CoderDeliverableOptions, type CoderWinnerStrategy, type CombinatorShape, type CompletionAnalyst, type CompletionEvidence, type CompletionPolicy, type CompletionVerdict, type CoordinationDriverOptions, type CoordinationMcpHandle, type Corpus, type CorpusFilter, type CorpusRecord, type CreateScopeAnalystOptions, type CriuCapableClient, type DefinePersona, type DefinePersonaInput, type Deliverable, type DeliverableSpec, type DriverChat, type DriverMessage, type DriverToolCall, type DriverTurn, type Environment, type EqualKArm, type EqualKOnCost, type EqualKOnCostOptions, type EqualKVerdict, type EvolutionArchiveNode, type EvolutionAuthor, type EvolutionBandInfo, type EvolutionCandidate, type EvolutionGeneration, type EvolutionReport, ExecCtx, Executor, type ExecutorConfig, ExecutorFactory, ExecutorRegistry, type Fanout, type FanoutOptions, type FanoutSynthesis, type FanoutWinnerSelector, FileCorpus, FileResultBlobStore, FileSpawnJournal, type FlatWidenGate, type ForkCapableBox, type GitWorkspaceOptions, type HarvestCorpusOptions, type HarvestFailure, type HarvestReport, InMemoryCorpus, InMemoryResultBlobStore, InMemorySpawnJournal, type Inbox, type InboxMessage, type IntentAudit, Iteration, type LoopDispatchOptions, type LoopOptionsForDispatch, LoopResult, type LoopShape, LoopTokenUsage, type LoopUntil, type LoopUntilSpec, type LoopUntilState, type McpEndpoint, type McpEnvironmentOptions, type NestedScopeSeam, NodeId, type Observation, type ObserveInput, type ObserveOptions, type OpenSandboxRunOptions, type Outcome, type Panel, type PanelJudge, type PanelSpec, type PanelVerdict, type Persona, type PersonaContext, type PersonaExecutors, type Pipeline, type PipelineStage, type PromotionGateOptions, type PromotionVerdict, type RegistryAnalyzeProjection, type RenderCorpusToInstructions, type RenderCorpusToInstructionsOptions, type ReservationTicket, ResultBlobStore, RootHandle, RouterConfig, type RouterSeam, type RouterToolsSeam, type RunAgenticOptions, RunLoopOptions, type RunPersonified, type RunPersonifiedOptions, type SandboxCapabilities, SandboxClient, type SandboxLineage, type SandboxLineageHandle, type SandboxRun, type SandboxSeam, Scope, type ScopeAnalyst, type ScopeAnalyzeInput, type ScopeWidenGate, type SessionCapableBox, type SessionMessageLike, type SessionTraceBox, Settled, type ShapeBudget, type ShapeContext, type ShapeRegistry, type Shell, type ShotPersona, type ShotSpec, SpawnEvent, SpawnJournal, Spend, type SteerContext, type Strategy, type StrategyCtx, type StrategyEvolutionConfig, type StrategyResult, SupervisedResult, Supervisor, type SurfaceScore, type ToolPartDecoder, ToolSpec, type ToolStepInput, type TraceSource, type TrajectoryAnalysis, type TrajectoryNode, type TrajectoryReport, type TrajectoryReportFn, type TrajectoryReportOptions, TreeView, type TurnResult, UsageEvent, type UsageSink, type VerifierEnvironmentOptions, type Verify, type VerifySpec, type WatchTraceOptions, type WaterfallCollector, type WaterfallReport, type WaterfallSpan, type Widen, type WidenDecision, type WidenLineage, type WidenSpec, type Workspace, type WorkspaceCommit, type WorkspaceRun, type WorktreeCliExecutorOptions, type WorktreeCoderFanoutOptions, type WorktreeCommandResult, type WorktreePatchArtifact, acquireSandbox, adaptiveRefine, analyzeTrace, anytimeReport, asAuthoredProfile, assertStrategyContract, assertTraceDerivedFindings, auditIntent, authorStrategy, authoredWorker, breadthDriver, buildSteerContext, builtinShapes, cliWorktreeExecutor, coderDeliverable, completionAuthorizes, contentAddress, coordinationDriverAgent, createBudgetPool, createExecutor, createExecutorRegistry, createInbox, createMcpEnvironment, createPartsTraceSource, createPushTraceSource, createRootHandle, createSandboxLineage, createScope, createScopeAnalyst, createShapeRegistry, createSupervisor, createVerifierEnvironment, createWaterfallCollector, createWorktreeCliExecutor, decodeAnthropicPart, decodeOpenAiPart, decodeOpencodePart, decodeToolPart, defaultAnalystInstruction, defaultAuditorInstruction, defaultToolDetectors, definePersona, defineStrategy, depthDriver, deterministicCompletion, discriminatingMeans, driverChild, driverExecutorFactory, driverRuntime, equalKOnCost, extractLlmCallEvent, fanout, flatWidenGate, gateOnDeliverable, gitWorkspace, harvestCorpus, inlineSandboxClient, isDriverSpec, jjWorkspace, localShell, loopDispatch, loopUntil, mapSandboxEvent, materializeTreeView, nestedScopeSeamKey, observe, openSandboxRun, panel, pickChampion, pipeline, printBenchmarkReport, probeSandboxCapabilities, promotionGate, refine, registerShape, registryScopeAnalyst, renderAnytimeTable, renderCorpusToInstructions, renderReport, replaySpawnTree, reportLoopUsage, routerDriverChat, runAgentic, runBenchmark, runInWorkspace, runPersonified, runStrategyEvolution, sample, sampleThenRefine, sandboxSessionTraceSource, selectChampion, sentinelCompletion, serveCoordinationMcp, settledToIteration, spendFromUsageEvents, stopSentinel, strategyAuthorContract, supervisorSkill, toToolSpan, toolPartDecoders, trajectoryReport, verify, watchTrace, widen, withDriverExecutor, worktreeCoderFanout };