@tangle-network/agent-runtime 0.82.0 → 0.83.0

package/dist/loops.d.ts

@@ -2,31 +2,30 @@ import { ChatClient, RunRecord, AnalystFinding, AgentProfile, AnalystRunInputs,
 export { AnalystFinding, DefaultVerdict, computeFindingId, makeFinding } from '@tangle-network/agent-eval';
 import { SandboxEvent, SandboxInstance, CreateSandboxOptions } from '@tangle-network/sandbox';
 export { AgentProfile, CreateSandboxOptions, SandboxEvent, SandboxInstance } from '@tangle-network/sandbox';
-import { d as ResultBlobStore, S as SpawnJournal, N as NodeId, j as SpawnEvent, E as ExecutorFactory, c as Agent, B as Budget, i as Scope, g as Settled, f as SupervisedResult, h as Spend, U as UsageEvent, b as ExecutorRegistry, k as Supervisor } from './types-By9LXllv.js';
-export { A as AgentSpec, a as Executor, l as ExecutorContext, m as ExecutorResult, R as Runtime, n as SupervisorOpts, T as TreeView, W as WidenGate } from './types-By9LXllv.js';
-import { ak as MakeWorkerAgent, A as AnalystRegistry, o as CoordinationTools, n as CoordinationEvent, ar as QuestionPolicy, a$ as ExecutorConfig } from './coordination-BI9tpcmF.js';
-export { b0 as BusEvent, b1 as BusRecord, b2 as BusStats, b3 as EventBus, b4 as ProviderSeam, b5 as PublishOptions, b6 as cliWorktreeExecutor, b7 as createEventBus, b8 as createExecutor, b9 as createExecutorRegistry } from './coordination-BI9tpcmF.js';
-import { R as RuntimeHooks, I as Iteration, S as SandboxClient, W as Driver, A as AgentRunSpec, b as OutputAdapter, V as Validator, E as ExecCtx, X as LoopWinner, Y as LoopLineageOptions, Z as LoopResult, L as LoopTokenUsage, a as RuntimeStreamEvent, _ as MountRecorder } from './types-BF-MEsQB.js';
-export { $ as LoopDecisionPayload, a0 as LoopEndedPayload, a1 as LoopIterationDispatchPayload, a2 as LoopIterationEndedPayload, a3 as LoopIterationStartedPayload, a4 as LoopPlanDescription, a5 as LoopPlanPayload, d as LoopSandboxPlacement, a6 as LoopStartedPayload, a7 as LoopTeardownFailedPayload, e as LoopTraceEmitter, c as LoopTraceEvent, a8 as MountManifestEntry, a9 as RunProvenance, aa as SelectionReceipt, ab as ValidationCtx } from './types-BF-MEsQB.js';
+import { d as ResultBlobStore, S as SpawnJournal, N as NodeId, j as SpawnEvent, E as ExecutorFactory, c as Agent, B as Budget, i as Scope, g as Settled, f as SupervisedResult, h as Spend, U as UsageEvent, b as ExecutorRegistry, k as Supervisor } from './types-Driepl87.js';
+export { A as AgentSpec, a as Executor, l as ExecutorContext, m as ExecutorResult, R as Runtime, n as SupervisorOpts, T as TreeView, W as WidenGate } from './types-Driepl87.js';
+import { ak as MakeWorkerAgent, A as AnalystRegistry, o as CoordinationTools, n as CoordinationEvent, ar as QuestionPolicy, a$ as ExecutorConfig } from './coordination-CuDLO8wj.js';
+export { b0 as BusEvent, b1 as BusRecord, b2 as BusStats, b3 as EventBus, b4 as ProviderSeam, b5 as PublishOptions, b6 as cliWorktreeExecutor, b7 as createEventBus, b8 as createExecutor, b9 as createExecutorRegistry } from './coordination-CuDLO8wj.js';
+import { R as RuntimeHooks, I as Iteration, S as SandboxClient, W as Driver, A as AgentRunSpec, b as OutputAdapter, V as Validator, E as ExecCtx, X as LoopWinner, Y as LoopLineageOptions, Z as LoopResult, L as LoopTokenUsage, a as RuntimeStreamEvent, _ as MountRecorder } from './types-ESeMOj94.js';
+export { $ as LoopDecisionPayload, a0 as LoopEndedPayload, a1 as LoopIterationDispatchPayload, a2 as LoopIterationEndedPayload, a3 as LoopIterationStartedPayload, a4 as LoopPlanDescription, a5 as LoopPlanPayload, d as LoopSandboxPlacement, a6 as LoopStartedPayload, a7 as LoopTeardownFailedPayload, e as LoopTraceEmitter, c as LoopTraceEvent, a8 as MountManifestEntry, a9 as RunProvenance, aa as SelectionReceipt, ab as ValidationCtx } from './types-ESeMOj94.js';
 export { AgentEnvironmentProviderRef, AgentEnvironmentProviderRegistry, ProviderAsSandboxClientOptions, ProviderExecutorOptions, SandboxClientProviderOptions, createAgentEnvironmentProviderRegistry, providerAsExecutor, providerAsSandboxClient, resolveAgentEnvironmentProvider, sandboxClientAsProvider } from './environment-provider.js';
-import { C as CorpusRecord, c as Corpus, O as Outcome, S as ScopeAnalyzeInput, d as AssertTraceDerivedFindings, e as SteerContext, f as ScopeAnalyst, F as FanoutOptions, g as CombinatorShape, h as ScopeWidenGate, L as LoopUntilSpec, P as PanelSpec, i as PipelineStage, W as WinnerStrategy, j as FanoutWinnerSelector, V as VerifySpec, k as WidenSpec, l as CorpusFilter, R as RenderCorpusToInstructionsOptions, D as DefinePersonaInput, m as Persona, n as RunPersonifiedOptions, o as ShapeRegistry, p as LoopShape, E as EqualKArm, q as EqualKOnCostOptions, r as EqualKVerdict, T as TrajectoryReportOptions, s as TrajectoryReport } from './worktree-fanout-D9Z2dMS9.js';
-export { A as AuthoredHarness, t as DefinePersona, u as EqualKOnCost, v as Fanout, w as FanoutSynthesis, x as FlatWidenGate, y as LoopUntil, z as LoopUntilState, B as Panel, G as PanelJudge, H as PanelVerdict, I as PatchDeliverableOptions, J as PersonaContext, K as PersonaExecutors, M as Pipeline, N as RenderCorpusToInstructions, Q as RunPersonified, U as ShapeBudget, X as ShapeContext, Y as TrajectoryNode, Z as TrajectoryReportFn, _ as Verify, $ as Widen, a0 as WidenDecision, a1 as WidenLineage, a2 as WorktreeCliExecutorOptions, a as WorktreeFanoutOptions, b as WorktreePatchArtifact, a3 as createWorktreeCliExecutor, a4 as patchDelivered, a5 as worktreeFanout } from './worktree-fanout-D9Z2dMS9.js';
+import { C as CorpusRecord, c as Corpus, O as Outcome, S as ScopeAnalyzeInput, d as AssertTraceDerivedFindings, e as SteerContext, f as ScopeAnalyst, F as FanoutOptions, g as CombinatorShape, h as ScopeWidenGate, L as LoopUntilSpec, P as PanelSpec, i as PipelineStage, W as WinnerStrategy, j as FanoutWinnerSelector, V as VerifySpec, k as WidenSpec, l as CorpusFilter, R as RenderCorpusToInstructionsOptions, D as DefinePersonaInput, m as Persona, n as RunPersonifiedOptions, o as ShapeRegistry, p as LoopShape, E as EqualKArm, q as EqualKOnCostOptions, r as EqualKVerdict, T as TrajectoryReportOptions, s as TrajectoryReport } from './worktree-fanout-D6xR2CIA.js';
+export { A as AuthoredHarness, t as DefinePersona, u as EqualKOnCost, v as Fanout, w as FanoutSynthesis, x as FlatWidenGate, y as LoopUntil, z as LoopUntilState, B as Panel, G as PanelJudge, H as PanelVerdict, I as PatchDeliverableOptions, J as PersonaContext, K as PersonaExecutors, M as Pipeline, N as RenderCorpusToInstructions, Q as RunPersonified, U as ShapeBudget, X as ShapeContext, Y as TrajectoryNode, Z as TrajectoryReportFn, _ as Verify, $ as Widen, a0 as WidenDecision, a1 as WidenLineage, a2 as WorktreeCliExecutorOptions, a as WorktreeFanoutOptions, b as WorktreePatchArtifact, a3 as createWorktreeCliExecutor, a4 as patchDelivered, a5 as worktreeFanout } from './worktree-fanout-D6xR2CIA.js';
 import { Scenario, DispatchFn, ProfileDispatchFn } from '@tangle-network/agent-eval/campaign';
 import { b as AnalystRegistryLike } from './types-BC3bZpH0.js';
 import { AgentProfile as AgentProfile$1 } from '@tangle-network/agent-interface';
-import { R as RouterConfig, a as ToolLoopChat, b as ToolLoopCompactionOptions } from './router-client-D6Ocf4jG.js';
-export { c as RouterChatResult, d as RouterChatToolsResult, e as RouterToolCall, f as RouterToolLoopResult, g as ToolLoopCompaction, T as ToolSpec, r as routerBrain, h as routerChatWithTools, i as routerChatWithUsage, j as routerToolLoop } from './router-client-D6Ocf4jG.js';
-import { D as DeliverableSpec } from './worktree-harness-Dx8XULW3.js';
-export { g as WorktreeCommandResult, h as gateOnDeliverable } from './worktree-harness-Dx8XULW3.js';
+import { R as RouterConfig, a as ToolLoopChat, b as ToolLoopCompactionOptions } from './router-client-r8y_VFVM.js';
+export { c as RouterChatResult, d as RouterChatToolsResult, e as RouterToolCall, f as RouterToolLoopResult, g as ToolLoopCompaction, T as ToolSpec, r as routerBrain, h as routerChatWithTools, i as routerChatWithUsage, j as routerToolLoop } from './router-client-r8y_VFVM.js';
+import { D as DeliverableSpec } from './worktree-harness-CX_McRLp.js';
+export { g as WorktreeCommandResult, h as gateOnDeliverable } from './worktree-harness-CX_McRLp.js';
 import { stuckLoopView, toolWasteView } from '@tangle-network/agent-eval/pipelines';
 export { AgentEnvironment, AgentEnvironmentCapabilities, AgentEnvironmentEvent, AgentEnvironmentProvider, AgentEnvironmentQuery, AgentEnvironmentStatus, AgentEnvironmentSummary, AgentProfileRef, AgentSession, AgentSessionRef, AgentSessionStatus, AgentTurnInput, AgentTurnResult, CheckpointRef, CheckpointRequest, CreateAgentEnvironmentInput, ExecRequest, ExecResult, ForkRequest, PlacementInfo, ResourceRequest, WorkspaceRequest } from '@tangle-network/agent-interface/environment-provider';
-import './substrate-rNj6TDc3.js';
+import './substrate-DO2GHNg2.js';
 import './otel-export-BKmNwiCb.js';
-import './local-harness-DU7yV6mG.js';
+import './local-harness-sI0S_XNA.js';
 import 'node:child_process';
 
 /**
- * @experimental
  *
  * Event-sourced spawn journal for the recursive execution atom (build steps 3 + 7).
  *
@@ -44,6 +43,8 @@ import 'node:child_process';
  * each settlement — NOT wall-clock. `replaySpawnTree` sorts strictly by `seq` before
  * touching the blob store, so the order in which rehydration `get`s resolve can never
  * reorder the replayed `Settled[]`; the result is identical regardless of blob latency.
+ *
+ * @experimental
  */
 
 /**
@@ -136,6 +137,7 @@ interface WaterfallCollector {
     }): string;
     reset(): void;
 }
+/** Build a `WaterfallCollector` that records agent spans and renders them as an ASCII timeline. */
 declare function createWaterfallCollector(): WaterfallCollector;
 
 /**
@@ -273,7 +275,9 @@ interface IntentAudit {
     steer?: string;
     confidence: number;
 }
+/** Default system instruction for intent-auditor agents: diagnose diverged/drifting trajectories. */
 declare const defaultAuditorInstruction: string;
+/** The route-rigor analyst: compare declared vs revealed vs user intent over a trajectory and return aligned / drifting / diverged with evidence and one recommended intervention. */
 declare function auditIntent(input: AuditIntentInput, opts: AuditIntentOptions): Promise<IntentAudit>;
 
 /**
@@ -410,7 +414,6 @@ declare function renderLeaderboardSvg(report: Leaderboard): string;
 declare function renderLeaderboardHtml(report: Leaderboard): string;
 
 /**
- * @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
@@ -431,6 +434,8 @@ declare function renderLeaderboardHtml(report: Leaderboard): string;
  *     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).
+ *
+ * @experimental
  */
 
 /** Trace-derived evidence for a completion claim — an artifact (output) or a verifier metric,
@@ -464,6 +469,7 @@ interface CompletionPolicy {
     /** Minimum confidence a PROBABILISTIC verdict must clear to end. Default 0.8. */
     minConfidence?: number;
 }
+/** Decide whether a `CompletionVerdict` may end the node under the policy: authority scales with the verdict's determinism, and probabilistic verdicts must clear `minConfidence`. */
 declare function completionAuthorizes(v: CompletionVerdict, policy?: CompletionPolicy): boolean;
 /**
  * A unique, attributable stop sentinel for a node (ralph-loop style). Deterministic from the
@@ -546,6 +552,7 @@ interface Observation {
     /** Operator-facing markdown: what the observer noticed + what to change. */
     report: string;
 }
+/** The third-person trace analyst: read a worker's trace and produce steer findings for the next attempt plus durable `learned` facts for the cross-run corpus. */
 declare function observe(input: ObserveInput, opts: ObserveOptions): Promise<Observation>;
 /** Operator-facing report, split by who should act. The agent block is the
  *  steer; the operator block is the advice. */
@@ -605,6 +612,7 @@ interface HarvestReport {
     /** Per-run analysis failures — reported, never silently dropped. */
     failures: HarvestFailure[];
 }
+/** Batch the firewalled `observe()` analyst over completed runs and accrete the trace-derived facts into the durable corpus — the production-traces→corpus write side of the flywheel. */
 declare function harvestCorpus(opts: HarvestCorpusOptions): Promise<HarvestReport>;
 
 /** Context handed to each `onPrompt` call. */
@@ -664,7 +672,6 @@ declare function inProcessSandboxClient(options: InProcessSandboxClientOptions):
 declare function inlineSandboxClient(factory: ExecutorFactory<unknown>): SandboxClient;
 
 /**
- * @experimental
  *
  * `runLoop` — the topology-agnostic kernel built atop the sandbox SDK.
  *
@@ -686,6 +693,8 @@ declare function inlineSandboxClient(factory: ExecutorFactory<unknown>): Sandbox
  * emission. The kernel does NOT own: what the agent runs (sandbox SDK +
  * profile), how outputs are decoded (output adapter), how outputs are
  * scored (validator), or topology (driver).
+ *
+ * @experimental
  */
 
 /** @experimental */
@@ -753,7 +762,11 @@ interface RunLoopOptions<Task, Output, Decision> {
      */
     lineage?: LoopLineageOptions;
 }
-/** @experimental */
+/**
+ * The round-synchronous loop kernel: each round `driver.plan()` fans N tasks to sandboxes (bounded concurrency), parses + validates each output, and folds results through `driver.decide`.
+ *
+ * @experimental
+ */
 declare function runLoop<Task, Output, Decision>(options: RunLoopOptions<Task, Output, Decision>): Promise<LoopResult<Task, Output, Decision>>;
 /**
  * The kernel's winner argmax — best-valid-score, ties broken by earliest index,
@@ -975,7 +988,9 @@ interface Strategy {
     readonly name: string;
     driver(surface: AgenticSurface, task: AgenticTask, opts: AgenticOptions, budget: number): Agent<unknown, Outcome<unknown>>;
 }
+/** Built-in `Strategy`: K independent attempts, keep the best-verifying (best-of-N / resample). */
 declare const sample: Strategy;
+/** Built-in `Strategy`: attempt → `observe()` reads the trace → steer the next attempt → repeat (deepen one lineage). */
 declare const refine: Strategy;
 /** A role for one shot — multi-agent loops (researcher + engineer, a panel of k
  *  researchers) give each shot its own system prompt and optionally its own model. */
@@ -1144,6 +1159,7 @@ interface BenchmarkStrategySummary {
     usd: number;
     ms: number;
 }
+/** Benchmark output: per-strategy means plus the full per-task × per-strategy losses table an optimizer mines. */
 interface BenchmarkReport {
     n: number;
     excluded: number;
@@ -1206,10 +1222,10 @@ interface McpEnvironmentOptions {
     /** Cap on a tool result's text fed back to the worker. Default 1500 chars. */
     maxResultChars?: number;
 }
+/** Wrap any MCP server as an `Environment`: `tools/list` becomes `AgenticTool[]` with provider-safe schemas; the domain supplies only the artifact lifecycle hooks. */
 declare function createMcpEnvironment(opts: McpEnvironmentOptions): Environment;
 
 /**
- * @experimental
  *
  * Analyst-on-scope (G1) — the analyze→findings→steer wire over the reactive `Scope`.
  *
@@ -1226,6 +1242,8 @@ declare function createMcpEnvironment(opts: McpEnvironmentOptions): Environment;
  * drains its settlement, then enforces the firewall on the way out — a judge-derived finding
  * ABORTS, it is never filtered. Fail loud: a down analyst, a non-array result, or a tainted finding
  * throws; there is no silent empty-findings path that would let a combinator steer on nothing.
+ *
+ * @experimental
  */
 
 declare const assertTraceDerivedFindings: AssertTraceDerivedFindings;
@@ -1303,7 +1321,6 @@ declare function registryScopeAnalyst<D>(registry: AnalystRegistryLike, buildInp
 declare function buildSteerContext<D>(findings: ReadonlyArray<AnalystFinding>, settledSoFar: ReadonlyArray<Settled<Outcome<D>>>): SteerContext<D>;
 
 /**
- * @experimental
  *
  * The generic combinator library — the content-free act-bodies the wave's §1 contract froze.
  *
@@ -1323,6 +1340,8 @@ declare function buildSteerContext<D>(findings: ReadonlyArray<AnalystFinding>, s
  * Two fail-loud invariants every combinator honors: a child the conserved pool cannot admit is a
  * CONCRETE blocker (never an eager over-fan, never a silent drop), and a `blocked` outcome always
  * names at least one blocker (a shape that cannot finish MUST say why — `blocked([])` throws).
+ *
+ * @experimental
  */
 
 /**
@@ -1406,7 +1425,6 @@ declare function widen<Task, Seed, D>(spec: WidenSpec<Seed, D>): CombinatorShape
 declare function flatWidenGate<D>(): ScopeWidenGate<D>;
 
 /**
- * @experimental
  *
  * The cross-run corpus (G2) — the learning-flywheel's durable accreted-fact store.
  *
@@ -1421,6 +1439,8 @@ declare function flatWidenGate<D>(): ScopeWidenGate<D>;
  * the same `id`. Malformed records — a structurally-invalid `CorpusRecord` from disk or a caller —
  * fail loud (the validator throws), since a corpus that silently accepts garbage would poison
  * every downstream run that reads it back.
+ *
+ * @experimental
  */
 
 /**
@@ -1475,7 +1495,6 @@ declare class FileCorpus implements Corpus {
 declare function renderCorpusToInstructions(opts: RenderCorpusToInstructionsOptions): Promise<AgentProfile$1>;
 
 /**
- * @experimental
  *
  * The personify layer impl — `definePersona` (the thin builder) + `runPersonified` (composes
  * the persona + chosen shape onto the keystone `Supervisor`), plus `createShapeContext`, the
@@ -1492,6 +1511,8 @@ declare function renderCorpusToInstructions(opts: RenderCorpusToInstructionsOpti
  * that supplies raw `seams` is therefore wrapped here into a registry whose resolved factories
  * receive a ctx with the persona seams merged in — so a persona never has to pre-close its
  * factories by hand. A persona may instead supply a fully-built `registry` and skip the wrap.
+ *
+ * @experimental
  */
 
 /**
@@ -1510,7 +1531,6 @@ declare function definePersona<D = unknown>(input: DefinePersonaInput<D>): Perso
 declare function runPersonified<Task, D>(options: RunPersonifiedOptions<Task, D>): Promise<SupervisedResult<Outcome<D>>>;
 
 /**
- * @experimental
  *
  * The loop-shape registry — the OPEN, content-free extension point for the personify layer.
  *
@@ -1524,6 +1544,8 @@ declare function runPersonified<Task, D>(options: RunPersonifiedOptions<Task, D>
  * `verify`/`widen`) take spec arguments, so they are not bare zero-arg factories — a caller that
  * wants name-resolution registers its own COMPOSED shape (a combinator already applied to its
  * spec) on a registry instance. The registry carries SHAPE only; the domain lives on the persona.
+ *
+ * @experimental
  */
 
 /**
@@ -1539,7 +1561,6 @@ declare const builtinShapes: ShapeRegistry;
 declare function registerShape<Task, D>(name: string, factory: LoopShape<Task, D>): void;
 
 /**
- * @experimental
  *
  * Trajectory trace + cost ledger — the post-hoc tree reconstructor (§4 of `wave-types`).
  *
@@ -1560,6 +1581,8 @@ declare function registerShape<Task, D>(name: string, factory: LoopShape<Task, D
  * CROSS-run analogue the pool cannot reach — proving equal compute before any win is claimed.
  *
  * Pure over the journal/blobs — no live agent calls; safe to run on a finished run's log.
+ *
+ * @experimental
  */
 
 /**
@@ -1635,6 +1658,7 @@ interface PromotionVerdict {
         high: number;
     };
 }
+/** Statistical promotion decision over a holdout benchmark: a seeded paired bootstrap (`heldoutSignificance`) whose CI lower bound must clear `deltaThreshold`. */
 declare function promotionGate(opts: PromotionGateOptions): PromotionVerdict;
 
 /**
@@ -1720,7 +1744,6 @@ interface ResolveSandboxClientOptions {
 declare function resolveSandboxClient(opts: ResolveSandboxClientOptions): SandboxClient;
 
 /**
- * @experimental
  *
  * `acquireSandbox` — cold-start-resilient sandbox acquisition. Eliminates the
  * "create timed out at the proxy" failure mode conceptually by DECOUPLING "the
@@ -1744,6 +1767,8 @@ declare function resolveSandboxClient(opts: ResolveSandboxClientOptions): Sandbo
  * but never reaches `running` (abort, terminal status, budget) is torn down
  * before the failure propagates, so an abort storm during cold start does not
  * leak live sandboxes.
+ *
+ * @experimental
  */
 
 /** @experimental */
@@ -1765,11 +1790,14 @@ interface AcquireOptions {
     /** Sleep override for deterministic tests. */
     sleep?: (ms: number) => Promise<void>;
 }
-/** @experimental */
+/**
+ * Cold-start-resilient sandbox acquisition: create by name, observe readiness from the sandbox's own status (not the create call), and re-attach after gateway timeouts.
+ *
+ * @experimental
+ */
 declare function acquireSandbox(client: SandboxClient, options: CreateSandboxOptions, acquire?: AcquireOptions): Promise<SandboxInstance>;
 
 /**
- * @experimental
  *
  * Capability probe for the loop kernel's backend-blind lineage seams. The
  * kernel must NEVER ask "is this Docker or Firecracker?"; it asks "can this
@@ -1781,6 +1809,8 @@ declare function acquireSandbox(client: SandboxClient, options: CreateSandboxOpt
  * Invariant: a client with no `criuStatus` method (the loop's test fakes, the
  * raw SDK before it grew the probe) reports `canFork = false`. The seam is
  * fail-CLOSED — never assume forking works, only enable it on a positive probe.
+ *
+ * @experimental
  */
 
 /**
@@ -1892,7 +1922,6 @@ declare function mapSandboxEvent(event: SandboxEvent, opts?: {
 }): RuntimeStreamEvent | undefined;
 
 /**
- * @experimental
  *
  * `SandboxLineage` — the backend-blind owner of box + session handles for a
  * single `runLoop` invocation. It exists so `run-loop.ts` never references a
@@ -1923,6 +1952,8 @@ declare function mapSandboxEvent(event: SandboxEvent, opts?: {
  * in `run-loop.ts`; the lineage only hands back the live `streamPrompt` iterable
  * so the kernel keeps ownership of event collection, cost accounting, and trace
  * emission.
+ *
+ * @experimental
  */
 
 /**
@@ -2074,12 +2105,13 @@ interface SessionCapableBox {
  */
 
 /**
- * @experimental
  * How a typed deliverable `Out` is materialized from a finished turn.
  * - `events`   — pure parse over the event array (identical to `OutputAdapter`).
  * - `artifact` — read a file off the box AFTER the turn drains, then map it (+ the
  *                events). For diffs/codebases/documents that don't fit the chat
  *                stream. `path` relative ⇒ workspace root; absolute ⇒ container FS.
+ *
+ * @experimental
  */
 type Deliverable<Out> = {
     kind: 'events';
@@ -2090,10 +2122,11 @@ type Deliverable<Out> = {
     fromArtifact: (raw: string, events: SandboxEvent[]) => Out;
 };
 /**
- * @experimental
  * One finished turn over the artifact. A failed FS read is surfaced in `readError`
  * (never masked as an empty deliverable) so a caller distinguishes "agent produced
  * nothing" from a transport/FS fault.
+ *
+ * @experimental
  */
 interface TurnResult<Out> {
     out: Out;
@@ -2101,7 +2134,6 @@ interface TurnResult<Out> {
     readError?: string;
 }
 /**
- * @experimental
  * Thrown when a turn is aborted/timed-out mid-settle. Carries the events drained
  * BEFORE the abort fired (and any in-progress `readError`) so an aborted run is
  * DIAGNOSABLE — the caller can tell never-started (`events: []`) from looped
@@ -2109,6 +2141,8 @@ interface TurnResult<Out> {
  *
  * `name === 'AbortError'`, so existing `err.name === 'AbortError'` callers (the
  * loop kernel, scope, supervise runtime) keep matching it unchanged.
+ *
+ * @experimental
  */
 declare class SandboxRunAbortError extends Error {
     readonly name = "AbortError";
@@ -2149,15 +2183,15 @@ interface OpenSandboxRunOptions {
     readRetryDelayMs?: number;
 }
 /**
- * @experimental
  * Open a sandbox run. Harness-agnostic: the harness lives in
  * `options.agentRun.sandboxOverrides.backend.type`, so opencode/codex/claude-code/
  * kimi-code all flow through this one entrypoint with identical env/auth wiring.
+ *
+ * @experimental
  */
 declare function openSandboxRun<Out>(client: SandboxClient, options: OpenSandboxRunOptions, deliverable: Deliverable<Out>): Promise<SandboxRun<Out>>;
 
 /**
- * @experimental
  *
  * Leak-free steering drivers — the non-LLM controls for the driven loop.
  *
@@ -2198,6 +2232,8 @@ declare function openSandboxRun<Out>(client: SandboxClient, options: OpenSandbox
  * They consume nothing the loop kernel does not already give `plan()`/`decide()`
  * — `runLoop` requires no change. A benchmark picks a driver by name and the
  * kernel does the rest.
+ *
+ * @experimental
  */
 
 /**
@@ -2554,10 +2590,10 @@ declare function pickChampion(means: Record<string, {
 }>, fieldOrder: string[], policy: ChampionPolicy, epsilon: number): ChampionPick;
 /** Search-side champion selection over a tournament report. */
 declare function selectChampion(report: BenchmarkReport, fieldOrder: string[], policy: ChampionPolicy, epsilon: number): ChampionPick;
+/** Multi-generation strategy search: author candidates from tournament losses, play them against the incumbent at equal budget, promote via `promotionGate` on an untouched holdout slice. */
 declare function runStrategyEvolution(cfg: StrategyEvolutionConfig): Promise<EvolutionReport>;
 
 /**
- * @experimental
  *
  * The supervisor's intelligence is AUTHORING the agents it spawns — not pressing buttons.
  *
@@ -2569,6 +2605,8 @@ declare function runStrategyEvolution(cfg: StrategyEvolutionConfig): Promise<Evo
  *
  * 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.
+ *
+ * @experimental
  */
 
 /** What the supervisor AUTHORS per sub-task — a worker recipe (a partial `AgentProfile`). */
@@ -2602,6 +2640,7 @@ interface ProfileRichnessThresholds {
     /** A prompt with fewer than this many non-blank lines is thin (default 6). */
     readonly minSystemPromptLines: number;
 }
+/** Default thresholds for `ProfileRichnessThresholds` — 600 chars / 6 lines minimum system prompt. */
 declare const defaultProfileRichnessThresholds: ProfileRichnessThresholds;
 /** Per-field verdict on one authored profile — the raw material the bench renders + scores. */
 interface ProfileRichness {
@@ -2639,7 +2678,6 @@ declare function profileRichnessFinding(richness: ProfileRichness, opts?: {
 }): AnalystFinding;
 
 /**
- * @experimental
  *
  * The conserved budget reservation pool — the invariant the whole instrument
  * rests on (critique M5/B3). One root `Budget` becomes a conserved pool of three
@@ -2657,6 +2695,8 @@ declare function profileRichnessFinding(richness: ProfileRichness, opts?: {
  * Pure and deterministic: `now()` is injected, there is no I/O, and no wall-clock or
  * RNG read. A `reserve`/`reconcile` ticket is single-use (fail-loud on double or
  * unknown reconcile) so a child can never refund twice.
+ *
+ * @experimental
  */
 
 /** Opaque, single-use reservation handle returned by `reserve` and consumed by
@@ -2735,7 +2775,6 @@ declare function spendFromUsageEvents(events: UsageEvent[]): Spend;
 declare function createBudgetPool(root: Budget, now?: () => number): BudgetPool;
 
 /**
- * @experimental
  *
  * `driverAgent` — the driver's BRAIN.
  *
@@ -2759,6 +2798,8 @@ declare function createBudgetPool(root: Budget, now?: () => number): BudgetPool;
  *    sandboxed harness drives the verbs as MCP tools. The same seam every tool-loop uses.
  *  - `systemPrompt` — the driver's stance (the agent-eval worker-driver prompt / the prompt
  *    generator). Injected, never hardcoded — the prompt is a pluggable role.
+ *
+ * @experimental
  */
 
 interface DriverAgentOptions {
@@ -2835,7 +2876,6 @@ declare function finalizeBestDelivered(settled: ReadonlyArray<{
 }>, blobs: ResultBlobStore): Promise<unknown>;
 
 /**
- * @experimental
  *
  * Serve the coordination verbs (spawn_agent / await_event / observe_agent / steer_agent / stop)
  * as a real HTTP MCP server over a LIVE `Scope`. This is the keystone that lets a coding-harness
@@ -2852,6 +2892,8 @@ declare function finalizeBestDelivered(settled: ReadonlyArray<{
  * 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.
+ *
+ * @experimental
  */
 
 interface CoordinationMcpHandle {
@@ -2955,10 +2997,10 @@ interface SupervisorAgentDeps {
      *  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>;
 
 /**
- * @experimental
  *
  * `delegate` — the one generic delegation verb. You hand it an INTENT (what you want done) and it
  * hands that intent to a default AUTHORING supervisor: a router-brained supervisor whose standing
@@ -2975,6 +3017,8 @@ declare function supervisorAgent(profile: SupervisorProfile, deps: SupervisorAge
  * caller on BOTH paths — a `winner` carries the delivered worker's spend, a `no-winner` carries the
  * spend incurred before it failed. That cost channel means a `delegate()` caller always learns what
  * the delegation actually spent.
+ *
+ * @experimental
  */
 
 /** The conserved pool a `delegate()` call applies when the caller does not pass its own `budget`.
@@ -3020,7 +3064,6 @@ interface DelegateOptions<Out = unknown> {
 declare function delegate<Out = unknown>(intent: string, opts?: DelegateOptions<Out>): Promise<SupervisedResult<Out>>;
 
 /**
- * @experimental
  *
  * `TraceSource` — the ONE substrate-agnostic source of a worker's tool-call trace. The online
  * detectors and the settle-time analyzers consume agent-eval `ToolSpan`s from here, regardless of
@@ -3036,6 +3079,8 @@ declare function delegate<Out = unknown>(intent: string, opts?: DelegateOptions<
  *
  * This module imports NO substrate SDK — it decodes generic message parts / OpenAI tool-call shapes.
  * The sandbox wiring (`sandboxSessionTraceSource`) is the thin adapter that feeds box session parts in.
+ *
+ * @experimental
  */
 
 interface ToolStepInput {
@@ -3095,13 +3140,14 @@ declare function sandboxSessionTraceSource(box: SessionTraceBox, sessionId: stri
 }): TraceSource;
 
 /**
- * @experimental
  *
  * The ONLINE analyst: watch a `TraceSource` and fold each tool span through agent-eval's published
  * streaming detector kernel (`repeatedActionDetector`/`errorStreakDetector` — the SAME kernel the
  * control loop folds), firing `onSignal` the moment a worker loops or error-storms. Substrate-
  * agnostic: it consumes spans from any source (owned router/bridge loop OR a sandbox box session),
  * never the raw tool seam. Detection logic + the failure taxonomy live in agent-eval; not reimplemented.
+ *
+ * @experimental
  */
 
 interface WatchTraceOptions {
@@ -3124,7 +3170,6 @@ declare function defaultToolDetectors(): StreamingDetector[];
 declare function watchTrace(source: TraceSource, opts?: WatchTraceOptions): () => void;
 
 /**
- * @experimental
  *
  * The worker-side receive end of the down-leg: a per-worker inbox an executor exposes as
  * `Executor.deliver`. The driver's `steer_agent` / `answer_question` land here,
@@ -3138,6 +3183,8 @@ declare function watchTrace(source: TraceSource, opts?: WatchTraceOptions): () =
  *     of a wrong path mid-task instead of waiting for it to finish the step.
  *
  * `deliver` never throws — a malformed message is ignored, per the `Executor.deliver` contract.
+ *
+ * @experimental
  */
 interface InboxMessage {
     readonly kind: 'steer' | 'answer';
@@ -3159,6 +3206,7 @@ interface Inbox {
     /** Render drained messages as ONE operator turn to fold into the worker's conversation. */
     fold(messages: ReadonlyArray<InboxMessage>): string;
 }
+/** Create the worker-side inbox for the down-leg: the driver's `steer_agent` / `answer_question` messages queue here and the worker's loop drains them at step boundaries and before settle. */
 declare function createInbox(): Inbox;
 
 /**
@@ -3169,7 +3217,6 @@ declare function createInbox(): Inbox;
 declare function assertModelAllowed(model: string | undefined, allowed: readonly string[] | undefined): void;
 
 /**
- * @experimental
  *
  * `createInMemoryRunContext` — the one-call bundle of the in-memory stores a
  * `createSupervisor().run(root, task, opts)` needs: a fresh `InMemorySpawnJournal`
@@ -3191,6 +3238,8 @@ declare function assertModelAllowed(model: string | undefined, allowed: readonly
  * The spread shape matches `SupervisorOpts` exactly, so the call site reads:
  *   const run = createInMemoryRunContext()
  *   await createSupervisor().run(root, task, { budget, runId, ...run })
+ *
+ * @experimental
  */
 
 /** Options for the in-memory run context. */
@@ -3219,7 +3268,6 @@ interface InMemoryRunContext {
 declare function createInMemoryRunContext(opts?: InMemoryRunContextOptions): InMemoryRunContext;
 
 /**
- * @experimental
  *
  * The reactive `Scope` impl (KEYSTONE, build step 4 + the step-8 adapter).
  *
@@ -3242,6 +3290,8 @@ declare function createInMemoryRunContext(opts?: InMemoryRunContextOptions): InM
  * The settle path is the only writer of journal `settled` events; the spawn path the only
  * writer of `spawned` events. The result blob is `put` BEFORE the journal `settled` record
  * references its `outRef`, so a crash can never leave a journaled ref with no blob.
+ *
+ * @experimental
  */
 
 /** Construction args for `createScope`. The supervisor threads the shared pool, journal,
@@ -3275,6 +3325,7 @@ interface ScopeArgs {
      *  (the topology viewer reads it). Undefined ⇒ the journal stays the only record. */
     readonly hooks?: RuntimeHooks;
 }
+/** Create the reactive `Scope` a driver's `Agent.act` runs inside: spawn children on an atomically reserved conserved budget, settle via the `next()` cursor, journal for replay. */
 declare function createScope<Out>(args: ScopeArgs): Scope<Out>;
 /**
  * The step-8 merge-boundary adapter (M4): rehydrate a `Settled.done` into the kernel's
@@ -3351,10 +3402,10 @@ interface SuperviseOptions {
      *  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>>;
 
 /**
- * @experimental
  *
  * The `Supervisor` impl (KEYSTONE, build step 5).
  *
@@ -3386,18 +3437,21 @@ declare function supervise(profile: SupervisorProfile, task: unknown, opts: Supe
  * winner `Out`. The supervisor content-addresses that `Out` for its replay `outRef`, reads
  * `spentTotal` off the journal (`settled` child work + `metered` driver inference), and wraps
  * it as a typed `winner` — it does not re-rank children behind the driver's back.
+ *
+ * @experimental
  */
 
 declare function createSupervisor<Task, Out>(): Supervisor<Task, Out>;
 
 /**
- * @experimental
  *
  * The SETTLE-time analyst: when a worker finishes, collect its tool spans from a `TraceSource` and run
  * agent-eval's PUBLISHED batch analyzers over them — `buildTrajectory` (structured run summary),
  * `stuckLoopView` (full-run repeated-call view, complementing the online consecutive detector), and
  * `toolWasteView`. Substrate-agnostic: the spans come from any source (an owned loop's buffer OR a
  * sandbox box session). No analysis reimplemented — this is the thin bridge into agent-eval's analyzers.
+ *
+ * @experimental
  */
 
 interface TrajectoryAnalysis {
@@ -3513,6 +3567,7 @@ interface VerifierEnvironmentOptions {
     /** Executes the extra tools. Required when `extraTools` is set. */
     callExtra?(task: AgenticTask, name: string, args: Record<string, unknown>): Promise<string> | string;
 }
+/** Any checkable task as an `Environment`, no tool surface required: the artifact is the worker's answer and the domain is one deployable `check` over it. */
 declare function createVerifierEnvironment(opts: VerifierEnvironmentOptions): Environment;
 
 /** Command runner seam. Host code can use `localShell`; sandbox code can wrap `box.exec`. */
@@ -3534,6 +3589,7 @@ interface Workspace {
     commit(dir: string, message: string): Promise<WorkspaceCommit>;
     head(): Promise<string>;
 }
+/** Host-process `Shell`: run a command via `execFile`, resolving `{ stdout, stderr, code }` (never throws on non-zero exit). */
 declare function localShell(): Shell;
 interface GitWorkspaceOptions {
     readonly ref: string;
@@ -3541,6 +3597,7 @@ interface GitWorkspaceOptions {
     readonly branch?: string;
     readonly noHooks?: boolean;
 }
+/** A `Workspace` over a git checkout: materialize an isolated worktree at `ref`, commit produced changes (conflict-aware), and read `head` — hooks disabled, identity pinned. */
 declare function gitWorkspace(opts: GitWorkspaceOptions): Workspace;
 /** A jj-backed `Workspace` (Jujutsu, colocated with git for the durable remote).
  *  Same port, same `Shell` — a drop-in for `gitWorkspace`. jj suits agent loops: