retrace-sdk 0.3.1 → 0.3.2

package/dist/index.d.ts

@@ -9,3 +9,5 @@ export { installAnthropicInterceptor, uninstallAnthropicInterceptor } from "./in
 export { RetraceError, RetraceAuthError, RetraceCreditsExhaustedError, RetraceConnectionError, RetraceRateLimitError } from "./errors.js";
 export { registerResumable, handleResume } from "./resume.js";
 export type { ResumeCommand } from "./resume.js";
+export { isReplaying, consumeCassetteEntry, handleReplay } from "./replay.js";
+export type { CassetteEntry, ReplayCommand } from "./replay.js";

package/dist/index.js

@@ -7,3 +7,4 @@ export { installOpenAIInterceptor, uninstallOpenAIInterceptor } from "./intercep
 export { installAnthropicInterceptor, uninstallAnthropicInterceptor } from "./interceptors/anthropic.js";
 export { RetraceError, RetraceAuthError, RetraceCreditsExhaustedError, RetraceConnectionError, RetraceRateLimitError } from "./errors.js";
 export { registerResumable, handleResume } from "./resume.js";
+export { isReplaying, consumeCassetteEntry, handleReplay } from "./replay.js";

package/dist/replay.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Deterministic Replay with Cassettes for Retrace TypeScript SDK.
+ *
+ * When the server sends a "replay" command, the SDK:
+ * 1. Loads the cassette (recorded span inputs/outputs)
+ * 2. Sets up a global cassette store
+ * 3. Re-executes the trace function
+ * 4. Tool calls are intercepted and return recorded outputs from the cassette
+ *
+ * This enables one-click reproduction of any production trace locally.
+ */
+export interface CassetteEntry {
+    index: number;
+    span_type: string;
+    name: string;
+    model: string | null;
+    input: unknown;
+    output: unknown;
+    error: string | null;
+}
+export interface ReplayCommand {
+    traceId: string;
+    traceName: string;
+    input: unknown;
+    cassette: CassetteEntry[];
+}
+/**
+ * Check if a replay is currently active.
+ */
+export declare function isReplaying(): boolean;
+/**
+ * Get the next cassette entry matching a span name and type.
+ * Uses sequential matching with name-based fallback for deterministic replay.
+ */
+export declare function consumeCassetteEntry(name: string, spanType: string): CassetteEntry | null;
+/**
+ * Handle a replay command from the server.
+ */
+export declare function handleReplay(command: ReplayCommand): boolean;
+export declare function parseReplayMessage(msg: {
+    type: string;
+    data?: unknown;
+}): ReplayCommand | null;

package/dist/replay.js

@@ -0,0 +1,97 @@
+/**
+ * Deterministic Replay with Cassettes for Retrace TypeScript SDK.
+ *
+ * When the server sends a "replay" command, the SDK:
+ * 1. Loads the cassette (recorded span inputs/outputs)
+ * 2. Sets up a global cassette store
+ * 3. Re-executes the trace function
+ * 4. Tool calls are intercepted and return recorded outputs from the cassette
+ *
+ * This enables one-click reproduction of any production trace locally.
+ */
+import { getResumable } from "./resume.js";
+// Global cassette state for the current replay session
+let activeCassette = null;
+let cassettePointer = 0;
+/**
+ * Check if a replay is currently active.
+ */
+export function isReplaying() {
+    return activeCassette !== null;
+}
+/**
+ * Get the next cassette entry matching a span name and type.
+ * Uses sequential matching with name-based fallback for deterministic replay.
+ */
+export function consumeCassetteEntry(name, spanType) {
+    if (!activeCassette)
+        return null;
+    // Primary: sequential pointer (deterministic order)
+    if (cassettePointer < activeCassette.length) {
+        const entry = activeCassette[cassettePointer];
+        if (entry.name === name && entry.span_type === spanType) {
+            cassettePointer++;
+            return entry;
+        }
+    }
+    // Fallback: search by name + type from current pointer forward
+    for (let i = cassettePointer; i < activeCassette.length; i++) {
+        if (activeCassette[i].name === name && activeCassette[i].span_type === spanType) {
+            cassettePointer = i + 1;
+            return activeCassette[i];
+        }
+    }
+    return null;
+}
+/**
+ * Handle a replay command from the server.
+ */
+export function handleReplay(command) {
+    const fn = getResumable(command.traceName);
+    if (!fn)
+        return false;
+    // Set up cassette
+    activeCassette = command.cassette;
+    cassettePointer = 0;
+    (async () => {
+        try {
+            const { TraceRecorder } = await import("./recorder.js");
+            const { TraceStatus } = await import("./trace.js");
+            const recorder = new TraceRecorder({
+                name: `Replay: ${command.traceName}`,
+                input: command.input,
+                metadata: {
+                    _replay_of: command.traceId,
+                    _deterministic_replay: true,
+                    _cassette_size: command.cassette.length,
+                },
+            });
+            recorder.start(`Replay: ${command.traceName}`, command.input);
+            const args = typeof command.input === "string"
+                ? [command.input]
+                : Array.isArray(command.input) ? command.input : [command.input];
+            const result = await Promise.resolve(fn(...args));
+            recorder.end(result, TraceStatus.COMPLETED);
+        }
+        catch (err) {
+            console.error("[retrace] Deterministic replay failed:", err);
+        }
+        finally {
+            // Clean up cassette state
+            activeCassette = null;
+            cassettePointer = 0;
+        }
+    })();
+    return true;
+}
+export function parseReplayMessage(msg) {
+    if (msg.type !== "replay" || !msg.data)
+        return null;
+    const data = msg.data;
+    return {
+        traceId: data.traceId,
+        traceName: data.traceName,
+        input: data.input,
+        cassette: data.cassette,
+    };
+}

package/dist/transport.js

@@ -43,6 +43,13 @@ export class WSTransport {
                         handleResume(cmd);
                 });
             }
+            else if (msg.type === "replay") {
+                import("./replay.js").then(({ parseReplayMessage, handleReplay }) => {
+                    const cmd = parseReplayMessage(msg);
+                    if (cmd)
+                        handleReplay(cmd);
+                });
+            }
             else if (msg.type === "halt") {
                 const reason = msg.data?.reason || "Guardrail triggered";
                 this.onError?.("halt", reason);

package/package.json

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