@tangle-network/agent-runtime 0.52.0 → 0.54.0

package/dist/runtime.d.ts

@@ -1,17 +1,21 @@
 import { AgentProfile, BackendType, CreateSandboxOptions, SandboxInstance, SandboxEvent } from '@tangle-network/sandbox';
 export { AgentProfile, CreateSandboxOptions, SandboxEvent, SandboxInstance } from '@tangle-network/sandbox';
-import { R as ResultBlobStore, a as SpawnJournal, N as NodeId, b as SpawnEvent, T as TreeView, c as Settled, d as AgentSpec, E as ExecutorRegistry, B as Budget, A as Agent, e as RootHandle, f as SupervisedResult, g as Spend, S as Scope, h as ExecutorFactory, U as UsageEvent, i as Supervisor } from './types-5MGt5KTY.js';
-export { j as Executor, k as ExecutorContext, l as ExecutorResult, H as Handle, m as NodeSnapshot, n as NodeStatus, o as Restart, p as RootSignal, q as Runtime, r as SpawnOpts, s as SupervisorOpts, W as WidenGate } from './types-5MGt5KTY.js';
+import { R as ResultBlobStore, p as SpawnJournal, N as NodeId, q as SpawnEvent, T as TreeView, r as Settled, s as AgentSpec, E as ExecutorRegistry, B as Budget, t as Agent, u as RootHandle, v as SupervisedResult, w as Spend, x as Scope, y as ExecutorFactory, z as Executor, U as UsageEvent, M as MakeWorkerAgent, D as Supervisor } from './coordination-BMzskrUR.js';
+export { G as ExecutorContext, H as ExecutorResult, K as Handle, L as NodeSnapshot, O as NodeStatus, P as Restart, V as RootSignal, W as Runtime, X as SpawnOpts, Y as SupervisorOpts, Z as WidenGate } from './coordination-BMzskrUR.js';
 import { R as RuntimeHooks } from './runtime-hooks-C7JwKb9E.js';
 import { ChatClient, AnalystFinding, DefaultVerdict, AgentProfile as AgentProfile$1, AnalystRunInputs } from '@tangle-network/agent-eval';
 export { DefaultVerdict } from '@tangle-network/agent-eval';
-export { A as AnalyzeInput, a as CompletionAnalyst, b as CompletionEvidence, c as CompletionPolicy, d as CompletionVerdict, C as CreateDriverOptions, D as DriverDecision, P as PlannerContext, e as TopologyMove, T as TopologyPlanner, f as completionAuthorizes, g as createDriver, h as deterministicCompletion, r as renderAnalyses, s as sentinelCompletion, i as stopSentinel } from './driver-DLI1io57.js';
-import { S as SandboxClient, b as LoopResult, d as LoopTokenUsage, R as RuntimeStreamEvent, A as AgentRunSpec, E as ExecCtx, I as Iteration } from './types-BEQsBhOE.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, e as LoopSandboxPlacement, Q as LoopStartedPayload, T as LoopTeardownFailedPayload, f as LoopTraceEmitter, g as LoopTraceEvent, L as LoopWinner, O as OutputAdapter, U as ValidationCtx, V as Validator } from './types-BEQsBhOE.js';
+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 { Scenario, ProfileDispatchFn } from '@tangle-network/agent-eval/campaign';
-import { R as RunLoopOptions } from './run-loop-BIineL1T.js';
-export { c as createSandboxForSpec, d as defaultSelectWinner, r as runLoop } from './run-loop-BIineL1T.js';
+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 { 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 './delegates-BPLIl8EC.js';
+import './coder-CEkUFv8h.js';
+import './substrate-CUgk7F7s.js';
 
 /**
  * @experimental
@@ -310,6 +314,85 @@ interface IntentAudit {
 declare const defaultAuditorInstruction: string;
 declare function auditIntent(input: AuditIntentInput, opts: AuditIntentOptions): Promise<IntentAudit>;
 
+/**
+ * @experimental
+ *
+ * Completion / satisfiability — the OTHER output of the pluggable analyst (the steer output
+ * is `AnalystFinding[]` via the `analyze` hook; this is the "is it done?" output via the
+ * `complete` hook). A `CompletionAnalyst` reads a node's trace and returns a `CompletionVerdict`
+ * the PARENT (driver) acts on: end the node, or keep going. It fits ANY node and composes to
+ * any depth — a 1-deep loop has one; an N-deep tree has one per node.
+ *
+ * The verdict's authority scales with its DETERMINISM (the thing that varies by task):
+ *   - `deterministic` — build/test/lint pass, a proof checks, every claim's citation resolves:
+ *     ground truth, the driver TRUSTS it and ends. Not an opinion.
+ *   - `probabilistic` — a quality/soundness judgment (marketing, "the experiment is sound"):
+ *     ADVISORY. It passes to the driver with its reasons; the driver validates (here: a
+ *     confidence threshold; a richer driver may re-examine the reasons) before ending.
+ *
+ * Two stop-signal mechanisms, by node mode, both → one `CompletionVerdict`:
+ *   - sandbox-agent (text stream): a unique per-node STOP SENTINEL the agent emits when done
+ *     (`stopSentinel` / `sentinelCompletion`) — ralph-loop style; the seed makes it
+ *     unguessable + attributable, so it can't be spuriously emitted or confused with content.
+ *   - deterministic check (compile/test/citation/proof): `deterministicCompletion(check)` —
+ *     a verifier over the output, never the judge verdict (selector ≠ judge holds).
+ */
+
+/** Trace-derived evidence for a completion claim — an artifact (output) or a verifier metric,
+ *  never the judge's own verdict. Mirrors the steer-firewall's provenance discipline. */
+interface CompletionEvidence {
+    kind: 'artifact' | 'metric';
+    uri: string;
+}
+/** The "is it done?" verdict an analyst returns to the parent. */
+interface CompletionVerdict {
+    done: boolean;
+    /** How verifiable the claim is — sets whether the driver trusts it or validates it. */
+    determinism: 'deterministic' | 'probabilistic';
+    /** Why the analyst believes it is (or isn't) done — what the driver validates. */
+    reasons?: string;
+    /** 0..1, for probabilistic verdicts; the driver's validation threshold reads this. */
+    confidence?: number;
+    evidence?: ReadonlyArray<CompletionEvidence>;
+}
+/** Reads a node's trace → a completion verdict. Same input shape as the `analyze` hook, so
+ *  ONE analyst node can back both channels (findings for steer, a verdict for stop). */
+interface CompletionAnalyst<Task, Output> {
+    assess(input: {
+        task: Task;
+        history: ReadonlyArray<Iteration<Task, Output>>;
+    }): CompletionVerdict | Promise<CompletionVerdict>;
+}
+/** When a verdict authorizes the driver to END. Deterministic → trust (ground truth);
+ *  probabilistic → validate by confidence threshold (the driver's check). */
+interface CompletionPolicy {
+    /** Minimum confidence a PROBABILISTIC verdict must clear to end. Default 0.8. */
+    minConfidence?: number;
+}
+declare function completionAuthorizes(v: CompletionVerdict, policy?: CompletionPolicy): boolean;
+/**
+ * A unique, attributable stop sentinel for a node (ralph-loop style). Deterministic from the
+ * seed (no Math.random — reproducible + attributable to the node); the agent is instructed to
+ * emit it VERBATIM when it judges itself done. Unguessable enough that content never trips it.
+ */
+declare function stopSentinel(seed: string): string;
+/**
+ * Completion for a sandbox-agent node: done iff the latest output carries the node's stop
+ * sentinel. PROBABILISTIC (the agent's own self-judgment) — the driver validates it.
+ */
+declare function sentinelCompletion<Task>(sentinel: string, opts?: {
+    confidence?: number;
+}): CompletionAnalyst<Task, string>;
+/**
+ * Completion for a DETERMINISTIC check (build/test/lint/citation/proof): done iff the check
+ * passes. Ground truth — the driver ends directly, no validation. The check reads the output
+ * (a verifier), never the judge verdict — selector ≠ judge stays intact.
+ */
+declare function deterministicCompletion<Task, Output>(check: (output: Output, history: ReadonlyArray<Iteration<Task, Output>>) => {
+    passed: boolean;
+    reasons?: string;
+}): CompletionAnalyst<Task, Output>;
+
 /**
  * @experimental
  *
@@ -528,6 +611,12 @@ interface RunPersonifiedOptions<Task, D> {
     /** Optional scope analyst threaded into the shape's ShapeContext so loopUntil/widen steer
      *  on trace-derived findings instead of the dormant empty default. */
     readonly analyst?: ScopeAnalyst<D>;
+    /**
+     * Lifecycle stream sink, forwarded to `SupervisorOpts.hooks` so the root `Scope`'s
+     * `agent.spawn`/`agent.child` events flow to an observer (e.g. the Intelligence SDK's
+     * trace export). Absent ⇒ no stream (the run is silent, as today).
+     */
+    readonly hooks?: RuntimeHooks;
 }
 /** The composed run signature. */
 type RunPersonified = <Task, D>(options: RunPersonifiedOptions<Task, D>) => Promise<SupervisedResult<Outcome<D>>>;
@@ -818,8 +907,7 @@ interface ScopeAnalyst<D> {
      */
     analyze(input: ScopeAnalyzeInput<D>): Promise<ReadonlyArray<AnalystFinding>>;
 }
-/** Input to a `ScopeAnalyst.analyze` — the root task framing + the children settled so far. The
- *  reactive analogue of the old `AnalyzeInput { task, history }`. */
+/** Input to a `ScopeAnalyst.analyze` — the root task framing + the children settled so far. */
 interface ScopeAnalyzeInput<D> {
     /** Opaque root-task framing (whatever the combinator was invoked with). */
     readonly task: unknown;
@@ -1122,7 +1210,7 @@ declare function renderReport(findings: ReadonlyArray<AnalystFinding>): string;
  *
  * NOTE on the read side: harvesting is safe and cheap; *injecting* facts back into runs
  * is the measured danger zone — naive unconditional priming tested NEGATIVE (−11.6pp,
- * context pollution; docs/research/layer-across-run.md). Gate any priming design on its
+ * context pollution; result now in .evolve/current.json + memory). Gate any priming design on its
  * own A/B; the corpus's first consumers are operators and optimizers, not prompts.
  */
 
@@ -1588,16 +1676,14 @@ declare function createMcpEnvironment(opts: McpEnvironmentOptions): Environment;
 /**
  * @experimental
  *
- * Analyst-on-scope (G1) — the PORT of the round-synchronous driver's analyze→findings→steer
- * wire (`dynamic.ts`) onto the reactive `Scope`.
+ * Analyst-on-scope (G1) — the analyze→findings→steer wire over the reactive `Scope`.
  *
- * The old dynamic driver wired the analyst at round boundaries: `plan` ran the analyst over
- * `history` BEFORE the planner and handed the findings forward via `PlannerContext.analyses`,
- * behind a provenance firewall (`assertTraceDerivedFindings`) that keeps the external write-only
- * judge out of the steer decision (selector ≠ judge). The reactive `Scope` has no rounds, so this
- * module carries the same wire across: a combinator's `act` asks a `ScopeAnalyst` to turn the
- * children it has drained off `scope.next()` SO FAR into `AnalystFinding[]`, and steers from THOSE
- * findings through a single `SteerContext`.
+ * The analyst runs over the children drained so far and hands its findings to the steer
+ * decision behind a provenance firewall (`assertTraceDerivedFindings`) that keeps the external
+ * write-only judge out of that decision (selector ≠ judge). The reactive `Scope` has no rounds:
+ * a combinator's `act` asks a `ScopeAnalyst` to turn the children it has drained off
+ * `scope.next()` SO FAR into `AnalystFinding[]`, and steers from THOSE findings through a single
+ * `SteerContext`.
  *
  * The analyst itself is not a new type — it is "just an `Agent<unknown, AnalystFinding[]>`" the
  * combinator spawns over a child's trace (harness `null`/`cli`). `createScopeAnalyst` spawns that
@@ -2035,117 +2121,6 @@ interface UsageSink {
  */
 declare function reportLoopUsage<Task, Output, Decision>(cost: UsageSink, result: Pick<LoopResult<Task, Output, Decision>, 'costUsd' | 'tokenUsage'>, source?: string): void;
 
-/**
- * The one router chat client: direct OpenAI-compatible completions through the
- * Tangle router — the cheapest dial, no sandbox. Three layers: `routerChatWithUsage`
- * (chat-only), `routerChatWithTools` (one completion with function tools), and
- * `routerToolLoop` (the off-box agentic loop over tool-calling). Shared by the
- * built-in executors and the bench/lab harnesses.
- *
- * Reports REAL token usage so the backend-integrity guard sees a real backend.
- * Returns `undefined` usage when the provider omitted it — never a fabricated 0
- * (a phantom 0 reads as a free call downstream, which the gate would act on).
- */
-interface RouterConfig {
-    routerBaseUrl: string;
-    routerKey: string;
-    model: string;
-}
-interface RouterChatResult {
-    content: string;
-    /** REAL usage, or undefined when the provider reported none. */
-    usage?: {
-        input: number;
-        output: number;
-    };
-    /** Derived from usage via `estimateCost` when the model is priced; else undefined. */
-    costUsd?: number;
-}
-declare function routerChatWithUsage(cfg: RouterConfig, messages: Array<{
-    role: string;
-    content: string;
-}>, opts?: {
-    temperature?: number;
-    signal?: AbortSignal;
-    maxTokens?: number;
-}): Promise<RouterChatResult>;
-/** A tool-call the model emitted (provider-neutral; mirrors the runtime's ToolCallRequest). */
-interface RouterToolCall {
-    id: string;
-    name: string;
-    /** Raw JSON arguments string as emitted by the model. */
-    arguments: string;
-}
-interface RouterChatToolsResult {
-    content: string | null;
-    toolCalls: RouterToolCall[];
-    usage?: {
-        input: number;
-        output: number;
-    };
-    costUsd?: number;
-}
-/**
- * A router completion WITH tool-calling — the operator driver's LLM seam. Passes OpenAI-shape
- * `messages` (system/user/assistant-with-tool_calls/tool roles) + function `tools`, and returns the
- * assistant text plus the tool calls the model wants run. Same fail-loud + real-usage discipline as
- * `routerChatWithUsage`. `tool_choice: 'auto'` lets the model decide; the driver loops on the result.
- */
-declare function routerChatWithTools(cfg: RouterConfig, messages: ReadonlyArray<Record<string, unknown>>, tools: ReadonlyArray<{
-    type: 'function';
-    function: {
-        name: string;
-        description?: string;
-        parameters: unknown;
-    };
-}>, opts?: {
-    temperature?: number;
-    signal?: AbortSignal;
-    toolChoice?: 'auto' | 'required' | 'none';
-}): Promise<RouterChatToolsResult>;
-interface ToolSpec {
-    type: 'function';
-    function: {
-        name: string;
-        description?: string;
-        parameters: unknown;
-    };
-}
-interface RouterToolLoopResult {
-    /** The model's final assistant text (the turn where it stopped calling tools, or the budget turn). */
-    final: string;
-    /** Inference turns spent (≤ maxTurns) — the equal-budget unit vs random@k. */
-    turns: number;
-    toolCalls: number;
-    /** The behavior trace: each tool call + its result, in order. What a trace-analyst
-     *  steerer reads (behavior, never the verdict) to diagnose + redirect the next shot. */
-    toolTrace: Array<{
-        name: string;
-        args: string;
-        result: string;
-    }>;
-    usage: {
-        input: number;
-        output: number;
-    };
-}
-/**
- * The tool-using router backend: a real agentic loop OVER the Tangle router (which
- * supports tool-calling), off-box — no sandbox. Each turn is one router completion
- * with `tools`; if the model emits tool_calls, `execute` runs them on the host and
- * their results are folded back as `tool` messages; the loop repeats until the
- * model answers without a tool call or the turn budget is hit. One turn = one
- * inference call, so `maxTurns` is the equal-compute unit against random@k.
- *
- * This is the depth substrate for agentic gates (the worker ACTS, observes the real
- * result, and continues) that the chat-only `routerChatWithUsage` cannot express.
- */
-declare function routerToolLoop(cfg: RouterConfig, system: string, user: string, tools: ReadonlyArray<ToolSpec>, execute: (name: string, args: Record<string, unknown>) => Promise<string>, opts?: {
-    maxTurns?: number;
-    temperature?: number;
-    signal?: AbortSignal;
-}): Promise<RouterToolLoopResult>;
-
 /**
  * @experimental
  *
@@ -2821,6 +2796,82 @@ declare function pickChampion(means: Record<string, {
 declare function selectChampion(report: BenchmarkReport, fieldOrder: string[], policy: ChampionPolicy, epsilon: number): ChampionPick;
 declare function runStrategyEvolution(cfg: StrategyEvolutionConfig): Promise<EvolutionReport>;
 
+/**
+ * @experimental
+ *
+ * The completion-oracle: **settled ⟺ DELIVERED.**
+ *
+ * Foreman's one hard lesson (0/18 self-improvement deliverables) — "done" must mean a check
+ * PASSED, not the agent's say-so. `gateOnDeliverable` wraps an `Executor` so its settlement
+ * is `valid` ONLY when the deliverable check passes. The child still RUNS and settles (its
+ * spend is conserved into the pool either way), but a child that ran WITHOUT delivering
+ * settles `valid:false` — so a keep-best driver never counts it as done, and a gate never
+ * inflates with self-judged wins.
+ *
+ * Dual-purpose by construction:
+ *  - product: the agent fleet only advances on real, checked deliverables.
+ *  - proof: the gate's `valid` is the honest settle — equal-k comparisons can't be gamed by an
+ *    arm that "ran" without producing the artifact.
+ *
+ * The check is a DEPLOYABLE oracle — a test command, a state verifier, the commit0 judge —
+ * read off the child's output, never the model judging itself. A throwing check is
+ * fail-closed (not delivered), never a crash.
+ */
+
+interface DeliverableSpec<Out = unknown> {
+    /** The deployable check that decides DELIVERED. `settled.valid ⟺ this resolves true`. */
+    check: (out: Out) => boolean | Promise<boolean>;
+    /** What the spawn was supposed to produce — surfaced in traces/reports. */
+    describe?: string;
+}
+/**
+ * Wrap an `Executor` so its settlement `valid` reflects the deliverable check, not the
+ * inner verdict. Handles both `execute` shapes (one-shot `Promise<ExecutorResult>` and
+ * streaming `AsyncIterable<UsageEvent>` + `resultArtifact()`); the check runs once the inner
+ * executor has produced its output. The inner `score` is preserved; only `valid` is gated.
+ */
+declare function gateOnDeliverable<Out>(inner: Executor<Out>, deliverable: DeliverableSpec<Out>): Executor<Out>;
+
+/**
+ * @experimental
+ *
+ * The supervisor's intelligence is AUTHORING the agents it spawns — not pressing buttons.
+ *
+ * Every agent here is three things: instructions (system prompt), tools, and a model — its
+ * `AgentProfile`. The supervisor's job is to WRITE those profiles: read the task, decompose it,
+ * and for each sub-task author a tailored worker recipe. `supervisorSkill` is the how-to the
+ * supervisor reads (its system prompt); `authoredWorker` builds a worker AGENT from a profile the
+ * supervisor authored — the authored systemPrompt + model shape the worker's call.
+ *
+ * The skill is the single OPTIMIZABLE surface: edit it → the supervisor designs better agents.
+ * That is the self-improvement lever (the prompt/skill lever), not the execution plumbing.
+ */
+
+/** What the supervisor AUTHORS per sub-task — a worker recipe (a partial `AgentProfile`). */
+interface AuthoredProfile {
+    name: string;
+    /** The rich, task-specific instructions the supervisor wrote for THIS worker. */
+    systemPrompt: string;
+    /** The model the supervisor chose for this sub-task (falls back to the run default). */
+    model?: string;
+}
+/** Narrow an untyped `spawn_worker` profile argument to an `AuthoredProfile`, or null if the
+ *  supervisor failed to author one (empty/placeholder profile — a skill violation worth catching). */
+declare function asAuthoredProfile(raw: unknown): AuthoredProfile | null;
+/** The supervisor SKILL — the how-to the supervisor reads (its system prompt). THE optimizable
+ *  surface: editing this changes how the supervisor designs every agent it spawns. */
+declare function supervisorSkill(opts?: {
+    goal?: string;
+}): string;
+/** Build a worker AGENT from a profile the supervisor authored: the authored `systemPrompt` +
+ *  `model` shape the worker's one model call; the deliverable gates settlement (valid ⟺ delivered). */
+declare function authoredWorker(profile: AuthoredProfile, opts: {
+    cfg: RouterConfig;
+    taskPrompt: string;
+    deliverable: DeliverableSpec;
+    temperature?: number;
+}): Agent<unknown, unknown>;
+
 /**
  * @experimental
  *
@@ -2903,6 +2954,206 @@ declare function spendFromUsageEvents(events: UsageEvent[]): Spend;
  */
 declare function createBudgetPool(root: Budget, now?: () => number): BudgetPool;
 
+/**
+ * @experimental
+ *
+ * `coordinationDriverAgent` — the driver's BRAIN.
+ *
+ * The recursive driver-executor (`driver-executor.ts`) runs a driver `Agent.act` inside a
+ * nested `Scope`; this is the intelligent `act`: it mounts the coordination MCP verbs
+ * (`createCoordinationTools`) over that scope and runs an LLM tool-loop, so the driver
+ * REASONS — spawn / observe / steer / await / stop — about how to drive its children,
+ * instead of running a fixed script. Each turn: ask the driver LLM for tool calls, run them
+ * against the live scope, fold the results back, repeat until the driver stops (no tool
+ * calls) or the turn cap forces a keep-best finalize.
+ *
+ * Recursion composes through `makeWorkerAgent`: `spawn_worker` resolves a `profile` to a
+ * worker LEAF or — when the profile is a driver — a `driverChild` wrapping ANOTHER
+ * `coordinationDriverAgent` over its own nested scope (see `driver-executor.ts`). So an agent
+ * drives an agent that drives an agent, each an LLM tool-loop, all on one conserved-budget
+ * tree.
+ *
+ * Two seams are INJECTED so the loop runs offline with no creds and stays decoupled:
+ *  - `chat` (`DriverChat`) — one driver-LLM turn; a test drives a scripted mock, production
+ *    adapts the router's tool-calling.
+ *  - `systemPrompt` — the driver's stance (the agent-eval worker-driver prompt / the prompt
+ *    generator). Injected, never hardcoded — the prompt is a pluggable role.
+ */
+
+/** One tool call the driver LLM asks for this turn. */
+interface DriverToolCall {
+    readonly id?: string;
+    readonly name: string;
+    readonly arguments: Record<string, unknown>;
+}
+/** A turn in the driver↔tools conversation. Tool results ride back as `role: 'tool'`. */
+interface DriverMessage {
+    readonly role: 'user' | 'assistant' | 'tool';
+    readonly content: string;
+    readonly toolCalls?: ReadonlyArray<DriverToolCall>;
+    readonly toolCallId?: string;
+    readonly name?: string;
+}
+/** What the driver LLM returns each turn. No `toolCalls` => the driver is finished. */
+interface DriverTurn {
+    readonly toolCalls?: ReadonlyArray<DriverToolCall>;
+    /** The driver's natural-language output — the answer when there are no tool calls. */
+    readonly content?: string;
+}
+/** The injected driver-LLM seam: one turn over the conversation + the coordination tool specs. */
+interface DriverChat {
+    next(input: {
+        readonly system: string;
+        readonly messages: ReadonlyArray<DriverMessage>;
+        readonly tools: ReadonlyArray<{
+            name: string;
+            description: string;
+            parameters: unknown;
+        }>;
+    }): Promise<DriverTurn>;
+}
+interface CoordinationDriverOptions {
+    readonly name: string;
+    /** The driver-LLM seam (scripted mock offline; router tool-calling in production). */
+    readonly chat: DriverChat;
+    /** Shared blob store — `observe_worker` reads settled outputs through it. */
+    readonly blobs: ResultBlobStore;
+    /** Resolve a spawned `profile` to a worker LEAF or a driver child (the recursion seam). */
+    readonly makeWorkerAgent: MakeWorkerAgent;
+    /** Per-child budget reserved from the conserved pool on each spawn. */
+    readonly perWorker: Budget;
+    /** 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. */
+    readonly maxTurns?: number;
+}
+/**
+ * Build the intelligent recursive driver. Its `act` is the LLM tool-loop; spawn it as a
+ * `driverChild` (`driver-executor.ts`) to run it inside a nested scope, recursively.
+ */
+declare function coordinationDriverAgent(opts: CoordinationDriverOptions): Agent<unknown, unknown>;
+
+/**
+ * @experimental
+ *
+ * Serve the coordination verbs (spawn_worker / await_next / 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
+ * `Scope.spawn` — a real box driving real boxes, not emulated function-tools.
+ *
+ * Transport: JSON-RPC over HTTP POST (the MCP streamable-HTTP shape — `application/json` for a
+ * single response). The server is created INSIDE an agent's `act(task, scope)` so it fronts that
+ * agent's live scope; tear it down when the act returns.
+ */
+
+interface CoordinationMcpHandle {
+    /** The URL an in-box harness mounts as `mcp.mcpServers.coordination.url`. */
+    readonly url: string;
+    readonly port: number;
+    /** The coordination tools' settled-worker ledger (for the driver's finalize). */
+    settled(): ReadonlyArray<{
+        status: string;
+        score?: number;
+        valid?: boolean;
+        outRef?: string;
+    }>;
+    isStopped(): boolean;
+    close(): Promise<void>;
+}
+/** Stand up the coordination MCP over a live scope. The HOST address is `127.0.0.1` (the bridge runs
+ *  opencode locally, same host); pass `host` to bind elsewhere when the harness is remote. */
+declare function serveCoordinationMcp(opts: {
+    scope: Scope<unknown>;
+    blobs: ResultBlobStore;
+    makeWorkerAgent: MakeWorkerAgent;
+    perWorker: Budget;
+    port?: number;
+    host?: string;
+}): Promise<CoordinationMcpHandle>;
+
+/**
+ * @experimental
+ *
+ * The recursive driver-executor — the seam that lets a SPAWNED child be a DRIVER, so
+ * agents drive agents drive agents over the one keystone atom.
+ *
+ * A spawned child resolves through the open registry to an `Executor`; the built-in
+ * executors (router/inline, sandbox, cli) are LEAVES — `execute(task, signal)` runs the
+ * work and settles. This executor is the recursive case: on `execute`, it mounts a NESTED
+ * `Scope` (the scope hands it the mount via the `nested-scope` seam) over the SAME
+ * conserved pool + shared journal/blobs + the same open registry, one `depth` deeper, then
+ * runs the wrapped driver `Agent.act(task, nestedScope)`. The driver spawns its own
+ * children into that nested scope; each resolves to EITHER a leaf executor (a worker child)
+ * OR this same driver-executor (a driver child) — recursively. So a driver spawns a driver
+ * spawns a worker, all on one budget-conserving tree.
+ *
+ * Why this preserves every keystone invariant (the scope owns the sharing; this executor
+ * only runs the driver over what the scope mounts):
+ *  - Conserved budget: the nested scope reserves from the SAME `BudgetPool` the root owns
+ *    (the scope mounts it over `args.pool`), so `Σk` is conserved ACROSS depth by
+ *    construction — a deep tree cannot overspend the root ceiling (reserve-on-spawn fails
+ *    closed at any depth).
+ *  - Journal: the nested scope writes to its OWN tree key (`${journalRoot}/${nodeId}`) so
+ *    its cursor `seq`s never collide with the parent's in the per-tree uniqueness guard,
+ *    while every nested tree shares the one `SpawnJournal` — the whole recursion is one
+ *    journal, queryable tree by tree.
+ *  - Settlement bubbling: the driver child settles into its PARENT scope with the conserved
+ *    spend summed off its nested tree's settled events, so the parent's pool reconcile +
+ *    the supervisor's `spentTotal` see the whole sub-tree's spend rolled up — settlements
+ *    bubble to the root.
+ *  - Depth ceiling: the nested scope runs at `depth+1`, so the supervisor's `maxDepth`
+ *    (paired with the conserved pool per R3) fails a spawn closed once the recursion is too
+ *    deep — exactly as it does for a flat tree.
+ *
+ * Layering: pure keystone composition. It reuses the scope's `NestedScopeSeam` + the shared
+ * `SpawnJournal`; it builds NO new budget, journal, or selection logic. The recursion rides
+ * the existing atom.
+ */
+
+/** The runtime tag the registry maps a driver child to. */
+declare const driverRuntime: "driver";
+/** A driver child's spec carries the `Agent` to run inside the nested scope. */
+interface DriverSpec extends AgentSpec {
+    readonly driver: Agent<unknown, unknown>;
+    /** The shared journal the nested tree is one tree key inside (so the executor can
+     *  begin its nested tree + sum its spend off the same record). */
+    readonly journal: SpawnJournal;
+}
+/**
+ * Mark + carry a driver `Agent` so the recursive registry resolves it to the
+ * driver-executor. The returned agent is SPAWNED (never run directly): its
+ * `executorSpec` is marked `role: 'driver'` and carries the driver agent + the shared
+ * journal so the executor can run its `act` inside a nested scope. `act` fails loud if
+ * called directly — a driver child runs THROUGH its nested-scope executor, never as a root.
+ */
+declare function driverChild<Out>(name: string, driver: Agent<unknown, Out>, journal: SpawnJournal): Agent<unknown, Out>;
+/** True when a spec is a driver child (carries the role marker + a driver Agent). */
+declare function isDriverSpec(spec: AgentSpec): spec is DriverSpec;
+/**
+ * The recursive driver-executor factory. `withDriverExecutor` routes a child marked
+ * `role: 'driver'` here; any other child resolves to a leaf built-in. On `execute`, it
+ * reads the `nested-scope` seam the SCOPE seeded, mounts a nested `Scope` one `depth`
+ * deeper over the shared pool/journal/blobs/registry, runs the driver
+ * `Agent.act(task, nestedScope)`, and reports the conserved spend summed off the nested
+ * tree's settled events — so the parent scope's reconcile rolls the whole sub-tree's spend
+ * into the conserved total.
+ *
+ * A `down` from the nested driver (a thrown `act` or an aborted scope) propagates as a
+ * thrown executor, which the parent scope types into a `down` settlement — the same
+ * fail-loud-into-typed-down discipline a leaf gets.
+ */
+declare const driverExecutorFactory: ExecutorFactory<unknown>;
+/**
+ * Register the driver-executor so a child marked `role: 'driver'` resolves to it. The base
+ * registry resolves by harness alone (it does not read `role`), so a recursive run needs a
+ * registry that routes the driver tag here FIRST. Returns a registry decorator: a
+ * driver-role spec → the driver-executor; everything else → the base registry's resolution
+ * (leaf built-ins + BYO).
+ */
+declare function withDriverExecutor(base: ExecutorRegistry): ExecutorRegistry;
+
 /**
  * @experimental
  *
@@ -3090,6 +3341,32 @@ interface ScopeArgs {
      *  (the topology viewer reads it). Undefined ⇒ the journal stays the only record. */
     readonly hooks?: RuntimeHooks;
 }
+/**
+ * The recursion seam key. A `Scope` seeds a value of this on each child's
+ * `ExecutorContext.seams` so a child whose executor is a DRIVER can mount a NESTED `Scope`
+ * over the SAME conserved pool at `depth+1`. A leaf executor never reads it. Single-sourced
+ * here so the scope and the driver-executor agree on the seam without a circular import.
+ */
+declare const nestedScopeSeamKey = "nested-scope";
+/**
+ * The recursion seam value: mount a nested `Scope` for a driver child. `parentId` is the
+ * driver child's own node id (so its children get `${nodeId}:s${ordinal}` ids and its
+ * nested journal tree is namespaced under it); `root` is the journal tree key for the
+ * nested tree (distinct from the parent's so cursor seqs never collide in the per-tree
+ * guard). `depth` is `parent.depth + 1`. The nested scope shares the parent's `pool`
+ * (conserved budget across depth), `journal`/`blobs` (one record), and `executors` (a
+ * nested child resolves to leaf-or-driver through the same open registry).
+ */
+interface NestedScopeSeam {
+    /** This scope's recursion depth — a nested scope runs at `depth + 1`. */
+    readonly depth: number;
+    /** The runtime recursion-depth ceiling, paired with the conserved pool (R3). */
+    readonly maxDepth?: number;
+    /** The journal tree key the parent scope writes to (used to namespace nested trees). */
+    readonly journalRoot: NodeId;
+    /** Mount a nested scope rooted at `nestedRoot`, parented at this driver child's node id. */
+    mount(nestedRoot: NodeId, signal: AbortSignal): Scope<unknown>;
+}
 declare function createScope<Out>(args: ScopeArgs): Scope<Out>;
 /**
  * The step-8 merge-boundary adapter (M4): rehydrate a `Settled.done` into the kernel's
@@ -3222,5 +3499,26 @@ declare function gitWorkspace(opts: GitWorkspaceOptions): Workspace;
  *  no staging area, and a first-class operation log (native resume/undo). Live use
  *  requires `jj` on the `Shell`'s host. */
 declare function jjWorkspace(opts: GitWorkspaceOptions): Workspace;
+interface WorkspaceRun<T> {
+    readonly valid: boolean;
+    readonly value: T;
+    /** Present when a commit was attempted (valid, or `commitOnInvalid`). */
+    readonly commit?: WorkspaceCommit;
+}
+/**
+ * Run a worker `body` inside a FRESH clone of a shared `Workspace`, then commit its work back
+ * so the next worker (or the supervisor) builds on it. This is the seam that turns isolated
+ * per-worker cwds into one compounding artifact — `body` gets a real materialized dir, its
+ * delivery is committed to the shared ref iff it's valid (a conflict is returned, never thrown).
+ * The clone is removed after; durable state lives only in the ref.
+ */
+declare function runInWorkspace<T>(ws: Workspace, body: (cwd: string) => Promise<{
+    valid: boolean;
+    value: T;
+    message?: string;
+}>, opts?: {
+    tmpPrefix?: string;
+    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 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 CombinatorShape, type Corpus, type CorpusFilter, type CorpusRecord, type CreateScopeAnalystOptions, type CriuCapableClient, type DefinePersona, type DefinePersonaInput, type Deliverable, type Environment, type EqualKArm, type EqualKOnCost, type EqualKOnCostOptions, type EqualKVerdict, type EvolutionArchiveNode, type EvolutionAuthor, type EvolutionBandInfo, type EvolutionCandidate, type EvolutionGeneration, type EvolutionReport, ExecCtx, type ExecutorConfig, ExecutorFactory, ExecutorRegistry, type Fanout, type FanoutOptions, type FanoutSynthesis, 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, 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, type RouterChatResult, type RouterChatToolsResult, type RouterConfig, type RouterSeam, type RouterToolCall, type RouterToolLoopResult, 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, type 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, acquireSandbox, adaptiveRefine, anytimeReport, assertStrategyContract, assertTraceDerivedFindings, auditIntent, authorStrategy, breadthDriver, buildSteerContext, builtinShapes, contentAddress, createBudgetPool, createExecutor, createExecutorRegistry, createMcpEnvironment, createRootHandle, createSandboxLineage, createScope, createScopeAnalyst, createShapeRegistry, createSupervisor, createVerifierEnvironment, createWaterfallCollector, defaultAnalystInstruction, defaultAuditorInstruction, definePersona, defineStrategy, depthDriver, discriminatingMeans, equalKOnCost, extractLlmCallEvent, fanout, flatWidenGate, gitWorkspace, harvestCorpus, inlineSandboxClient, jjWorkspace, localShell, loopDispatch, loopUntil, mapSandboxEvent, materializeTreeView, observe, openSandboxRun, panel, pickChampion, pipeline, printBenchmarkReport, probeSandboxCapabilities, promotionGate, refine, registerShape, registryScopeAnalyst, renderAnytimeTable, renderCorpusToInstructions, renderReport, replaySpawnTree, reportLoopUsage, routerChatWithTools, routerChatWithUsage, routerToolLoop, runAgentic, runBenchmark, runPersonified, runStrategyEvolution, sample, sampleThenRefine, selectChampion, settledToIteration, spendFromUsageEvents, strategyAuthorContract, trajectoryReport, verify, widen };
+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 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 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, 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, acquireSandbox, adaptiveRefine, anytimeReport, asAuthoredProfile, assertStrategyContract, assertTraceDerivedFindings, auditIntent, authorStrategy, authoredWorker, breadthDriver, buildSteerContext, builtinShapes, completionAuthorizes, contentAddress, coordinationDriverAgent, createBudgetPool, createExecutor, createExecutorRegistry, createMcpEnvironment, createRootHandle, createSandboxLineage, createScope, createScopeAnalyst, createShapeRegistry, createSupervisor, createVerifierEnvironment, createWaterfallCollector, 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 };