@tangle-network/agent-runtime 0.45.0 → 0.47.0

package/dist/{types-1HbsFa7H.d.ts → types-Cbx3dNK5.d.ts}

@@ -1,7 +1,7 @@
 import { DefaultVerdict } from '@tangle-network/agent-eval';
 import { AgentProfile, BackendType } from '@tangle-network/sandbox';
 import { R as RuntimeHooks } from './runtime-hooks-C7JwKb9E.js';
-import { d as LoopTokenUsage } from './types-DdzkffAm.js';
+import { c as LoopTokenUsage } from './types-nBMuollC.js';
 
 /**
  * @experimental
@@ -19,7 +19,7 @@ import { d as LoopTokenUsage } from './types-DdzkffAm.js';
  *  - The journal records a content-addressed `outRef` per child result, so replay
  *    rehydrates the exact `Settled` the driver branched on (the replay invariant below).
  *
- * The leaf RUNTIME is one OPEN `LeafExecutor` interface, not a closed `inline|sandbox|cli`
+ * The leaf RUNTIME is one OPEN `Executor` interface, not a closed `inline|sandbox|cli`
  * union the call site switches on. The built-ins (router/inline, sandbox, cli) are the
  * initial IMPLEMENTATIONS; any user agent is first-class the moment it implements the
  * interface. The interface IS the extension point — no per-vendor adapters live here.
@@ -45,7 +45,7 @@ interface Agent<Task, Out> {
 }
 /**
  * The leaf runtime — ONE open interface, not a closed union. `execute` returns a
- * `Promise<LeafResult>` for one-shot executors OR an `AsyncIterable<UsageEvent>` for
+ * `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
@@ -57,7 +57,7 @@ interface Agent<Task, Out> {
  * (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 LeafExecutor<Out> {
+interface Executor<Out> {
     /** Stable runtime tag for traces + the equal-k exemption check. */
     readonly runtime: Runtime;
     /**
@@ -67,11 +67,11 @@ interface LeafExecutor<Out> {
      */
     readonly budgetExempt?: boolean;
     /**
-     * One-shot → resolves a `LeafResult`; streaming → yields incremental `UsageEvent`s and
+     * 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<LeafResult<Out>> | AsyncIterable<UsageEvent>;
+    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_worker`
      * verb). A streaming executor drains pending messages between turns and folds them into the next
@@ -98,8 +98,8 @@ interface LeafExecutor<Out> {
         spent: Spend;
     };
 }
-/** Terminal artifact of a one-shot `LeafExecutor.execute`. */
-interface LeafResult<Out> {
+/** Terminal artifact of a one-shot `Executor.execute`. */
+interface ExecutorResult<Out> {
     outRef: string;
     out: Out;
     verdict?: DefaultVerdict;
@@ -120,7 +120,7 @@ type UsageEvent = {
 } | {
     kind: 'iteration';
 };
-/** The runtime tag of a `LeafExecutor` impl. Open by intent — `string` so a BYO executor
+/** The runtime tag of a `Executor` impl. Open by intent — `string` so a BYO executor
  *  names its own runtime; the built-ins use these literals. */
 type Runtime = 'router' | 'inline' | 'sandbox' | 'cli' | (string & {});
 /**
@@ -129,7 +129,7 @@ type Runtime = 'router' | 'inline' | 'sandbox' | 'cli' | (string & {});
  * 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 `LeafExecutor`).
+ *  - `executor` present        → BYO: use it verbatim (a user's own `Executor`).
  *  - `harness === null`        → router/inline: a direct Router call, no box.
  *  - `harness` is a `BackendType` → sandbox: compose `runLoop` against `profile` on that backend.
  * Fail loud on an unresolvable spec (no executor and an unknown harness).
@@ -139,15 +139,15 @@ interface AgentSpec {
     /** `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?: LeafExecutor<unknown>;
+    readonly executor?: Executor<unknown>;
 }
 /**
- * Builds a fresh `LeafExecutor` for one spawn from the resolved spec. Per-spawn (not
+ * 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 LeafExecutorFactory<Out> = (spec: AgentSpec, ctx: ExecutorContext) => LeafExecutor<Out>;
-/** Construction context handed to a `LeafExecutorFactory` — the seams a built-in needs
+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 {
@@ -156,14 +156,14 @@ interface ExecutorContext {
     readonly seams: Readonly<Record<string, unknown>>;
 }
 /**
- * The OPEN resolver: maps an `AgentSpec` to a `LeafExecutorFactory`. The default
+ * 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 `LeafExecutor` interface.
+ * 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: LeafExecutorFactory<Out>): void;
+    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
@@ -172,7 +172,7 @@ interface ExecutorRegistry {
      */
     resolve<Out>(spec: AgentSpec): {
         succeeded: true;
-        value: LeafExecutorFactory<Out>;
+        value: ExecutorFactory<Out>;
     } | {
         succeeded: false;
         error: string;
@@ -245,9 +245,9 @@ type Settled<Out> = {
 };
 /**
  * The budget-conserving reactive scope an `Agent.act` runs inside. `spawn` reserves
- * budget atomically from the shared pool and FAILS CLOSED when the pool can't cover it;
- * `next()` is a ray.wait cursor (n=1) over THIS scope's IN-MEMORY live set; `view` reads
- * the in-memory nursery (NOT the log), O(live).
+ * 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> {
     /**
@@ -367,7 +367,7 @@ interface SupervisorOpts {
     readonly journal: SpawnJournal;
     /** Result payload store backing `outRef` rehydration. */
     readonly blobs: ResultBlobStore;
-    /** Executor resolution — the open registry mapping `AgentSpec` → `LeafExecutor`. */
+    /** Executor resolution — the open registry mapping `AgentSpec` → `Executor`. */
     readonly executors: ExecutorRegistry;
     /** Runtime recursion-depth ceiling (paired with the conserved pool per R3). */
     readonly maxDepth?: number;
@@ -435,4 +435,4 @@ interface WidenGate<Out> {
     readonly judgeExempt?: boolean;
 }
 
-export type { Agent as A, Budget as B, ExecutorRegistry as E, Handle as H, LeafExecutorFactory as L, NodeId as N, ResultBlobStore as R, Scope as S, TreeView as T, UsageEvent as U, WidenGate as W, SpawnJournal as a, SpawnEvent as b, Settled as c, AgentSpec as d, RootHandle as e, SupervisedResult as f, Spend as g, Supervisor as h, ExecutorContext as i, LeafExecutor as j, LeafResult as k, NodeSnapshot as l, NodeStatus as m, Restart as n, RootSignal as o, Runtime as p, SpawnOpts as q, SupervisorOpts as r };
+export type { Agent as A, Budget as B, ExecutorFactory as E, Handle as H, NodeId as N, ResultBlobStore as R, Scope as S, TreeView as T, UsageEvent as U, WidenGate as W, SpawnJournal as a, SpawnEvent as b, Settled as c, AgentSpec as d, ExecutorRegistry as e, RootHandle as f, SupervisedResult as g, Spend as h, Supervisor as i, Executor as j, ExecutorContext as k, ExecutorResult as l, NodeSnapshot as m, NodeStatus as n, Restart as o, RootSignal as p, Runtime as q, SpawnOpts as r, SupervisorOpts as s };

package/dist/{types-DdzkffAm.d.ts → types-nBMuollC.d.ts}

@@ -639,6 +639,12 @@ declare function startRuntimeRun(options: RuntimeRunOptions): RuntimeRunHandle;
 interface ValidationCtx {
     /** Iteration index this output came from (0-based). */
     iteration: number;
+    /**
+     * Live sandbox for this iteration. Validators that need execution-grounded
+     * evidence can inspect files or run commands here instead of forcing callers
+     * to bypass the loop kernel with raw Sandbox SDK orchestration.
+     */
+    box?: SandboxInstance;
     /** Cooperative cancellation channel. */
     signal: AbortSignal;
     /**
@@ -668,6 +674,17 @@ interface AgentRunSpec<Task> {
     profile: AgentProfile;
     /** Task → prompt formatter. Pure and deterministic. */
     taskToPrompt: (task: Task) => string;
+    /**
+     * Optional pre-prompt sandbox provisioner. Runs after the sandbox is acquired
+     * and before the first prompt is streamed into that box. Use this for
+     * domain-agnostic setup such as repo snapshots, benchmark fixtures, policy
+     * files, or seed datasets. The hook is part of the runtime surface so loop
+     * consumers do not hand-roll Sandbox SDK orchestration just to prepare a
+     * workspace before the agent sees it.
+     */
+    prepareBox?: (box: SandboxInstance, ctx: {
+        signal: AbortSignal;
+    }) => Promise<void> | void;
     /**
      * Per-spec stable name. Surfaced in trace events and the default winner
      * selector tiebreak. Falls back to `profile.name ?? 'agent'`.
@@ -745,7 +762,7 @@ interface Driver<Task, Output, Decision> {
      * move + rationale (not just the inferred fan-width). Drivers whose topology
      * is a pure function of count (refine/fanout-vote) omit it — the kernel
      * infers `moveKind` from the planned-task count. Agent-authored drivers
-     * (`createDynamicDriver`) return their chosen move's kind + rationale.
+     * (`createDriver`) return their chosen move's kind + rationale.
      */
     describePlan?(): LoopPlanDescription | undefined;
     /**
@@ -807,7 +824,7 @@ interface LoopResult<Task, Output, Decision> {
  *
  * @experimental
  */
-interface LoopSandboxClient {
+interface SandboxClient {
     create(options?: CreateSandboxOptions): Promise<SandboxInstance>;
     describePlacement?(box: SandboxInstance): LoopSandboxPlacement;
     /**
@@ -840,7 +857,7 @@ interface LoopSandboxClient {
  * `describePlan` — refine, fanout-vote), the kernel prunes boxes no future
  * round can reach after each round, so the live set tracks the active frontier.
  * When the driver authors its own branch point (`describePlan().parentIndex` —
- * `createDynamicDriver`), it may descend from any prior
+ * `createDriver`), it may descend from any prior
  * iteration, so no box is pruned and the live-box count rises to the total
  * iterations across all rounds. Size `forkFanout` runs accordingly (CRIU forks
  * are copy-on-write, but each is still a live box until loop end).
@@ -878,6 +895,18 @@ interface LoopLineageOptions {
      * different-per-branch profiles use the unforked fanout path.
      */
     forkFanout?: boolean;
+    /**
+     * Per-turn sandbox streaming mode. Default `'sse'` (live `streamPrompt` —
+     * low-latency, full per-token trace; best for interactive chat). `'poll'`
+     * fire-and-detaches via `dispatchPrompt` and awaits the terminal result by
+     * status-polling, so a long, quiet in-box turn (clone + build + test) never
+     * holds a live stream a proxy idle-timeout can drop mid-execution. Lower trace
+     * fidelity (one terminal event), so it is opt-in — intended for BATCH eval
+     * runs, which don't need live streaming and were losing long turns to the
+     * idle-drop. Applies to the default fresh-box path too, not only when
+     * `sessionContinuity`/`forkFanout` are on.
+     */
+    streaming?: 'sse' | 'poll';
 }
 /** @experimental */
 interface LoopSandboxPlacement {
@@ -1041,7 +1070,7 @@ interface LoopTeardownFailedPayload {
 /** @experimental */
 interface ExecCtx {
     /** Sandbox SDK client — the kernel calls `.create()` per iteration. */
-    sandboxClient: LoopSandboxClient;
+    sandboxClient: SandboxClient;
     /** Optional runtime hooks. Execution-scoped; never part of `AgentProfile`. */
     hooks?: RuntimeHooks;
     /** Optional trace emitter. When set, the kernel emits `loop.*` events. */
@@ -1067,4 +1096,4 @@ interface ExecCtx {
     parentSpanId?: string;
 }
 
-export { type AgentRunSpec as A, type AgentTaskStatus as B, type RuntimeSessionStore as C, type Driver as D, type ExecCtx as E, type RuntimeSession as F, type AgentAdapter as G, type AgentKnowledgeProvider as H, type Iteration as I, type AgentRuntimeEventSink as J, type KnowledgeReadinessDecision as K, type LoopWinner as L, type AgentTaskContext as M, type AgentTaskSpec as N, type OutputAdapter as O, type BackendErrorDetail as P, type RuntimeRunHandle as Q, type RuntimeStreamEvent as R, type RuntimeRunPersistenceAdapter as S, type RuntimeRunRow as T, startRuntimeRun as U, type Validator as V, type LoopLineageOptions as a, type LoopSandboxClient as b, type LoopResult as c, type LoopTokenUsage as d, type OpenAIChatTool as e, type LoopTraceEmitter as f, type LoopSandboxPlacement as g, type LoopDecisionPayload as h, type LoopEndedPayload as i, type LoopIterationDispatchPayload as j, type LoopIterationEndedPayload as k, type LoopIterationStartedPayload as l, type LoopPlanDescription as m, type LoopPlanPayload as n, type LoopStartedPayload as o, type LoopTeardownFailedPayload as p, type LoopTraceEvent as q, type ValidationCtx as r, type AgentBackendInput as s, type AgentExecutionBackend as t, type OpenAIChatToolChoice as u, type AgentBackendContext as v, type RunAgentTaskOptions as w, type AgentTaskRunResult as x, type RunAgentTaskStreamOptions as y, type AgentRuntimeEvent as z };
+export { type AgentRunSpec as A, type BackendErrorDetail as B, type LoopDecisionPayload as C, type Driver as D, type ExecCtx as E, type LoopEndedPayload as F, type LoopIterationDispatchPayload as G, type LoopIterationEndedPayload as H, type Iteration as I, type LoopIterationStartedPayload as J, type KnowledgeReadinessDecision as K, type LoopWinner as L, type LoopPlanDescription as M, type LoopPlanPayload as N, type OutputAdapter as O, type LoopStartedPayload as P, type LoopTeardownFailedPayload as Q, type RuntimeStreamEvent as R, type SandboxClient as S, type LoopTraceEvent as T, type ValidationCtx as U, type Validator as V, type LoopLineageOptions as a, type LoopResult as b, type LoopTokenUsage as c, type OpenAIChatTool as d, type LoopTraceEmitter as e, type LoopSandboxPlacement as f, type AgentBackendInput as g, type AgentExecutionBackend as h, type OpenAIChatToolChoice as i, type AgentBackendContext as j, type RunAgentTaskOptions as k, type AgentTaskRunResult as l, type RunAgentTaskStreamOptions as m, type AgentRuntimeEvent as n, type AgentTaskStatus as o, type RuntimeSessionStore as p, type RuntimeSession as q, type AgentAdapter as r, type AgentKnowledgeProvider as s, type AgentRuntimeEventSink as t, type AgentTaskContext as u, type AgentTaskSpec as v, type RuntimeRunHandle as w, type RuntimeRunPersistenceAdapter as x, type RuntimeRunRow as y, startRuntimeRun as z };

package/dist/{types-BtRLF2U3.d.ts → types-p8dWBIXL.d.ts}

@@ -242,4 +242,4 @@ type AnalystLoopEvent = {
     durationMs: number;
 };
 
-export type { AnalystRegistryLike as A, FindingsStoreLike as F, ImprovementAdapter as I, KnowledgeAdapter as K, RunAnalystLoopOpts as R, RunAnalystLoopResult as a, AnalystLoopEvent as b, AnalystRegistryStreamingLike as c, AutoApplyPolicy as d, ImprovementEditBatch as e, ImprovementReport as f, KnowledgeProposalBatch as g, KnowledgeReport as h };
+export type { AnalystLoopEvent as A, FindingsStoreLike as F, ImprovementAdapter as I, KnowledgeAdapter as K, RunAnalystLoopOpts as R, RunAnalystLoopResult as a, AnalystRegistryLike as b, AnalystRegistryStreamingLike as c, AutoApplyPolicy as d, ImprovementEditBatch as e, ImprovementReport as f, KnowledgeProposalBatch as g, KnowledgeReport as h };

package/dist/workflow.d.ts

@@ -1,6 +1,6 @@
 import { AgentProfile, CreateSandboxOptions, PromptOptions, TaskOptions, SandboxEvent } from '@tangle-network/sandbox';
-import { b as LoopSandboxClient, O as OutputAdapter, g as LoopSandboxPlacement, c as LoopResult } from './types-DdzkffAm.js';
-import { R as RunLoopOptions } from './run-loop--hSoIknW.js';
+import { S as SandboxClient, O as OutputAdapter, f as LoopSandboxPlacement, b as LoopResult } from './types-nBMuollC.js';
+import { R as RunLoopOptions } from './run-loop-DvD4aGiE.js';
 import '@tangle-network/agent-eval';
 import './runtime-hooks-C7JwKb9E.js';
 
@@ -437,7 +437,7 @@ interface WorkflowSandboxAgentTrace<TOutput = unknown> {
     tokenUsage: WorkflowTokenUsage;
 }
 interface CreateSandboxWorkflowAgentDelegateOptions<TOutput = unknown> {
-    client: LoopSandboxClient;
+    client: SandboxClient;
     profile: WorkflowSandboxAgentProfileResolver;
     output?: OutputAdapter<TOutput>;
     stream?: WorkflowSandboxAgentStream;

package/dist/workflow.js

@@ -2,11 +2,11 @@ import {
   createSandboxForSpec,
   describeSandboxPlacement,
   runLoop
-} from "./chunk-KEWO4KI6.js";
+} from "./chunk-72JQCHOZ.js";
 import {
   ValidationError,
   extractLlmCallEvent
-} from "./chunk-PRX45WE2.js";
+} from "./chunk-GSUO5QS6.js";
 import "./chunk-DGUM43GV.js";
 
 // src/workflow/agent-delegate.ts