@vauban-org/agent-sdk 1.0.0 → 1.3.0

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);
+    },
+  };
+}

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

@@ -0,0 +1,121 @@
+/**
+ * localSqliteTelemetrySink — schema, write, idempotency tests.
+ *
+ * Uses `:memory:` SQLite so tests are hermetic. Requires `better-sqlite3`
+ * installed as a dev/peer dep. If absent, the sink degrades to no-op and
+ * the assertions tagged "degraded" pass.
+ *
+ * Ref: command-center:sprint-693:sink-sqlite
+ */
+
+import { describe, expect, it } from "vitest";
+
+import { localSqliteTelemetrySink } from "./sqlite.js";
+
+function isBetterSqliteAvailable(): boolean {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    require("better-sqlite3");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const RUN_START = {
+  runId: "11111111-1111-1111-1111-111111111111",
+  agentId: "agent-x",
+  agentVersion: "1.0.0",
+  model: "test",
+  provider: "test",
+  startedAt: "2026-05-16T17:00:00.000Z",
+};
+
+describe("localSqliteTelemetrySink", () => {
+  it("has a stable sink name", () => {
+    const sink = localSqliteTelemetrySink({ path: ":memory:" });
+    expect(
+      sink.name === "sqlite" || sink.name.startsWith("sqlite:degraded")
+    ).toBe(true);
+  });
+
+  it("never throws on start/step/finish", async () => {
+    const sink = localSqliteTelemetrySink({ path: ":memory:" });
+    await expect(sink.start(RUN_START)).resolves.toBeUndefined();
+    await expect(
+      sink.step("run-1", {
+        stepIndex: 0,
+        kind: "observe",
+        status: "completed",
+        inputTokens: 5,
+        outputTokens: 10,
+        costUsd: 0,
+      })
+    ).resolves.toBeUndefined();
+    await expect(
+      sink.finish("run-1", {
+        status: "success",
+        finishedAt: "2026-05-16T17:00:01.000Z",
+      })
+    ).resolves.toBeUndefined();
+  });
+
+  it.skipIf(!isBetterSqliteAvailable())(
+    "persists agent_run rows and supports finish update",
+    async () => {
+      // eslint-disable-next-line @typescript-eslint/no-require-imports
+      const BetterSqlite = require("better-sqlite3");
+      const sink = localSqliteTelemetrySink({ path: ":memory:" });
+
+      await sink.start(RUN_START);
+      await sink.finish(RUN_START.runId, {
+        status: "success",
+        finishedAt: "2026-05-16T17:00:01.000Z",
+        totalInputTokens: 100,
+        totalOutputTokens: 50,
+        totalCostUsd: 0.01,
+      });
+
+      // Re-open the file via the same in-memory path is impossible; instead,
+      // we trust the contract that no exceptions = persisted (since SQLite
+      // writes are sync). Spot-check by writing a separate file.
+      const path = `/tmp/vauban-telemetry-test-${Date.now()}.db`;
+      const sink2 = localSqliteTelemetrySink({ path });
+      await sink2.start(RUN_START);
+      await sink2.finish(RUN_START.runId, {
+        status: "success",
+        finishedAt: "2026-05-16T17:00:01.000Z",
+      });
+
+      const db = new BetterSqlite(path);
+      const row = db
+        .prepare("SELECT * FROM agent_run WHERE run_id = ?")
+        .get(RUN_START.runId);
+      db.close();
+
+      expect(row).toBeDefined();
+      expect(row.agent_id).toBe("agent-x");
+      expect(row.status).toBe("success");
+      expect(row.started_at).toBe(RUN_START.startedAt);
+    }
+  );
+
+  it.skipIf(!isBetterSqliteAvailable())(
+    "idempotent start (ON CONFLICT DO NOTHING)",
+    async () => {
+      const path = `/tmp/vauban-telemetry-test-${Date.now()}.db`;
+      const sink = localSqliteTelemetrySink({ path });
+      await sink.start(RUN_START);
+      await sink.start(RUN_START); // second call — should not throw or duplicate
+
+      // eslint-disable-next-line @typescript-eslint/no-require-imports
+      const BetterSqlite = require("better-sqlite3");
+      const db = new BetterSqlite(path);
+      const count = db
+        .prepare("SELECT COUNT(*) c FROM agent_run WHERE run_id = ?")
+        .get(RUN_START.runId);
+      db.close();
+      expect(count.c).toBe(1);
+    }
+  );
+});