retrace-sdk 0.10.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/recorder.js

@@ -9,10 +9,11 @@ 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;

package/dist/transport.d.ts

@@ -10,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;

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,6 +99,10 @@ 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;
@@ -136,17 +147,30 @@ export class HTTPTransport {
         // Retry up to 3 times with exponential backoff; awaited so shutdown can drain it.
         for (let n = 1; n <= 3; n++) {
             try {
-                await fetch(url, {
+                const res = await fetch(url, {
                     method: "POST",
                     headers: { "x-retrace-key": cfg.apiKey, "Content-Type": "application/json" },
                     body: payload,
                 });
-                return;
+                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 {
-                if (n < 3)
-                    await new Promise((r) => setTimeout(r, 1000 * n));
+            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() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "retrace-sdk",
-  "version": "0.10.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",