@tangle-network/agent-runtime 0.102.2 → 0.103.1

package/dist/supervise-BQdNAXtK.d.ts

@@ -1,131 +0,0 @@
-import { S as Scope, a as ResultBlobStore, B as Budget, A as Agent, b as SupervisedResult } from './types-D870JlH0.js';
-import { M as MakeWorkerAgent, A as AnalystRegistry, E as ExecutorConfig } from './coordination-D9l_YmwW.js';
-import { R as RouterConfig, T as ToolLoopChat, a as ToolLoopCompactionOptions } from './sanitize-DEbPNtyI.js';
-import { D as DeliverableSpec } from './completion-gate-C6dhVN-N.js';
-
-/** The supervisor's profile — the subset of an `AgentProfile` that selects + shapes its brain.
- *  `harness` is the backend-as-data discriminant; `systemPrompt` is the standing instruction. */
-interface SupervisorProfile {
-    readonly name?: string;
-    /** null/undefined → router brain (in-process tool-loop); a coding-CLI harness → sandboxed brain. */
-    readonly harness?: string | null;
-    /** The router model when the brain is router-driven (falls back to the deps router config). */
-    readonly model?: string;
-    /** The standing instructions ("you delegate, you do not solve"). */
-    readonly systemPrompt?: string;
-}
-/** How to run a sandboxed harness as the DRIVER, with the coordination verbs mounted — the substrate
- *  seam the caller supplies (mirrors `makeWorkerAgent` for spawned children). It runs `profile` on
- *  `task` in its backend (sandbox / cli-bridge) with `coordinationMcpUrl` mounted as an MCP server,
- *  so the harness calls spawn_agent / await_event / stop as native tools over the live scope. */
-type DriveHarness = (args: {
-    readonly profile: SupervisorProfile;
-    readonly task: unknown;
-    readonly scope: Scope<unknown>;
-    readonly coordinationMcpUrl: string;
-}) => Promise<void>;
-interface SupervisorAgentDeps {
-    readonly blobs: ResultBlobStore;
-    /** Resolve a spawned worker `profile` to a leaf agent — the recursion seam (same for both arms). */
-    readonly makeWorkerAgent: MakeWorkerAgent;
-    /** Per-child budget reserved from the conserved pool on each spawn. */
-    readonly perWorker: Budget;
-    /** Hard cap on simultaneously-LIVE workers across both arms — `spawn_agent` fails closed once
-     *  this many are in flight (a concurrency fence on top of the conserved-pool fence; bounds live
-     *  boxes/sandboxes, not total work). Omit/`<= 0` = no cap. */
-    readonly maxLiveWorkers?: number;
-    /** Router substrate for a router-brained supervisor (`harness` null). The profile's model wins. */
-    readonly router?: RouterConfig;
-    /** Inject the brain directly (tests / advanced) instead of resolving `routerBrain` from the profile. */
-    readonly brain?: ToolLoopChat;
-    /** Required for a sandboxed-harness supervisor (`harness` set): runs the harness as the driver. */
-    readonly driveHarness?: DriveHarness;
-    /** WORK tools the supervisor may call DIRECTLY (router arm) — so it can do simple work ITSELF and
-     *  only delegate when it needs parallelism. Pair with `executeExtraTool`. */
-    readonly extraTools?: ReadonlyArray<{
-        readonly name: string;
-        readonly description?: string;
-        readonly parameters: Record<string, unknown>;
-    }>;
-    /** Runs an `extraTools` call; null/undefined falls through to the coordination dispatch. */
-    readonly executeExtraTool?: (name: string, args: Record<string, unknown>) => Promise<string | null | undefined>;
-    /** Analyst lenses available to the driver (both arms). Required for `analyzeOnSettle`. */
-    readonly analysts?: AnalystRegistry;
-    /** Analyst kinds run on each worker-settle → a `finding` the driver composes its next steer from
-     *  (the self-improving UP-leg). Unset/empty = status quo (no analyst feed). Requires `analysts`. */
-    readonly analyzeOnSettle?: ReadonlyArray<string>;
-    readonly maxTurns?: number;
-    /** Give the supervisor brain a chapter-lifecycle on its OWN context window (router arm only) — it
-     *  distills its coordination transcript to a compact progress note once it exceeds the threshold,
-     *  instead of re-billing the whole thing every turn. See `DriverAgentOptions.compaction`. */
-    readonly compaction?: ToolLoopCompactionOptions;
-}
-/** Build a supervisor `Agent` from its profile: the brain resolves from `profile.harness` (backend-as-data), the same resolution rule as every worker. */
-declare function supervisorAgent(profile: SupervisorProfile, deps: SupervisorAgentDeps): Agent<unknown, unknown>;
-
-/** Build the worker seam from a backend (WHERE workers run) + an optional completion oracle (the
- *  deliverable check that makes "settled ⟺ delivered" true — the guard against "ran but didn't
- *  deliver"). The ONE place a backend becomes a spawnable worker. */
-declare function workerFromBackend(backend: ExecutorConfig, deliverable?: DeliverableSpec<unknown>): MakeWorkerAgent;
-interface SuperviseOptions {
-    /** The conserved compute pool for the whole run. */
-    readonly budget: Budget;
-    /** WHERE workers run — derives the worker seam. Provide this OR an explicit `makeWorkerAgent`. */
-    readonly backend?: ExecutorConfig;
-    /** The completion oracle for backend-derived workers (settled ⟺ delivered). Strongly recommended:
-     *  without it the supervisor trusts a worker's self-report — exactly the "ran but didn't deliver"
-     *  failure mode of a static orchestrator. */
-    readonly deliverable?: DeliverableSpec<unknown>;
-    /** Override the worker seam directly (tests / advanced) instead of deriving it from `backend`. */
-    readonly makeWorkerAgent?: MakeWorkerAgent;
-    /** The supervisor's router substrate (`harness` null). The profile's model wins. */
-    readonly router?: RouterConfig;
-    /** Inject the supervisor brain directly (tests / advanced). */
-    readonly brain?: ToolLoopChat;
-    /** Run a sandboxed-harness supervisor (`harness` set). */
-    readonly driveHarness?: DriveHarness;
-    /** WORK tools the supervisor may call DIRECTLY — so a recursive atom can ACT (do simple work
-     *  itself) OR SPAWN (delegate when it needs parallelism), not be a pure manager. Pair with
-     *  `executeExtraTool`. Router arm only (`harness` null). */
-    readonly extraTools?: ReadonlyArray<{
-        readonly name: string;
-        readonly description?: string;
-        readonly parameters: Record<string, unknown>;
-    }>;
-    /** Runs an `extraTools` call; null/undefined falls through to the coordination dispatch. */
-    readonly executeExtraTool?: (name: string, args: Record<string, unknown>) => Promise<string | null | undefined>;
-    /** Per-child budget reserved on each spawn. Defaults to a quarter of the pool's tokens. */
-    readonly perWorker?: Budget;
-    /** Hard cap on simultaneously-LIVE workers — `spawn_agent` fails closed once this many are in
-     *  flight. The conserved pool bounds TOTAL work; this bounds SIMULTANEOUS work (live boxes/
-     *  sandboxes a real fleet runs at once). Omit/`<= 0` = no cap (the pool stays the only fence). */
-    readonly maxLiveWorkers?: number;
-    /** Analyst lenses available to the driver. Required for `analyzeOnSettle`. Unset → status quo
-     *  (the driver receives settled worker outputs, no analyst findings). */
-    readonly analysts?: AnalystRegistry;
-    /** Analyst kind ids run AUTOMATICALLY when a worker settles `done` — each re-enters as a `finding`
-     *  the driver pulls (`await_event`) and composes its next steer from. The self-improving UP-leg,
-     *  threaded to the driver at this level (propagate to sub-drivers via a recursive `makeWorkerAgent`).
-     *  Omit/empty = status quo (no analyst feed). Requires `analysts`. */
-    readonly analyzeOnSettle?: ReadonlyArray<string>;
-    /** Worker output store. Defaults to in-memory. */
-    readonly blobs?: ResultBlobStore;
-    readonly maxDepth?: number;
-    readonly maxTurns?: number;
-    /** Give the supervisor brain a chapter-lifecycle on its OWN context window (router arm only): once
-     *  its coordination transcript exceeds `thresholdTokens` it distills to a compact progress note and
-     *  continues, instead of re-billing the whole transcript every turn (the cost that makes the LLM-brain
-     *  front door lose to a dumb-Ralph respawn). The live `Scope` roster is the durable state across
-     *  chapters. Default off. `distill` defaults to a brain self-summary + the settled-worker roster. */
-    readonly compaction?: ToolLoopCompactionOptions;
-    readonly runId?: string;
-    readonly now?: () => number;
-    /** Restrict the run to this subset of models. When set, every configured model — the
-     *  supervisor router model, the profile's model, and the backend's model — must be a member,
-     *  or `supervise()` throws a `ConfigError` before any compute is spent. Unset = unrestricted. */
-    readonly allowedModels?: readonly string[];
-}
-/** One-call supervisor: build + run a supervisor from its profile with sensible defaults; the raw `supervisorAgent` + `createSupervisor().run` seams stay available for power use. */
-declare function supervise(profile: SupervisorProfile, task: unknown, opts: SuperviseOptions): Promise<SupervisedResult<unknown>>;
-
-export { type DriveHarness as D, type SupervisorProfile as S, type SuperviseOptions as a, type SupervisorAgentDeps as b, supervisorAgent as c, supervise as s, workerFromBackend as w };

package/dist/types-D870JlH0.d.ts

@@ -1,500 +0,0 @@
-import { DefaultVerdict } from '@tangle-network/agent-eval';
-import { AgentProfile } from '@tangle-network/agent-interface';
-import { BackendType } from '@tangle-network/sandbox';
-import { L as LoopTokenUsage, R as RuntimeHooks } from './types-CLat4bT9.js';
-
-/**
- *
- * 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.
- *
- * @experimental
- */
-
-/**
- * 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_agent`
-     * 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: custom runtimes use their own string name.
- * External executors can register additional runtime strings without widening this type. */
-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;
-    /** Dollar accounting is known unless explicitly false. A false value must not be treated as $0
-     *  when enforcing a dollar-denominated comparison or limit. */
-    usdKnown?: boolean;
-    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>;
-    /**
-     * Non-blocking twin of `next()`: deliver an ALREADY-settled, undelivered child, or `null`
-     * when none is ready — never awaits a live child. The driver's post-loop drain reads this so
-     * a child that settled while the driver was busy (or after it stopped pulling) still reaches
-     * the finalize ledger instead of being silently lost.
-     */
-    nextResolved(): 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` returns events for inspection and completed-settlement replay, not live process
- * recovery; `appendEvent` runs 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;
-    /** The conserved spend incurred before the run failed — real cost is paid even when no
-     *  worker delivers, so the caller always learns what the delegation actually spent. Summed
-     *  off the same journal the `winner` path reads. */
-    spentTotal: Spend;
-};
-/** 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;
-}
-
-export type { Agent as A, Budget as B, ExecutorFactory as E, NodeId as N, Runtime as R, Scope as S, TreeView as T, UsageEvent as U, WidenGate as W, ResultBlobStore as a, SupervisedResult as b, Executor as c, Settled as d, Spend as e, AgentSpec as f, SpawnJournal as g, ExecutorRegistry as h, RootHandle as i, SpawnEvent as j, Supervisor as k, ExecutorContext as l, ExecutorResult as m, SupervisorOpts as n };