@vauban-org/agent-sdk 1.0.0 → 1.3.0

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

package/src/testing/test-brain-port.ts

@@ -5,17 +5,35 @@
  * Maps. Use for agent unit tests that need to archive/query without
  * external infrastructure.
  *
+ * OTel spans are emitted on archiveKnowledge and queryKnowledge via
+ * @opentelemetry/api. Gracefully degrades to noop spans when no OTel SDK
+ * is installed.
+ *
  * @public
  */
 
-import type { BrainPort, BrainEntry, BrainEntryInput, BrainQueryFilters } from "../ports/brain.js";
+import type { Span } from "@opentelemetry/api";
+import { SpanStatusCode, trace } from "@opentelemetry/api";
+import type {
+  BrainPort,
+  BrainEntry,
+  BrainEntryInput,
+  BrainQueryFilters,
+} from "../ports/brain.js";
 import {
   InMemoryWorkingMemory,
   InMemoryEpisodicMemory,
   InMemorySemanticMemory,
   InMemoryProceduralMemory,
 } from "../ports/brain.js";
-import type { WorkingMemoryPort, EpisodicMemoryPort, SemanticMemoryPort, ProceduralMemoryPort } from "../ports/brain.js";
+import type {
+  WorkingMemoryPort,
+  EpisodicMemoryPort,
+  SemanticMemoryPort,
+  ProceduralMemoryPort,
+} from "../ports/brain.js";
+
+const TEST_TRACER = trace.getTracer("vauban-agent-sdk.ports.test", "0.1.0");
 
 export class TestBrainPort implements BrainPort {
   readonly working: WorkingMemoryPort;
@@ -34,31 +52,87 @@ export class TestBrainPort implements BrainPort {
   }
 
   async archiveKnowledge(entry: BrainEntryInput): Promise<BrainEntry | null> {
-    const id = `test-${this.nextId++}`;
-    const created: BrainEntry = {
-      id,
-      content: entry.content,
-      category: entry.category,
-      tags: entry.tags,
-      metadata: entry.metadata as Record<string, unknown> | undefined,
-      created_at: new Date().toISOString(),
-    };
-    this.entries.set(id, created);
-    return created;
+    return TEST_TRACER.startActiveSpan(
+      "brain.archiveKnowledge",
+      {
+        attributes: {
+          "brain.entry.category": entry.category ?? "unknown",
+          "brain.entry.content_preview": entry.content.slice(0, 200),
+          "brain.entry.tags": entry.tags?.join(",") ?? "",
+          "vauban.port.name": "brain",
+          "vauban.port.impl": "TestBrainPort",
+        },
+      },
+      async (span: Span) => {
+        try {
+          const id = `test-${this.nextId++}`;
+          const created: BrainEntry = {
+            id,
+            content: entry.content,
+            category: entry.category,
+            tags: entry.tags,
+            metadata: entry.metadata as Record<string, unknown> | undefined,
+            created_at: new Date().toISOString(),
+          };
+          this.entries.set(id, created);
+          span.setAttribute("brain.entry.id", id);
+          span.setStatus({ code: SpanStatusCode.OK });
+          return created;
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          span.setStatus({ code: SpanStatusCode.ERROR, message });
+          if (err instanceof Error) span.recordException(err);
+          throw err;
+        } finally {
+          span.end();
+        }
+      }
+    );
   }
 
-  async queryKnowledge(query: string, filters?: BrainQueryFilters): Promise<BrainEntry[]> {
-    let results = Array.from(this.entries.values()).filter(
-      (e) => e.content.toLowerCase().includes(query.toLowerCase())
+  async queryKnowledge(
+    query: string,
+    filters?: BrainQueryFilters
+  ): Promise<BrainEntry[]> {
+    return TEST_TRACER.startActiveSpan(
+      "brain.queryKnowledge",
+      {
+        attributes: {
+          "brain.query.preview": query.slice(0, 200),
+          "brain.query.category": filters?.category ?? "none",
+          "brain.query.limit": filters?.limit ?? -1,
+          "vauban.port.name": "brain",
+          "vauban.port.impl": "TestBrainPort",
+        },
+      },
+      async (span: Span) => {
+        try {
+          let results = Array.from(this.entries.values()).filter((e) =>
+            e.content.toLowerCase().includes(query.toLowerCase())
+          );
+          if (filters?.category) {
+            results = results.filter((e) => e.category === filters.category);
+          }
+          if (filters?.tags && filters.tags.length > 0) {
+            results = results.filter((e) =>
+              e.tags?.some((t) => (filters.tags as string[]).includes(t))
+            );
+          }
+          const limit = (filters?.limit as number) ?? 10;
+          const sliced = results.slice(0, limit);
+          span.setAttribute("brain.query.result_count", sliced.length);
+          span.setStatus({ code: SpanStatusCode.OK });
+          return sliced;
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          span.setStatus({ code: SpanStatusCode.ERROR, message });
+          if (err instanceof Error) span.recordException(err);
+          throw err;
+        } finally {
+          span.end();
+        }
+      }
     );
-    if (filters?.category) {
-      results = results.filter((e) => e.category === filters.category);
-    }
-    if (filters?.tags && filters.tags.length > 0) {
-      results = results.filter((e) => e.tags?.some((t) => (filters.tags as string[]).includes(t)));
-    }
-    const limit = (filters?.limit as number) ?? 10;
-    return results.slice(0, limit);
   }
 
   /** Clear all entries. */