retrace-sdk 0.16.11 → 0.16.12

package/dist/resume.js

@@ -9,20 +9,60 @@
  */
 // Registry of resumable functions
 const resumableFunctions = new Map();
+import { getConfig } from "./config.js";
 export function registerResumable(name, fn) {
     resumableFunctions.set(name, fn);
 }
 export function getResumable(name) {
     return resumableFunctions.get(name);
 }
+/**
+ * Best-effort execution-start / heartbeat claim. Returns false ONLY on a definitive 409 (a newer
+ * replay superseded this one). ANY other outcome — network/timeout, 401/403, deploy-window 404, 429,
+ * 5xx — returns true and PROCEEDS: this fence is best-effort by design; the server's completion CAS
+ * is the final authority that rejects a stale result. It does NOT, on its own, prevent stale work on
+ * a claim-endpoint failure.
+ */
+async function claimExecution(forkId, executionId) {
+    try {
+        const cfg = getConfig();
+        const resp = await fetch(`${cfg.baseUrl}/api/v1/forks/${forkId}/replay/claim`, {
+            method: "POST",
+            headers: { "x-retrace-key": cfg.apiKey, "Content-Type": "application/json" },
+            body: JSON.stringify({ execution_id: executionId }),
+            signal: AbortSignal.timeout(5000),
+        });
+        return resp.status !== 409;
+    }
+    catch {
+        return true; // ambiguous failure → proceed (best-effort)
+    }
+}
 export async function handleResume(command) {
     const fn = getResumable(command.traceName);
     if (!fn)
         return false;
+    // Execution-start fence BEFORE creating the recorder, so a superseded replay leaves NO leaked
+    // recorder/trace/interceptors/context (the recorder is only started once we're cleared to run).
+    if (command.executionId && !(await claimExecution(command.forkId, command.executionId))) {
+        console.warn("[retrace] Cascade replay superseded by a newer replay — aborting before execution.");
+        return false;
+    }
+    // Keep-alive heartbeat: refresh our generation while a (possibly long) replay runs so a new dispatch
+    // can't reclaim it as stale — which is what would otherwise let a second replay run concurrently.
+    // Interval is well under the server lease window; stopped in finally.
+    let heartbeat = null;
+    if (command.executionId) {
+        heartbeat = setInterval(() => { void claimExecution(command.forkId, command.executionId); }, 5 * 60 * 1000);
+        if (typeof heartbeat.unref === "function")
+            heartbeat.unref();
+    }
+    let recorder = null;
+    let markFailed = null;
     try {
         const { TraceRecorder } = await import("./recorder.js");
         const { TraceStatus } = await import("./trace.js");
-        const recorder = new TraceRecorder({
+        recorder = new TraceRecorder({
             name: `Fork: ${command.traceName}`,
             input: command.modifiedInput,
             metadata: {
@@ -35,6 +75,10 @@ export async function handleResume(command) {
             forkPointSpanId: command.forkPointSpanId,
             forkPointIndex: command.forkPointIndex,
         });
+        // Finalizer captured with the right enum type — used to end the trace as FAILED if user code
+        // throws, so a thrown replay never leaks a running trace / interceptor routing / trace context /
+        // an elevated active-recorder count.
+        markFailed = () => recorder.end(undefined, TraceStatus.FAILED);
         recorder.start(`Fork: ${command.traceName}`, command.modifiedInput);
         // Determine args for re-execution
         let args = command.originalArgs || [];
@@ -50,8 +94,16 @@ export async function handleResume(command) {
     }
     catch (err) {
         console.error("[retrace] Cascade replay failed:", err);
+        try {
+            markFailed?.();
+        }
+        catch { /* best-effort finalize */ }
         return false;
     }
+    finally {
+        if (heartbeat)
+            clearInterval(heartbeat);
+    }
 }
 export function parseResumeMessage(msg) {
     if (msg.type !== "resume" || !msg.data)

package/dist/transport.js

@@ -87,7 +87,7 @@ export class WSTransport {
                 // (no-op on runtimes without `_socket`, e.g. the global WebSocket). Graceful shutdown still
                 // drains via flush()/beforeExit.
                 socket?._socket?.unref?.();
-                socket.send(JSON.stringify({ type: "auth", api_key: getConfig().apiKey, resumable: getConfig().allowRemoteReplay }));
+                socket.send(JSON.stringify({ type: "auth", api_key: getConfig().apiKey, resumable: getConfig().allowRemoteReplay, replay_generation: 1 }));
             });
             socket.addEventListener("message", (ev) => {
                 try {

package/package.json

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