@tangle-network/agent-runtime 0.43.0 → 0.45.0

package/dist/{kb-gate-DTBum3vH.d.ts → kb-gate-D9GBocLN.d.ts}

@@ -1,6 +1,7 @@
-import { CoderOutput, CoderTask } from './profiles.js';
-import { L as LoopSandboxClient, c as LoopTraceEmitter } from './types-Bcp071Jg.js';
+import { C as CoderOutput, a as CoderTask } from './coder-CczgMqFx.js';
+import { b as LoopSandboxClient, f as LoopTraceEmitter } from './types-DdzkffAm.js';
 import { SandboxInstance } from '@tangle-network/sandbox';
+import { a as UiLens, U as UiFinding } from './substrate-CUgk7F7s.js';
 
 /**
  * @experimental
@@ -102,7 +103,7 @@ declare function createFleetWorkspaceExecutor(options: FleetWorkspaceExecutorOpt
  */
 
 /** @experimental */
-type DelegationProfile = 'coder' | 'researcher';
+type DelegationProfile = 'coder' | 'researcher' | 'ui-auditor';
 /** @experimental */
 type DelegationStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
 /**
@@ -223,7 +224,73 @@ type DelegationResultPayload = {
 } | {
     profile: 'researcher';
     output: ResearchOutputShape;
+} | {
+    profile: 'ui-auditor';
+    output: UiAuditorDelegationOutput;
 };
+/**
+ * Wire-shape of a completed UI-audit delegation. The `findings` array
+ * contains every finding persisted to the workspace during the run,
+ * already enriched with `id` and `createdAt` by the writer. `workspaceDir`
+ * is the absolute path to the workspace; `indexFile` is the workspace-
+ * relative path to the regenerated index.md.
+ *
+ * @experimental
+ */
+interface UiAuditorDelegationOutput {
+    workspaceDir: string;
+    indexFile: string;
+    findings: UiFinding[];
+    /** Total iterations the loop ran for this delegation. */
+    iterations: number;
+}
+/** @experimental */
+type UiAuditLensFilter = readonly UiLens[];
+/** Optional per-route capture spec the agent surfaces over the wire. */
+interface DelegateUiAuditRoute {
+    /** Stable route name (used in screenshot filenames + finding metadata). */
+    name: string;
+    /** Fully-qualified URL. */
+    url: string;
+    /** Viewports to capture at. Defaults to `[{ width: 1280, height: 800 }]`. */
+    viewports?: readonly {
+        width: number;
+        height: number;
+    }[];
+    /** Default false. Full-page captures for the broad lenses. */
+    fullPage?: boolean;
+    /** Selector to wait for before capture. */
+    waitFor?: string;
+}
+/** @experimental */
+interface DelegateUiAuditConfig {
+    /**
+     * Lenses to iterate. Default: every lens except `'other'`. Order is
+     * preserved — the driver iterates lens-by-lens.
+     */
+    lenses?: UiAuditLensFilter;
+    /** Maximum total iterations across all (lens × route) pairs. Default 33 (11 lenses × 3 routes). */
+    maxIterations?: number;
+    /** Maximum concurrent iterations within a single plan() round. Default 2. */
+    maxConcurrency?: number;
+    /** Free-form product context surfaced to the judge. */
+    productContext?: string;
+}
+/** @experimental */
+interface DelegateUiAuditArgs {
+    /** Workspace root for the audit (absolute path). */
+    workspaceDir: string;
+    /** Routes to audit. Must be non-empty. */
+    routes: readonly DelegateUiAuditRoute[];
+    /** Multi-tenant scope. */
+    namespace?: string;
+    config?: DelegateUiAuditConfig;
+}
+/** @experimental */
+interface DelegateUiAuditResult {
+    taskId: string;
+    estimatedDurationMs?: number;
+}
 /**
  * Loose shape of a research output over the wire — the substrate cannot
  * import the `ResearchOutput` type from agent-knowledge without inducing
@@ -274,7 +341,7 @@ interface DelegationHistoryEntry {
     taskId: string;
     profile: DelegationProfile;
     namespace?: string;
-    args: DelegateCodeArgs | DelegateResearchArgs;
+    args: DelegateCodeArgs | DelegateResearchArgs | DelegateUiAuditArgs;
     status: DelegationStatus;
     feedback?: DelegationFeedbackSnapshot[];
     costUsd?: number;
@@ -295,6 +362,16 @@ interface DelegateRunCtx {
 type CoderDelegate = (args: DelegateCodeArgs, ctx: DelegateRunCtx) => Promise<CoderOutput>;
 /** @experimental */
 type ResearcherDelegate = (args: DelegateResearchArgs, ctx: DelegateRunCtx) => Promise<ResearchOutputShape>;
+/**
+ * UI-auditor delegate — fully consumer-injected. agent-runtime ships no
+ * default factory because the inputs are workspace path + judge function
+ * + (optionally) a `LoopSandboxClient`, and the judge is the consumer's
+ * model seam. See `createInProcessUiAuditClient` + `uiAuditorProfile` in
+ * `@tangle-network/agent-runtime/profiles` for the canonical wiring.
+ *
+ * @experimental
+ */
+type UiAuditorDelegate = (args: DelegateUiAuditArgs, ctx: DelegateRunCtx) => Promise<UiAuditorDelegationOutput>;
 /** @experimental Structured review verdict over a coder candidate. */
 interface CoderReview {
     /** Gate: only approved candidates are eligible to win. */
@@ -443,4 +520,4 @@ interface CreateKbGateOptions {
  */
 declare function createKbGate(options?: CreateKbGateOptions): (candidate: FactCandidate) => Promise<KbGateResult>;
 
-export { type DelegateRunCtx as A, type FactJudge as B, type CoderReviewer as C, type DelegateCodeArgs as D, type FactJudgeVerdict as E, type FactCandidate as F, type FeedbackRating as G, type FeedbackRefersTo as H, type FleetWorkspaceExecutorOptions as I, type ResearchOutputShape as J, type KbGateResult as K, createDefaultCoderDelegate as L, createFleetWorkspaceExecutor as M, createKbGate as N, createSiblingSandboxExecutor as O, type ResearcherDelegate as R, type SiblingSandboxExecutorOptions as S, type CoderWinnerSelection as a, type CreateKbGateOptions as b, type FleetHandle as c, type DelegationExecutor as d, type DelegateFeedbackArgs as e, type DelegationFeedbackSnapshot as f, type DelegationProfile as g, type DelegateResearchArgs as h, type DelegationStatus as i, type DelegationProgress as j, type DelegationResultPayload as k, type DelegationError as l, type DelegationStatusResult as m, type DelegationHistoryArgs as n, type DelegationHistoryEntry as o, type CoderDelegate as p, type DelegateCodeResult as q, type DelegateFeedbackResult as r, type ResearchSource as s, type DelegateResearchResult as t, type DelegationHistoryResult as u, type DelegationStatusArgs as v, type CoderReview as w, type CreateDefaultCoderDelegateOptions as x, type DelegateCodeConfig as y, type DelegateResearchConfig as z };
+export { type DelegateCodeConfig as A, type DelegateResearchConfig as B, type CoderReviewer as C, type DelegateCodeArgs as D, type DelegateRunCtx as E, type FactCandidate as F, type DelegateUiAuditConfig as G, type DelegateUiAuditRoute as H, type FactJudge as I, type FactJudgeVerdict as J, type FeedbackRating as K, type FeedbackRefersTo as L, type FleetWorkspaceExecutorOptions as M, type KbGateResult as N, type ResearchOutputShape as O, type UiAuditorDelegationOutput as P, createDefaultCoderDelegate as Q, type ResearcherDelegate as R, type SiblingSandboxExecutorOptions as S, createFleetWorkspaceExecutor as T, type UiAuditorDelegate as U, createKbGate as V, createSiblingSandboxExecutor as W, type CoderWinnerSelection as a, type CreateKbGateOptions as b, type FleetHandle as c, type DelegationExecutor as d, type DelegateFeedbackArgs as e, type DelegationFeedbackSnapshot as f, type DelegationProfile as g, type DelegateResearchArgs as h, type DelegateUiAuditArgs as i, type DelegationStatus as j, type DelegationProgress as k, type DelegationResultPayload as l, type DelegationError as m, type DelegationStatusResult as n, type DelegationHistoryArgs as o, type DelegationHistoryEntry as p, type CoderDelegate as q, type DelegateCodeResult as r, type DelegateFeedbackResult as s, type ResearchSource as t, type DelegateResearchResult as u, type DelegateUiAuditResult as v, type DelegationHistoryResult as w, type DelegationStatusArgs as x, type CoderReview as y, type CreateDefaultCoderDelegateOptions as z };

package/dist/{loop-runner-bin-CVoCBmYk.d.ts → loop-runner-bin-CPrCoKqC.d.ts}

@@ -1,10 +1,10 @@
 import { Scenario } from '@tangle-network/agent-eval/campaign';
-import { R as RunAnalystLoopOpts, a as RunAnalystLoopResult } from './types-p8dWBIXL.js';
-import { O as OptimizePromptOptions, a as OptimizePromptResult } from './optimize-prompt-D-urF2wW.js';
-import { T as TopologyPlanner, D as DynamicDecision } from './dynamic-B_7GgCwu.js';
-import { L as LoopSandboxClient, a as OutputAdapter, V as Validator, A as AgentRunSpec, b as LoopResult } from './types-Bcp071Jg.js';
-import { D as DelegateCodeArgs, C as CoderReviewer, a as CoderWinnerSelection, F as FactCandidate, b as CreateKbGateOptions } from './kb-gate-DTBum3vH.js';
-import { CoderOutput } from './profiles.js';
+import { SelfImproveOptions, SelfImproveResult } from '@tangle-network/agent-eval/contract';
+import { R as RunAnalystLoopOpts, a as RunAnalystLoopResult } from './types-BtRLF2U3.js';
+import { D as DelegateCodeArgs, C as CoderReviewer, a as CoderWinnerSelection, F as FactCandidate, b as CreateKbGateOptions } from './kb-gate-D9GBocLN.js';
+import { C as CoderOutput } from './coder-CczgMqFx.js';
+import { b as LoopSandboxClient, O as OutputAdapter, V as Validator, A as AgentRunSpec, c as LoopResult } from './types-DdzkffAm.js';
+import { T as TopologyPlanner, C as CreateDynamicDriverOptions, D as DynamicDecision } from './dynamic-BvllHV6M.js';
 
 /**
  * @experimental
@@ -19,7 +19,7 @@ import { CoderOutput } from './profiles.js';
  *   review       → code mode with a REQUIRED reviewer (the gate is the point)
  *   research     → research-in-a-loop with valid-only KB growth (createKbGate)
  *   audit        → analyze trace/run data → findings (runAnalystLoop, caller-wired)
- *   self-improve → identity-gated prompt optimization (optimizePrompt, caller-wired)
+ *   self-improve → closed-loop text/config optimization (selfImprove, held-out gated)
  *   dynamic      → agent-authored topology (runLoop + createDynamicDriver)
  *
  * It is intentionally a thin façade: the value is that EVERY product reuses the
@@ -91,7 +91,7 @@ declare function reviewLoopRunner(options: CoderLoopRunnerOptions & {
 /** @experimental Options for the default `dynamic` runner. */
 interface DynamicLoopRunnerOptions<Task, Output> {
     sandboxClient: LoopSandboxClient;
-    /** The agent-authored topology planner (e.g. `createSandboxPlanner(...)`). */
+    /** The agent-authored topology planner (sync or async; an async planner is where an LLM call goes). */
     planner: TopologyPlanner<Task, Output>;
     task: Task;
     output: OutputAdapter<Output>;
@@ -101,6 +101,10 @@ interface DynamicLoopRunnerOptions<Task, Output> {
     agentRuns?: AgentRunSpec<Task>[];
     maxIterations?: number;
     maxFanout?: number;
+    /** Optional trace-analyst hook forwarded to the dynamic driver so the loop runs
+     *  `f(trace, findings)` — see `CreateDynamicDriverOptions.analyze`. Caller-side
+     *  seam to `runAnalystLoop`; keeps this runner analyst-free. */
+    analyze?: CreateDynamicDriverOptions<Task, Output>['analyze'];
 }
 /** @experimental `dynamic` mode — agent-authored topology over `runLoop`. */
 declare function dynamicLoopRunner<Task, Output>(o: DynamicLoopRunnerOptions<Task, Output>): DelegatedLoopRunner<LoopResult<Task, Output, DynamicDecision>>;
@@ -142,8 +146,8 @@ interface ResearchLoopRunnerOptions {
  * never silently dropped) so the caller audits vs retries.
  */
 declare function researchLoopRunner(o: ResearchLoopRunnerOptions): DelegatedLoopRunner<ResearchLoopResult>;
-/** @experimental `self-improve` mode — identity-gated prompt optimization. */
-declare function selfImproveLoopRunner<TScenario extends Scenario, TArtifact>(options: OptimizePromptOptions<TScenario, TArtifact>): DelegatedLoopRunner<OptimizePromptResult<TArtifact, TScenario>>;
+/** @experimental `self-improve` mode — agent-eval's one-call closed loop (held-out gated). */
+declare function selfImproveLoopRunner<TScenario extends Scenario, TArtifact>(options: SelfImproveOptions<TScenario, TArtifact>): DelegatedLoopRunner<SelfImproveResult<TScenario, TArtifact>>;
 /** @experimental `audit` mode — analyst loop over captured trace/run data. */
 declare function auditLoopRunner<TProposal = unknown, TEdit = unknown>(options: RunAnalystLoopOpts): DelegatedLoopRunner<RunAnalystLoopResult<TProposal, TEdit>>;
 

package/dist/loop-runner-bin.d.ts

@@ -1,11 +1,13 @@
 #!/usr/bin/env node
-export { L as LoopRunnerCliArgs, f as LoopRunnerCliResult, p as parseLoopRunnerArgv, o as runLoopRunnerCli } from './loop-runner-bin-CVoCBmYk.js';
+export { L as LoopRunnerCliArgs, f as LoopRunnerCliResult, p as parseLoopRunnerArgv, o as runLoopRunnerCli } from './loop-runner-bin-CPrCoKqC.js';
 import '@tangle-network/agent-eval/campaign';
-import './types-p8dWBIXL.js';
+import '@tangle-network/agent-eval/contract';
+import './types-BtRLF2U3.js';
 import '@tangle-network/agent-eval';
-import './optimize-prompt-D-urF2wW.js';
-import './dynamic-B_7GgCwu.js';
-import './types-Bcp071Jg.js';
+import './kb-gate-D9GBocLN.js';
+import './coder-CczgMqFx.js';
 import '@tangle-network/sandbox';
-import './kb-gate-DTBum3vH.js';
-import './profiles.js';
+import './types-DdzkffAm.js';
+import './runtime-hooks-C7JwKb9E.js';
+import './substrate-CUgk7F7s.js';
+import './dynamic-BvllHV6M.js';

package/dist/loop-runner-bin.js

@@ -2,15 +2,13 @@
 import {
   parseLoopRunnerArgv,
   runLoopRunnerCli
-} from "./chunk-C5HMTTNY.js";
-import "./chunk-XBUG326M.js";
-import "./chunk-VOX6Z3II.js";
+} from "./chunk-NYN5RTLP.js";
 import "./chunk-FNMGYYSS.js";
-import "./chunk-MJDGCRAT.js";
-import "./chunk-EKBSQYZE.js";
-import "./chunk-3HMHSN22.js";
-import "./chunk-PY6NMZYX.js";
-import "./chunk-SQSCRJ7U.js";
+import "./chunk-IJ6FGOPO.js";
+import "./chunk-QR4UUC5P.js";
+import "./chunk-FK53TXOP.js";
+import "./chunk-KEWO4KI6.js";
+import "./chunk-PRX45WE2.js";
 import "./chunk-DGUM43GV.js";
 export {
   parseLoopRunnerArgv,

package/dist/loops.d.ts

@@ -1,373 +1,9 @@
-import { AgentProfile, SandboxEvent, SandboxInstance } from '@tangle-network/sandbox';
 export { AgentProfile, CreateSandboxOptions, SandboxEvent, SandboxInstance } from '@tangle-network/sandbox';
-import { P as PlannerContext, T as TopologyPlanner } from './dynamic-B_7GgCwu.js';
-export { C as CreateDynamicDriverOptions, D as DynamicDecision, a as TopologyMove, c as createDynamicDriver, s as summarizeHistory } from './dynamic-B_7GgCwu.js';
-import { D as Driver, I as Iteration, L as LoopSandboxClient, A as AgentRunSpec, a as OutputAdapter, V as Validator, E as ExecCtx, d as LoopWinner, b as LoopResult, R as RuntimeStreamEvent } from './types-Bcp071Jg.js';
-export { e as LoopDecisionPayload, f as LoopEndedPayload, g as LoopIterationDispatchPayload, h as LoopIterationEndedPayload, i as LoopIterationStartedPayload, j as LoopPlanDescription, k as LoopPlanPayload, l as LoopSandboxPlacement, m as LoopStartedPayload, n as LoopTokenUsage, c as LoopTraceEmitter, o as LoopTraceEvent, p as ValidationCtx } from './types-Bcp071Jg.js';
-import { DefaultVerdict, AgentProfile as AgentProfile$1 } from '@tangle-network/agent-eval';
+export { AssertTraceDerivedFindings, BudgetPool, BudgetReadout, CheckpointCapableBox, CliSeam, CombinatorShape, Corpus, CorpusFilter, CorpusRecord, CreateScopeAnalystOptions, CriuCapableClient, DefinePersona, DefinePersonaInput, EqualKArm, EqualKOnCost, EqualKOnCostOptions, EqualKVerdict, Fanout, FanoutOptions, FanoutSynthesis, FileCorpus, FileResultBlobStore, FileSpawnJournal, FlatWidenGate, ForkCapableBox, InMemoryCorpus, InMemoryResultBlobStore, InMemorySpawnJournal, LoopDispatchOptions, LoopOptionsForDispatch, LoopShape, LoopUntil, LoopUntilSpec, LoopUntilState, Outcome, Panel, PanelJudge, PanelSpec, PanelVerdict, Persona, PersonaContext, PersonaExecutors, Pipeline, PipelineStage, RenderCorpusToInstructions, RenderCorpusToInstructionsOptions, ReservationTicket, RouterSeam, RunPersonified, RunPersonifiedOptions, SandboxCapabilities, SandboxLineage, SandboxLineageHandle, SandboxSeam, ScopeAnalyst, ScopeAnalyzeInput, ScopeWidenGate, SessionCapableBox, ShapeBudget, ShapeContext, ShapeRegistry, SteerContext, TrajectoryNode, TrajectoryReport, TrajectoryReportFn, TrajectoryReportOptions, UsageSink, Verify, VerifySpec, Widen, WidenDecision, WidenLineage, WidenSpec, acquireSandbox, assertTraceDerivedFindings, buildSteerContext, builtinShapes, cliExecutor, contentAddress, createBudgetPool, createExecutorRegistry, createRootHandle, createSandboxLineage, createScope, createScopeAnalyst, createShapeRegistry, createSupervisor, definePersona, equalKOnCost, extractLlmCallEvent, fanout, flatWidenGate, loopDispatch, loopUntil, mapSandboxEvent, materializeTreeView, panel, pipeline, probeSandboxCapabilities, registerShape, renderCorpusToInstructions, replaySpawnTree, reportLoopUsage, routerInlineExecutor, runPersonified, sandboxExecutor, settledToIteration, spendFromUsageEvents, trajectoryReport, verify, widen } from './runtime.js';
+export { A as AnalyzeInput, a as CompletionAnalyst, b as CompletionEvidence, c as CompletionPolicy, d as CompletionVerdict, C as CreateDynamicDriverOptions, D as DynamicDecision, P as PlannerContext, e as TopologyMove, T as TopologyPlanner, f as completionAuthorizes, g as createDynamicDriver, h as deterministicCompletion, r as renderAnalyses, s as sentinelCompletion, i as stopSentinel } from './dynamic-BvllHV6M.js';
+export { R as RunLoopOptions, c as createSandboxForSpec, d as defaultSelectWinner, r as runLoop } from './run-loop--hSoIknW.js';
+export { A as Agent, d as AgentSpec, B as Budget, i as ExecutorContext, E as ExecutorRegistry, H as Handle, j as LeafExecutor, L as LeafExecutorFactory, k as LeafResult, N as NodeId, l as NodeSnapshot, m as NodeStatus, n as Restart, R as ResultBlobStore, e as RootHandle, o as RootSignal, p as Runtime, S as Scope, c as Settled, b as SpawnEvent, a as SpawnJournal, q as SpawnOpts, g as Spend, f as SupervisedResult, h as Supervisor, r as SupervisorOpts, T as TreeView, U as UsageEvent, W as WidenGate } from './types-1HbsFa7H.js';
+export { A as AgentRunSpec, D as Driver, E as ExecCtx, I as Iteration, h as LoopDecisionPayload, i as LoopEndedPayload, j as LoopIterationDispatchPayload, k as LoopIterationEndedPayload, l as LoopIterationStartedPayload, a as LoopLineageOptions, m as LoopPlanDescription, n as LoopPlanPayload, c as LoopResult, b as LoopSandboxClient, g as LoopSandboxPlacement, o as LoopStartedPayload, p as LoopTeardownFailedPayload, d as LoopTokenUsage, f as LoopTraceEmitter, q as LoopTraceEvent, L as LoopWinner, O as OutputAdapter, r as ValidationCtx, V as Validator } from './types-DdzkffAm.js';
 export { DefaultVerdict } from '@tangle-network/agent-eval';
-import { Scenario, DispatchFn, ProfileDispatchFn } from '@tangle-network/agent-eval/campaign';
-
-/**
- * @experimental
- *
- * FanoutVote driver — N parallel attempts in iteration 0, pick the highest-
- * scoring valid output. No second iteration: the topology is "spawn N, score,
- * pick winner". The kernel handles heterogeneous fanout via the
- * `agentRuns: AgentRunSpec[]` form on `runLoop`.
- */
-
-type FanoutVoteDecision = 'pick-winner' | 'fail';
-/** @experimental */
-interface FanoutVoteScored<Task, Output> {
-    task: Task;
-    output: Output;
-    verdict?: DefaultVerdict;
-    iterationIndex: number;
-    agentRunName: string;
-}
-/** @experimental */
-interface CreateFanoutVoteDriverOptions<Task, Output> {
-    /** Number of parallel attempts. Must be >= 1. */
-    n: number;
-    /**
-     * Pick the winner from the scored set. Default: highest `verdict.score`
-     * among valid outputs (ties broken by smallest iteration index). When
-     * no valid outputs exist, returns `undefined` and `decide()` resolves
-     * to `'fail'`. The kernel still records winners structurally — this
-     * selector only feeds `decide()`'s pass/fail signal.
-     */
-    selector?: (scored: FanoutVoteScored<Task, Output>[]) => FanoutVoteScored<Task, Output> | undefined;
-    /** Stable identifier surfaced in trace events. Default `'fanout-vote'`. */
-    name?: string;
-}
-/** @experimental */
-declare function createFanoutVoteDriver<Task, Output>(options: CreateFanoutVoteDriverOptions<Task, Output>): Driver<Task, Output, FanoutVoteDecision>;
-/**
- * Test helper: surface the per-iteration scored view a custom `selector`
- * would receive. Exposed so consumers writing a custom selector can test it
- * standalone without driving the full kernel.
- *
- * @experimental
- */
-declare function scoreFanoutVoteIterations<Task, Output>(iterations: ReadonlyArray<Iteration<Task, Output>>): FanoutVoteScored<Task, Output>[];
-
-/**
- * @experimental
- *
- * Refine driver — single task per iteration, validator-gated.
- *
- * `plan` returns `[task]` (possibly transformed via `refineTask`) until the
- * prior verdict is valid OR the local cap is hit, then `[]`.
- * `decide` returns `'stop'` once the latest verdict is valid OR the cap is
- * reached. The kernel's `maxIterations` is an orthogonal safety cap;
- * whichever is lower wins.
- */
-
-type RefineDecision = 'continue' | 'stop';
-/** @experimental */
-interface CreateRefineDriverOptions<Task> {
-    /** Hard cap on iterations. Default 5. */
-    maxIterations?: number;
-    /**
-     * Optional task transform applied each round based on the prior verdict.
-     * When omitted, the same task is replayed and the agent is expected to
-     * inspect the sandbox session state for prior attempts.
-     */
-    refineTask?: (task: Task, prior: DefaultVerdict) => Task;
-    /** Stable identifier surfaced in trace events. Default `'refine'`. */
-    name?: string;
-}
-/** @experimental */
-declare function createRefineDriver<Task, Output>(options?: CreateRefineDriverOptions<Task>): Driver<Task, Output, RefineDecision>;
-/**
- * Test helper: select the last-valid iteration (or the last attempt if
- * none passed). Mirrors the kernel's default selector ordering for refine
- * topologies — the most recent successful attempt wins.
- *
- * @experimental
- */
-declare function refineWinnerIndex<Task, Output>(iterations: ReadonlyArray<Iteration<Task, Output>>): number | undefined;
-
-/**
- * @experimental
- *
- * `createSandboxPlanner` — wire the dynamic driver's `TopologyPlanner` to a
- * real agent. Each round it spins a sandbox on `profile`, streams a prompt that
- * carries the history summary, and decodes the agent's chosen `TopologyMove`
- * from a JSON envelope it emits. This is the "agent authors its own loop
- * topology" path: the planner profile can be any harness (claude-code, codex,
- * opencode, pi) — its only job is to read what happened and emit the next move.
- *
- * The planner profile is deliberately distinct from the worker `agentRuns`: a
- * cheap fast model can steer topology while expensive workers do the labor, and
- * the planner never names which harness runs a branch — the kernel's
- * `agentRuns` round-robin decides that.
- *
- * Envelope contract the agent must emit (fenced ```json or a structured
- * `result`/`final` event payload):
- *   { "kind": "refine" | "fanout" | "stop",
- *     "tasks"?: [ <task>, ... ],   // decoded via `decodeTask`
- *     "n"?: number,                // fanout shorthand: N copies of the root task
- *     "rationale"?: string }
- *
- * A missing / unparseable / unknown-kind envelope throws `PlannerError` — the
- * loop never silently runs a topology the agent did not choose.
- */
-
-/** Raw, pre-decode envelope an agent emits to choose the next move. */
-interface TopologyMoveEnvelope {
-    kind: string;
-    tasks?: unknown[];
-    n?: number;
-    rationale?: string;
-}
-/** @experimental */
-interface CreateSandboxPlannerOptions<Task, Output> {
-    /** Sandbox client — the planner calls `.create()` once per round. */
-    client: LoopSandboxClient;
-    /** The planner agent. Steers topology; does not run the work. */
-    profile: AgentProfile;
-    /**
-     * Decode one raw task from the envelope's `tasks[]` into a domain `Task`.
-     * Required because `Task` is opaque to this module — only the caller knows
-     * its shape. Throw to reject a malformed task; the error surfaces as a
-     * `PlannerError`.
-     */
-    decodeTask: (raw: unknown, ctx: PlannerContext<Task, Output>) => Task;
-    /** Override the default prompt (history summary + envelope contract). */
-    buildPrompt?: (ctx: PlannerContext<Task, Output>) => string;
-    /** Override envelope extraction from the event stream. */
-    parseEnvelope?: (events: SandboxEvent[]) => TopologyMoveEnvelope | undefined;
-    /** Sandbox overrides for the planner sandbox (timeouts, env, etc.). */
-    sandboxOverrides?: AgentRunSpec<Task>['sandboxOverrides'];
-    /** Cancellation for the planner's own LLM call. */
-    signal?: AbortSignal;
-}
-/** @experimental */
-declare function createSandboxPlanner<Task, Output>(opts: CreateSandboxPlannerOptions<Task, Output>): TopologyPlanner<Task, Output>;
-
-/**
- * @experimental
- *
- * `runLoop` — the topology-agnostic kernel built atop the sandbox SDK.
- *
- * Each iteration:
- *   1. `driver.plan(task, history)` → N tasks (1 = refine, N = fanout, 0 = stop)
- *   2. For each task (parallel, bounded by `maxConcurrency`):
- *        a. round-robin an `AgentRunSpec` from `agentRuns`
- *        b. `sandboxClient.create({ backend: { profile }, ...overrides })`
- *        c. emit `loop.iteration.dispatch` with the placement
- *           (`{ sibling, sandboxId }` or `{ fleet, fleetId, machineId, sandboxId }`)
- *        d. iterate `box.streamPrompt(taskToPrompt(task))` and collect events
- *   3. `output.parse(events)` → typed `Output`
- *   4. `validator?.validate(output)` → `DefaultVerdict`
- *   5. Append `Iteration` to history; emit `loop.iteration.ended`
- *   6. `driver.decide(history)` → if terminal, return result + winner
- *
- * The kernel owns: iteration accounting, per-iteration timing, error
- * capture, abort propagation, concurrency cap, cost aggregation, and trace
- * 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 */
-interface RunLoopOptions<Task, Output, Decision> {
-    driver: Driver<Task, Output, Decision>;
-    /**
-     * Single agent spec — every iteration uses this profile. Mutually
-     * exclusive with `agentRuns`.
-     */
-    agentRun?: AgentRunSpec<Task>;
-    /**
-     * Multiple specs for heterogeneous fanout. The kernel round-robins
-     * through them when the driver plans N tasks. Mutually exclusive with
-     * `agentRun`.
-     */
-    agentRuns?: AgentRunSpec<Task>[];
-    output: OutputAdapter<Output>;
-    validator?: Validator<Output>;
-    task: Task;
-    ctx: ExecCtx;
-    /** Default 10. Hard cap on total iterations across all `plan()` rounds. */
-    maxIterations?: number;
-    /** Default 4. In-flight worker cap within a single `plan()` batch. */
-    maxConcurrency?: number;
-    /**
-     * Pre-allocated id for trace correlation. Default = `loop-${random}`.
-     * Surfaces as `runId` on every emitted `LoopTraceEvent`.
-     */
-    runId?: string;
-    /**
-     * Clock override; default `Date.now`. Deterministic tests pass a
-     * monotonic counter to stabilize iteration timing fields.
-     */
-    now?: () => number;
-    /**
-     * Override the default winner selector (highest-valid-score, ties broken
-     * by earliest iteration).
-     */
-    selectWinner?: (iterations: Iteration<Task, Output>[]) => LoopWinner<Task, Output> | undefined;
-}
-/** @experimental */
-declare function runLoop<Task, Output, Decision>(options: RunLoopOptions<Task, Output, Decision>): Promise<LoopResult<Task, Output, Decision>>;
-/**
- * Instantiate a sandbox for an `AgentRunSpec`: sets `backend.profile` to the
- * spec's profile (inferring the backend type when the spec doesn't override
- * it) and merges `sandboxOverrides`. Shared by the loop kernel and the
- * `AgentRuntime.act` sandbox bridge so both boot the sandbox identically.
- */
-declare function createSandboxForSpec<Task>(client: LoopSandboxClient, spec: AgentRunSpec<Task>, signal: AbortSignal): Promise<SandboxInstance>;
-
-/**
- * `loopDispatch` — turn `runLoop` into an agent-eval campaign dispatch.
- *
- * Without this adapter a consumer wiring `runLoop` into `runProfileMatrix` /
- * `runCampaign` has to, by hand, every time: (a) build an `ExecCtx` with a
- * sandbox client, (b) adapt the campaign `DispatchContext.trace` into a
- * `LoopTraceEmitter` (or lose all loop trace correlation), and (c) remember to
- * forward the loop's cost + tokens via `ctx.cost` (forgetting it yields a
- * `{0,0}` cell the backend-integrity guard reads as a stub). Three foot-guns,
- * the third silent. The fleet's products skipped (c) and fell back to a
- * `workerRecords[]` side-channel — the exact anti-pattern the substrate exists
- * to kill.
- *
- * `loopDispatch` collapses all three into one typed call:
- *
- *   const dispatch = loopDispatch({
- *     sandboxClient,
- *     toLoopOptions: (scenario, profile) => ({ driver, agentRun, output, validator, task }),
- *   })
- *   await runProfileMatrix({ profiles, scenarios, dispatch, judges, commitSha })
- *
- * Usage is reported automatically; trace events are forwarded automatically;
- * the ctx is built automatically. The seam becomes impossible to mis-wire.
- *
- * Typed structurally against the campaign `DispatchContext` (imported type-only
- * from `@tangle-network/agent-eval/campaign`) — a downward dependency, never an
- * inversion.
- */
-
-/** runLoop options minus the `ctx` (loopDispatch builds the ctx). */
-type LoopOptionsForDispatch<Task, Output, Decision> = Omit<RunLoopOptions<Task, Output, Decision>, 'ctx'>;
-interface LoopDispatchOptions<Task, Output, Decision, TScenario extends Scenario, TArtifact> {
-    /** Sandbox client used for every cell's `runLoop`. Supplied once. */
-    sandboxClient: LoopSandboxClient;
-    /** Build the per-cell runLoop options from the scenario (+ profile, when
-     *  used with `runProfileMatrix`). */
-    toLoopOptions: (scenario: TScenario, profile: AgentProfile$1) => LoopOptionsForDispatch<Task, Output, Decision>;
-    /** Map the finished loop to the artifact the judges score. Default:
-     *  `result.winner?.output`. A loop with no winner yields `undefined` (judges
-     *  skip the cell) — but the loop's token usage is STILL reported, so the
-     *  integrity guard sees real activity. */
-    toArtifact?: (result: LoopResult<Task, Output, Decision>) => TArtifact;
-    /** Forward `loop.*` trace events into the campaign's scoped trace so loop
-     *  spans correlate with the cell. Default true. */
-    forwardTrace?: boolean;
-    /** Cost-meter source label for the loop's spend. Default `'loop'`. */
-    costSource?: string;
-}
-/**
- * Adapter for `runProfileMatrix` (profile is an axis). Returns a
- * `ProfileDispatchFn` that runs `runLoop` per (profile, scenario) cell and
- * reports usage automatically.
- */
-declare function loopDispatch<Task, Output, Decision, TScenario extends Scenario, TArtifact>(opts: LoopDispatchOptions<Task, Output, Decision, TScenario, TArtifact>): ProfileDispatchFn<TScenario, TArtifact>;
-/**
- * Adapter for `runCampaign` (no profile axis). `toLoopOptions` receives only
- * the scenario; the `profile` passed to the shared core is a stable sentinel
- * so a single `runLoop` config is reused across cells.
- */
-declare function loopCampaignDispatch<Task, Output, Decision, TScenario extends Scenario, TArtifact>(opts: Omit<LoopDispatchOptions<Task, Output, Decision, TScenario, TArtifact>, 'toLoopOptions'> & {
-    toLoopOptions: (scenario: TScenario) => LoopOptionsForDispatch<Task, Output, Decision>;
-}): DispatchFn<TScenario, TArtifact>;
-
-/**
- * Bridge a finished `runLoop` into an agent-eval campaign / profile-matrix
- * dispatch.
- *
- * `runProfileMatrix` (and `runCampaign`) run the backend-integrity guard over
- * the token usage a dispatch reports through `ctx.cost`. A dispatch that wraps
- * `runLoop` must forward the loop's cost AND token usage, or the guard reads
- * the run as a stub and throws. `reportLoopUsage` is that one line:
- *
- *   const dispatch: ProfileDispatchFn<S, A> = async (profile, scenario, ctx) => {
- *     const result = await runLoop({ ...optsFor(profile, scenario), ctx: loopCtx })
- *     reportLoopUsage(ctx, result)
- *     return result.winner?.output as A
- *   }
- *
- * Typed structurally against the campaign `DispatchContext.cost` so this module
- * stays free of an agent-eval import — it works with any cost meter exposing
- * `observe` + `observeTokens`.
- */
-
-/** The slice of an agent-eval campaign `DispatchContext.cost` this needs. */
-interface UsageSink {
-    observe(amountUsd: number, source: string): void;
-    observeTokens(usage: {
-        input: number;
-        output: number;
-    }): void;
-}
-/**
- * Forward a `LoopResult`'s aggregated cost + token usage into a campaign cost
- * meter so the backend-integrity guard sees real LLM activity. `source`
- * defaults to `'loop'`.
- */
-declare function reportLoopUsage<Task, Output, Decision>(cost: UsageSink, result: Pick<LoopResult<Task, Output, Decision>, 'costUsd' | 'tokenUsage'>, source?: string): void;
-
-/**
- * Sandbox-event → runtime-event mapping.
- *
- * The sandbox SDK emits a polymorphic `SandboxEvent = { type, data, id? }`
- * whose `type` vocabulary is backend-determined (opencode, etc.) rather than
- * enumerated by the SDK. Two consumers project it:
- *   - the loop kernel's cost ledger (`extractLlmCallEvent`) — sums usage off
- *     every cost-bearing event, regardless of stream shape;
- *   - the `AgentRuntime.act` streaming contract (`mapSandboxEvent`) — projects
- *     incremental events to the `RuntimeStreamEvent` chat-UX vocabulary.
- *
- * Both live here so the empirically-observed `type` vocabulary has one home.
- */
-
-/**
- * Extract a `RuntimeStreamEvent`-shaped `llm_call` from a sandbox event when
- * the event carries usage/cost data. Returns `undefined` for non-cost events
- * so the kernel can iterate the full stream without branching.
- *
- * Canonical cost-carrying types observed in the wild:
- *   - `llm_call` — `data: { model, tokensIn, tokensOut, costUsd, ... }`
- *   - `message.completed` / `result` — `data: { usage: { inputTokens,
- *      outputTokens, totalCostUsd? } }`
- *   - `cost.usage` / `usage` — same shape under a dedicated type
- *
- * Numeric coercion is strict: `Number.isFinite` gates every accumulator write
- * so a sentinel `NaN` from a misbehaving backend cannot poison the ledger.
- */
-declare function extractLlmCallEvent(event: SandboxEvent, agentRunName: string): (RuntimeStreamEvent & {
-    type: 'llm_call';
-}) | undefined;
-/**
- * Project one `SandboxEvent` onto the `RuntimeStreamEvent` chat-UX vocabulary,
- * for runtimes that bridge a sandbox `streamPrompt` into the
- * `AgentRuntime.act` streaming contract. Returns `undefined` for events that
- * have no faithful projection — the raw stream is preserved separately for the
- * `OutputAdapter`, so an unmapped event never loses data.
- *
- * Mapped (the task-optional incremental variants — no synthesized task
- * lifecycle, no guessed tool-part shapes):
- *   - `message.part.updated` text part → `text_delta`
- *   - `message.part.updated` reasoning/thinking part → `reasoning_delta`
- *   - cost-bearing events → `llm_call` (shared with the ledger extractor)
- *
- * The opencode backend emits incremental text as
- * `{ type: 'message.part.updated', data: { part: { type, text }, delta } }`;
- * `delta` is the increment, `part.text` the running accumulation.
- */
-declare function mapSandboxEvent(event: SandboxEvent, opts?: {
-    agentRunName?: string;
-}): RuntimeStreamEvent | undefined;
-
-export { AgentRunSpec, type CreateFanoutVoteDriverOptions, type CreateRefineDriverOptions, type CreateSandboxPlannerOptions, Driver, ExecCtx, type FanoutVoteDecision, type FanoutVoteScored, Iteration, type LoopDispatchOptions, type LoopOptionsForDispatch, LoopResult, LoopSandboxClient, LoopWinner, OutputAdapter, PlannerContext, type RefineDecision, type RunLoopOptions, type TopologyMoveEnvelope, TopologyPlanner, type UsageSink, Validator, createFanoutVoteDriver, createRefineDriver, createSandboxForSpec, createSandboxPlanner, extractLlmCallEvent, loopCampaignDispatch, loopDispatch, mapSandboxEvent, refineWinnerIndex, reportLoopUsage, runLoop, scoreFanoutVoteIterations };
+import '@tangle-network/agent-eval/campaign';
+import './runtime-hooks-C7JwKb9E.js';