@vauban-org/agent-sdk 1.2.0 → 1.4.0

package/src/telemetry/index.ts

@@ -0,0 +1,49 @@
+/**
+ * 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";

package/src/telemetry/port.ts

@@ -0,0 +1,160 @@
+/**
+ * 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
+ */
+
+// ─── Run lifecycle types (compatible with legacy AgentRunTracker) ────────────
+
+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;
+}
+
+// ─── Sink interface ──────────────────────────────────────────────────────────
+
+/**
+ * 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>;
+}
+
+// ─── 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: TelemetrySink = {
+  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 {
+  constructor(
+    message: string,
+    public readonly sinkName: string,
+    public readonly cause?: unknown
+  ) {
+    super(`[telemetry:${sinkName}] ${message}`);
+    this.name = "TelemetrySinkError";
+  }
+}

package/src/telemetry/sinks/otlp.test.ts

@@ -0,0 +1,146 @@
+/**
+ * otlpTelemetrySink — payload shape + fetch mocking tests.
+ *
+ * Ref: command-center:sprint-693:sink-otlp
+ */
+
+import { describe, expect, it, vi } from "vitest";
+
+import { otlpTelemetrySink } from "./otlp.js";
+
+const RUN_START = {
+  runId: "11111111-1111-1111-1111-111111111111",
+  agentId: "agent-x",
+  agentVersion: "1.0.0",
+  model: "groq-llama-3.3-70b",
+  provider: "groq",
+  startedAt: "2026-05-16T17:00:00.000Z",
+};
+
+describe("otlpTelemetrySink", () => {
+  it("posts to {url}/v1/traces on finish", async () => {
+    const fetchImpl = vi.fn(async () => new Response("ok", { status: 200 }));
+    const sink = otlpTelemetrySink({
+      url: "https://collector.example.com",
+      fetchImpl: fetchImpl as unknown as typeof fetch,
+    });
+
+    await sink.start(RUN_START);
+    await sink.finish(RUN_START.runId, {
+      status: "success",
+      finishedAt: "2026-05-16T17:00:05.000Z",
+    });
+
+    // start should NOT post — only finish does (start collected, finish emits).
+    expect(fetchImpl).toHaveBeenCalledTimes(1);
+    const [url, init] = fetchImpl.mock.calls[0] as [string, RequestInit];
+    expect(url).toBe("https://collector.example.com/v1/traces");
+    expect((init as { method: string }).method).toBe("POST");
+
+    const body = JSON.parse((init.body as string) ?? "{}");
+    expect(body.resourceSpans).toHaveLength(1);
+    const span = body.resourceSpans[0].scopeSpans[0].spans[0];
+    expect(span.name).toContain("ooda.cycle");
+    expect(span.traceId).toMatch(/^[0-9a-f]{32}$/);
+    expect(span.spanId).toMatch(/^[0-9a-f]{16}$/);
+  });
+
+  it("posts a child span per step", async () => {
+    const fetchImpl = vi.fn(async () => new Response("ok", { status: 200 }));
+    const sink = otlpTelemetrySink({
+      url: "https://collector.example.com",
+      fetchImpl: fetchImpl as unknown as typeof fetch,
+    });
+
+    await sink.start(RUN_START);
+    await sink.step(RUN_START.runId, {
+      stepIndex: 0,
+      kind: "observe",
+      status: "completed",
+      inputTokens: 5,
+      outputTokens: 10,
+      costUsd: 0,
+    });
+    await sink.finish(RUN_START.runId, {
+      status: "success",
+      finishedAt: "2026-05-16T17:00:05.000Z",
+    });
+
+    expect(fetchImpl).toHaveBeenCalledTimes(2); // step + finish
+    const stepBody = JSON.parse(
+      (fetchImpl.mock.calls[0]?.[1] as RequestInit | undefined)?.body as string
+    );
+    const stepSpan = stepBody.resourceSpans[0].scopeSpans[0].spans[0];
+    expect(stepSpan.name).toBe("ooda.observe");
+    expect(stepSpan.parentSpanId).toMatch(/^[0-9a-f]{16}$/);
+  });
+
+  it("includes static headers", async () => {
+    const fetchImpl = vi.fn(async () => new Response("ok", { status: 200 }));
+    const sink = otlpTelemetrySink({
+      url: "https://collector.example.com",
+      headers: { Authorization: "Bearer secret" },
+      fetchImpl: fetchImpl as unknown as typeof fetch,
+    });
+    await sink.start(RUN_START);
+    await sink.finish(RUN_START.runId, {
+      status: "success",
+      finishedAt: "2026-05-16T17:00:05.000Z",
+    });
+    const init = fetchImpl.mock.calls[0]?.[1] as RequestInit;
+    expect((init.headers as Record<string, string>).Authorization).toBe(
+      "Bearer secret"
+    );
+  });
+
+  it("rejects when receiver returns non-2xx", async () => {
+    const fetchImpl = vi.fn(async () => new Response("bad", { status: 500 }));
+    const sink = otlpTelemetrySink({
+      url: "https://collector.example.com",
+      fetchImpl: fetchImpl as unknown as typeof fetch,
+    });
+    await sink.start(RUN_START);
+    await expect(
+      sink.finish(RUN_START.runId, {
+        status: "success",
+        finishedAt: "2026-05-16T17:00:05.000Z",
+      })
+    ).rejects.toThrow(/OTLP 500/);
+  });
+
+  it("preserves the caller-provided trace id", async () => {
+    const fetchImpl = vi.fn(async () => new Response("ok", { status: 200 }));
+    const traceId = "abcdef1234567890abcdef1234567890";
+    const sink = otlpTelemetrySink({
+      url: "https://collector.example.com",
+      fetchImpl: fetchImpl as unknown as typeof fetch,
+    });
+    await sink.start({ ...RUN_START, traceId });
+    await sink.finish(RUN_START.runId, {
+      status: "success",
+      finishedAt: "2026-05-16T17:00:05.000Z",
+    });
+    const body = JSON.parse(
+      (fetchImpl.mock.calls[0]?.[1] as RequestInit | undefined)?.body as string
+    );
+    expect(body.resourceSpans[0].scopeSpans[0].spans[0].traceId).toBe(traceId);
+  });
+
+  it("status code maps failed → ERROR(2)", async () => {
+    const fetchImpl = vi.fn(async () => new Response("ok", { status: 200 }));
+    const sink = otlpTelemetrySink({
+      url: "https://c.example.com",
+      fetchImpl: fetchImpl as unknown as typeof fetch,
+    });
+    await sink.start(RUN_START);
+    await sink.finish(RUN_START.runId, {
+      status: "failed",
+      errorMessage: "boom",
+      finishedAt: "2026-05-16T17:00:05.000Z",
+    });
+    const body = JSON.parse(
+      (fetchImpl.mock.calls[0]?.[1] as RequestInit | undefined)?.body as string
+    );
+    expect(body.resourceSpans[0].scopeSpans[0].spans[0].status.code).toBe(2);
+  });
+});

package/src/telemetry/sinks/otlp.ts

@@ -0,0 +1,250 @@
+/**
+ * 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 {
+  TelemetryRunFinish,
+  TelemetryRunStart,
+  TelemetryRunStep,
+  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;
+}
+
+// ─── Run state cache (correlate step→span) ───────────────────────────────────
+
+interface RunState {
+  traceId: string;
+  spanId: string;
+  startUnixNano: string;
+  attributes: Record<string, string | number>;
+  steps: number;
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+const HEX = "0123456789abcdef";
+
+function randHex(bytes: number): string {
+  let s = "";
+  for (let i = 0; i < bytes * 2; i++) {
+    s += HEX[Math.floor(Math.random() * 16)];
+  }
+  return s;
+}
+
+function isoToUnixNano(iso: string): string {
+  const ms = Date.parse(iso);
+  if (Number.isNaN(ms)) return `${Date.now() * 1_000_000}`;
+  return `${ms * 1_000_000}`;
+}
+
+function toKeyValue(attrs: Record<string, unknown>): Array<{
+  key: string;
+  value: { stringValue?: string; intValue?: string; doubleValue?: number };
+}> {
+  const out: ReturnType<typeof toKeyValue> = [];
+  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: OtlpTelemetrySinkOptions
+): TelemetrySink {
+  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<string, RunState>();
+
+  async function postSpan(span: Record<string, unknown>): Promise<void> {
+    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: TelemetryRunStart) {
+      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: string, delta: TelemetryRunStep) {
+      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: string, event: TelemetryRunFinish) {
+      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);
+    },
+  };
+}