@tangle-network/agent-app 0.10.1 → 0.11.1

package/dist/index.js

@@ -17,9 +17,10 @@ import {
   parseMissionBlocks,
   parseSessionStreamEnvelope,
   reduceMissionEvents,
+  stepAgentActivity,
   stepGateProposalId,
   volumeGateProposalId
-} from "./chunk-UIWB2F6N.js";
+} from "./chunk-UDXMR3AD.js";
 import {
   addSecurityHeaders,
   checkRateLimit,
@@ -38,6 +39,22 @@ import {
   redactForIngestion,
   revealSpan
 } from "./chunk-5RMIUJDI.js";
+import {
+  buildFlowTrace,
+  childSpanContext,
+  createMissionTraceContext,
+  renderHistogram,
+  renderWaterfall,
+  summarize,
+  timedEventsFromLines,
+  traceEnv
+} from "./chunk-5RT6KY4G.js";
+import {
+  composeMissionFlowTrace,
+  delegationActivityToFlowSpans,
+  loopTraceEventsToFlowSpans,
+  stepActivityFlowTrace
+} from "./chunk-AFDROJ64.js";
 import {
   ApprovalEventSchema,
   BrandTokensSchema,
@@ -74,12 +91,12 @@ import {
   createPresetToolHandlers,
   createPresetWorkspaceKeyManager,
   createPresetWorkspaceKeyStore
-} from "./chunk-EYXTDVDY.js";
+} from "./chunk-SAOAAA3S.js";
 import {
   createPlatformBalanceManager,
   createTcloudKeyProvisioner,
   createWorkspaceKeyManager
-} from "./chunk-YS6A6G57.js";
+} from "./chunk-G3HCU7TA.js";
 import {
   createFieldCrypto,
   decodeHexKey,
@@ -228,14 +245,17 @@ export {
   buildCatalog,
   buildConsentUrl,
   buildDelegationMcpServer,
+  buildFlowTrace,
   buildHttpMcpServer,
   buildKnowledgeRequirements,
   buildRedactedDocument,
   buildUserTextParts,
   checkRateLimit,
+  childSpanContext,
   clearCookieHeader,
   coalesceDeltas,
   coerceHarness,
+  composeMissionFlowTrace,
   createAgentRuntime,
   createAppToolRuntimeExecutor,
   createBrokerTokenProvider,
@@ -249,6 +269,7 @@ export {
   createMemoryTurnEventStore,
   createMissionEngine,
   createMissionService,
+  createMissionTraceContext,
   createOpenAICompatStreamTurn,
   createPlatformBalanceManager,
   createPresetDrizzleSchema,
@@ -266,6 +287,7 @@ export {
   decryptBytes,
   decryptWithKey,
   defineAgentApp,
+  delegationActivityToFlowSpans,
   delegationMcpForConfig,
   deriveKey,
   deriveSignals,
@@ -288,6 +310,7 @@ export {
   isMissionTerminal,
   isTangleBillingEnforcementDisabled,
   isTangleExecutionKeyError,
+  loopTraceEventsToFlowSpans,
   maskSpans,
   mergeMissionState,
   mergePersistedPart,
@@ -309,6 +332,8 @@ export {
   readToolArgs,
   redactForIngestion,
   reduceMissionEvents,
+  renderHistogram,
+  renderWaterfall,
   replayTurnEvents,
   requireString,
   resolveChatTurn,
@@ -325,10 +350,15 @@ export {
   runAppToolLoop,
   safeParseAssetSpec,
   serializeCookie,
+  stepActivityFlowTrace,
+  stepAgentActivity,
   stepGateProposalId,
   streamAppToolLoop,
+  summarize,
   tangleExecutionKeyHttpError,
+  timedEventsFromLines,
   toLoopEvents,
+  traceEnv,
   verifyCapabilityToken,
   verifyCompletion,
   volumeGateProposalId,

package/dist/missions/index.d.ts

@@ -1,3 +1,6 @@
+import { S as StepAgentActivity } from '../agent-activity-C8ZG0F0M.js';
+export { W as WithAgentActivity, s as stepAgentActivity } from '../agent-activity-C8ZG0F0M.js';
+
 /**
  * Durable mission state — the guarded status machine for a multi-step agent run.
  *
@@ -130,7 +133,11 @@ interface MissionAuditEvent {
  */
 interface MissionStorePort {
     load(id: string): Promise<MissionRecord | null>;
-    insert(record: MissionRecord): Promise<MissionRecord>;
+    /** `extras` are the opaque product-column values from
+     *  `CreateMissionInput.extras` — write them in the SAME statement as the
+     *  record (single-write creation) or ignore them if the table has no extra
+     *  columns. */
+    insert(record: MissionRecord, extras?: Record<string, unknown>): Promise<MissionRecord>;
     update(id: string, guard: MissionUpdateGuard, patch: MissionUpdatePatch): Promise<MissionRecord | null>;
     appendEvent(event: MissionAuditEvent): Promise<void>;
 }
@@ -160,6 +167,13 @@ interface CreateMissionInput {
      *  model). Read back via `mission.metadata`; the engine only reads
      *  `stopRequested` from it. */
     metadata?: Record<string, unknown> | null;
+    /**
+     * Opaque product-column values handed VERBATIM to `MissionStorePort.insert`
+     * (e.g. a `workflowId` FK on the product's mission table), so creation is a
+     * single write — no post-insert stamp. The service never reads, validates,
+     * or persists them itself; they exist only on the insert call.
+     */
+    extras?: Record<string, unknown>;
 }
 interface SetStepStatusPatch {
     sublabel?: string;
@@ -204,8 +218,14 @@ interface MissionServiceOptions {
     store: MissionStorePort;
     /** Injectable clock (epoch ms). Default `Date.now`. */
     now?: () => number;
-    /** Row-id generator when `CreateMissionInput.id` is omitted.
-     *  Default `crypto.randomUUID`. */
+    /**
+     * Row-id generator when `CreateMissionInput.id` is omitted. Default
+     * `crypto.randomUUID()` — a 36-char dashed UUID. Inject your own when your
+     * mission table already has an id shape (e.g. 32-hex matching D1 row
+     * defaults): the service stamps the generated id verbatim onto the inserted
+     * record, so a mismatch with the rest of your schema surfaces only at the
+     * product layer. Keep id shape parity here, not in the store.
+     */
     generateId?: () => string;
 }
 declare function createMissionService(options: MissionServiceOptions): MissionService;
@@ -243,6 +263,7 @@ declare function createInMemoryMissionStore(): InMemoryMissionStore;
  *     idempotent + order-tolerant, so a re-sent or duplicated event converges.
  *     The sink itself does no dedupe.
  */
+
 interface MissionEventSink {
     emit(event: MissionStreamEvent): void;
 }
@@ -291,7 +312,14 @@ type MissionStreamEvent = {
     missionId: string;
     at: number;
     stepId: string;
-    sublabel: string;
+    sublabel?: string;
+    /**
+     * Full CURRENT snapshot of the step's delegated runs — never a delta.
+     * The reducer replaces the whole lane (latest snapshot wins by `at`), so
+     * emitters re-send everything they know each time and at-least-once /
+     * out-of-order delivery converges.
+     */
+    agentActivity?: StepAgentActivity[];
 } | {
     type: 'step.completed';
     missionId: string;
@@ -360,6 +388,11 @@ interface MissionStepState {
     sublabel?: string;
     reason?: string;
     durationMs?: number;
+    /** Latest delegated-run snapshot for the step (see `step.updated`). */
+    agentActivity?: StepAgentActivity[];
+    /** The `at` of the snapshot currently held — an older snapshot arriving
+     *  late never replaces a newer one. */
+    agentActivityAt?: number;
 }
 /** Live per-mission view the reducer folds events into. */
 interface MissionState {
@@ -695,4 +728,4 @@ declare function parseMissionBlocks(fullContent: string, options?: ParseMissionB
  */
 declare function buildAgentMissionPlan(steps: ParsedMissionStep[]): MissionStep[];
 
-export { type CompleteMissionInput, type CreateMissionInput, DEFAULT_MISSION_STEP_KINDS, type InMemoryMissionStore, MISSION_CONTROL_CHANNEL_ID, type MissionApprovalsPort, type MissionAuditEvent, MissionConcurrencyError, type MissionCostLedger, type MissionEngine, type MissionEngineOptions, type MissionEventSink, type MissionGateKind, type MissionGateOptions, type MissionGateProposal, type MissionOutcome, type MissionPlanRunOptions, type MissionProposalResolution, type MissionRecord, type MissionService, type MissionServiceOptions, type MissionState, type MissionStatus, type MissionStep, type MissionStepState, type MissionStepStatus, type MissionStorePort, type MissionStreamEvent, type MissionStreamStatus, type MissionStreamStep, type MissionStreamStepStatus, type MissionUpdateGuard, type MissionUpdatePatch, type ParseMissionBlocksOptions, type ParsedMission, type ParsedMissionStep, type PlanOutcome, RetryableStepError, type SandboxDispatch, type SandboxDispatchDoneResult, type SandboxDispatchInProgressResult, type SandboxDispatchInput, type SandboxDispatchResult, type SetStepStatusPatch, type StepGateClassification, type StepOutcome, applyMissionEvent, asMissionStreamEvent, budgetGateProposalId, buildAgentMissionPlan, createInMemoryMissionStore, createMissionEngine, createMissionService, isMissionStopRequested, isMissionTerminal, mergeMissionState, noopEventSink, parseMissionBlocks, parseSessionStreamEnvelope, reduceMissionEvents, stepGateProposalId, volumeGateProposalId };
+export { type CompleteMissionInput, type CreateMissionInput, DEFAULT_MISSION_STEP_KINDS, type InMemoryMissionStore, MISSION_CONTROL_CHANNEL_ID, type MissionApprovalsPort, type MissionAuditEvent, MissionConcurrencyError, type MissionCostLedger, type MissionEngine, type MissionEngineOptions, type MissionEventSink, type MissionGateKind, type MissionGateOptions, type MissionGateProposal, type MissionOutcome, type MissionPlanRunOptions, type MissionProposalResolution, type MissionRecord, type MissionService, type MissionServiceOptions, type MissionState, type MissionStatus, type MissionStep, type MissionStepState, type MissionStepStatus, type MissionStorePort, type MissionStreamEvent, type MissionStreamStatus, type MissionStreamStep, type MissionStreamStepStatus, type MissionUpdateGuard, type MissionUpdatePatch, type ParseMissionBlocksOptions, type ParsedMission, type ParsedMissionStep, type PlanOutcome, RetryableStepError, type SandboxDispatch, type SandboxDispatchDoneResult, type SandboxDispatchInProgressResult, type SandboxDispatchInput, type SandboxDispatchResult, type SetStepStatusPatch, StepAgentActivity, type StepGateClassification, type StepOutcome, applyMissionEvent, asMissionStreamEvent, budgetGateProposalId, buildAgentMissionPlan, createInMemoryMissionStore, createMissionEngine, createMissionService, isMissionStopRequested, isMissionTerminal, mergeMissionState, noopEventSink, parseMissionBlocks, parseSessionStreamEnvelope, reduceMissionEvents, stepGateProposalId, volumeGateProposalId };

package/dist/missions/index.js

@@ -17,9 +17,10 @@ import {
   parseMissionBlocks,
   parseSessionStreamEnvelope,
   reduceMissionEvents,
+  stepAgentActivity,
   stepGateProposalId,
   volumeGateProposalId
-} from "../chunk-UIWB2F6N.js";
+} from "../chunk-UDXMR3AD.js";
 export {
   DEFAULT_MISSION_STEP_KINDS,
   MISSION_CONTROL_CHANNEL_ID,
@@ -39,6 +40,7 @@ export {
   parseMissionBlocks,
   parseSessionStreamEnvelope,
   reduceMissionEvents,
+  stepAgentActivity,
   stepGateProposalId,
   volumeGateProposalId
 };

package/dist/preset-cloudflare/index.js

@@ -7,8 +7,8 @@ import {
   createPresetToolHandlers,
   createPresetWorkspaceKeyManager,
   createPresetWorkspaceKeyStore
-} from "../chunk-EYXTDVDY.js";
-import "../chunk-YS6A6G57.js";
+} from "../chunk-SAOAAA3S.js";
+import "../chunk-G3HCU7TA.js";
 import "../chunk-TA5Q4I2K.js";
 export {
   PRESET_MIGRATION_SQL,

package/dist/trace/index.d.ts

@@ -1,3 +1,138 @@
+import { S as StepAgentActivity } from '../agent-activity-C8ZG0F0M.js';
+
+/**
+ * Mission trace context — mint + thread the trace ids that join a mission's
+ * step attempts and its delegated agent runs into ONE trace tree.
+ *
+ * ID formats are byte-compatible with agent-runtime's trace propagation
+ * (`readTraceContextFromEnv` / OTLP export): 32 lowercase hex chars for a
+ * trace id (16 bytes), 16 for a span id (8 bytes). The env pair from
+ * {@link traceEnv} is exactly what agent-runtime's MCP subprocess reads at
+ * startup (`TRACE_ID` + `PARENT_SPAN_ID`), so a delegation dispatched with it
+ * parents its loop→round→iteration spans under the mission's step span.
+ *
+ * Pure functions, no deps. Ids are DETERMINISTIC when a key is supplied
+ * (missionId / step-attempt seed) so a crashed driver re-mints the identical
+ * context on re-dispatch and the re-run joins the same trace instead of
+ * forking a new one; without a key they are random.
+ */
+interface MissionTraceContext {
+    /** 32-hex trace id shared by every span in the mission's tree. */
+    traceId: string;
+    /** 16-hex span id of the mission root — the parent of every step span. */
+    rootSpanId: string;
+}
+interface StepSpanContext {
+    traceId: string;
+    /** 16-hex span id of this step attempt (or any nested unit of work). */
+    spanId: string;
+    /** The span this one nests under. */
+    parentSpanId: string;
+}
+/**
+ * Mint a mission's trace context. With `missionId` the ids are a pure
+ * function of it; omitted, both ids are random.
+ */
+declare function createMissionTraceContext(missionId?: string): MissionTraceContext;
+/**
+ * Derive a child span context under `parent` — one per step attempt (seed
+ * e.g. `"${stepId}#${attempt}"`), or nested under another step span. With a
+ * seed the span id is deterministic for the same parent + seed; omitted, it
+ * is random.
+ */
+declare function childSpanContext(parent: MissionTraceContext | StepSpanContext, seed?: string): StepSpanContext;
+/**
+ * The env pair a delegation subprocess inherits — agent-runtime's
+ * `readTraceContextFromEnv` reads exactly these names. `PARENT_SPAN_ID` is
+ * the span the dispatched work nests under: the root for a mission context,
+ * the step-attempt span for a step context.
+ */
+declare function traceEnv(ctx: MissionTraceContext | StepSpanContext): {
+    TRACE_ID: string;
+    PARENT_SPAN_ID: string;
+};
+
+/**
+ * Delegation → FlowSpan converters — render what a mission's delegated agent
+ * runs actually did as ONE FlowTrace, drawable by the existing
+ * `renderWaterfall` (or any viewer that consumes FlowSpans).
+ *
+ * Two fidelities, one tree:
+ *  - COARSE: `delegationActivityToFlowSpans` draws one 'tool' span per
+ *    delegation from the StepAgentActivity snapshot (startedAt/durationMs) —
+ *    available live, from the step's journaled lane.
+ *  - FINE: `loopTraceEventsToFlowSpans` reconstructs agent-runtime's
+ *    loop → round → iteration hierarchy from the LoopTraceEvent journal a
+ *    delegation persists. FlowSpans carry no parent ids, so nesting rides the
+ *    span NAME (`loop ▸ round 0 ▸ iter 1 (coder)`), matching how the ASCII
+ *    waterfall reads.
+ *
+ * `composeMissionFlowTrace` lays a whole mission out: one 'pipeline' span per
+ * step, each step's delegations beneath it. Pure data transforms — the
+ * structural `LoopTraceEventLike` keeps this module free of the optional
+ * agent-runtime peer.
+ */
+
+/** Structural mirror of agent-runtime's `LoopTraceEvent` — same fields, no
+ *  import, so journals parsed from JSON feed straight in. */
+interface LoopTraceEventLike {
+    kind: string;
+    runId: string;
+    /** Epoch ms. */
+    timestamp: number;
+    payload: object;
+}
+/**
+ * One 'tool' FlowSpan per delegation, positioned relative to `turnStartMs`
+ * (the epoch-ms origin of the trace — usually the step or mission start).
+ * A row whose `startedAt` does not parse cannot be placed on a timeline and
+ * is omitted from the WATERFALL (it stays in the lane itself). A run without
+ * `durationMs` is still in flight: its span extends to `opts.nowMs` when
+ * given, else renders as a point — `approx` flags both.
+ */
+declare function delegationActivityToFlowSpans(activity: StepAgentActivity[], turnStartMs: number, opts?: {
+    nowMs?: number;
+}): FlowSpan[];
+/**
+ * Reconstruct one delegation's loop → round → iteration tree from its
+ * journaled LoopTraceEvents, as FlowSpans relative to `loop.started` (or the
+ * first event). Mirrors agent-runtime's `buildLoopOtelSpans` topology:
+ * rounds open on `loop.plan` and flush on the next plan / `loop.decision` /
+ * `loop.ended`; iterations span `loop.iteration.started` → `.ended`.
+ */
+declare function loopTraceEventsToFlowSpans(events: LoopTraceEventLike[]): FlowSpan[];
+/**
+ * A single step's activity lane as its own FlowTrace — what a per-step
+ * drill-in renders. Origin defaults to the earliest delegation start so the
+ * waterfall begins at the lane's first run.
+ */
+declare function stepActivityFlowTrace(activity: StepAgentActivity[], opts?: {
+    startedAt?: number;
+    nowMs?: number;
+}): FlowTrace;
+interface MissionFlowStep {
+    id: string;
+    intent: string;
+    status?: string;
+    /** Epoch ms the step attempt started. Absent → laid out sequentially after
+     *  the previous step (missions run steps in order), `approx` flagged. */
+    startedAt?: number;
+    durationMs?: number;
+}
+/**
+ * Compose a mission-wide FlowTrace: one 'pipeline' span per step, the step's
+ * delegated runs ('tool' spans, from `activity[stepId]`) beneath it. A step
+ * span always covers its delegations' extent. Cost is the sum of delegation
+ * `costUsd`; token counts are not knowable from the activity lane and stay 0.
+ */
+declare function composeMissionFlowTrace(input: {
+    steps: MissionFlowStep[];
+    /** Delegated-run snapshots keyed by step id (the step's `agentActivity`). */
+    activity?: Record<string, StepAgentActivity[]>;
+    /** Epoch-ms origin. Default: the earliest known step/delegation start. */
+    startedAt?: number;
+}): FlowTrace;
+
 /**
  * `@tangle-network/agent-app/trace` — flow observability for agent turns.
  *
@@ -13,6 +148,7 @@
  * pump's flush window and the reader's poll cadence (~100–400ms); spans
  * carry `approx: true` to keep reports honest about that.
  */
+
 interface TimedEvent {
     /** ms since turn start (`_t` stamped by pumpBufferedTurn). */
     t: number;
@@ -68,4 +204,4 @@ declare function renderHistogram(values: number[], opts?: {
     format?: (v: number) => string;
 }): string;
 
-export { type DistributionSummary, type FlowSpan, type FlowTrace, type TimedEvent, buildFlowTrace, renderHistogram, renderWaterfall, summarize, timedEventsFromLines };
+export { type DistributionSummary, type FlowSpan, type FlowTrace, type LoopTraceEventLike, type MissionFlowStep, type MissionTraceContext, type StepSpanContext, type TimedEvent, buildFlowTrace, childSpanContext, composeMissionFlowTrace, createMissionTraceContext, delegationActivityToFlowSpans, loopTraceEventsToFlowSpans, renderHistogram, renderWaterfall, stepActivityFlowTrace, summarize, timedEventsFromLines, traceEnv };

package/dist/trace/index.js

@@ -1,145 +1,31 @@
-// src/trace/index.ts
-function timedEventsFromLines(lines) {
-  const out = [];
-  for (const line of lines) {
-    try {
-      const parsed = JSON.parse(line);
-      if (typeof parsed._t === "number") out.push({ t: parsed._t, event: parsed });
-    } catch {
-    }
-  }
-  return out.sort((a, b) => a.t - b.t);
-}
-function innerOf(e) {
-  return (e.kind === "event" ? e.event : e) ?? {};
-}
-function buildFlowTrace(events, opts) {
-  const spans = [];
-  let promptTokens = 0;
-  let completionTokens = 0;
-  let toolCalls = 0;
-  const first = events[0]?.t ?? 0;
-  if (first > 0) {
-    spans.push({ kind: "pipeline", name: "dispatch \u2192 first event", startMs: 0, endMs: first });
-  }
-  let segStart = null;
-  let segEnd = 0;
-  let segKinds = /* @__PURE__ */ new Set();
-  let lastDeltaT = first;
-  const openCalls = /* @__PURE__ */ new Map();
-  const closeSegment = () => {
-    if (segStart !== null) {
-      spans.push({
-        kind: "model",
-        name: segKinds.has("reasoning") ? "model turn (reasoning + text)" : "model turn",
-        startMs: segStart,
-        endMs: segEnd,
-        approx: true
-      });
-      segStart = null;
-      segKinds = /* @__PURE__ */ new Set();
-    }
-  };
-  for (const { t, event } of events) {
-    const inner = innerOf(event);
-    const type = String(event.kind === "tool_result" ? "tool_result" : inner.type ?? "");
-    if (type === "text" || type === "reasoning") {
-      if (segStart === null) segStart = t;
-      segEnd = t;
-      segKinds.add(type);
-      lastDeltaT = t;
-    } else if (type === "tool_call") {
-      closeSegment();
-      toolCalls++;
-      const call = inner.call ?? inner;
-      const id = String(call.toolCallId ?? `call_${toolCalls}`);
-      openCalls.set(id, { name: String(call.toolName ?? "tool"), emitT: t, lastDeltaT });
-    } else if (type === "tool_result") {
-      const id = String(event.toolCallId ?? inner.toolCallId ?? "");
-      const open = openCalls.get(id);
-      if (open) {
-        spans.push({
-          kind: "tool",
-          name: open.name,
-          // Execution happens between the end of the model turn that emitted
-          // the call and the result landing in the buffer.
-          startMs: open.lastDeltaT,
-          endMs: t,
-          approx: true,
-          meta: { ok: (event.outcome ?? inner.outcome)?.ok }
-        });
-        openCalls.delete(id);
-      }
-    } else if (type === "usage") {
-      const u = inner.usage ?? {};
-      promptTokens += u.promptTokens ?? 0;
-      completionTokens += u.completionTokens ?? 0;
-    }
-  }
-  closeSegment();
-  const totalMs = events.length ? events[events.length - 1].t : 0;
-  const trace = { spans, totalMs, promptTokens, completionTokens, toolCalls };
-  const p = opts?.pricing;
-  if (p && (p.prompt != null || p.completion != null)) {
-    trace.costUsd = promptTokens * Number(p.prompt ?? 0) + completionTokens * Number(p.completion ?? 0);
-  }
-  return trace;
-}
-var fmtS = (ms) => `${(ms / 1e3).toFixed(1)}s`;
-function renderWaterfall(trace, opts) {
-  const width = opts?.width ?? 40;
-  const scale = trace.totalMs > 0 ? width / trace.totalMs : 0;
-  const lines = [];
-  const spans = [...trace.spans].sort((a, b) => a.startMs - b.startMs);
-  for (let i = 0; i < spans.length; i++) {
-    const s = spans[i];
-    const offset = Math.round(s.startMs * scale);
-    const len = Math.max(1, Math.round((s.endMs - s.startMs) * scale));
-    const bar = " ".repeat(offset) + (s.kind === "tool" ? "\u2593" : s.kind === "pipeline" ? "\u2591" : "\u2588").repeat(len);
-    const branch = i === spans.length - 1 ? "\u2514\u2500" : "\u251C\u2500";
-    const dur = `${fmtS(s.endMs - s.startMs)}${s.approx ? "~" : ""}`;
-    lines.push(`${fmtS(s.startMs).padStart(7)} ${branch} ${bar.padEnd(width + 2)} ${s.name} (${dur})`);
-  }
-  const cost = trace.costUsd != null ? `  $${trace.costUsd.toFixed(trace.costUsd < 0.01 ? 6 : 4)}` : "";
-  lines.push(
-    `${fmtS(trace.totalMs).padStart(7)} \u2500\u2500 total \xB7 ${trace.promptTokens}p + ${trace.completionTokens}c tok \xB7 ${trace.toolCalls} tool calls${cost}`
-  );
-  return lines.join("\n");
-}
-function summarize(values) {
-  const sorted = [...values].sort((a, b) => a - b);
-  const q = (p) => sorted[Math.min(sorted.length - 1, Math.floor(p * sorted.length))] ?? 0;
-  return { n: sorted.length, min: sorted[0] ?? 0, p50: q(0.5), p90: q(0.9), max: sorted[sorted.length - 1] ?? 0 };
-}
-function renderHistogram(values, opts) {
-  if (!values.length) return "(no samples)";
-  const buckets = opts?.buckets ?? 6;
-  const width = opts?.width ?? 24;
-  const fmt = opts?.format ?? ((v) => `${Math.round(v)}${opts?.unit ?? ""}`);
-  const s = summarize(values);
-  const lo = s.min;
-  const hi = s.max === s.min ? s.min + 1 : s.max;
-  const counts = new Array(buckets).fill(0);
-  for (const v of values) {
-    counts[Math.min(buckets - 1, Math.floor((v - lo) / (hi - lo) * buckets))]++;
-  }
-  const maxCount = Math.max(...counts);
-  const lines = [
-    `n=${s.n}  min=${fmt(s.min)}  p50=${fmt(s.p50)}  p90=${fmt(s.p90)}  max=${fmt(s.max)}`
-  ];
-  for (let i = 0; i < buckets; i++) {
-    const a = lo + (hi - lo) * i / buckets;
-    const b = lo + (hi - lo) * (i + 1) / buckets;
-    const bar = "\u2588".repeat(Math.max(counts[i] > 0 ? 1 : 0, Math.round(counts[i] / maxCount * width)));
-    lines.push(`${fmt(a).padStart(8)}-${fmt(b).padEnd(8)} ${bar} ${counts[i]}`);
-  }
-  return lines.join("\n");
-}
+import {
+  buildFlowTrace,
+  childSpanContext,
+  createMissionTraceContext,
+  renderHistogram,
+  renderWaterfall,
+  summarize,
+  timedEventsFromLines,
+  traceEnv
+} from "../chunk-5RT6KY4G.js";
+import {
+  composeMissionFlowTrace,
+  delegationActivityToFlowSpans,
+  loopTraceEventsToFlowSpans,
+  stepActivityFlowTrace
+} from "../chunk-AFDROJ64.js";
 export {
   buildFlowTrace,
+  childSpanContext,
+  composeMissionFlowTrace,
+  createMissionTraceContext,
+  delegationActivityToFlowSpans,
+  loopTraceEventsToFlowSpans,
   renderHistogram,
   renderWaterfall,
+  stepActivityFlowTrace,
   summarize,
-  timedEventsFromLines
+  timedEventsFromLines,
+  traceEnv
 };
 //# sourceMappingURL=index.js.map

package/dist/trace/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/trace/index.ts"],"sourcesContent":["/**\n * `@tangle-network/agent-app/trace` — flow observability for agent turns.\n *\n * The turn buffer stamps `_t` (ms since turn start) on every event, so any\n * live stream OR any historical turn replayed from a TurnEventStore can be\n * reconstructed into a span trace: pipeline overhead, model segments (with\n * thinking TTFT), tool executions, token usage, and cost. Renderers turn\n * traces and multi-run samples into ASCII waterfalls and histograms — the\n * default artifact for \"how did this run actually behave\" questions across\n * evals, hill-climbs, and production debugging.\n *\n * Span boundaries derived from a buffered stream are quantized by the\n * pump's flush window and the reader's poll cadence (~100–400ms); spans\n * carry `approx: true` to keep reports honest about that.\n */\n\nexport interface TimedEvent {\n  /** ms since turn start (`_t` stamped by pumpBufferedTurn). */\n  t: number\n  event: Record<string, unknown>\n}\n\nexport interface FlowSpan {\n  kind: 'pipeline' | 'model' | 'tool'\n  name: string\n  startMs: number\n  endMs: number\n  approx?: boolean\n  meta?: Record<string, unknown>\n}\n\nexport interface FlowTrace {\n  spans: FlowSpan[]\n  totalMs: number\n  promptTokens: number\n  completionTokens: number\n  /** Computed when per-token pricing is supplied. */\n  costUsd?: number\n  toolCalls: number\n}\n\n/** Parse stored turn-event lines (JSON strings with `_t`) into TimedEvents. */\nexport function timedEventsFromLines(lines: string[]): TimedEvent[] {\n  const out: TimedEvent[] = []\n  for (const line of lines) {\n    try {\n      const parsed = JSON.parse(line) as Record<string, unknown>\n      if (typeof parsed._t === 'number') out.push({ t: parsed._t, event: parsed })\n    } catch {\n      /* skip torn lines */\n    }\n  }\n  return out.sort((a, b) => a.t - b.t)\n}\n\nfunction innerOf(e: Record<string, unknown>): Record<string, unknown> {\n  return (e.kind === 'event' ? (e.event as Record<string, unknown>) : e) ?? {}\n}\n\n/**\n * Derive a span trace from timestamped turn events. Model segments are runs\n * of text/reasoning deltas; a tool span opens at the last delta before its\n * tool_call emission and closes at the matching tool_result.\n */\nexport function buildFlowTrace(\n  events: TimedEvent[],\n  opts?: { pricing?: { prompt?: string | number; completion?: string | number } },\n): FlowTrace {\n  const spans: FlowSpan[] = []\n  let promptTokens = 0\n  let completionTokens = 0\n  let toolCalls = 0\n\n  const first = events[0]?.t ?? 0\n  if (first > 0) {\n    spans.push({ kind: 'pipeline', name: 'dispatch → first event', startMs: 0, endMs: first })\n  }\n\n  let segStart: number | null = null\n  let segEnd = 0\n  let segKinds = new Set<string>()\n  let lastDeltaT = first\n  const openCalls = new Map<string, { name: string; emitT: number; lastDeltaT: number }>()\n\n  const closeSegment = () => {\n    if (segStart !== null) {\n      spans.push({\n        kind: 'model',\n        name: segKinds.has('reasoning') ? 'model turn (reasoning + text)' : 'model turn',\n        startMs: segStart,\n        endMs: segEnd,\n        approx: true,\n      })\n      segStart = null\n      segKinds = new Set()\n    }\n  }\n\n  for (const { t, event } of events) {\n    const inner = innerOf(event)\n    const type = String(event.kind === 'tool_result' ? 'tool_result' : (inner.type ?? ''))\n\n    if (type === 'text' || type === 'reasoning') {\n      if (segStart === null) segStart = t\n      segEnd = t\n      segKinds.add(type)\n      lastDeltaT = t\n    } else if (type === 'tool_call') {\n      closeSegment()\n      toolCalls++\n      const call = (inner.call ?? inner) as Record<string, unknown>\n      const id = String(call.toolCallId ?? `call_${toolCalls}`)\n      openCalls.set(id, { name: String(call.toolName ?? 'tool'), emitT: t, lastDeltaT })\n    } else if (type === 'tool_result') {\n      const id = String(event.toolCallId ?? inner.toolCallId ?? '')\n      const open = openCalls.get(id)\n      if (open) {\n        spans.push({\n          kind: 'tool',\n          name: open.name,\n          // Execution happens between the end of the model turn that emitted\n          // the call and the result landing in the buffer.\n          startMs: open.lastDeltaT,\n          endMs: t,\n          approx: true,\n          meta: { ok: ((event.outcome ?? inner.outcome) as { ok?: boolean } | undefined)?.ok },\n        })\n        openCalls.delete(id)\n      }\n    } else if (type === 'usage') {\n      const u = (inner.usage ?? {}) as { promptTokens?: number; completionTokens?: number }\n      promptTokens += u.promptTokens ?? 0\n      completionTokens += u.completionTokens ?? 0\n    }\n  }\n  closeSegment()\n\n  const totalMs = events.length ? events[events.length - 1]!.t : 0\n  const trace: FlowTrace = { spans, totalMs, promptTokens, completionTokens, toolCalls }\n  const p = opts?.pricing\n  if (p && (p.prompt != null || p.completion != null)) {\n    trace.costUsd = promptTokens * Number(p.prompt ?? 0) + completionTokens * Number(p.completion ?? 0)\n  }\n  return trace\n}\n\nconst fmtS = (ms: number) => `${(ms / 1000).toFixed(1)}s`\n\n/** ASCII waterfall cascade — the default artifact for explaining a flow. */\nexport function renderWaterfall(trace: FlowTrace, opts?: { width?: number }): string {\n  const width = opts?.width ?? 40\n  const scale = trace.totalMs > 0 ? width / trace.totalMs : 0\n  const lines: string[] = []\n  const spans = [...trace.spans].sort((a, b) => a.startMs - b.startMs)\n  for (let i = 0; i < spans.length; i++) {\n    const s = spans[i]!\n    const offset = Math.round(s.startMs * scale)\n    const len = Math.max(1, Math.round((s.endMs - s.startMs) * scale))\n    const bar = ' '.repeat(offset) + (s.kind === 'tool' ? '▓' : s.kind === 'pipeline' ? '░' : '█').repeat(len)\n    const branch = i === spans.length - 1 ? '└─' : '├─'\n    const dur = `${fmtS(s.endMs - s.startMs)}${s.approx ? '~' : ''}`\n    lines.push(`${fmtS(s.startMs).padStart(7)} ${branch} ${bar.padEnd(width + 2)} ${s.name} (${dur})`)\n  }\n  const cost = trace.costUsd != null ? `  $${trace.costUsd.toFixed(trace.costUsd < 0.01 ? 6 : 4)}` : ''\n  lines.push(\n    `${fmtS(trace.totalMs).padStart(7)} ── total · ${trace.promptTokens}p + ${trace.completionTokens}c tok · ${trace.toolCalls} tool calls${cost}`,\n  )\n  return lines.join('\\n')\n}\n\nexport interface DistributionSummary {\n  n: number\n  min: number\n  p50: number\n  p90: number\n  max: number\n}\n\nexport function summarize(values: number[]): DistributionSummary {\n  const sorted = [...values].sort((a, b) => a - b)\n  const q = (p: number) => sorted[Math.min(sorted.length - 1, Math.floor(p * sorted.length))] ?? 0\n  return { n: sorted.length, min: sorted[0] ?? 0, p50: q(0.5), p90: q(0.9), max: sorted[sorted.length - 1] ?? 0 }\n}\n\n/** ASCII histogram for multi-run samples (eval latencies, costs, scores). */\nexport function renderHistogram(\n  values: number[],\n  opts?: { buckets?: number; width?: number; unit?: string; format?: (v: number) => string },\n): string {\n  if (!values.length) return '(no samples)'\n  const buckets = opts?.buckets ?? 6\n  const width = opts?.width ?? 24\n  const fmt = opts?.format ?? ((v: number) => `${Math.round(v)}${opts?.unit ?? ''}`)\n  const s = summarize(values)\n  const lo = s.min\n  const hi = s.max === s.min ? s.min + 1 : s.max\n  const counts = new Array<number>(buckets).fill(0)\n  for (const v of values) {\n    counts[Math.min(buckets - 1, Math.floor(((v - lo) / (hi - lo)) * buckets))]!++\n  }\n  const maxCount = Math.max(...counts)\n  const lines = [\n    `n=${s.n}  min=${fmt(s.min)}  p50=${fmt(s.p50)}  p90=${fmt(s.p90)}  max=${fmt(s.max)}`,\n  ]\n  for (let i = 0; i < buckets; i++) {\n    const a = lo + ((hi - lo) * i) / buckets\n    const b = lo + ((hi - lo) * (i + 1)) / buckets\n    const bar = '█'.repeat(Math.max(counts[i]! > 0 ? 1 : 0, Math.round((counts[i]! / maxCount) * width)))\n    lines.push(`${fmt(a).padStart(8)}-${fmt(b).padEnd(8)} ${bar} ${counts[i]}`)\n  }\n  return lines.join('\\n')\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}