retrace-sdk 0.16.6 → 0.16.8

package/README.md

@@ -1,6 +1,6 @@
 <div align="center">
 
-<img src="https://raw.githubusercontent.com/yash1511-bogam/retrace-sdk/main/assets/banner.gif" alt="Retrace" width="480" />
+<img src="https://raw.githubusercontent.com/Retraceai-tech/retrace-sdk/main/assets/banner.gif" alt="Retrace" width="480" />
 
 ![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?logo=typescript&logoColor=white)
 
@@ -207,7 +207,7 @@ Typed errors for auth failures, credit exhaustion, rate limiting, and enforcemen
 ## Links
 
 - [Documentation](https://docs.retraceai.tech)
-- [GitHub](https://github.com/yash1511-bogam/retrace-sdk)
+- [GitHub](https://github.com/Retraceai-tech/retrace-sdk)
 - [npm](https://www.npmjs.com/package/retrace-sdk)
 
 ## License

package/dist/enforcement.js

@@ -16,7 +16,7 @@ function shortHash(input) {
         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 n.toString(16).padStart(16, "0");
     };
     return (pass(0) + pass(0x9e3779b9)).slice(0, 32);
 }

package/dist/interceptors/anthropic.js

@@ -219,5 +219,6 @@ export function uninstallAnthropicInterceptor() {
             proto.create = originalCreate;
     }).catch(() => { });
     installed = false;
+    installStarted = false; // allow a subsequent installAnthropicInterceptor() to re-patch (was a no-op)
     onSpanCallback = null;
 }

package/dist/interceptors/openai.js

@@ -307,5 +307,6 @@ export function uninstallOpenAIInterceptor() {
             proto.create = originalCreate;
     }).catch(() => { });
     installed = false;
+    installStarted = false; // allow a subsequent installOpenAIInterceptor() to re-patch (was a no-op)
     onSpanCallback = null;
 }

package/dist/transport.d.ts

@@ -69,10 +69,24 @@ export declare class WSTransport implements Transport {
     private flushViaHttp;
 }
 export declare class HTTPTransport implements Transport {
-    private traceData;
-    private spans;
+    private pending;
+    private spanTrace;
+    private backlog;
+    private readonly backlogCap;
+    private dropped;
+    private entry;
     send(eventType: string, data: Record<string, unknown>): void;
-    flush(): Promise<void>;
+    /** Flush one trace (on its trace_ended) or, when no id is given, every pending trace (shutdown). */
+    flush(traceId?: string): Promise<void>;
+    private flushOne;
+    /** POST one complete trace payload. Returns "ok" | "reject" (non-retryable 4xx) | "retry"
+     *  (429 / 5xx / network after retries exhausted — caller should retain the payload). */
+    private upload;
+    /** Retain a failed trace for a later retry; bounded — drop + count the oldest on overflow. */
+    private enqueueBacklog;
+    /** Retry previously-failed traces oldest-first; stop at the first still-failing one so a server
+     *  that is still down isn't hammered. */
+    private drainBacklog;
     private buildSpans;
     close(): void;
     /** HTTP is already the one-shot channel — just drain. */

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 }));
+                socket.send(JSON.stringify({ type: "auth", api_key: getConfig().apiKey, resumable: getConfig().allowRemoteReplay }));
             });
             socket.addEventListener("message", (ev) => {
                 try {
@@ -347,31 +347,90 @@ export class WSTransport {
     }
 }
 export class HTTPTransport {
-    traceData = null;
-    spans = [];
+    // Buffer per-trace so concurrent traces in one process (parallel requests / Promise.all) never
+    // clobber each other. The previous single traceData/spans pair merged interleaved traces into one
+    // corrupt POST (trace B's trace_started overwrote A; A's flush sent B's data + both sets of spans).
+    // Keyed by trace id; spans route by their trace_id.
+    pending = new Map();
+    // span_ended events carry no trace_id (parity with the WS protocol), so remember each span's trace
+    // from its span_started to route the end event to the right per-trace buffer.
+    spanTrace = new Map();
+    // Bounded offline backlog (parity with WSTransport's queue + the Python HTTPTransport): a trace
+    // that fails to upload after exhausting transient retries is RETAINED here and retried on a later
+    // flush instead of being silently dropped. Bounded so a long outage can't grow memory unbounded.
+    backlog = [];
+    backlogCap = 1000;
+    dropped = 0;
+    entry(traceId) {
+        let e = this.pending.get(traceId);
+        if (!e) {
+            e = { data: {}, spans: [] };
+            this.pending.set(traceId, e);
+        }
+        return e;
+    }
     send(eventType, data) {
         if (eventType === "trace_started") {
-            this.traceData = data;
+            const id = data.id;
+            if (!id)
+                return;
+            const e = this.entry(id);
+            e.data = { ...e.data, ...data };
+        }
+        else if (eventType === "span_started") {
+            const tid = data.trace_id;
+            if (!tid)
+                return;
+            this.spanTrace.set(data.id, tid);
+            this.entry(tid).spans.push({ ...data, _event: eventType });
         }
-        else if (eventType === "span_started" || eventType === "span_ended") {
-            this.spans.push({ ...data, _event: eventType });
+        else if (eventType === "span_ended") {
+            // span_ended has no trace_id — route by the span id captured at span_started.
+            const tid = data.trace_id || this.spanTrace.get(data.id);
+            if (!tid)
+                return;
+            this.entry(tid).spans.push({ ...data, _event: eventType });
         }
         else if (eventType === "trace_ended") {
-            if (this.traceData)
-                Object.assign(this.traceData, data);
-            void this.flush();
+            const id = data.id;
+            if (!id)
+                return;
+            const e = this.pending.get(id);
+            if (e)
+                Object.assign(e.data, data);
+            void this.flush(id);
         }
     }
-    async flush() {
-        if (!this.traceData)
+    /** Flush one trace (on its trace_ended) or, when no id is given, every pending trace (shutdown). */
+    async flush(traceId) {
+        // Opportunistically retry anything stranded by a previous outage first.
+        if (this.backlog.length)
+            await this.drainBacklog();
+        if (traceId !== undefined) {
+            await this.flushOne(traceId);
             return;
+        }
+        for (const id of [...this.pending.keys()])
+            await this.flushOne(id);
+    }
+    async flushOne(traceId) {
+        const e = this.pending.get(traceId);
+        if (!e)
+            return;
+        // Remove first so a concurrent flush (e.g. trace_ended then shutdown drain) can't double-send.
+        this.pending.delete(traceId);
+        for (const ev of e.spans)
+            this.spanTrace.delete(ev.id);
+        const payload = JSON.stringify({ ...e.data, spans: this.buildSpans(e.spans) });
+        // On a transient failure, RETAIN the trace in the bounded backlog instead of dropping it.
+        if ((await this.upload(payload)) === "retry")
+            this.enqueueBacklog(payload);
+    }
+    /** POST one complete trace payload. Returns "ok" | "reject" (non-retryable 4xx) | "retry"
+     *  (429 / 5xx / network after retries exhausted — caller should retain the payload). */
+    async upload(payload) {
         const cfg = getConfig();
         const url = `${cfg.baseUrl}/api/v1/traces`;
-        const body = { ...this.traceData, spans: this.buildSpans() };
-        const payload = JSON.stringify(body);
-        // 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 {
@@ -381,13 +440,13 @@ export class HTTPTransport {
                     body: payload,
                 });
                 if (res.ok)
-                    return;
+                    return "ok";
                 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;
+                    return "reject";
                 }
                 // 5xx / 429 — transient; retry.
                 if (n === 3)
@@ -400,10 +459,30 @@ export class HTTPTransport {
             if (n < 3)
                 await new Promise((r) => setTimeout(r, 1000 * n));
         }
+        return "retry";
+    }
+    /** Retain a failed trace for a later retry; bounded — drop + count the oldest on overflow. */
+    enqueueBacklog(payload) {
+        this.backlog.push(payload);
+        while (this.backlog.length > this.backlogCap) {
+            this.backlog.shift();
+            this.dropped++;
+            console.error(`[retrace] offline buffer full (cap ${this.backlogCap}) — dropped oldest trace (total dropped: ${this.dropped})`);
+        }
+    }
+    /** Retry previously-failed traces oldest-first; stop at the first still-failing one so a server
+     *  that is still down isn't hammered. */
+    async drainBacklog() {
+        while (this.backlog.length) {
+            const r = await this.upload(this.backlog[0]);
+            if (r === "retry")
+                break; // still failing — keep the rest for next time
+            this.backlog.shift(); // "ok" (delivered) or "reject" (unrecoverable) → remove
+        }
     }
-    buildSpans() {
+    buildSpans(spans) {
         const merged = new Map();
-        for (const ev of this.spans) {
+        for (const ev of spans) {
             const { _event, ...rest } = ev;
             const id = rest.id;
             if (_event === "span_started") {
@@ -423,7 +502,7 @@ export class HTTPTransport {
         await this.flush();
     }
     hasPendingData() {
-        return this.traceData !== null || this.spans.length > 0;
+        return this.pending.size > 0 || this.backlog.length > 0;
     }
 }
 export function createTransport(mode = "auto") {

package/dist/utils.js

@@ -6,7 +6,6 @@ export function genId() {
     return globalThis.crypto.randomUUID();
 }
 const _textEncoder = new TextEncoder();
-const _textDecoder = new TextDecoder();
 export function nowIso() {
     return new Date().toISOString();
 }
@@ -34,17 +33,47 @@ export function shouldSample(rate, seed, key) {
     }
     return ((hash >>> 0) / 4294967296) < rate;
 }
+/** Truncate a string to at most `maxBytes` UTF-8 bytes WITHOUT splitting a multi-byte codepoint, so
+ *  there's no garbled/replacement-char tail. Iterates whole code points (via the string iterator). */
+function sliceStringToBytes(s, maxBytes) {
+    if (maxBytes <= 0)
+        return "";
+    if (_textEncoder.encode(s).length <= maxBytes)
+        return s;
+    let out = "";
+    let n = 0;
+    for (const ch of s) {
+        const b = _textEncoder.encode(ch).length;
+        if (n + b > maxBytes)
+            break;
+        out += ch;
+        n += b;
+    }
+    return out;
+}
 export function truncateJson(obj, maxBytes = 10240) {
+    let s;
     try {
-        const s = JSON.stringify(obj);
-        const bytes = _textEncoder.encode(s);
-        if (bytes.length <= maxBytes)
-            return obj;
-        return JSON.parse(_textDecoder.decode(bytes.subarray(0, maxBytes)));
+        s = JSON.stringify(obj);
     }
     catch {
-        return String(obj).slice(0, maxBytes);
+        s = undefined;
     }
+    // Not JSON-serializable (circular ref, BigInt, …): char-safe string slice, not a broken parse.
+    if (typeof s !== "string")
+        return sliceStringToBytes(String(obj), maxBytes);
+    const byteLen = _textEncoder.encode(s).length;
+    if (byteLen <= maxBytes)
+        return obj;
+    // Over the limit. Return a self-describing, VALID marker with a UTF-8-safe preview. The old code
+    // byte-sliced the JSON mid-codepoint and JSON.parse()'d the fragment — which almost always threw,
+    // falling back to String(obj) = "[object Object]" for any object (total data loss) and a garbled
+    // tail for strings. `wasTruncated` still flags this so the server refuses to byte-replay it.
+    return {
+        _truncated: true,
+        _original_bytes: byteLen,
+        _preview: sliceStringToBytes(s, Math.max(0, maxBytes - 64)),
+    };
 }
 /** True if truncateJson(obj, maxBytes) would drop bytes. Used to flag a span's output as truncated
  *  so the server refuses to byte-replay it (the replayed value would differ from the original). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "retrace-sdk",
-  "version": "0.16.6",
+  "version": "0.16.8",
   "description": "The execution replay engine for AI agents. Record, replay, fork, and share agent executions.",
   "type": "module",
   "main": "dist/index.js",
@@ -28,7 +28,7 @@
   "author": "Yash Bogam",
   "repository": {
     "type": "git",
-    "url": "https://github.com/yash1511-bogam/retrace-sdk",
+    "url": "https://github.com/Retraceai-tech/retrace-sdk",
     "directory": "packages/sdk-typescript"
   },
   "homepage": "https://retraceai.tech/docs/sdk-typescript",