retrace-sdk 0.14.0 → 0.16.0

package/dist/cassette.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Golden cassette writer for CI regression replay (Phase 4b).
+ *
+ * After recording a run, write its cassette to a file you commit to your repo; `retrace ci replay`
+ * diffs a fresh run against it in CI. The JSON shape is the cross-language contract in
+ * `@retrace/shared` (CassetteSchema) — keep this writer in sync with it.
+ */
 import type { TraceRecorder } from "./recorder.js";
 export interface CassetteTolerance {
     default?: "exact" | "ignore" | "semantic" | "judge";

package/dist/cassette.js

@@ -1,12 +1,12 @@
-/**
- * Golden cassette writer for CI regression replay (Phase 4b).
- *
- * After recording a run, write its cassette to a file you commit to your repo; `retrace ci replay`
- * diffs a fresh run against it in CI. The JSON shape is the cross-language contract in
- * `@retrace/shared` (CassetteSchema) — keep this writer in sync with it.
- */
-import { writeFileSync } from "node:fs";
 import { getActiveRecorder } from "./init.js";
+// node:fs is loaded LAZILY (not a static import) so this module — re-exported from the package
+// barrel — still evaluates on edge runtimes. Golden cassettes are a Node/CI feature (writing a file
+// to disk), so on Node we resolve writeFileSync once at module load; on edge writeGoldenCassette
+// throws a clear error. The microtask import resolves long before any real post-run cassette write.
+let _writeFileSync = null;
+if (typeof process !== "undefined" && process.versions?.node) {
+    void import("node:fs").then((m) => { _writeFileSync = m.writeFileSync; }).catch(() => { });
+}
 /**
  * Write the active (or given) recorder's run to `path` as a golden cassette. Returns the cassette.
  * Throws if no recorder is active — call it inside/after your traced function, before the process
@@ -19,6 +19,9 @@ export function writeGoldenCassette(path, opts) {
     const cassette = recorder.toCassette();
     if (opts?.tolerance)
         cassette.tolerance = opts.tolerance;
-    writeFileSync(path, JSON.stringify(cassette, null, 2));
+    if (!_writeFileSync) {
+        throw new Error("writeGoldenCassette requires a Node.js filesystem; it isn't available on this runtime (e.g. edge).");
+    }
+    _writeFileSync(path, JSON.stringify(cassette, null, 2));
     return cassette;
 }

package/dist/config.js

@@ -1,19 +1,23 @@
+// Runtime-safe env: edge runtimes (Cloudflare Workers, Deno/Supabase Edge) may not define a global
+// `process`, so reading process.env.* directly would throw at module-evaluation time. Fall back to
+// an empty map there; explicit configure({ apiKey, ... }) still works on every runtime.
+const env = typeof process !== "undefined" && process.env ? process.env : {};
 const config = {
-    apiKey: process.env.RETRACE_API_KEY || "",
-    baseUrl: process.env.RETRACE_BASE_URL || "https://api.retraceai.tech",
+    apiKey: env.RETRACE_API_KEY || "",
+    baseUrl: env.RETRACE_BASE_URL || "https://api.retraceai.tech",
     wsUrl: "",
-    projectId: process.env.RETRACE_PROJECT_ID || undefined,
-    enabled: !["false", "0"].includes((process.env.RETRACE_ENABLED || "true").toLowerCase()),
-    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()),
-    maxStepsPerRun: process.env.RETRACE_MAX_STEPS_PER_RUN ? parseInt(process.env.RETRACE_MAX_STEPS_PER_RUN, 10) : undefined,
-    maxTokensPerRun: process.env.RETRACE_MAX_TOKENS_PER_RUN ? parseInt(process.env.RETRACE_MAX_TOKENS_PER_RUN, 10) : undefined,
-    maxUsdPerRun: process.env.RETRACE_MAX_USD_PER_RUN ? parseFloat(process.env.RETRACE_MAX_USD_PER_RUN) : undefined,
-    serverEnforcement: ["true", "1", "yes"].includes((process.env.RETRACE_SERVER_ENFORCEMENT || "").toLowerCase()),
-    enforcementHoldWaitSeconds: process.env.RETRACE_ENFORCEMENT_HOLD_WAIT_SECONDS ? parseInt(process.env.RETRACE_ENFORCEMENT_HOLD_WAIT_SECONDS, 10) : 0,
-    environment: process.env.RETRACE_ENVIRONMENT || undefined,
+    projectId: env.RETRACE_PROJECT_ID || undefined,
+    enabled: !["false", "0"].includes((env.RETRACE_ENABLED || "true").toLowerCase()),
+    sampleRate: parseFloat(env.RETRACE_SAMPLE_RATE || "1"),
+    sampleSeed: env.RETRACE_SAMPLE_SEED || undefined,
+    transport: (["auto", "ws", "http"].includes(env.RETRACE_TRANSPORT || "") ? env.RETRACE_TRANSPORT : "auto"),
+    strictReplay: ["true", "1"].includes((env.RETRACE_STRICT_REPLAY || "").toLowerCase()),
+    maxStepsPerRun: env.RETRACE_MAX_STEPS_PER_RUN ? parseInt(env.RETRACE_MAX_STEPS_PER_RUN, 10) : undefined,
+    maxTokensPerRun: env.RETRACE_MAX_TOKENS_PER_RUN ? parseInt(env.RETRACE_MAX_TOKENS_PER_RUN, 10) : undefined,
+    maxUsdPerRun: env.RETRACE_MAX_USD_PER_RUN ? parseFloat(env.RETRACE_MAX_USD_PER_RUN) : undefined,
+    serverEnforcement: ["true", "1", "yes"].includes((env.RETRACE_SERVER_ENFORCEMENT || "").toLowerCase()),
+    enforcementHoldWaitSeconds: env.RETRACE_ENFORCEMENT_HOLD_WAIT_SECONDS ? parseInt(env.RETRACE_ENFORCEMENT_HOLD_WAIT_SECONDS, 10) : 0,
+    environment: env.RETRACE_ENVIRONMENT || undefined,
 };
 config.wsUrl = config.baseUrl.replace("https://", "wss://").replace("http://", "ws://");
 export function configure(opts) {

package/dist/enforcement.d.ts

@@ -1,3 +1,14 @@
+/**
+ * Client-side enforcement gate (circuit breakers) — the TypeScript twin of the Python
+ * `EnforcementGate` (same names, same semantics).
+ *
+ * LOCAL ceilings (max steps / tokens / USD per run) are enforced entirely offline — zero network, so
+ * the breaker trips even when the API is unreachable, and it throws SYNCHRONOUSLY before the next
+ * call. When `serverEnforcement` is enabled the gate ALSO consults the server `/enforcement/check`
+ * endpoint; because auto-instrumentation routes spans synchronously, that call is best-effort and
+ * fire-and-forget — a server block trips the NEXT span (one-span lag) rather than the current one,
+ * and a transport failure is logged, never swallowed (server policy is authoritative at ingest).
+ */
 import type { Config } from "./config.js";
 /** Stable short hash of tool arguments so raw args never leave the process for a loop/debounce check. */
 export declare function hashToolArgs(args: unknown): string;

package/dist/enforcement.js

@@ -1,16 +1,25 @@
-/**
- * Client-side enforcement gate (circuit breakers) — the TypeScript twin of the Python
- * `EnforcementGate` (same names, same semantics).
- *
- * LOCAL ceilings (max steps / tokens / USD per run) are enforced entirely offline — zero network, so
- * the breaker trips even when the API is unreachable, and it throws SYNCHRONOUSLY before the next
- * call. When `serverEnforcement` is enabled the gate ALSO consults the server `/enforcement/check`
- * endpoint; because auto-instrumentation routes spans synchronously, that call is best-effort and
- * fire-and-forget — a server block trips the NEXT span (one-span lag) rather than the current one,
- * and a transport failure is logged, never swallowed (server policy is authoritative at ingest).
- */
-import { createHash } from "node:crypto";
 import { RetraceEnforcementError } from "./errors.js";
+// Synchronous, dependency-free hash → 32 hex chars (cyrb53 variant, two seeds for a wider digest).
+// Used ONLY for LOCAL loop/debounce dedup keys within a single run — never a security or
+// cross-language boundary — so a fast non-cryptographic hash is sufficient. This keeps the gate
+// synchronous (Web Crypto's subtle.digest is async) AND runtime-agnostic (no `node:crypto` import,
+// which would break module evaluation on edge runtimes).
+function shortHash(input) {
+    const pass = (seed) => {
+        let h1 = 0xdeadbeef ^ seed;
+        let h2 = 0x41c6ce57 ^ seed;
+        for (let i = 0; i < input.length; i++) {
+            const ch = input.charCodeAt(i);
+            h1 = Math.imul(h1 ^ ch, 2654435761);
+            h2 = Math.imul(h2 ^ ch, 1597334677);
+        }
+        h1 = Math.imul(h1 ^ (h1 >>> 16), 2246822507) ^ Math.imul(h2 ^ (h2 >>> 13), 3266489909);
+        h2 = Math.imul(h2 ^ (h2 >>> 16), 2246822507) ^ Math.imul(h1 ^ (h1 >>> 13), 3266489909);
+        const n = 4294967296 * (2097151 & h2) + (h1 >>> 0);
+        return n.toString(16).padStart(14, "0");
+    };
+    return (pass(0) + pass(0x9e3779b9)).slice(0, 32);
+}
 /** Stable short hash of tool arguments so raw args never leave the process for a loop/debounce check. */
 export function hashToolArgs(args) {
     let serialized;
@@ -20,7 +29,7 @@ export function hashToolArgs(args) {
     catch {
         serialized = String(args);
     }
-    return createHash("sha256").update(serialized).digest("hex").slice(0, 32);
+    return shortHash(serialized);
 }
 export class EnforcementGate {
     config;

package/dist/interceptors/anthropic.js

@@ -3,6 +3,7 @@ import { genId, nowIso, truncateJson, wasTruncated } from "../utils.js";
 import { isReplaying, consumeCassetteEntry } from "../replay.js";
 import { emitAnthropicToolCalls, emitAnthropicToolResults, parseToolArgs, resetToolResultDedup, extractToolSchemas, extractSamplingParams } from "./tool-spans.js";
 import { dispatchRegisterOpenSpan, dispatchUnregisterOpenSpan } from "./_dispatch.js";
+import { UNKNOWN_MODEL_PRICING, costFromRate } from "../pricing.js";
 const PRICING = {
     "claude-opus-4.7": [5.0, 25.0],
     "claude-opus-4.6": [5.0, 25.0],
@@ -17,9 +18,10 @@ const PRICING = {
 function calcCost(model, inputTokens, outputTokens) {
     for (const [key, p] of Object.entries(PRICING)) {
         if (model.includes(key))
-            return (inputTokens * p[0] + outputTokens * p[1]) / 1_000_000;
+            return costFromRate(p, inputTokens, outputTokens);
     }
-    return 0;
+    // Unknown model — never cost $0 (that silently disarms USD budget ceilings). Conservative fallback.
+    return costFromRate(UNKNOWN_MODEL_PRICING, inputTokens, outputTokens);
 }
 let originalCreate = null;
 let installed = false;

package/dist/interceptors/gemini.js

@@ -2,6 +2,7 @@ import { SpanType } from "../trace.js";
 import { genId, nowIso, truncateJson } from "../utils.js";
 import { dispatchRegisterOpenSpan, dispatchUnregisterOpenSpan, captureActiveSpanEmit } from "./_dispatch.js";
 import { emitGeminiToolCalls, emitGeminiToolResults, resetToolResultDedup, extractToolSchemas, extractSamplingParams } from "./tool-spans.js";
+import { UNKNOWN_MODEL_PRICING, costFromRate } from "../pricing.js";
 const PRICING = {
     "gemini-3.1-flash-lite": [0.10, 0.40],
     "gemini-3.1-flash": [0.50, 3.0],
@@ -15,8 +16,10 @@ const PRICING = {
     "gemini-2.0-flash-lite": [0.05, 0.20],
 };
 function calcCost(model, inputTokens, outputTokens) {
-    const p = PRICING[model] || [0, 0];
-    return (inputTokens * p[0] + outputTokens * p[1]) / 1_000_000;
+    // Exact-match table (substring matching would mis-rank "…-flash" vs "…-flash-lite"); an unknown
+    // model falls back to a conservative non-zero rate so USD budget ceilings still engage.
+    const p = PRICING[model] ?? UNKNOWN_MODEL_PRICING;
+    return costFromRate(p, inputTokens, outputTokens);
 }
 let onSpanCallback = null;
 // eslint-disable-next-line @typescript-eslint/no-explicit-any

package/dist/interceptors/openai.js

@@ -5,6 +5,7 @@ import { getConfig } from "../config.js";
 import { RetraceRateLimitError, RetraceAuthError, RetraceConnectionError } from "../errors.js";
 import { emitOpenAIToolCalls, emitOpenAIToolResults, parseToolArgs, resetToolResultDedup, extractToolSchemas, extractSamplingParams } from "./tool-spans.js";
 import { dispatchRegisterOpenSpan, dispatchUnregisterOpenSpan } from "./_dispatch.js";
+import { UNKNOWN_MODEL_PRICING, costFromRate } from "../pricing.js";
 /** Hardcoded fallback pricing ($/1M tokens: [input, output]). Updated periodically. */
 const FALLBACK_PRICING = {
     "gpt-5.5-pro": [30.0, 180.0],
@@ -55,9 +56,10 @@ function calcCost(model, inputTokens, outputTokens) {
     const pricing = livePricing || FALLBACK_PRICING;
     for (const [key, p] of Object.entries(pricing)) {
         if (model.includes(key))
-            return (inputTokens * p[0] + outputTokens * p[1]) / 1_000_000;
+            return costFromRate(p, inputTokens, outputTokens);
     }
-    return 0;
+    // Unknown model — never cost $0 (that silently disarms USD budget ceilings). Conservative fallback.
+    return costFromRate(UNKNOWN_MODEL_PRICING, inputTokens, outputTokens);
 }
 let originalCreate = null;
 let installed = false;

package/dist/pricing.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Conservative fallback pricing for models not present in an interceptor's price table.
+ *
+ * A model that matches no key (a brand-new release, a fine-tune, an OpenRouter alias) would
+ * otherwise be costed at $0 — and a $0 cost silently disarms USD budget ceilings in the enforcement
+ * gate (the gate trips on estimated USD per run). We instead cost unknown models at a conservative
+ * mid/high frontier rate so a budget cap still engages; the value self-corrects the moment the
+ * server price table (synced via /api/v1/pricing/models) learns the model.
+ *
+ * $/1M tokens: [input, output].
+ */
+export declare const UNKNOWN_MODEL_PRICING: readonly [number, number];
+/** Cost in USD from an [input, output] $/1M-token rate. */
+export declare function costFromRate(rate: readonly [number, number], inputTokens: number, outputTokens: number): number;

package/dist/pricing.js

@@ -0,0 +1,16 @@
+/**
+ * Conservative fallback pricing for models not present in an interceptor's price table.
+ *
+ * A model that matches no key (a brand-new release, a fine-tune, an OpenRouter alias) would
+ * otherwise be costed at $0 — and a $0 cost silently disarms USD budget ceilings in the enforcement
+ * gate (the gate trips on estimated USD per run). We instead cost unknown models at a conservative
+ * mid/high frontier rate so a budget cap still engages; the value self-corrects the moment the
+ * server price table (synced via /api/v1/pricing/models) learns the model.
+ *
+ * $/1M tokens: [input, output].
+ */
+export const UNKNOWN_MODEL_PRICING = [5.0, 15.0];
+/** Cost in USD from an [input, output] $/1M-token rate. */
+export function costFromRate(rate, inputTokens, outputTokens) {
+    return (inputTokens * rate[0] + outputTokens * rate[1]) / 1_000_000;
+}

package/dist/telemetry.js

@@ -14,7 +14,7 @@ import { getConfig } from "./config.js";
 const ANON_ID = Math.random().toString(16).slice(2, 18);
 const DISABLED = new Set(["0", "false", "no", "off"]);
 // Keep in sync with package.json version.
-const SDK_VERSION = "0.14.0";
+const SDK_VERSION = "0.16.0";
 function enabled() {
     return !DISABLED.has((process.env.RETRACE_TELEMETRY ?? "1").trim().toLowerCase());
 }

package/dist/transport.d.ts

@@ -16,6 +16,7 @@ export interface Transport {
 }
 export declare class WSTransport implements Transport {
     private ws;
+    private connecting;
     private connected;
     private closed;
     private backoff;

package/dist/transport.js

@@ -1,11 +1,50 @@
-import WebSocket from "ws";
 import { getConfig } from "./config.js";
 import { classifyServerSignal } from "./errors.js";
 // Client identifier sent on every request so the backend can attribute SDK usage/version.
 // Keep in sync with package.json on release.
-const CLIENT_ID = "typescript-sdk/0.13.2";
+const CLIENT_ID = "typescript-sdk/0.16.0";
+// ─── Runtime-agnostic WebSocket ──────────────────────────────────────────────
+// Prefer the global Web `WebSocket` (Node 20+, Bun, Deno, browsers, and every edge runtime); fall
+// back to the OPTIONAL `ws` package only on older Node that lacks a global. Both expose the standard
+// `addEventListener`/`send`/`close`/`readyState`/`bufferedAmount` surface used here, so the transport
+// is identical across runtimes. On edge `ws` is simply absent — we use the global, or (if WS can't
+// connect) the HTTP transport via `fetch`.
+const WS_OPEN = 1; // CONNECTING=0, OPEN=1, CLOSING=2, CLOSED=3 (web standard; `ws` matches)
+let _wsCtor = null;
+function resolveWebSocketCtor() {
+    if (_wsCtor)
+        return _wsCtor;
+    const globalWS = globalThis.WebSocket;
+    if (typeof globalWS === "function") {
+        _wsCtor = Promise.resolve(globalWS);
+        return _wsCtor;
+    }
+    // No global WebSocket (older Node) → try the optional `ws` package. The variable specifier +
+    // ignore comments stop edge bundlers from statically resolving a dep that isn't installed there;
+    // this branch is never reached on runtimes that ship a global WebSocket.
+    const pkg = ["w", "s"].join("");
+    _wsCtor = import(/* webpackIgnore: true */ /* @vite-ignore */ pkg)
+        .then((m) => {
+        const mod = m;
+        return (mod.default ?? mod);
+    })
+        .catch(() => null); // `ws` not installed (e.g. edge build) → caller falls back to HTTP
+    return _wsCtor;
+}
+// Normalize a WS message payload to a string across runtimes: the global WebSocket delivers text
+// frames as a string; `ws` delivers a Buffer; ArrayBuffer/typed-array are handled defensively.
+function wsDataToString(data) {
+    if (typeof data === "string")
+        return data;
+    if (data instanceof ArrayBuffer)
+        return new TextDecoder().decode(data);
+    if (ArrayBuffer.isView(data))
+        return new TextDecoder().decode(data);
+    return String(data?.toString?.() ?? data);
+}
 export class WSTransport {
     ws = null;
+    connecting = false;
     connected = false;
     closed = false;
     backoff = 1000;
@@ -24,79 +63,94 @@ export class WSTransport {
     /** Whether a trace lost events to a buffer drop (so the API/replay can refuse byte-replay). */
     isTraceLossy(traceId) { return this.lossyTraces.has(traceId); }
     connect() {
-        if (this.closed)
+        if (this.closed || this.ws || this.connecting)
             return;
+        this.connecting = true;
         const cfg = getConfig();
         const url = `${cfg.wsUrl}/ws/v1/stream`;
-        this.ws = new WebSocket(url);
-        this.ws.on("open", () => {
-            // Unref the underlying socket so a short-lived script (the common SDK usage) can exit
-            // once its work is done instead of hanging on an open WebSocket. Graceful shutdown
-            // still drains via flush()/beforeExit.
-            this.ws?._socket?.unref?.();
-            this.ws.send(JSON.stringify({ type: "auth", api_key: cfg.apiKey }));
-        });
-        this.ws.on("message", (raw) => {
+        void resolveWebSocketCtor().then((Ctor) => {
+            this.connecting = false;
+            // No WebSocket implementation (edge without a global, or `ws` not installed), or we were
+            // closed/connected while resolving → bail. In "auto" mode the fallback timer switches to HTTP.
+            if (!Ctor || this.closed || this.ws)
+                return;
+            let socket;
             try {
-                const msg = JSON.parse(raw.toString());
-                if (msg.type === "auth_ok") {
-                    this.connected = true;
-                    this.backoff = 1000;
-                    this.flushQueue();
-                }
-                else if (msg.type === "ping") {
-                    this.ws?.send(JSON.stringify({ type: "pong" }));
-                }
-                else if (msg.type === "error") {
-                    this.surfaceSignal(classifyServerSignal("error", msg.error));
-                }
-                else if (msg.type === "resume") {
-                    import("./resume.js").then(({ parseResumeMessage, handleResume }) => {
-                        const cmd = parseResumeMessage(msg);
-                        if (cmd)
-                            handleResume(cmd);
-                    });
-                }
-                else if (msg.type === "replay") {
-                    import("./replay.js").then(({ parseReplayMessage, handleReplay }) => {
-                        const cmd = parseReplayMessage(msg);
-                        if (cmd)
-                            handleReplay(cmd);
-                    });
+                socket = new Ctor(url);
+            }
+            catch {
+                return; // construction unsupported on this runtime → leave disconnected (HTTP fallback)
+            }
+            this.ws = socket;
+            socket.addEventListener("open", () => {
+                // Unref the underlying Node socket so a short-lived script can exit once its work is done
+                // (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 }));
+            });
+            socket.addEventListener("message", (ev) => {
+                try {
+                    const msg = JSON.parse(wsDataToString(ev.data));
+                    if (msg.type === "auth_ok") {
+                        this.connected = true;
+                        this.backoff = 1000;
+                        this.flushQueue();
+                    }
+                    else if (msg.type === "ping") {
+                        socket.send(JSON.stringify({ type: "pong" }));
+                    }
+                    else if (msg.type === "error") {
+                        this.surfaceSignal(classifyServerSignal("error", msg.error));
+                    }
+                    else if (msg.type === "resume") {
+                        import("./resume.js").then(({ parseResumeMessage, handleResume }) => {
+                            const cmd = parseResumeMessage(msg);
+                            if (cmd)
+                                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";
+                        const signal = classifyServerSignal("halt", reason);
+                        // halt CHANGES behavior, deliberately: flush what's already recorded, then STOP recording
+                        // (close the transport). This is a hard server directive, distinct from credits_exhausted
+                        // (which leaves recording alive so the user can swap keys / upgrade mid-run). Surfaced as a
+                        // fatal signal — never a silent dark-out.
+                        this.surfaceSignal(signal);
+                        void this.flush().finally(() => this.close());
+                    }
+                    else {
+                        // DEFAULT: an unhandled/unknown server message type must not be silently swallowed (the
+                        // F-P6 class). Throttled-warn so a future message type surfaces instead of vanishing.
+                        this.warnUnknownType(msg.type);
+                    }
                 }
-                else if (msg.type === "halt") {
-                    const reason = msg.data?.reason || "Guardrail triggered";
-                    const signal = classifyServerSignal("halt", reason);
-                    // halt CHANGES behavior, deliberately: flush what's already recorded, then STOP recording
-                    // (close the transport). This is a hard server directive, distinct from credits_exhausted
-                    // (which leaves recording alive so the user can swap keys / upgrade mid-run). Surfaced as a
-                    // fatal signal — never a silent dark-out.
-                    this.surfaceSignal(signal);
-                    void this.flush().finally(() => this.close());
+                catch (e) {
+                    // A malformed/unparseable frame must not take down the listener.
+                    this.throttledSignalWarn("parse", `[retrace] dropped an unparseable server frame: ${e?.message ?? e}`);
                 }
-                else {
-                    // DEFAULT: an unhandled/unknown server message type must not be silently swallowed (the
-                    // F-P6 class). Throttled-warn so a future message type surfaces instead of vanishing.
-                    this.warnUnknownType(msg.type);
+            });
+            socket.addEventListener("close", () => {
+                this.connected = false;
+                this.ws = null;
+                if (!this.closed) {
+                    this.reconnectTimer = setTimeout(() => this.reconnect(), this.backoff * (0.5 + Math.random() * 0.5));
+                    // Don't let the reconnect timer keep the event loop (and the process) alive.
+                    this.reconnectTimer?.unref?.();
+                    this.backoff = Math.min(this.backoff * 2, 30000);
                 }
-            }
-            catch (e) {
-                // A malformed/unparseable frame must not take down the listener.
-                this.throttledSignalWarn("parse", `[retrace] dropped an unparseable server frame: ${e?.message ?? e}`);
-            }
-        });
-        this.ws.on("close", () => {
-            this.connected = false;
-            this.ws = null;
-            if (!this.closed) {
-                this.reconnectTimer = setTimeout(() => this.reconnect(), this.backoff * (0.5 + Math.random() * 0.5));
-                // Don't let the reconnect timer keep the event loop (and the process) alive.
-                this.reconnectTimer?.unref?.();
-                this.backoff = Math.min(this.backoff * 2, 30000);
-            }
-        });
-        this.ws.on("error", () => {
-            this.ws?.close();
+            });
+            socket.addEventListener("error", () => {
+                socket.close();
+            });
         });
     }
     reconnect() {
@@ -173,7 +227,7 @@ export class WSTransport {
     }
     /** Whether there is anything worth flushing on exit. */
     hasPendingData() {
-        return this.queue.length > 0 || (this.ws?.readyState === WebSocket.OPEN && this.ws.bufferedAmount > 0);
+        return this.queue.length > 0 || (this.ws?.readyState === WS_OPEN && this.ws.bufferedAmount > 0);
     }
     send(eventType, data) {
         // Unconfigured (no API key): never buffer and never reach the network. An imported-but-unused
@@ -188,7 +242,7 @@ export class WSTransport {
             return;
         }
         const item = { eventType, data, traceId, spanId };
-        if (this.connected && this.ws?.readyState === WebSocket.OPEN) {
+        if (this.connected && this.ws?.readyState === WS_OPEN) {
             this.transmit(item);
         }
         else {
@@ -216,7 +270,7 @@ export class WSTransport {
      *  the process before exit. Best-effort with a hard timeout. */
     async flush() {
         const start = Date.now();
-        while (this.ws && this.ws.readyState === WebSocket.OPEN && this.ws.bufferedAmount > 0 && Date.now() - start < 2000) {
+        while (this.ws && this.ws.readyState === WS_OPEN && this.ws.bufferedAmount > 0 && Date.now() - start < 2000) {
             await new Promise((r) => setTimeout(r, 50));
         }
     }
@@ -502,6 +556,9 @@ export function onProcessExit(fn) {
  * listenerCount gate here; Python via a SIG_DFL/main-thread gate) — that parity is real.
  */
 export function registerProcessExitFlush(transport, budgetMs = 1500) {
+    const proc = globalThis.process;
+    if (!proc || typeof proc.on !== "function")
+        return;
     const drain = async (reason) => {
         for (const h of preExitHooks) {
             try {
@@ -520,20 +577,20 @@ export function registerProcessExitFlush(transport, budgetMs = 1500) {
             await transport.flush();
     };
     let draining = false;
-    process.on("beforeExit", () => {
+    proc.on("beforeExit", () => {
         if (draining)
             return;
         draining = true;
         void drain("graceful").finally(() => { draining = false; });
     });
     for (const sig of ["SIGTERM", "SIGINT"]) {
-        const userOwnsExit = process.listenerCount(sig) > 0; // captured BEFORE we register ours
-        process.on(sig, () => {
+        const userOwnsExit = proc.listenerCount(sig) > 0; // captured BEFORE we register ours
+        proc.on(sig, () => {
             drain("signal").finally(() => {
                 // Sole listener: we suppressed the default terminate, so we must exit or the process hangs.
                 // User has their own handler: they own exit — never call it for them.
                 if (!userOwnsExit)
-                    process.exit(sig === "SIGINT" ? 130 : 143);
+                    proc.exit(sig === "SIGINT" ? 130 : 143);
             });
         });
     }

package/dist/utils.js

@@ -1,7 +1,12 @@
-import { randomUUID } from "crypto";
+// Runtime-agnostic UUID + UTF-8 byte helpers. Web Crypto (globalThis.crypto) and TextEncoder/
+// TextDecoder are available on Node 20+, Bun, Deno, browsers, and every edge runtime — so we avoid
+// a hard `node:crypto` import and the Node-only `Buffer`, both of which break module evaluation on
+// edge runtimes (Cloudflare Workers, Vercel Edge, Supabase Edge).
 export function genId() {
-    return randomUUID();
+    return globalThis.crypto.randomUUID();
 }
+const _textEncoder = new TextEncoder();
+const _textDecoder = new TextDecoder();
 export function nowIso() {
     return new Date().toISOString();
 }
@@ -32,9 +37,10 @@ export function shouldSample(rate, seed, key) {
 export function truncateJson(obj, maxBytes = 10240) {
     try {
         const s = JSON.stringify(obj);
-        if (Buffer.byteLength(s) <= maxBytes)
+        const bytes = _textEncoder.encode(s);
+        if (bytes.length <= maxBytes)
             return obj;
-        return JSON.parse(Buffer.from(s).subarray(0, maxBytes).toString());
+        return JSON.parse(_textDecoder.decode(bytes.subarray(0, maxBytes)));
     }
     catch {
         return String(obj).slice(0, maxBytes);
@@ -44,7 +50,7 @@ export function truncateJson(obj, maxBytes = 10240) {
  *  so the server refuses to byte-replay it (the replayed value would differ from the original). */
 export function wasTruncated(obj, maxBytes = 10240) {
     try {
-        return Buffer.byteLength(JSON.stringify(obj)) > maxBytes;
+        return _textEncoder.encode(JSON.stringify(obj)).length > maxBytes;
     }
     catch {
         return String(obj).length > maxBytes;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "retrace-sdk",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "The execution replay engine for AI agents. Record, replay, fork, and share agent executions.",
   "type": "module",
   "main": "dist/index.js",
@@ -53,7 +53,7 @@
     "test": "vitest run",
     "prepublishOnly": "npm run build"
   },
-  "dependencies": {
+  "optionalDependencies": {
     "ws": "^8.20.1"
   },
   "peerDependencies": {