@tangle-network/agent-runtime 0.86.0 → 0.88.0

package/dist/{chunk-4J6RBI3K.js → chunk-FVJ7M3DA.js}

@@ -66,6 +66,83 @@ function pickFiniteNumber(data, keys) {
   }
   return void 0;
 }
+function createSandboxToolPartState() {
+  return { statusByCall: /* @__PURE__ */ new Map(), seq: 0 };
+}
+var TERMINAL_TOOL_FAILURE = /^(error|errored|failed|failure|cancelled|canceled|timeout|timed_out)$/i;
+function mapSandboxToolEvent(event, state) {
+  if (!event || typeof event !== "object") return [];
+  const type = String(event.type ?? "");
+  const data = event.data && typeof event.data === "object" ? event.data : {};
+  if (type === "message.part.updated") {
+    const part = data.part && typeof data.part === "object" ? data.part : {};
+    if (String(part.type ?? "") !== "tool") return [];
+    return projectToolPart(part, state, typeof event.id === "string" ? event.id : void 0);
+  }
+  if (type.includes("tool")) {
+    const callId = pickString(data, ["toolCallId", "tool_use_id", "id"]) ?? (typeof event.id === "string" ? event.id : void 0) ?? `sandbox-tool-${++state.seq}`;
+    const toolName = pickString(data, ["name", "toolName", "tool"]) ?? "sandbox_tool";
+    if (type.includes("result")) {
+      return [
+        {
+          type: "tool_result",
+          toolName,
+          toolCallId: callId,
+          result: data.output ?? data.result ?? data.content ?? data
+        }
+      ];
+    }
+    return [
+      { type: "tool_call", toolName, toolCallId: callId, args: data.input ?? data.args ?? {} }
+    ];
+  }
+  return [];
+}
+function projectToolPart(part, state, eventId) {
+  const callId = pickString(part, ["callID", "callId", "toolCallId", "id"]) ?? eventId ?? `sandbox-tool-${++state.seq}`;
+  const toolName = pickString(part, ["tool", "toolName", "name"]) ?? "sandbox_tool";
+  const toolState = part.state && typeof part.state === "object" ? part.state : {};
+  const metadata = toolState.metadata && typeof toolState.metadata === "object" ? toolState.metadata : {};
+  const status = pickString(toolState, ["status"]) ?? "updated";
+  const previous = state.statusByCall.get(callId);
+  const settled = previous === "completed" || previous !== void 0 && TERMINAL_TOOL_FAILURE.test(previous);
+  if (settled) return [];
+  const out = [];
+  if (previous === void 0) {
+    out.push({
+      type: "tool_call",
+      toolName,
+      toolCallId: callId,
+      args: toolState.input ?? metadata.input ?? {}
+    });
+  }
+  state.statusByCall.set(callId, status);
+  if (status === "completed") {
+    out.push({
+      type: "tool_result",
+      toolName,
+      toolCallId: callId,
+      result: toolState.output ?? metadata.output ?? ""
+    });
+  } else if (TERMINAL_TOOL_FAILURE.test(status)) {
+    const message = pickString(toolState, ["error", "message"]) ?? pickString(metadata, ["error", "message"]) ?? `sandbox tool ended with status ${status}`;
+    const output = toolState.output ?? metadata.output;
+    out.push({
+      type: "tool_result",
+      toolName,
+      toolCallId: callId,
+      result: { error: message, status, ...output !== void 0 ? { output } : {} }
+    });
+  }
+  return out;
+}
+function pickString(data, keys) {
+  for (const key of keys) {
+    const value = data[key];
+    if (typeof value === "string" && value.length > 0) return value;
+  }
+  return void 0;
+}
 function mapSandboxEvent(event, opts = {}) {
   if (!event || typeof event !== "object") return void 0;
   const type = String(event.type ?? "");
@@ -87,6 +164,8 @@ function mapSandboxEvent(event, opts = {}) {
 export {
   extractLlmCallEvent,
   sumSandboxUsage,
+  createSandboxToolPartState,
+  mapSandboxToolEvent,
   mapSandboxEvent
 };
-//# sourceMappingURL=chunk-4J6RBI3K.js.map
+//# sourceMappingURL=chunk-FVJ7M3DA.js.map

package/dist/chunk-FVJ7M3DA.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/runtime/sandbox-events.ts"],"sourcesContent":["/**\n * Sandbox-event → runtime-event mapping.\n *\n * The sandbox SDK emits a polymorphic `SandboxEvent = { type, data, id? }`\n * whose `type` vocabulary is backend-determined (opencode, etc.) rather than\n * enumerated by the SDK. Two consumers project it:\n *   - the loop kernel's cost ledger (`extractLlmCallEvent`) — sums usage off\n *     every cost-bearing event, regardless of stream shape;\n *   - the `AgentRuntime.act` streaming contract (`mapSandboxEvent`) — projects\n *     incremental events to the `RuntimeStreamEvent` chat-UX vocabulary.\n *\n * Both live here so the empirically-observed `type` vocabulary has one home.\n */\n\nimport type { SandboxEvent } from '@tangle-network/sandbox'\nimport type { RuntimeStreamEvent } from '../types'\n\n/**\n * Extract a `RuntimeStreamEvent`-shaped `llm_call` from a sandbox event when\n * the event carries usage/cost data. Returns `undefined` for non-cost events\n * so the kernel can iterate the full stream without branching.\n *\n * Canonical cost-carrying types observed in the wild:\n *   - `llm_call` — `data: { model, tokensIn, tokensOut, costUsd, ... }`\n *   - `message.completed` / `result` — `data: { usage: { inputTokens,\n *      outputTokens, totalCostUsd? } }`\n *   - `cost.usage` / `usage` — same shape under a dedicated type\n *\n * Numeric coercion is strict: `Number.isFinite` gates every accumulator write\n * so a sentinel `NaN` from a misbehaving backend cannot poison the ledger.\n */\nexport function extractLlmCallEvent(\n  event: SandboxEvent,\n  agentRunName: string,\n): (RuntimeStreamEvent & { type: 'llm_call' }) | undefined {\n  if (!event || typeof event !== 'object') return undefined\n  const type = String(event.type ?? '')\n  const data =\n    event.data && typeof event.data === 'object'\n      ? (event.data as Record<string, unknown>)\n      : ({} as Record<string, unknown>)\n\n  if (type === 'llm_call' || type === 'cost.usage' || type === 'usage') {\n    return buildLlmCall(data, agentRunName)\n  }\n  if (type === 'message.completed' || type === 'result' || type === 'final') {\n    const usage = data.usage as Record<string, unknown> | undefined\n    if (!usage || typeof usage !== 'object') return undefined\n    return buildLlmCall({ ...usage, model: data.model ?? usage.model }, agentRunName)\n  }\n  // sandbox 0.4.0 terminal event: `data = { tokenUsage: { inputTokens, outputTokens,\n  // reasoningTokens, cacheReadInputTokens }, totalCostUsd }`. Usage lives under\n  // `tokenUsage` (not `usage`) and the cost is top-level — neither matched the\n  // branches above, so an in-process loopDispatch run reported {0,0} and the\n  // backend-integrity guard misread a real run as a stub. Reasoning tokens are\n  // billed output (reasoning models), so they fold into the output count.\n  if (type === 'done') {\n    const usage = data.tokenUsage as Record<string, unknown> | undefined\n    if (!usage || typeof usage !== 'object') return undefined\n    const out = pickFiniteNumber(usage, ['outputTokens', 'completion_tokens', 'tokensOut'])\n    const reasoning = pickFiniteNumber(usage, ['reasoningTokens'])\n    const mergedOut =\n      out !== undefined || reasoning !== undefined ? (out ?? 0) + (reasoning ?? 0) : undefined\n    return buildLlmCall(\n      {\n        inputTokens: usage.inputTokens,\n        outputTokens: mergedOut,\n        totalCostUsd: data.totalCostUsd,\n        model: data.model ?? usage.model,\n      },\n      agentRunName,\n    )\n  }\n  return undefined\n}\n\n/**\n * Sum the token usage + USD cost of a sandbox turn's events — the one honest way to meter an\n * `openSandboxRun` cell. Folds `extractLlmCallEvent` over the stream (which reads usage off EVERY backend\n * event shape), so a `runProfileMatrix` dispatch can report it to `ctx.cost`:\n *\n *     const turn = await run.start(prompt)\n *     const u = sumSandboxUsage(turn.events)\n *     if (u.input || u.output) ctx.cost.observeTokens({ input: u.input, output: u.output })\n *     if (u.costUsd) ctx.cost.observe(u.costUsd, 'sandbox-cell')\n *\n * Without this a cell reads `{tokens:0, cost:0}` and the backend-integrity guard correctly aborts the\n * matrix as a stub. `agentRunName` is the fallback model label for cost-only events (default `'agent'`).\n */\nexport function sumSandboxUsage(\n  events: readonly SandboxEvent[],\n  agentRunName = 'agent',\n): { input: number; output: number; costUsd: number } {\n  let input = 0\n  let output = 0\n  let costUsd = 0\n  for (const ev of events) {\n    const call = extractLlmCallEvent(ev, agentRunName)\n    if (!call) continue\n    input += call.tokensIn ?? 0\n    output += call.tokensOut ?? 0\n    costUsd += call.costUsd ?? 0\n  }\n  return { input, output, costUsd }\n}\n\nfunction buildLlmCall(\n  data: Record<string, unknown>,\n  agentRunName: string,\n): (RuntimeStreamEvent & { type: 'llm_call' }) | undefined {\n  const tokensIn = pickFiniteNumber(data, ['tokensIn', 'inputTokens', 'prompt_tokens'])\n  const tokensOut = pickFiniteNumber(data, ['tokensOut', 'outputTokens', 'completion_tokens'])\n  const costUsd = pickFiniteNumber(data, ['costUsd', 'totalCostUsd', 'cost_usd', 'cost'])\n  if (tokensIn === undefined && tokensOut === undefined && costUsd === undefined) {\n    return undefined\n  }\n  const model = typeof data.model === 'string' && data.model.length > 0 ? data.model : agentRunName\n  const event: RuntimeStreamEvent & { type: 'llm_call' } = {\n    type: 'llm_call',\n    model,\n  }\n  if (tokensIn !== undefined) event.tokensIn = tokensIn\n  if (tokensOut !== undefined) event.tokensOut = tokensOut\n  if (costUsd !== undefined) event.costUsd = costUsd\n  return event\n}\n\nfunction pickFiniteNumber(data: Record<string, unknown>, keys: string[]): number | undefined {\n  for (const key of keys) {\n    const value = data[key]\n    if (typeof value === 'number' && Number.isFinite(value)) return value\n  }\n  return undefined\n}\n\n/**\n * Cross-event state for {@link mapSandboxToolEvent}. Sandbox backends emit a\n * tool invocation as MANY `message.part.updated` frames on the same call id\n * (pending → running → completed), so faithful projection needs per-call\n * status memory: one `tool_call` on first sighting, at most one `tool_result`\n * on the terminal transition, nothing on intermediate re-frames. Create one\n * state per turn via {@link createSandboxToolPartState}.\n *\n * @experimental\n */\nexport interface SandboxToolPartState {\n  /** Last seen status per tool call id. A terminal status is sticky — later\n   *  frames on a settled call project to nothing. */\n  statusByCall: Map<string, string>\n  /** Sequence for synthesized call ids when an event carries none. */\n  seq: number\n}\n\n/**\n * Fresh per-turn {@link SandboxToolPartState} for {@link mapSandboxToolEvent} — an\n * empty call-status map so each turn projects tool frames independently.\n *\n * @experimental\n */\nexport function createSandboxToolPartState(): SandboxToolPartState {\n  return { statusByCall: new Map(), seq: 0 }\n}\n\n/** Terminal tool statuses that are failures (everything here settles the call). */\nconst TERMINAL_TOOL_FAILURE =\n  /^(error|errored|failed|failure|cancelled|canceled|timeout|timed_out)$/i\n\n/**\n * Project one `SandboxEvent` onto the `tool_call` / `tool_result` variants of\n * `RuntimeStreamEvent` — the tool-part projection `mapSandboxEvent`\n * deliberately does NOT perform. Opt-in and additive: `mapSandboxEvent`'s\n * default vocabulary (text/reasoning deltas + `llm_call`) is unchanged;\n * consumers that need the tool surface (chat UIs rendering tool activity)\n * compose this projector alongside it — `streamAgentTurn` does exactly that\n * under its `preserveToolParts` option.\n *\n * Handled shapes (observed on the opencode / claude-code sandbox backends):\n *   - `message.part.updated` with `part.type === 'tool'` — stateful: a\n *     `tool_call` on the call id's first frame (args from `state.input` or\n *     `state.metadata.input`), a `tool_result` when the status transitions to\n *     `completed` (result from `state.output` / `metadata.output`) or to a\n *     terminal failure (result is `{ error, status, output? }` — the error\n *     surfaced in-band, never dropped).\n *   - bare `tool*` event types (`tool.call`, `tool_result`, …) — stateless:\n *     `*result*` types project to `tool_result`, the rest to `tool_call`.\n *\n * Returns `[]` for every non-tool event.\n *\n * @experimental\n */\nexport function mapSandboxToolEvent(\n  event: SandboxEvent,\n  state: SandboxToolPartState,\n): (RuntimeStreamEvent & { type: 'tool_call' | 'tool_result' })[] {\n  if (!event || typeof event !== 'object') return []\n  const type = String(event.type ?? '')\n  const data =\n    event.data && typeof event.data === 'object'\n      ? (event.data as Record<string, unknown>)\n      : ({} as Record<string, unknown>)\n\n  if (type === 'message.part.updated') {\n    const part =\n      data.part && typeof data.part === 'object' ? (data.part as Record<string, unknown>) : {}\n    if (String(part.type ?? '') !== 'tool') return []\n    return projectToolPart(part, state, typeof event.id === 'string' ? event.id : undefined)\n  }\n\n  if (type.includes('tool')) {\n    const callId =\n      pickString(data, ['toolCallId', 'tool_use_id', 'id']) ??\n      (typeof event.id === 'string' ? event.id : undefined) ??\n      `sandbox-tool-${++state.seq}`\n    const toolName = pickString(data, ['name', 'toolName', 'tool']) ?? 'sandbox_tool'\n    if (type.includes('result')) {\n      return [\n        {\n          type: 'tool_result',\n          toolName,\n          toolCallId: callId,\n          result: data.output ?? data.result ?? data.content ?? data,\n        },\n      ]\n    }\n    return [\n      { type: 'tool_call', toolName, toolCallId: callId, args: data.input ?? data.args ?? {} },\n    ]\n  }\n\n  return []\n}\n\nfunction projectToolPart(\n  part: Record<string, unknown>,\n  state: SandboxToolPartState,\n  eventId: string | undefined,\n): (RuntimeStreamEvent & { type: 'tool_call' | 'tool_result' })[] {\n  const callId =\n    pickString(part, ['callID', 'callId', 'toolCallId', 'id']) ??\n    eventId ??\n    `sandbox-tool-${++state.seq}`\n  const toolName = pickString(part, ['tool', 'toolName', 'name']) ?? 'sandbox_tool'\n  const toolState =\n    part.state && typeof part.state === 'object' ? (part.state as Record<string, unknown>) : {}\n  const metadata =\n    toolState.metadata && typeof toolState.metadata === 'object'\n      ? (toolState.metadata as Record<string, unknown>)\n      : {}\n  const status = pickString(toolState, ['status']) ?? 'updated'\n\n  const previous = state.statusByCall.get(callId)\n  const settled =\n    previous === 'completed' || (previous !== undefined && TERMINAL_TOOL_FAILURE.test(previous))\n  if (settled) return []\n\n  const out: (RuntimeStreamEvent & { type: 'tool_call' | 'tool_result' })[] = []\n  if (previous === undefined) {\n    out.push({\n      type: 'tool_call',\n      toolName,\n      toolCallId: callId,\n      args: toolState.input ?? metadata.input ?? {},\n    })\n  }\n  state.statusByCall.set(callId, status)\n\n  if (status === 'completed') {\n    out.push({\n      type: 'tool_result',\n      toolName,\n      toolCallId: callId,\n      result: toolState.output ?? metadata.output ?? '',\n    })\n  } else if (TERMINAL_TOOL_FAILURE.test(status)) {\n    const message =\n      pickString(toolState, ['error', 'message']) ??\n      pickString(metadata, ['error', 'message']) ??\n      `sandbox tool ended with status ${status}`\n    const output = toolState.output ?? metadata.output\n    out.push({\n      type: 'tool_result',\n      toolName,\n      toolCallId: callId,\n      result: { error: message, status, ...(output !== undefined ? { output } : {}) },\n    })\n  }\n  return out\n}\n\nfunction pickString(data: Record<string, unknown>, keys: string[]): string | undefined {\n  for (const key of keys) {\n    const value = data[key]\n    if (typeof value === 'string' && value.length > 0) return value\n  }\n  return undefined\n}\n\n/**\n * Project one `SandboxEvent` onto the `RuntimeStreamEvent` chat-UX vocabulary,\n * for runtimes that bridge a sandbox `streamPrompt` into the\n * `AgentRuntime.act` streaming contract. Returns `undefined` for events that\n * have no faithful projection — the raw stream is preserved separately for the\n * `OutputAdapter`, so an unmapped event never loses data.\n *\n * Mapped (the task-optional incremental variants — no synthesized task\n * lifecycle, no guessed tool-part shapes):\n *   - `message.part.updated` text part → `text_delta`\n *   - `message.part.updated` reasoning/thinking part → `reasoning_delta`\n *   - cost-bearing events → `llm_call` (shared with the ledger extractor)\n *\n * Tool parts are deliberately NOT mapped here (unchanged default) — compose\n * {@link mapSandboxToolEvent} alongside when a consumer needs them.\n *\n * The opencode backend emits incremental text as\n * `{ type: 'message.part.updated', data: { part: { type, text }, delta } }`;\n * `delta` is the increment, `part.text` the running accumulation.\n */\nexport function mapSandboxEvent(\n  event: SandboxEvent,\n  opts: { agentRunName?: string } = {},\n): RuntimeStreamEvent | undefined {\n  if (!event || typeof event !== 'object') return undefined\n  const type = String(event.type ?? '')\n  const data =\n    event.data && typeof event.data === 'object'\n      ? (event.data as Record<string, unknown>)\n      : ({} as Record<string, unknown>)\n\n  if (type === 'message.part.updated') {\n    const part =\n      data.part && typeof data.part === 'object' ? (data.part as Record<string, unknown>) : {}\n    const partType = String(part.type ?? '')\n    const delta = typeof data.delta === 'string' ? data.delta : undefined\n    const text = delta ?? (typeof part.text === 'string' ? part.text : undefined)\n    if (text === undefined) return undefined\n    if (partType === 'text') return { type: 'text_delta', text }\n    if (partType === 'reasoning' || partType === 'thinking')\n      return { type: 'reasoning_delta', text }\n    return undefined\n  }\n\n  return extractLlmCallEvent(event, opts.agentRunName ?? 'agent')\n}\n"],"mappings":"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","names":[]}

package/dist/{chunk-EJ7MAQN4.js → chunk-HBE77SWV.js}

@@ -5,13 +5,13 @@ import {
   definePersona,
   runPersonified,
   worktreeFanout
-} from "./chunk-3TZOXS7B.js";
+} from "./chunk-22HPUH77.js";
 import {
   createExecutorRegistry
-} from "./chunk-F7OO2SKB.js";
+} from "./chunk-LRNRPJAV.js";
 import {
   runAnalystLoop
-} from "./chunk-YPA5MLVE.js";
+} from "./chunk-ZQZX77MM.js";
 import {
   ConfigError
 } from "./chunk-YEJR7IXO.js";
@@ -196,4 +196,4 @@ export {
   runLoopRunnerCli,
   parseLoopRunnerArgv
 };
-//# sourceMappingURL=chunk-EJ7MAQN4.js.map
+//# sourceMappingURL=chunk-HBE77SWV.js.map

package/dist/{chunk-U4TS65XZ.js → chunk-JHULWWQD.js}

@@ -8,7 +8,7 @@ import {
   DELEGATION_STATUS_DESCRIPTION,
   DELEGATION_STATUS_INPUT_SCHEMA,
   DELEGATION_STATUS_TOOL_NAME
-} from "./chunk-F7OO2SKB.js";
+} from "./chunk-LRNRPJAV.js";
 
 // src/mcp/openai-tools.ts
 function buildTool(name, description, parameters) {
@@ -45,4 +45,4 @@ export {
   mcpToolsForRuntimeMcp,
   mcpToolsForRuntimeMcpSubset
 };
-//# sourceMappingURL=chunk-U4TS65XZ.js.map
+//# sourceMappingURL=chunk-JHULWWQD.js.map

package/dist/{chunk-F7OO2SKB.js → chunk-LRNRPJAV.js}

@@ -18,7 +18,7 @@ import {
 } from "./chunk-BZF3KQ6G.js";
 import {
   extractLlmCallEvent
-} from "./chunk-4J6RBI3K.js";
+} from "./chunk-FVJ7M3DA.js";
 import {
   harnessInvocation,
   runLocalHarness
@@ -342,9 +342,13 @@ function buildBackendOptions(profile, overrides) {
 // src/runtime/sandbox-lineage.ts
 var TEARDOWN_TIMEOUT_MS = 15e3;
 var DEFAULT_FORK_CONCURRENCY = 4;
-async function* pollPromptEvents(box, prompt, sessionId, signal) {
+async function* pollPromptEvents(box, prompt, sessionId, signal, promptOptions) {
   if (signal.aborted) throwAbort();
-  const dispatched = await box.dispatchPrompt(prompt, { sessionId, signal });
+  const dispatched = await box.dispatchPrompt(prompt, {
+    ...promptOptions ?? {},
+    sessionId,
+    signal
+  });
   const activeSessionId = dispatched.sessionId;
   const result = await box.session(activeSessionId).result();
   if (signal.aborted) throwAbort();
@@ -359,8 +363,8 @@ async function* pollPromptEvents(box, prompt, sessionId, signal) {
     }
   };
 }
-function promptEvents(streaming, box, prompt, sessionId, signal) {
-  return streaming === "poll" ? pollPromptEvents(box, prompt, sessionId, signal) : box.streamPrompt(prompt, { sessionId, signal });
+function promptEvents(streaming, box, prompt, sessionId, signal, promptOptions) {
+  return streaming === "poll" ? pollPromptEvents(box, prompt, sessionId, signal, promptOptions) : box.streamPrompt(prompt, { ...promptOptions ?? {}, sessionId, signal });
 }
 function createSandboxLineage(client, capabilities, options = {}) {
   if (!client || typeof client.create !== "function") {
@@ -383,16 +387,16 @@ function createSandboxLineage(client, capabilities, options = {}) {
     return box;
   };
   return {
-    async start(spec, prompt, signal) {
+    async start(spec, prompt, signal, promptOptions) {
       const box = await acquireFresh(spec, signal);
       const sessionId = mintSessionId();
-      const events = promptEvents(streaming, box, prompt, sessionId, signal);
+      const events = promptEvents(streaming, box, prompt, sessionId, signal, promptOptions);
       return { handle: { box, sessionId }, events };
     },
-    async continue(handle, prompt, signal) {
+    async continue(handle, prompt, signal, promptOptions) {
       if (signal.aborted) throwAbort();
       await assertSessionLive(handle.box, handle.sessionId);
-      return promptEvents(streaming, handle.box, prompt, handle.sessionId, signal);
+      return promptEvents(streaming, handle.box, prompt, handle.sessionId, signal, promptOptions);
     },
     async fork(parent, prompts, specs, signal) {
       if (prompts.length === 0) {
@@ -5255,6 +5259,243 @@ function canonicalize(value) {
   return out;
 }
 
+// src/runtime/supervise/loop-executor.ts
+var loopRuntime = "loop";
+var loopRole = "loop";
+function defineLoop(name, spec) {
+  if (!name) throw new ValidationError("defineLoop: a loop needs a name");
+  if (!Number.isInteger(spec.maxRounds) || spec.maxRounds < 1) {
+    throw new ValidationError(`defineLoop: "${name}" needs an integer maxRounds >= 1`);
+  }
+  const hasRound = typeof spec.round === "function";
+  const hasAgents = Array.isArray(spec.agents) && spec.agents.length > 0;
+  if (hasRound === hasAgents) {
+    throw new ValidationError(
+      `defineLoop: "${name}" needs exactly one of round(ctx) or a non-empty agents[]`
+    );
+  }
+  const round = hasRound ? spec.round : agentPipelineRound(name, spec.agents ?? []);
+  return {
+    name,
+    maxRounds: spec.maxRounds,
+    round,
+    ...spec.check ? { check: spec.check } : {},
+    ...spec.describe ? { describe: spec.describe } : {}
+  };
+}
+function agentPipelineRound(name, agents) {
+  for (const agent of agents) {
+    if (!agent || typeof agent.run !== "function" || !agent.name) {
+      throw new ValidationError(`defineLoop: "${name}" has an agent missing a name or run()`);
+    }
+  }
+  return async (ctx) => {
+    let out = ctx.task;
+    for (const agent of agents) {
+      out = await agent.run(ctx, out);
+    }
+    return { out };
+  };
+}
+function loopChild(loop, journal) {
+  const spec = {
+    profile: { name: loop.name, metadata: { role: loopRole } },
+    harness: null,
+    loop,
+    journal
+  };
+  return {
+    name: loop.name,
+    executorSpec: spec,
+    act() {
+      throw new ValidationError(
+        `loopChild: "${loop.name}" was run directly; a loop child runs through its nested-scope executor`
+      );
+    }
+  };
+}
+function isLoopSpec(spec) {
+  const role = spec.profile.metadata?.role;
+  if (role !== loopRole) return false;
+  const loop = spec.loop;
+  if (!isLoopDef(loop)) {
+    throw new ValidationError(
+      "loopExecutor: a loop-role spec must carry a `loop` LoopDef to run inside its nested scope"
+    );
+  }
+  return true;
+}
+var loopExecutorFactory = (spec, ctx) => {
+  if (!isLoopSpec(spec)) {
+    throw new ValidationError(
+      'loopExecutorFactory: spec is not a loop child (no role:"loop" marker)'
+    );
+  }
+  const loop = spec.loop;
+  const journal = spec.journal;
+  const seam = readNestedScopeSeam(ctx);
+  const inbox = createInbox();
+  let artifact;
+  let meteredSpend;
+  return {
+    runtime: loopRuntime,
+    // The steer seam: `steer_agent` → `Scope.send` → here. Never throws (inbox contract).
+    deliver(msg) {
+      inbox.deliver(msg);
+    },
+    async execute(task, signal) {
+      const nestedRoot = nestedTreeKey(seam, journal);
+      await journal.beginTree(nestedRoot, (/* @__PURE__ */ new Date(0)).toISOString());
+      const nestedScope = seam.mount(nestedRoot, signal);
+      let out;
+      let delivered = false;
+      try {
+        for (let round = 1; round <= loop.maxRounds; round++) {
+          if (signal.aborted || nestedScope.signal.aborted) break;
+          const steer = drainSteer(inbox);
+          const roundInterrupt = inbox.freshInterrupt();
+          const roundSignal = AbortSignal.any([signal, nestedScope.signal, roundInterrupt]);
+          const result = await loop.round({
+            task,
+            scope: nestedScope,
+            round,
+            maxRounds: loop.maxRounds,
+            steer,
+            budget: nestedScope.budget,
+            signal: roundSignal
+          });
+          out = result.out;
+          if (loop.check && await runCheck(loop.check, out)) {
+            delivered = true;
+            break;
+          }
+          if (result.done) break;
+        }
+        const events = await loadTreeEvents(journal, nestedRoot);
+        const settled = events.filter(isSettled);
+        meteredSpend = nonZeroOrUndef(sumMetered(events));
+        const valid = loop.check ? await runCheck(loop.check, out) : delivered;
+        const verdict = { valid, score: valid ? 1 : 0 };
+        artifact = {
+          outRef: `${loopRuntime}:${nestedRoot}`,
+          out,
+          spent: sumSpend(settled),
+          verdict
+        };
+        return artifact;
+      } catch (err) {
+        meteredSpend = await safeSumMetered(journal, nestedRoot);
+        throw err;
+      }
+    },
+    metered() {
+      return meteredSpend;
+    },
+    teardown() {
+      return Promise.resolve({ destroyed: true });
+    },
+    resultArtifact() {
+      if (!artifact)
+        throw new ValidationError("loopExecutor: resultArtifact() read before execute()");
+      return artifact;
+    }
+  };
+};
+function withLoopExecutor(base) {
+  return {
+    register: base.register.bind(base),
+    resolve(spec) {
+      const role = spec.profile.metadata?.role;
+      if (role === loopRole && !spec.executor) {
+        return { succeeded: true, value: loopExecutorFactory };
+      }
+      return base.resolve(spec);
+    }
+  };
+}
+function drainSteer(inbox) {
+  return inbox.drain().map((m) => m.text);
+}
+async function runCheck(check, out) {
+  try {
+    return await check(out) === true;
+  } catch {
+    return false;
+  }
+}
+function nestedTreeKey(seam, journal) {
+  return `${seam.journalRoot}/l${nextNestOrdinal(journal)}`;
+}
+var nestCounters = /* @__PURE__ */ new WeakMap();
+function nextNestOrdinal(journal) {
+  let c = nestCounters.get(journal);
+  if (!c) {
+    c = { n: 0 };
+    nestCounters.set(journal, c);
+  }
+  return c.n++;
+}
+async function loadTreeEvents(journal, nestedRoot) {
+  const events = await journal.loadTree(nestedRoot);
+  if (events === void 0) {
+    throw new ValidationError(
+      `loopExecutor: nested tree '${nestedRoot}' missing from the journal after run (corrupted log)`
+    );
+  }
+  return events;
+}
+function isSettled(ev) {
+  return ev.kind === "settled";
+}
+function sumSpend(settled) {
+  const total = { iterations: 0, tokens: { input: 0, output: 0 }, usd: 0, ms: 0 };
+  for (const ev of settled) {
+    total.iterations += ev.spent.iterations;
+    total.tokens.input += ev.spent.tokens.input;
+    total.tokens.output += ev.spent.tokens.output;
+    total.usd += ev.spent.usd;
+    total.ms += ev.spent.ms;
+  }
+  return total;
+}
+function sumMetered(events) {
+  const total = { iterations: 0, tokens: { input: 0, output: 0 }, usd: 0, ms: 0 };
+  for (const ev of events) {
+    if (ev.kind !== "metered") continue;
+    total.iterations += ev.spend.iterations;
+    total.tokens.input += ev.spend.tokens.input;
+    total.tokens.output += ev.spend.tokens.output;
+    total.usd += ev.spend.usd;
+    total.ms += ev.spend.ms;
+  }
+  return total;
+}
+function isNonZeroSpend(s) {
+  return s.iterations > 0 || s.tokens.input > 0 || s.tokens.output > 0 || s.usd > 0 || s.ms > 0;
+}
+function nonZeroOrUndef(s) {
+  return isNonZeroSpend(s) ? s : void 0;
+}
+async function safeSumMetered(journal, nestedRoot) {
+  try {
+    return nonZeroOrUndef(sumMetered(await loadTreeEvents(journal, nestedRoot)));
+  } catch {
+    return void 0;
+  }
+}
+function readNestedScopeSeam(ctx) {
+  const seam = ctx.seams[nestedScopeSeamKey];
+  if (!seam || typeof seam.mount !== "function") {
+    throw new ValidationError(
+      `loopExecutor: missing required seam "${nestedScopeSeamKey}" \u2014 a loop child must be spawned through a Scope that seeds it (the keystone scope does)`
+    );
+  }
+  return seam;
+}
+function isLoopDef(value) {
+  return typeof value === "object" && value !== null && typeof value.round === "function" && typeof value.name === "string" && Number.isInteger(value.maxRounds);
+}
+
 // src/runtime/supervise/driver-executor.ts
 var driverRuntime = "driver";
 var driverRole = "driver";
@@ -5277,30 +5518,30 @@ var driverExecutorFactory = (spec, ctx) => {
   }
   const driver = spec.driver;
   const journal = spec.journal;
-  const seam = readNestedScopeSeam(ctx);
+  const seam = readNestedScopeSeam2(ctx);
   let artifact;
   let meteredSpend;
   return {
     runtime: driverRuntime,
     async execute(task, signal) {
-      const nestedRoot = nestedTreeKey(seam, journal);
+      const nestedRoot = nestedTreeKey2(seam, journal);
       await journal.beginTree(nestedRoot, (/* @__PURE__ */ new Date(0)).toISOString());
       const nestedScope = seam.mount(nestedRoot, signal);
       try {
         const out = await driver.act(task, nestedScope);
-        const events = await loadTreeEvents(journal, nestedRoot);
-        const settled = events.filter(isSettled);
-        meteredSpend = nonZeroOrUndef(sumMetered(events));
+        const events = await loadTreeEvents2(journal, nestedRoot);
+        const settled = events.filter(isSettled2);
+        meteredSpend = nonZeroOrUndef2(sumMetered2(events));
         const verdict = deriveDeliveryVerdict(settled);
         artifact = {
           outRef: `${driverRuntime}:${nestedRoot}`,
           out,
-          spent: sumSpend(settled),
+          spent: sumSpend2(settled),
           ...verdict ? { verdict } : {}
         };
         return artifact;
       } catch (err) {
-        meteredSpend = await safeSumMetered(journal, nestedRoot);
+        meteredSpend = await safeSumMetered2(journal, nestedRoot);
         throw err;
       }
     },
@@ -5330,19 +5571,19 @@ function withDriverExecutor(base) {
     }
   };
 }
-function nestedTreeKey(seam, journal) {
-  return `${seam.journalRoot}/d${nextNestOrdinal(journal)}`;
+function nestedTreeKey2(seam, journal) {
+  return `${seam.journalRoot}/d${nextNestOrdinal2(journal)}`;
 }
-var nestCounters = /* @__PURE__ */ new WeakMap();
-function nextNestOrdinal(journal) {
-  let c = nestCounters.get(journal);
+var nestCounters2 = /* @__PURE__ */ new WeakMap();
+function nextNestOrdinal2(journal) {
+  let c = nestCounters2.get(journal);
   if (!c) {
     c = { n: 0 };
-    nestCounters.set(journal, c);
+    nestCounters2.set(journal, c);
   }
   return c.n++;
 }
-async function loadTreeEvents(journal, nestedRoot) {
+async function loadTreeEvents2(journal, nestedRoot) {
   const events = await journal.loadTree(nestedRoot);
   if (events === void 0) {
     throw new ValidationError(
@@ -5351,10 +5592,10 @@ async function loadTreeEvents(journal, nestedRoot) {
   }
   return events;
 }
-function isSettled(ev) {
+function isSettled2(ev) {
   return ev.kind === "settled";
 }
-function sumSpend(settled) {
+function sumSpend2(settled) {
   const total = { iterations: 0, tokens: { input: 0, output: 0 }, usd: 0, ms: 0 };
   for (const ev of settled) {
     total.iterations += ev.spent.iterations;
@@ -5365,7 +5606,7 @@ function sumSpend(settled) {
   }
   return total;
 }
-function sumMetered(events) {
+function sumMetered2(events) {
   const total = { iterations: 0, tokens: { input: 0, output: 0 }, usd: 0, ms: 0 };
   for (const ev of events) {
     if (ev.kind !== "metered") continue;
@@ -5377,15 +5618,15 @@ function sumMetered(events) {
   }
   return total;
 }
-function isNonZeroSpend(s) {
+function isNonZeroSpend2(s) {
   return s.iterations > 0 || s.tokens.input > 0 || s.tokens.output > 0 || s.usd > 0 || s.ms > 0;
 }
-function nonZeroOrUndef(s) {
-  return isNonZeroSpend(s) ? s : void 0;
+function nonZeroOrUndef2(s) {
+  return isNonZeroSpend2(s) ? s : void 0;
 }
-async function safeSumMetered(journal, nestedRoot) {
+async function safeSumMetered2(journal, nestedRoot) {
   try {
-    return nonZeroOrUndef(sumMetered(await loadTreeEvents(journal, nestedRoot)));
+    return nonZeroOrUndef2(sumMetered2(await loadTreeEvents2(journal, nestedRoot)));
   } catch {
     return void 0;
   }
@@ -5415,7 +5656,7 @@ function deriveDeliveryVerdict(settled) {
     score: anyValid ? bestValidScore ?? 1 : bestDoneScore ?? 0
   };
 }
-function readNestedScopeSeam(ctx) {
+function readNestedScopeSeam2(ctx) {
   const seam = ctx.seams[nestedScopeSeamKey];
   if (!seam || typeof seam.mount !== "function") {
     throw new ValidationError(
@@ -5431,10 +5672,13 @@ function isAgent(value) {
 // src/runtime/supervise/run-context.ts
 function createInMemoryRunContext(opts = {}) {
   const base = createExecutorRegistry();
+  let executors = base;
+  if (opts.withDriver) executors = withDriverExecutor(executors);
+  if (opts.withLoop) executors = withLoopExecutor(executors);
   return {
     journal: new InMemorySpawnJournal(),
     blobs: new InMemoryResultBlobStore(),
-    executors: opts.withDriver ? withDriverExecutor(base) : base
+    executors
   };
 }
 
@@ -6575,6 +6819,10 @@ export {
   composeLoopTraceEmitters,
   DelegationTaskQueue,
   hashIdempotencyInput,
+  loopRuntime,
+  defineLoop,
+  loopChild,
+  withLoopExecutor,
   createInMemoryRunContext,
   supervisorAgent,
   workerFromBackend,
@@ -6610,4 +6858,4 @@ export {
   createInProcessTransport,
   serveCoordinationMcp
 };
-//# sourceMappingURL=chunk-F7OO2SKB.js.map
+//# sourceMappingURL=chunk-LRNRPJAV.js.map