retrace-sdk 0.11.6 → 0.11.7

package/dist/config.d.ts

@@ -11,6 +11,11 @@ export interface Config {
      *  request/response only (recommended for short-lived scripts and serverless — it never
      *  holds an open socket and always surfaces upload errors); "ws" forces WebSocket. */
     transport: "auto" | "ws" | "http";
+    /** Replay safety. When a deterministic replay hits a cassette MISS (no recorded entry for a
+     *  call), the SDK otherwise falls through to a REAL provider call (live cost + non-determinism).
+     *  With strictReplay=true the SDK throws instead (fail-closed). Default false: warn + fall through.
+     *  Env: RETRACE_STRICT_REPLAY. */
+    strictReplay: boolean;
     /** Called with a STRUCTURED signal when the server signals credits_exhausted | rate_limited |
      *  halt | error. Branch on `signal.code`; use `signal.retryable`/`signal.fatal` to decide
      *  behavior. Defaults to a throttled console warning so signals are never silently dropped. */

package/dist/config.js

@@ -7,6 +7,7 @@ const config = {
     sampleRate: parseFloat(process.env.RETRACE_SAMPLE_RATE || "1"),
     sampleSeed: process.env.RETRACE_SAMPLE_SEED || undefined,
     transport: (["auto", "ws", "http"].includes(process.env.RETRACE_TRANSPORT || "") ? process.env.RETRACE_TRANSPORT : "auto"),
+    strictReplay: ["true", "1"].includes((process.env.RETRACE_STRICT_REPLAY || "").toLowerCase()),
 };
 config.wsUrl = config.baseUrl.replace("https://", "wss://").replace("http://", "ws://");
 export function configure(opts) {

package/dist/replay.js

@@ -10,6 +10,7 @@
  * This enables one-click reproduction of any production trace locally.
  */
 import { getResumable } from "./resume.js";
+import { getConfig } from "./config.js";
 import { AsyncLocalStorage } from "async_hooks";
 const cassetteStorage = new AsyncLocalStorage();
 /**
@@ -42,8 +43,25 @@ export function consumeCassetteEntry(name, spanType) {
             return ctx.cassette[i];
         }
     }
+    // Cassette MISS during an active replay: there is NO recorded entry for this call. Returning null
+    // makes the interceptor fall through to a REAL provider call (live cost + non-determinism). Never
+    // do that silently — warn (throttled), and fail closed if strictReplay is set.
+    reportCassetteMiss(name, spanType);
     return null;
 }
+const _missWarnedAt = new Map();
+/** Throttled-warn (or throw, under strictReplay) on a cassette miss during replay. */
+function reportCassetteMiss(name, spanType) {
+    if (getConfig().strictReplay) {
+        throw new Error(`[retrace] Replay cassette MISS for ${spanType} "${name}": no recorded entry, and strictReplay is enabled — refusing to fall through to a real provider call. The recorded trace likely diverged (different call order/count).`);
+    }
+    const key = `${spanType}:${name}`;
+    const now = Date.now();
+    if (now - (_missWarnedAt.get(key) ?? 0) > 5000) {
+        _missWarnedAt.set(key, now);
+        console.warn(`[retrace] Replay cassette MISS for ${spanType} "${name}" — no recorded entry; falling through to a REAL provider call (live cost + non-determinism). Set strictReplay:true (or RETRACE_STRICT_REPLAY=true) to fail closed instead.`);
+    }
+}
 /**
  * Handle a replay command from the server.
  * Returns a Promise that resolves when replay completes or rejects on failure.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "retrace-sdk",
-  "version": "0.11.6",
+  "version": "0.11.7",
   "description": "The execution replay engine for AI agents. Record, replay, fork, and share agent executions.",
   "type": "module",
   "main": "dist/index.js",