@tangle-network/agent-runtime 0.33.0 → 0.34.0

package/dist/loops.d.ts

@@ -1,7 +1,7 @@
 import { AgentProfile, SandboxEvent } from '@tangle-network/sandbox';
 export { AgentProfile, CreateSandboxOptions, SandboxEvent, SandboxInstance } from '@tangle-network/sandbox';
-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-CpCX1pfx.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-CpCX1pfx.js';
+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';
@@ -316,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.
  *
@@ -414,4 +379,39 @@ declare function loopCampaignDispatch<Task, Output, Decision, TScenario extends
     toLoopOptions: (scenario: TScenario) => LoopOptionsForDispatch<Task, Output, Decision>;
 }): DispatchFn<TScenario, TArtifact>;
 
+/**
+ * Bridge a finished `runLoop` into an agent-eval campaign / profile-matrix
+ * dispatch.
+ *
+ * `runProfileMatrix` (and `runCampaign`) run the backend-integrity guard over
+ * the token usage a dispatch reports through `ctx.cost`. A dispatch that wraps
+ * `runLoop` must forward the loop's cost AND token usage, or the guard reads
+ * the run as a stub and throws. `reportLoopUsage` is that one line:
+ *
+ *   const dispatch: ProfileDispatchFn<S, A> = async (profile, scenario, ctx) => {
+ *     const result = await runLoop({ ...optsFor(profile, scenario), ctx: loopCtx })
+ *     reportLoopUsage(ctx, result)
+ *     return result.winner?.output as A
+ *   }
+ *
+ * Typed structurally against the campaign `DispatchContext.cost` so this module
+ * stays free of an agent-eval import — it works with any cost meter exposing
+ * `observe` + `observeTokens`.
+ */
+
+/** The slice of an agent-eval campaign `DispatchContext.cost` this needs. */
+interface UsageSink {
+    observe(amountUsd: number, source: string): void;
+    observeTokens(usage: {
+        input: number;
+        output: number;
+    }): void;
+}
+/**
+ * Forward a `LoopResult`'s aggregated cost + token usage into a campaign cost
+ * meter so the backend-integrity guard sees real LLM activity. `source`
+ * defaults to `'loop'`.
+ */
+declare function reportLoopUsage<Task, Output, Decision>(cost: UsageSink, result: Pick<LoopResult<Task, Output, Decision>, 'costUsd' | 'tokenUsage'>, source?: string): void;
+
 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

@@ -8,7 +8,7 @@ import {
   reportLoopUsage,
   runLoop,
   summarizeHistory
-} from "./chunk-GLTUUKTN.js";
+} from "./chunk-7KS6UEHB.js";
 import {
   createFanoutVoteDriver,
   scoreFanoutVoteIterations

package/dist/mcp/bin.js

@@ -3,12 +3,12 @@ import {
   createDefaultCoderDelegate,
   createMcpServer,
   detectExecutor
-} from "../chunk-AAJVQRPL.js";
+} from "../chunk-VVHX5RKE.js";
 import "../chunk-HSX6PFZR.js";
 import "../chunk-GLR25NG7.js";
 import {
   runLoop
-} from "../chunk-GLTUUKTN.js";
+} from "../chunk-7KS6UEHB.js";
 import "../chunk-5QVVET72.js";
 import "../chunk-PY6NMZYX.js";
 import "../chunk-SQSCRJ7U.js";

package/dist/mcp/index.d.ts

@@ -1,10 +1,10 @@
-import { L as LoopSandboxClient, h as LoopSandboxPlacement, k as LoopTraceEmitter } from '../types-CpCX1pfx.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-AAJVQRPL.js";
+} from "../chunk-VVHX5RKE.js";
 import {
+  buildLoopOtelSpans,
   createOtelExporter,
-  loopEventToOtelSpan,
   mcpToolsForRuntimeMcp,
   mcpToolsForRuntimeMcpSubset
-} from "../chunk-RO7K6JNF.js";
+} from "../chunk-Q4ZDSLBD.js";
 import {
   DELEGATE_CODE_DESCRIPTION,
   DELEGATE_CODE_INPUT_SCHEMA,
@@ -50,7 +50,7 @@ import {
 import {
   runLocalHarness
 } from "../chunk-GLR25NG7.js";
-import "../chunk-GLTUUKTN.js";
+import "../chunk-7KS6UEHB.js";
 import "../chunk-5QVVET72.js";
 import "../chunk-PY6NMZYX.js";
 import "../chunk-SQSCRJ7U.js";
@@ -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-CpCX1pfx.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/{types-CpCX1pfx.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, 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, 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.33.0",
+  "version": "0.34.0",
   "description": "Reusable runtime lifecycle for domain-specific agents.",
   "homepage": "https://github.com/tangle-network/agent-runtime#readme",
   "repository": {
@@ -60,7 +60,8 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "skills"
   ],
   "publishConfig": {
     "access": "public"

package/skills/agent-runtime-adoption/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: agent-runtime-adoption
+description: Adopt @tangle-network/agent-runtime in a product — the driven-loop kernel (runLoop), topology drivers (refine / fanout-vote / dynamic agent-authored), the loopDispatch campaign bridge, MCP delegation, and identity-gated prompt-surface optimization (optimizePrompt). Self-contained; needs only the published package + @tangle-network/agent-eval. Use when wiring runLoop, choosing a topology driver, optimizing a system/planner prompt, or exposing delegation tools.
+---
+
+# agent-runtime adoption — driven loops, topology drivers, prompt optimization
+
+`@tangle-network/agent-runtime` is the task-lifecycle skeleton: it owns the loop
+kernel and orchestration seams; it delegates domain behavior (models, tools,
+scoring) to adapters you supply. It depends on `@tangle-network/agent-eval`
+(substrate); never the reverse. This skill is self-contained — you need only the
+two published packages.
+
+## Principle
+
+The kernel owns iteration accounting, concurrency, abort, cost/token aggregation,
+and trace emission. It does NOT own *what the agent runs* (sandbox SDK + profile),
+*how output is decoded* (output adapter), *how it's scored* (validator), or
+*topology* (driver). Keep those four as injected seams — do not fork the kernel.
+
+**Fail loud.** External-boundary calls return typed outcomes; a `null` sandbox
+client, a `null` output adapter return, or a malformed planner move must throw,
+never silently produce a `{0,0}` cell the integrity guard reads as a stub.
+
+## The Driver seam — `runLoop` + topology
+
+`runLoop({ driver, agentRun | agentRuns, output, validator?, task, ctx })` runs
+each iteration: `driver.plan(task, history) → Task[]` → per task spawn a sandbox
+on an `AgentRunSpec.profile` + `streamPrompt` → `output.parse(events)` →
+`validator?.validate(...)` → `driver.decide(history)`. Terminal decisions:
+`'stop' | 'pick-winner' | 'fail' | 'done'`. Returns
+`LoopResult { decision, iterations, winner, costUsd, tokenUsage }`.
+
+A `Driver<Task, Output, Decision>` is just `plan(task, history) → Task[]`
+(`[task]`→refine, N copies→fanout, `[]`→stop) + `decide(history) → Decision`.
+Topology is data; the kernel is topology-agnostic.
+
+### Three shipped drivers — `@tangle-network/agent-runtime/loops`
+
+- **`createRefineDriver({ maxIterations?, refineTask? })`** — one task/iteration,
+  validator-gated; replay or rewrite the task until valid or capped. Use for
+  incremental patches, document revision, anything monotonic.
+- **`createFanoutVoteDriver({ n, selector? })`** — N parallel attempts in
+  iteration 0, score once, pick the winner (default: highest valid score). Use
+  for multi-harness coder fanout, redundant research with disagreement detection.
+- **`createDynamicDriver({ planner, maxIterations?, maxFanout? })`** — **the
+  agent authors the topology.** `plan`/`decide` are backed by an injected
+  `TopologyPlanner` that emits one `TopologyMove` per round
+  (`{kind:'refine',task}` | `{kind:'fanout',tasks}` | `{kind:'stop'}`). The
+  planner is invoked once per round in `plan()`; `decide()` reads the cached move
+  so an LLM planner is never double-called. Use when the right shape is
+  task-dependent (scout-then-fanout, refine-then-branch, decompose).
+
+Topology is **orthogonal to harness**: a driver returns `Task[]`; the kernel
+round-robins `agentRuns[]` to decide which harness (claude-code / codex /
+opencode / pi) runs each branch. One driver spans all backends, including
+fanning a single round across several.
+
+### Wiring an LLM planner — `createSandboxPlanner`
+
+```ts
+import { createDynamicDriver, createSandboxPlanner, runLoop } from '@tangle-network/agent-runtime/loops'
+
+const planner = createSandboxPlanner<Task, Out>({
+  client, profile: plannerProfile,          // any harness; cheap model is fine
+  decodeTask: (raw) => raw as Task,          // envelope task → domain Task
+  // buildPrompt?  — defaults to a history-summary prompt; override to customize
+})
+const result = await runLoop({
+  driver: createDynamicDriver({ planner, maxIterations: 8 }),
+  agentRuns: workerSpecs, output, validator, task, ctx: { sandboxClient: client },
+})
+```
+
+The planner emits a JSON envelope (`{ kind, tasks?, n?, rationale }`); a missing,
+unparseable, or unknown-kind envelope throws `PlannerError` — the loop never runs
+a topology nobody chose.
+
+### Driver gotchas
+
+- `runLoop` validates `ctx.sandboxClient.create` exists or throws
+  `ValidationError`. Never stub a `null` client.
+- The kernel emits `loop.started / iteration.dispatch / iteration.ended /
+  decision / ended` via `ctx.traceEmitter`. Wire it to the same OTLP sink as the
+  chat path so loop telemetry is queryable.
+- The output adapter MUST return a typed value or throw. A `null`/`undefined`
+  return silently drops the iteration from scoring.
+- Dynamic driver: set the kernel's `runLoop` `maxIterations >=` the driver's so
+  the driver's cap governs and the loop closes on a clean `'done'`.
+
+## Campaign bridge — `loopDispatch` / `loopCampaignDispatch`
+
+To run `runLoop` as an agent-eval campaign cell, do NOT hand-build the ExecCtx +
+forward trace + report usage every time (the third is silent — forgetting it
+yields a `{0,0}` cell `assertRealBackend` reads as a stub). Use the adapter:
+
+```ts
+import { loopCampaignDispatch } from '@tangle-network/agent-runtime/loops'
+const dispatch = loopCampaignDispatch({
+  sandboxClient,
+  toLoopOptions: (scenario) => ({ driver, agentRun, output, validator, task: toTask(scenario) }),
+  // toArtifact? — defaults to result.winner?.output
+})
+// pass `dispatch` to runCampaign / runEvalCampaign; usage + trace are auto-forwarded
+```
+
+`loopDispatch` is the `runProfileMatrix` variant (profile is an axis).
+
+## Identity-gated prompt optimization — `optimizePrompt`
+
+`@tangle-network/agent-runtime/improvement`. The text-surface entry point onto
+agent-eval's `runImprovementLoop` — sibling to `improvementDriver` (the
+code/worktree path). Optimizes any prompt surface (system / planner / judge
+rubric) and is **identity-gated by construction**: it runs evals, proposes
+candidates (default driver `gepaDriver`), and the held-out gate compares
+candidate vs baseline. `result.prompt` is the **baseline unless the gate decided
+`'ship'`** — so registering a prompt for optimization can never regress it; it
+only improves when held-out data earns it.
+
+```ts
+import { optimizePrompt } from '@tangle-network/agent-runtime/improvement'
+const { prompt, improved, decision, delta } = await optimizePrompt({
+  baselinePrompt: CURRENT_SYSTEM_PROMPT,
+  runWithPrompt: (prompt, scenario, ctx) => runYourThing(prompt, scenario),  // sandbox / runLoop / direct call
+  scenarios, holdoutScenarios, judges, runDir,
+  reflection: { llm, model: REFLECTION_MODEL },   // builds the default gepaDriver
+  // gate? — defaults to heldOutGate; pass defaultProductionGate for red-team hardening
+})
+// use `prompt` unconditionally: it's the baseline until a candidate genuinely wins
+```
+
+### optimizePrompt gotchas — read before wiring
+
+- **`gepaDriver` mutates TEXT only**, and its only structural guard is `##` H2
+  headings (`preserveSections`) + `maxSentenceEdits`. Make load-bearing sections
+  of your prompt real `##` headings, and treat the output schema as fixed code —
+  GEPA optimizes the prose, never the envelope/contract.
+- **Scenarios must be domain-real.** Derive them from the surface's own traces /
+  ground truth, not from unrelated corpora. Cross-domain examples are noise.
+- **Extend, don't fork.** If the product already wires `runImprovementLoop`
+  (e.g. for a main-agent prompt), add the new surface as another target in that
+  harness rather than bolting on a second optimizer.
+- `runWithPrompt` is the only domain seam — the optimizer never assumes how a
+  prompt runs. Report cost via `ctx.cost` inside it so the integrity guard sees
+  real activity.
+- A live run needs a real backend (`TANGLE_API_KEY` / router, or local
+  cli-bridge) and real spend; it is not free.
+
+## MCP delegation — `@tangle-network/agent-runtime/mcp`
+
+`agent-runtime-mcp` (stdio) exposes delegation tools (`delegate_code`,
+`delegate_research`, …) that drive `runLoop` behind the scenes (refine or
+fanout-vote per `variants`). Env: `TANGLE_API_KEY`, `SANDBOX_BASE_URL`,
+`TANGLE_FLEET_ID` (sibling vs fleet placement), `MCP_CODER_FANOUT_HARNESSES`.
+Mount it on a production `AgentProfile.mcp`; do not re-implement delegation.
+
+## Acceptance checklist
+
+- [ ] Topology is a `Driver`, not hard-coded control flow. Reuse refine /
+      fanout-vote / dynamic; build a custom `Driver` against
+      `loops/types.ts:Driver` only when none fit — never fork the kernel.
+- [ ] `runLoop` is bridged to campaigns via `loopDispatch` / `loopCampaignDispatch`
+      (usage + trace auto-forwarded), not a hand-rolled ExecCtx.
+- [ ] Every optimizable prompt is registered through `optimizePrompt` (or the
+      product's existing `runImprovementLoop`), identity-gated on a held-out set.
+- [ ] Boundaries fail loud: no `null` sandbox client, no silent adapter return,
+      no unguarded planner envelope.
+
+For the full self-improving pipeline (trace sink → analyst loop → scorecard →
+production loop → CI), see the broader `agent-eval-adoption` skill.