@vauban-org/agent-sdk 0.16.0

package/src/replay/replay.ts

@@ -0,0 +1,271 @@
+/**
+ * replayFrom — deterministic agent run replay.
+ *
+ * Given a runId, a ReplayLoader (fetches original trace + recorded artifacts),
+ * and a ReplayRunner (re-executes the agent with virtualized dependencies),
+ * replayFrom produces a ReplayResult containing:
+ *   - The replayed trace.
+ *   - A match flag: true iff rootHash of replay === rootHash of original.
+ *   - A diff array listing step-level field mismatches (when match is false).
+ *
+ * Design invariant:
+ *   Replay proves byte-identical traces when ClockPort, RandomPort, and
+ *   LLMResponseCache are virtualized. It does NOT prove LLM provider-side
+ *   determinism — the provider may return different tokens under identical
+ *   inputs (temperature, context window, batching).
+ *
+ * @module replay/replay
+ */
+
+import type { Trace, TraceStep } from "../trace/schema.js";
+import type { ClockPort } from "./clock.js";
+import type { RandomPort } from "./random.js";
+import type { LLMResponseCache } from "./llm-cache.js";
+
+// ─── ReplayMode ───────────────────────────────────────────────────────────────
+
+/**
+ * Controls strictness of the replay session.
+ *
+ * - 'strict': crypto()/cryptoUuid() throws CryptoRandomDuringReplayError.
+ *             Any non-deterministic call is surfaced immediately.
+ * - 'tolerant': crypto()/cryptoUuid() returns fresh bytes (non-fatal).
+ *               Useful for runs that legitimately mix deterministic + crypto calls.
+ */
+export type ReplayMode = "strict" | "tolerant";
+
+// ─── ReplayContext ────────────────────────────────────────────────────────────
+
+/**
+ * Virtualised execution context for a replay run.
+ * Pass this to ReplayRunner.run() in place of the production context.
+ */
+export interface ReplayContext {
+  /** runId of the original run being replayed. */
+  readonly originalRunId: string;
+  /**
+   * A distinct runId for this replay run.
+   * Must differ from originalRunId — replay runs are traceable separately.
+   */
+  readonly replayRunId: string;
+  /** Strictness mode for crypto calls. */
+  readonly mode: ReplayMode;
+  /** Virtualized clock replaying the original run's timestamps. */
+  readonly clock: ClockPort;
+  /** Virtualized PRNG replaying the original run's random values. */
+  readonly random: RandomPort;
+  /** Virtualized LLM cache replaying the original run's responses. */
+  readonly cache: LLMResponseCache;
+}
+
+// ─── ReplayResult ─────────────────────────────────────────────────────────────
+
+/**
+ * Result of a replay execution.
+ *
+ * match === true  → replay is byte-identical to the original (rootHash matches).
+ * match === false → at least one step diverged; see diff for details.
+ */
+export interface ReplayResult {
+  /** The replay run identifier. */
+  replayRunId: string;
+  /** The trace produced by the replay run. */
+  trace: Trace;
+  /**
+   * True iff the rootHash of the replay trace equals the rootHash of the
+   * original trace. This is the primary audit assertion.
+   */
+  match: boolean;
+  /**
+   * Step-level field mismatches, populated when match is false.
+   * Empty array when match is true.
+   */
+  diff?: {
+    stepIndex: number;
+    field: keyof TraceStep;
+    original: unknown;
+    replayed: unknown;
+  }[];
+}
+
+// ─── ReplayLoader ─────────────────────────────────────────────────────────────
+
+/**
+ * Port for loading the artifacts needed to replay a run.
+ * The host provides a concrete implementation (e.g. pgsql, file system).
+ */
+export interface ReplayLoader {
+  /**
+   * Fetch the original Trace for the given runId.
+   * Throws if the run is not found.
+   */
+  loadOriginalTrace(runId: string): Promise<Trace>;
+
+  /**
+   * Fetch all recorded artifacts for the given runId:
+   *   - recordedTs: timestamps array for RecordedClock
+   *   - recordedNext: float array for RecordedRandom.next()
+   *   - recordedUuids: UUID array for RecordedRandom.uuid()
+   *   - cache: LLMResponseCache populated with the original run's responses
+   */
+  loadCacheEntries(runId: string): Promise<{
+    recordedTs: number[];
+    recordedNext: number[];
+    recordedUuids: string[];
+    cache: LLMResponseCache;
+  }>;
+}
+
+// ─── ReplayRunner ─────────────────────────────────────────────────────────────
+
+/**
+ * Port for re-executing the agent with a virtualised context.
+ * The host provides a concrete implementation that wires the agent
+ * to the virtualised ClockPort, RandomPort, and LLMResponseCache.
+ *
+ * Extended contract (counterfactual support):
+ *   Implementations MAY inspect `(ctx as { strategyOverride?: string }).strategyOverride`
+ *   to swap their compute strategy for offline counterfactual analysis.
+ *   This field is injected exclusively by `replayCounterfactual` (offline tool) —
+ *   it is never present in production replay contexts.
+ */
+export interface ReplayRunner {
+  /**
+   * Re-execute the agent using ctx (virtual clock/random/cache)
+   * starting from the state described in originalTrace.
+   *
+   * Returns the new Trace produced by the replay.
+   *
+   * @param ctx           Virtualised execution context. When ctx carries a
+   *                      `strategyOverride` field (injected by replayCounterfactual),
+   *                      the implementation SHOULD honour it by swapping its
+   *                      compute strategy accordingly. This parameter is optional
+   *                      on the interface — existing implementations that do not
+   *                      inspect it remain fully compatible.
+   * @param originalTrace Original trace providing the starting state.
+   */
+  run(ctx: ReplayContext, originalTrace: Trace): Promise<Trace>;
+}
+
+// ─── NonDeterministicReplayError ─────────────────────────────────────────────
+
+/**
+ * Thrown when strict-mode replay detects a non-deterministic deviation
+ * that cannot be represented as a diff (e.g. step count mismatch, missing steps).
+ *
+ * For field-level mismatches, see ReplayResult.diff instead.
+ */
+export class NonDeterministicReplayError extends Error {
+  constructor(
+    public readonly stepIndex: number,
+    public readonly reason: string,
+  ) {
+    super(`Non-deterministic replay at step ${stepIndex}: ${reason}`);
+    this.name = "NonDeterministicReplayError";
+  }
+}
+
+// ─── diffTraces ───────────────────────────────────────────────────────────────
+
+/**
+ * Compute a step-level diff between two traces.
+ * Returns an empty array if the traces are identical at the step level.
+ */
+function diffTraces(
+  original: Trace,
+  replayed: Trace,
+): ReplayResult["diff"] {
+  const diffs: NonNullable<ReplayResult["diff"]> = [];
+
+  const minLen = Math.min(original.steps.length, replayed.steps.length);
+  for (let i = 0; i < minLen; i++) {
+    const origStep = original.steps[i];
+    const repStep = replayed.steps[i];
+    for (const field of Object.keys(origStep) as (keyof TraceStep)[]) {
+      const ov = origStep[field];
+      const rv = repStep[field];
+      // Compare via JSON serialization to handle nested objects correctly
+      if (JSON.stringify(ov) !== JSON.stringify(rv)) {
+        diffs.push({ stepIndex: i, field, original: ov, replayed: rv });
+      }
+    }
+  }
+
+  // If step counts differ, flag the extra/missing steps
+  if (original.steps.length !== replayed.steps.length) {
+    diffs.push({
+      stepIndex: minLen,
+      field: "index" as keyof TraceStep,
+      original: original.steps.length,
+      replayed: replayed.steps.length,
+    });
+  }
+
+  return diffs;
+}
+
+// ─── replayFrom ───────────────────────────────────────────────────────────────
+
+/**
+ * Main replay entry point.
+ *
+ * 1. Loads the original trace and recorded artifacts via ReplayLoader.
+ * 2. Builds a ReplayContext with RecordedClock, RecordedRandom, and LLM cache.
+ * 3. Re-executes the agent via ReplayRunner.run().
+ * 4. Compares rootHashes and computes a step-level diff if they differ.
+ *
+ * @param runId   The original run identifier to replay.
+ * @param loader  Host-provided loader for trace + artifacts.
+ * @param runner  Host-provided runner that wires the agent to virtualised deps.
+ * @param opts    Optional overrides: replay mode, step index to replay from.
+ */
+export async function replayFrom(
+  runId: string,
+  loader: ReplayLoader,
+  runner: ReplayRunner,
+  opts?: { mode?: ReplayMode; fromStepIndex?: number },
+): Promise<ReplayResult> {
+  const mode = opts?.mode ?? "strict";
+
+  // 1. Load original artifacts
+  const [originalTrace, artifacts] = await Promise.all([
+    loader.loadOriginalTrace(runId),
+    loader.loadCacheEntries(runId),
+  ]);
+
+  // 2. Import concrete implementations lazily to avoid circular references
+  const { RecordedClock } = await import("./clock.js");
+  const { RecordedRandom } = await import("./random.js");
+
+  const clock = new RecordedClock(artifacts.recordedTs);
+  const random = new RecordedRandom(
+    artifacts.recordedNext,
+    artifacts.recordedUuids,
+    mode,
+  );
+
+  // 3. Build the replay context
+  const replayRunId = globalThis.crypto.randomUUID();
+  const ctx: ReplayContext = {
+    originalRunId: runId,
+    replayRunId,
+    mode,
+    clock,
+    random,
+    cache: artifacts.cache,
+  };
+
+  // 4. Re-execute
+  const replayTrace = await runner.run(ctx, originalTrace);
+
+  // 5. Compare
+  const match = originalTrace.rootHash === replayTrace.rootHash;
+  const diff = match ? [] : diffTraces(originalTrace, replayTrace);
+
+  return {
+    replayRunId,
+    trace: replayTrace,
+    match,
+    diff,
+  };
+}

package/src/resilience/bulkhead.ts

@@ -0,0 +1,95 @@
+/**
+ * Bulkhead — bound concurrent execution of an async operation.
+ *
+ * Sprint-468. Wrap a function so at most `maxConcurrent` invocations
+ * are active at once; additional calls queue up to `maxQueued` before
+ * rejecting with BulkheadFullError. Prevents a slow backend from
+ * exhausting the agent's event loop or memory.
+ *
+ * Usage:
+ *   const safeArchive = bulkhead(brain.archiveKnowledge.bind(brain), {
+ *     name: "brain.archive",
+ *     maxConcurrent: 5,
+ *     maxQueued: 50,
+ *   });
+ */
+
+export interface BulkheadOptions {
+  /** Label for BulkheadFullError messages. */
+  name: string;
+  /** In-flight invocation cap. Default 5. */
+  maxConcurrent?: number;
+  /** Queue depth cap. Reject once full. Default 50. */
+  maxQueued?: number;
+}
+
+export class BulkheadFullError extends Error {
+  readonly bulkheadName: string;
+  constructor(bulkheadName: string, queueDepth: number) {
+    super(
+      `Bulkhead "${bulkheadName}" full — queue depth ${queueDepth} reached.`,
+    );
+    this.name = "BulkheadFullError";
+    this.bulkheadName = bulkheadName;
+  }
+}
+
+export interface BulkheadStats {
+  active: number;
+  queued: number;
+}
+
+export interface Bulkhead<TArgs extends unknown[], TResult> {
+  (...args: TArgs): Promise<TResult>;
+  readonly stats: BulkheadStats;
+}
+
+export function bulkhead<TArgs extends unknown[], TResult>(
+  fn: (...args: TArgs) => Promise<TResult>,
+  options: BulkheadOptions,
+): Bulkhead<TArgs, TResult> {
+  const maxConcurrent = options.maxConcurrent ?? 5;
+  const maxQueued = options.maxQueued ?? 50;
+
+  let active = 0;
+  const queue: Array<() => void> = [];
+
+  const acquire = (): Promise<void> => {
+    if (active < maxConcurrent) {
+      active += 1;
+      return Promise.resolve();
+    }
+    if (queue.length >= maxQueued) {
+      return Promise.reject(
+        new BulkheadFullError(options.name, queue.length),
+      );
+    }
+    return new Promise<void>((resolve) => {
+      queue.push(() => {
+        active += 1;
+        resolve();
+      });
+    });
+  };
+
+  const release = (): void => {
+    active -= 1;
+    const next = queue.shift();
+    if (next) next();
+  };
+
+  async function run(...args: TArgs): Promise<TResult> {
+    await acquire();
+    try {
+      return await fn(...args);
+    } finally {
+      release();
+    }
+  }
+
+  const wrapper = run as Bulkhead<TArgs, TResult>;
+  Object.defineProperty(wrapper, "stats", {
+    get: () => ({ active, queued: queue.length }),
+  });
+  return wrapper;
+}

package/src/resilience/circuit-breaker.ts

@@ -0,0 +1,129 @@
+/**
+ * Circuit breaker — Hystrix-style state machine.
+ *
+ * Sprint-468. Wrap an unreliable async operation so N consecutive
+ * failures trip the breaker OPEN (all subsequent calls fast-fail
+ * without invoking the operation) for `resetAfterMs`. After that a
+ * single probe call runs in HALF-OPEN state; success → back to CLOSED,
+ * failure → back to OPEN.
+ *
+ *   CLOSED (normal)
+ *     ├─ N failures ──► OPEN (fast-fail, window)
+ *     └─ success ──► CLOSED
+ *   OPEN
+ *     └─ after resetAfterMs ──► HALF-OPEN (1 probe)
+ *   HALF-OPEN
+ *     ├─ probe success ──► CLOSED
+ *     └─ probe failure ──► OPEN (new window)
+ *
+ * Usage:
+ *   const safeArchive = circuitBreaker(brain.archiveKnowledge.bind(brain), {
+ *     name: "brain.archive",
+ *     failureThreshold: 5,
+ *     resetAfterMs: 30_000,
+ *   });
+ */
+
+export type CircuitState = "closed" | "open" | "half-open";
+
+export interface CircuitBreakerOptions {
+  /** Operation identifier for CircuitOpenError messages. */
+  name: string;
+  /** Consecutive failures required to trip OPEN. Default 5. */
+  failureThreshold?: number;
+  /** How long to stay OPEN before the HALF-OPEN probe. Default 30s. */
+  resetAfterMs?: number;
+  /** Optional clock for tests. */
+  now?: () => number;
+  /**
+   * Predicate — classify an error as "should count as failure" vs
+   * "fast-exit without tripping". Default: every thrown value counts.
+   */
+  isFailure?: (err: unknown) => boolean;
+}
+
+export class CircuitOpenError extends Error {
+  readonly circuitName: string;
+  readonly retryAfterMs: number;
+  constructor(circuitName: string, retryAfterMs: number) {
+    super(
+      `Circuit "${circuitName}" is OPEN — fast-fail. Retry after ${retryAfterMs}ms.`,
+    );
+    this.name = "CircuitOpenError";
+    this.circuitName = circuitName;
+    this.retryAfterMs = retryAfterMs;
+  }
+}
+
+export interface CircuitBreaker<TArgs extends unknown[], TResult> {
+  (...args: TArgs): Promise<TResult>;
+  readonly state: CircuitState;
+  /** Consecutive failures in the current CLOSED window. */
+  readonly failureCount: number;
+  /** Force back to CLOSED (for tests or operational reset). */
+  reset(): void;
+}
+
+export function circuitBreaker<TArgs extends unknown[], TResult>(
+  fn: (...args: TArgs) => Promise<TResult>,
+  options: CircuitBreakerOptions,
+): CircuitBreaker<TArgs, TResult> {
+  const failureThreshold = options.failureThreshold ?? 5;
+  const resetAfterMs = options.resetAfterMs ?? 30_000;
+  const now = options.now ?? (() => Date.now());
+  const isFailure = options.isFailure ?? (() => true);
+
+  let state: CircuitState = "closed";
+  let failureCount = 0;
+  let openedAt = 0;
+
+  async function run(...args: TArgs): Promise<TResult> {
+    if (state === "open") {
+      const elapsed = now() - openedAt;
+      if (elapsed < resetAfterMs) {
+        throw new CircuitOpenError(options.name, resetAfterMs - elapsed);
+      }
+      state = "half-open";
+    }
+
+    try {
+      const result = await fn(...args);
+      if (state === "half-open") {
+        state = "closed";
+        failureCount = 0;
+      } else {
+        failureCount = 0;
+      }
+      return result;
+    } catch (err) {
+      if (!isFailure(err)) throw err;
+
+      if (state === "half-open") {
+        state = "open";
+        openedAt = now();
+        throw err;
+      }
+
+      failureCount += 1;
+      if (failureCount >= failureThreshold) {
+        state = "open";
+        openedAt = now();
+      }
+      throw err;
+    }
+  }
+
+  const wrapper = run as CircuitBreaker<TArgs, TResult>;
+  Object.defineProperty(wrapper, "state", { get: () => state });
+  Object.defineProperty(wrapper, "failureCount", {
+    get: () => failureCount,
+  });
+  Object.defineProperty(wrapper, "reset", {
+    value: () => {
+      state = "closed";
+      failureCount = 0;
+      openedAt = 0;
+    },
+  });
+  return wrapper;
+}

package/src/resilience/idempotent.ts

@@ -0,0 +1,126 @@
+/**
+ * Idempotency cache — dedupe duplicate calls by a caller-supplied key.
+ *
+ * Sprint-468. Wrap an async operation so repeated calls with the same
+ * key return the cached result without re-invoking the operation.
+ * Essential for retry-safe writes (BrainPort.archiveKnowledge on
+ * retryable failures).
+ *
+ * Defaults to an in-memory LRU with 1024 entries / 5 min TTL. Production
+ * hosts with multi-process topology should inject a shared
+ * implementation (e.g. Redis-backed) via the `cache` option.
+ *
+ * Usage:
+ *   const safe = idempotent(brain.archiveKnowledge.bind(brain), {
+ *     keyFor: (entry) => sha256(entry.content + entry.author),
+ *     ttlMs: 60_000,
+ *   });
+ */
+
+import { createHash } from "node:crypto";
+
+export interface IdempotencyCache<T> {
+  get(key: string): T | undefined;
+  set(key: string, value: T): void;
+  delete(key: string): void;
+}
+
+/**
+ * Simple bounded TTL cache. In-memory only; single-process.
+ * Eviction: oldest entry first when `maxEntries` is exceeded, and
+ * entries past `ttlMs` are skipped on read.
+ */
+export class BoundedTtlCache<T> implements IdempotencyCache<T> {
+  private readonly store = new Map<string, { value: T; expiresAt: number }>();
+  constructor(
+    private readonly maxEntries: number,
+    private readonly ttlMs: number,
+    private readonly now: () => number = () => Date.now(),
+  ) {}
+
+  get(key: string): T | undefined {
+    const entry = this.store.get(key);
+    if (!entry) return undefined;
+    if (entry.expiresAt < this.now()) {
+      this.store.delete(key);
+      return undefined;
+    }
+    // Refresh LRU position.
+    this.store.delete(key);
+    this.store.set(key, entry);
+    return entry.value;
+  }
+
+  set(key: string, value: T): void {
+    if (this.store.size >= this.maxEntries) {
+      const oldest = this.store.keys().next().value;
+      if (oldest !== undefined) this.store.delete(oldest);
+    }
+    this.store.set(key, {
+      value,
+      expiresAt: this.now() + this.ttlMs,
+    });
+  }
+
+  delete(key: string): void {
+    this.store.delete(key);
+  }
+
+  get size(): number {
+    return this.store.size;
+  }
+}
+
+export interface IdempotentOptions<TArgs extends unknown[], TResult> {
+  /** Derive a stable cache key from the call arguments. */
+  keyFor: (...args: TArgs) => string;
+  /** Optional cache implementation (defaults to BoundedTtlCache). */
+  cache?: IdempotencyCache<TResult>;
+  /** Default cache: entries count cap. Default 1024. */
+  maxEntries?: number;
+  /** Default cache: entry TTL in ms. Default 5 minutes. */
+  ttlMs?: number;
+}
+
+/**
+ * Wrap an async function so identical keyed calls share the same
+ * result. Failures are NOT cached — a failed call is retryable.
+ */
+export function idempotent<TArgs extends unknown[], TResult>(
+  fn: (...args: TArgs) => Promise<TResult>,
+  options: IdempotentOptions<TArgs, TResult>,
+): (...args: TArgs) => Promise<TResult> {
+  const cache =
+    options.cache ??
+    new BoundedTtlCache<TResult>(
+      options.maxEntries ?? 1024,
+      options.ttlMs ?? 5 * 60_000,
+    );
+
+  return async (...args: TArgs): Promise<TResult> => {
+    const key = options.keyFor(...args);
+    const hit = cache.get(key);
+    if (hit !== undefined) return hit;
+    const result = await fn(...args);
+    cache.set(key, result);
+    return result;
+  };
+}
+
+/**
+ * Convenience: hash the JSON-serialisable arguments as the cache key.
+ * Useful when the args already fully determine the operation (e.g.
+ * BrainPort.archiveKnowledge takes a single entry object).
+ */
+export function hashKey(...parts: unknown[]): string {
+  const h = createHash("sha256");
+  for (const part of parts) {
+    let serialised: string;
+    if (typeof part === "string") serialised = part;
+    else if (part === undefined) serialised = "__undefined__";
+    else serialised = JSON.stringify(part) ?? "__unserialisable__";
+    h.update(serialised);
+    h.update("\x1f"); // unit-separator
+  }
+  return h.digest("hex");
+}

package/src/resilience/index.ts

@@ -0,0 +1,51 @@
+/**
+ * Resilience primitives — Hystrix-style patterns for port wrappers.
+ *
+ * Sprint-468. Three composable wrappers that turn any async function
+ * into a production-grade primitive:
+ *
+ *   - circuitBreaker : trip OPEN after N consecutive failures, recover
+ *     via HALF-OPEN probe. Prevents overload of a failing dependency.
+ *   - idempotent     : dedupe by a stable key; retry-safe writes.
+ *   - bulkhead       : bound concurrent in-flight calls + queue depth.
+ *
+ * These are orthogonal and composable:
+ *
+ *   const safe = circuitBreaker(
+ *     bulkhead(
+ *       idempotent(brain.archiveKnowledge.bind(brain), { keyFor: ... }),
+ *       { name: "brain.archive", maxConcurrent: 5 }
+ *     ),
+ *     { name: "brain.archive", failureThreshold: 5, resetAfterMs: 30_000 }
+ *   );
+ */
+
+export {
+  circuitBreaker,
+  CircuitOpenError,
+} from "./circuit-breaker.js";
+export type {
+  CircuitBreaker,
+  CircuitBreakerOptions,
+  CircuitState,
+} from "./circuit-breaker.js";
+
+export {
+  idempotent,
+  hashKey,
+  BoundedTtlCache,
+} from "./idempotent.js";
+export type {
+  IdempotencyCache,
+  IdempotentOptions,
+} from "./idempotent.js";
+
+export {
+  bulkhead,
+  BulkheadFullError,
+} from "./bulkhead.js";
+export type {
+  Bulkhead,
+  BulkheadOptions,
+  BulkheadStats,
+} from "./bulkhead.js";

package/src/router/index.ts

@@ -0,0 +1,11 @@
+export {
+  createProviderRouter,
+  ProviderRouterError,
+} from "./provider-router.js";
+export type {
+  ProviderRouter,
+  ProviderRouterRequest,
+  ProviderRouterResponse,
+  ProviderRouterOptions,
+  AnthropicLike,
+} from "./provider-router.js";