@vauban-org/agent-sdk 0.16.0

package/src/replay/llm-cache.ts

@@ -0,0 +1,199 @@
+/**
+ * LLMResponseCache — content-addressed in-memory cache for LLM responses.
+ *
+ * Cache key: SHA-256(canonical({provider, model, messages, temperature, seed?}))
+ * This makes the cache deterministic across runs given identical inputs,
+ * enabling replay of LLM responses without hitting the actual provider.
+ *
+ * Production adapters (pgsql, Redis) belong to the B-series tasks.
+ * This module ships the in-memory implementation + the hash utility.
+ *
+ * @module replay/llm-cache
+ */
+
+import { canonicalize } from "../trace/canonical.js";
+
+// ─── LLMCacheKey ──────────────────────────────────────────────────────────────
+
+/**
+ * Canonical key for an LLM response cache entry.
+ * All fields are included in the SHA-256 hash — changing any field
+ * produces a different cache key (cache miss).
+ */
+export interface LLMCacheKey {
+  /** LLM provider identifier (e.g. "openai", "groq", "anthropic"). */
+  provider: string;
+  /** Model identifier (e.g. "gpt-4o", "llama-3.3-70b"). */
+  model: string;
+  /**
+   * Message array passed to the LLM. Array order matters: a different
+   * ordering of the same messages will produce a different hash.
+   */
+  messages: unknown;
+  /** Sampling temperature. Included in key — same prompt at different temps yields different responses. */
+  temperature: number;
+  /**
+   * Optional provider-side seed for deterministic sampling.
+   * When present, influences the cache key to distinguish seeded from unseeded calls.
+   */
+  seed?: number;
+}
+
+// ─── LLMCacheEntry ────────────────────────────────────────────────────────────
+
+/**
+ * A single cache entry: the hash key, the stored response, and when it was recorded.
+ */
+export interface LLMCacheEntry {
+  /** SHA-256(canonical(LLMCacheKey)) — hex-encoded. */
+  key: string;
+  /** Full serialized response payload from the LLM provider. */
+  response: unknown;
+  /** Unix epoch milliseconds when this entry was recorded. */
+  recordedAt: number;
+}
+
+// ─── LLMResponseCache interface ───────────────────────────────────────────────
+
+/**
+ * Content-addressed store for LLM responses.
+ *
+ * Implementations:
+ *   - InMemoryLLMResponseCache (this module) — for tests and dev.
+ *   - PostgreSQL adapter (B-series tasks) — for production replay.
+ */
+export interface LLMResponseCache {
+  /**
+   * Look up a cached response for the given key.
+   * Returns undefined on a cache miss.
+   */
+  get(key: LLMCacheKey): Promise<LLMCacheEntry | undefined>;
+
+  /**
+   * Store a response for the given key.
+   * Overwrites any existing entry with the same hash.
+   */
+  put(key: LLMCacheKey, response: unknown): Promise<void>;
+
+  /**
+   * Test helper: wipe the entire in-memory store.
+   * Optional — production adapters may omit this.
+   */
+  clear?(): void;
+}
+
+// ─── hashLLMCacheKey ──────────────────────────────────────────────────────────
+
+/**
+ * Compute the SHA-256 hex hash of a canonical LLMCacheKey.
+ *
+ * Uses Web Crypto API (globalThis.crypto.subtle) — zero external dependencies.
+ * Requires Node >= 20 or any modern browser.
+ *
+ * Array order in `messages` is significant: two arrays with the same elements
+ * in different order will produce different hashes.
+ */
+export async function hashLLMCacheKey(key: LLMCacheKey): Promise<string> {
+  const canonical = canonicalize(key);
+  const encoded = new TextEncoder().encode(canonical);
+  const hashBuffer = await globalThis.crypto.subtle.digest("SHA-256", encoded);
+  return bufferToHex(hashBuffer);
+}
+
+function bufferToHex(buffer: ArrayBuffer): string {
+  return Array.from(new Uint8Array(buffer))
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+// ─── InMemoryLLMResponseCache ─────────────────────────────────────────────────
+
+/**
+ * In-memory LLM response cache keyed by SHA-256(canonical(LLMCacheKey)).
+ *
+ * Intended for:
+ *   - Unit and integration tests (deterministic, zero I/O).
+ *   - Development replay (fast, ephemeral).
+ *
+ * NOT intended for production: data is lost on process restart.
+ * Production replay should use the PostgreSQL adapter (B-series).
+ */
+export class InMemoryLLMResponseCache implements LLMResponseCache {
+  private readonly store = new Map<string, LLMCacheEntry>();
+
+  async get(key: LLMCacheKey): Promise<LLMCacheEntry | undefined> {
+    const hash = await hashLLMCacheKey(key);
+    return this.store.get(hash);
+  }
+
+  async put(key: LLMCacheKey, response: unknown): Promise<void> {
+    const hash = await hashLLMCacheKey(key);
+    this.store.set(hash, {
+      key: hash,
+      response,
+      recordedAt: Date.now(),
+    });
+  }
+
+  clear(): void {
+    this.store.clear();
+  }
+}
+
+// ─── CompositeLLMResponseCache ────────────────────────────────────────────────
+
+/**
+ * Composite (two-level) LLM response cache.
+ *
+ * Lookup order: child cache first, then parent cache (lookup-through).
+ * Writes go only to the child cache. In replay mode the child is typically
+ * read-only (no new entries), so `put()` is a no-op — pass `readOnly: true`.
+ *
+ * Use `withParent()` to construct a child cache that inherits responses from a
+ * parent cycle without polluting the parent's store.
+ */
+export class CompositeLLMResponseCache implements LLMResponseCache {
+  constructor(
+    private readonly child: LLMResponseCache,
+    private readonly parent: LLMResponseCache,
+    private readonly readOnly: boolean = false,
+  ) {}
+
+  async get(key: LLMCacheKey): Promise<LLMCacheEntry | undefined> {
+    // Child takes priority (own cycle entries override parent)
+    const childHit = await this.child.get(key);
+    if (childHit !== undefined) return childHit;
+    return this.parent.get(key);
+  }
+
+  async put(key: LLMCacheKey, response: unknown): Promise<void> {
+    if (this.readOnly) return;
+    await this.child.put(key, response);
+  }
+
+  clear(): void {
+    if (!this.readOnly && typeof this.child.clear === "function") {
+      this.child.clear();
+    }
+  }
+}
+
+/**
+ * Factory: creates a composite cache that looks up `parentCache` on miss.
+ * The child is a fresh InMemoryLLMResponseCache — writes do NOT propagate to
+ * the parent (write-back disabled in replay mode by default).
+ *
+ * @param parentCache  The parent cycle's cache (read-only access).
+ * @param readOnly     When true, put() is a no-op (replay write-back disabled).
+ *                     Defaults to true for replay safety.
+ */
+export function withParent(
+  parentCache: LLMResponseCache,
+  readOnly = true,
+): LLMResponseCache {
+  return new CompositeLLMResponseCache(
+    new InMemoryLLMResponseCache(),
+    parentCache,
+    readOnly,
+  );
+}

package/src/replay/random.ts

@@ -0,0 +1,249 @@
+/**
+ * RandomPort — dual-API random number source for deterministic replay.
+ *
+ * CH4 DUAL API DESIGN:
+ *   Two distinct APIs with different guarantees — never conflate them:
+ *
+ *   Deterministic (replay-safe, NON SECURITY-GRADE):
+ *     next()   — float in [0, 1) via xorshift32 seeded PRNG
+ *     uuid()   — deterministic v4-like UUID from xorshift32 (NOT crypto-strong)
+ *
+ *   Crypto-strong (NON REPLAY-SAFE by design — security trumps audit):
+ *     crypto(bytes)  — random bytes via globalThis.crypto.getRandomValues
+ *     cryptoUuid()   — crypto-strong UUID via globalThis.crypto.randomUUID
+ *
+ * Use next()/uuid() for application logic that needs to be replayable.
+ * Use crypto()/cryptoUuid() for security-critical values (tokens, nonces, keys)
+ * that MUST NOT be replayable.
+ *
+ * During replay, calling crypto()/cryptoUuid() on RecordedRandom in strict mode
+ * throws CryptoRandomDuringReplayError to surface the violation at the boundary.
+ *
+ * @module replay/random
+ */
+
+// ─── RandomPort interface ─────────────────────────────────────────────────────
+
+/**
+ * Abstract random source with a dual API:
+ * - Deterministic arm (next/uuid): seedable, replay-safe, NON SECURITY-GRADE.
+ * - Crypto arm (crypto/cryptoUuid): crypto-strong, NON REPLAY-SAFE by design.
+ */
+export interface RandomPort {
+  /**
+   * Returns a float in [0, 1) via the deterministic PRNG.
+   * NON SECURITY-GRADE — use for application logic only.
+   */
+  next(): number;
+
+  /**
+   * Returns a deterministic v4-like UUID from the seeded PRNG.
+   * Format: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx
+   * NON SECURITY-GRADE — use for replayable correlation IDs only.
+   */
+  uuid(): string;
+
+  /**
+   * Returns `bytes` cryptographically random bytes via globalThis.crypto.
+   * NON REPLAY-SAFE by design — security trumps audit.
+   */
+  crypto(bytes: number): Promise<Uint8Array>;
+
+  /**
+   * Returns a cryptographically strong UUID via globalThis.crypto.randomUUID.
+   * NON REPLAY-SAFE by design.
+   */
+  cryptoUuid(): string;
+}
+
+// ─── CryptoRandomDuringReplayError ────────────────────────────────────────────
+
+/**
+ * Thrown by RecordedRandom in 'strict' mode when crypto()/cryptoUuid() is called.
+ * Signals that the agent called a non-replayable code path during replay —
+ * a violation of the deterministic replay contract.
+ */
+export class CryptoRandomDuringReplayError extends Error {
+  constructor() {
+    super(
+      "crypto() / cryptoUuid() called during replay. " +
+        "Crypto random is NON-REPLAY-SAFE by design (security trumps audit). " +
+        "Use random.next() / random.uuid() for replayable values.",
+    );
+    this.name = "CryptoRandomDuringReplayError";
+  }
+}
+
+// ─── xorshift32 PRNG ─────────────────────────────────────────────────────────
+
+/**
+ * xorshift32 — minimal seedable PRNG.
+ * Period: 2^32 - 1. Passes BigCrush for basic applications.
+ * NOT cryptographically secure — use only for deterministic application logic.
+ *
+ * Reference: Marsaglia, G. (2003). "Xorshift RNGs". Journal of Statistical Software.
+ */
+function xorshift32(state: Uint32Array): number {
+  let x = state[0];
+  x ^= x << 13;
+  x ^= x >>> 17;
+  x ^= x << 5;
+  state[0] = x >>> 0; // force unsigned 32-bit
+  return x >>> 0;
+}
+
+/** Convert 4 uint32 nibbles to a standard UUID v4-like hex string. */
+function nibblesToUuid(a: number, b: number, c: number, d: number): string {
+  const hex = (n: number, len: number) =>
+    n.toString(16).padStart(len, "0");
+
+  // v4-like: set version bits (4) and variant bits (10xx)
+  const timeLow = hex(a, 8);
+  const timeMid = hex((b >>> 16) & 0xffff, 4);
+  // version nibble: force 4
+  const timeHiAndVersion = hex(((b & 0x0fff) | 0x4000), 4);
+  // variant: force 10xx
+  const clockSeqHiAndRes = hex(((c >>> 24) & 0x3f) | 0x80, 2);
+  const clockSeqLow = hex((c >>> 16) & 0xff, 2);
+  const node = hex(((c & 0xffff) * 0x100000000 + d) >>> 0, 12).padStart(12, "0");
+
+  return `${timeLow}-${timeMid}-${timeHiAndVersion}-${clockSeqHiAndRes}${clockSeqLow}-${node}`;
+}
+
+// ─── RealRandom ───────────────────────────────────────────────────────────────
+
+/**
+ * Production implementation:
+ * - next()/uuid(): xorshift32 seeded PRNG (deterministic if seed is fixed).
+ * - crypto()/cryptoUuid(): globalThis.crypto (non-deterministic, crypto-strong).
+ *
+ * Pass a fixed seed to make next()/uuid() deterministic across runs.
+ * Default seed: Date.now() XOR a random 32-bit value (non-deterministic).
+ */
+export class RealRandom implements RandomPort {
+  private readonly state: Uint32Array;
+
+  constructor(seed?: number) {
+    const s =
+      seed !== undefined
+        ? seed >>> 0 // coerce to uint32
+        : (Date.now() ^ Math.floor(Math.random() * 2 ** 32)) >>> 0;
+    // xorshift32 must not start with 0
+    this.state = new Uint32Array([s === 0 ? 1 : s]);
+  }
+
+  next(): number {
+    // xorshift32 returns uint32; divide by 2^32 to get [0, 1)
+    return xorshift32(this.state) / 0x100000000;
+  }
+
+  uuid(): string {
+    const a = xorshift32(this.state);
+    const b = xorshift32(this.state);
+    const c = xorshift32(this.state);
+    const d = xorshift32(this.state);
+    return nibblesToUuid(a, b, c, d);
+  }
+
+  async crypto(bytes: number): Promise<Uint8Array> {
+    const buf = new Uint8Array(bytes);
+    globalThis.crypto.getRandomValues(buf);
+    return buf;
+  }
+
+  cryptoUuid(): string {
+    return globalThis.crypto.randomUUID();
+  }
+}
+
+// ─── RecordedRandom ───────────────────────────────────────────────────────────
+
+/**
+ * Replay implementation: replays recorded next()/uuid() sequences.
+ *
+ * - next(): returns the next value from recordedNext (throws RangeError when exhausted).
+ * - uuid(): returns the next value from recordedUuids (throws RangeError when exhausted).
+ * - crypto(): throws CryptoRandomDuringReplayError in 'strict' mode;
+ *             returns fresh crypto bytes in 'tolerant' mode.
+ * - cryptoUuid(): throws CryptoRandomDuringReplayError in 'strict' mode;
+ *                 returns fresh crypto UUID in 'tolerant' mode.
+ */
+export class RecordedRandom implements RandomPort {
+  private nextCursor = 0;
+  private uuidCursor = 0;
+
+  constructor(
+    private readonly recordedNext: readonly number[],
+    private readonly recordedUuids: readonly string[],
+    private readonly mode: "strict" | "tolerant" = "strict",
+  ) {}
+
+  next(): number {
+    if (this.nextCursor >= this.recordedNext.length) {
+      throw new RangeError(
+        `RecordedRandom.next() exhausted: ${this.recordedNext.length} values recorded, ` +
+          `${this.nextCursor + 1} requested`,
+      );
+    }
+    return this.recordedNext[this.nextCursor++];
+  }
+
+  uuid(): string {
+    if (this.uuidCursor >= this.recordedUuids.length) {
+      throw new RangeError(
+        `RecordedRandom.uuid() exhausted: ${this.recordedUuids.length} values recorded, ` +
+          `${this.uuidCursor + 1} requested`,
+      );
+    }
+    return this.recordedUuids[this.uuidCursor++];
+  }
+
+  async crypto(bytes: number): Promise<Uint8Array> {
+    if (this.mode === "strict") {
+      throw new CryptoRandomDuringReplayError();
+    }
+    // tolerant: return fresh crypto bytes (non-deterministic but not fatal)
+    const buf = new Uint8Array(bytes);
+    globalThis.crypto.getRandomValues(buf);
+    return buf;
+  }
+
+  cryptoUuid(): string {
+    if (this.mode === "strict") {
+      throw new CryptoRandomDuringReplayError();
+    }
+    return globalThis.crypto.randomUUID();
+  }
+
+  /**
+   * Returns a new RecordedRandom that shares the same underlying recorded arrays
+   * and starts at the CURRENT cursor positions (nextCursor + uuidCursor). Each
+   * clone maintains its own independent cursors — arrays are shared (read-only).
+   *
+   * Use for cross-cycle propagation: child cycle picks up exactly where the
+   * parent left off in both the next() and uuid() sequences.
+   *
+   * Clone invariant: clone.next() returns the same value as `this.next()` would
+   * at the moment clone() is called.
+   */
+  clone(): RecordedRandom {
+    const child = new RecordedRandom(
+      this.recordedNext,
+      this.recordedUuids,
+      this.mode,
+    );
+    child.nextCursor = this.nextCursor;
+    child.uuidCursor = this.uuidCursor;
+    return child;
+  }
+
+  /** Returns current nextCursor (number of next() values consumed). */
+  getNextCursor(): number {
+    return this.nextCursor;
+  }
+
+  /** Returns current uuidCursor (number of uuid() values consumed). */
+  getUuidCursor(): number {
+    return this.uuidCursor;
+  }
+}