@tangle-network/agent-runtime 0.104.0 → 0.106.0

package/dist/environment-provider-IUGU3epE.d.ts

@@ -0,0 +1,964 @@
+import { E as SandboxClient, K as RuntimeHooks, v as LoopTokenUsage } from "./types-BevOjfTY.js";
+import { DefaultVerdict, ToolSpan } from "@tangle-network/agent-eval";
+import { AgentProfile as AgentProfile$1, AgentProfileValidationResult } from "@tangle-network/agent-interface";
+import { BackendType, CreateSandboxOptions, Sandbox } from "@tangle-network/sandbox";
+import { AgentEnvironment, AgentEnvironmentCapabilities, AgentEnvironmentCapabilities as AgentEnvironmentCapabilities$1, AgentEnvironmentEvent, AgentEnvironmentProvider, AgentEnvironmentProvider as AgentEnvironmentProvider$1, AgentEnvironmentQuery, AgentEnvironmentStatus, AgentEnvironmentSummary, AgentProfileRef, AgentProfileRef as AgentProfileRef$1, AgentSession, AgentSessionRef, AgentSessionStatus, AgentTurnInput, AgentTurnInput as AgentTurnInput$1, AgentTurnResult, CheckpointRef, CheckpointRequest, CreateAgentEnvironmentInput, CreateAgentEnvironmentInput as CreateAgentEnvironmentInput$1, ExecRequest, ExecResult, ForkRequest, PlacementInfo, ResourceRequest, WorkspaceRequest } from "@tangle-network/agent-interface/environment-provider";
+//#region src/runtime/supervise/progress.d.ts
+/** How long a worker may produce no metered activity before a `progress()` read calls it stalled.
+ *  Deliberately generous: a coding harness routinely spends minutes inside one tool call, and a
+ *  false stall that provokes a steer is worse than a late one. */
+declare const DEFAULT_STALL_AFTER_MS = 180000;
+/** The most recent activity the executor can name — one tool call, one turn, or a free-form note.
+ *  `label` is the tool/file/turn name; `detail` is a short, already-truncated descriptor (a path,
+ *  a command head) that a driver can read without pulling the whole transcript. */
+interface ActivityNote {
+  readonly at: number;
+  readonly kind: 'turn' | 'tool' | 'note';
+  readonly label: string;
+  readonly status?: 'ok' | 'error';
+  readonly detail?: string;
+}
+/** What an executor OPTIONALLY adds to the scope-derived progress (`Executor.progress()`). Every
+ *  field is optional: an executor that knows only its own turn count reports only that. */
+interface ExecutorProgress {
+  /** The executor's own turn/step count when it is more meaningful than metered iterations. */
+  readonly turns?: number;
+  /** Steers/answers delivered but not yet folded into the worker's conversation. */
+  readonly pendingMessages?: number;
+  /** Newest-last window of what the worker has been doing. */
+  readonly recentActivity?: ReadonlyArray<ActivityNote>;
+  /** A one-line human-readable state ("turn 3, running tests"). */
+  readonly note?: string;
+}
+/** The full live view of one worker, as `observe_agent` returns it mid-flight. */
+interface WorkerProgress {
+  readonly id: string;
+  readonly status: NodeStatus;
+  /** True while the node is neither done, failed, nor cancelled — i.e. a steer could still land. */
+  readonly live: boolean;
+  /** True when this worker's executor exposes an inbox (`Executor.deliver`) — i.e. `steer_agent`
+   *  can actually reach it. False means a steer would be recorded and dropped. */
+  readonly steerable: boolean;
+  readonly startedAt: number;
+  /** Epoch ms of the last metered usage event or executor-reported activity. */
+  readonly lastActivityAt: number;
+  readonly idleMs: number;
+  readonly stalled: boolean;
+  readonly stallAfterMs: number;
+  /** Metered iterations so far (the executor's own count when it reports one). */
+  readonly turns: number;
+  readonly tokens: {
+    readonly input: number;
+    readonly output: number;
+  };
+  readonly usd: number;
+  /** Steers delivered but not yet read by the worker. */
+  readonly pendingMessages: number;
+  /** Newest-last window of tool/turn activity; empty when the executor exposes none. */
+  readonly recentActivity: ReadonlyArray<ActivityNote>;
+  readonly note?: string;
+}
+/** A bounded newest-last ring of `ActivityNote`s an executor keeps to answer `progress()`. */
+interface ActivityLog {
+  push(note: ActivityNote): void;
+  /** Newest-last, at most `limit` entries. */
+  read(): ReadonlyArray<ActivityNote>;
+  last(): ActivityNote | undefined;
+  size(): number;
+}
+/** Create a bounded activity ring. `limit` caps memory for a worker that runs thousands of tools. */
+declare function createActivityLog(limit?: number): ActivityLog;
+/** The scope-side facts about a child, independent of whether its executor cooperates. */
+interface ScopeProgressInput {
+  readonly id: string;
+  readonly status: NodeStatus;
+  readonly steerable: boolean;
+  readonly startedAt: number;
+  readonly lastActivityAt: number;
+  readonly turns: number;
+  readonly tokens: {
+    readonly input: number;
+    readonly output: number;
+  };
+  readonly usd: number;
+}
+/** Fold the scope-derived facts and the executor's optional enrichment into one read. Pure: the
+ *  caller supplies `now`, so a test can observe a stall without waiting for one. */
+declare function readWorkerProgress(scope: ScopeProgressInput, executor: ExecutorProgress | undefined, now: number, stallAfterMs?: number): WorkerProgress;
+//#endregion
+//#region src/runtime/supervise/trace-source.d.ts
+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;
+  /** Real per-call wall-clock when the source has it (owned tool-loop; opencode parts with `time`).
+   *  When omitted the span collapses to a single instant (`at`) — order + counts only, no duration. */
+  readonly startedAt?: number;
+  readonly endedAt?: number;
+}
+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[]>;
+}
+/** 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 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;
+//#endregion
+//#region src/runtime/supervise/wait.d.ts
+/**
+ *
+ * WAIT-STATES — a supervision-tree node that waits on wall-clock time or an external condition
+ * without holding a worker, an executor, a sandbox, or a single LLM turn.
+ *
+ * A long-horizon run spends most of its wall-clock NOT computing: waiting for CI to finish,
+ * for a nightly job to land, for a human to reply, for a rate-limit window to reopen. Before
+ * this, the only way to express that was to keep something alive and re-ask — which spends
+ * driver tokens per re-ask and pins a process to the wait.
+ *
+ * Two node kinds, both first-class:
+ *   - `timer` — wake at an ABSOLUTE wall-clock instant (`untilMs`).
+ *   - `poll`  — re-run a named predicate every `intervalMs` until it returns true, or until an
+ *               absolute `timeoutAtMs` passes (CI status, file existence, an HTTP probe, an
+ *               inbox message).
+ *
+ * ── How this differs from `await_event`'s 15s poll fence (`DEFAULT_AWAIT_EVENT_TIMEOUT_MS`) ──
+ *
+ * They look similar and are not the same mechanism. `await_event` is an IN-RUN RENDEZVOUS: the
+ * driver blocks on the coordination bus for the next event from a live worker, and the 15s fence
+ * exists only so a remote MCP request does not exceed the client's timeout — the caller re-polls.
+ * Every re-poll is another driver inference turn (real tokens) against a process that must stay
+ * up, and nothing about that wait is recorded: kill the process and the wait is simply gone.
+ *
+ * A wait-state is a NODE, not a call. It has a node id in the tree, a journal record carrying its
+ * ABSOLUTE deadline, and it settles through the same `Scope.next()` cursor as any worker. Nobody
+ * is blocked on it — the driver can stop reasoning entirely, and the process can die. Cost while
+ * waiting: zero LLM calls, zero executor, zero sandbox, zero conserved budget (a wait reserves
+ * nothing from the pool). The only in-process residue is one timer entry.
+ *
+ * ── Why probes are NAMED, not passed as closures ────────────────────────────────────────────
+ *
+ * A wait must survive a process restart with its original deadline intact, and a closure cannot
+ * be journaled. So a `poll` names its predicate (`probe: 'ci-green'`) and the run resolves it
+ * through a `WaitProbeRegistry`. A brand-new process re-resolves the SAME name against its own
+ * registry and re-arms the wait — which is what makes "kill the box, the wait keeps waiting"
+ * true rather than aspirational.
+ *
+ * Absolute instants for the same reason: `untilMs` / `timeoutAtMs` are epoch ms, not durations,
+ * so a resumed wait counts down from the original arm, not from the restart. `timerAt`/`pollFor`
+ * build them from a duration when that is what the caller has.
+ *
+ * @experimental
+ */
+/** What a wait node is waiting for. Both variants carry ABSOLUTE epoch-ms instants so a wait
+ *  re-armed by a later process keeps the deadline the first process set. */
+type WaitSpec = {
+  readonly kind: 'timer';
+  /** Absolute epoch ms to wake at. A past instant fires immediately. */
+  readonly untilMs: number;
+} | {
+  readonly kind: 'poll';
+  /** Name of the predicate in the run's `WaitProbeRegistry`. Named (not a closure) so a
+   *  resumed process can re-resolve it — see the module header. */
+  readonly probe: string;
+  /** How often to re-run the predicate, in ms. Must be > 0. */
+  readonly intervalMs: number;
+  /** Absolute epoch ms after which an unfired poll settles `timeout`. Omit = no timeout
+   *  (then the run's own deadline is the only bound, and a run WITH a deadline refuses an
+   *  unbounded poll — see `assertWaitWithinDeadline`). */
+  readonly timeoutAtMs?: number;
+  /** Opaque JSON handed to the probe on every check. Journaled with the spec, so a resumed
+   *  probe gets the same arguments. */
+  readonly args?: Record<string, unknown>;
+};
+/** Build a `timer` spec from a DURATION. The instant is resolved once, at arm time — a resumed
+ *  wait re-uses the journaled instant, never a fresh `now + ms`. */
+declare function timerAt(ms: number, now: number): WaitSpec;
+/** Build a bounded `poll` spec from a duration. */
+declare function pollFor(probe: string, opts: {
+  readonly intervalMs: number;
+  readonly timeoutMs?: number;
+  readonly args?: Record<string, unknown>;
+}, now: number): WaitSpec;
+/**
+ * A named predicate a `poll` node re-checks. Returns true when the condition it watches has
+ * flipped. A throw is treated as "not yet" (an unreachable CI endpoint is not a settled answer),
+ * and is counted in the outcome's `probeErrors` so a probe that never works is visible rather
+ * than silently polling forever.
+ */
+type WaitProbe = (args: Record<string, unknown> | undefined, signal: AbortSignal) => boolean | Promise<boolean>;
+/** Resolves a `poll` spec's `probe` name to its predicate. Threaded through `SupervisorOpts` so
+ *  the SAME registry a fresh run used is what a resumed run re-resolves against. */
+interface WaitProbeRegistry {
+  resolve(name: string): WaitProbe | undefined;
+}
+/** Registry over a plain name→predicate record. */
+declare function createWaitProbes(entries: Record<string, WaitProbe>): WaitProbeRegistry;
+/** The `out` a settled wait node delivers through `Scope.next()`. `settled` is the outcome the
+ *  caller branches on: `'fired'` = the timer reached its instant or the predicate flipped;
+ *  `'timeout'` = a bounded poll gave up. A timeout is a first-class ANSWER, not a failure — a
+ *  wait only settles `down` when it is cancelled or aborted. */
+interface WaitOutcome {
+  /** Tag for `isWaitOutcome` — a wait outcome arrives on the same cursor as worker outputs. */
+  readonly waitOutcome: true;
+  readonly kind: WaitSpec['kind'];
+  readonly settled: 'fired' | 'timeout';
+  readonly label: string;
+  /** The absolute instant this wait was armed for (timer `untilMs` / poll `timeoutAtMs`); absent
+   *  for an unbounded poll. */
+  readonly untilMs?: number;
+  /** Epoch ms the wait was FIRST armed — preserved across a resume, so `wokenAt - armedAt` is
+   *  the true end-to-end wait even when it spanned several processes. */
+  readonly armedAt: number;
+  readonly wokenAt: number;
+  /** Predicate checks performed in the process that settled it (a resume restarts this count). */
+  readonly polls: number;
+  /** Probe checks that threw (counted, not fatal). */
+  readonly probeErrors: number;
+  /** True when a later process re-armed this wait from the journal instead of creating it. */
+  readonly resumed: boolean;
+}
+/** Narrow a settlement's `out` to a wait outcome — a wait settles on the SAME cursor as workers,
+ *  so a driver that mixes them tags them apart with this. */
+declare function isWaitOutcome(value: unknown): value is WaitOutcome;
+/** A wait recorded in the journal that never woke — what a resumed run re-arms. */
+interface PendingWait {
+  readonly id: string;
+  readonly label: string;
+  readonly spec: WaitSpec;
+  /** The ORIGINAL arm instant. A re-armed wait keeps it, so its deadline never slides. */
+  readonly armedAt: number;
+  /** The wait ordinal in its parent scope, so a resumed scope continues past it. */
+  readonly ordinal: number;
+}
+/** Reject reasons for `Scope.wait`, mirroring `Scope.spawn`'s fail-closed admission shape. */
+type WaitRejection = 'invalid-spec' | 'unknown-probe' | 'deadline-exceeded';
+/** The absolute instant a spec is bounded by, or `undefined` for an unbounded poll. */
+declare function waitUntil(spec: WaitSpec): number | undefined;
+/** Structural validation, independent of the run. Returns null when the spec is usable. */
+declare function validateWaitSpec(spec: WaitSpec): string | null;
+//#endregion
+//#region src/runtime/supervise/types.d.ts
+/** Options for `Scope.wait`. `label` is the wait's identity within its parent scope — it is what
+ *  a resumed run matches to re-adopt a journaled, still-unfired wait, so it must be stable across
+ *  processes (a label derived from wall-clock would resume as a NEW wait). */
+interface WaitOpts {
+  readonly label: string;
+}
+/**
+ * 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 `runAgentRounds` 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;
+  /**
+   * Optional LIVE progress: what this worker is doing RIGHT NOW, read synchronously and
+   * cheaply while `execute` is still streaming. The scope already derives activity timing,
+   * turns, and spend from the metered usage stream for EVERY executor; this adds only what
+   * the executor alone knows — the harness's tool/file activity, its own turn count, and how
+   * many delivered steers it has not yet folded in. Never throws; a read that cannot be
+   * answered returns `undefined`.
+   *
+   * This is the observe half of steering: `deliver` lets a driver correct a worker, and this
+   * is the evidence it corrects FROM. An executor that implements neither cannot be supervised
+   * mid-flight — it can only be waited on.
+   */
+  progress?(): ExecutorProgress | undefined;
+  /**
+   * Optional live tool-call trace for the ONLINE detectors (`watchTrace`). An executor that
+   * can see its worker's tool calls exposes them here, so a supervisor can run the streaming
+   * repeated-action / error-streak panel over a RUNNING worker and raise a `finding` the
+   * moment it loops, instead of discovering it at settle. Omitted = no online detection for
+   * this runtime (the settle-time analyzers still work).
+   */
+  traceSource?(): TraceSource | undefined;
+  /**
+   * 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 `runAgentRounds` against `profile` on that backend.
+ * Fail loud on an unresolvable spec (no executor and an unknown harness).
+ */
+interface AgentSpec {
+  readonly profile: AgentProfile$1;
+  /** `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.
+ *  `'waiting'` is first-class for the opposite reason: a wait-state node holds NO executor, NO
+ *  box, and no conserved budget — it is neither in flight nor settled, so neither `inFlight` nor
+ *  a terminal status describes it (see `Scope.wait`). */
+type NodeStatus = 'pending' | 'acquiring' | 'running' | 'waiting' | '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;
+  /**
+   * Arm a WAIT-STATE node: a first-class tree node that waits on wall-clock time (`timer`) or on
+   * a named external predicate (`poll`) and settles through THIS scope's `next()` cursor like any
+   * other child — but holds no executor, no sandbox, and no conserved budget. Waiting costs zero
+   * tokens and zero dollars by construction.
+   *
+   * It is journaled (`waiting` → `woken`) with its ABSOLUTE deadline, so a run that dies mid-wait
+   * resumes still waiting: the supervisor surfaces the un-woken waits on `Scope.resume.waits`, and
+   * re-arming the same `label` adopts the recorded node id and original instant instead of
+   * restarting the countdown.
+   *
+   * Fail-closed admission, mirroring `spawn`: `invalid-spec`, `unknown-probe` (a `poll` naming a
+   * predicate this run's registry cannot resolve), or `deadline-exceeded` (the wait would outlive
+   * the pool's hard wall-clock ceiling — a wait never extends a budget guard).
+   *
+   * NOT `await_event`: that is an in-run rendezvous on the coordination bus whose 15s fence makes
+   * the caller re-poll — each re-poll a driver inference turn against a process that must stay up,
+   * and nothing about it survives a restart. See `supervise/wait.ts`.
+   */
+  wait(spec: WaitSpec, opts: WaitOpts): {
+    ok: true;
+    handle: Handle<WaitOutcome>;
+  } | {
+    ok: false;
+    reason: WaitRejection;
+  };
+  /**
+   * The LIVE read-model of one child, valid WHILE it runs: last-activity timestamp, idle time,
+   * a derived `stalled` flag, tokens/turns spent so far, whether a steer can even reach it
+   * (`steerable`), and whatever tool activity its executor exposes. `undefined` for an unknown
+   * id. This is the counterpart to `send`: a driver that can steer but cannot observe has
+   * nothing to steer on, which is precisely why steering went unused.
+   *
+   * Pull-based and side-effect free — reading it starts no timer and spends nothing. `now` and
+   * `stallAfterMs` are injectable so a caller (and a test) controls what counts as stalled.
+   */
+  progress(nodeId: NodeId, opts?: {
+    now?: number;
+    stallAfterMs?: number;
+  }): WorkerProgress | undefined;
+  /** The live tool-call trace of one child when its executor exposes one (`Executor.traceSource`),
+   *  for running the online detector panel over a RUNNING worker. `undefined` otherwise. */
+  traceSource(nodeId: NodeId): TraceSource | undefined;
+  /** 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>;
+  /**
+   * Prior committed work, present ONLY on a resumed run (`undefined` on a fresh run, which is
+   * every run that did not pass `SupervisorOpts.resume`). The supervisor `loadTree`s the journal
+   * first; when a non-empty tree exists it rehydrates the already-settled children (via
+   * `replaySpawnTree`) and hands them here so a resume-aware `act` re-uses them instead of
+   * re-spawning committed work. A resume-blind driver simply ignores it and re-spawns — correct
+   * but redundant. The scope's spawn ordinal + cursor seq are already advanced past the recorded
+   * maxima, so any NEW spawn appends without colliding with a journaled event.
+   */
+  readonly resume?: ResumedWork<Out>;
+  /** 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;
+  }>;
+}
+/**
+ * The committed work a resumed run inherits from its journal. `settled` is the replayed
+ * `Settled[]` (cursor-ordered, rehydrated from the blob store by `replaySpawnTree`); `view`
+ * is the tree as `materializeTreeView` folded it at the recorded cursor position. A
+ * resume-aware `act` reads `scope.resume?.settled` to pick up where the crashed run left off.
+ */
+interface ResumedWork<Out> {
+  readonly settled: ReadonlyArray<Settled<Out>>;
+  readonly view: TreeView;
+  /**
+   * Wait-state nodes the journal shows as ARMED but never woken — the run died mid-wait. Each
+   * carries the ORIGINAL arm instant and absolute deadline, so re-arming the same `label` through
+   * `Scope.wait` resumes the countdown instead of restarting it. Empty on a fresh run and on a
+   * resumed run that was not waiting.
+   */
+  readonly waits: ReadonlyArray<PendingWait>;
+}
+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;
+  /** Count of nodes in `waiting` — armed wait-states. Deliberately NOT folded into `inFlight`:
+   *  a wait burns no executor and no budget, so counting it as flow would misreport both idle
+   *  capacity and how much work is actually running. */
+  readonly waiting: 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 wait-state node was ARMED. Lives in the SPAWN-ORDINAL namespace (`seq` is the wait
+   *  ordinal within its parent scope), exactly like `spawned` — it creates a node, it does not
+   *  settle one. It carries the whole `spec` and the original `armedAt` so a brand-new process
+   *  re-arms the identical wait with the identical ABSOLUTE deadline. */
+  kind: 'waiting';
+  id: NodeId;
+  parent?: NodeId;
+  label: string;
+  spec: WaitSpec;
+  armedAt: number;
+  seq: number;
+  at: string;
+} | {
+  /** A wait-state node SETTLED — the cursor-namespace twin of `settled`, kept distinct so a
+   *  reader can tell zero-cost waiting apart from paid work without inspecting payloads. A
+   *  wait carries no `spent` (it is free by construction, not by measurement); `outRef`
+   *  rehydrates its `WaitOutcome`, absent when the wait was cancelled. */
+  kind: 'woken';
+  id: NodeId;
+  by: 'fired' | 'timeout' | 'cancelled';
+  outRef?: 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;
+  /** Predicate resolution for `poll` wait-states (`Scope.wait`). A `poll` names its predicate so
+   *  the wait can be journaled and re-armed by a later process; this is what the name resolves
+   *  against. Unset ⇒ `poll` waits are refused (`unknown-probe`); `timer` waits are unaffected. */
+  readonly probes?: WaitProbeRegistry;
+  /** 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;
+  /**
+   * Opt into RESUME-FIRST: read any prior journal tree for this `runId` BEFORE beginning a fresh
+   * one, and when a non-empty tree exists rehydrate its committed work onto `Scope.resume`
+   * (`replaySpawnTree` + `materializeTreeView`) instead of starting over. Requires a journal +
+   * blob store that OUTLIVE the process (`createFileRunContext(dir)`); against the in-memory
+   * stores there is never a prior tree, so it is a no-op.
+   *
+   * Default `false` — a run always begins a fresh tree, which is the behavior every existing
+   * consumer has. Resume is a durability contract the caller opts into, never a silent default.
+   */
+  readonly resume?: boolean;
+  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 `runAgentRounds` 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;
+}
+//#endregion
+//#region src/runtime/tangle-sandbox-exact-process-provider.d.ts
+type SandboxControlClient = Pick<Sandbox, 'create' | 'get' | 'list'>;
+interface CreateTangleSandboxExactProcessProviderOptions {
+  name?: string;
+}
+/**
+ * Adapt Tangle Sandbox's managed control runtime to Runtime's exact-process provider.
+ *
+ * The adapter deliberately exposes no ordinary agent environment: an exact experiment
+ * must start a fresh Sandbox with no managed agent and launch its declared argv directly.
+ */
+declare function createTangleSandboxExactProcessProvider(client: SandboxControlClient, options?: CreateTangleSandboxExactProcessProviderOptions): AgentEnvironmentProvider;
+//#endregion
+//#region src/runtime/environment-provider.d.ts
+/** Provider object or registry name accepted by runtime provider adapters.
+ * @experimental */
+type AgentEnvironmentProviderRef = AgentEnvironmentProvider | string;
+/** In-memory registry for named `AgentEnvironmentProvider` instances.
+ * @experimental */
+interface AgentEnvironmentProviderRegistry {
+  register(provider: AgentEnvironmentProvider, options?: {
+    replace?: boolean;
+  }): void;
+  has(name: string): boolean;
+  get(name: string): AgentEnvironmentProvider | undefined;
+  require(name: string): AgentEnvironmentProvider;
+  names(): string[];
+  providers(): AgentEnvironmentProvider[];
+  capabilities(name: string): Promise<AgentEnvironmentCapabilities>;
+}
+/** Create a registry that resolves provider names to concrete provider instances.
+ * @experimental */
+declare function createAgentEnvironmentProviderRegistry(providers?: Iterable<AgentEnvironmentProvider>): AgentEnvironmentProviderRegistry;
+/** Resolve a provider instance or registry name, failing loudly when a name is unknown.
+ * @experimental */
+declare function resolveAgentEnvironmentProvider(provider: AgentEnvironmentProviderRef, registry?: AgentEnvironmentProviderRegistry): AgentEnvironmentProvider;
+/** Options for exposing an `AgentEnvironmentProvider` through the legacy sandbox client port.
+ * @experimental */
+interface ProviderAsSandboxClientOptions {
+  defaults?: Partial<CreateAgentEnvironmentInput>;
+  requireTerminalEvent?: boolean;
+  mapCreateOptions?: (options: CreateSandboxOptions | undefined) => Partial<CreateAgentEnvironmentInput>;
+}
+/** Adapt a neutral environment provider to the `SandboxClient` interface used by existing loop paths.
+ * @experimental */
+declare function providerAsSandboxClient(provider: AgentEnvironmentProvider, options?: ProviderAsSandboxClientOptions): SandboxClient;
+/** Options for wrapping the current Tangle sandbox client as an environment provider.
+ * @experimental */
+interface SandboxClientProviderOptions {
+  name?: string;
+  defaultBackend?: BackendType;
+  capabilities?: AgentEnvironmentCapabilities | (() => AgentEnvironmentCapabilities | Promise<AgentEnvironmentCapabilities>);
+  validateProfile?: (profile: AgentProfileRef) => AgentProfileValidationResult | Promise<AgentProfileValidationResult>;
+  /** Resolve a named profile before calling Sandbox, which accepts inline profiles only. */
+  resolveProfile?: (profileId: string) => AgentProfile$1 | Promise<AgentProfile$1>;
+  mapCreateInput?: (input: CreateAgentEnvironmentInput) => CreateSandboxOptions;
+}
+/** Adapt a `SandboxClient` into the shared `AgentEnvironmentProvider` contract.
+ * @experimental */
+declare function sandboxClientAsProvider(client: SandboxClient, options?: SandboxClientProviderOptions): AgentEnvironmentProvider;
+/** Options for running a provider as a supervise-mode executor.
+ * @experimental */
+interface ProviderExecutorOptions {
+  defaults?: Partial<CreateAgentEnvironmentInput>;
+  runtime?: Runtime;
+  destroyOnSettle?: boolean;
+  requireTerminalEvent?: boolean;
+  taskToTurn?: (task: unknown, specProfile: AgentProfile$1) => AgentTurnInput;
+}
+/** Adapt an environment provider into an `ExecutorFactory` for `createExecutor`.
+ * @experimental */
+declare function providerAsExecutor(provider: AgentEnvironmentProvider, options?: ProviderExecutorOptions): ExecutorFactory<unknown>;
+//#endregion
+export { RootSignal as $, providerAsSandboxClient as A, createPushTraceSource as At, Executor as B, readWorkerProgress as Bt, ProviderAsSandboxClientOptions as C, timerAt as Ct, WorkspaceRequest as D, SessionTraceBox as Dt, SandboxClientProviderOptions as E, SessionMessageLike as Et, createTangleSandboxExactProcessProvider as F, DEFAULT_STALL_AFTER_MS as Ft, Handle as G, ExecutorFactory as H, Agent as I, ExecutorProgress as It, NodeStatus as J, NodeId as K, AgentSpec as L, ScopeProgressInput as Lt, sandboxClientAsProvider as M, sandboxSessionTraceSource as Mt, CreateTangleSandboxExactProcessProviderOptions as N, ActivityLog as Nt, createAgentEnvironmentProviderRegistry as O, ToolStepInput as Ot, SandboxControlClient as P, ActivityNote as Pt, RootHandle as Q, Budget as R, WorkerProgress as Rt, PlacementInfo as S, pollFor as St, ResourceRequest as T, waitUntil as Tt, ExecutorRegistry as U, ExecutorContext as V, ExecutorResult as W, ResultBlobStore as X, Restart as Y, ResumedWork as Z, CheckpointRequest as _, WaitProbeRegistry as _t, AgentEnvironmentProviderRef as a, SpawnOpts as at, ExecResult as b, createWaitProbes as bt, AgentEnvironmentStatus as c, Supervisor as ct, AgentSession as d, UsageEvent as dt, Runtime as et, AgentSessionRef as f, WaitOpts as ft, CheckpointRef as g, WaitProbe as gt, AgentTurnResult as h, WaitOutcome as ht, AgentEnvironmentProvider$1 as i, SpawnJournal as it, resolveAgentEnvironmentProvider as j, decodeToolPart as jt, providerAsExecutor as k, TraceSource as kt, AgentEnvironmentSummary as l, SupervisorOpts as lt, AgentTurnInput$1 as m, PendingWait as mt, AgentEnvironmentCapabilities$1 as n, Settled as nt, AgentEnvironmentProviderRegistry as o, Spend as ot, AgentSessionStatus as p, WidenGate as pt, NodeSnapshot as q, AgentEnvironmentEvent as r, SpawnEvent as rt, AgentEnvironmentQuery as s, SupervisedResult as st, AgentEnvironment as t, Scope as tt, AgentProfileRef$1 as u, TreeView as ut, CreateAgentEnvironmentInput$1 as v, WaitRejection as vt, ProviderExecutorOptions as w, validateWaitSpec as wt, ForkRequest as x, isWaitOutcome as xt, ExecRequest as y, WaitSpec as yt, DefaultVerdict as z, createActivityLog as zt };
+//# sourceMappingURL=environment-provider-IUGU3epE.d.ts.map