retrace-sdk 0.9.0 → 0.10.0

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

@@ -17,6 +17,10 @@ function getSharedTransport() {
     }
     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;
@@ -15,12 +17,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

@@ -98,6 +98,14 @@ export class WSTransport {
         }
         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 +120,34 @@ 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 {
+                await fetch(url, {
+                    method: "POST",
+                    headers: { "x-retrace-key": cfg.apiKey, "Content-Type": "application/json" },
+                    body: payload,
+                });
+                return;
+            }
+            catch {
+                if (n < 3)
+                    await new Promise((r) => setTimeout(r, 1000 * n));
+            }
+        }
     }
     buildSpans() {
         const merged = new Map();
@@ -150,7 +164,7 @@ export class HTTPTransport {
         return [...merged.values()];
     }
     close() {
-        this.flush();
+        void this.flush();
     }
 }
 export function createTransport(mode = "auto") {
@@ -214,5 +228,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.10.0",
   "description": "The execution replay engine for AI agents. Record, replay, fork, and share agent executions.",
   "type": "module",
   "main": "dist/index.js",