@vauban-org/agent-sdk 1.0.0 → 1.3.0

package/docs/attestation.md

@@ -0,0 +1,199 @@
+# Run Certificate Verification (Standalone)
+
+**Module:** `@vauban-org/agent-sdk/proof/cert-verify` · **Since:** CC v3.1 sprint-562 (Livrable D, 2026-05-14)
+
+The standalone verifier in `src/proof/cert-verify.ts` verifies a `SignedRunProofCertificate` without any database or network dependency. It is the verification counterpart to the CC server's signing surface (`src/proof/ed25519-signer.ts`) and implements [draft-vauban-skill-attestation-00 §5](https://datatracker.ietf.org/doc/draft-vauban-skill-attestation/).
+
+Suitable for: CI pipelines, third-party integrators, audits, and the `preste attest verify` CLI command.
+
+## Quick start
+
+```typescript
+import { verifyRunCertificate } from "@vauban-org/agent-sdk/proof/cert-verify";
+import { readFileSync } from "node:fs";
+
+const cert = JSON.parse(readFileSync("cert.json", "utf-8"));
+
+const result = verifyRunCertificate(cert);
+
+if (!result.valid) {
+  console.error(`Verification failed: ${result.reason} — ${result.details}`);
+  process.exit(1);
+}
+
+console.log("Certificate valid. hash:", result.recomputed_cert_hash_felt252);
+```
+
+---
+
+## Imports
+
+```typescript
+import {
+  verifyRunCertificate,
+  computeCertHashFelt252,
+  publicKeyFromSpkiB64,
+  CERT_MARKER_FELT,
+} from "@vauban-org/agent-sdk/proof/cert-verify";
+
+import type {
+  CertVerifyResult,
+  CertVerifyFailReason,
+  CertVerifyOptions,
+  SignedRunProofCertificateLike,
+  SignaturePayload,
+} from "@vauban-org/agent-sdk/proof/cert-verify";
+```
+
+---
+
+## Types
+
+```typescript
+interface CertVerifyResult {
+  valid: boolean;
+  reason?: CertVerifyFailReason;          // only when valid === false
+  details?: string;                       // human-readable context
+  recomputed_cert_hash_felt252: string;   // always present — useful for debug
+}
+
+type CertVerifyFailReason =
+  | "missing_signature"    // cert.signature field absent
+  | "wrong_alg"            // alg !== "Ed25519"
+  | "hash_mismatch"        // embedded cert_hash_felt252 != recomputed
+  | "kid_mismatch"         // expectedKid set and does not match
+  | "pubkey_unresolvable"  // SPKI base64 malformed or not Ed25519
+  | "signature_invalid"    // Ed25519 verify returns false
+  | "malformed_signature"; // signature.value is not valid base64 / wrong length
+
+interface CertVerifyOptions {
+  expectedPublicKey?: KeyObject;  // Node.js KeyObject (bypass embedded SPKI)
+  expectedKid?: string;           // pin to a specific key ID
+}
+```
+
+---
+
+## `verifyRunCertificate(cert, opts?)`
+
+```typescript
+function verifyRunCertificate(
+  cert: SignedRunProofCertificateLike,
+  opts?: CertVerifyOptions
+): CertVerifyResult
+```
+
+Returns synchronously — all crypto is Node.js built-in `node:crypto`. Never throws on verification failure; only throws when `cert` is not a plain object.
+
+`recomputed_cert_hash_felt252` is always returned regardless of outcome — use it to debug `hash_mismatch` failures without a separate call.
+
+### Basic verification
+
+```typescript
+const result = verifyRunCertificate(cert);
+if (!result.valid) {
+  console.error(`Invalid: ${result.reason} — ${result.details}`);
+}
+```
+
+### Pin to a known public key (recommended for production)
+
+```typescript
+import { publicKeyFromSpkiB64, verifyRunCertificate } from "@vauban-org/agent-sdk/proof/cert-verify";
+
+const pubkey = publicKeyFromSpkiB64(process.env["CC_ATTEST_PUBKEY_SPKI_B64"]!);
+
+const result = verifyRunCertificate(cert, { expectedPublicKey: pubkey });
+```
+
+`publicKeyFromSpkiB64` throws if the base64 is malformed or the key is not Ed25519. Call it once at startup and cache the `KeyObject`.
+
+### Pin to a key ID
+
+```typescript
+const result = verifyRunCertificate(cert, {
+  expectedKid: "cc-attest-2026-05",
+});
+// → reason: "kid_mismatch" if cert was signed with a different key
+```
+
+### CI pipeline — exit code gate
+
+```typescript
+import { verifyRunCertificate } from "@vauban-org/agent-sdk/proof/cert-verify";
+import { readFileSync } from "node:fs";
+
+const cert = JSON.parse(readFileSync("cert.json", "utf-8"));
+const { valid, reason, recomputed_cert_hash_felt252 } = verifyRunCertificate(cert);
+
+console.log(`hash: ${recomputed_cert_hash_felt252}`);
+process.exit(valid ? 0 : 1);
+```
+
+---
+
+## Verification algorithm
+
+Implements draft-vauban-skill-attestation-00 §5. Seven sequential checks — the first failure stops the chain:
+
+| Step | Check | Failure reason |
+|------|-------|----------------|
+| 1 | `cert.signature` field is present | `missing_signature` |
+| 2 | `signature.alg === "Ed25519"` | `wrong_alg` |
+| 3 | Strip `signature`, JCS-canonicalize (RFC 8785 subset: sorted keys, `-0 → 0`), SHA-256 first 31 bytes → felt252, Poseidon(`[0x1, sha_felt, CERT_MARKER_FELT]`) — compare with `signature.cert_hash_felt252` | `hash_mismatch` |
+| 4 | If `opts.expectedKid` set, compare with `signature.kid` | `kid_mismatch` |
+| 5 | Resolve public key: `opts.expectedPublicKey` if provided, else `publicKeyFromSpkiB64(signature.pubkey_spki_b64)` | `pubkey_unresolvable` |
+| 6 | Decode `signature.value` from base64, assert 64 bytes | `malformed_signature` |
+| 7 | Ed25519 verify: `crypto.verify(null, felt252Bytes(recomputed), pubkey, sigBytes)` | `signature_invalid` |
+
+**`CERT_MARKER_FELT`** is the domain separator — UTF-8 `"run_cert"` encoded as a felt252 (right-aligned, zero-padded). It prevents cross-context signature reuse: a signature over a different cert type cannot satisfy the Poseidon preimage.
+
+---
+
+## `computeCertHashFelt252(cert)`
+
+Standalone hash computation — useful for debugging `hash_mismatch` failures.
+
+```typescript
+import { computeCertHashFelt252 } from "@vauban-org/agent-sdk/proof/cert-verify";
+
+const expected = cert.signature?.cert_hash_felt252;
+const recomputed = computeCertHashFelt252(cert);
+
+if (expected !== recomputed) {
+  console.error("Hash mismatch:");
+  console.error("  embedded  :", expected);
+  console.error("  recomputed:", recomputed);
+}
+```
+
+`computeCertHashFelt252` strips the embedded `signature` field before hashing — calling it on a signed cert and on the pre-signature cert produces the same result.
+
+---
+
+## Security considerations
+
+!!! warning "Treat embedded `pubkey_spki_b64` as a key-discovery hint, not a security guarantee"
+    The `pubkey_spki_b64` field in `signature` helps resolve the signing key for display and debugging, but an attacker can substitute it with their own public key and produce a valid self-consistent signature.
+
+    For production use, always pin to a known public key via `opts.expectedPublicKey` (loaded from a trusted source such as an environment variable, K8s secret, or a JWKS registry keyed on `signature.kid`). Never accept a certificate as authoritative based solely on its embedded public key.
+
+---
+
+## `preste attest verify` CLI
+
+The standalone verifier is the engine behind the CLI command:
+
+```bash
+preste attest verify cert.json
+# Exit 0: certificate valid
+# Exit 1: verification failed — reason printed to stderr
+
+preste attest verify cert.json --kid cc-attest-2026-05
+# Adds kid pinning
+
+preste attest verify cert.json --pubkey "$CC_ATTEST_PUBKEY_SPKI_B64"
+# Pins to an explicit SPKI base64 public key
+```
+
+The CLI sets `process.exitCode` to `1` on failure so it composes naturally with `&&` in shell scripts and CI steps.

package/docs/identity.md

@@ -0,0 +1,193 @@
+# Agent Identity & Persona
+
+**Module:** `@vauban-org/agent-sdk` · **Since:** CC v3.1 sprint-562 (Livrable E, 2026-05-14)
+
+An `AgentPersona` is a structured description of how an agent communicates — tone, formality, domain expertise, and response-shape preferences. The persona travels from Brain Tier 3 (semantic storage) through the CC server as a system-prompt prefix, and can be overridden locally via `~/.preste/persona.yaml`.
+
+## Quick start
+
+```typescript
+import {
+  buildPersonaPromptBlock,
+  mergePersona,
+  DEFAULT_PERSONA,
+  validatePersona,
+} from "@vauban-org/agent-sdk";
+import type { AgentPersona } from "@vauban-org/agent-sdk";
+
+const persona: AgentPersona = {
+  identity: {
+    name: "ARCHITECT",
+    role: "Senior Cairo/TypeScript engineer",
+    tone: "concise",
+    formality: "technical",
+    language: "en",
+  },
+  domain_expertise: ["Starknet", "TypeScript", "ZK proofs"],
+  communication: {
+    acknowledgment_style: "minimal",
+    explain_reasoning: "on_error",
+  },
+};
+
+const systemPrompt =
+  "You are an agent in the Vauban ecosystem." +
+  buildPersonaPromptBlock(persona);
+```
+
+The `buildPersonaPromptBlock` call appends the block only when actionable fields are present — it is safe to concatenate unconditionally.
+
+---
+
+## `AgentPersona` schema
+
+All fields are optional. Zod validation enforces the limits below; `PersonaSchema.parse(input)` throws on violation.
+
+```typescript
+interface AgentPersona {
+  identity?: {
+    name?: string;       // max 64 chars
+    role?: string;       // max 256 chars
+    tone?: "concise" | "detailed" | "pedagogical";
+    formality?: "casual" | "formal" | "technical";
+    language?: string;   // BCP 47, e.g. "en", "fr-FR"
+  };
+  traits?: string[];           // max 16 items, max 64 chars each
+  domain_expertise?: string[]; // max 32 items, max 128 chars each
+  communication?: {
+    max_response_length?: number;
+    use_analogies?: boolean;
+    explain_reasoning?: "always" | "on_error" | "never";
+    acknowledgment_style?: "minimal" | "detailed" | "none";
+  };
+}
+```
+
+`DEFAULT_PERSONA` is applied before any user-defined value:
+
+```typescript
+const DEFAULT_PERSONA: AgentPersona = {
+  identity: { tone: "concise", formality: "technical", language: "en" },
+  traits: [],
+  domain_expertise: [],
+  communication: { explain_reasoning: "on_error", acknowledgment_style: "minimal" },
+};
+```
+
+---
+
+## `buildPersonaPromptBlock(persona)`
+
+Converts an `AgentPersona` to a compact system-prompt block bounded by `--- persona ---` / `--- end persona ---` markers.
+
+```typescript
+import { buildPersonaPromptBlock } from "@vauban-org/agent-sdk";
+
+const block = buildPersonaPromptBlock({
+  identity: { name: "SCRIBE", tone: "pedagogical", formality: "formal" },
+  domain_expertise: ["technical writing", "API documentation"],
+  communication: { explain_reasoning: "always" },
+});
+
+// block ===
+// \n--- persona ---
+// You are SCRIBE.
+// Communication style: pedagogical, formal.
+// Domain expertise: technical writing, API documentation.
+// Always explain your reasoning step by step.
+// --- end persona ---
+```
+
+**Properties:**
+
+- Returns `""` when the persona has no actionable fields — safe for unconditional concatenation.
+- `language` field only emits an instruction when it differs from `"en"`.
+- Empty `traits` / `domain_expertise` arrays produce no output.
+- The leading `\n` ensures correct spacing when appended to an existing system prompt.
+
+---
+
+## Merge semantics
+
+`mergePersona(base, local)` applies `local` on top of `base` field-by-field. Brain Tier 3 is the base; `~/.preste/persona.yaml` is the local override.
+
+```typescript
+import { mergePersona, DEFAULT_PERSONA } from "@vauban-org/agent-sdk";
+
+const brainPersona: AgentPersona = {
+  identity: { name: "BUILDER", tone: "concise" },
+  domain_expertise: ["Cairo", "TypeScript"],
+};
+
+const localOverride: AgentPersona = {
+  identity: { tone: "detailed" },       // overrides tone only
+  domain_expertise: ["Rust"],           // REPLACES the array entirely
+};
+
+const resolved = mergePersona(
+  mergePersona(DEFAULT_PERSONA, brainPersona),
+  localOverride,
+);
+// resolved.identity.name === "BUILDER"  (from brainPersona)
+// resolved.identity.tone === "detailed" (from localOverride)
+// resolved.domain_expertise === ["Rust"] (array replaced, not extended)
+```
+
+!!! warning "Array replacement semantics"
+    `traits` and `domain_expertise` are **replaced**, not extended. If you want to extend the Brain-stored array, concatenate before calling `mergePersona`:
+    ```typescript
+    const extended = mergePersona(base, {
+      ...local,
+      domain_expertise: [...(base.domain_expertise ?? []), ...(local.domain_expertise ?? [])],
+    });
+    ```
+
+---
+
+## System-level injection (CC server)
+
+Set `CC_AGENT_PERSONA_JSON` on the CC server to inject the persona as a system message prefix for every agent call, without modifying agent code.
+
+**Generate the env value:**
+
+```bash
+echo '{"identity":{"name":"ARCHITECT","role":"Senior Cairo/TypeScript engineer","tone":"concise","formality":"technical"},"domain_expertise":["Starknet","TypeScript","ZK proofs"],"communication":{"acknowledgment_style":"minimal","explain_reasoning":"on_error"}}' | base64 -w0
+```
+
+```bash
+export CC_AGENT_PERSONA_JSON="<base64 output>"
+```
+
+The CC server decodes, validates via `PersonaSchema.parse`, and calls `buildPersonaPromptBlock` before prepending to each agent system message.
+
+---
+
+## CLI persona management
+
+The `preste persona` sub-command manages the local `~/.preste/persona.yaml` override file.
+
+```bash
+preste persona show                                         # display resolved persona (Brain + local merge)
+preste persona set --name ARCHITECT --role "..." --tone concise --formality technical
+preste persona export persona.yaml                          # write to YAML file
+preste persona import persona.yaml                          # load from YAML file (validates schema)
+preste persona reset                                        # delete ~/.preste/persona.yaml (revert to Brain-only)
+```
+
+`preste persona show` prints the fully-resolved persona (Brain base + local override + defaults) and the rendered `buildPersonaPromptBlock` output so you can inspect what the model will receive.
+
+---
+
+## Validation
+
+```typescript
+import { validatePersona } from "@vauban-org/agent-sdk";
+
+try {
+  const persona = validatePersona(untrustedInput);
+} catch (err) {
+  // ZodError — inspect err.issues for field-level messages
+}
+```
+
+`validatePersona` wraps `PersonaSchema.parse` and throws `ZodError` on invalid input. Call it at ingestion boundaries (e.g., when loading `~/.preste/persona.yaml` or deserializing from Brain).

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)