@vauban-org/agent-sdk 1.2.0 → 1.3.0

package/dist/telemetry/bus.js

@@ -0,0 +1,159 @@
+/**
+ * TelemetryBus — fanout to multiple {@link TelemetrySink}s, non-blocking.
+ *
+ * Invariants :
+ *   1. Sink failures are ISOLATED — one sink throwing never affects the others
+ *      nor the host agent loop. Failures are logged via the bus logger.
+ *   2. The bus itself implements {@link TelemetrySink}, so it can be passed
+ *      transparently to consumers expecting a single sink (composition).
+ *   3. When `nonBlocking: true` (default), `start`/`step`/`finish` return
+ *      immediately and dispatch in background. Errors surface via the logger.
+ *   4. Backpressure : if internal queue > `maxQueueDepth`, oldest events are
+ *      dropped and counted.
+ *
+ * Ref: command-center:sprint-693:telemetry-bus
+ */
+import { NOOP_TELEMETRY_SINK, } from "./port.js";
+const NOOP_LOGGER = {
+    warn: () => {
+        /* no-op */
+    },
+    error: () => {
+        /* no-op */
+    },
+};
+class TelemetryBusImpl {
+    name = "telemetry-bus";
+    _sinks;
+    _logger;
+    _nonBlocking;
+    _maxQueueDepth;
+    /** Per-sink queue of pending events (FIFO). */
+    _queues;
+    /** Per-sink drain promise (single-flight). */
+    _draining;
+    _dropped = 0;
+    _sinkErrors = 0;
+    _dispatched = 0;
+    constructor(opts) {
+        this._sinks = opts.sinks;
+        this._logger = opts.logger ?? NOOP_LOGGER;
+        this._nonBlocking = opts.nonBlocking ?? true;
+        this._maxQueueDepth = opts.maxQueueDepth ?? 1000;
+        this._queues = this._sinks.map(() => []);
+        this._draining = this._sinks.map(() => null);
+    }
+    get counters() {
+        return {
+            dropped: this._dropped,
+            sinkErrors: this._sinkErrors,
+            dispatched: this._dispatched,
+        };
+    }
+    async start(event) {
+        return this._fanout({
+            kind: "start",
+            exec: (s) => s.start(event),
+        });
+    }
+    async step(runId, delta) {
+        return this._fanout({
+            kind: "step",
+            exec: (s) => s.step(runId, delta),
+        });
+    }
+    async finish(runId, event) {
+        return this._fanout({
+            kind: "finish",
+            exec: (s) => s.finish(runId, event),
+        });
+    }
+    async flush() {
+        await Promise.all([
+            ...this._draining.map((p) => p ?? Promise.resolve()),
+            ...this._sinks.map((s) => s.flush?.().catch((err) => {
+                this._sinkErrors += 1;
+                this._logger.warn({ sink: s.name, err: errorMessage(err) }, "telemetry-bus: flush failed");
+            })),
+        ]);
+    }
+    // ── internal ───────────────────────────────────────────────────────────────
+    async _fanout(evt) {
+        if (this._nonBlocking) {
+            // Enqueue on each sink, kick drain in background.
+            this._sinks.forEach((_, i) => this._enqueue(i, evt));
+            return;
+        }
+        // Blocking mode (tests) — dispatch sequentially and surface errors via log.
+        await Promise.all(this._sinks.map((sink) => this._dispatchOne(sink, evt)));
+    }
+    _enqueue(sinkIdx, evt) {
+        const queue = this._queues[sinkIdx];
+        if (queue.length >= this._maxQueueDepth) {
+            queue.shift(); // drop oldest
+            this._dropped += 1;
+            const sink = this._sinks[sinkIdx];
+            this._logger.warn({ sink: sink.name, depth: queue.length, dropped: this._dropped }, "telemetry-bus: queue overflow, oldest dropped");
+        }
+        queue.push(evt);
+        void this._drain(sinkIdx);
+    }
+    async _drain(sinkIdx) {
+        if (this._draining[sinkIdx])
+            return;
+        const sink = this._sinks[sinkIdx];
+        const queue = this._queues[sinkIdx];
+        const promise = (async () => {
+            while (queue.length > 0) {
+                const evt = queue.shift();
+                await this._dispatchOne(sink, evt);
+            }
+        })();
+        this._draining[sinkIdx] = promise;
+        try {
+            await promise;
+        }
+        finally {
+            this._draining[sinkIdx] = null;
+        }
+    }
+    async _dispatchOne(sink, evt) {
+        try {
+            await evt.exec(sink);
+            this._dispatched += 1;
+        }
+        catch (err) {
+            this._sinkErrors += 1;
+            this._logger.warn({
+                sink: sink.name,
+                kind: evt.kind,
+                err: errorMessage(err),
+            }, "telemetry-bus: sink dispatch failed (isolated)");
+        }
+    }
+}
+// ─── Factory ─────────────────────────────────────────────────────────────────
+/**
+ * Build a TelemetryBus that fans events to all sinks non-blockingly.
+ *
+ * If `sinks` is empty, returns {@link NOOP_TELEMETRY_SINK} so callers never
+ * need to null-check.
+ */
+export function createTelemetryBus(opts) {
+    if (opts.sinks.length === 0) {
+        // Wrap NOOP with stub counters + flush for type consistency.
+        return {
+            ...NOOP_TELEMETRY_SINK,
+            counters: { dropped: 0, sinkErrors: 0, dispatched: 0 },
+            async flush() {
+                /* no-op */
+            },
+        };
+    }
+    return new TelemetryBusImpl(opts);
+}
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+//# sourceMappingURL=bus.js.map

package/dist/telemetry/bus.js.map

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

package/dist/telemetry/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Public telemetry API for agent-sdk consumers.
+ *
+ * Per ADR-ECO-039. Sovereign multi-sink observability for OODA agents.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   createOODAAgent,
+ *   stdoutTelemetrySink,
+ *   localSqliteTelemetrySink,
+ * } from "@vauban-org/agent-sdk";
+ *
+ * createOODAAgent({
+ *   agentId: "my-agent",
+ *   telemetry: {
+ *     sinks: [
+ *       stdoutTelemetrySink(),
+ *       localSqliteTelemetrySink(),
+ *     ],
+ *   },
+ * });
+ * ```
+ */
+export { NOOP_TELEMETRY_SINK, TelemetrySinkError } from "./port.js";
+export type { TelemetryRunStatus, TelemetryRunFinish, TelemetryRunStart, TelemetryRunStep, TelemetrySink, } from "./port.js";
+export { createTelemetryBus } from "./bus.js";
+export type { TelemetryBusOptions, TelemetryCounters, TelemetryLogger, } from "./bus.js";
+export { stdoutTelemetrySink } from "./sinks/stdout.js";
+export type { StdoutTelemetrySinkOptions } from "./sinks/stdout.js";
+export { localSqliteTelemetrySink } from "./sinks/sqlite.js";
+export type { LocalSqliteTelemetrySinkOptions } from "./sinks/sqlite.js";
+export { otlpTelemetrySink } from "./sinks/otlp.js";
+export type { OtlpTelemetrySinkOptions } from "./sinks/otlp.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/telemetry/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/telemetry/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AACpE,YAAY,EACV,kBAAkB,EAClB,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,aAAa,GACd,MAAM,WAAW,CAAC;AAEnB,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAC9C,YAAY,EACV,mBAAmB,EACnB,iBAAiB,EACjB,eAAe,GAChB,MAAM,UAAU,CAAC;AAElB,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,YAAY,EAAE,0BAA0B,EAAE,MAAM,mBAAmB,CAAC;AAEpE,OAAO,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAC7D,YAAY,EAAE,+BAA+B,EAAE,MAAM,mBAAmB,CAAC;AAEzE,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,YAAY,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/telemetry/index.js

@@ -0,0 +1,30 @@
+/**
+ * Public telemetry API for agent-sdk consumers.
+ *
+ * Per ADR-ECO-039. Sovereign multi-sink observability for OODA agents.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   createOODAAgent,
+ *   stdoutTelemetrySink,
+ *   localSqliteTelemetrySink,
+ * } from "@vauban-org/agent-sdk";
+ *
+ * createOODAAgent({
+ *   agentId: "my-agent",
+ *   telemetry: {
+ *     sinks: [
+ *       stdoutTelemetrySink(),
+ *       localSqliteTelemetrySink(),
+ *     ],
+ *   },
+ * });
+ * ```
+ */
+export { NOOP_TELEMETRY_SINK, TelemetrySinkError } from "./port.js";
+export { createTelemetryBus } from "./bus.js";
+export { stdoutTelemetrySink } from "./sinks/stdout.js";
+export { localSqliteTelemetrySink } from "./sinks/sqlite.js";
+export { otlpTelemetrySink } from "./sinks/otlp.js";
+//# sourceMappingURL=index.js.map

package/dist/telemetry/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/telemetry/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AASpE,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAO9C,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAGxD,OAAO,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAG7D,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/telemetry/port.d.ts

@@ -0,0 +1,121 @@
+/**
+ * TelemetryPort — sovereign multi-sink observability for agent runs.
+ *
+ * Per ADR-ECO-039 (accepted 2026-05-16). Sink-based interface replaces the
+ * implicit coupling between agent-sdk and the CC `agent_run` table (legacy
+ * `AgentRunTracker`). Callers configure 0..N sinks; the {@link TelemetryBus}
+ * fans events out non-blockingly.
+ *
+ * Three modes :
+ *   1. Standalone   : `[stdoutTelemetrySink(), localSqliteTelemetrySink()]`
+ *   2. + CC SaaS    : add `commandCenterTelemetrySink({apiKey})`
+ *   3. Tiered       : same code, API key changes entitlement server-side
+ *
+ * Ref: command-center:sprint-693:port-interface
+ */
+export interface TelemetryRunStart {
+    /** Caller-generated run id (matches the OODA loop's runId / trace). */
+    runId: string;
+    agentId: string;
+    agentVersion: string;
+    model: string;
+    provider: string;
+    /** Optional tenant scoping — required by the CC sink. */
+    tenantId?: string;
+    /** OTel trace id for replay linkage. */
+    traceId?: string;
+    /** ISO8601 timestamp of cycle start. */
+    startedAt: string;
+}
+export interface TelemetryRunStep {
+    /** Monotonic step index within the run, starting at 0. */
+    stepIndex: number;
+    /** OODA phase or step kind ("observe" | "orient" | "decide" | "act" | ...). */
+    kind: string;
+    /** Status of THIS step (not the whole run). */
+    status: "completed" | "failed" | "skipped";
+    inputTokens: number;
+    outputTokens: number;
+    toolCalls?: number;
+    /**
+     * USD cost delta. MUST be >= 0. Use 0 for non-LLM steps.
+     * Fixed(6) precision recommended.
+     */
+    costUsd: number;
+    /** Optional duration in ms — useful for OTLP span span_start/span_end. */
+    durationMs?: number;
+    /** Optional metadata. Hashed at sink boundary unless `includePayloads`. */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Run final status.
+ *
+ * NEW (sprint-693) : "skipped" — added so that session_guard /
+ * risk_guard / heap_exceeded short-circuits are observably distinct
+ * from "success" or "failed".
+ */
+export type TelemetryRunStatus = "success" | "failed" | "skipped" | "timeout" | "incoherent";
+export interface TelemetryRunFinish {
+    status: TelemetryRunStatus;
+    /** Free-text reason — e.g. "session_guard:business-hours". */
+    stopReason?: string;
+    /** Only set when status === "failed" | "incoherent". */
+    errorMessage?: string;
+    /** ISO8601 timestamp of cycle finish. */
+    finishedAt: string;
+    /** Optional cumulative totals — sinks may compute or trust caller. */
+    totalInputTokens?: number;
+    totalOutputTokens?: number;
+    totalCostUsd?: number;
+    totalToolCalls?: number;
+}
+/**
+ * TelemetrySink — pluggable destination for run lifecycle events.
+ *
+ * Contract :
+ *   - `start` is called ONCE per run before any `step`.
+ *   - `step` MAY be called 0..N times after start; the bus serialises per-run.
+ *   - `finish` is called ONCE after the last `step` (or directly after `start`
+ *     for skipped runs).
+ *   - All methods MUST be idempotent w.r.t. their (runId, stepIndex) pair —
+ *     the bus may retry on transient sink failures.
+ *   - Implementations MUST NOT throw on transient errors ; return a rejected
+ *     Promise instead so the bus can isolate the failure.
+ *
+ * Implementations should NOT block the agent loop. Long-running I/O should
+ * be batched/queued internally.
+ */
+export interface TelemetrySink {
+    /** Unique sink identifier — used for audit log + Prometheus labels. */
+    readonly name: string;
+    /**
+     * Record run start. Returns a sink-local reference (e.g. DB UUID, file
+     * offset, span id) the bus may pass back to `step` / `finish` for
+     * correlation. Return value is opaque to the bus.
+     */
+    start(event: TelemetryRunStart): Promise<string | void>;
+    /** Record a single OODA step delta. */
+    step(runId: string, delta: TelemetryRunStep): Promise<void>;
+    /** Record run finish. */
+    finish(runId: string, event: TelemetryRunFinish): Promise<void>;
+    /**
+     * Flush pending I/O (best-effort). Called on agent shutdown.
+     * Implementations without a buffer can no-op.
+     */
+    flush?(): Promise<void>;
+}
+/**
+ * No-op sink. The bus uses this when no sinks are configured, so callers
+ * never need to null-check.
+ */
+export declare const NOOP_TELEMETRY_SINK: TelemetrySink;
+/**
+ * Thrown only at the BUS boundary when ALL sinks fail. Individual sink
+ * failures are warned and isolated (see {@link TelemetryBus}).
+ */
+export declare class TelemetrySinkError extends Error {
+    readonly sinkName: string;
+    readonly cause?: unknown | undefined;
+    constructor(message: string, sinkName: string, cause?: unknown | undefined);
+}
+//# sourceMappingURL=port.d.ts.map

package/dist/telemetry/port.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"port.d.ts","sourceRoot":"","sources":["../../src/telemetry/port.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,MAAM,WAAW,iBAAiB;IAChC,uEAAuE;IACvE,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wCAAwC;IACxC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wCAAwC;IACxC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,0DAA0D;IAC1D,SAAS,EAAE,MAAM,CAAC;IAClB,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IACb,+CAA+C;IAC/C,MAAM,EAAE,WAAW,GAAG,QAAQ,GAAG,SAAS,CAAC;IAC3C,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB,GAC1B,SAAS,GACT,QAAQ,GACR,SAAS,GACT,SAAS,GACT,YAAY,CAAC;AAEjB,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,kBAAkB,CAAC;IAC3B,8DAA8D;IAC9D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wDAAwD;IACxD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,yCAAyC;IACzC,UAAU,EAAE,MAAM,CAAC;IACnB,sEAAsE;IACtE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAID;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,aAAa;IAC5B,uEAAuE;IACvE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;;;OAIG;IACH,KAAK,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAExD,uCAAuC;IACvC,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5D,yBAAyB;IACzB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEhE;;;OAGG;IACH,KAAK,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB;AAID;;;GAGG;AACH,eAAO,MAAM,mBAAmB,EAAE,aAWjC,CAAC;AAIF;;;GAGG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;aAGzB,QAAQ,EAAE,MAAM;aAChB,KAAK,CAAC,EAAE,OAAO;gBAF/B,OAAO,EAAE,MAAM,EACC,QAAQ,EAAE,MAAM,EAChB,KAAK,CAAC,EAAE,OAAO,YAAA;CAKlC"}

package/dist/telemetry/port.js

@@ -0,0 +1,48 @@
+/**
+ * TelemetryPort — sovereign multi-sink observability for agent runs.
+ *
+ * Per ADR-ECO-039 (accepted 2026-05-16). Sink-based interface replaces the
+ * implicit coupling between agent-sdk and the CC `agent_run` table (legacy
+ * `AgentRunTracker`). Callers configure 0..N sinks; the {@link TelemetryBus}
+ * fans events out non-blockingly.
+ *
+ * Three modes :
+ *   1. Standalone   : `[stdoutTelemetrySink(), localSqliteTelemetrySink()]`
+ *   2. + CC SaaS    : add `commandCenterTelemetrySink({apiKey})`
+ *   3. Tiered       : same code, API key changes entitlement server-side
+ *
+ * Ref: command-center:sprint-693:port-interface
+ */
+// ─── NOOP — default when no sinks configured ─────────────────────────────────
+/**
+ * No-op sink. The bus uses this when no sinks are configured, so callers
+ * never need to null-check.
+ */
+export const NOOP_TELEMETRY_SINK = {
+    name: "noop",
+    async start() {
+        /* no-op */
+    },
+    async step() {
+        /* no-op */
+    },
+    async finish() {
+        /* no-op */
+    },
+};
+// ─── Error type ──────────────────────────────────────────────────────────────
+/**
+ * Thrown only at the BUS boundary when ALL sinks fail. Individual sink
+ * failures are warned and isolated (see {@link TelemetryBus}).
+ */
+export class TelemetrySinkError extends Error {
+    sinkName;
+    cause;
+    constructor(message, sinkName, cause) {
+        super(`[telemetry:${sinkName}] ${message}`);
+        this.sinkName = sinkName;
+        this.cause = cause;
+        this.name = "TelemetrySinkError";
+    }
+}
+//# sourceMappingURL=port.js.map

package/dist/telemetry/port.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"port.js","sourceRoot":"","sources":["../../src/telemetry/port.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AA+GH,gFAAgF;AAEhF;;;GAGG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAkB;IAChD,IAAI,EAAE,MAAM;IACZ,KAAK,CAAC,KAAK;QACT,WAAW;IACb,CAAC;IACD,KAAK,CAAC,IAAI;QACR,WAAW;IACb,CAAC;IACD,KAAK,CAAC,MAAM;QACV,WAAW;IACb,CAAC;CACF,CAAC;AAEF,gFAAgF;AAEhF;;;GAGG;AACH,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAGzB;IACA;IAHlB,YACE,OAAe,EACC,QAAgB,EAChB,KAAe;QAE/B,KAAK,CAAC,cAAc,QAAQ,KAAK,OAAO,EAAE,CAAC,CAAC;QAH5B,aAAQ,GAAR,QAAQ,CAAQ;QAChB,UAAK,GAAL,KAAK,CAAU;QAG/B,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF"}

package/dist/telemetry/sinks/otlp.d.ts

@@ -0,0 +1,45 @@
+/**
+ * otlpTelemetrySink — OTLP/HTTP exporter for agent runs.
+ *
+ * Maps {@link TelemetryRunStart} / Step / Finish to OpenTelemetry spans using
+ * GenAI semantic conventions. Sends as protobuf-over-HTTP to any compliant
+ * OTLP receiver (Tempo, Jaeger, Langfuse self-host, Honeycomb…).
+ *
+ * Lightweight implementation : JSON over HTTP `application/json` rather than
+ * protobuf to avoid pulling in `@opentelemetry/exporter-trace-otlp-proto`.
+ * The OTel spec allows JSON-encoded OTLP as a first-class transport (since
+ * v1.0). This keeps the SDK zero-dep — no `@opentelemetry/*` runtime needed.
+ *
+ * Ref: command-center:sprint-693:sink-otlp
+ */
+import type { TelemetrySink } from "../port.js";
+export interface OtlpTelemetrySinkOptions {
+    /**
+     * OTLP/HTTP endpoint base URL (no trailing slash).
+     * Example : `https://langfuse.vauban.tech/api/public/otel`
+     * Path `/v1/traces` is appended automatically.
+     */
+    url: string;
+    /** Static headers (Authorization, x-tenant-id, …). */
+    headers?: Record<string, string>;
+    /**
+     * Service name attached to every span. Defaults to `"vauban-agent-sdk"`.
+     * Override per-deployment to disambiguate in your tracing backend.
+     */
+    serviceName?: string;
+    /**
+     * fetch implementation override (for tests). Defaults to global `fetch`.
+     */
+    fetchImpl?: typeof fetch;
+    /**
+     * Request timeout in ms. Defaults to 5000.
+     */
+    timeoutMs?: number;
+}
+/**
+ * Create an OTLP/HTTP sink. The sink batches at the bus level (FIFO), so
+ * one HTTP request is sent per event in this minimal implementation.
+ * High-volume deployments should wrap with an upstream batcher.
+ */
+export declare function otlpTelemetrySink(opts: OtlpTelemetrySinkOptions): TelemetrySink;
+//# sourceMappingURL=otlp.d.ts.map

package/dist/telemetry/sinks/otlp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"otlp.d.ts","sourceRoot":"","sources":["../../../src/telemetry/sinks/otlp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAIV,aAAa,EACd,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,wBAAwB;IACvC;;;;OAIG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ,sDAAsD;IACtD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;OAEG;IACH,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAqDD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,wBAAwB,GAC7B,aAAa,CAiJf"}

package/dist/telemetry/sinks/otlp.js

@@ -0,0 +1,195 @@
+/**
+ * otlpTelemetrySink — OTLP/HTTP exporter for agent runs.
+ *
+ * Maps {@link TelemetryRunStart} / Step / Finish to OpenTelemetry spans using
+ * GenAI semantic conventions. Sends as protobuf-over-HTTP to any compliant
+ * OTLP receiver (Tempo, Jaeger, Langfuse self-host, Honeycomb…).
+ *
+ * Lightweight implementation : JSON over HTTP `application/json` rather than
+ * protobuf to avoid pulling in `@opentelemetry/exporter-trace-otlp-proto`.
+ * The OTel spec allows JSON-encoded OTLP as a first-class transport (since
+ * v1.0). This keeps the SDK zero-dep — no `@opentelemetry/*` runtime needed.
+ *
+ * Ref: command-center:sprint-693:sink-otlp
+ */
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+const HEX = "0123456789abcdef";
+function randHex(bytes) {
+    let s = "";
+    for (let i = 0; i < bytes * 2; i++) {
+        s += HEX[Math.floor(Math.random() * 16)];
+    }
+    return s;
+}
+function isoToUnixNano(iso) {
+    const ms = Date.parse(iso);
+    if (Number.isNaN(ms))
+        return `${Date.now() * 1_000_000}`;
+    return `${ms * 1_000_000}`;
+}
+function toKeyValue(attrs) {
+    const out = [];
+    for (const [k, v] of Object.entries(attrs)) {
+        if (v === null || v === undefined)
+            continue;
+        if (typeof v === "number") {
+            out.push({
+                key: k,
+                value: Number.isInteger(v)
+                    ? { intValue: String(v) }
+                    : { doubleValue: v },
+            });
+        }
+        else {
+            out.push({ key: k, value: { stringValue: String(v) } });
+        }
+    }
+    return out;
+}
+// ─── Factory ─────────────────────────────────────────────────────────────────
+/**
+ * Create an OTLP/HTTP sink. The sink batches at the bus level (FIFO), so
+ * one HTTP request is sent per event in this minimal implementation.
+ * High-volume deployments should wrap with an upstream batcher.
+ */
+export function otlpTelemetrySink(opts) {
+    const baseUrl = opts.url.replace(/\/+$/, "");
+    const tracesUrl = `${baseUrl}/v1/traces`;
+    const headers = {
+        "Content-Type": "application/json",
+        ...(opts.headers ?? {}),
+    };
+    const serviceName = opts.serviceName ?? "vauban-agent-sdk";
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const timeoutMs = opts.timeoutMs ?? 5000;
+    const runStates = new Map();
+    async function postSpan(span) {
+        const body = {
+            resourceSpans: [
+                {
+                    resource: {
+                        attributes: toKeyValue({
+                            "service.name": serviceName,
+                            "telemetry.sdk.name": "vauban-agent-sdk",
+                            "telemetry.sdk.language": "nodejs",
+                        }),
+                    },
+                    scopeSpans: [
+                        {
+                            scope: { name: "vauban.agent.ooda", version: "1.3.0" },
+                            spans: [span],
+                        },
+                    ],
+                },
+            ],
+        };
+        const ctrl = new AbortController();
+        const t = setTimeout(() => ctrl.abort(), timeoutMs);
+        try {
+            const res = await fetchImpl(tracesUrl, {
+                method: "POST",
+                headers,
+                body: JSON.stringify(body),
+                signal: ctrl.signal,
+            });
+            if (!res.ok) {
+                const text = await res.text().catch(() => "");
+                throw new Error(`OTLP ${res.status}: ${text.slice(0, 200)}`);
+            }
+        }
+        finally {
+            clearTimeout(t);
+        }
+    }
+    return {
+        name: "otlp",
+        async start(event) {
+            const traceId = event.traceId ?? randHex(16);
+            const spanId = randHex(8);
+            runStates.set(event.runId, {
+                traceId,
+                spanId,
+                startUnixNano: isoToUnixNano(event.startedAt),
+                attributes: {
+                    "vauban.run_id": event.runId,
+                    "vauban.agent.id": event.agentId,
+                    "vauban.agent.version": event.agentVersion,
+                    "gen_ai.system": event.provider,
+                    "gen_ai.request.model": event.model,
+                    ...(event.tenantId ? { "vauban.tenant.id": event.tenantId } : {}),
+                },
+                steps: 0,
+            });
+            // Don't post yet — wait for finish to send full span (start+end).
+        },
+        async step(runId, delta) {
+            const state = runStates.get(runId);
+            if (!state)
+                return;
+            state.steps += 1;
+            // Emit a child span per step for granular tracing.
+            const stepStart = isoToUnixNano(new Date().toISOString());
+            const durationNs = (delta.durationMs ?? 0) * 1_000_000;
+            const stepSpan = {
+                traceId: state.traceId,
+                spanId: randHex(8),
+                parentSpanId: state.spanId,
+                name: `ooda.${delta.kind}`,
+                kind: 1, // SPAN_KIND_INTERNAL
+                startTimeUnixNano: stepStart,
+                endTimeUnixNano: String(BigInt(stepStart) + BigInt(durationNs)),
+                attributes: toKeyValue({
+                    "vauban.step.index": delta.stepIndex,
+                    "vauban.step.kind": delta.kind,
+                    "vauban.step.status": delta.status,
+                    "gen_ai.usage.input_tokens": delta.inputTokens,
+                    "gen_ai.usage.output_tokens": delta.outputTokens,
+                    "vauban.step.tool_calls": delta.toolCalls ?? 0,
+                    "vauban.step.cost_usd": delta.costUsd,
+                }),
+                status: {
+                    code: delta.status === "failed" ? 2 : 1, // ERROR=2, OK=1
+                },
+            };
+            await postSpan(stepSpan);
+        },
+        async finish(runId, event) {
+            const state = runStates.get(runId);
+            if (!state)
+                return;
+            runStates.delete(runId);
+            const endNano = isoToUnixNano(event.finishedAt);
+            const span = {
+                traceId: state.traceId,
+                spanId: state.spanId,
+                name: `ooda.cycle.${state.attributes["vauban.agent.id"] ?? "agent"}`,
+                kind: 1,
+                startTimeUnixNano: state.startUnixNano,
+                endTimeUnixNano: endNano,
+                attributes: toKeyValue({
+                    ...state.attributes,
+                    "vauban.run.status": event.status,
+                    ...(event.stopReason
+                        ? { "vauban.run.stop_reason": event.stopReason }
+                        : {}),
+                    ...(event.totalInputTokens !== undefined
+                        ? { "gen_ai.usage.input_tokens": event.totalInputTokens }
+                        : {}),
+                    ...(event.totalOutputTokens !== undefined
+                        ? { "gen_ai.usage.output_tokens": event.totalOutputTokens }
+                        : {}),
+                    ...(event.totalCostUsd !== undefined
+                        ? { "vauban.run.cost_usd": event.totalCostUsd }
+                        : {}),
+                    "vauban.run.steps": state.steps,
+                }),
+                status: {
+                    code: event.status === "failed" || event.status === "incoherent" ? 2 : 1,
+                    ...(event.errorMessage ? { message: event.errorMessage } : {}),
+                },
+            };
+            await postSpan(span);
+        },
+    };
+}
+//# sourceMappingURL=otlp.js.map