@vauban-org/agent-sdk 1.0.0 → 1.3.0

package/src/telemetry/bus.test.ts

@@ -0,0 +1,231 @@
+/**
+ * TelemetryBus — fanout, isolation, backpressure tests.
+ *
+ * Ref: command-center:sprint-693:telemetry-bus
+ */
+
+import { describe, expect, it, vi } from "vitest";
+
+import { createTelemetryBus } from "./bus.js";
+import type { TelemetrySink } from "./port.js";
+
+function makeSink(
+  name: string,
+  behavior: "ok" | "throw" = "ok"
+): TelemetrySink {
+  const calls = { start: 0, step: 0, finish: 0 };
+  return {
+    name,
+    async start() {
+      calls.start += 1;
+      if (behavior === "throw") throw new Error(`${name}.start failed`);
+    },
+    async step() {
+      calls.step += 1;
+      if (behavior === "throw") throw new Error(`${name}.step failed`);
+    },
+    async finish() {
+      calls.finish += 1;
+      if (behavior === "throw") throw new Error(`${name}.finish failed`);
+    },
+    // expose counters via name munging — vitest reads `(sink as any).calls`
+    // @ts-expect-error — test affordance
+    calls,
+  };
+}
+
+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",
+};
+
+const STEP_DELTA = {
+  stepIndex: 0,
+  kind: "observe",
+  status: "completed" as const,
+  inputTokens: 10,
+  outputTokens: 20,
+  costUsd: 0.001,
+};
+
+const FINISH = {
+  status: "success" as const,
+  finishedAt: "2026-05-16T17:00:05.000Z",
+};
+
+describe("createTelemetryBus", () => {
+  it("returns a NOOP sink when sinks=[]", async () => {
+    const bus = createTelemetryBus({ sinks: [] });
+    expect(bus.name).toBe("noop");
+    await expect(bus.start(RUN_START)).resolves.toBeUndefined();
+    expect(bus.counters.dispatched).toBe(0);
+  });
+
+  it("fans out start/step/finish to every sink (blocking mode)", async () => {
+    const a = makeSink("a");
+    const b = makeSink("b");
+    const bus = createTelemetryBus({
+      sinks: [a, b],
+      nonBlocking: false,
+    });
+
+    await bus.start(RUN_START);
+    await bus.step(RUN_START.runId, STEP_DELTA);
+    await bus.finish(RUN_START.runId, FINISH);
+
+    // @ts-expect-error — test affordance
+    expect(a.calls).toEqual({ start: 1, step: 1, finish: 1 });
+    // @ts-expect-error — test affordance
+    expect(b.calls).toEqual({ start: 1, step: 1, finish: 1 });
+    expect(bus.counters.dispatched).toBe(6); // 3 events × 2 sinks
+    expect(bus.counters.sinkErrors).toBe(0);
+  });
+
+  it("isolates failures — one sink throwing does not affect others", async () => {
+    const good = makeSink("good");
+    const bad = makeSink("bad", "throw");
+    const warn = vi.fn();
+    const bus = createTelemetryBus({
+      sinks: [good, bad],
+      logger: { warn, error: () => {} },
+      nonBlocking: false,
+    });
+
+    await bus.start(RUN_START);
+    await bus.step(RUN_START.runId, STEP_DELTA);
+    await bus.finish(RUN_START.runId, FINISH);
+
+    // @ts-expect-error
+    expect(good.calls).toEqual({ start: 1, step: 1, finish: 1 });
+    // @ts-expect-error
+    expect(bad.calls).toEqual({ start: 1, step: 1, finish: 1 });
+    expect(bus.counters.sinkErrors).toBe(3);
+    expect(warn).toHaveBeenCalledTimes(3);
+    expect(warn.mock.calls[0]![1]).toMatch(/isolated/);
+  });
+
+  it("backpressure: drops oldest events when queue exceeds maxQueueDepth", async () => {
+    // Pending-resolver sink — caller controls when each call resolves.
+    const pending: Array<() => void> = [];
+    const blockingSink: TelemetrySink = {
+      name: "slow",
+      async start() {
+        await new Promise<void>((res) => {
+          pending.push(res);
+        });
+      },
+      async step() {},
+      async finish() {},
+    };
+    const warn = vi.fn();
+    const bus = createTelemetryBus({
+      sinks: [blockingSink],
+      logger: { warn, error: () => {} },
+      nonBlocking: true,
+      maxQueueDepth: 3,
+    });
+
+    // Enqueue 6 starts — 1 enters dispatch and blocks; the next 3 fill the
+    // queue; the 5th and 6th cause overflow (drop oldest).
+    for (let i = 0; i < 6; i++) {
+      await bus.start({ ...RUN_START, runId: `run-${i}` });
+    }
+    expect(bus.counters.dropped).toBeGreaterThanOrEqual(1);
+
+    // Release all pending dispatches so flush() resolves.
+    while (pending.length > 0 || bus.counters.dispatched < 4) {
+      const r = pending.shift();
+      r?.();
+      await new Promise((res) => setTimeout(res, 0));
+    }
+    await bus.flush();
+  }, 10_000);
+
+  it("non-blocking mode returns immediately", async () => {
+    let resolveSink: (() => void) | undefined;
+    const sink: TelemetrySink = {
+      name: "slow",
+      async start() {
+        await new Promise<void>((res) => {
+          resolveSink = res;
+        });
+      },
+      async step() {},
+      async finish() {},
+    };
+    const bus = createTelemetryBus({ sinks: [sink], nonBlocking: true });
+
+    const t0 = Date.now();
+    await bus.start(RUN_START); // should return immediately
+    const elapsed = Date.now() - t0;
+    expect(elapsed).toBeLessThan(50);
+    expect(bus.counters.dispatched).toBe(0); // not dispatched yet
+
+    resolveSink?.();
+    await bus.flush();
+  });
+
+  it("flush awaits in-flight dispatches", async () => {
+    const sink = makeSink("a");
+    const bus = createTelemetryBus({ sinks: [sink], nonBlocking: true });
+
+    await bus.start(RUN_START);
+    await bus.step(RUN_START.runId, STEP_DELTA);
+    await bus.finish(RUN_START.runId, FINISH);
+    await bus.flush();
+
+    // @ts-expect-error
+    expect(sink.calls).toEqual({ start: 1, step: 1, finish: 1 });
+    expect(bus.counters.dispatched).toBe(3);
+  });
+
+  it("preserves FIFO order per sink", async () => {
+    const events: string[] = [];
+    const sink: TelemetrySink = {
+      name: "ordered",
+      async start(e) {
+        events.push(`start:${e.runId}`);
+      },
+      async step(runId, d) {
+        events.push(`step:${runId}:${d.stepIndex}`);
+      },
+      async finish(runId) {
+        events.push(`finish:${runId}`);
+      },
+    };
+    const bus = createTelemetryBus({ sinks: [sink], nonBlocking: true });
+
+    await bus.start(RUN_START);
+    await bus.step(RUN_START.runId, { ...STEP_DELTA, stepIndex: 0 });
+    await bus.step(RUN_START.runId, { ...STEP_DELTA, stepIndex: 1 });
+    await bus.finish(RUN_START.runId, FINISH);
+    await bus.flush();
+
+    expect(events).toEqual([
+      `start:${RUN_START.runId}`,
+      `step:${RUN_START.runId}:0`,
+      `step:${RUN_START.runId}:1`,
+      `finish:${RUN_START.runId}`,
+    ]);
+  });
+
+  it("counts dispatched accurately under mixed success/failure", async () => {
+    const good = makeSink("good");
+    const bad = makeSink("bad", "throw");
+    const bus = createTelemetryBus({
+      sinks: [good, bad],
+      nonBlocking: false,
+      logger: { warn: () => {}, error: () => {} },
+    });
+
+    await bus.start(RUN_START);
+    await bus.finish(RUN_START.runId, FINISH);
+
+    expect(bus.counters.dispatched).toBe(2); // good's 2 events
+    expect(bus.counters.sinkErrors).toBe(2); // bad's 2 events
+  });
+});

package/src/telemetry/bus.ts

@@ -0,0 +1,241 @@
+/**
+ * TelemetryBus — fanout to multiple {@link TelemetrySink}s, non-blocking.
+ *
+ * Invariants :
+ *   1. Sink failures are ISOLATED — one sink throwing never affects the others
+ *      nor the host agent loop. Failures are logged via the bus logger.
+ *   2. The bus itself implements {@link TelemetrySink}, so it can be passed
+ *      transparently to consumers expecting a single sink (composition).
+ *   3. When `nonBlocking: true` (default), `start`/`step`/`finish` return
+ *      immediately and dispatch in background. Errors surface via the logger.
+ *   4. Backpressure : if internal queue > `maxQueueDepth`, oldest events are
+ *      dropped and counted.
+ *
+ * Ref: command-center:sprint-693:telemetry-bus
+ */
+
+import {
+  NOOP_TELEMETRY_SINK,
+  type TelemetryRunFinish,
+  type TelemetryRunStart,
+  type TelemetryRunStep,
+  type TelemetrySink,
+} from "./port.js";
+
+// ─── Minimal logger interface (avoid SDK dep) ────────────────────────────────
+
+export interface TelemetryLogger {
+  warn(obj: Record<string, unknown>, msg?: string): void;
+  error(obj: Record<string, unknown>, msg?: string): void;
+}
+
+const NOOP_LOGGER: TelemetryLogger = {
+  warn: () => {
+    /* no-op */
+  },
+  error: () => {
+    /* no-op */
+  },
+};
+
+// ─── Bus options ─────────────────────────────────────────────────────────────
+
+export interface TelemetryBusOptions {
+  sinks: readonly TelemetrySink[];
+  /** Pino-compatible logger. Defaults to no-op. */
+  logger?: TelemetryLogger;
+  /**
+   * When true (default), `start/step/finish` resolve immediately and dispatch
+   * in background. Set false in tests for deterministic assertions.
+   */
+  nonBlocking?: boolean;
+  /**
+   * Max number of in-flight events per sink before dropping oldest.
+   * Defaults to 1000.
+   */
+  maxQueueDepth?: number;
+}
+
+// ─── Telemetry counters (exposed for Prometheus or tests) ────────────────────
+
+export interface TelemetryCounters {
+  /** Events dropped due to queue overflow. */
+  readonly dropped: number;
+  /** Sink errors caught and isolated. */
+  readonly sinkErrors: number;
+  /** Events successfully dispatched. */
+  readonly dispatched: number;
+}
+
+// ─── Implementation ──────────────────────────────────────────────────────────
+
+interface PendingEvent {
+  kind: "start" | "step" | "finish";
+  exec: (sink: TelemetrySink) => Promise<unknown>;
+}
+
+class TelemetryBusImpl implements TelemetrySink {
+  readonly name = "telemetry-bus";
+
+  private readonly _sinks: readonly TelemetrySink[];
+  private readonly _logger: TelemetryLogger;
+  private readonly _nonBlocking: boolean;
+  private readonly _maxQueueDepth: number;
+  /** Per-sink queue of pending events (FIFO). */
+  private readonly _queues: PendingEvent[][];
+  /** Per-sink drain promise (single-flight). */
+  private readonly _draining: Array<Promise<void> | null>;
+
+  private _dropped = 0;
+  private _sinkErrors = 0;
+  private _dispatched = 0;
+
+  constructor(opts: TelemetryBusOptions) {
+    this._sinks = opts.sinks;
+    this._logger = opts.logger ?? NOOP_LOGGER;
+    this._nonBlocking = opts.nonBlocking ?? true;
+    this._maxQueueDepth = opts.maxQueueDepth ?? 1000;
+    this._queues = this._sinks.map(() => []);
+    this._draining = this._sinks.map(() => null);
+  }
+
+  get counters(): TelemetryCounters {
+    return {
+      dropped: this._dropped,
+      sinkErrors: this._sinkErrors,
+      dispatched: this._dispatched,
+    };
+  }
+
+  async start(event: TelemetryRunStart): Promise<void> {
+    return this._fanout({
+      kind: "start",
+      exec: (s) => s.start(event),
+    });
+  }
+
+  async step(runId: string, delta: TelemetryRunStep): Promise<void> {
+    return this._fanout({
+      kind: "step",
+      exec: (s) => s.step(runId, delta),
+    });
+  }
+
+  async finish(runId: string, event: TelemetryRunFinish): Promise<void> {
+    return this._fanout({
+      kind: "finish",
+      exec: (s) => s.finish(runId, event),
+    });
+  }
+
+  async flush(): Promise<void> {
+    await Promise.all([
+      ...this._draining.map((p) => p ?? Promise.resolve()),
+      ...this._sinks.map((s) =>
+        s.flush?.().catch((err) => {
+          this._sinkErrors += 1;
+          this._logger.warn(
+            { sink: s.name, err: errorMessage(err) },
+            "telemetry-bus: flush failed"
+          );
+        })
+      ),
+    ]);
+  }
+
+  // ── internal ───────────────────────────────────────────────────────────────
+
+  private async _fanout(evt: PendingEvent): Promise<void> {
+    if (this._nonBlocking) {
+      // Enqueue on each sink, kick drain in background.
+      this._sinks.forEach((_, i) => this._enqueue(i, evt));
+      return;
+    }
+    // Blocking mode (tests) — dispatch sequentially and surface errors via log.
+    await Promise.all(this._sinks.map((sink) => this._dispatchOne(sink, evt)));
+  }
+
+  private _enqueue(sinkIdx: number, evt: PendingEvent): void {
+    const queue = this._queues[sinkIdx]!;
+    if (queue.length >= this._maxQueueDepth) {
+      queue.shift(); // drop oldest
+      this._dropped += 1;
+      const sink = this._sinks[sinkIdx]!;
+      this._logger.warn(
+        { sink: sink.name, depth: queue.length, dropped: this._dropped },
+        "telemetry-bus: queue overflow, oldest dropped"
+      );
+    }
+    queue.push(evt);
+    void this._drain(sinkIdx);
+  }
+
+  private async _drain(sinkIdx: number): Promise<void> {
+    if (this._draining[sinkIdx]) return;
+    const sink = this._sinks[sinkIdx]!;
+    const queue = this._queues[sinkIdx]!;
+
+    const promise = (async () => {
+      while (queue.length > 0) {
+        const evt = queue.shift()!;
+        await this._dispatchOne(sink, evt);
+      }
+    })();
+    this._draining[sinkIdx] = promise;
+    try {
+      await promise;
+    } finally {
+      this._draining[sinkIdx] = null;
+    }
+  }
+
+  private async _dispatchOne(
+    sink: TelemetrySink,
+    evt: PendingEvent
+  ): Promise<void> {
+    try {
+      await evt.exec(sink);
+      this._dispatched += 1;
+    } catch (err) {
+      this._sinkErrors += 1;
+      this._logger.warn(
+        {
+          sink: sink.name,
+          kind: evt.kind,
+          err: errorMessage(err),
+        },
+        "telemetry-bus: sink dispatch failed (isolated)"
+      );
+    }
+  }
+}
+
+// ─── Factory ─────────────────────────────────────────────────────────────────
+
+/**
+ * Build a TelemetryBus that fans events to all sinks non-blockingly.
+ *
+ * If `sinks` is empty, returns {@link NOOP_TELEMETRY_SINK} so callers never
+ * need to null-check.
+ */
+export function createTelemetryBus(
+  opts: TelemetryBusOptions
+): TelemetrySink & { counters: TelemetryCounters; flush(): Promise<void> } {
+  if (opts.sinks.length === 0) {
+    // Wrap NOOP with stub counters + flush for type consistency.
+    return {
+      ...NOOP_TELEMETRY_SINK,
+      counters: { dropped: 0, sinkErrors: 0, dispatched: 0 },
+      async flush() {
+        /* no-op */
+      },
+    };
+  }
+  return new TelemetryBusImpl(opts);
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function errorMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}

package/src/telemetry/index.ts

@@ -0,0 +1,49 @@
+/**
+ * Public telemetry API for agent-sdk consumers.
+ *
+ * Per ADR-ECO-039. Sovereign multi-sink observability for OODA agents.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   createOODAAgent,
+ *   stdoutTelemetrySink,
+ *   localSqliteTelemetrySink,
+ * } from "@vauban-org/agent-sdk";
+ *
+ * createOODAAgent({
+ *   agentId: "my-agent",
+ *   telemetry: {
+ *     sinks: [
+ *       stdoutTelemetrySink(),
+ *       localSqliteTelemetrySink(),
+ *     ],
+ *   },
+ * });
+ * ```
+ */
+
+export { NOOP_TELEMETRY_SINK, TelemetrySinkError } from "./port.js";
+export type {
+  TelemetryRunStatus,
+  TelemetryRunFinish,
+  TelemetryRunStart,
+  TelemetryRunStep,
+  TelemetrySink,
+} from "./port.js";
+
+export { createTelemetryBus } from "./bus.js";
+export type {
+  TelemetryBusOptions,
+  TelemetryCounters,
+  TelemetryLogger,
+} from "./bus.js";
+
+export { stdoutTelemetrySink } from "./sinks/stdout.js";
+export type { StdoutTelemetrySinkOptions } from "./sinks/stdout.js";
+
+export { localSqliteTelemetrySink } from "./sinks/sqlite.js";
+export type { LocalSqliteTelemetrySinkOptions } from "./sinks/sqlite.js";
+
+export { otlpTelemetrySink } from "./sinks/otlp.js";
+export type { OtlpTelemetrySinkOptions } from "./sinks/otlp.js";

package/src/telemetry/port.ts

@@ -0,0 +1,160 @@
+/**
+ * TelemetryPort — sovereign multi-sink observability for agent runs.
+ *
+ * Per ADR-ECO-039 (accepted 2026-05-16). Sink-based interface replaces the
+ * implicit coupling between agent-sdk and the CC `agent_run` table (legacy
+ * `AgentRunTracker`). Callers configure 0..N sinks; the {@link TelemetryBus}
+ * fans events out non-blockingly.
+ *
+ * Three modes :
+ *   1. Standalone   : `[stdoutTelemetrySink(), localSqliteTelemetrySink()]`
+ *   2. + CC SaaS    : add `commandCenterTelemetrySink({apiKey})`
+ *   3. Tiered       : same code, API key changes entitlement server-side
+ *
+ * Ref: command-center:sprint-693:port-interface
+ */
+
+// ─── Run lifecycle types (compatible with legacy AgentRunTracker) ────────────
+
+export interface TelemetryRunStart {
+  /** Caller-generated run id (matches the OODA loop's runId / trace). */
+  runId: string;
+  agentId: string;
+  agentVersion: string;
+  model: string;
+  provider: string;
+  /** Optional tenant scoping — required by the CC sink. */
+  tenantId?: string;
+  /** OTel trace id for replay linkage. */
+  traceId?: string;
+  /** ISO8601 timestamp of cycle start. */
+  startedAt: string;
+}
+
+export interface TelemetryRunStep {
+  /** Monotonic step index within the run, starting at 0. */
+  stepIndex: number;
+  /** OODA phase or step kind ("observe" | "orient" | "decide" | "act" | ...). */
+  kind: string;
+  /** Status of THIS step (not the whole run). */
+  status: "completed" | "failed" | "skipped";
+  inputTokens: number;
+  outputTokens: number;
+  toolCalls?: number;
+  /**
+   * USD cost delta. MUST be >= 0. Use 0 for non-LLM steps.
+   * Fixed(6) precision recommended.
+   */
+  costUsd: number;
+  /** Optional duration in ms — useful for OTLP span span_start/span_end. */
+  durationMs?: number;
+  /** Optional metadata. Hashed at sink boundary unless `includePayloads`. */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Run final status.
+ *
+ * NEW (sprint-693) : "skipped" — added so that session_guard /
+ * risk_guard / heap_exceeded short-circuits are observably distinct
+ * from "success" or "failed".
+ */
+export type TelemetryRunStatus =
+  | "success"
+  | "failed"
+  | "skipped"
+  | "timeout"
+  | "incoherent";
+
+export interface TelemetryRunFinish {
+  status: TelemetryRunStatus;
+  /** Free-text reason — e.g. "session_guard:business-hours". */
+  stopReason?: string;
+  /** Only set when status === "failed" | "incoherent". */
+  errorMessage?: string;
+  /** ISO8601 timestamp of cycle finish. */
+  finishedAt: string;
+  /** Optional cumulative totals — sinks may compute or trust caller. */
+  totalInputTokens?: number;
+  totalOutputTokens?: number;
+  totalCostUsd?: number;
+  totalToolCalls?: number;
+}
+
+// ─── Sink interface ──────────────────────────────────────────────────────────
+
+/**
+ * TelemetrySink — pluggable destination for run lifecycle events.
+ *
+ * Contract :
+ *   - `start` is called ONCE per run before any `step`.
+ *   - `step` MAY be called 0..N times after start; the bus serialises per-run.
+ *   - `finish` is called ONCE after the last `step` (or directly after `start`
+ *     for skipped runs).
+ *   - All methods MUST be idempotent w.r.t. their (runId, stepIndex) pair —
+ *     the bus may retry on transient sink failures.
+ *   - Implementations MUST NOT throw on transient errors ; return a rejected
+ *     Promise instead so the bus can isolate the failure.
+ *
+ * Implementations should NOT block the agent loop. Long-running I/O should
+ * be batched/queued internally.
+ */
+export interface TelemetrySink {
+  /** Unique sink identifier — used for audit log + Prometheus labels. */
+  readonly name: string;
+
+  /**
+   * Record run start. Returns a sink-local reference (e.g. DB UUID, file
+   * offset, span id) the bus may pass back to `step` / `finish` for
+   * correlation. Return value is opaque to the bus.
+   */
+  start(event: TelemetryRunStart): Promise<string | void>;
+
+  /** Record a single OODA step delta. */
+  step(runId: string, delta: TelemetryRunStep): Promise<void>;
+
+  /** Record run finish. */
+  finish(runId: string, event: TelemetryRunFinish): Promise<void>;
+
+  /**
+   * Flush pending I/O (best-effort). Called on agent shutdown.
+   * Implementations without a buffer can no-op.
+   */
+  flush?(): Promise<void>;
+}
+
+// ─── NOOP — default when no sinks configured ─────────────────────────────────
+
+/**
+ * No-op sink. The bus uses this when no sinks are configured, so callers
+ * never need to null-check.
+ */
+export const NOOP_TELEMETRY_SINK: TelemetrySink = {
+  name: "noop",
+  async start() {
+    /* no-op */
+  },
+  async step() {
+    /* no-op */
+  },
+  async finish() {
+    /* no-op */
+  },
+};
+
+// ─── Error type ──────────────────────────────────────────────────────────────
+
+/**
+ * Thrown only at the BUS boundary when ALL sinks fail. Individual sink
+ * failures are warned and isolated (see {@link TelemetryBus}).
+ */
+export class TelemetrySinkError extends Error {
+  constructor(
+    message: string,
+    public readonly sinkName: string,
+    public readonly cause?: unknown
+  ) {
+    super(`[telemetry:${sinkName}] ${message}`);
+    this.name = "TelemetrySinkError";
+  }
+}