@vauban-org/agent-sdk 1.2.0 → 1.3.0

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

package/src/telemetry/sinks/sqlite.ts

@@ -0,0 +1,260 @@
+/**
+ * localSqliteTelemetrySink — sovereign local mirror of agent runs.
+ *
+ * Per ADR-ECO-039 §5 : SQLite sink is ON by default. It is the exit plan for
+ * any remote sink (CC SaaS, OTLP backend) — if the network sink is revoked,
+ * the local SQLite file retains the full history.
+ *
+ * Schema (created on first use) :
+ *   - `agent_run`  : one row per OODA cycle (start + finish join)
+ *   - `agent_run_step` : one row per OODA step
+ *
+ * Dependency : `better-sqlite3` declared as **peerDependency optional**.
+ * If absent, this sink degrades gracefully — logs a warning and no-ops.
+ *
+ * Ref: command-center:sprint-693:sink-sqlite
+ */
+
+import { homedir } from "node:os";
+import { dirname, resolve as resolvePath } from "node:path";
+import { mkdirSync } from "node:fs";
+
+import type {
+  TelemetryRunFinish,
+  TelemetryRunStart,
+  TelemetryRunStep,
+  TelemetrySink,
+} from "../port.js";
+
+export interface LocalSqliteTelemetrySinkOptions {
+  /**
+   * Database file path. Default `~/.vauban/runs.db`.
+   * Pass `:memory:` for ephemeral test mode.
+   */
+  path?: string;
+  /** Synchronous mode (better-sqlite3 default). Tests may override. */
+  readonly?: boolean;
+}
+
+// ─── better-sqlite3 dynamic type stub ────────────────────────────────────────
+
+interface Statement {
+  run(...params: unknown[]): { changes: number; lastInsertRowid: number };
+  get(...params: unknown[]): unknown;
+  all(...params: unknown[]): unknown[];
+}
+
+interface Database {
+  prepare(sql: string): Statement;
+  exec(sql: string): void;
+  close(): void;
+  pragma(sql: string, options?: { simple: boolean }): unknown;
+}
+
+// ─── Schema ──────────────────────────────────────────────────────────────────
+
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS agent_run (
+  run_id            TEXT PRIMARY KEY,
+  agent_id          TEXT NOT NULL,
+  agent_version     TEXT NOT NULL,
+  model             TEXT,
+  provider          TEXT,
+  tenant_id         TEXT,
+  trace_id          TEXT,
+  started_at        TEXT NOT NULL,
+  finished_at       TEXT,
+  status            TEXT,
+  stop_reason       TEXT,
+  error_message     TEXT,
+  total_input_tokens  INTEGER DEFAULT 0,
+  total_output_tokens INTEGER DEFAULT 0,
+  total_cost_usd      REAL DEFAULT 0,
+  total_tool_calls    INTEGER DEFAULT 0
+);
+
+CREATE INDEX IF NOT EXISTS idx_agent_run_agent_started
+  ON agent_run (agent_id, started_at DESC);
+
+CREATE INDEX IF NOT EXISTS idx_agent_run_status
+  ON agent_run (status, started_at DESC);
+
+CREATE TABLE IF NOT EXISTS agent_run_step (
+  run_id        TEXT NOT NULL,
+  step_index    INTEGER NOT NULL,
+  kind          TEXT NOT NULL,
+  status        TEXT NOT NULL,
+  input_tokens  INTEGER DEFAULT 0,
+  output_tokens INTEGER DEFAULT 0,
+  tool_calls    INTEGER DEFAULT 0,
+  cost_usd      REAL DEFAULT 0,
+  duration_ms   INTEGER,
+  metadata      TEXT,
+  recorded_at   TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  PRIMARY KEY (run_id, step_index)
+);
+
+CREATE INDEX IF NOT EXISTS idx_agent_run_step_run
+  ON agent_run_step (run_id, step_index);
+`;
+
+// ─── Factory ─────────────────────────────────────────────────────────────────
+
+/**
+ * Build a local SQLite sink. Returns a no-op sink if `better-sqlite3` is not
+ * installed — the caller is warned via `console.warn` once.
+ */
+export function localSqliteTelemetrySink(
+  opts: LocalSqliteTelemetrySinkOptions = {}
+): TelemetrySink {
+  const dbPath = resolveDbPath(opts.path);
+  const db = openDatabaseSafely(dbPath, opts.readonly ?? false);
+
+  if (!db) {
+    return degradedSink(dbPath);
+  }
+
+  db.exec(SCHEMA);
+  db.pragma("journal_mode = WAL");
+  db.pragma("synchronous = NORMAL");
+
+  const insertRun = db.prepare(`
+    INSERT INTO agent_run
+      (run_id, agent_id, agent_version, model, provider,
+       tenant_id, trace_id, started_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT (run_id) DO NOTHING
+  `);
+
+  const insertStep = db.prepare(`
+    INSERT INTO agent_run_step
+      (run_id, step_index, kind, status,
+       input_tokens, output_tokens, tool_calls, cost_usd,
+       duration_ms, metadata)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT (run_id, step_index) DO NOTHING
+  `);
+
+  const updateFinish = db.prepare(`
+    UPDATE agent_run
+       SET finished_at = ?,
+           status = ?,
+           stop_reason = ?,
+           error_message = ?,
+           total_input_tokens = COALESCE(?, total_input_tokens),
+           total_output_tokens = COALESCE(?, total_output_tokens),
+           total_cost_usd = COALESCE(?, total_cost_usd),
+           total_tool_calls = COALESCE(?, total_tool_calls)
+     WHERE run_id = ?
+  `);
+
+  return {
+    name: "sqlite",
+
+    async start(event: TelemetryRunStart) {
+      insertRun.run(
+        event.runId,
+        event.agentId,
+        event.agentVersion,
+        event.model ?? null,
+        event.provider ?? null,
+        event.tenantId ?? null,
+        event.traceId ?? null,
+        event.startedAt
+      );
+    },
+
+    async step(runId: string, delta: TelemetryRunStep) {
+      insertStep.run(
+        runId,
+        delta.stepIndex,
+        delta.kind,
+        delta.status,
+        delta.inputTokens,
+        delta.outputTokens,
+        delta.toolCalls ?? 0,
+        delta.costUsd,
+        delta.durationMs ?? null,
+        delta.metadata ? JSON.stringify(delta.metadata) : null
+      );
+    },
+
+    async finish(runId: string, event: TelemetryRunFinish) {
+      updateFinish.run(
+        event.finishedAt,
+        event.status,
+        event.stopReason ?? null,
+        event.errorMessage ?? null,
+        event.totalInputTokens ?? null,
+        event.totalOutputTokens ?? null,
+        event.totalCostUsd ?? null,
+        event.totalToolCalls ?? null,
+        runId
+      );
+    },
+
+    async flush() {
+      // better-sqlite3 is synchronous — no buffer to flush.
+    },
+  };
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function resolveDbPath(input?: string): string {
+  if (!input) return resolvePath(homedir(), ".vauban", "runs.db");
+  if (input === ":memory:") return input;
+  // Expand leading ~ manually (Node doesn't do it).
+  if (input.startsWith("~/")) {
+    return resolvePath(homedir(), input.slice(2));
+  }
+  return resolvePath(input);
+}
+
+let warnedMissing = false;
+
+function openDatabaseSafely(path: string, readonly: boolean): Database | null {
+  try {
+    // Dynamic require so better-sqlite3 stays optional.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const createRequire = require("node:module").createRequire as (
+      specifier: string
+    ) => NodeJS.Require;
+    const req = createRequire(import.meta.url);
+    const BetterSqlite = req("better-sqlite3") as new (
+      path: string,
+      opts?: { readonly?: boolean }
+    ) => Database;
+
+    if (path !== ":memory:") {
+      mkdirSync(dirname(path), { recursive: true });
+    }
+    return new BetterSqlite(path, { readonly });
+  } catch (err) {
+    if (!warnedMissing) {
+      warnedMissing = true;
+      // eslint-disable-next-line no-console
+      console.warn(
+        "[telemetry:sqlite] better-sqlite3 not installed — sink degraded to no-op.",
+        "Install with: `pnpm add better-sqlite3` (peerDependencyOptional).",
+        err instanceof Error ? err.message : ""
+      );
+    }
+    return null;
+  }
+}
+
+function degradedSink(path: string): TelemetrySink {
+  return {
+    name: `sqlite:degraded(${path})`,
+    async start() {
+      /* no-op when better-sqlite3 missing */
+    },
+    async step() {
+      /* no-op */
+    },
+    async finish() {
+      /* no-op */
+    },
+  };
+}

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

@@ -0,0 +1,109 @@
+/**
+ * stdoutTelemetrySink — JSON emission tests.
+ *
+ * Ref: command-center:sprint-693:sink-stdout
+ */
+
+import { describe, expect, it } from "vitest";
+import { Writable } from "node:stream";
+
+import { stdoutTelemetrySink } from "./stdout.js";
+
+function collectingStream(): {
+  stream: Writable;
+  lines: () => string[];
+} {
+  const chunks: string[] = [];
+  const stream = new Writable({
+    write(chunk, _enc, cb) {
+      chunks.push(chunk.toString());
+      cb();
+    },
+  });
+  return {
+    stream,
+    lines: () =>
+      chunks
+        .join("")
+        .split("\n")
+        .filter((l) => l.length > 0),
+  };
+}
+
+const RUN_START = {
+  runId: "run-1",
+  agentId: "a",
+  agentVersion: "1.0.0",
+  model: "test",
+  provider: "test",
+  startedAt: "2026-05-16T17:00:00.000Z",
+};
+
+describe("stdoutTelemetrySink", () => {
+  it("emits one JSON line per event", async () => {
+    const { stream, lines } = collectingStream();
+    const sink = stdoutTelemetrySink({ stream });
+
+    await sink.start(RUN_START);
+    await sink.step("run-1", {
+      stepIndex: 0,
+      kind: "observe",
+      status: "completed",
+      inputTokens: 5,
+      outputTokens: 10,
+      costUsd: 0,
+    });
+    await sink.finish("run-1", {
+      status: "success",
+      finishedAt: "2026-05-16T17:00:01.000Z",
+    });
+
+    const out = lines();
+    expect(out).toHaveLength(3);
+    expect(JSON.parse(out[0]!)).toMatchObject({
+      telemetry: "run.start",
+      runId: "run-1",
+      agentId: "a",
+    });
+    expect(JSON.parse(out[1]!)).toMatchObject({
+      telemetry: "run.step",
+      runId: "run-1",
+      kind: "observe",
+    });
+    expect(JSON.parse(out[2]!)).toMatchObject({
+      telemetry: "run.finish",
+      runId: "run-1",
+      status: "success",
+    });
+  });
+
+  it("emits key=value when json=false", async () => {
+    const { stream, lines } = collectingStream();
+    const sink = stdoutTelemetrySink({ stream, json: false });
+    await sink.start(RUN_START);
+    expect(lines()[0]).toContain('runId="run-1"');
+    expect(lines()[0]).toContain('agentId="a"');
+  });
+
+  it("emits a JSON shape compatible with `jq`", async () => {
+    const { stream, lines } = collectingStream();
+    const sink = stdoutTelemetrySink({ stream });
+    await sink.start(RUN_START);
+    const parsed = JSON.parse(lines()[0]!);
+    // jq-friendly: top-level keys are sortable strings, no nested undefined
+    expect(parsed).toHaveProperty("telemetry");
+    expect(parsed).toHaveProperty("runId");
+    expect(parsed).toHaveProperty("startedAt");
+  });
+
+  it("has name 'stdout'", () => {
+    const sink = stdoutTelemetrySink();
+    expect(sink.name).toBe("stdout");
+  });
+
+  it("defaults to stderr when no stream given", () => {
+    // Just verify constructor doesn't throw; can't capture global stderr in jsdom.
+    const sink = stdoutTelemetrySink();
+    expect(typeof sink.start).toBe("function");
+  });
+});

package/src/telemetry/sinks/stdout.ts

@@ -0,0 +1,59 @@
+/**
+ * stdoutTelemetrySink — JSON line emission to stderr (dev-friendly default).
+ *
+ * One JSON object per event, suitable for `jq`, `pino-pretty`, or any
+ * structured-log pipeline. Writes to stderr (not stdout) so that the agent's
+ * own stdout remains free for user output.
+ *
+ * Ref: command-center:sprint-693:sink-stdout
+ */
+
+import type {
+  TelemetryRunFinish,
+  TelemetryRunStart,
+  TelemetryRunStep,
+  TelemetrySink,
+} from "../port.js";
+
+export interface StdoutTelemetrySinkOptions {
+  /** Stream to write to. Defaults to `process.stderr`. */
+  stream?: NodeJS.WritableStream;
+  /** When true (default), emits as `key=value` instead of JSON. */
+  json?: boolean;
+}
+
+/**
+ * Default sink for dev visibility. Zero dependency, zero I/O latency
+ * (synchronous write to stream).
+ */
+export function stdoutTelemetrySink(
+  opts: StdoutTelemetrySinkOptions = {}
+): TelemetrySink {
+  const stream = opts.stream ?? process.stderr;
+  const useJson = opts.json ?? true;
+
+  function emit(event: Record<string, unknown>): void {
+    const line = useJson
+      ? JSON.stringify(event)
+      : Object.entries(event)
+          .map(([k, v]) => `${k}=${JSON.stringify(v)}`)
+          .join(" ");
+    stream.write(`${line}\n`);
+  }
+
+  return {
+    name: "stdout",
+
+    async start(event: TelemetryRunStart) {
+      emit({ telemetry: "run.start", ...event });
+    },
+
+    async step(runId: string, delta: TelemetryRunStep) {
+      emit({ telemetry: "run.step", runId, ...delta });
+    },
+
+    async finish(runId: string, event: TelemetryRunFinish) {
+      emit({ telemetry: "run.finish", runId, ...event });
+    },
+  };
+}