@tangle-network/agent-app 0.45.53 → 0.45.55

package/dist/{types-B25Mib1r.d.ts → tools/types.d.ts}

@@ -1,69 +1,3 @@
-/** The four canonical app-tool names. Stable identifiers the model calls in
- *  both the sandbox (MCP server name) and runtime (function-tool name) paths. */
-declare const APP_TOOL_NAMES: readonly ["submit_proposal", "schedule_followup", "render_ui", "add_citation"];
-/** Resolve a valid application tool name from the predefined list of tool names */
-type AppToolName = (typeof APP_TOOL_NAMES)[number];
-/** Determine if a string matches a valid application tool name */
-declare function isAppToolName(name: string): name is AppToolName;
-/** A minimal OpenAI Chat Completions function-tool shape — structurally
- *  compatible with `@tangle-network/agent-runtime`'s `OpenAIChatTool` without
- *  importing it (keeps this package runtime-free). */
-interface OpenAIFunctionTool {
-    type: 'function';
-    function: {
-        name: string;
-        description: string;
-        parameters: Record<string, unknown>;
-    };
-}
-/**
- * Build the four app tools in OpenAI function-tool shape. `submit_proposal`'s
- * `type` enum is the product's {@link AppToolTaxonomy.proposalTypes}; the
- * model-facing descriptions and the follow-up priority enum default to the
- * Tangle reference vocabulary and can be retuned via {@link BuildAppToolsOptions}
- * (the tool names + JSON-Schema shapes stay fixed — they are mechanism). Pass
- * the result to the agent-runtime backend's `tools`.
- */
-declare function buildAppToolOpenAITools(taxonomy: AppToolTaxonomy, opts?: BuildAppToolsOptions): OpenAIFunctionTool[];
-
-/**
- * A product-defined app tool — the open registration seam.
- *
- * The four built-ins (`submit_proposal`/`schedule_followup`/`render_ui`/
- * `add_citation`) are mechanism and stay hard-typed. This is how a product adds
- * a fifth+ tool (e.g. gtm-agent's `set_config`) WITHOUT forking the shell: the
- * `name` + JSON-Schema `parameters` are what the model sees, and `execute` is
- * dispatched through the SAME validation/outcome path as the built-ins — a
- * thrown {@link ToolInputError} becomes a correctable 4xx, any other throw an
- * internal error, and a tool call never silently "succeeds" without its effect.
- */
-interface AppToolDefinition<Args = Record<string, unknown>> {
-    /** Stable identifier the model calls (and the MCP server name). Must not
-     *  collide with a built-in app tool. */
-    name: string;
-    /** Model-facing description. */
-    description: string;
-    /** JSON-Schema for the parameters (the OpenAI `function.parameters` object). */
-    parameters: Record<string, unknown>;
-    /** Default route path the per-turn MCP server / HTTP handler is mounted at.
-     *  Overridable per call via `paths`/`buildHttpMcpServer`. */
-    path?: string;
-    /** Fulfil the call; the return value is the tool result the model sees.
-     *  `ctx` is the trusted per-turn identity (never from tool args). */
-    execute: (args: Args, ctx: AppToolContext) => Promise<unknown> | unknown;
-}
-/**
- * Validate + brand a product tool definition. Throws when the name is empty or
- * collides with a built-in (those are reserved mechanism). Identity otherwise —
- * call it at module scope so a bad definition fails at boot, not first use.
- */
-declare function defineAppTool<Args = Record<string, unknown>>(def: AppToolDefinition<Args>): AppToolDefinition<Args>;
-/** The OpenAI function-tool def for a custom tool — appended to the built-ins by
- *  `buildAppToolOpenAITools`. */
-declare function customToolToOpenAI(def: AppToolDefinition): OpenAIFunctionTool;
-/** Find a registered custom tool by the name the model called. */
-declare function findCustomTool(name: string, tools: readonly AppToolDefinition[] | undefined): AppToolDefinition | undefined;
-
 /**
  * The structured agent→app tool side channel, domain-seamed.
  *
@@ -87,7 +21,7 @@ declare function findCustomTool(name: string, tools: readonly AppToolDefinition[
 /** Server-set, trusted per-turn context. Recovered from request headers (HTTP
  *  path) or supplied directly (runtime path) — never from model tool args, so
  *  the model cannot forge identity or target another workspace. */
-interface AppToolContext {
+export interface AppToolContext {
     userId: string;
     workspaceId: string;
     threadId: string | null;
@@ -95,7 +29,7 @@ interface AppToolContext {
 /** The product's proposal taxonomy — the only domain-specific vocabulary the
  *  generic layer needs (to validate `submit_proposal.type` and label the
  *  regulated subset). */
-interface AppToolTaxonomy {
+export interface AppToolTaxonomy {
     /** Every accepted proposal type. */
     proposalTypes: readonly string[];
     /** The subset that cannot execute without a named certified human (regulated
@@ -108,14 +42,14 @@ interface AppToolTaxonomy {
  *  both transports rely on); the model-facing PROSE and the follow-up priority
  *  vocabulary are domain — a product with no vault/contacts/OpenUI can retune
  *  them here instead of forking the shell. Omit for the defaults. */
-interface BuildAppToolsOptions {
+export interface BuildAppToolsOptions {
     /** Override the model-facing description of any of the four tools. */
     descriptions?: Partial<Record<'submit_proposal' | 'schedule_followup' | 'render_ui' | 'add_citation', string>>;
     /** The `schedule_followup.priority` enum (defaults to `['low','medium','high']`). */
     priorityValues?: readonly string[];
     /** Product-registered tools to advertise to the model alongside the four
      *  built-ins (appended in order, after the built-ins). */
-    customTools?: readonly AppToolDefinition[];
+    customTools?: readonly import('./registry').AppToolDefinition[];
     /**
      * Teach the model the interactive page vocabulary (forms, inputs, sliders)
      * by appending {@link import('../openui/index').OPENUI_INTERACTIVE_AUTHORING_GUIDE}
@@ -129,7 +63,7 @@ interface BuildAppToolsOptions {
     interactiveUi?: boolean;
 }
 /** Define the arguments required to submit a proposal including type, title, description, and approval status */
-interface SubmitProposalArgs {
+export interface SubmitProposalArgs {
     type: string;
     title: string;
     description?: string | null;
@@ -139,7 +73,7 @@ interface SubmitProposalArgs {
     regulated?: boolean;
 }
 /** Describe the result of submitting a proposal including deduplication and execution status */
-interface SubmitProposalResult {
+export interface SubmitProposalResult {
     proposalId: string;
     /** True when an identical (workspace, title) proposal already existed. */
     deduped: boolean;
@@ -152,24 +86,24 @@ interface SubmitProposalResult {
     [extra: string]: unknown;
 }
 /** Define arguments required to schedule a follow-up with optional priority */
-interface ScheduleFollowupArgs {
+export interface ScheduleFollowupArgs {
     title: string;
     dueDate: string;
     priority?: string;
 }
 /** Define the result structure for scheduling a follow-up with unique identification and due date */
-interface ScheduleFollowupResult {
+export interface ScheduleFollowupResult {
     id: string;
     dueDate: string;
     deduped: boolean;
 }
 /** Define arguments required to render a UI including title and schema */
-interface RenderUiArgs {
+export interface RenderUiArgs {
     title: string;
     schema: unknown;
 }
 /** Describe the result of rendering UI including the artifact path and exact persisted content */
-interface RenderUiResult {
+export interface RenderUiResult {
     /** The persisted artifact path. */
     path: string;
     /** The exact persisted body — surfaced as the `artifact` produced event so a
@@ -177,13 +111,13 @@ interface RenderUiResult {
     content: string;
 }
 /** Define arguments required to add a citation including path, quote, and optional label */
-interface AddCitationArgs {
+export interface AddCitationArgs {
     path: string;
     quote: string;
     label?: string;
 }
 /** Represent the result of adding a citation including its identifier and location path */
-interface AddCitationResult {
+export interface AddCitationResult {
     citationId: string;
     path: string;
 }
@@ -194,7 +128,7 @@ interface AddCitationResult {
  * `submitProposal` is the only handler whose result feeds the approval queue;
  * the others execute immediately.
  */
-interface AppToolHandlers {
+export interface AppToolHandlers {
     submitProposal(args: SubmitProposalArgs, ctx: AppToolContext): Promise<SubmitProposalResult>;
     scheduleFollowup(args: ScheduleFollowupArgs, ctx: AppToolContext): Promise<ScheduleFollowupResult>;
     renderUi(args: RenderUiArgs, ctx: AppToolContext): Promise<RenderUiResult>;
@@ -204,7 +138,7 @@ interface AppToolHandlers {
  *  site, so a consumer's eval/completion oracle credits a persisted proposal or
  *  artifact. Deliberately substrate-free (no RuntimeStreamEvent import); the
  *  consumer maps these onto its own telemetry shape. */
-type AppToolProducedEvent = {
+export type AppToolProducedEvent = {
     type: 'proposal_created';
     proposalId: string;
     title: string;
@@ -220,7 +154,7 @@ type AppToolProducedEvent = {
  *  the loop's `role: 'tool'` result message. Defined here (not imported) to keep
  *  the `tools/` module substrate-free: it depends only on Web `Request`/
  *  `Response`, never on the agent runtime. */
-type AppToolOutcome = {
+export type AppToolOutcome = {
     ok: true;
     result: unknown;
 } | {
@@ -229,5 +163,3 @@ type AppToolOutcome = {
     message: string;
     status?: number;
 };
-
-export { type AppToolContext as A, type BuildAppToolsOptions as B, type OpenAIFunctionTool as O, type RenderUiArgs as R, type ScheduleFollowupArgs as S, type AppToolName as a, type AppToolDefinition as b, type AppToolProducedEvent as c, type AppToolHandlers as d, type AppToolTaxonomy as e, type AppToolOutcome as f, APP_TOOL_NAMES as g, type AddCitationArgs as h, type AddCitationResult as i, type RenderUiResult as j, type ScheduleFollowupResult as k, type SubmitProposalArgs as l, type SubmitProposalResult as m, buildAppToolOpenAITools as n, customToolToOpenAI as o, defineAppTool as p, findCustomTool as q, isAppToolName as r };

package/dist/{flow-types-CJxEmaRy.d.ts → trace/flow-types.d.ts}

@@ -4,7 +4,7 @@
  * (`./mission-flow`, which emit them) import, so neither has to reach back
  * through the barrel. The barrel re-exports these names unchanged.
  */
-interface FlowSpan {
+export interface FlowSpan {
     kind: 'pipeline' | 'model' | 'tool';
     name: string;
     startMs: number;
@@ -13,7 +13,7 @@ interface FlowSpan {
     meta?: Record<string, unknown>;
 }
 /** Describe the structure of a flow trace including spans, timing, tokens, cost, and tool calls */
-interface FlowTrace {
+export interface FlowTrace {
     spans: FlowSpan[];
     totalMs: number;
     promptTokens: number;
@@ -22,5 +22,3 @@ interface FlowTrace {
     costUsd?: number;
     toolCalls: number;
 }
-
-export type { FlowTrace as F, FlowSpan as a };

package/dist/trace/index.d.ts

@@ -1,141 +1,3 @@
-import { F as FlowTrace, a as FlowSpan } from '../flow-types-CJxEmaRy.js';
-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;
-}
-/** Define context information for a step span including trace, span, and parent span identifiers */
-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;
-/** Define a step in a mission flow with id, intent, optional status, start time, and duration */
-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.
  *
@@ -151,32 +13,35 @@ declare function composeMissionFlowTrace(input: {
  * pump's flush window and the reader's poll cadence (~100–400ms); spans
  * carry `approx: true` to keep reports honest about that.
  */
-
+export * from './mission-trace';
+export * from './flow-types';
+export * from './mission-flow';
+import type { FlowTrace } from './flow-types';
 /** Represent a timed event with a timestamp and associated event data */
-interface TimedEvent {
+export interface TimedEvent {
     /** ms since turn start (`_t` stamped by pumpBufferedTurn). */
     t: number;
     event: Record<string, unknown>;
 }
 /** Parse stored turn-event lines (JSON strings with `_t`) into TimedEvents. */
-declare function timedEventsFromLines(lines: string[]): TimedEvent[];
+export declare function timedEventsFromLines(lines: string[]): TimedEvent[];
 /**
  * Derive a span trace from timestamped turn events. Model segments are runs
  * of text/reasoning deltas; a tool span opens at the last delta before its
  * tool_call emission and closes at the matching tool_result.
  */
-declare function buildFlowTrace(events: TimedEvent[], opts?: {
+export declare function buildFlowTrace(events: TimedEvent[], opts?: {
     pricing?: {
         prompt?: string | number;
         completion?: string | number;
     };
 }): FlowTrace;
 /** ASCII waterfall cascade — the default artifact for explaining a flow. */
-declare function renderWaterfall(trace: FlowTrace, opts?: {
+export declare function renderWaterfall(trace: FlowTrace, opts?: {
     width?: number;
 }): string;
 /** Summarize key statistics of a numerical distribution including count, min, percentiles, and max */
-interface DistributionSummary {
+export interface DistributionSummary {
     n: number;
     min: number;
     p50: number;
@@ -184,13 +49,11 @@ interface DistributionSummary {
     max: number;
 }
 /** Summarize numeric values into a distribution summary including count, min, median, 90th percentile, and max */
-declare function summarize(values: number[]): DistributionSummary;
+export declare function summarize(values: number[]): DistributionSummary;
 /** ASCII histogram for multi-run samples (eval latencies, costs, scores). */
-declare function renderHistogram(values: number[], opts?: {
+export declare function renderHistogram(values: number[], opts?: {
     buckets?: number;
     width?: number;
     unit?: string;
     format?: (v: number) => string;
 }): string;
-
-export { type DistributionSummary, FlowSpan, 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/mission-flow.d.ts

@@ -0,0 +1,82 @@
+/**
+ * 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.
+ */
+import type { StepAgentActivity } from '../missions/agent-activity';
+import type { FlowSpan, FlowTrace } from './flow-types';
+/** Structural mirror of agent-runtime's `LoopTraceEvent` — same fields, no
+ *  import, so journals parsed from JSON feed straight in. */
+export 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.
+ */
+export 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`.
+ */
+export 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.
+ */
+export declare function stepActivityFlowTrace(activity: StepAgentActivity[], opts?: {
+    startedAt?: number;
+    nowMs?: number;
+}): FlowTrace;
+/** Define a step in a mission flow with id, intent, optional status, start time, and duration */
+export 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.
+ */
+export 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;

package/dist/trace/mission-trace.d.ts

@@ -0,0 +1,52 @@
+/**
+ * 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.
+ */
+export 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;
+}
+/** Define context information for a step span including trace, span, and parent span identifiers */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export declare function traceEnv(ctx: MissionTraceContext | StepSpanContext): {
+    TRACE_ID: string;
+    PARENT_SPAN_ID: string;
+};