retrace-sdk 0.16.7 → 0.16.9

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/config.js

@@ -63,7 +63,7 @@ export function configure(opts) {
     if (config.enabled) {
         void import("./interceptors/install.js").then((m) => m.ensureInterceptorsInstalled()).catch(() => { });
     }
-    void import("./telemetry.js").then((m) => m.track("configure")).catch(() => { });
+    void import("./telemetry.js").then((m) => m.track("sdk_init", { has_api_key: !!config.apiKey, enabled: config.enabled })).catch(() => { });
     return config;
 }
 export function requireApiKey() {

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

@@ -184,6 +184,13 @@ export class TraceRecorder {
             // lossy / capture_complete:false). Only a naturally-drained run produces a clean terminal.
             ...(opts?.terminatedEarly ? { terminated_early: true } : {}),
         });
+        // Anonymous usage analytics (fire-and-forget; never throws): record success/failure + which
+        // provider families ran. No PII, no user content.
+        try {
+            const dict = this.builder.toDict();
+            void import("./telemetry.js").then((m) => m.trackRecord(String(data.status), dict.spans ?? [], dict.metadata ?? {})).catch(() => { });
+        }
+        catch { /* never affect the user's program */ }
         // Restore the enclosing trace's fallback (e.g. the ambient init() recorder) instead of nulling.
         setActiveRecorderFallback(this.prevFallback, this.prevFallbackSink);
         this.prevFallback = null;

package/dist/telemetry.d.ts

@@ -1 +1,8 @@
+/** Coarse provider family from a model name (analytics only — never the key or content). */
+export declare function providerOf(model?: string | null): string;
 export declare function track(event: string, fields?: Record<string, string | number | boolean>): void;
+/** Emit record_success / record_failure with anonymous, aggregate-only fields (span count, provider
+ *  families used, whether the run was resumable / a cascade replay). Never throws. */
+export declare function trackRecord(status: string, spans: Array<{
+    model?: string | null;
+}>, metadata?: Record<string, unknown>): void;

package/dist/telemetry.js

@@ -1,26 +1,35 @@
 /**
- * Anonymous, opt-out diagnostic telemetry.
+ * Anonymous, always-on diagnostic telemetry.
  *
  * Sends NO user code, API keys, prompts, responses, or personal information — only the SDK version,
- * the runtime/OS family, an anonymous per-process id, and event/error *categories* — to the Retrace
- * API's internal log ingest (forwarded to the centralized logging platform under
- * service="sdk-typescript"). Fire-and-forget; never blocks, never throws.
+ * the runtime/OS family, an anonymous per-process id, and event/error *categories*. Events are POSTed
+ * to the Retrace API's internal ingest, which forwards them to PostHog (and the logging platform)
+ * under service="sdk-typescript" — so the SDK NEVER holds any analytics key (SDK → Retrace API →
+ * PostHog).
  *
- * Disable entirely with RETRACE_TELEMETRY=0 (also accepts false/no/off).
+ * Fire-and-forget: never blocks the user's program, never throws. Anonymous by construction (no PII,
+ * random per-process id) and intentionally NOT user-disableable.
  */
 import os from "node:os";
 import { getConfig } from "./config.js";
 // Per-process random id — anonymous, not linked to any account, user, or machine identity.
 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.16.5";
-function enabled() {
-    return !DISABLED.has((process.env.RETRACE_TELEMETRY ?? "1").trim().toLowerCase());
+const SDK_VERSION = "0.16.9";
+/** Coarse provider family from a model name (analytics only — never the key or content). */
+export function providerOf(model) {
+    const m = (model || "").toLowerCase();
+    if (!m)
+        return "";
+    if (m.startsWith("gemini") || m.includes("google"))
+        return "google";
+    if (/^(gpt|o1|o3|o4|chatgpt|text-embedding|davinci)/.test(m))
+        return "openai";
+    if (m.includes("claude"))
+        return "anthropic";
+    return "other";
 }
 export function track(event, fields = {}) {
-    if (!enabled())
-        return;
     try {
         const base = (getConfig().baseUrl || "https://api.retraceai.tech").replace(/\/$/, "");
         const body = JSON.stringify({
@@ -49,3 +58,19 @@ export function track(event, fields = {}) {
         /* telemetry must never affect the user's program */
     }
 }
+/** Emit record_success / record_failure with anonymous, aggregate-only fields (span count, provider
+ *  families used, whether the run was resumable / a cascade replay). Never throws. */
+export function trackRecord(status, spans, metadata = {}) {
+    try {
+        const provs = Array.from(new Set(spans.map((s) => providerOf(s.model)).filter(Boolean)));
+        track(status === "completed" ? "record_success" : "record_failure", {
+            spans: spans.length,
+            providers: provs.join(",") || "none",
+            resumable: !!metadata._resumable,
+            cascade: !!metadata._cascade_replay,
+        });
+    }
+    catch {
+        /* never throw */
+    }
+}

package/dist/transport.d.ts

@@ -69,13 +69,16 @@ 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;

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,40 +347,82 @@ 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" || eventType === "span_ended") {
-            this.spans.push({ ...data, _event: eventType });
+        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_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() {
+    /** 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 (!this.traceData)
+        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;
-        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 = [];
-        // On a transient failure, RETAIN the trace in the bounded backlog instead of dropping it — the
-        // previous code cleared the buffer unconditionally, losing the trace under sustained 429/5xx.
+        // 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);
     }
@@ -438,9 +480,9 @@ export class HTTPTransport {
             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") {
@@ -460,7 +502,7 @@ export class HTTPTransport {
         await this.flush();
     }
     hasPendingData() {
-        return this.traceData !== null || this.spans.length > 0 || this.backlog.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.7",
+  "version": "0.16.9",
   "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",