@tangle-network/agent-runtime 0.87.0 → 0.88.0

package/dist/{chunk-LCXXIL3U.js → chunk-ZQZX77MM.js}

@@ -1,6 +1,6 @@
 import {
   extractLlmCallEvent
-} from "./chunk-QUXZBZCS.js";
+} from "./chunk-FVJ7M3DA.js";
 import {
   AnalystError
 } from "./chunk-YEJR7IXO.js";
@@ -579,4 +579,4 @@ export {
   iterationsToTraceStore,
   runAnalystLoop
 };
-//# sourceMappingURL=chunk-LCXXIL3U.js.map
+//# sourceMappingURL=chunk-ZQZX77MM.js.map

package/dist/index.js

@@ -1,7 +1,7 @@
 import {
   mcpToolsForRuntimeMcp,
   mcpToolsForRuntimeMcpSubset
-} from "./chunk-MHYF2LIP.js";
+} from "./chunk-JHULWWQD.js";
 import {
   DEFAULT_ROUTER_BASE_URL,
   cleanModelId,
@@ -20,7 +20,7 @@ import {
   runLoopRunnerCli,
   selfImproveLoopRunner,
   worktreeLoopRunner
-} from "./chunk-FLVVVBWV.js";
+} from "./chunk-HBE77SWV.js";
 import "./chunk-SGKPNBXE.js";
 import {
   InMemoryRuntimeSessionStore,
@@ -31,14 +31,14 @@ import {
   normalizeBackendStreamEvent,
   nowIso,
   touchSession
-} from "./chunk-VKVNDNG4.js";
+} from "./chunk-22HPUH77.js";
 import {
   assertModelAllowed,
   composeRuntimeHooks,
   defineRuntimeHooks,
   notifyRuntimeDecisionPoint,
   notifyRuntimeHookEvent
-} from "./chunk-6XCW3M7W.js";
+} from "./chunk-LRNRPJAV.js";
 import {
   INTELLIGENCE_WIRE_VERSION,
   buildLoopOtelSpans,
@@ -48,8 +48,8 @@ import {
   loopEventToOtelSpan
 } from "./chunk-UD4BHQMI.js";
 import "./chunk-BZF3KQ6G.js";
-import "./chunk-LCXXIL3U.js";
-import "./chunk-QUXZBZCS.js";
+import "./chunk-ZQZX77MM.js";
+import "./chunk-FVJ7M3DA.js";
 import {
   agenticGenerator,
   commandVerifier,

package/dist/loop-runner-bin.js

@@ -2,14 +2,14 @@
 import {
   parseLoopRunnerArgv,
   runLoopRunnerCli
-} from "./chunk-FLVVVBWV.js";
+} from "./chunk-HBE77SWV.js";
 import "./chunk-SGKPNBXE.js";
-import "./chunk-VKVNDNG4.js";
-import "./chunk-6XCW3M7W.js";
+import "./chunk-22HPUH77.js";
+import "./chunk-LRNRPJAV.js";
 import "./chunk-UD4BHQMI.js";
 import "./chunk-BZF3KQ6G.js";
-import "./chunk-LCXXIL3U.js";
-import "./chunk-QUXZBZCS.js";
+import "./chunk-ZQZX77MM.js";
+import "./chunk-FVJ7M3DA.js";
 import "./chunk-7LO5GMAO.js";
 import "./chunk-YEJR7IXO.js";
 import "./chunk-DPEUKJRO.js";

package/dist/loops.d.ts

@@ -2,7 +2,7 @@ import { ChatClient, RunRecord, HarnessType, AgentProfile, AnalystFinding, Analy
 export { AnalystFinding, DefaultVerdict, computeFindingId, makeFinding } from '@tangle-network/agent-eval';
 import { SandboxEvent, SandboxInstance, CreateSandboxOptions, PromptOptions, TaskOptions } 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-Driepl87.js';
+import { d as ResultBlobStore, S as SpawnJournal, N as NodeId, j as SpawnEvent, E as ExecutorFactory, i as Scope, c as Agent, b as ExecutorRegistry, B as Budget, g as Settled, f as SupervisedResult, h as Spend, U as UsageEvent, 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';
@@ -679,6 +679,11 @@ interface DefinedLeaderboard<TCase, TArtifact = string> {
     /** The same domain surface in the structural `BenchmarkAdapter` shape. */
     toBenchmarkAdapter(): LeaderboardBenchmarkAdapter<TArtifact>;
 }
+/**
+ * Assemble a declarative spec (`cases` + `prompt` + `score`) into a runnable
+ * harness×model leaderboard — `run()` executes the matrix, `toBenchmarkAdapter()`
+ * exposes the same domain as a structural `BenchmarkAdapter`.
+ */
 declare function defineLeaderboard<TCase, TArtifact = string>(spec: LeaderboardSpec<TCase, TArtifact>): DefinedLeaderboard<TCase, TArtifact>;
 
 /**
@@ -874,6 +879,182 @@ declare function inProcessSandboxClient(options: InProcessSandboxClientOptions):
  */
 declare function inlineSandboxClient(factory: ExecutorFactory<unknown>): SandboxClient;
 
+/**
+ *
+ * The loop-executor — a spawnable, budget-conserving, gated, STEERABLE multi-round loop
+ * as a first-class atom, the sibling of the recursive driver-executor.
+ *
+ * A leaf worker runs one turn and settles. A driver child (driver-executor.ts) runs an
+ * LLM brain that spawns children and reacts. A LOOP child is the third shape: a CODED loop
+ * whose control flow is written, not left to a model's judgment. On `execute` it mounts a
+ * NESTED `Scope` (via the same `nested-scope` seam the driver-executor uses) one `depth`
+ * deeper over the SAME conserved pool + shared journal/blobs + open registry, then runs the
+ * authored loop's `round(ctx)` up to `maxRounds` times. Each round may spawn children into
+ * that nested scope (conserved budget, depth-bounded), and the runtime — not the authored
+ * body — owns the three guarantees a "loop" must make:
+ *
+ *  - BOUNDED: at most `maxRounds` rounds; the run-wide conserved pool still fails a spawn
+ *    closed at any depth, so a loop can never overspend the root ceiling.
+ *  - GATED: the loop settles `valid` iff its deployable `check(out)` passes (the completion
+ *    oracle, same discipline as `gateOnDeliverable`). A loop that exhausts `maxRounds`
+ *    without the check ever passing settles `valid: false` — ran, did not deliver.
+ *  - STEERABLE: the executor owns an `Inbox` and exposes `deliver`, so a supervisor's
+ *    `steer_agent` (→ `Scope.send` → this `deliver`) lands between rounds. Queued messages
+ *    fold into the next round's `ctx.steer`; a forceful `interrupt` aborts the in-flight
+ *    round's linked signal so the loop re-plans immediately with the message folded in.
+ *
+ * Why this preserves every keystone invariant: identical to the driver-executor — the SCOPE
+ * owns the sharing (nested scope over `args.pool`, one `SpawnJournal` tree per child), this
+ * executor only runs the coded loop over what the scope mounts and rolls the sub-tree's
+ * conserved spend up on settle. It builds NO new budget, journal, or selection logic.
+ *
+ * The authored loop body is `defineLoop(name, { maxRounds, round, check })`. `round` is
+ * ordinary code — arbitrary composition inside a round (spawn one child, fan out many,
+ * pipeline) — while the runtime owns iteration, the budget, the gate, and steer-folding.
+ * So a loop is "codemode" (the author writes control flow) yet structurally bounded.
+ *
+ * @experimental
+ */
+
+/** The runtime tag the registry maps a loop child to. */
+declare const loopRuntime: "loop";
+/** What one round of a loop receives. The scope is the NESTED scope — spawn conserved
+ *  children here; budget/depth are enforced by the scope, not the body. */
+interface LoopRoundCtx {
+    /** The spawn task, verbatim. */
+    readonly task: unknown;
+    /** The nested, conserved scope. Spawn children with `scope.spawn`, react with `scope.next`. */
+    readonly scope: Scope<unknown>;
+    /** 1-based round index. */
+    readonly round: number;
+    /** The declared ceiling on rounds. */
+    readonly maxRounds: number;
+    /** Supervisor `steer_agent` messages that arrived since the last round, folded to text. */
+    readonly steer: readonly string[];
+    /** Conserved-pool readouts (post-reservation) for in-body budget-awareness. */
+    readonly budget: Scope<unknown>['budget'];
+    /** Abort signal: the spawn signal + nested-scope signal + a fresh per-round interrupt.
+     *  A forceful steer during the round aborts THIS signal so the body can break and re-plan. */
+    readonly signal: AbortSignal;
+}
+/** What a round returns. `out` is the running result; `done: true` stops the loop early
+ *  (the author's own stop condition, distinct from the runtime's gate `check`). */
+interface LoopRoundResult {
+    readonly out: unknown;
+    readonly done?: boolean;
+}
+/** An authored coded loop: a name, a round ceiling, the round body, and an optional
+ *  deployable gate `check`. `check` decides DELIVERED — the loop settles `valid` iff it
+ *  passes — and is polled after each round to stop as soon as the loop has delivered. */
+interface LoopDef {
+    readonly name: string;
+    readonly maxRounds: number;
+    round(ctx: LoopRoundCtx): Promise<LoopRoundResult>;
+    /** The deployable completion oracle. `settled.valid ⟺ this resolves true`. A throwing
+     *  check is fail-closed (not delivered). Omit for a loop whose only stop is `done`. */
+    check?(out: unknown): boolean | Promise<boolean>;
+    /** What the loop was supposed to produce — surfaced in traces. */
+    readonly describe?: string;
+}
+/** One named agent in a MULTI-AGENT loop (the `agents` form of `defineLoop`). `run` does the
+ *  agent's work for a round; `prior` is the previous agent's output, or `ctx.task` for the first.
+ *  The last agent's return is the round's `out`. So a proposer→verifier loop is just two agents. */
+interface LoopAgent {
+    /** A short, human name for the agent this plays (proposer, verifier, engineer). */
+    readonly name: string;
+    run(ctx: LoopRoundCtx, prior: unknown): Promise<unknown>;
+}
+/**
+ * Author a coded loop atom. The returned `LoopDef` is handed to `loopChild` to become a
+ * spawnable `Agent`. The runtime owns `maxRounds`, the conserved budget, the gate, and
+ * steer-folding; you supply ONE of two round shapes:
+ *
+ *  - `round` — freeform: write the whole round yourself (arbitrary code, may spawn children).
+ *  - `agents` — declarative MULTI-AGENT: an ordered list of named agents piped each round
+ *    (`task → agents[0] → agents[1] → … → out`). "How many agents" is self-evident from the
+ *    list, so a two-agent research loop is `agents: [proposer, verifier]` — no bespoke function.
+ *
+ * Provide EXACTLY one of `round` / `agents`.
+ */
+declare function defineLoop(name: string, spec: {
+    maxRounds: number;
+    round?: (ctx: LoopRoundCtx) => Promise<LoopRoundResult>;
+    agents?: readonly LoopAgent[];
+    check?: (out: unknown) => boolean | Promise<boolean>;
+    describe?: string;
+}): LoopDef;
+/**
+ * Mark + carry an authored loop so the recursive registry resolves it to the
+ * loop-executor. The returned agent is SPAWNED (never run directly): its `executorSpec` is
+ * marked `role: 'loop'` and carries the `LoopDef` + the shared journal. `act` fails loud if
+ * called directly — a loop child runs THROUGH its nested-scope executor, never as a root.
+ */
+declare function loopChild<Out>(loop: LoopDef, journal: SpawnJournal): Agent<unknown, Out>;
+/**
+ * Register the loop-executor so a child marked `role: 'loop'` resolves to it. Mirrors
+ * `withDriverExecutor`: a loop-role spec → the loop-executor; everything else → the base
+ * registry's resolution. Compose it WITH `withDriverExecutor` so loops and drivers coexist:
+ * `withLoopExecutor(withDriverExecutor(base))`.
+ */
+declare function withLoopExecutor(base: ExecutorRegistry): ExecutorRegistry;
+
+/**
+ * authorLoop — the codemode layer over the loop atom: an LLM reads a goal + the defineLoop
+ * contract and WRITES a coded loop as a module; the caller spawns it as a first-class atom
+ * (`loopChild` → the loop-executor) and it settles gated on its own `check`, budget-conserved
+ * and depth-bounded like any spawned child.
+ *
+ * This is to `defineLoop` what `authorStrategy` is to `defineStrategy`: the "supervisor writes
+ * the loop" seam. The authored body composes real code (spawns children on the nested scope,
+ * fans out, pipelines) while the runtime owns iteration, the conserved budget, the gate, and
+ * steer-between-rounds — so an authored loop can be WRONG but cannot overspend the pool or
+ * skip the completion check.
+ *
+ * Safety is structural, not a sandbox (mirrors `authorStrategy`): the same `assertStrategyContract`
+ * lint bounds the module to the loops import and bans out-of-band compute (require/eval/fetch/
+ * process/node builtins), and the authored module is written to `outDir` and dynamically imported
+ * under a TS-capable loader (tsx) since models emit type annotations.
+ */
+
+/** The compressed consumable a skill carries: everything an author needs to emit a loop atom. */
+declare const loopAuthorContract = "\nYou author a LOOP ATOM for an agent supervisor. A loop runs a bounded, multi-round journey\ntoward a deployable check; a supervisor spawns / observes / steers it exactly like a worker.\nYou write ONE round; the runtime owns the round ceiling, the conserved budget, the gate, and\nfolding a supervisor's steer into the next round. So write real control flow inside a round,\nbut never write the loop's stop condition as \"hope the model stops\" \u2014 that is the runtime's job.\n\nYou export ONE module of EXACTLY this shape (no other imports, no commentary outside the code):\n\nimport { defineLoop } from '@tangle-network/agent-runtime/loops'\nexport default defineLoop('your-loop-name', {\n  maxRounds: 3,\n  round: async ({ task, scope, round, maxRounds, steer, budget, signal }) => {\n    // arbitrary code for ONE round. Do real work by spawning children on the nested scope:\n    //   const w = scope.spawn(childAgent, subtask, { budget: perRound, label: `r${round}` })\n    //   if (!w.ok) throw new Error(w.reason)      // fail loud: budget-exhausted | depth-exceeded\n    //   const settled = await scope.next()        // conserved child work; settles gated\n    // 'steer' is the supervisor's messages since the last round (fold them into what you do next).\n    // 'signal' aborts if a forceful steer arrives mid-round \u2014 pass it to your awaited work.\n    return { out: /* the running result */ undefined, done: false }  // done:true stops early\n  },\n  check: (out) => /* the deployable completion oracle */ Boolean(out),\n})\n\nFor a MULTI-AGENT loop (a proposer then a verifier, a researcher then an engineer), do NOT\nhand-write the pipeline in 'round' \u2014 use 'agents' instead: an ordered list of named agents piped\neach round (task -> agents[0] -> agents[1] -> ... -> out). \"How many agents\" is then self-evident.\n\nimport { defineLoop } from '@tangle-network/agent-runtime/loops'\nexport default defineLoop('your-loop-name', {\n  maxRounds: 3,\n  agents: [\n    { name: 'proposer', run: async (ctx, prior) => { /* spawn a worker, produce a draft */ return draft } },\n    { name: 'verifier', run: async (ctx, prior) => { /* verify/refine the proposer's draft */ return checked } },\n  ],\n  check: (out) => Boolean(out),\n})\n\nProvide EXACTLY one of 'round' or 'agents'. The round context (for the 'round' form, and passed to\neach agent's run as its first arg):\n  task       the spawn task, verbatim.\n  scope      the NESTED conserved scope. scope.spawn(agent, task, { budget, label }) reserves\n             budget and fails closed; scope.next() awaits one child settlement. Budget NESTS \u2014\n             the pool reserves each spawn's full ceiling until it settles, so give children a\n             per-round budget smaller than the loop's own.\n  round      1-based round index. maxRounds is the declared ceiling.\n  steer      readonly string[] \u2014 supervisor steer_agent messages that arrived since last round.\n  budget     conserved-pool readouts (tokensLeft, usdLeft, deadlineMs) for in-body awareness.\n  signal     AbortSignal \u2014 the spawn signal + a fresh per-round interrupt; honor it in awaits.\n\nThe round result: { out: unknown; done?: boolean }. 'out' is the running result the gate reads;\n'done: true' is YOUR early stop (distinct from the runtime's gate 'check').\n\ncheck(out): boolean | Promise<boolean>. The DEPLOYABLE oracle \u2014 an executable test, a state\nverifier, a readiness score threshold \u2014 read off 'out', never the model judging itself. The loop\nsettles valid IFF check passes, and the runtime polls it after each round to stop the instant the\nloop has delivered. A loop that exhausts maxRounds without check passing settles valid:false.\n\nRules:\n- ALWAYS await every scope.spawn drain / async call \u2014 a floating rejection crashes the run.\n- Do real work by SPAWNING children; raw un-metered inference in the body is not budget-conserved.\n- Give 'check' a real oracle. A loop whose check is a self-judged score cannot be trusted.\n- The only import allowed is '@tangle-network/agent-runtime/loops'. No require/eval/fetch/process/\n  node builtins \u2014 the runtime meters and gates you; out-of-band compute breaks that.\n";
+interface AuthorLoopOptions {
+    /** The model-call seam (agent-eval `createChatClient`). */
+    chat: ChatClient;
+    model?: string;
+    /** A NAMED fallback author tried once when the primary call fails or returns no code block
+     *  (thinking models can time out at the edge on long authoring prompts, or return empty
+     *  content without `maxTokens`). Opt-in — absent means the primary's failure propagates. */
+    fallbackModel?: string;
+    /** The contract text shown to the author. Default `loopAuthorContract`. A skill/GEPA loop can
+     *  evolve this text and gate each variant on the same check as any loop. */
+    contract?: string;
+    /** What the loop must accomplish — the objective, in plain language (the author's orientation). */
+    goal: string;
+    /** Optional orienting context: the check's shape, the child agents available, prior findings —
+     *  never the check's internals (the author stays blind to the oracle, like `authorStrategy`). */
+    context?: string;
+    /** The round ceiling the loop must respect. */
+    maxRounds: number;
+    /** Where the authored module file is written (created if missing). */
+    outDir: string;
+    temperature?: number;
+    /** Completion cap — required by thinking-model authors that stream reasoning first. */
+    maxTokens?: number;
+    signal?: AbortSignal;
+}
+interface AuthoredLoop {
+    loop: LoopDef;
+    file: string;
+    code: string;
+}
+/**
+ * Author + load a coded loop from a goal. Throws when the author emits no loadable module; with
+ * `fallbackModel` set, the named fallback gets one attempt first. The returned `loop` is handed
+ * to `loopChild(loop, journal)` and spawned as a first-class atom.
+ */
+declare function authorLoop(opts: AuthorLoopOptions): Promise<AuthoredLoop>;
+
 /**
  *
  * `runLoop` — the topology-agnostic kernel built atop the sandbox SDK.
@@ -2120,7 +2301,12 @@ interface SandboxToolPartState {
     /** Sequence for synthesized call ids when an event carries none. */
     seq: number;
 }
-/** @experimental */
+/**
+ * Fresh per-turn {@link SandboxToolPartState} for {@link mapSandboxToolEvent} — an
+ * empty call-status map so each turn projects tool frames independently.
+ *
+ * @experimental
+ */
 declare function createSandboxToolPartState(): SandboxToolPartState;
 /**
  * Project one `SandboxEvent` onto the `tool_call` / `tool_result` variants of
@@ -2236,7 +2422,7 @@ interface SandboxLineage {
      * Acquire a fresh box and begin a new session on it. Returns the handle and
      * the live `streamPrompt` iterable for the first turn (caller drains it).
      */
-    start(spec: AgentRunSpec<unknown>, prompt: string, signal: AbortSignal): Promise<{
+    start(spec: AgentRunSpec<unknown>, prompt: string, signal: AbortSignal, promptOptions?: Omit<PromptOptions, 'signal' | 'sessionId'>): Promise<{
         handle: SandboxLineageHandle;
         events: AsyncIterable<SandboxEvent>;
     }>;
@@ -2247,7 +2433,7 @@ interface SandboxLineage {
      * silently dropped the client-minted session id surfaces as an error instead
      * of a contextless turn the caller mistakes for a real continuation.
      */
-    continue(handle: SandboxLineageHandle, prompt: string, signal: AbortSignal): Promise<AsyncIterable<SandboxEvent>>;
+    continue(handle: SandboxLineageHandle, prompt: string, signal: AbortSignal, promptOptions?: Omit<PromptOptions, 'signal' | 'sessionId'>): Promise<AsyncIterable<SandboxEvent>>;
     /**
      * Branch `count` children from `parent`. When the platform can fork, each
      * child inherits `parent`'s checkpoint — and therefore the parent's IMAGE and
@@ -2414,6 +2600,14 @@ interface SandboxRun<Out> {
     resume(prompt: string): Promise<TurnResult<Out>>;
     close(): Promise<void>;
 }
+/** Prompt options forwarded to every sandbox prompt turn in this run. The
+ * runtime owns `sessionId` and `signal` so callers cannot accidentally break
+ * resume or cancellation semantics while still setting backend-level prompt
+ * controls such as `timeoutMs`.
+ *
+ * @experimental
+ */
+type OpenSandboxRunPromptOptions = Omit<PromptOptions, 'signal' | 'sessionId'>;
 /** @experimental */
 interface OpenSandboxRunOptions {
     /** Profile + sandbox env/overrides. `sandboxOverrides.backend.type` is the harness. */
@@ -2425,6 +2619,9 @@ interface OpenSandboxRunOptions {
     runId?: string;
     /** Optional benchmark/scenario id carried into emitted hook events. */
     scenarioId?: string;
+    /** Per-prompt sandbox SDK options forwarded to both `start()` and `resume()`.
+     *  The runtime still owns the session id and abort signal for each turn. */
+    promptOptions?: OpenSandboxRunPromptOptions;
     /** Test seam for deterministic hook timestamps. Defaults to `Date.now`. */
     now?: () => number;
     /** Bounds box-creation bursts inside lineage fanout. Default from lineage. */
@@ -3693,6 +3890,13 @@ interface InMemoryRunContextOptions {
      * leaf workers. Default `false`.
      */
     readonly withDriver?: boolean;
+    /**
+     * Wrap the executor registry with `withLoopExecutor` so a spawned child marked
+     * `role: 'loop'` resolves to the loop-executor (a coded, budget-conserving, gated,
+     * steerable multi-round loop over a nested `Scope` on the same pool). Composes with
+     * `withDriver` so loops and drivers coexist. Default `false`.
+     */
+    readonly withLoop?: boolean;
 }
 /**
  * The bundle of stores a supervised run needs, shaped to spread into `SupervisorOpts`.
@@ -4068,4 +4272,4 @@ declare function runInWorkspace<T>(ws: Workspace, body: (cwd: string) => Promise
     commitOnInvalid?: boolean;
 }): Promise<WorkspaceRun<T>>;
 
-export { Agent, AgentRunSpec, type AgentTurnBackend, type AgentTurnUsage, type AgenticOptions, type AgenticRunResult, type AgenticSurface, type AgenticTask, type AgenticTool, AnalystRegistry, type AnytimeReport, type AnytimeStrategySummary, type AnytimeTaskCurve, type ApplyContinuation, type ArtifactHandle, AssertTraceDerivedFindings, type AuditIntentInput, type AuditIntentOptions, type AuthorStrategyOptions, type AuthoredProfile, type AuthoredStrategy, type BenchmarkCell, type BenchmarkConfig, type BenchmarkLift, type BenchmarkReport, type BenchmarkStrategySummary, type BenchmarkTaskRow, Budget, type BudgetPool, type BudgetReadout, type ChampionPick, type ChampionPolicy, type CheckpointCapableBox, type CollectedAgentTurn, CombinatorShape, type CompletionAnalyst, type CompletionEvidence, type CompletionPolicy, type CompletionVerdict, CoordinationEvent, type CoordinationMcpHandle, Corpus, CorpusFilter, CorpusRecord, type CreateScopeAnalystOptions, type CriuCapableClient, DefinePersonaInput, type DefinedLeaderboard, type DelegateOptions, type Deliverable, DeliverableSpec, type DriveHarness, Driver, type DriverAgentOptions, type DumbDriverOptions, type Environment, EqualKArm, EqualKOnCostOptions, EqualKVerdict, type EvolutionArchiveNode, type EvolutionAuthor, type EvolutionBandInfo, type EvolutionCandidate, type EvolutionGeneration, type EvolutionReport, ExecCtx, ExecutorConfig, ExecutorFactory, ExecutorRegistry, FanoutOptions, FanoutWinnerSelector, FileCorpus, type ForkCapableBox, type GitWorkspaceOptions, type HarvestCorpusOptions, type HarvestFailure, type HarvestReport, InMemoryCorpus, InMemoryResultBlobStore, type InMemoryRunContext, type InMemoryRunContextOptions, InMemorySpawnJournal, type InProcessOnPrompt, type InProcessPromptCtx, type InProcessSandboxClientOptions, type Inbox, type InboxMessage, type IntentAudit, type Interval, Iteration, type Leaderboard, type LeaderboardBenchScore, type LeaderboardBenchTask, type LeaderboardBenchmarkAdapter, type LeaderboardFlagSpec, type LeaderboardIterationInfo, type LeaderboardOptions, type LeaderboardRow, type LeaderboardRunContext, type LeaderboardScenario, type LeaderboardScore, type LeaderboardSpec, type LoopCampaignDispatchOptions, type LoopDispatchOptions, LoopLineageOptions, type LoopOptionsForDispatch, LoopResult, LoopShape, LoopTokenUsage, LoopUntilSpec, LoopWinner, MakeWorkerAgent, type McpEndpoint, type McpEnvironmentOptions, MountRecorder, type NaiveDriverOptions, type Observation, type ObserveInput, type ObserveOptions, type OpenSandboxRunOptions, Outcome, OutputAdapter, type PairwiseOptions, type PairwiseVerdict, PanelSpec, Persona, PipelineStage, type ProfileRichness, type ProfileRichnessThresholds, type PromotionGateOptions, type PromotionVerdict, type RegistryAnalyzeProjection, RenderCorpusToInstructionsOptions, type ReservationTicket, type ResolveSandboxClientOptions, ResultBlobStore, RouterConfig, type RunAgenticOptions, RunPersonifiedOptions, type SandboxCapabilities, SandboxClient, type SandboxLineage, type SandboxLineageHandle, type SandboxRun, SandboxRunAbortError, type SandboxToolPartState, Scope, ScopeAnalyst, ScopeAnalyzeInput, ScopeWidenGate, type SessionCapableBox, type SessionTraceBox, Settled, ShapeRegistry, type Shell, type ShotPersona, type ShotSpec, Spend, SteerContext, type SteeringDecision, type Strategy, type StrategyCtx, type StrategyEvolutionConfig, type StrategyResult, type StreamAgentTurnOptions, type SuperviseOptions, type SuperviseSurfaceOptions, type SuperviseSurfaceResult, SupervisedResult, Supervisor, type SupervisorAgentDeps, type SupervisorProfile, type SurfaceScore, type SurfaceWorkerConfig, type SurfaceWorkerOut, ToolLoopChat, ToolLoopCompactionOptions, type TraceSource, type TrajectoryAnalysis, TrajectoryReport, TrajectoryReportOptions, type TurnResult, UsageEvent, type UsageSink, Validator, type VerifierEnvironmentOptions, VerifySpec, type WatchTraceOptions, type WaterfallCollector, type WaterfallReport, type WaterfallSpan, WidenSpec, WinnerStrategy, type Workspace, type WorkspaceCommit, type WorkspaceRun, acquireSandbox, adaptiveRefine, analyzeTrace, anytimeReport, asAuthoredProfile, assertModelAllowed, assertStrategyContract, assertTraceDerivedFindings, assessAuthoredProfile, auditIntent, authorStrategy, authoredWorker, breadthStrategy, buildSteerContext, builtinShapes, collectAgentTurn, completionAuthorizes, contentAddress, createBudgetPool, createInMemoryRunContext, createInbox, createMcpEnvironment, createPushTraceSource, createSandboxLineage, createSandboxToolPartState, createScope, createScopeAnalyst, createShapeRegistry, createSupervisor, createVerifierEnvironment, createWaterfallCollector, decodeToolPart, defaultAnalystInstruction, defaultAuditorInstruction, defaultDelegateBudget, defaultProfileRichnessThresholds, defaultSelectWinner, defaultToolDetectors, defineLeaderboard, definePersona, defineStrategy, delegate, depthStrategy, deterministicCompletion, discriminatingMeans, driverAgent, dumbDriver, equalKOnCost, extractLlmCallEvent, failuresAnalyst, fanout, finalizeBestDelivered, flatWidenGate, gitWorkspace, harvestCorpus, inProcessSandboxClient, inlineSandboxClient, jjWorkspace, leaderboard, localShell, loopCampaignDispatch, loopDispatch, loopUntil, mapSandboxEvent, mapSandboxToolEvent, naiveDriver, observe, openSandboxRun, pairwiseSignificance, panel, pickChampion, pipeline, printBenchmarkReport, probeSandboxCapabilities, profileRichnessFinding, promotionGate, refine, registerShape, registryScopeAnalyst, renderAnytimeTable, renderCorpusToInstructions, renderLeaderboardHtml, renderLeaderboardMarkdown, renderLeaderboardSvg, renderPairwiseMarkdown, renderReport, reportLoopUsage, resolveSandboxClient, runAgentic, runBenchmark, runInWorkspace, runLoop, runPersonified, runStrategyEvolution, sample, sampleThenRefine, sandboxSessionTraceSource, selectChampion, selectValidWinner, sentinelCompletion, serveCoordinationMcp, settledToIteration, spendFromUsageEvents, stopSentinel, strategyAuthorContract, streamAgentTurn, sumSandboxUsage, supervise, superviseSurface, supervisorAgent, supervisorInstructions, trajectoryReport, verify, watchTrace, widen, workerFromBackend };
+export { Agent, AgentRunSpec, type AgentTurnBackend, type AgentTurnUsage, type AgenticOptions, type AgenticRunResult, type AgenticSurface, type AgenticTask, type AgenticTool, AnalystRegistry, type AnytimeReport, type AnytimeStrategySummary, type AnytimeTaskCurve, type ApplyContinuation, type ArtifactHandle, AssertTraceDerivedFindings, type AuditIntentInput, type AuditIntentOptions, type AuthorLoopOptions, type AuthorStrategyOptions, type AuthoredLoop, type AuthoredProfile, type AuthoredStrategy, type BenchmarkCell, type BenchmarkConfig, type BenchmarkLift, type BenchmarkReport, type BenchmarkStrategySummary, type BenchmarkTaskRow, Budget, type BudgetPool, type BudgetReadout, type ChampionPick, type ChampionPolicy, type CheckpointCapableBox, type CollectedAgentTurn, CombinatorShape, type CompletionAnalyst, type CompletionEvidence, type CompletionPolicy, type CompletionVerdict, CoordinationEvent, type CoordinationMcpHandle, Corpus, CorpusFilter, CorpusRecord, type CreateScopeAnalystOptions, type CriuCapableClient, DefinePersonaInput, type DefinedLeaderboard, type DelegateOptions, type Deliverable, DeliverableSpec, type DriveHarness, Driver, type DriverAgentOptions, type DumbDriverOptions, type Environment, EqualKArm, EqualKOnCostOptions, EqualKVerdict, type EvolutionArchiveNode, type EvolutionAuthor, type EvolutionBandInfo, type EvolutionCandidate, type EvolutionGeneration, type EvolutionReport, ExecCtx, ExecutorConfig, ExecutorFactory, ExecutorRegistry, FanoutOptions, FanoutWinnerSelector, FileCorpus, type ForkCapableBox, type GitWorkspaceOptions, type HarvestCorpusOptions, type HarvestFailure, type HarvestReport, InMemoryCorpus, InMemoryResultBlobStore, type InMemoryRunContext, type InMemoryRunContextOptions, InMemorySpawnJournal, type InProcessOnPrompt, type InProcessPromptCtx, type InProcessSandboxClientOptions, type Inbox, type InboxMessage, type IntentAudit, type Interval, Iteration, type Leaderboard, type LeaderboardBenchScore, type LeaderboardBenchTask, type LeaderboardBenchmarkAdapter, type LeaderboardFlagSpec, type LeaderboardIterationInfo, type LeaderboardOptions, type LeaderboardRow, type LeaderboardRunContext, type LeaderboardScenario, type LeaderboardScore, type LeaderboardSpec, type LoopAgent, type LoopCampaignDispatchOptions, type LoopDef, type LoopDispatchOptions, LoopLineageOptions, type LoopOptionsForDispatch, LoopResult, type LoopRoundCtx, type LoopRoundResult, LoopShape, LoopTokenUsage, LoopUntilSpec, LoopWinner, MakeWorkerAgent, type McpEndpoint, type McpEnvironmentOptions, MountRecorder, type NaiveDriverOptions, type Observation, type ObserveInput, type ObserveOptions, type OpenSandboxRunOptions, type OpenSandboxRunPromptOptions, Outcome, OutputAdapter, type PairwiseOptions, type PairwiseVerdict, PanelSpec, Persona, PipelineStage, type ProfileRichness, type ProfileRichnessThresholds, type PromotionGateOptions, type PromotionVerdict, type RegistryAnalyzeProjection, RenderCorpusToInstructionsOptions, type ReservationTicket, type ResolveSandboxClientOptions, ResultBlobStore, RouterConfig, type RunAgenticOptions, RunPersonifiedOptions, type SandboxCapabilities, SandboxClient, type SandboxLineage, type SandboxLineageHandle, type SandboxRun, SandboxRunAbortError, type SandboxToolPartState, Scope, ScopeAnalyst, ScopeAnalyzeInput, ScopeWidenGate, type SessionCapableBox, type SessionTraceBox, Settled, ShapeRegistry, type Shell, type ShotPersona, type ShotSpec, Spend, SteerContext, type SteeringDecision, type Strategy, type StrategyCtx, type StrategyEvolutionConfig, type StrategyResult, type StreamAgentTurnOptions, type SuperviseOptions, type SuperviseSurfaceOptions, type SuperviseSurfaceResult, SupervisedResult, Supervisor, type SupervisorAgentDeps, type SupervisorProfile, type SurfaceScore, type SurfaceWorkerConfig, type SurfaceWorkerOut, ToolLoopChat, ToolLoopCompactionOptions, type TraceSource, type TrajectoryAnalysis, TrajectoryReport, TrajectoryReportOptions, type TurnResult, UsageEvent, type UsageSink, Validator, type VerifierEnvironmentOptions, VerifySpec, type WatchTraceOptions, type WaterfallCollector, type WaterfallReport, type WaterfallSpan, WidenSpec, WinnerStrategy, type Workspace, type WorkspaceCommit, type WorkspaceRun, acquireSandbox, adaptiveRefine, analyzeTrace, anytimeReport, asAuthoredProfile, assertModelAllowed, assertStrategyContract, assertTraceDerivedFindings, assessAuthoredProfile, auditIntent, authorLoop, authorStrategy, authoredWorker, breadthStrategy, buildSteerContext, builtinShapes, collectAgentTurn, completionAuthorizes, contentAddress, createBudgetPool, createInMemoryRunContext, createInbox, createMcpEnvironment, createPushTraceSource, createSandboxLineage, createSandboxToolPartState, createScope, createScopeAnalyst, createShapeRegistry, createSupervisor, createVerifierEnvironment, createWaterfallCollector, decodeToolPart, defaultAnalystInstruction, defaultAuditorInstruction, defaultDelegateBudget, defaultProfileRichnessThresholds, defaultSelectWinner, defaultToolDetectors, defineLeaderboard, defineLoop, definePersona, defineStrategy, delegate, depthStrategy, deterministicCompletion, discriminatingMeans, driverAgent, dumbDriver, equalKOnCost, extractLlmCallEvent, failuresAnalyst, fanout, finalizeBestDelivered, flatWidenGate, gitWorkspace, harvestCorpus, inProcessSandboxClient, inlineSandboxClient, jjWorkspace, leaderboard, localShell, loopAuthorContract, loopCampaignDispatch, loopChild, loopDispatch, loopRuntime, loopUntil, mapSandboxEvent, mapSandboxToolEvent, naiveDriver, observe, openSandboxRun, pairwiseSignificance, panel, pickChampion, pipeline, printBenchmarkReport, probeSandboxCapabilities, profileRichnessFinding, promotionGate, refine, registerShape, registryScopeAnalyst, renderAnytimeTable, renderCorpusToInstructions, renderLeaderboardHtml, renderLeaderboardMarkdown, renderLeaderboardSvg, renderPairwiseMarkdown, renderReport, reportLoopUsage, resolveSandboxClient, runAgentic, runBenchmark, runInWorkspace, runLoop, runPersonified, runStrategyEvolution, sample, sampleThenRefine, sandboxSessionTraceSource, selectChampion, selectValidWinner, sentinelCompletion, serveCoordinationMcp, settledToIteration, spendFromUsageEvents, stopSentinel, strategyAuthorContract, streamAgentTurn, sumSandboxUsage, supervise, superviseSurface, supervisorAgent, supervisorInstructions, trajectoryReport, verify, watchTrace, widen, withLoopExecutor, workerFromBackend };

package/dist/loops.js

@@ -8,6 +8,7 @@ import {
   assertStrategyContract,
   assertTraceDerivedFindings,
   auditIntent,
+  authorLoop,
   authorStrategy,
   breadthStrategy,
   buildSteerContext,
@@ -43,6 +44,7 @@ import {
   jjWorkspace,
   leaderboard,
   localShell,
+  loopAuthorContract,
   loopCampaignDispatch,
   loopDispatch,
   loopUntil,
@@ -89,7 +91,7 @@ import {
   watchTrace,
   widen,
   worktreeFanout
-} from "./chunk-VKVNDNG4.js";
+} from "./chunk-22HPUH77.js";
 import {
   InMemoryResultBlobStore,
   InMemorySpawnJournal,
@@ -113,10 +115,13 @@ import {
   defaultDelegateBudget,
   defaultProfileRichnessThresholds,
   defaultSelectWinner,
+  defineLoop,
   delegate,
   driverAgent,
   finalizeBestDelivered,
   gateOnDeliverable,
+  loopChild,
+  loopRuntime,
   probeSandboxCapabilities,
   profileRichnessFinding,
   routerBrain,
@@ -130,8 +135,9 @@ import {
   supervise,
   supervisorAgent,
   supervisorInstructions,
+  withLoopExecutor,
   workerFromBackend
-} from "./chunk-6XCW3M7W.js";
+} from "./chunk-LRNRPJAV.js";
 import "./chunk-UD4BHQMI.js";
 import {
   createAgentEnvironmentProviderRegistry,
@@ -146,7 +152,7 @@ import {
   mapSandboxEvent,
   mapSandboxToolEvent,
   sumSandboxUsage
-} from "./chunk-QUXZBZCS.js";
+} from "./chunk-FVJ7M3DA.js";
 import "./chunk-7LO5GMAO.js";
 import "./chunk-YEJR7IXO.js";
 import "./chunk-DPEUKJRO.js";
@@ -167,6 +173,7 @@ export {
   assertTraceDerivedFindings,
   assessAuthoredProfile,
   auditIntent,
+  authorLoop,
   authorStrategy,
   authoredWorker,
   breadthStrategy,
@@ -203,6 +210,7 @@ export {
   defaultSelectWinner,
   defaultToolDetectors,
   defineLeaderboard,
+  defineLoop,
   definePersona,
   defineStrategy,
   delegate,
@@ -225,8 +233,11 @@ export {
   jjWorkspace,
   leaderboard,
   localShell,
+  loopAuthorContract,
   loopCampaignDispatch,
+  loopChild,
   loopDispatch,
+  loopRuntime,
   loopUntil,
   makeFinding,
   mapSandboxEvent,
@@ -290,6 +301,7 @@ export {
   verify,
   watchTrace,
   widen,
+  withLoopExecutor,
   workerFromBackend,
   worktreeFanout
 };

package/dist/mcp/bin.js

@@ -9,10 +9,10 @@ import {
   DelegationTaskQueue,
   FileDelegationStore,
   createMcpServer
-} from "../chunk-6XCW3M7W.js";
+} from "../chunk-LRNRPJAV.js";
 import "../chunk-UD4BHQMI.js";
 import "../chunk-BZF3KQ6G.js";
-import "../chunk-QUXZBZCS.js";
+import "../chunk-FVJ7M3DA.js";
 import "../chunk-7LO5GMAO.js";
 import "../chunk-YEJR7IXO.js";
 import "../chunk-DPEUKJRO.js";

package/dist/mcp/index.js

@@ -6,7 +6,7 @@ import {
 import {
   mcpToolsForRuntimeMcp,
   mcpToolsForRuntimeMcpSubset
-} from "../chunk-MHYF2LIP.js";
+} from "../chunk-JHULWWQD.js";
 import {
   createKbGate
 } from "../chunk-SGKPNBXE.js";
@@ -14,7 +14,7 @@ import {
   assertTraceDerivedFindings,
   runCoderChecks,
   selectValidWinner
-} from "../chunk-VKVNDNG4.js";
+} from "../chunk-22HPUH77.js";
 import {
   DELEGATE_DESCRIPTION,
   DELEGATE_FEEDBACK_DESCRIPTION,
@@ -64,7 +64,7 @@ import {
   validateDelegateUiAuditArgs,
   validateDelegationHistoryArgs,
   validateDelegationStatusArgs
-} from "../chunk-6XCW3M7W.js";
+} from "../chunk-LRNRPJAV.js";
 import "../chunk-UD4BHQMI.js";
 import {
   deleteBoxSafe,
@@ -72,7 +72,7 @@ import {
   throwAbort,
   throwIfAborted
 } from "../chunk-BZF3KQ6G.js";
-import "../chunk-QUXZBZCS.js";
+import "../chunk-FVJ7M3DA.js";
 import {
   runLocalHarness
 } from "../chunk-7LO5GMAO.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-runtime",
-  "version": "0.87.0",
+  "version": "0.88.0",
   "description": "Shared task-lifecycle skeleton for agents: a recursive loop kernel for chat turns, one-shot tasks, and multi-attempt loops, with trace capture and eval-gated self-improvement. Domain behavior lives in adapters; scoring and ship-gates in @tangle-network/agent-eval.",
   "homepage": "https://github.com/tangle-network/agent-runtime#readme",
   "repository": {
@@ -94,7 +94,7 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.15",
-    "@tangle-network/agent-eval": "^0.103.1",
+    "@tangle-network/agent-eval": "^0.103.2",
     "@tangle-network/agent-interface": ">=0.14.0 <1.0.0",
     "@tangle-network/sandbox": ">=0.8.0 <1.0.0",
     "@types/node": "^25.9.3",

package/skills/build-with-agent-runtime/SKILL.md

@@ -78,6 +78,8 @@ to its native default (`HARNESS_NATIVE_MODEL`) — never silently dropped.
 | **Produce-then-gate / multi-judge quorum / fixed chain** | `verify` / `panel` / `pipeline` — `/loops` | canonical-api §3.1 |
 | **Run depth-vs-breadth (or a custom strategy) over a stateful tool domain** | `runAgentic({ surface, task, mode\|strategy, budget })` — `/loops` | canonical-api §3.3 |
 | **Author a new topology/strategy compactly** | `defineStrategy(name, body)` w/ `ctx.shot()`+`ctx.critique()` — `/loops` | canonical-api §3.3 |
+| **Spawn a coded loop as a first-class atom** (bounded/gated/steerable, spawned + steered like a worker — the 3rd shape beside leaf worker + driver child) | `defineLoop(name, { maxRounds, round | agents, check })` + `loopChild`, wired via `createInMemoryRunContext({ withLoop: true })` — `/loops` — multi-agent = `agents: [proposer, verifier]` (declarative chain, not a bespoke `runTwoAgent…` fn); NOT a hand-driver looping in the model's head; the loop-executor owns maxRounds + conserved budget + gate + steer-between-rounds | canonical-api decision table |
+| **Have an LLM AUTHOR a loop at runtime** (codemode: the supervisor writes a `defineLoop` module for a novel goal) | `authorLoop({ chat, goal, maxRounds, outDir })` → a `LoopDef` for `loopChild` — `/loops` — NOT a per-product loop-code generator or a VM around authored code; the sibling of `authorStrategy`, safety is the conserved pool + gate + `assertStrategyContract` lint | `src/runtime/loop-author.ts` |
 | **Add a stateful tool-using domain** | implement `AgenticSurface` (5 hooks) — `/loops` | canonical-api §3.3 |
 | **Drive a team of agents over a graded `AgenticSurface` task** (workers settle on its check, driver self-improves from the failing tests) | `superviseSurface(profile, task, { surface, worker })` — `/loops` | canonical-api §2 |
 | **Benchmark: compare strategies + significance + Pareto on a domain** | `runBenchmark({ environment, tasks, worker, strategies })` — `/loops` | canonical-api §3.3 |
@@ -148,6 +150,10 @@ holds the load-bearing invariant the parallel breaks:
 - a per-provider stream→event mapper for a single agent turn **≈**
   `streamAgentTurn` + `collectAgentTurn` (0.85+; one `RuntimeStreamEvent`
   contract over box / executor / chat, guaranteed terminal result+usage).
+- a supervisor `act` with a `for (round…)` loop that spawns + checks + continues
+  in the model's reasoning **≈** `defineLoop` + `loopChild` (the loop-executor
+  enforces the round ceiling, the conserved pool, the completion gate, and
+  steer-between-rounds; a hand-driver loop enforces none of them).
 
 ## End-to-end recipe