retrace-sdk 0.16.0 → 0.16.1

package/README.md

@@ -1,58 +1,118 @@
-# retrace-sdk
+<div align="center">
 
-The execution replay engine for AI agents. Record, replay, fork & share AI agent executions — TypeScript SDK.
+<img src="https://raw.githubusercontent.com/yash1511-bogam/retrace-sdk/main/assets/banner.gif" alt="Retrace" width="480" />
 
-## Installation
+![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?logo=typescript&logoColor=white)
+
+Record every LLM call, tool invocation, and error your agent makes. Replay it step-by-step like a video. Fork from any point, change the input, and watch the whole agent re-execute down a new path. Share any run as an interactive, public link.
+
+[Quick Start](#quick-start) · [How It Works](#how-it-works) · [Recipes](#usage-recipes) · [Enforcement](#enforcement-circuit-breakers) · [Docs](https://docs.retraceai.tech)
+
+</div>
+
+---
+
+## Install
 
 ```bash
 npm install retrace-sdk
 ```
 
-Requires Node.js 20+. ESM-only package.
+Requires Node.js 20+. ESM-only. Works in Node and edge runtimes.
+
+---
 
 ## Quick Start
 
 ```typescript
 import { configure, trace } from "retrace-sdk";
 
-configure({ apiKey: "rt_..." }); // Get your key at retraceai.tech/settings
+configure({ apiKey: "rt_..." }); // get a key in the dashboard
 
-const myAgent = trace(async (prompt: string) => {
-  const response = await openai.chat.completions.create({
-    model: "gpt-5.5",
-    messages: [{ role: "user", content: prompt }],
-  });
-  return response.choices[0].message.content;
-}, { name: "my-agent" });
+const runAgent = trace(async (prompt: string) => {
+  const plan = await callPlanner(prompt);   // captured automatically
+  const results = await callTools(plan);    // captured automatically
+  return summarize(results);                // captured automatically
+}, { name: "research-agent", resumable: true });
 
-await myAgent("What is quantum computing?");
+await runAgent("What changed in vector databases this year?");
 ```
 
+That's it. The run appears in the dashboard as an interactive timeline you can scrub, replay, and fork.
+
+---
+
+## How It Works
+
+The SDK is a thin capture layer. It wraps your function, auto-instruments provider calls, and streams spans to Retrace over a resilient transport — never blocking or crashing your agent.
+
+```mermaid
+flowchart LR
+    subgraph yourproc["Your process"]
+        fn["trace(fn)"] --> cap["auto-captured spans<br/>(LLM · tool · error)"]
+        cap --> buf["offline buffer<br/>(bounded, flush on reconnect)"]
+    end
+
+    buf == "WebSocket (primary)" ==> api["Retrace"]
+    buf -. "HTTP fallback" .-> api
+    api == "resume: re-execute from fork point" ==> fn
+
+    classDef p fill:#0f3d2e,stroke:#10b981,color:#d1fae5;
+    class api p;
+```
+
+- **Capture** — provider calls (OpenAI, Anthropic, Gemini) are intercepted automatically; you can also emit manual spans.
+- **Transport** — spans stream over a **WebSocket**; if it drops, the SDK falls back to **HTTP** and replays a bounded **offline buffer** on reconnect, so nothing is lost.
+- **Resumable** — with `resumable: true`, the SDK listens for a `resume` command and **re-executes your function from a fork point** with modified input, powering cascade replay from the dashboard.
+- **Safe by default** — failures in the SDK never throw into your agent; typed errors surface real problems explicitly.
+
+---
+
 ## Auto-Instrumentation
 
-LLM calls from all major providers are captured automatically:
+LLM calls from major providers are captured with no extra code — just install the provider SDK alongside `retrace-sdk`:
+
+| Provider | Captured call |
+|---|---|
+| **OpenAI** | `openai.chat.completions.create()` |
+| **Anthropic** | `anthropic.messages.create()` |
+| **Google Gemini** | `ai.models.generateContent()` |
+
+Framework adapters are available for agent frameworks (e.g. LangChain, Vercel AI SDK) — see the [docs](https://docs.retraceai.tech).
 
-- **OpenAI** — `openai.chat.completions.create()` captured
-- **Anthropic** — `anthropic.messages.create()` captured
-- **Google Gemini** — `ai.models.generateContent()` captured
+---
 
-No extra setup needed. Install the provider SDK alongside `retrace-sdk`.
+## Capabilities
 
-## Configuration
+| Capability | What it does |
+|---|---|
+| **Record** | One `trace()` wrapper captures the full execution tree. |
+| **Cascade replay** | `resumable: true` lets a dashboard fork re-execute the whole function from any step. |
+| **Enforcement** | Local budget/step/loop ceilings stop a runaway agent *before* the next call. |
+| **Multi-agent** | Tag spans with an agent id/role for topology + inter-agent detectors. |
+| **Golden cassettes** | Record a run as a CI regression fixture and gate on it offline. |
+| **Sampling** | Record a fraction of traffic in production. |
+| **Sessions** | Group multi-turn conversations under one session. |
+
+---
+
+## Usage Recipes
+
+### Configure
 
 ```typescript
 import { configure } from "retrace-sdk";
 
 configure({
-  apiKey: "rt_...",           // or RETRACE_API_KEY env var
+  apiKey: "rt_...",                  // or RETRACE_API_KEY
   baseUrl: "https://api.retraceai.tech",
-  projectId: "...",                 // or RETRACE_PROJECT_ID env var
+  projectId: "...",                  // or RETRACE_PROJECT_ID
 });
 ```
 
 Set `RETRACE_ENABLED=false` to disable recording without changing code.
 
-## Manual Span Creation
+### Manual spans
 
 ```typescript
 import { record, SpanType } from "retrace-sdk";
@@ -67,35 +127,19 @@ recorder.endSpan(span, { results: ["..."] });
 recorder.end("Done");
 ```
 
-## Resumable Execution (Cascade Replay)
-
-Mark a function as resumable to enable full cascade replay from the dashboard:
+### Resumable execution (cascade replay)
 
 ```typescript
-import { configure, trace } from "retrace-sdk";
-
-configure({ apiKey: "rt_..." });
-
-const myAgent = trace(async (prompt: string) => {
+const runAgent = 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, RetraceEnforcementError } from "retrace-sdk";
-```
-
-Typed errors for auth failures, credit exhaustion, and rate limiting.
-
-## Enforcement (Circuit Breakers)
+When you fork at any span in the dashboard, the SDK re-executes the **entire** function with the modified input — not just one call. Every downstream step that depends on the change diverges.
 
-Hard ceilings that stop a runaway agent before the next call. Local limits are enforced offline (zero network); `serverEnforcement: true` also consults centrally-managed server policies.
+### Enforcement (circuit breakers)
 
 ```typescript
 import { configure, RetraceEnforcementError } from "retrace-sdk";
@@ -104,7 +148,7 @@ configure({
   apiKey: "rt_...",
   maxStepsPerRun: 50,
   maxUsdPerRun: 2.0,
-  serverEnforcement: true, // optional: also consult server policies
+  serverEnforcement: true, // optional: also consult centrally-managed server policies
 });
 
 try {
@@ -114,11 +158,9 @@ try {
 }
 ```
 
-Precedence: explicit arg > env var (`RETRACE_MAX_STEPS_PER_RUN`, `RETRACE_MAX_TOKENS_PER_RUN`, `RETRACE_MAX_USD_PER_RUN`, `RETRACE_SERVER_ENFORCEMENT`) > unset. If the server check is unreachable, local limits still apply.
-
-## Multi-Agent Context
+Local ceilings are enforced offline (zero network). Precedence: explicit arg > env var (`RETRACE_MAX_STEPS_PER_RUN`, `RETRACE_MAX_TOKENS_PER_RUN`, `RETRACE_MAX_USD_PER_RUN`, `RETRACE_SERVER_ENFORCEMENT`) > unset. If the server check is unreachable, local limits still apply.
 
-Tag spans with an agent id/role so the dashboard can draw the agent topology and run inter-agent detectors:
+### Multi-agent context
 
 ```typescript
 import { withAgent } from "retrace-sdk";
@@ -128,9 +170,9 @@ await withAgent({ id: "planner", role: "planner" }, async () => {
 });
 ```
 
-## Golden Cassettes (CI Regression Gates)
+Tags spans so the dashboard can draw the agent topology and run inter-agent detectors (ping-pong, reasoning–action mismatch, task derailment).
 
-Record a run as a golden cassette and gate on it offline in CI with `retrace ci replay`:
+### Golden cassettes (CI regression gates)
 
 ```typescript
 import { writeGoldenCassette } from "retrace-sdk";
@@ -138,51 +180,36 @@ import { writeGoldenCassette } from "retrace-sdk";
 writeGoldenCassette("golden.json", { recorder });
 ```
 
-## Sampling
+Gate on it offline in CI with `retrace ci replay`.
+
+### Sampling
 
 ```typescript
-configure({ apiKey: "rt_...", sampleRate: 0.1 }); // Record 10% of traces
+configure({ apiKey: "rt_...", sampleRate: 0.1 }); // record 10% of traces
 ```
 
-## Changelog
-
-### 0.13.0
-
-- **Multi-agent context** — `withAgent({ id, role })` tags spans for topology + inter-agent detectors
-- **Golden cassettes** — `writeGoldenCassette(path, { recorder })` records a run as a CI regression fixture
-- **Pre-call enforcement gate** — local step/token/USD-per-run ceilings enforced offline; `RetraceEnforcementError` thrown instead of silently skipping the call
+### Error handling
 
+```typescript
+import {
+  RetraceError,
+  RetraceAuthError,
+  RetraceCreditsExhaustedError,
+  RetraceRateLimitError,
+  RetraceEnforcementError,
+} from "retrace-sdk";
+```
 
-- **Sessions** — `sessionId` option in `TraceRecorder` and `trace()` to group multi-turn conversations
-- **Multi-Agent** — `setAgentId()` on `SpanBuilder` for cross-agent tracing
-- **Guardrail support** — SDK respects HALT commands from server-side guardrail policies
-
-### 0.2.2
-
-- **Fixed** — OpenAI interceptor no longer creates dummy client instance to find prototype
-
-### 0.6.0
-
-- **Token ID capture** — Stores output token IDs + logprobs from OpenAI responses (enables speculative decoding during replay)
-- **SpanData extended** — New `token_ids` and `logprobs` fields on SpanData interface
-- **Shared schema** — SpanInputSchema updated with `token_ids` and `logprobs` optional arrays
-
-### 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 for auth failures, credit exhaustion, rate limiting, and enforcement blocks. Transient transport problems never crash your agent.
 
-- Typed errors (RetraceAuthError, RetraceCreditsExhaustedError, RetraceRateLimitError)
-- Trace sampling via `sampleRate` config
-- Auto-instrumentation for OpenAI, Anthropic, Gemini
-- WebSocket + HTTP fallback transport
+---
 
 ## Links
 
-- [Documentation](https://retraceai.tech/docs)
-- [GitHub](https://github.com/yash1511-bogam/retrace)
+- [Documentation](https://docs.retraceai.tech)
+- [GitHub](https://github.com/yash1511-bogam/retrace-sdk)
 - [npm](https://www.npmjs.com/package/retrace-sdk)
+
+## License
+
+MIT

package/dist/interceptors/openai.js

@@ -280,8 +280,13 @@ function createPatchedCreate() {
             // Wrap provider errors in typed Retrace exceptions for user-facing clarity
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
             const status = err?.status || err?.response?.status;
+            // openai v5+ makes APIError.headers a Web `Headers` instance (use .get()); pre-v5 it was a
+            // plain record (bracket access). Support both so retry-after is honored across the peer range.
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const eh = err?.headers;
+            const retryAfter = (eh && typeof eh.get === "function" ? eh.get("retry-after") : eh?.["retry-after"]) || "60";
             if (status === 429)
-                throw new RetraceRateLimitError(parseInt(err?.headers?.["retry-after"] || "60", 10));
+                throw new RetraceRateLimitError(parseInt(retryAfter, 10));
             if (status === 401 || status === 403)
                 throw new RetraceAuthError(`OpenAI auth failed: ${err.message}`);
             if (err?.message?.includes("ECONNREFUSED") || err?.message?.includes("fetch failed")) {

package/dist/telemetry.js

@@ -14,7 +14,7 @@ import { getConfig } from "./config.js";
 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.0";
+const SDK_VERSION = "0.16.1";
 function enabled() {
     return !DISABLED.has((process.env.RETRACE_TELEMETRY ?? "1").trim().toLowerCase());
 }

package/dist/transport.js

@@ -2,7 +2,7 @@ import { getConfig } from "./config.js";
 import { classifyServerSignal } from "./errors.js";
 // Client identifier sent on every request so the backend can attribute SDK usage/version.
 // Keep in sync with package.json on release.
-const CLIENT_ID = "typescript-sdk/0.16.0";
+const CLIENT_ID = "typescript-sdk/0.16.1";
 // ─── Runtime-agnostic WebSocket ──────────────────────────────────────────────
 // Prefer the global Web `WebSocket` (Node 20+, Bun, Deno, browsers, and every edge runtime); fall
 // back to the OPTIONAL `ws` package only on older Node that lacks a global. Both expose the standard

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "retrace-sdk",
-  "version": "0.16.0",
+  "version": "0.16.1",
   "description": "The execution replay engine for AI agents. Record, replay, fork, and share agent executions.",
   "type": "module",
   "main": "dist/index.js",
@@ -57,10 +57,10 @@
     "ws": "^8.20.1"
   },
   "peerDependencies": {
-    "@google/genai": ">=1.52.0",
-    "openai": ">=4.0.0",
     "@anthropic-ai/sdk": ">=0.30.0",
-    "@langchain/core": ">=0.3.0"
+    "@google/genai": ">=1.52.0",
+    "@langchain/core": ">=0.3.0",
+    "openai": ">=4.0.0"
   },
   "peerDependenciesMeta": {
     "@google/genai": {
@@ -77,11 +77,11 @@
     }
   },
   "devDependencies": {
-    "@google/genai": "^1.52.0",
-    "@types/node": "22.15.3",
+    "@anthropic-ai/sdk": "^0.105.0",
+    "@google/genai": "^2.9.0",
+    "@types/node": "24.13.2",
     "@types/ws": "8.18.1",
-    "typescript": "6.0.3",
-    "openai": "^4.90.0",
-    "@anthropic-ai/sdk": "^0.95.0"
+    "openai": "^6.44.0",
+    "typescript": "6.0.3"
   }
 }