@tangle-network/agent-runtime 0.32.0 → 0.34.0

package/dist/loops.d.ts

@@ -1,12 +1,116 @@
+import { AgentProfile, SandboxEvent } from '@tangle-network/sandbox';
 export { AgentProfile, CreateSandboxOptions, SandboxEvent, SandboxInstance } from '@tangle-network/sandbox';
-import { D as Driver, I as Iteration, A as AgentRunSpec, O as OutputAdapter, V as Validator, E as ExecCtx, L as LoopWinner, a as LoopResult, b as LoopSandboxClient } from './types-Co507h15.js';
-export { c as LoopDecisionPayload, d as LoopEndedPayload, e as LoopIterationDispatchPayload, f as LoopIterationEndedPayload, g as LoopIterationStartedPayload, h as LoopSandboxPlacement, i as LoopStartedPayload, j as LoopTokenUsage, k as LoopTraceEmitter, l as LoopTraceEvent, m as ValidationCtx } from './types-Co507h15.js';
-import { DefaultVerdict, AgentProfile } from '@tangle-network/agent-eval';
+import { I as Iteration, D as Driver, L as LoopSandboxClient, A as AgentRunSpec, O as OutputAdapter, V as Validator, E as ExecCtx, a as LoopWinner, b as LoopResult } from './types-BZw2bqJc.js';
+export { c as LoopDecisionPayload, d as LoopEndedPayload, e as LoopIterationDispatchPayload, f as LoopIterationEndedPayload, g as LoopIterationStartedPayload, h as LoopPlanDescription, i as LoopPlanPayload, j as LoopSandboxPlacement, k as LoopStartedPayload, l as LoopTokenUsage, m as LoopTraceEmitter, n as LoopTraceEvent, o as ValidationCtx } from './types-BZw2bqJc.js';
+import { DefaultVerdict, AgentProfile as AgentProfile$1 } from '@tangle-network/agent-eval';
 export { DefaultVerdict } from '@tangle-network/agent-eval';
 import { Scenario, DispatchFn, ProfileDispatchFn } from '@tangle-network/agent-eval/campaign';
 import './runtime-run-B8VIiOhI.js';
 import './types-CsCCryln.js';
 
+/**
+ * @experimental
+ *
+ * Dynamic driver — the agent authors the loop topology at runtime.
+ *
+ * Where `refine` and `fanout-vote` encode a fixed shape as a pure function of
+ * history, this driver delegates the per-round shape to an injected
+ * `TopologyPlanner`. Each round the planner inspects the task + iteration
+ * history and emits one `TopologyMove`:
+ *   - `refine` → one task next round (optionally rewritten from the prior attempt)
+ *   - `fanout` → N tasks next round (the kernel round-robins `agentRuns`, so a
+ *     2-harness fanout dispatches branch 0 to harness A and branch 1 to harness B)
+ *   - `stop`   → terminate; the kernel selects the winner across all iterations
+ *
+ * The planner is the brain; this driver is the structure. It maps moves onto
+ * the kernel's `plan`/`decide` contract, enforces the iteration + fanout caps,
+ * and fails loud on a malformed move. The planner is injected exactly like
+ * `refine`'s `refineTask` and `fanout-vote`'s `selector` — so a test can drive
+ * a deterministic policy through the real kernel, and production can wire it to
+ * an LLM via `createSandboxPlanner`.
+ *
+ * Topology is orthogonal to harness: the planner never names a backend. Which
+ * harness runs a branch is decided by the `AgentRunSpec` the kernel round-robins
+ * to, so one dynamic driver works across claude-code, codex, opencode, pi —
+ * including fanning a single round across several at once.
+ */
+
+/** Terminal once `decide` returns `'done'` (a kernel terminal decision). */
+type DynamicDecision = 'continue' | 'done';
+/**
+ * One topology decision for the next round. `fanout` carries explicit tasks
+ * rather than a count so the planner can issue heterogeneous branches (a
+ * different sub-task per harness); pass N copies of one task for a homogeneous
+ * fanout that relies on `agentRuns` diversity instead.
+ *
+ * @experimental
+ */
+type TopologyMove<Task> = {
+    kind: 'refine';
+    task: Task;
+    rationale?: string;
+} | {
+    kind: 'fanout';
+    tasks: Task[];
+    rationale?: string;
+} | {
+    kind: 'stop';
+    rationale?: string;
+};
+/** @experimental */
+interface PlannerContext<Task, Output> {
+    /** The root task the loop was invoked with — stable across rounds. */
+    task: Task;
+    /** Every iteration so far, in dispatch order, with outputs + verdicts. */
+    history: ReadonlyArray<Iteration<Task, Output>>;
+    /** `history.length` — iterations already spent. */
+    iterationsSpent: number;
+    /** Iterations left before the driver's `maxIterations` cap forces a stop. */
+    iterationsRemaining: number;
+}
+/**
+ * Chooses the next topology move from the task + history. Sync or async; an
+ * async planner is where an LLM call goes (see `createSandboxPlanner`).
+ *
+ * @experimental
+ */
+type TopologyPlanner<Task, Output> = (ctx: PlannerContext<Task, Output>) => TopologyMove<Task> | Promise<TopologyMove<Task>>;
+/** @experimental */
+interface CreateDynamicDriverOptions<Task, Output> {
+    /** The agent-authored topology policy. Invoked once per round in `plan`. */
+    planner: TopologyPlanner<Task, Output>;
+    /**
+     * Hard safety cap on total iterations. When reached, the driver stops before
+     * consulting the planner. Default 8. Set the kernel's `runLoop`
+     * `maxIterations >= ` this so the driver's cap governs and the loop closes on
+     * a clean `'done'` rather than a truncated `'continue'`.
+     */
+    maxIterations?: number;
+    /** Max branches a single `fanout` move may dispatch. Default 4. */
+    maxFanout?: number;
+    /** Stable identifier surfaced in trace events. Default `'dynamic'`. */
+    name?: string;
+}
+/** @experimental */
+declare function createDynamicDriver<Task, Output>(options: CreateDynamicDriverOptions<Task, Output>): Driver<Task, Output, DynamicDecision>;
+/**
+ * Compact, planner-friendly view of iteration history — what an LLM planner
+ * needs to choose the next move without the raw event streams. Output is
+ * truncated so a long run's prompt stays bounded.
+ *
+ * @experimental
+ */
+declare function summarizeHistory<Task, Output>(history: ReadonlyArray<Iteration<Task, Output>>, opts?: {
+    maxOutputChars?: number;
+}): Array<{
+    index: number;
+    agentRunName: string;
+    valid?: boolean;
+    score?: number;
+    error?: string;
+    output?: string;
+}>;
+
 /**
  * @experimental
  *
@@ -88,6 +192,64 @@ declare function createRefineDriver<Task, Output>(options?: CreateRefineDriverOp
  */
 declare function refineWinnerIndex<Task, Output>(iterations: ReadonlyArray<Iteration<Task, Output>>): number | undefined;
 
+/**
+ * @experimental
+ *
+ * `createSandboxPlanner` — wire the dynamic driver's `TopologyPlanner` to a
+ * real agent. Each round it spins a sandbox on `profile`, streams a prompt that
+ * carries the history summary, and decodes the agent's chosen `TopologyMove`
+ * from a JSON envelope it emits. This is the "agent authors its own loop
+ * topology" path: the planner profile can be any harness (claude-code, codex,
+ * opencode, pi) — its only job is to read what happened and emit the next move.
+ *
+ * The planner profile is deliberately distinct from the worker `agentRuns`: a
+ * cheap fast model can steer topology while expensive workers do the labor, and
+ * the planner never names which harness runs a branch — the kernel's
+ * `agentRuns` round-robin decides that.
+ *
+ * Envelope contract the agent must emit (fenced ```json or a structured
+ * `result`/`final` event payload):
+ *   { "kind": "refine" | "fanout" | "stop",
+ *     "tasks"?: [ <task>, ... ],   // decoded via `decodeTask`
+ *     "n"?: number,                // fanout shorthand: N copies of the root task
+ *     "rationale"?: string }
+ *
+ * A missing / unparseable / unknown-kind envelope throws `PlannerError` — the
+ * loop never silently runs a topology the agent did not choose.
+ */
+
+/** Raw, pre-decode envelope an agent emits to choose the next move. */
+interface TopologyMoveEnvelope {
+    kind: string;
+    tasks?: unknown[];
+    n?: number;
+    rationale?: string;
+}
+/** @experimental */
+interface CreateSandboxPlannerOptions<Task, Output> {
+    /** Sandbox client — the planner calls `.create()` once per round. */
+    client: LoopSandboxClient;
+    /** The planner agent. Steers topology; does not run the work. */
+    profile: AgentProfile;
+    /**
+     * Decode one raw task from the envelope's `tasks[]` into a domain `Task`.
+     * Required because `Task` is opaque to this module — only the caller knows
+     * its shape. Throw to reject a malformed task; the error surfaces as a
+     * `PlannerError`.
+     */
+    decodeTask: (raw: unknown, ctx: PlannerContext<Task, Output>) => Task;
+    /** Override the default prompt (history summary + envelope contract). */
+    buildPrompt?: (ctx: PlannerContext<Task, Output>) => string;
+    /** Override envelope extraction from the event stream. */
+    parseEnvelope?: (events: SandboxEvent[]) => TopologyMoveEnvelope | undefined;
+    /** Sandbox overrides for the planner sandbox (timeouts, env, etc.). */
+    sandboxOverrides?: AgentRunSpec<Task>['sandboxOverrides'];
+    /** Cancellation for the planner's own LLM call. */
+    signal?: AbortSignal;
+}
+/** @experimental */
+declare function createSandboxPlanner<Task, Output>(opts: CreateSandboxPlannerOptions<Task, Output>): TopologyPlanner<Task, Output>;
+
 /**
  * @experimental
  *
@@ -154,41 +316,6 @@ interface RunLoopOptions<Task, Output, Decision> {
 /** @experimental */
 declare function runLoop<Task, Output, Decision>(options: RunLoopOptions<Task, Output, Decision>): Promise<LoopResult<Task, Output, Decision>>;
 
-/**
- * Bridge a finished `runLoop` into an agent-eval campaign / profile-matrix
- * dispatch.
- *
- * `runProfileMatrix` (and `runCampaign`) run the backend-integrity guard over
- * the token usage a dispatch reports through `ctx.cost`. A dispatch that wraps
- * `runLoop` must forward the loop's cost AND token usage, or the guard reads
- * the run as a stub and throws. `reportLoopUsage` is that one line:
- *
- *   const dispatch: ProfileDispatchFn<S, A> = async (profile, scenario, ctx) => {
- *     const result = await runLoop({ ...optsFor(profile, scenario), ctx: loopCtx })
- *     reportLoopUsage(ctx, result)
- *     return result.winner?.output as A
- *   }
- *
- * Typed structurally against the campaign `DispatchContext.cost` so this module
- * stays free of an agent-eval import — it works with any cost meter exposing
- * `observe` + `observeTokens`.
- */
-
-/** The slice of an agent-eval campaign `DispatchContext.cost` this needs. */
-interface UsageSink {
-    observe(amountUsd: number, source: string): void;
-    observeTokens(usage: {
-        input: number;
-        output: number;
-    }): void;
-}
-/**
- * Forward a `LoopResult`'s aggregated cost + token usage into a campaign cost
- * meter so the backend-integrity guard sees real LLM activity. `source`
- * defaults to `'loop'`.
- */
-declare function reportLoopUsage<Task, Output, Decision>(cost: UsageSink, result: Pick<LoopResult<Task, Output, Decision>, 'costUsd' | 'tokenUsage'>, source?: string): void;
-
 /**
  * `loopDispatch` — turn `runLoop` into an agent-eval campaign dispatch.
  *
@@ -225,7 +352,7 @@ interface LoopDispatchOptions<Task, Output, Decision, TScenario extends Scenario
     sandboxClient: LoopSandboxClient;
     /** Build the per-cell runLoop options from the scenario (+ profile, when
      *  used with `runProfileMatrix`). */
-    toLoopOptions: (scenario: TScenario, profile: AgentProfile) => LoopOptionsForDispatch<Task, Output, Decision>;
+    toLoopOptions: (scenario: TScenario, profile: AgentProfile$1) => LoopOptionsForDispatch<Task, Output, Decision>;
     /** Map the finished loop to the artifact the judges score. Default:
      *  `result.winner?.output`. A loop with no winner yields `undefined` (judges
      *  skip the cell) — but the loop's token usage is STILL reported, so the
@@ -252,4 +379,39 @@ declare function loopCampaignDispatch<Task, Output, Decision, TScenario extends
     toLoopOptions: (scenario: TScenario) => LoopOptionsForDispatch<Task, Output, Decision>;
 }): DispatchFn<TScenario, TArtifact>;
 
-export { AgentRunSpec, type CreateFanoutVoteDriverOptions, type CreateRefineDriverOptions, Driver, ExecCtx, type FanoutVoteDecision, type FanoutVoteScored, Iteration, type LoopDispatchOptions, type LoopOptionsForDispatch, LoopResult, LoopSandboxClient, LoopWinner, OutputAdapter, type RefineDecision, type RunLoopOptions, type UsageSink, Validator, createFanoutVoteDriver, createRefineDriver, loopCampaignDispatch, loopDispatch, refineWinnerIndex, reportLoopUsage, runLoop, scoreFanoutVoteIterations };
+/**
+ * Bridge a finished `runLoop` into an agent-eval campaign / profile-matrix
+ * dispatch.
+ *
+ * `runProfileMatrix` (and `runCampaign`) run the backend-integrity guard over
+ * the token usage a dispatch reports through `ctx.cost`. A dispatch that wraps
+ * `runLoop` must forward the loop's cost AND token usage, or the guard reads
+ * the run as a stub and throws. `reportLoopUsage` is that one line:
+ *
+ *   const dispatch: ProfileDispatchFn<S, A> = async (profile, scenario, ctx) => {
+ *     const result = await runLoop({ ...optsFor(profile, scenario), ctx: loopCtx })
+ *     reportLoopUsage(ctx, result)
+ *     return result.winner?.output as A
+ *   }
+ *
+ * Typed structurally against the campaign `DispatchContext.cost` so this module
+ * stays free of an agent-eval import — it works with any cost meter exposing
+ * `observe` + `observeTokens`.
+ */
+
+/** The slice of an agent-eval campaign `DispatchContext.cost` this needs. */
+interface UsageSink {
+    observe(amountUsd: number, source: string): void;
+    observeTokens(usage: {
+        input: number;
+        output: number;
+    }): void;
+}
+/**
+ * Forward a `LoopResult`'s aggregated cost + token usage into a campaign cost
+ * meter so the backend-integrity guard sees real LLM activity. `source`
+ * defaults to `'loop'`.
+ */
+declare function reportLoopUsage<Task, Output, Decision>(cost: UsageSink, result: Pick<LoopResult<Task, Output, Decision>, 'costUsd' | 'tokenUsage'>, source?: string): void;
+
+export { AgentRunSpec, type CreateDynamicDriverOptions, type CreateFanoutVoteDriverOptions, type CreateRefineDriverOptions, type CreateSandboxPlannerOptions, Driver, type DynamicDecision, ExecCtx, type FanoutVoteDecision, type FanoutVoteScored, Iteration, type LoopDispatchOptions, type LoopOptionsForDispatch, LoopResult, LoopSandboxClient, LoopWinner, OutputAdapter, type PlannerContext, type RefineDecision, type RunLoopOptions, type TopologyMove, type TopologyMoveEnvelope, type TopologyPlanner, type UsageSink, Validator, createDynamicDriver, createFanoutVoteDriver, createRefineDriver, createSandboxPlanner, loopCampaignDispatch, loopDispatch, refineWinnerIndex, reportLoopUsage, runLoop, scoreFanoutVoteIterations, summarizeHistory };

package/dist/loops.js

@@ -1,25 +1,31 @@
 import {
+  createDynamicDriver,
   createRefineDriver,
+  createSandboxPlanner,
   loopCampaignDispatch,
   loopDispatch,
   refineWinnerIndex,
   reportLoopUsage,
-  runLoop
-} from "./chunk-PACEJFUE.js";
+  runLoop,
+  summarizeHistory
+} from "./chunk-7KS6UEHB.js";
 import {
   createFanoutVoteDriver,
   scoreFanoutVoteIterations
-} from "./chunk-URDSRUPQ.js";
-import "./chunk-XZYF3YJN.js";
+} from "./chunk-PY6NMZYX.js";
+import "./chunk-SQSCRJ7U.js";
 import "./chunk-DGUM43GV.js";
 export {
+  createDynamicDriver,
   createFanoutVoteDriver,
   createRefineDriver,
+  createSandboxPlanner,
   loopCampaignDispatch,
   loopDispatch,
   refineWinnerIndex,
   reportLoopUsage,
   runLoop,
-  scoreFanoutVoteIterations
+  scoreFanoutVoteIterations,
+  summarizeHistory
 };
 //# sourceMappingURL=loops.js.map

package/dist/mcp/bin.js

@@ -3,15 +3,15 @@ import {
   createDefaultCoderDelegate,
   createMcpServer,
   detectExecutor
-} from "../chunk-XNZYEQMF.js";
-import "../chunk-UNQM6XQO.js";
+} from "../chunk-VVHX5RKE.js";
+import "../chunk-HSX6PFZR.js";
 import "../chunk-GLR25NG7.js";
 import {
   runLoop
-} from "../chunk-PACEJFUE.js";
-import "../chunk-CBQVID7G.js";
-import "../chunk-URDSRUPQ.js";
-import "../chunk-XZYF3YJN.js";
+} from "../chunk-7KS6UEHB.js";
+import "../chunk-5QVVET72.js";
+import "../chunk-PY6NMZYX.js";
+import "../chunk-SQSCRJ7U.js";
 import "../chunk-DGUM43GV.js";
 
 // src/mcp/bin.ts

package/dist/mcp/index.d.ts

@@ -1,10 +1,10 @@
-import { b as LoopSandboxClient, h as LoopSandboxPlacement, k as LoopTraceEmitter } from '../types-Co507h15.js';
+import { L as LoopSandboxClient, j as LoopSandboxPlacement, m as LoopTraceEmitter } from '../types-BZw2bqJc.js';
 import { SandboxInstance } from '@tangle-network/sandbox';
 import { CoderOutput } from '../profiles.js';
 import { L as LocalHarness, r as runLocalHarness } from '../local-harness-KrdFTY5R.js';
 export { a as LocalHarnessResult, R as RunLocalHarnessOptions } from '../local-harness-KrdFTY5R.js';
-import { O as OtelExporter } from '../otel-export-CsgwKFq8.js';
-export { m as mcpToolsForRuntimeMcp, a as mcpToolsForRuntimeMcpSubset } from '../otel-export-CsgwKFq8.js';
+import { O as OtelExporter } from '../otel-export-xgf4J6bo.js';
+export { m as mcpToolsForRuntimeMcp, a as mcpToolsForRuntimeMcpSubset } from '../otel-export-xgf4J6bo.js';
 import '@tangle-network/agent-eval';
 import '../runtime-run-B8VIiOhI.js';
 import '../types-CsCCryln.js';

package/dist/mcp/index.js

@@ -9,13 +9,13 @@ import {
   createWorktree,
   detectExecutor,
   removeWorktree
-} from "../chunk-XNZYEQMF.js";
+} from "../chunk-VVHX5RKE.js";
 import {
+  buildLoopOtelSpans,
   createOtelExporter,
-  loopEventToOtelSpan,
   mcpToolsForRuntimeMcp,
   mcpToolsForRuntimeMcpSubset
-} from "../chunk-IORDTTVB.js";
+} from "../chunk-Q4ZDSLBD.js";
 import {
   DELEGATE_CODE_DESCRIPTION,
   DELEGATE_CODE_INPUT_SCHEMA,
@@ -46,14 +46,14 @@ import {
   validateDelegateResearchArgs,
   validateDelegationHistoryArgs,
   validateDelegationStatusArgs
-} from "../chunk-UNQM6XQO.js";
+} from "../chunk-HSX6PFZR.js";
 import {
   runLocalHarness
 } from "../chunk-GLR25NG7.js";
-import "../chunk-PACEJFUE.js";
-import "../chunk-CBQVID7G.js";
-import "../chunk-URDSRUPQ.js";
-import "../chunk-XZYF3YJN.js";
+import "../chunk-7KS6UEHB.js";
+import "../chunk-5QVVET72.js";
+import "../chunk-PY6NMZYX.js";
+import "../chunk-SQSCRJ7U.js";
 import "../chunk-DGUM43GV.js";
 
 // src/mcp/trace-propagation.ts
@@ -64,11 +64,20 @@ function readTraceContextFromEnv() {
 }
 function createPropagatingTraceEmitter(ctx) {
   const exporter = createOtelExporter();
+  const buffers = /* @__PURE__ */ new Map();
   const emitter = {
     emit(event) {
       if (!exporter) return;
-      const span = loopEventToOtelSpan(event, ctx.traceId, ctx.parentSpanId);
-      exporter.exportSpan(span);
+      const buf = buffers.get(event.runId);
+      if (buf) buf.push(event);
+      else buffers.set(event.runId, [event]);
+      if (event.kind === "loop.ended") {
+        const events = buffers.get(event.runId) ?? [event];
+        buffers.delete(event.runId);
+        for (const span of buildLoopOtelSpans(events, ctx.traceId, ctx.parentSpanId)) {
+          exporter.exportSpan(span);
+        }
+      }
     }
   };
   return { emitter, exporter, context: ctx };

package/dist/mcp/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/mcp/trace-propagation.ts"],"sourcesContent":["/**\n * @experimental\n *\n * Trace context propagation for MCP subprocess.\n *\n * When the MCP server is launched as a child process by a sandbox harness,\n * the parent passes trace context via environment variables:\n *\n *   TRACE_ID=<current-run-trace-id>\n *   PARENT_SPAN_ID=<span-that-dispatched-the-delegation>\n *\n * The MCP server reads these at startup and uses them as the root of its\n * internal trace tree. All spans emitted by `runLoop` invocations inside\n * the MCP are children of the parent's delegation span.\n *\n * When these env vars are absent, the MCP generates a fresh trace root —\n * the server operates standalone without trace joining.\n */\n\nimport type { LoopTraceEmitter, LoopTraceEvent } from '../loops/types'\nimport type { OtelExporter } from '../otel-export'\nimport { createOtelExporter, loopEventToOtelSpan } from '../otel-export'\n\nexport interface TraceContext {\n  /** Trace id inherited from the parent process, or a fresh one. */\n  traceId: string\n  /** Parent span id from the delegation that launched this MCP server. */\n  parentSpanId?: string\n}\n\n/**\n * Read trace context from the process environment.\n * Returns a context with inherited ids or a freshly generated root.\n */\nexport function readTraceContextFromEnv(): TraceContext {\n  const traceId = process.env.TRACE_ID || generateTraceId()\n  const parentSpanId = process.env.PARENT_SPAN_ID || undefined\n  return { traceId, parentSpanId }\n}\n\n/**\n * Create a LoopTraceEmitter that:\n *   1. Parents all spans under the inherited PARENT_SPAN_ID.\n *   2. Exports spans to OTEL when OTEL_EXPORTER_OTLP_ENDPOINT is set.\n *\n * Returns both the emitter and the optional exporter handle for shutdown.\n */\nexport function createPropagatingTraceEmitter(ctx: TraceContext): {\n  emitter: LoopTraceEmitter\n  exporter: OtelExporter | undefined\n  context: TraceContext\n} {\n  const exporter = createOtelExporter()\n\n  const emitter: LoopTraceEmitter = {\n    emit(event: LoopTraceEvent) {\n      if (!exporter) return\n      const span = loopEventToOtelSpan(event, ctx.traceId, ctx.parentSpanId)\n      exporter.exportSpan(span)\n    },\n  }\n\n  return { emitter, exporter, context: ctx }\n}\n\n/**\n * Build env vars to pass to a child MCP subprocess so it inherits the\n * current trace context.\n */\nexport function traceContextToEnv(ctx: TraceContext): Record<string, string> {\n  const env: Record<string, string> = { TRACE_ID: ctx.traceId }\n  if (ctx.parentSpanId) env.PARENT_SPAN_ID = ctx.parentSpanId\n  return env\n}\n\nfunction generateTraceId(): string {\n  const bytes = new Uint8Array(16)\n  if (typeof globalThis.crypto?.getRandomValues === 'function') {\n    globalThis.crypto.getRandomValues(bytes)\n  } else {\n    for (let i = 0; i < 16; i++) bytes[i] = Math.floor(Math.random() * 256)\n  }\n  return Array.from(bytes)\n    .map((b) => b.toString(16).padStart(2, '0'))\n    .join('')\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkCO,SAAS,0BAAwC;AACtD,QAAM,UAAU,QAAQ,IAAI,YAAY,gBAAgB;AACxD,QAAM,eAAe,QAAQ,IAAI,kBAAkB;AACnD,SAAO,EAAE,SAAS,aAAa;AACjC;AASO,SAAS,8BAA8B,KAI5C;AACA,QAAM,WAAW,mBAAmB;AAEpC,QAAM,UAA4B;AAAA,IAChC,KAAK,OAAuB;AAC1B,UAAI,CAAC,SAAU;AACf,YAAM,OAAO,oBAAoB,OAAO,IAAI,SAAS,IAAI,YAAY;AACrE,eAAS,WAAW,IAAI;AAAA,IAC1B;AAAA,EACF;AAEA,SAAO,EAAE,SAAS,UAAU,SAAS,IAAI;AAC3C;AAMO,SAAS,kBAAkB,KAA2C;AAC3E,QAAM,MAA8B,EAAE,UAAU,IAAI,QAAQ;AAC5D,MAAI,IAAI,aAAc,KAAI,iBAAiB,IAAI;AAC/C,SAAO;AACT;AAEA,SAAS,kBAA0B;AACjC,QAAM,QAAQ,IAAI,WAAW,EAAE;AAC/B,MAAI,OAAO,WAAW,QAAQ,oBAAoB,YAAY;AAC5D,eAAW,OAAO,gBAAgB,KAAK;AAAA,EACzC,OAAO;AACL,aAAS,IAAI,GAAG,IAAI,IAAI,IAAK,OAAM,CAAC,IAAI,KAAK,MAAM,KAAK,OAAO,IAAI,GAAG;AAAA,EACxE;AACA,SAAO,MAAM,KAAK,KAAK,EACpB,IAAI,CAAC,MAAM,EAAE,SAAS,EAAE,EAAE,SAAS,GAAG,GAAG,CAAC,EAC1C,KAAK,EAAE;AACZ;","names":[]}
+{"version":3,"sources":["../../src/mcp/trace-propagation.ts"],"sourcesContent":["/**\n * @experimental\n *\n * Trace context propagation for MCP subprocess.\n *\n * When the MCP server is launched as a child process by a sandbox harness,\n * the parent passes trace context via environment variables:\n *\n *   TRACE_ID=<current-run-trace-id>\n *   PARENT_SPAN_ID=<span-that-dispatched-the-delegation>\n *\n * The MCP server reads these at startup and uses them as the root of its\n * internal trace tree. All spans emitted by `runLoop` invocations inside\n * the MCP are children of the parent's delegation span.\n *\n * When these env vars are absent, the MCP generates a fresh trace root —\n * the server operates standalone without trace joining.\n */\n\nimport type { LoopTraceEmitter, LoopTraceEvent } from '../loops/types'\nimport type { OtelExporter } from '../otel-export'\nimport { buildLoopOtelSpans, createOtelExporter } from '../otel-export'\n\nexport interface TraceContext {\n  /** Trace id inherited from the parent process, or a fresh one. */\n  traceId: string\n  /** Parent span id from the delegation that launched this MCP server. */\n  parentSpanId?: string\n}\n\n/**\n * Read trace context from the process environment.\n * Returns a context with inherited ids or a freshly generated root.\n */\nexport function readTraceContextFromEnv(): TraceContext {\n  const traceId = process.env.TRACE_ID || generateTraceId()\n  const parentSpanId = process.env.PARENT_SPAN_ID || undefined\n  return { traceId, parentSpanId }\n}\n\n/**\n * Create a LoopTraceEmitter that:\n *   1. Parents all spans under the inherited PARENT_SPAN_ID.\n *   2. Exports spans to OTEL when OTEL_EXPORTER_OTLP_ENDPOINT is set.\n *\n * Returns both the emitter and the optional exporter handle for shutdown.\n */\nexport function createPropagatingTraceEmitter(ctx: TraceContext): {\n  emitter: LoopTraceEmitter\n  exporter: OtelExporter | undefined\n  context: TraceContext\n} {\n  const exporter = createOtelExporter()\n\n  // Buffer events per loop run, then emit the full nested span tree on\n  // `loop.ended` so the topology hierarchy (loop → round → branch) reaches the\n  // OTLP collector — not a flat list of zero-duration point spans. A run that\n  // never reaches `loop.ended` (hard abort) drops its buffer; acceptable for\n  // the short-lived MCP subprocess.\n  const buffers = new Map<string, LoopTraceEvent[]>()\n\n  const emitter: LoopTraceEmitter = {\n    emit(event: LoopTraceEvent) {\n      if (!exporter) return\n      const buf = buffers.get(event.runId)\n      if (buf) buf.push(event)\n      else buffers.set(event.runId, [event])\n      if (event.kind === 'loop.ended') {\n        const events = buffers.get(event.runId) ?? [event]\n        buffers.delete(event.runId)\n        for (const span of buildLoopOtelSpans(events, ctx.traceId, ctx.parentSpanId)) {\n          exporter.exportSpan(span)\n        }\n      }\n    },\n  }\n\n  return { emitter, exporter, context: ctx }\n}\n\n/**\n * Build env vars to pass to a child MCP subprocess so it inherits the\n * current trace context.\n */\nexport function traceContextToEnv(ctx: TraceContext): Record<string, string> {\n  const env: Record<string, string> = { TRACE_ID: ctx.traceId }\n  if (ctx.parentSpanId) env.PARENT_SPAN_ID = ctx.parentSpanId\n  return env\n}\n\nfunction generateTraceId(): string {\n  const bytes = new Uint8Array(16)\n  if (typeof globalThis.crypto?.getRandomValues === 'function') {\n    globalThis.crypto.getRandomValues(bytes)\n  } else {\n    for (let i = 0; i < 16; i++) bytes[i] = Math.floor(Math.random() * 256)\n  }\n  return Array.from(bytes)\n    .map((b) => b.toString(16).padStart(2, '0'))\n    .join('')\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkCO,SAAS,0BAAwC;AACtD,QAAM,UAAU,QAAQ,IAAI,YAAY,gBAAgB;AACxD,QAAM,eAAe,QAAQ,IAAI,kBAAkB;AACnD,SAAO,EAAE,SAAS,aAAa;AACjC;AASO,SAAS,8BAA8B,KAI5C;AACA,QAAM,WAAW,mBAAmB;AAOpC,QAAM,UAAU,oBAAI,IAA8B;AAElD,QAAM,UAA4B;AAAA,IAChC,KAAK,OAAuB;AAC1B,UAAI,CAAC,SAAU;AACf,YAAM,MAAM,QAAQ,IAAI,MAAM,KAAK;AACnC,UAAI,IAAK,KAAI,KAAK,KAAK;AAAA,UAClB,SAAQ,IAAI,MAAM,OAAO,CAAC,KAAK,CAAC;AACrC,UAAI,MAAM,SAAS,cAAc;AAC/B,cAAM,SAAS,QAAQ,IAAI,MAAM,KAAK,KAAK,CAAC,KAAK;AACjD,gBAAQ,OAAO,MAAM,KAAK;AAC1B,mBAAW,QAAQ,mBAAmB,QAAQ,IAAI,SAAS,IAAI,YAAY,GAAG;AAC5E,mBAAS,WAAW,IAAI;AAAA,QAC1B;AAAA,MACF;AAAA,IACF;AAAA,EACF;AAEA,SAAO,EAAE,SAAS,UAAU,SAAS,IAAI;AAC3C;AAMO,SAAS,kBAAkB,KAA2C;AAC3E,QAAM,MAA8B,EAAE,UAAU,IAAI,QAAQ;AAC5D,MAAI,IAAI,aAAc,KAAI,iBAAiB,IAAI;AAC/C,SAAO;AACT;AAEA,SAAS,kBAA0B;AACjC,QAAM,QAAQ,IAAI,WAAW,EAAE;AAC/B,MAAI,OAAO,WAAW,QAAQ,oBAAoB,YAAY;AAC5D,eAAW,OAAO,gBAAgB,KAAK;AAAA,EACzC,OAAO;AACL,aAAS,IAAI,GAAG,IAAI,IAAI,IAAK,OAAM,CAAC,IAAI,KAAK,MAAM,KAAK,OAAO,IAAI,GAAG;AAAA,EACxE;AACA,SAAO,MAAM,KAAK,KAAK,EACpB,IAAI,CAAC,MAAM,EAAE,SAAS,EAAE,EAAE,SAAS,GAAG,GAAG,CAAC,EAC1C,KAAK,EAAE;AACZ;","names":[]}

package/dist/{otel-export-CsgwKFq8.d.ts → otel-export-xgf4J6bo.d.ts}

@@ -110,6 +110,28 @@ declare function loopEventToOtelSpan(event: {
     timestamp: number;
     payload: object;
 }, traceId: string, parentSpanId?: string): OtelSpan;
+/**
+ * Build a nested, real-duration OTLP span tree for ONE loop run from its full
+ * ordered `LoopTraceEvent` stream. Unlike `loopEventToOtelSpan` (one flat,
+ * zero-duration span per event), this reconstructs the topology hierarchy a
+ * GenAI trace viewer renders natively:
+ *
+ *   loop (invoke_workflow)
+ *     └─ loop.round[k] (invoke_workflow)   ← tangle.loop.move.{kind,width,rationale}
+ *          ├─ loop.iteration[i] (invoke_agent)  ← gen_ai.agent.name + usage + verdict + placement
+ *          └─ …
+ *
+ * Attributes follow the current GenAI semconv (`gen_ai.*`) where they apply and
+ * a namespaced `tangle.loop.*` / `tangle.cost.usd` extension for topology /
+ * verdict / placement / cost (not yet standardized). Pure: feed it a buffered
+ * per-runId event array (e.g. flushed on `loop.ended`) and export the result.
+ */
+declare function buildLoopOtelSpans(events: ReadonlyArray<{
+    kind: string;
+    runId: string;
+    timestamp: number;
+    payload: object;
+}>, traceId: string, rootParentSpanId?: string): OtelSpan[];
 /** Wire version the eval-runs ingest enforces (X-Tangle-Wire-Version + body). */
 declare const INTELLIGENCE_WIRE_VERSION = "2026-05-26.v1";
 interface EvalRunGeneration {
@@ -166,4 +188,4 @@ interface EvalRunsExportResult {
  */
 declare function exportEvalRuns(events: EvalRunEvent[], config?: EvalRunsExportConfig): Promise<EvalRunsExportResult>;
 
-export { type EvalRunEvent as E, INTELLIGENCE_WIRE_VERSION as I, type OtelExporter as O, mcpToolsForRuntimeMcpSubset as a, type EvalRunGeneration as b, type EvalRunsExportConfig as c, type EvalRunsExportResult as d, type OtelAttribute as e, type OtelExportConfig as f, type OtelSpan as g, createOtelExporter as h, exportEvalRuns as i, loopEventToOtelSpan as l, mcpToolsForRuntimeMcp as m };
+export { type EvalRunEvent as E, INTELLIGENCE_WIRE_VERSION as I, type OtelExporter as O, mcpToolsForRuntimeMcpSubset as a, type EvalRunGeneration as b, type EvalRunsExportConfig as c, type EvalRunsExportResult as d, type OtelAttribute as e, type OtelExportConfig as f, type OtelSpan as g, buildLoopOtelSpans as h, createOtelExporter as i, exportEvalRuns as j, loopEventToOtelSpan as l, mcpToolsForRuntimeMcp as m };

package/dist/profiles.d.ts

@@ -1,5 +1,5 @@
 import { AgentProfile } from '@tangle-network/sandbox';
-import { O as OutputAdapter, V as Validator, A as AgentRunSpec, D as Driver } from './types-Co507h15.js';
+import { O as OutputAdapter, V as Validator, A as AgentRunSpec, D as Driver } from './types-BZw2bqJc.js';
 import '@tangle-network/agent-eval';
 import './runtime-run-B8VIiOhI.js';
 import './types-CsCCryln.js';

package/dist/profiles.js

@@ -2,9 +2,9 @@ import {
   coderProfile,
   createCoderValidator,
   multiHarnessCoderFanout
-} from "./chunk-CBQVID7G.js";
-import "./chunk-URDSRUPQ.js";
-import "./chunk-XZYF3YJN.js";
+} from "./chunk-5QVVET72.js";
+import "./chunk-PY6NMZYX.js";
+import "./chunk-SQSCRJ7U.js";
 import "./chunk-DGUM43GV.js";
 export {
   coderProfile,

package/dist/{types-Co507h15.d.ts → types-BZw2bqJc.d.ts}

@@ -118,6 +118,23 @@ interface Driver<Task, Output, Decision> {
      * is hit, or when the abort signal fires.
      */
     decide(history: ReadonlyArray<Iteration<Task, Output>>): Decision | Promise<Decision>;
+    /**
+     * Optional: describe the move `plan()` just produced, for trace emission.
+     * The kernel calls this immediately after `plan()` and emits the result in
+     * the `loop.plan` event so a topology viewer can render the agent's chosen
+     * 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.
+     */
+    describePlan?(): LoopPlanDescription | undefined;
+}
+/** @experimental Driver-supplied description of the just-planned move. */
+interface LoopPlanDescription {
+    /** Topology move this round — e.g. `'refine' | 'fanout' | 'verify' | 'stop'`. */
+    kind: string;
+    /** Why the driver chose this move (the agent's rationale), when available. */
+    rationale?: string;
 }
 /** @experimental */
 interface LoopWinner<Task, Output> {
@@ -174,6 +191,11 @@ type LoopTraceEvent = {
     runId: string;
     timestamp: number;
     payload: LoopStartedPayload;
+} | {
+    kind: 'loop.plan';
+    runId: string;
+    timestamp: number;
+    payload: LoopPlanPayload;
 } | {
     kind: 'loop.iteration.started';
     runId: string;
@@ -207,6 +229,24 @@ interface LoopStartedPayload {
     maxIterations: number;
     maxConcurrency: number;
 }
+/**
+ * Emitted once per `plan()` round, immediately after the driver plans. Carries
+ * the topology move so a viewer renders WHAT the agent decided + WHY, not just
+ * the inferred fan-width. `moveKind` is the driver's `describePlan().kind` when
+ * provided, else inferred from `plannedCount` (0→stop, 1→refine, N→fanout).
+ *
+ * @experimental
+ */
+interface LoopPlanPayload {
+    /** 0-based plan round (one per `plan()` call). */
+    roundIndex: number;
+    /** Tasks the driver issued this round. */
+    plannedCount: number;
+    /** Topology move — `'refine' | 'fanout' | 'verify' | 'stop'` etc. */
+    moveKind: string;
+    /** Driver rationale for the move, when available. */
+    rationale?: string;
+}
 /** @experimental */
 interface LoopIterationStartedPayload {
     iterationIndex: number;
@@ -241,6 +281,9 @@ interface LoopIterationEndedPayload {
     error?: string;
     costUsd: number;
     durationMs: number;
+    /** Summed LLM token usage for this iteration — maps to gen_ai.usage.* on the
+     *  branch span. Omitted when no `llm_call` events carried token counts. */
+    tokenUsage?: LoopTokenUsage;
 }
 /** @experimental */
 interface LoopDecisionPayload {
@@ -281,4 +324,4 @@ interface ExecCtx {
     parentSpanId?: string;
 }
 
-export type { AgentRunSpec as A, Driver as D, ExecCtx as E, Iteration as I, LoopWinner as L, OutputAdapter as O, Validator as V, LoopResult as a, LoopSandboxClient as b, LoopDecisionPayload as c, LoopEndedPayload as d, LoopIterationDispatchPayload as e, LoopIterationEndedPayload as f, LoopIterationStartedPayload as g, LoopSandboxPlacement as h, LoopStartedPayload as i, LoopTokenUsage as j, LoopTraceEmitter as k, LoopTraceEvent as l, ValidationCtx as m };
+export type { AgentRunSpec as A, Driver as D, ExecCtx as E, Iteration as I, LoopSandboxClient as L, OutputAdapter as O, Validator as V, LoopWinner as a, LoopResult as b, LoopDecisionPayload as c, LoopEndedPayload as d, LoopIterationDispatchPayload as e, LoopIterationEndedPayload as f, LoopIterationStartedPayload as g, LoopPlanDescription as h, LoopPlanPayload as i, LoopSandboxPlacement as j, LoopStartedPayload as k, LoopTokenUsage as l, LoopTraceEmitter as m, LoopTraceEvent as n, ValidationCtx as o };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-runtime",
-  "version": "0.32.0",
+  "version": "0.34.0",
   "description": "Reusable runtime lifecycle for domain-specific agents.",
   "homepage": "https://github.com/tangle-network/agent-runtime#readme",
   "repository": {
@@ -60,11 +60,22 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "skills"
   ],
   "publishConfig": {
     "access": "public"
   },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "prepare": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "biome check src tests examples",
+    "lint:fix": "biome check --write src tests examples",
+    "typecheck": "tsc --noEmit"
+  },
   "dependencies": {},
   "devDependencies": {
     "@biomejs/biome": "^2.4.0",
@@ -75,10 +86,20 @@
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"
   },
+  "pnpm": {
+    "minimumReleaseAge": 4320,
+    "minimumReleaseAgeExclude": [
+      "@tangle-network/agent-eval"
+    ],
+    "onlyBuiltDependencies": [
+      "esbuild"
+    ]
+  },
   "engines": {
     "node": ">=20"
   },
   "license": "MIT",
+  "packageManager": "pnpm@10.28.0",
   "peerDependencies": {
     "@tangle-network/agent-eval": ">=0.61.0 <1.0.0",
     "@tangle-network/agent-knowledge": ">=1.3.0 <2.0.0",
@@ -91,14 +112,5 @@
     "@tangle-network/sandbox": {
       "optional": true
     }
-  },
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "lint": "biome check src tests examples",
-    "lint:fix": "biome check --write src tests examples",
-    "typecheck": "tsc --noEmit"
   }
-}
+}