@vauban-org/agent-sdk 1.2.0 → 1.4.0

package/dist/telemetry/sinks/otlp.js.map

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

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

@@ -0,0 +1,32 @@
+/**
+ * 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 type { 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;
+}
+/**
+ * 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 declare function localSqliteTelemetrySink(opts?: LocalSqliteTelemetrySinkOptions): TelemetrySink;
+//# sourceMappingURL=sqlite.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite.d.ts","sourceRoot":"","sources":["../../../src/telemetry/sinks/sqlite.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAMH,OAAO,KAAK,EAIV,aAAa,EACd,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,+BAA+B;IAC9C;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qEAAqE;IACrE,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAkED;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,GAAE,+BAAoC,GACzC,aAAa,CA2Ff"}

package/dist/telemetry/sinks/sqlite.js

@@ -0,0 +1,170 @@
+/**
+ * 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";
+// ─── 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 = {}) {
+    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) {
+            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, delta) {
+            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, event) {
+            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) {
+    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, readonly) {
+    try {
+        // Dynamic require so better-sqlite3 stays optional.
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const createRequire = require("node:module").createRequire;
+        const req = createRequire(import.meta.url);
+        const BetterSqlite = req("better-sqlite3");
+        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) {
+    return {
+        name: `sqlite:degraded(${path})`,
+        async start() {
+            /* no-op when better-sqlite3 missing */
+        },
+        async step() {
+            /* no-op */
+        },
+        async finish() {
+            /* no-op */
+        },
+    };
+}
+//# sourceMappingURL=sqlite.js.map

package/dist/telemetry/sinks/sqlite.js.map

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

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

@@ -0,0 +1,22 @@
+/**
+ * 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 { 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 declare function stdoutTelemetrySink(opts?: StdoutTelemetrySinkOptions): TelemetrySink;
+//# sourceMappingURL=stdout.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"stdout.d.ts","sourceRoot":"","sources":["../../../src/telemetry/sinks/stdout.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAIV,aAAa,EACd,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,0BAA0B;IACzC,wDAAwD;IACxD,MAAM,CAAC,EAAE,MAAM,CAAC,cAAc,CAAC;IAC/B,iEAAiE;IACjE,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,GAAE,0BAA+B,GACpC,aAAa,CA4Bf"}

package/dist/telemetry/sinks/stdout.js

@@ -0,0 +1,38 @@
+/**
+ * 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
+ */
+/**
+ * Default sink for dev visibility. Zero dependency, zero I/O latency
+ * (synchronous write to stream).
+ */
+export function stdoutTelemetrySink(opts = {}) {
+    const stream = opts.stream ?? process.stderr;
+    const useJson = opts.json ?? true;
+    function emit(event) {
+        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) {
+            emit({ telemetry: "run.start", ...event });
+        },
+        async step(runId, delta) {
+            emit({ telemetry: "run.step", runId, ...delta });
+        },
+        async finish(runId, event) {
+            emit({ telemetry: "run.finish", runId, ...event });
+        },
+    };
+}
+//# sourceMappingURL=stdout.js.map

package/dist/telemetry/sinks/stdout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdout.js","sourceRoot":"","sources":["../../../src/telemetry/sinks/stdout.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAgBH;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CACjC,OAAmC,EAAE;IAErC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC;IAC7C,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC;IAElC,SAAS,IAAI,CAAC,KAA8B;QAC1C,MAAM,IAAI,GAAG,OAAO;YAClB,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC;YACvB,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC;iBAClB,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC;iBAC5C,IAAI,CAAC,GAAG,CAAC,CAAC;QACjB,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,IAAI,CAAC,CAAC;IAC5B,CAAC;IAED,OAAO;QACL,IAAI,EAAE,QAAQ;QAEd,KAAK,CAAC,KAAK,CAAC,KAAwB;YAClC,IAAI,CAAC,EAAE,SAAS,EAAE,WAAW,EAAE,GAAG,KAAK,EAAE,CAAC,CAAC;QAC7C,CAAC;QAED,KAAK,CAAC,IAAI,CAAC,KAAa,EAAE,KAAuB;YAC/C,IAAI,CAAC,EAAE,SAAS,EAAE,UAAU,EAAE,KAAK,EAAE,GAAG,KAAK,EAAE,CAAC,CAAC;QACnD,CAAC;QAED,KAAK,CAAC,MAAM,CAAC,KAAa,EAAE,KAAyB;YACnD,IAAI,CAAC,EAAE,SAAS,EAAE,YAAY,EAAE,KAAK,EAAE,GAAG,KAAK,EAAE,CAAC,CAAC;QACrD,CAAC;KACF,CAAC;AACJ,CAAC"}

package/docs/telemetry/migration.md

@@ -0,0 +1,155 @@
+# Migration : 1.2 → 1.3
+
+!!! success "Zero breaking changes"
+    Existing 1.2.x consumers continue to work unchanged. All new APIs are
+    additive.
+
+## TL;DR
+
+- `AgentRunTracker` still works. Marked deprecated, will be removed in 2.0.
+- New `telemetry` field on `OODAAgentConfig`. Opt-in.
+- 4 new sinks shipped : `stdout`, `sqlite`, `otlp` in core ; `cc` in
+  `@vauban-org/cc-telemetry`.
+
+## What changed
+
+### `AgentRunFinalStatus` adds `"skipped"`
+
+Before :
+
+```ts
+type AgentRunFinalStatus = "success" | "failed" | "timeout" | "incoherent";
+```
+
+After :
+
+```ts
+type AgentRunFinalStatus = "success" | "failed" | "skipped" | "timeout" | "incoherent";
+```
+
+`"skipped"` distinguishes session_guard / risk_guard / heap_exceeded
+short-circuits from real successes. Existing exhaustive `switch` statements
+on this type will need to add a case (TypeScript will surface it).
+
+For the new `TelemetryRunStatus` type (used by the new sinks), see the
+[port.ts source](https://github.com/vauban-org/command-center/blob/main/packages/agent-sdk/src/telemetry/port.ts).
+
+### New optional `OODAAgentConfig.telemetry`
+
+```ts
+interface OODAAgentConfig {
+  // …existing fields…
+  readonly telemetry?: TelemetrySink;   // NEW, optional
+}
+```
+
+When set, the OODA loop auto-emits `start` + `step` + `finish` events.
+When omitted, behavior is identical to 1.2.
+
+### Legacy `AgentRunTracker` is deprecated
+
+```ts
+import { createAgentRunTracker } from "@vauban-org/agent-sdk";   // deprecated
+
+const tracker = createAgentRunTracker(db);
+// Still works, still INSERTs into agent_run. Will be removed in 2.0.
+```
+
+Migration target :
+
+```ts
+import {
+  createTelemetryBus,
+  localSqliteTelemetrySink,
+} from "@vauban-org/agent-sdk";
+import { commandCenterTelemetrySink } from "@vauban-org/cc-telemetry";
+
+const telemetry = createTelemetryBus({
+  sinks: [
+    localSqliteTelemetrySink(),
+    commandCenterTelemetrySink({ apiKey: process.env.VAUBAN_API_KEY! }),
+  ],
+});
+
+createOODAAgent({
+  agentId: "my-agent",
+  telemetry,
+  // …no more `createAgentRunTracker(db)` needed
+});
+```
+
+## Recipes for common migrations
+
+### From `AgentRunTracker` to sinks
+
+Before :
+
+```ts
+const tracker = createAgentRunTracker(db);
+const uuid = await tracker.start({ agentId, agentVersion, runId, model, provider });
+await tracker.recordStep(uuid, { inputTokens, outputTokens, costUsd });
+await tracker.finish(uuid, { status: "success" });
+```
+
+After :
+
+```ts
+// No imperative calls — the OODA loop handles it.
+createOODAAgent({
+  agentId: "my-agent",
+  telemetry: localSqliteTelemetrySink(),
+});
+// runCycle() automatically emits start/step/finish.
+```
+
+If you ran tracker calls *outside* the OODA loop (e.g. from a custom
+event handler), you can still use it ; the loop's telemetry and the
+custom calls coexist (they write to different tables in v1.3 :
+`agent_run` for legacy tracker, `telemetry_run_step` for SDK sinks).
+
+### From `console.log` to stdoutTelemetrySink
+
+Before :
+
+```ts
+console.log("[my-agent] cycle start", { runId, agentId });
+```
+
+After :
+
+```ts
+createOODAAgent({
+  agentId: "my-agent",
+  telemetry: stdoutTelemetrySink(),
+});
+```
+
+You get structured JSON automatically, plus the same data lands in any
+other sinks you configure later.
+
+## Removed (only in 2.0, not yet)
+
+Targeted for removal in **2.0** (no earlier than Q4 2026) :
+
+- `createAgentRunTracker(db)`
+- `AgentRunTracker` interface
+- `tracking/agent-run-tracker.ts` module
+- `tracking/cost-tracked-agent-run-tracker.ts` (consumer in CC backend)
+
+Until then, both APIs coexist.
+
+## Testing the upgrade
+
+```bash
+# Pin to old version
+pnpm add @vauban-org/agent-sdk@1.2.0
+
+# Pin to new version
+pnpm add @vauban-org/agent-sdk@1.3.0
+
+# Run your test suite
+pnpm test
+```
+
+You should see 0 failures, 0 new warnings (other than the deprecation
+notice if you still call `createAgentRunTracker`).

package/docs/telemetry/overview.md

@@ -0,0 +1,154 @@
+# Telemetry Overview
+
+!!! info "Status — public-experimental"
+    Introduced in `@vauban-org/agent-sdk@1.3.0` (ADR-ECO-039). Interface
+    stable, additional event fields may be added before 2.0.
+
+The agent-sdk exposes a **port-based telemetry pipeline** : agents emit
+lifecycle events (`start` → `step…` → `finish`) and configurable **sinks**
+decide where those events go. Sovereignty is preserved by default — no
+network calls happen unless you explicitly opt in.
+
+## Why a port + sinks pattern ?
+
+Before v1.3, the SDK had an implicit DB coupling (`AgentRunTracker.start`
+INSERTed directly into a Command Center–specific `agent_run` table). That
+violated three invariants : sovereignty (SDK unusable without the CC DB),
+boundary discipline (SDK knowing CC schema), and standalone-product
+design (CC should be an optional consumer).
+
+The port pattern fixes all three. See the design rationale in
+[ADR-ECO-039](https://github.com/vauban-org/vauban-gouvernance/blob/main/governance/decisions/ADR-ECO-039-sdk-telemetry-port.md).
+
+## Three usage modes
+
+```mermaid
+graph TD
+  A[OODA loop runCycle()] -->|TelemetrySink| B[TelemetryBus]
+  B --> S1[stdoutTelemetrySink]
+  B --> S2[localSqliteTelemetrySink]
+  B --> S3[otlpTelemetrySink]
+  B --> S4["commandCenterTelemetrySink<br/>(separate npm pkg)"]
+
+  S1 -.-> O1[stderr / pino-pretty]
+  S2 -.-> O2["~/.vauban/runs.db"]
+  S3 -.-> O3["Langfuse / Tempo / Jaeger"]
+  S4 -.-> O4["command.vauban.tech<br/>or self-hosted CC"]
+```
+
+### Mode 1 — Standalone (sovereign default)
+
+Zero phone-home. Zero account required. Runs everywhere.
+
+```ts
+import {
+  createOODAAgent,
+  createTelemetryBus,
+  stdoutTelemetrySink,
+  localSqliteTelemetrySink,
+} from "@vauban-org/agent-sdk";
+
+createOODAAgent({
+  agentId: "my-agent",
+  /* …other config… */
+  telemetry: createTelemetryBus({
+    sinks: [
+      stdoutTelemetrySink(),
+      localSqliteTelemetrySink(),     // ~/.vauban/runs.db by default
+    ],
+  }),
+});
+```
+
+Inspect locally via `sqlite3` or the upcoming `vauban-agent runs list` CLI.
+
+### Mode 2 — Free Vauban CC SaaS
+
+Adds remote backup + a hosted dashboard at `command.vauban.tech`.
+
+```bash
+pnpm add @vauban-org/cc-telemetry
+```
+
+```ts
+import {
+  createOODAAgent,
+  createTelemetryBus,
+  localSqliteTelemetrySink,
+} from "@vauban-org/agent-sdk";
+import { commandCenterTelemetrySink } from "@vauban-org/cc-telemetry";
+
+createOODAAgent({
+  agentId: "my-agent",
+  telemetry: createTelemetryBus({
+    sinks: [
+      localSqliteTelemetrySink(),                                    // sovereign mirror
+      commandCenterTelemetrySink({ apiKey: process.env.VAUBAN_API_KEY! }),
+    ],
+  }),
+});
+```
+
+Free tier policy : **1 000 runs / month + 7 day retention** (see
+[ADR-ECO-039 §3](https://github.com/vauban-org/vauban-gouvernance/blob/main/governance/decisions/ADR-ECO-039-sdk-telemetry-port.md)).
+Sign up at [`command.vauban.tech`](https://command.vauban.tech).
+
+### Mode 3 — Tiered (Team / Pro / Sovereign)
+
+Same code as Mode 2. The API key prefix (`vauban_team_*` / `vauban_pro_*` /
+`vauban_sovereign_*`) determines server-side entitlement. Pro tier signs
+each run with a Vauban Claim Algebra attestation ; Sovereign runs in a
+TDX/SEV-SNP enclave with L3 Madara anchoring. See
+[sinks/cc.md](sinks/cc.md#tiers).
+
+### Mode 4 — Self-hosted Command Center
+
+Compatible with the AGPL CC backend (per [ADR-ECO-014](https://github.com/vauban-org/vauban-gouvernance/blob/main/governance/decisions/ADR-ECO-014-cc-oss-release.md)).
+
+```ts
+commandCenterTelemetrySink({
+  apiKey: "internal",
+  baseUrl: "https://cc.myorg.internal",
+});
+```
+
+## Privacy guarantees
+
+| # | Guarantee | Enforced by |
+|---|---|---|
+| 1 | Zero phone-home by default | No sinks configured = no network |
+| 2 | Local sink always available | `localSqliteTelemetrySink` ships with SDK |
+| 3 | PII never crosses sinks | `metadata` hashed unless `includePayloads: true` |
+| 4 | Tenant isolation | RLS in CC backend, scoped Bearer keys |
+| 5 | Audit log of active sinks | `vauban-agent telemetry status` (upcoming) |
+| 6 | Sink failures never block agent | TelemetryBus isolates per-sink failures |
+
+## Failure modes & guarantees
+
+- **One sink crashes** → others continue. The agent loop is never blocked.
+- **Network sink unreachable** → events queue locally up to `maxQueueDepth`
+  (default 1000), then drop-oldest with a Prometheus-friendly counter.
+- **OOM / heap exceeded** → no retry storm ; the agent enters `skipped`
+  state with a `stopReason: "heap_exceeded:Xmb"` that surfaces in every
+  sink.
+- **CC backend down** → SDK auto-retries 5xx with exponential backoff +
+  jitter. 4xx (auth, quota) are NOT retried (would only burn quota).
+
+## Where it sits relative to Langfuse
+
+Both coexist by design ([Brain entry 1b9ab97d](https://command.vauban.tech/brain/1b9ab97d)) :
+
+| Layer | What | Tool |
+|---|---|---|
+| Token-level | Per LLM call, latency, tokens, cost | Langfuse self-host |
+| **Run-level** | **Per OODA cycle, status, outcome** | **TelemetryPort (this module)** |
+| Outcome-level | Business value, HITL, proof | CC `outcome` table + L3 anchor |
+
+## Next steps
+
+- [stdout sink](sinks/stdout.md) — dev visibility
+- [SQLite sink](sinks/sqlite.md) — sovereign local mirror
+- [OTLP sink](sinks/otlp.md) — push to any OpenTelemetry receiver
+- [CC sink](sinks/cc.md) — Vauban Command Center (free → sovereign)
+- [Privacy & spotlighting](privacy.md)
+- [Migration 1.2 → 1.3](migration.md)