retrace-sdk 0.2.0 → 0.2.1

package/README.md

@@ -67,9 +67,53 @@ recorder.endSpan(span, { results: ["..."] });
 recorder.end("Done");
 ```
 
-## API Key
+## Resumable Execution (Cascade Replay)
 
-A Retrace API key (`rt_live_...`) is required. Get yours free at [retrace.yashbogam.me/settings](https://retrace.yashbogam.me/settings).
+Mark a function as resumable to enable full cascade replay from the dashboard:
+
+```typescript
+import { configure, trace } from "retrace-sdk";
+
+configure({ apiKey: "rt_live_..." });
+
+const myAgent = trace(async (prompt: string) => {
+  const plan = await planner(prompt);
+  const result = await executor(plan);
+  return summarize(result);
+}, { name: "my-agent", resumable: true });
+```
+
+When you fork at any span in the dashboard, the SDK re-executes the entire function with modified input — not just one LLM call.
+
+## Error Handling
+
+```typescript
+import { RetraceError, RetraceAuthError, RetraceCreditsExhaustedError, RetraceRateLimitError } from "retrace-sdk";
+```
+
+Typed errors for auth failures, credit exhaustion, and rate limiting.
+
+## Sampling
+
+```typescript
+configure({ apiKey: "rt_live_...", sampleRate: 0.1 }); // Record 10% of traces
+```
+
+## Changelog
+
+### 0.2.1
+
+- **Offline buffer** — stores up to 1000 messages when WebSocket disconnects, flushes on reconnect
+- **HTTP retry** — 3 attempts with exponential backoff on fallback transport
+- **Cascade replay** — `resumable: true` option registers function for SDK-level re-execution
+- **Resume listener** — handles server 'resume' commands for fork replay
+
+### 0.2.0
+
+- Typed errors (RetraceAuthError, RetraceCreditsExhaustedError, RetraceRateLimitError)
+- Trace sampling via `sampleRate` config
+- Auto-instrumentation for OpenAI, Anthropic, Gemini
+- WebSocket + HTTP fallback transport
 
 ## Links
 

package/dist/config.js

@@ -1,6 +1,6 @@
 const config = {
     apiKey: process.env.RETRACE_API_KEY || "",
-    baseUrl: process.env.RETRACE_BASE_URL || "http://localhost:3001",
+    baseUrl: process.env.RETRACE_BASE_URL || "https://api-retrace.yashbogam.me",
     wsUrl: "",
     projectId: process.env.RETRACE_PROJECT_ID || undefined,
     enabled: !["false", "0"].includes((process.env.RETRACE_ENABLED || "true").toLowerCase()),

package/dist/errors.d.ts

@@ -0,0 +1,16 @@
+export declare class RetraceError extends Error {
+    constructor(message: string);
+}
+export declare class RetraceAuthError extends RetraceError {
+    constructor(message?: string);
+}
+export declare class RetraceCreditsExhaustedError extends RetraceError {
+    constructor(message?: string);
+}
+export declare class RetraceConnectionError extends RetraceError {
+    constructor(message?: string);
+}
+export declare class RetraceRateLimitError extends RetraceError {
+    retryAfter: number;
+    constructor(retryAfter: number);
+}

package/dist/errors.js

@@ -0,0 +1,16 @@
+export class RetraceError extends Error {
+    constructor(message) { super(message); this.name = "RetraceError"; }
+}
+export class RetraceAuthError extends RetraceError {
+    constructor(message = "Invalid or missing API key") { super(message); this.name = "RetraceAuthError"; }
+}
+export class RetraceCreditsExhaustedError extends RetraceError {
+    constructor(message = "Monthly trace limit reached. Upgrade at retrace.yashbogam.me/pricing") { super(message); this.name = "RetraceCreditsExhaustedError"; }
+}
+export class RetraceConnectionError extends RetraceError {
+    constructor(message = "Failed to connect to Retrace API") { super(message); this.name = "RetraceConnectionError"; }
+}
+export class RetraceRateLimitError extends RetraceError {
+    retryAfter;
+    constructor(retryAfter) { super(`Rate limited. Retry after ${retryAfter}s`); this.name = "RetraceRateLimitError"; this.retryAfter = retryAfter; }
+}

package/dist/index.d.ts

@@ -6,3 +6,6 @@ export { SpanType, TraceStatus } from "./trace.js";
 export { installGeminiInterceptor, uninstallGeminiInterceptor } from "./interceptors/gemini.js";
 export { installOpenAIInterceptor, uninstallOpenAIInterceptor } from "./interceptors/openai.js";
 export { installAnthropicInterceptor, uninstallAnthropicInterceptor } from "./interceptors/anthropic.js";
+export { RetraceError, RetraceAuthError, RetraceCreditsExhaustedError, RetraceConnectionError, RetraceRateLimitError } from "./errors.js";
+export { registerResumable, handleResume } from "./resume.js";
+export type { ResumeCommand } from "./resume.js";

package/dist/index.js

@@ -5,3 +5,5 @@ export { SpanType, TraceStatus } from "./trace.js";
 export { installGeminiInterceptor, uninstallGeminiInterceptor } from "./interceptors/gemini.js";
 export { installOpenAIInterceptor, uninstallOpenAIInterceptor } from "./interceptors/openai.js";
 export { installAnthropicInterceptor, uninstallAnthropicInterceptor } from "./interceptors/anthropic.js";
+export { RetraceError, RetraceAuthError, RetraceCreditsExhaustedError, RetraceConnectionError, RetraceRateLimitError } from "./errors.js";
+export { registerResumable, handleResume } from "./resume.js";

package/dist/recorder.d.ts

@@ -19,4 +19,6 @@ export declare class TraceRecorder {
     private installInterceptors;
 }
 export declare function record(opts?: RecordOptions): TraceRecorder;
-export declare function trace<T>(fn: (...args: unknown[]) => T, opts?: RecordOptions): (...args: unknown[]) => T;
+export declare function trace<T>(fn: (...args: unknown[]) => T, opts?: RecordOptions & {
+    resumable?: boolean;
+}): (...args: unknown[]) => T;

package/dist/recorder.js

@@ -103,6 +103,12 @@ export function record(opts) {
 }
 export function trace(fn, opts) {
     const cfg = getConfig();
+    // Register for cascade replay if resumable
+    if (opts?.resumable) {
+        import("./resume.js").then(({ registerResumable }) => {
+            registerResumable(opts?.name || fn.name || "anonymous", fn);
+        });
+    }
     return (...args) => {
         if (!cfg.enabled || Math.random() > cfg.sampleRate)
             return fn(...args);

package/dist/resume.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Full cascade replay for Retrace TypeScript SDK.
+ *
+ * When trace({ resumable: true }) is used, the SDK:
+ * 1. Stores the function reference
+ * 2. Listens for 'resume' commands on WebSocket
+ * 3. Re-executes the function with modified input
+ * 4. Streams new spans back
+ */
+export interface ResumeCommand {
+    forkId: string;
+    traceId: string;
+    traceName: string;
+    forkPointSpanId: string;
+    modifiedInput: unknown;
+    originalArgs?: unknown[];
+}
+export declare function registerResumable(name: string, fn: (...args: unknown[]) => unknown): void;
+export declare function getResumable(name: string): ((...args: unknown[]) => unknown) | undefined;
+export declare function handleResume(command: ResumeCommand): boolean;
+export declare function parseResumeMessage(msg: {
+    type: string;
+    data?: Record<string, unknown>;
+}): ResumeCommand | null;

package/dist/resume.js

@@ -0,0 +1,66 @@
+/**
+ * Full cascade replay for Retrace TypeScript SDK.
+ *
+ * When trace({ resumable: true }) is used, the SDK:
+ * 1. Stores the function reference
+ * 2. Listens for 'resume' commands on WebSocket
+ * 3. Re-executes the function with modified input
+ * 4. Streams new spans back
+ */
+// Registry of resumable functions
+const resumableFunctions = new Map();
+export function registerResumable(name, fn) {
+    resumableFunctions.set(name, fn);
+}
+export function getResumable(name) {
+    return resumableFunctions.get(name);
+}
+export function handleResume(command) {
+    const fn = getResumable(command.traceName);
+    if (!fn)
+        return false;
+    // Re-execute async in background
+    (async () => {
+        try {
+            const { TraceRecorder } = await import("./recorder.js");
+            const { TraceStatus } = await import("./trace.js");
+            const recorder = new TraceRecorder({
+                name: `Fork: ${command.traceName}`,
+                input: command.modifiedInput,
+                metadata: {
+                    _fork_id: command.forkId,
+                    _fork_of: command.traceId,
+                    _fork_point: command.forkPointSpanId,
+                    _cascade_replay: true,
+                },
+            });
+            recorder.start(`Fork: ${command.traceName}`, command.modifiedInput);
+            // Determine args for re-execution
+            let args = command.originalArgs || [];
+            if (typeof command.modifiedInput === "string") {
+                args = [command.modifiedInput, ...args.slice(1)];
+            }
+            else if (typeof command.modifiedInput === "object" && !Array.isArray(command.modifiedInput)) {
+                args = [command.modifiedInput];
+            }
+            const result = await Promise.resolve(fn(...args));
+            recorder.end(result, TraceStatus.COMPLETED);
+        }
+        catch (err) {
+            console.error("[retrace] Cascade replay failed:", err);
+        }
+    })();
+    return true;
+}
+export function parseResumeMessage(msg) {
+    if (msg.type !== "resume" || !msg.data)
+        return null;
+    return {
+        forkId: msg.data.forkId,
+        traceId: msg.data.traceId,
+        traceName: msg.data.traceName,
+        forkPointSpanId: msg.data.forkPointSpanId,
+        modifiedInput: msg.data.modifiedInput,
+        originalArgs: msg.data.originalArgs,
+    };
+}

package/dist/transport.d.ts

@@ -8,6 +8,7 @@ export declare class WSTransport implements Transport {
     private closed;
     private backoff;
     private queue;
+    onError?: (type: string, message: string) => void;
     get isConnected(): boolean;
     connect(): void;
     private reconnect;

package/dist/transport.js

@@ -6,6 +6,7 @@ export class WSTransport {
     closed = false;
     backoff = 1000;
     queue = [];
+    onError;
     get isConnected() { return this.connected; }
     connect() {
         if (this.closed)
@@ -26,6 +27,22 @@ export class WSTransport {
             else if (msg.type === "ping") {
                 this.ws?.send(JSON.stringify({ type: "pong" }));
             }
+            else if (msg.type === "error") {
+                const err = msg.error;
+                if (err?.includes("limit reached"))
+                    this.onError?.("credits_exhausted", err);
+                else if (err?.includes("Rate limit"))
+                    this.onError?.("rate_limited", err);
+                else
+                    this.onError?.("error", err);
+            }
+            else if (msg.type === "resume") {
+                import("./resume.js").then(({ parseResumeMessage, handleResume }) => {
+                    const cmd = parseResumeMessage(msg);
+                    if (cmd)
+                        handleResume(cmd);
+                });
+            }
         });
         this.ws.on("close", () => {
             this.connected = false;
@@ -54,7 +71,9 @@ export class WSTransport {
             this.ws.send(msg);
         }
         else {
-            this.queue.push(msg);
+            // Cap offline buffer at 1000 messages to prevent memory leak
+            if (this.queue.length < 1000)
+                this.queue.push(msg);
             if (!this.ws && !this.closed)
                 this.connect();
         }
@@ -90,11 +109,17 @@ export class HTTPTransport {
         const cfg = getConfig();
         const url = `${cfg.baseUrl}/api/v1/traces`;
         const body = { ...this.traceData, spans: this.buildSpans() };
-        fetch(url, {
-            method: "POST",
-            headers: { "x-retrace-key": cfg.apiKey, "Content-Type": "application/json" },
-            body: JSON.stringify(body),
-        }).catch(() => { });
+        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);
         this.traceData = null;
         this.spans = [];
     }

package/package.json

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