@nifrajs/agent-telemetry 3.1.0 → 3.3.0

package/README.md

@@ -16,6 +16,35 @@ Requests under `/_nifra/tool/*` and requests to `/mcp` receive tool-name, input-
 duration, and status observations. When `@nifrajs/otel` owns the request observation, tool spans are
 attached as children; otherwise the plugin creates a standalone observation. Other routes pass through.
 
+## Tracing agent runs
+
+`traceAgentRun` turns a `@nifrajs/agent` run's step evidence into an OpenTelemetry trace: one
+`nifra.agent.run` span per run, one child span per evidence item, with tool names, effect ids, error
+codes, and effect-ledger heads carried as span attributes. Only the runner's constrained evidence
+fields are exported - prompts, tool inputs, and outputs cannot enter a trace.
+
+Orchestration correlation is opt-in and cardinality-bounded. Allowed attributes are run, plan, node,
+attempt, evidence, replay, and trace coordinates plus bounded status/error codes. Content-bearing or
+unbounded attributes are rejected; the exporter is not a payload retention sink.
+
+```ts
+import { traceAgentRun } from "@nifrajs/agent-telemetry"
+import { combineAgentTelemetry, runAgent } from "@nifrajs/agent"
+
+const trace = traceAgentRun({ agent: agent.name, turnId, exporter })
+const result = await runAgent(agent, input, {
+  ...ports,
+  telemetry: combineAgentTelemetry(ports.telemetry, trace.telemetry),
+})
+trace.end(result)
+```
+
+Model evidence arrives as a started/terminal pair and becomes one timed `nifra.agent.model` span;
+tool, approval, budget, and state evidence are terminal-only and become instant children. Pass
+`parent` (for example the enclosing request observation's `context`) to nest runs under the HTTP
+span, or `traceparent` to continue an inbound W3C trace; `trace.context` is the run span's identity,
+forwardable with `traceHeaders`. Telemetry is fail-open: a throwing exporter never fails the turn.
+
 ## For AI agents
 
 Start with [`LLM.md`](./LLM.md) - this package's contract card (the exports you call + its footguns),

package/dist/index.d.ts

@@ -9,6 +9,7 @@
  * routes on the sync fast path unless hooks are present at registration time.
  */
 import { type ActiveObservation, type ObservationAdapter } from "@nifrajs/otel";
+export { type AgentRunEvidence, type AgentRunOutcome, type AgentRunTrace, type TraceAgentRunOptions, traceAgentRun, } from "./run.js";
 export interface AgentTelemetryOptions {
     /** Exporter that receives completed tool-call spans. */
     readonly exporter: ObservationAdapter;
@@ -50,5 +51,35 @@ export declare function agentTelemetry(options: AgentTelemetryOptions): {
  * ```
  */
 export declare function consoleAgentExporter(log?: (line: string) => void): ObservationAdapter;
-export {};
+/** Content-free lifecycle kinds emitted by run dispatch and recovery. */
+export type OrchestrationTelemetryKind = "started" | "checkpointed" | "retrying" | "recovered" | "cancelled" | "completed" | "failed" | "dead-lettered";
+/** Allowlisted correlation fields. No index signature is intentional: arbitrary attributes are rejected. */
+export interface OrchestrationTelemetryEvent {
+    readonly kind: OrchestrationTelemetryKind;
+    readonly runId: string;
+    readonly planDigest: string;
+    readonly nodeId: string;
+    readonly attempt: number;
+    readonly evidenceSeq: number;
+    readonly at: number;
+    readonly evidenceId?: string;
+    readonly replayId?: string;
+    readonly traceRef?: string;
+    readonly scheduleToken?: string;
+    readonly statusCode?: string;
+}
+export interface OrchestrationTelemetryOptions {
+    /** No exporter means disabled telemetry and zero spans. */
+    readonly exporter?: ObservationAdapter;
+    readonly adapters?: readonly ObservationAdapter[];
+    readonly maxDistinctValues?: number;
+}
+export interface OrchestrationTelemetry {
+    readonly enabled: boolean;
+    readonly dropped: number;
+    record(event: OrchestrationTelemetryEvent | unknown): boolean;
+    close(): void;
+}
+/** Create an opt-in, bounded telemetry bridge for run/retry/recovery correlation. */
+export declare function orchestrationTelemetry(options?: OrchestrationTelemetryOptions): OrchestrationTelemetry;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EACL,KAAK,iBAAiB,EAEtB,KAAK,kBAAkB,EACxB,MAAM,eAAe,CAAA;AAMtB,MAAM,WAAW,qBAAqB;IACpC,wDAAwD;IACxD,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAA;IACrC,qEAAqE;IACrE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC5C,oDAAoD;IACpD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CACtC;AAED,gEAAgE;AAChE,UAAU,WAAW;IACnB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE;QACf,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;QACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;QACvB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;KAC1B,CAAA;IACD,2EAA2E;IAC3E,QAAQ,CAAC,WAAW,CAAC,EAAE,iBAAiB,CAAA;CACzC;AAMD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,qBAAqB;;0BAUnC,WAAW;mBAiClB,OAAO,WAAW,WAAW;yBAMvB,QAAQ,WAAW,OAAO;EAqDlD;AAMD;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAEtB,GACA,kBAAkB,CAWpB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EACL,KAAK,iBAAiB,EAEtB,KAAK,kBAAkB,EACxB,MAAM,eAAe,CAAA;AAEtB,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,oBAAoB,EACzB,aAAa,GACd,MAAM,UAAU,CAAA;AAMjB,MAAM,WAAW,qBAAqB;IACpC,wDAAwD;IACxD,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAA;IACrC,qEAAqE;IACrE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC5C,oDAAoD;IACpD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CACtC;AAED,gEAAgE;AAChE,UAAU,WAAW;IACnB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE;QACf,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;QACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;QACvB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;KAC1B,CAAA;IACD,2EAA2E;IAC3E,QAAQ,CAAC,WAAW,CAAC,EAAE,iBAAiB,CAAA;CACzC;AAMD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,qBAAqB;;0BAUnC,WAAW;mBAiClB,OAAO,WAAW,WAAW;yBAMvB,QAAQ,WAAW,OAAO;EAqDlD;AAMD;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAEtB,GACA,kBAAkB,CAWpB;AAMD,yEAAyE;AACzE,MAAM,MAAM,0BAA0B,GAClC,SAAS,GACT,cAAc,GACd,UAAU,GACV,WAAW,GACX,WAAW,GACX,WAAW,GACX,QAAQ,GACR,eAAe,CAAA;AAEnB,4GAA4G;AAC5G,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,IAAI,EAAE,0BAA0B,CAAA;IACzC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;IAC/B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAC7B;AAED,MAAM,WAAW,6BAA6B;IAC5C,2DAA2D;IAC3D,QAAQ,CAAC,QAAQ,CAAC,EAAE,kBAAkB,CAAA;IACtC,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAA;IACjD,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAA;CACpC;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,MAAM,CAAC,KAAK,EAAE,2BAA2B,GAAG,OAAO,GAAG,OAAO,CAAA;IAC7D,KAAK,IAAI,IAAI,CAAA;CACd;AAiID,qFAAqF;AACrF,wBAAgB,sBAAsB,CACpC,OAAO,GAAE,6BAAkC,GAC1C,sBAAsB,CA0DxB"}

package/dist/index.js

@@ -9,6 +9,7 @@
  * routes on the sync fast path unless hooks are present at registration time.
  */
 import { createObservationLifecycle, } from "@nifrajs/otel";
+export { traceAgentRun, } from "./run.js";
 // ---------------------------------------------------------------------------
 // Middleware
 // ---------------------------------------------------------------------------
@@ -135,4 +136,186 @@ export function consoleAgentExporter(log = (line) => {
         },
     };
 }
+const ORCHESTRATION_TOKEN = /^[A-Za-z0-9._:-]{1,128}$/;
+const ORCHESTRATION_DIGEST = /^[0-9a-f]{64}$/;
+const ORCHESTRATION_KINDS = new Set([
+    "started",
+    "checkpointed",
+    "retrying",
+    "recovered",
+    "cancelled",
+    "completed",
+    "failed",
+    "dead-lettered",
+]);
+const ORCHESTRATION_FIELDS = new Set([
+    "kind",
+    "runId",
+    "planDigest",
+    "nodeId",
+    "attempt",
+    "evidenceSeq",
+    "at",
+    "evidenceId",
+    "replayId",
+    "traceRef",
+    "scheduleToken",
+    "statusCode",
+]);
+const ORCHESTRATION_FORBIDDEN = new Set([
+    "prompt",
+    "message",
+    "text",
+    "input",
+    "output",
+    "arguments",
+    "body",
+    "response",
+    "secret",
+    "credential",
+    "diagnostic",
+    "stack",
+    "content",
+    "transcript",
+    "artifact",
+    "path",
+]);
+function orchestrationRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function boundedTelemetryToken(value) {
+    return typeof value === "string" && ORCHESTRATION_TOKEN.test(value);
+}
+function parseOrchestrationEvent(value) {
+    if (!orchestrationRecord(value))
+        return undefined;
+    for (const key of Object.keys(value)) {
+        if (ORCHESTRATION_FORBIDDEN.has(key.toLowerCase()) || !ORCHESTRATION_FIELDS.has(key))
+            return undefined;
+    }
+    if (typeof value.kind !== "string" ||
+        !ORCHESTRATION_KINDS.has(value.kind) ||
+        !boundedTelemetryToken(value.runId) ||
+        !boundedTelemetryToken(value.nodeId) ||
+        typeof value.planDigest !== "string" ||
+        !ORCHESTRATION_DIGEST.test(value.planDigest) ||
+        typeof value.at !== "number" ||
+        !Number.isSafeInteger(value.at) ||
+        value.at < 0 ||
+        typeof value.attempt !== "number" ||
+        !Number.isSafeInteger(value.attempt) ||
+        value.attempt < 1 ||
+        typeof value.evidenceSeq !== "number" ||
+        !Number.isSafeInteger(value.evidenceSeq) ||
+        value.evidenceSeq < 0)
+        return undefined;
+    for (const key of [
+        "evidenceId",
+        "replayId",
+        "traceRef",
+        "scheduleToken",
+        "statusCode",
+    ]) {
+        const candidate = value[key];
+        if (candidate !== undefined && !boundedTelemetryToken(candidate))
+            return undefined;
+    }
+    return Object.freeze({
+        kind: value.kind,
+        runId: value.runId,
+        planDigest: value.planDigest,
+        nodeId: value.nodeId,
+        attempt: value.attempt,
+        evidenceSeq: value.evidenceSeq,
+        at: value.at,
+        ...(value.evidenceId === undefined ? {} : { evidenceId: value.evidenceId }),
+        ...(value.replayId === undefined ? {} : { replayId: value.replayId }),
+        ...(value.traceRef === undefined ? {} : { traceRef: value.traceRef }),
+        ...(value.scheduleToken === undefined ? {} : { scheduleToken: value.scheduleToken }),
+        ...(value.statusCode === undefined ? {} : { statusCode: value.statusCode }),
+    });
+}
+function orchestrationAttributes(event) {
+    return {
+        "nifra.orchestration.run_id": event.runId,
+        "nifra.orchestration.plan_digest": event.planDigest,
+        "nifra.orchestration.node_id": event.nodeId,
+        "nifra.orchestration.attempt": event.attempt,
+        "nifra.orchestration.evidence_seq": event.evidenceSeq,
+        "nifra.orchestration.at": event.at,
+        ...(event.evidenceId === undefined
+            ? {}
+            : { "nifra.orchestration.evidence_id": event.evidenceId }),
+        ...(event.replayId === undefined ? {} : { "nifra.orchestration.replay_id": event.replayId }),
+        ...(event.traceRef === undefined ? {} : { "nifra.orchestration.trace_ref": event.traceRef }),
+        ...(event.scheduleToken === undefined
+            ? {}
+            : { "nifra.orchestration.schedule": event.scheduleToken }),
+        ...(event.statusCode === undefined
+            ? {}
+            : { "nifra.orchestration.status_code": event.statusCode }),
+    };
+}
+/** Create an opt-in, bounded telemetry bridge for run/retry/recovery correlation. */
+export function orchestrationTelemetry(options = {}) {
+    const adapters = [
+        ...(options.exporter === undefined ? [] : [options.exporter]),
+        ...(options.adapters ?? []),
+    ];
+    const enabled = adapters.length > 0;
+    const maxDistinct = options.maxDistinctValues ?? 512;
+    if (!Number.isSafeInteger(maxDistinct) || maxDistinct < 1 || maxDistinct > 10_000)
+        throw new RangeError("orchestration telemetry maxDistinctValues is invalid");
+    if (!enabled)
+        return {
+            enabled: false,
+            get dropped() {
+                return 0;
+            },
+            record: () => false,
+            close: () => undefined,
+        };
+    const lifecycle = createObservationLifecycle({ adapters });
+    const run = lifecycle.start({ name: "nifra.orchestration.run", attributes: {} });
+    const distinct = new Map();
+    let droppedCount = 0;
+    let closed = false;
+    const record = (raw) => {
+        if (closed)
+            return false;
+        const event = parseOrchestrationEvent(raw);
+        if (event === undefined) {
+            droppedCount = Math.min(1_000_000, droppedCount + 1);
+            return false;
+        }
+        const attrs = orchestrationAttributes(event);
+        for (const [key, value] of Object.entries(attrs)) {
+            if (typeof value !== "string")
+                continue;
+            const values = distinct.get(key) ?? new Set();
+            if (!values.has(value) && values.size >= maxDistinct) {
+                droppedCount = Math.min(1_000_000, droppedCount + 1);
+                return false;
+            }
+            values.add(value);
+            distinct.set(key, values);
+        }
+        const status = event.kind === "failed" || event.kind === "dead-lettered" ? "error" : "ok";
+        run.startChild({ name: `nifra.orchestration.${event.kind}`, attributes: attrs }).end({ status });
+        return true;
+    };
+    return {
+        enabled: true,
+        get dropped() {
+            return droppedCount;
+        },
+        record,
+        close() {
+            if (closed)
+                return;
+            closed = true;
+            run.end({ status: "ok" });
+        },
+    };
+}
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/run.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Agent-run tracing - one OpenTelemetry span per bounded agent run, one child span per step
+ * evidence item, effect ledger heads carried as span attributes.
+ *
+ * The bridge consumes only the runner's constrained step-evidence contract (`seq`, `kind`,
+ * `outcome`, tool name, effect id, error code, ledger head): prompts, tool inputs, and outputs
+ * cannot enter an export. The evidence shape is declared structurally so the package stays
+ * dependency-free on `@nifrajs/agent`; the returned `telemetry` object satisfies its
+ * `AgentTelemetryPort` as-is.
+ */
+import { type ObservationAdapter, type ObservationContext, type ObservationParent } from "@nifrajs/otel";
+/** Structural twin of `@nifrajs/agent`'s `AgentStepEvidence`. */
+export interface AgentRunEvidence {
+    readonly seq: number;
+    readonly at: number;
+    readonly kind: "model" | "tool" | "approval" | "budget" | "state";
+    readonly outcome: "started" | "passed" | "failed" | "denied" | "suspended" | "committed";
+    readonly name?: string;
+    readonly effectId?: string;
+    readonly code?: string;
+    readonly ledgerHead?: string;
+}
+/** Structural slice of the runner's `AgentRunResult` that `end()` reads. */
+export interface AgentRunOutcome {
+    readonly status: "completed" | "suspended" | "continue";
+    readonly error?: {
+        readonly code: string;
+    };
+    readonly reason?: string;
+}
+export interface TraceAgentRunOptions {
+    /** Agent name, recorded as `nifra.agent.name`. */
+    readonly agent: string;
+    /** Turn id, recorded as `nifra.agent.turn_id`. */
+    readonly turnId: string;
+    /** Exporter that receives the run span and its evidence child spans. */
+    readonly exporter?: ObservationAdapter;
+    readonly adapters?: readonly ObservationAdapter[];
+    /**
+     * Parent span for the run - pass the enclosing request observation's `context` to nest agent
+     * runs under the HTTP span. `null` forces a root span; `undefined` falls back to `traceparent`.
+     */
+    readonly parent?: ObservationParent | null;
+    /** Inbound W3C header used when `parent` is undefined. */
+    readonly traceparent?: string | null;
+}
+export interface AgentRunTrace {
+    /** Pass as (or combine into) `ports.telemetry`. Never throws; a failing adapter cannot fail the turn. */
+    readonly telemetry: {
+        step(evidence: AgentRunEvidence): void;
+    };
+    /** The run span's trace identity, forwardable with `traceHeaders`. */
+    readonly context: ObservationContext;
+    /**
+     * End the run span. Pass the runner's result to record the final status
+     * (`nifra.agent.status`, pending reason, error code); omit it when the run threw.
+     * Exactly-once: repeated calls are ignored.
+     */
+    end(result?: AgentRunOutcome): void;
+}
+/**
+ * Open a run span and adapt the runner's step evidence into child spans.
+ *
+ *   const trace = traceAgentRun({ agent: agent.name, turnId, exporter, parent: c.observation?.context })
+ *   const result = await runAgent(agent, input, { ...ports, telemetry: trace.telemetry }, options)
+ *   trace.end(result)
+ *
+ * Model evidence arrives as a started/terminal pair and becomes one timed `nifra.agent.model`
+ * span; every other evidence item is terminal-only and becomes an instant child span.
+ */
+export declare function traceAgentRun(options: TraceAgentRunOptions): AgentRunTrace;
+//# sourceMappingURL=run.d.ts.map

package/dist/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAIL,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACvB,MAAM,eAAe,CAAA;AAEtB,iEAAiE;AACjE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,UAAU,GAAG,QAAQ,GAAG,OAAO,CAAA;IACjE,QAAQ,CAAC,OAAO,EAAE,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,WAAW,GAAG,WAAW,CAAA;IACxF,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAC7B;AAED,4EAA4E;AAC5E,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,WAAW,GAAG,UAAU,CAAA;IACvD,QAAQ,CAAC,KAAK,CAAC,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;IAC1C,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CACzB;AAED,MAAM,WAAW,oBAAoB;IACnC,kDAAkD;IAClD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,kDAAkD;IAClD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,CAAC,EAAE,kBAAkB,CAAA;IACtC,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAA;IACjD;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAAA;IAC1C,0DAA0D;IAC1D,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACrC;AAED,MAAM,WAAW,aAAa;IAC5B,yGAAyG;IACzG,QAAQ,CAAC,SAAS,EAAE;QAAE,IAAI,CAAC,QAAQ,EAAE,gBAAgB,GAAG,IAAI,CAAA;KAAE,CAAA;IAC9D,sEAAsE;IACtE,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAA;IACpC;;;;OAIG;IACH,GAAG,CAAC,MAAM,CAAC,EAAE,eAAe,GAAG,IAAI,CAAA;CACpC;AAcD;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,aAAa,CAmE1E"}

package/dist/run.js

@@ -0,0 +1,106 @@
+/**
+ * Agent-run tracing - one OpenTelemetry span per bounded agent run, one child span per step
+ * evidence item, effect ledger heads carried as span attributes.
+ *
+ * The bridge consumes only the runner's constrained step-evidence contract (`seq`, `kind`,
+ * `outcome`, tool name, effect id, error code, ledger head): prompts, tool inputs, and outputs
+ * cannot enter an export. The evidence shape is declared structurally so the package stays
+ * dependency-free on `@nifrajs/agent`; the returned `telemetry` object satisfies its
+ * `AgentTelemetryPort` as-is.
+ */
+import { createObservationLifecycle, } from "@nifrajs/otel";
+function evidenceAttributes(evidence) {
+    const attributes = {
+        "nifra.agent.evidence.seq": evidence.seq,
+        "nifra.agent.evidence.outcome": evidence.outcome,
+    };
+    if (evidence.name !== undefined)
+        attributes["tool.name"] = evidence.name;
+    if (evidence.effectId !== undefined)
+        attributes["nifra.effect.id"] = evidence.effectId;
+    if (evidence.code !== undefined)
+        attributes["nifra.agent.error_code"] = evidence.code;
+    if (evidence.ledgerHead !== undefined)
+        attributes["nifra.ledger.head"] = evidence.ledgerHead;
+    return attributes;
+}
+/**
+ * Open a run span and adapt the runner's step evidence into child spans.
+ *
+ *   const trace = traceAgentRun({ agent: agent.name, turnId, exporter, parent: c.observation?.context })
+ *   const result = await runAgent(agent, input, { ...ports, telemetry: trace.telemetry }, options)
+ *   trace.end(result)
+ *
+ * Model evidence arrives as a started/terminal pair and becomes one timed `nifra.agent.model`
+ * span; every other evidence item is terminal-only and becomes an instant child span.
+ */
+export function traceAgentRun(options) {
+    const adapters = [
+        ...(options.exporter === undefined ? [] : [options.exporter]),
+        ...(options.adapters ?? []),
+    ];
+    const lifecycle = createObservationLifecycle({ adapters });
+    const run = lifecycle.start({
+        name: "nifra.agent.run",
+        ...(options.parent === undefined ? {} : { parent: options.parent }),
+        ...(options.traceparent === undefined ? {} : { traceparent: options.traceparent }),
+        attributes: {
+            "nifra.agent.name": options.agent,
+            "nifra.agent.turn_id": options.turnId,
+        },
+    });
+    // The runner is sequential - at most one model call is in flight, so a single slot pairs the
+    // `started` item with its terminal twin. Kinds other than "model" emit terminal items only.
+    let openModel;
+    const step = (evidence) => {
+        try {
+            if (evidence.kind === "model" && evidence.outcome === "started") {
+                openModel?.end({ status: "error", attributes: { "nifra.agent.error_code": "unpaired" } });
+                openModel = run.startChild({
+                    name: "nifra.agent.model",
+                    attributes: evidenceAttributes(evidence),
+                });
+                return;
+            }
+            const failed = evidence.outcome === "failed" || evidence.outcome === "denied";
+            const status = failed ? "error" : "ok";
+            if (evidence.kind === "model" && openModel !== undefined) {
+                const span = openModel;
+                openModel = undefined;
+                span.setAttributes(evidenceAttributes(evidence));
+                span.end({ status });
+                return;
+            }
+            run
+                .startChild({
+                name: `nifra.agent.${evidence.kind}`,
+                attributes: evidenceAttributes(evidence),
+            })
+                .end({ status });
+        }
+        catch {
+            // Telemetry must never fail the turn it observes.
+        }
+    };
+    const end = (result) => {
+        try {
+            openModel?.end({ status: "error", attributes: { "nifra.agent.error_code": "run_ended" } });
+            openModel = undefined;
+            if (result === undefined) {
+                run.end({ status: "error", attributes: { "nifra.agent.status": "threw" } });
+                return;
+            }
+            const attributes = { "nifra.agent.status": result.status };
+            if (result.reason !== undefined)
+                attributes["nifra.agent.pending_reason"] = result.reason;
+            if (result.error !== undefined)
+                attributes["nifra.agent.error_code"] = result.error.code;
+            run.end({ status: result.error === undefined ? "ok" : "error", attributes });
+        }
+        catch {
+            // Same fail-open rule as step().
+        }
+    };
+    return Object.freeze({ telemetry: Object.freeze({ step }), context: run.context, end });
+}
+//# sourceMappingURL=run.js.map

package/dist/run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAGL,0BAA0B,GAI3B,MAAM,eAAe,CAAA;AAmDtB,SAAS,kBAAkB,CAAC,QAA0B;IACpD,MAAM,UAAU,GAAmC;QACjD,0BAA0B,EAAE,QAAQ,CAAC,GAAG;QACxC,8BAA8B,EAAE,QAAQ,CAAC,OAAO;KACjD,CAAA;IACD,IAAI,QAAQ,CAAC,IAAI,KAAK,SAAS;QAAE,UAAU,CAAC,WAAW,CAAC,GAAG,QAAQ,CAAC,IAAI,CAAA;IACxE,IAAI,QAAQ,CAAC,QAAQ,KAAK,SAAS;QAAE,UAAU,CAAC,iBAAiB,CAAC,GAAG,QAAQ,CAAC,QAAQ,CAAA;IACtF,IAAI,QAAQ,CAAC,IAAI,KAAK,SAAS;QAAE,UAAU,CAAC,wBAAwB,CAAC,GAAG,QAAQ,CAAC,IAAI,CAAA;IACrF,IAAI,QAAQ,CAAC,UAAU,KAAK,SAAS;QAAE,UAAU,CAAC,mBAAmB,CAAC,GAAG,QAAQ,CAAC,UAAU,CAAA;IAC5F,OAAO,UAAU,CAAA;AACnB,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,aAAa,CAAC,OAA6B;IACzD,MAAM,QAAQ,GAAG;QACf,GAAG,CAAC,OAAO,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QAC7D,GAAG,CAAC,OAAO,CAAC,QAAQ,IAAI,EAAE,CAAC;KAC5B,CAAA;IACD,MAAM,SAAS,GAAG,0BAA0B,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAA;IAC1D,MAAM,GAAG,GAAG,SAAS,CAAC,KAAK,CAAC;QAC1B,IAAI,EAAE,iBAAiB;QACvB,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC;QACnE,GAAG,CAAC,OAAO,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE,CAAC;QAClF,UAAU,EAAE;YACV,kBAAkB,EAAE,OAAO,CAAC,KAAK;YACjC,qBAAqB,EAAE,OAAO,CAAC,MAAM;SACtC;KACF,CAAC,CAAA;IACF,6FAA6F;IAC7F,4FAA4F;IAC5F,IAAI,SAAwC,CAAA;IAE5C,MAAM,IAAI,GAAG,CAAC,QAA0B,EAAQ,EAAE;QAChD,IAAI,CAAC;YACH,IAAI,QAAQ,CAAC,IAAI,KAAK,OAAO,IAAI,QAAQ,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;gBAChE,SAAS,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,EAAE,wBAAwB,EAAE,UAAU,EAAE,EAAE,CAAC,CAAA;gBACzF,SAAS,GAAG,GAAG,CAAC,UAAU,CAAC;oBACzB,IAAI,EAAE,mBAAmB;oBACzB,UAAU,EAAE,kBAAkB,CAAC,QAAQ,CAAC;iBACzC,CAAC,CAAA;gBACF,OAAM;YACR,CAAC;YACD,MAAM,MAAM,GAAG,QAAQ,CAAC,OAAO,KAAK,QAAQ,IAAI,QAAQ,CAAC,OAAO,KAAK,QAAQ,CAAA;YAC7E,MAAM,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAA;YACtC,IAAI,QAAQ,CAAC,IAAI,KAAK,OAAO,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;gBACzD,MAAM,IAAI,GAAG,SAAS,CAAA;gBACtB,SAAS,GAAG,SAAS,CAAA;gBACrB,IAAI,CAAC,aAAa,CAAC,kBAAkB,CAAC,QAAQ,CAAC,CAAC,CAAA;gBAChD,IAAI,CAAC,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC,CAAA;gBACpB,OAAM;YACR,CAAC;YACD,GAAG;iBACA,UAAU,CAAC;gBACV,IAAI,EAAE,eAAe,QAAQ,CAAC,IAAI,EAAE;gBACpC,UAAU,EAAE,kBAAkB,CAAC,QAAQ,CAAC;aACzC,CAAC;iBACD,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC,CAAA;QACpB,CAAC;QAAC,MAAM,CAAC;YACP,kDAAkD;QACpD,CAAC;IACH,CAAC,CAAA;IAED,MAAM,GAAG,GAAG,CAAC,MAAwB,EAAQ,EAAE;QAC7C,IAAI,CAAC;YACH,SAAS,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,EAAE,wBAAwB,EAAE,WAAW,EAAE,EAAE,CAAC,CAAA;YAC1F,SAAS,GAAG,SAAS,CAAA;YACrB,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;gBACzB,GAAG,CAAC,GAAG,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,EAAE,oBAAoB,EAAE,OAAO,EAAE,EAAE,CAAC,CAAA;gBAC3E,OAAM;YACR,CAAC;YACD,MAAM,UAAU,GAAmC,EAAE,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,CAAA;YAC1F,IAAI,MAAM,CAAC,MAAM,KAAK,SAAS;gBAAE,UAAU,CAAC,4BAA4B,CAAC,GAAG,MAAM,CAAC,MAAM,CAAA;YACzF,IAAI,MAAM,CAAC,KAAK,KAAK,SAAS;gBAAE,UAAU,CAAC,wBAAwB,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAA;YACxF,GAAG,CAAC,GAAG,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,EAAE,UAAU,EAAE,CAAC,CAAA;QAC9E,CAAC;QAAC,MAAM,CAAC;YACP,iCAAiC;QACnC,CAAC;IACH,CAAC,CAAA;IAED,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,CAAA;AACzF,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nifrajs/agent-telemetry",
-  "version": "3.1.0",
+  "version": "3.3.0",
   "description": "Agent telemetry plugin - child spans for AI tool calls on /_nifra/tool/* and MCP endpoints.",
   "keywords": [
     "bun",
@@ -38,10 +38,10 @@
     "access": "public"
   },
   "dependencies": {
-    "@nifrajs/otel": "3.1.0"
+    "@nifrajs/otel": "3.3.0"
   },
   "peerDependencies": {
-    "@nifrajs/core": "^3.1.0"
+    "@nifrajs/core": "^3.3.0"
   },
   "devDependencies": {
     "@nifrajs/core": "workspace:*"

package/src/index.ts

@@ -15,6 +15,14 @@ import {
   type ObservationAdapter,
 } from "@nifrajs/otel"
 
+export {
+  type AgentRunEvidence,
+  type AgentRunOutcome,
+  type AgentRunTrace,
+  type TraceAgentRunOptions,
+  traceAgentRun,
+} from "./run.ts"
+
 // ---------------------------------------------------------------------------
 // Types
 // ---------------------------------------------------------------------------
@@ -183,3 +191,238 @@ export function consoleAgentExporter(
     },
   }
 }
+
+// ---------------------------------------------------------------------------
+// Orchestration correlation
+// ---------------------------------------------------------------------------
+
+/** Content-free lifecycle kinds emitted by run dispatch and recovery. */
+export type OrchestrationTelemetryKind =
+  | "started"
+  | "checkpointed"
+  | "retrying"
+  | "recovered"
+  | "cancelled"
+  | "completed"
+  | "failed"
+  | "dead-lettered"
+
+/** Allowlisted correlation fields. No index signature is intentional: arbitrary attributes are rejected. */
+export interface OrchestrationTelemetryEvent {
+  readonly kind: OrchestrationTelemetryKind
+  readonly runId: string
+  readonly planDigest: string
+  readonly nodeId: string
+  readonly attempt: number
+  readonly evidenceSeq: number
+  readonly at: number
+  readonly evidenceId?: string
+  readonly replayId?: string
+  readonly traceRef?: string
+  readonly scheduleToken?: string
+  readonly statusCode?: string
+}
+
+export interface OrchestrationTelemetryOptions {
+  /** No exporter means disabled telemetry and zero spans. */
+  readonly exporter?: ObservationAdapter
+  readonly adapters?: readonly ObservationAdapter[]
+  readonly maxDistinctValues?: number
+}
+
+export interface OrchestrationTelemetry {
+  readonly enabled: boolean
+  readonly dropped: number
+  record(event: OrchestrationTelemetryEvent | unknown): boolean
+  close(): void
+}
+
+const ORCHESTRATION_TOKEN = /^[A-Za-z0-9._:-]{1,128}$/
+const ORCHESTRATION_DIGEST = /^[0-9a-f]{64}$/
+const ORCHESTRATION_KINDS: ReadonlySet<string> = new Set([
+  "started",
+  "checkpointed",
+  "retrying",
+  "recovered",
+  "cancelled",
+  "completed",
+  "failed",
+  "dead-lettered",
+])
+const ORCHESTRATION_FIELDS = new Set([
+  "kind",
+  "runId",
+  "planDigest",
+  "nodeId",
+  "attempt",
+  "evidenceSeq",
+  "at",
+  "evidenceId",
+  "replayId",
+  "traceRef",
+  "scheduleToken",
+  "statusCode",
+])
+const ORCHESTRATION_FORBIDDEN = new Set([
+  "prompt",
+  "message",
+  "text",
+  "input",
+  "output",
+  "arguments",
+  "body",
+  "response",
+  "secret",
+  "credential",
+  "diagnostic",
+  "stack",
+  "content",
+  "transcript",
+  "artifact",
+  "path",
+])
+
+function orchestrationRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+function boundedTelemetryToken(value: unknown): value is string {
+  return typeof value === "string" && ORCHESTRATION_TOKEN.test(value)
+}
+
+function parseOrchestrationEvent(value: unknown): OrchestrationTelemetryEvent | undefined {
+  if (!orchestrationRecord(value)) return undefined
+  for (const key of Object.keys(value)) {
+    if (ORCHESTRATION_FORBIDDEN.has(key.toLowerCase()) || !ORCHESTRATION_FIELDS.has(key))
+      return undefined
+  }
+  if (
+    typeof value.kind !== "string" ||
+    !ORCHESTRATION_KINDS.has(value.kind) ||
+    !boundedTelemetryToken(value.runId) ||
+    !boundedTelemetryToken(value.nodeId) ||
+    typeof value.planDigest !== "string" ||
+    !ORCHESTRATION_DIGEST.test(value.planDigest) ||
+    typeof value.at !== "number" ||
+    !Number.isSafeInteger(value.at) ||
+    value.at < 0 ||
+    typeof value.attempt !== "number" ||
+    !Number.isSafeInteger(value.attempt) ||
+    value.attempt < 1 ||
+    typeof value.evidenceSeq !== "number" ||
+    !Number.isSafeInteger(value.evidenceSeq) ||
+    value.evidenceSeq < 0
+  )
+    return undefined
+  for (const key of [
+    "evidenceId",
+    "replayId",
+    "traceRef",
+    "scheduleToken",
+    "statusCode",
+  ] as const) {
+    const candidate = value[key]
+    if (candidate !== undefined && !boundedTelemetryToken(candidate)) return undefined
+  }
+  return Object.freeze({
+    kind: value.kind as OrchestrationTelemetryKind,
+    runId: value.runId,
+    planDigest: value.planDigest,
+    nodeId: value.nodeId,
+    attempt: value.attempt,
+    evidenceSeq: value.evidenceSeq,
+    at: value.at,
+    ...(value.evidenceId === undefined ? {} : { evidenceId: value.evidenceId as string }),
+    ...(value.replayId === undefined ? {} : { replayId: value.replayId as string }),
+    ...(value.traceRef === undefined ? {} : { traceRef: value.traceRef as string }),
+    ...(value.scheduleToken === undefined ? {} : { scheduleToken: value.scheduleToken as string }),
+    ...(value.statusCode === undefined ? {} : { statusCode: value.statusCode as string }),
+  })
+}
+
+function orchestrationAttributes(
+  event: OrchestrationTelemetryEvent,
+): Record<string, string | number> {
+  return {
+    "nifra.orchestration.run_id": event.runId,
+    "nifra.orchestration.plan_digest": event.planDigest,
+    "nifra.orchestration.node_id": event.nodeId,
+    "nifra.orchestration.attempt": event.attempt,
+    "nifra.orchestration.evidence_seq": event.evidenceSeq,
+    "nifra.orchestration.at": event.at,
+    ...(event.evidenceId === undefined
+      ? {}
+      : { "nifra.orchestration.evidence_id": event.evidenceId }),
+    ...(event.replayId === undefined ? {} : { "nifra.orchestration.replay_id": event.replayId }),
+    ...(event.traceRef === undefined ? {} : { "nifra.orchestration.trace_ref": event.traceRef }),
+    ...(event.scheduleToken === undefined
+      ? {}
+      : { "nifra.orchestration.schedule": event.scheduleToken }),
+    ...(event.statusCode === undefined
+      ? {}
+      : { "nifra.orchestration.status_code": event.statusCode }),
+  }
+}
+
+/** Create an opt-in, bounded telemetry bridge for run/retry/recovery correlation. */
+export function orchestrationTelemetry(
+  options: OrchestrationTelemetryOptions = {},
+): OrchestrationTelemetry {
+  const adapters = [
+    ...(options.exporter === undefined ? [] : [options.exporter]),
+    ...(options.adapters ?? []),
+  ]
+  const enabled = adapters.length > 0
+  const maxDistinct = options.maxDistinctValues ?? 512
+  if (!Number.isSafeInteger(maxDistinct) || maxDistinct < 1 || maxDistinct > 10_000)
+    throw new RangeError("orchestration telemetry maxDistinctValues is invalid")
+  if (!enabled)
+    return {
+      enabled: false,
+      get dropped() {
+        return 0
+      },
+      record: () => false,
+      close: () => undefined,
+    }
+
+  const lifecycle = createObservationLifecycle({ adapters })
+  const run = lifecycle.start({ name: "nifra.orchestration.run", attributes: {} })
+  const distinct = new Map<string, Set<string>>()
+  let droppedCount = 0
+  let closed = false
+  const record = (raw: OrchestrationTelemetryEvent | unknown): boolean => {
+    if (closed) return false
+    const event = parseOrchestrationEvent(raw)
+    if (event === undefined) {
+      droppedCount = Math.min(1_000_000, droppedCount + 1)
+      return false
+    }
+    const attrs = orchestrationAttributes(event)
+    for (const [key, value] of Object.entries(attrs)) {
+      if (typeof value !== "string") continue
+      const values = distinct.get(key) ?? new Set<string>()
+      if (!values.has(value) && values.size >= maxDistinct) {
+        droppedCount = Math.min(1_000_000, droppedCount + 1)
+        return false
+      }
+      values.add(value)
+      distinct.set(key, values)
+    }
+    const status = event.kind === "failed" || event.kind === "dead-lettered" ? "error" : "ok"
+    run.startChild({ name: `nifra.orchestration.${event.kind}`, attributes: attrs }).end({ status })
+    return true
+  }
+  return {
+    enabled: true,
+    get dropped() {
+      return droppedCount
+    },
+    record,
+    close() {
+      if (closed) return
+      closed = true
+      run.end({ status: "ok" })
+    },
+  }
+}

package/src/run.ts

@@ -0,0 +1,159 @@
+/**
+ * Agent-run tracing - one OpenTelemetry span per bounded agent run, one child span per step
+ * evidence item, effect ledger heads carried as span attributes.
+ *
+ * The bridge consumes only the runner's constrained step-evidence contract (`seq`, `kind`,
+ * `outcome`, tool name, effect id, error code, ledger head): prompts, tool inputs, and outputs
+ * cannot enter an export. The evidence shape is declared structurally so the package stays
+ * dependency-free on `@nifrajs/agent`; the returned `telemetry` object satisfies its
+ * `AgentTelemetryPort` as-is.
+ */
+
+import {
+  type ActiveObservation,
+  type AttributeValue,
+  createObservationLifecycle,
+  type ObservationAdapter,
+  type ObservationContext,
+  type ObservationParent,
+} from "@nifrajs/otel"
+
+/** Structural twin of `@nifrajs/agent`'s `AgentStepEvidence`. */
+export interface AgentRunEvidence {
+  readonly seq: number
+  readonly at: number
+  readonly kind: "model" | "tool" | "approval" | "budget" | "state"
+  readonly outcome: "started" | "passed" | "failed" | "denied" | "suspended" | "committed"
+  readonly name?: string
+  readonly effectId?: string
+  readonly code?: string
+  readonly ledgerHead?: string
+}
+
+/** Structural slice of the runner's `AgentRunResult` that `end()` reads. */
+export interface AgentRunOutcome {
+  readonly status: "completed" | "suspended" | "continue"
+  readonly error?: { readonly code: string }
+  readonly reason?: string
+}
+
+export interface TraceAgentRunOptions {
+  /** Agent name, recorded as `nifra.agent.name`. */
+  readonly agent: string
+  /** Turn id, recorded as `nifra.agent.turn_id`. */
+  readonly turnId: string
+  /** Exporter that receives the run span and its evidence child spans. */
+  readonly exporter?: ObservationAdapter
+  readonly adapters?: readonly ObservationAdapter[]
+  /**
+   * Parent span for the run - pass the enclosing request observation's `context` to nest agent
+   * runs under the HTTP span. `null` forces a root span; `undefined` falls back to `traceparent`.
+   */
+  readonly parent?: ObservationParent | null
+  /** Inbound W3C header used when `parent` is undefined. */
+  readonly traceparent?: string | null
+}
+
+export interface AgentRunTrace {
+  /** Pass as (or combine into) `ports.telemetry`. Never throws; a failing adapter cannot fail the turn. */
+  readonly telemetry: { step(evidence: AgentRunEvidence): void }
+  /** The run span's trace identity, forwardable with `traceHeaders`. */
+  readonly context: ObservationContext
+  /**
+   * End the run span. Pass the runner's result to record the final status
+   * (`nifra.agent.status`, pending reason, error code); omit it when the run threw.
+   * Exactly-once: repeated calls are ignored.
+   */
+  end(result?: AgentRunOutcome): void
+}
+
+function evidenceAttributes(evidence: AgentRunEvidence): Record<string, AttributeValue> {
+  const attributes: Record<string, AttributeValue> = {
+    "nifra.agent.evidence.seq": evidence.seq,
+    "nifra.agent.evidence.outcome": evidence.outcome,
+  }
+  if (evidence.name !== undefined) attributes["tool.name"] = evidence.name
+  if (evidence.effectId !== undefined) attributes["nifra.effect.id"] = evidence.effectId
+  if (evidence.code !== undefined) attributes["nifra.agent.error_code"] = evidence.code
+  if (evidence.ledgerHead !== undefined) attributes["nifra.ledger.head"] = evidence.ledgerHead
+  return attributes
+}
+
+/**
+ * Open a run span and adapt the runner's step evidence into child spans.
+ *
+ *   const trace = traceAgentRun({ agent: agent.name, turnId, exporter, parent: c.observation?.context })
+ *   const result = await runAgent(agent, input, { ...ports, telemetry: trace.telemetry }, options)
+ *   trace.end(result)
+ *
+ * Model evidence arrives as a started/terminal pair and becomes one timed `nifra.agent.model`
+ * span; every other evidence item is terminal-only and becomes an instant child span.
+ */
+export function traceAgentRun(options: TraceAgentRunOptions): AgentRunTrace {
+  const adapters = [
+    ...(options.exporter === undefined ? [] : [options.exporter]),
+    ...(options.adapters ?? []),
+  ]
+  const lifecycle = createObservationLifecycle({ adapters })
+  const run = lifecycle.start({
+    name: "nifra.agent.run",
+    ...(options.parent === undefined ? {} : { parent: options.parent }),
+    ...(options.traceparent === undefined ? {} : { traceparent: options.traceparent }),
+    attributes: {
+      "nifra.agent.name": options.agent,
+      "nifra.agent.turn_id": options.turnId,
+    },
+  })
+  // The runner is sequential - at most one model call is in flight, so a single slot pairs the
+  // `started` item with its terminal twin. Kinds other than "model" emit terminal items only.
+  let openModel: ActiveObservation | undefined
+
+  const step = (evidence: AgentRunEvidence): void => {
+    try {
+      if (evidence.kind === "model" && evidence.outcome === "started") {
+        openModel?.end({ status: "error", attributes: { "nifra.agent.error_code": "unpaired" } })
+        openModel = run.startChild({
+          name: "nifra.agent.model",
+          attributes: evidenceAttributes(evidence),
+        })
+        return
+      }
+      const failed = evidence.outcome === "failed" || evidence.outcome === "denied"
+      const status = failed ? "error" : "ok"
+      if (evidence.kind === "model" && openModel !== undefined) {
+        const span = openModel
+        openModel = undefined
+        span.setAttributes(evidenceAttributes(evidence))
+        span.end({ status })
+        return
+      }
+      run
+        .startChild({
+          name: `nifra.agent.${evidence.kind}`,
+          attributes: evidenceAttributes(evidence),
+        })
+        .end({ status })
+    } catch {
+      // Telemetry must never fail the turn it observes.
+    }
+  }
+
+  const end = (result?: AgentRunOutcome): void => {
+    try {
+      openModel?.end({ status: "error", attributes: { "nifra.agent.error_code": "run_ended" } })
+      openModel = undefined
+      if (result === undefined) {
+        run.end({ status: "error", attributes: { "nifra.agent.status": "threw" } })
+        return
+      }
+      const attributes: Record<string, AttributeValue> = { "nifra.agent.status": result.status }
+      if (result.reason !== undefined) attributes["nifra.agent.pending_reason"] = result.reason
+      if (result.error !== undefined) attributes["nifra.agent.error_code"] = result.error.code
+      run.end({ status: result.error === undefined ? "ok" : "error", attributes })
+    } catch {
+      // Same fail-open rule as step().
+    }
+  }
+
+  return Object.freeze({ telemetry: Object.freeze({ step }), context: run.context, end })
+}