retrace-sdk 0.9.0 → 0.11.0

package/dist/config.d.ts

@@ -7,6 +7,10 @@ export interface Config {
     sampleRate: number;
     /** Optional seed for deterministic sampling. When set, the same trace name always produces the same sample decision. */
     sampleSeed: string | undefined;
+    /** Transport mode. "auto" (default) tries WebSocket then falls back to HTTP; "http" is
+     *  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";
 }
 export declare function configure(opts: Partial<Config>): Config;
 export declare function requireApiKey(): string;

package/dist/config.js

@@ -6,6 +6,7 @@ const config = {
     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"),
 };
 config.wsUrl = config.baseUrl.replace("https://", "wss://").replace("http://", "ws://");
 export function configure(opts) {

package/dist/init.js

@@ -1,5 +1,5 @@
 import { configure, getConfig, requireApiKey } from "./config.js";
-import { TraceRecorder } from "./recorder.js";
+import { TraceRecorder, flushSharedTransport } from "./recorder.js";
 import { TraceStatus } from "./trace.js";
 let ambient = null;
 let exitHooked = false;
@@ -54,10 +54,20 @@ export function init(opts = {}) {
             }
             catch { /* best effort on shutdown */ }
         };
+        // On signal-triggered exits, process.exit() would otherwise kill the process before the
+        // final trace_ended is delivered over the network. End the trace, then await a transport
+        // drain (capped by a hard timeout so a hung network can't block shutdown) before exiting.
+        const finishAndExit = (status, code) => {
+            finish(status);
+            void Promise.race([
+                flushSharedTransport().catch(() => { }),
+                new Promise((r) => setTimeout(r, 3000)),
+            ]).then(() => process.exit(code));
+        };
         process.once("beforeExit", () => finish(TraceStatus.COMPLETED));
-        process.once("SIGINT", () => { finish(TraceStatus.COMPLETED); process.exit(130); });
-        process.once("SIGTERM", () => { finish(TraceStatus.COMPLETED); process.exit(143); });
-        process.once("uncaughtException", (err) => { finish(TraceStatus.FAILED); console.error(err); process.exit(1); });
+        process.once("SIGINT", () => finishAndExit(TraceStatus.COMPLETED, 130));
+        process.once("SIGTERM", () => finishAndExit(TraceStatus.COMPLETED, 143));
+        process.once("uncaughtException", (err) => { console.error(err); finishAndExit(TraceStatus.FAILED, 1); });
     }
     return ambient;
 }

package/dist/recorder.d.ts

@@ -1,4 +1,6 @@
 import { SpanBuilder, SpanData, SpanType, TraceStatus } from "./trace.js";
+/** Drain the shared transport's in-flight data to the network (awaited on graceful shutdown). */
+export declare function flushSharedTransport(): Promise<void>;
 export interface RecordOptions {
     name?: string;
     input?: unknown;

package/dist/recorder.js

@@ -9,14 +9,19 @@ import { installAnthropicInterceptor } from "./interceptors/anthropic.js";
 let sharedTransport = null;
 function getSharedTransport() {
     if (!sharedTransport) {
-        sharedTransport = createTransport();
-        // Flush pending data before process exits
+        sharedTransport = createTransport(getConfig().transport);
+        // Flush pending data before the process exits. Flushing (not just close) ensures the
+        // final trace is actually uploaded — close() alone can race the process exiting.
         if (typeof process !== "undefined") {
-            process.on("beforeExit", () => { sharedTransport?.close(); });
+            process.on("beforeExit", () => { void flushSharedTransport(); });
         }
     }
     return sharedTransport;
 }
+/** Drain the shared transport's in-flight data to the network (awaited on graceful shutdown). */
+export async function flushSharedTransport() {
+    await sharedTransport?.flush();
+}
 export class TraceRecorder {
     builder;
     transport;

package/dist/trace.js

@@ -83,7 +83,12 @@ export class TraceBuilder {
         return this.data;
     }
     addSpan(span) {
-        this.data.spans.push(span);
+        // Spans are streamed individually through the transport (and HTTPTransport keeps its own
+        // per-trace buffer for the batched POST), so this retained array is only an in-memory
+        // convenience and is never itself transmitted. Cap it so init()'s long-lived ambient
+        // trace can't accumulate spans for the life of the process (an unbounded memory leak).
+        if (this.data.spans.length < 1000)
+            this.data.spans.push(span);
         this.data.total_tokens += (span.input_tokens || 0) + (span.output_tokens || 0);
         this.data.total_cost += span.cost || 0;
     }

package/dist/transport.d.ts

@@ -1,6 +1,8 @@
 export interface Transport {
     send(eventType: string, data: Record<string, unknown>): void;
     close(): void;
+    /** Drain in-flight data to the network (awaited on graceful shutdown). */
+    flush(): Promise<void>;
 }
 export declare class WSTransport implements Transport {
     private ws;
@@ -8,6 +10,7 @@ export declare class WSTransport implements Transport {
     private closed;
     private backoff;
     private queue;
+    private reconnectTimer;
     onError?: (type: string, message: string) => void;
     get isConnected(): boolean;
     connect(): void;
@@ -15,12 +18,15 @@ export declare class WSTransport implements Transport {
     private flushQueue;
     send(eventType: string, data: Record<string, unknown>): void;
     close(): void;
+    /** Wait for the socket's send buffer to drain so the final trace_ended actually leaves
+     *  the process before exit. Best-effort with a hard timeout. */
+    flush(): Promise<void>;
 }
 export declare class HTTPTransport implements Transport {
     private traceData;
     private spans;
     send(eventType: string, data: Record<string, unknown>): void;
-    flush(): void;
+    flush(): Promise<void>;
     private buildSpans;
     close(): void;
 }

package/dist/transport.js

@@ -6,6 +6,7 @@ export class WSTransport {
     closed = false;
     backoff = 1000;
     queue = [];
+    reconnectTimer = null;
     onError;
     get isConnected() { return this.connected; }
     connect() {
@@ -15,6 +16,10 @@ export class WSTransport {
         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) => {
@@ -60,7 +65,9 @@ export class WSTransport {
             this.connected = false;
             this.ws = null;
             if (!this.closed) {
-                setTimeout(() => this.reconnect(), this.backoff * (0.5 + Math.random() * 0.5));
+                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);
             }
         });
@@ -92,12 +99,24 @@ export class WSTransport {
     }
     close() {
         this.closed = true;
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
         if (this.ws) {
             this.ws.close();
             this.ws = null;
         }
         this.connected = false;
     }
+    /** Wait for the socket's send buffer to drain so the final trace_ended actually leaves
+     *  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) {
+            await new Promise((r) => setTimeout(r, 50));
+        }
+    }
 }
 export class HTTPTransport {
     traceData = null;
@@ -112,28 +131,47 @@ export class HTTPTransport {
         else if (eventType === "trace_ended") {
             if (this.traceData)
                 Object.assign(this.traceData, data);
-            this.flush();
+            void this.flush();
         }
     }
-    flush() {
+    async flush() {
         if (!this.traceData)
             return;
         const cfg = getConfig();
         const url = `${cfg.baseUrl}/api/v1/traces`;
         const body = { ...this.traceData, spans: this.buildSpans() };
         const payload = JSON.stringify(body);
-        // Retry up to 3 times with exponential backoff
-        const attempt = (n, delay) => {
-            fetch(url, {
-                method: "POST",
-                headers: { "x-retrace-key": cfg.apiKey, "Content-Type": "application/json" },
-                body: payload,
-            }).catch(() => { if (n < 3)
-                setTimeout(() => attempt(n + 1, delay * 2), delay); });
-        };
-        attempt(1, 1000);
+        // Clear first so a concurrent flush (e.g. trace_ended then shutdown drain) can't double-send.
         this.traceData = null;
         this.spans = [];
+        // Retry up to 3 times with exponential backoff; awaited so shutdown can drain it.
+        for (let n = 1; n <= 3; n++) {
+            try {
+                const res = await fetch(url, {
+                    method: "POST",
+                    headers: { "x-retrace-key": cfg.apiKey, "Content-Type": "application/json" },
+                    body: payload,
+                });
+                if (res.ok)
+                    return;
+                const txt = await res.text().catch(() => "");
+                // 4xx (except 429) is a client/payload error that won't succeed on retry — surface
+                // it loudly and stop, rather than silently dropping the trace.
+                if (res.status < 500 && res.status !== 429) {
+                    console.error(`[retrace] trace upload rejected (HTTP ${res.status}): ${txt.slice(0, 300)}`);
+                    return;
+                }
+                // 5xx / 429 — transient; retry.
+                if (n === 3)
+                    console.error(`[retrace] trace upload failed after ${n} attempts (HTTP ${res.status}): ${txt.slice(0, 200)}`);
+            }
+            catch (err) {
+                if (n === 3)
+                    console.error(`[retrace] trace upload network error after ${n} attempts: ${err?.message ?? err}`);
+            }
+            if (n < 3)
+                await new Promise((r) => setTimeout(r, 1000 * n));
+        }
     }
     buildSpans() {
         const merged = new Map();
@@ -150,7 +188,7 @@ export class HTTPTransport {
         return [...merged.values()];
     }
     close() {
-        this.flush();
+        void this.flush();
     }
 }
 export function createTransport(mode = "auto") {
@@ -214,5 +252,24 @@ export function createTransport(mode = "auto") {
                 http.close();
             }
         },
+        async flush() {
+            if (!decided) {
+                // Never connected over WS — force the HTTP fallback and drain the buffer so the
+                // final trace isn't lost on shutdown.
+                decided = true;
+                useWs = false;
+                clearTimeout(fallbackTimer);
+                ws.close();
+                for (const item of buffer.splice(0))
+                    http.send(item.eventType, item.data);
+                await http.flush();
+            }
+            else if (useWs) {
+                await ws.flush();
+            }
+            else {
+                await http.flush();
+            }
+        },
     };
 }

package/package.json

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