retrace-sdk 0.4.0 → 0.5.0

package/dist/config.d.ts

@@ -5,6 +5,8 @@ export interface Config {
     projectId: string | undefined;
     enabled: boolean;
     sampleRate: number;
+    /** Optional seed for deterministic sampling. When set, the same trace name always produces the same sample decision. */
+    sampleSeed: string | undefined;
 }
 export declare function configure(opts: Partial<Config>): Config;
 export declare function requireApiKey(): string;

package/dist/config.js

@@ -5,6 +5,7 @@ const config = {
     projectId: process.env.RETRACE_PROJECT_ID || undefined,
     enabled: !["false", "0"].includes((process.env.RETRACE_ENABLED || "true").toLowerCase()),
     sampleRate: parseFloat(process.env.RETRACE_SAMPLE_RATE || "1"),
+    sampleSeed: process.env.RETRACE_SAMPLE_SEED || undefined,
 };
 config.wsUrl = config.baseUrl.replace("https://", "wss://").replace("http://", "ws://");
 export function configure(opts) {

package/dist/index.d.ts

@@ -11,3 +11,4 @@ export { registerResumable, handleResume } from "./resume.js";
 export type { ResumeCommand } from "./resume.js";
 export { isReplaying, consumeCassetteEntry, handleReplay } from "./replay.js";
 export type { CassetteEntry, ReplayCommand } from "./replay.js";
+export { setTraceContext, clearTraceContext, getTraceparent, injectTraceparent, parseTraceparent } from "./traceparent.js";

package/dist/index.js

@@ -8,3 +8,4 @@ export { installAnthropicInterceptor, uninstallAnthropicInterceptor } from "./in
 export { RetraceError, RetraceAuthError, RetraceCreditsExhaustedError, RetraceConnectionError, RetraceRateLimitError } from "./errors.js";
 export { registerResumable, handleResume } from "./resume.js";
 export { isReplaying, consumeCassetteEntry, handleReplay } from "./replay.js";
+export { setTraceContext, clearTraceContext, getTraceparent, injectTraceparent, parseTraceparent } from "./traceparent.js";

package/dist/interceptors/openai.js

@@ -1,7 +1,10 @@
 import { SpanType } from "../trace.js";
 import { genId, nowIso, truncateJson } from "../utils.js";
 import { isReplaying, consumeCassetteEntry } from "../replay.js";
-const PRICING = {
+import { getConfig } from "../config.js";
+import { RetraceRateLimitError, RetraceAuthError, RetraceConnectionError } from "../errors.js";
+/** Hardcoded fallback pricing ($/1M tokens: [input, output]). Updated periodically. */
+const FALLBACK_PRICING = {
     "gpt-5.5-pro": [30.0, 180.0],
     "gpt-5.5": [5.0, 30.0],
     "gpt-5.4-pro": [15.0, 90.0],
@@ -20,8 +23,35 @@ const PRICING = {
     "o4-mini": [1.10, 4.40],
     "o3-mini": [1.10, 4.40],
 };
+let livePricing = null;
+let pricingFetchedAt = 0;
+const PRICING_TTL_MS = 3600_000; // Refresh every hour
+/** Fetch live pricing from Retrace API. Falls back to hardcoded on failure. */
+async function fetchPricing() {
+    if (livePricing && Date.now() - pricingFetchedAt < PRICING_TTL_MS)
+        return livePricing;
+    try {
+        const cfg = getConfig();
+        const res = await fetch(`${cfg.baseUrl}/api/v1/pricing/models`, {
+            signal: AbortSignal.timeout(3000),
+        });
+        if (res.ok) {
+            const data = await res.json();
+            if (data && typeof data === "object") {
+                livePricing = data;
+                pricingFetchedAt = Date.now();
+                return livePricing;
+            }
+        }
+    }
+    catch { /* silent — use fallback */ }
+    return FALLBACK_PRICING;
+}
+// Kick off initial fetch (non-blocking)
+fetchPricing().catch(() => { });
 function calcCost(model, inputTokens, outputTokens) {
-    for (const [key, p] of Object.entries(PRICING)) {
+    const pricing = livePricing || FALLBACK_PRICING;
+    for (const [key, p] of Object.entries(pricing)) {
         if (model.includes(key))
             return (inputTokens * p[0] + outputTokens * p[1]) / 1_000_000;
     }
@@ -64,9 +94,18 @@ function createPatchedCreate() {
         const opts = args[0] || {};
         const model = opts.model || "unknown";
         const messages = opts.messages || [];
+        const isStreaming = !!opts.stream;
         const spanId = genId();
         const startedAt = nowIso();
         const startMs = Date.now();
+        // Capture vision (image_url) and structured output (response_format) metadata
+        const hasVision = messages.some((m) => Array.isArray(m.content) && m.content.some((p) => p.type === "image_url"));
+        const responseFormat = opts.response_format;
+        const spanMetadata = {};
+        if (hasVision)
+            spanMetadata.vision = true;
+        if (responseFormat)
+            spanMetadata.structured_output = typeof responseFormat === "object" ? responseFormat.type || "json_schema" : responseFormat;
         // During replay, return mocked response from cassette instead of calling the real API
         if (isReplaying()) {
             const entry = consumeCassetteEntry("openai.chat.completions.create", "llm_call");
@@ -92,6 +131,57 @@ function createPatchedCreate() {
         }
         try {
             const result = await originalCreate.apply(this, args);
+            // Streaming response: wrap the async iterator to collect chunks
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            if (isStreaming && result && typeof result[Symbol.asyncIterator] === "function") {
+                const chunks = [];
+                let inputTokens = 0;
+                let outputTokens = 0;
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                const originalIterator = result[Symbol.asyncIterator]();
+                const wrappedStream = {
+                    [Symbol.asyncIterator]() {
+                        return {
+                            async next() {
+                                const { value, done } = await originalIterator.next();
+                                if (done) {
+                                    // Stream complete — emit span
+                                    const durationMs = Date.now() - startMs;
+                                    const output = chunks.join("");
+                                    const span = {
+                                        id: spanId, trace_id: "", parent_id: null,
+                                        span_type: SpanType.LLM_CALL, name: "openai.chat.completions.create", model,
+                                        input: truncateJson({ messages: messages.slice(0, 10) }),
+                                        output: truncateJson(output),
+                                        input_tokens: inputTokens, output_tokens: outputTokens,
+                                        cost: calcCost(model, inputTokens, outputTokens),
+                                        duration_ms: durationMs, started_at: startedAt, ended_at: nowIso(),
+                                        metadata: { streaming: true },
+                                    };
+                                    onSpanCallback?.(span);
+                                    return { value: undefined, done: true };
+                                }
+                                // Collect content delta
+                                const delta = value?.choices?.[0]?.delta?.content;
+                                if (delta)
+                                    chunks.push(delta);
+                                // Collect usage from final chunk
+                                if (value?.usage) {
+                                    inputTokens = value.usage.prompt_tokens || 0;
+                                    outputTokens = value.usage.completion_tokens || 0;
+                                }
+                                return { value, done: false };
+                            },
+                            return() { return originalIterator.return?.() ?? Promise.resolve({ value: undefined, done: true }); },
+                            throw(e) { return originalIterator.throw?.(e) ?? Promise.reject(e); },
+                        };
+                    },
+                    // Preserve tee/controller methods if present
+                    ...(result.controller ? { controller: result.controller } : {}),
+                };
+                return wrappedStream;
+            }
+            // Non-streaming response
             const durationMs = Date.now() - startMs;
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
             const res = result;
@@ -101,11 +191,12 @@ function createPatchedCreate() {
             const span = {
                 id: spanId, trace_id: "", parent_id: null,
                 span_type: SpanType.LLM_CALL, name: "openai.chat.completions.create", model,
-                input: truncateJson({ messages: messages.slice(0, 10) }),
+                input: truncateJson({ messages: messages.slice(0, 10), ...(responseFormat ? { response_format: responseFormat } : {}) }),
                 output: truncateJson(output),
                 input_tokens: inputTokens, output_tokens: outputTokens,
                 cost: calcCost(model, inputTokens, outputTokens),
                 duration_ms: durationMs, started_at: startedAt, ended_at: nowIso(),
+                ...(Object.keys(spanMetadata).length ? { metadata: spanMetadata } : {}),
             };
             onSpanCallback?.(span);
             return result;
@@ -120,6 +211,16 @@ function createPatchedCreate() {
                 error: err instanceof Error ? err.message : String(err),
             };
             onSpanCallback?.(span);
+            // 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;
+            if (status === 429)
+                throw new RetraceRateLimitError(parseInt(err?.headers?.["retry-after"] || "60", 10));
+            if (status === 401 || status === 403)
+                throw new RetraceAuthError(`OpenAI auth failed: ${err.message}`);
+            if (err?.message?.includes("ECONNREFUSED") || err?.message?.includes("fetch failed")) {
+                throw new RetraceConnectionError(`OpenAI connection failed: ${err.message}`);
+            }
             throw err;
         }
     };

package/dist/recorder.js

@@ -1,6 +1,7 @@
 import { getConfig, requireApiKey } from "./config.js";
 import { SpanBuilder, SpanType, TraceBuilder, TraceStatus } from "./trace.js";
 import { createTransport } from "./transport.js";
+import { shouldSample } from "./utils.js";
 import { installGeminiInterceptor } from "./interceptors/gemini.js";
 import { installOpenAIInterceptor } from "./interceptors/openai.js";
 import { installAnthropicInterceptor } from "./interceptors/anthropic.js";
@@ -108,7 +109,7 @@ export class TraceRecorder {
 }
 export function record(opts) {
     const cfg = getConfig();
-    if (!cfg.enabled || Math.random() > cfg.sampleRate) {
+    if (!cfg.enabled || !shouldSample(cfg.sampleRate, cfg.sampleSeed, opts?.name)) {
         // Return a typed no-op stub (preserves type safety unlike Proxy)
         return {
             get traceId() { return ""; },
@@ -131,7 +132,7 @@ export function trace(fn, opts) {
         });
     }
     return (...args) => {
-        if (!cfg.enabled || Math.random() > cfg.sampleRate)
+        if (!cfg.enabled || !shouldSample(cfg.sampleRate, cfg.sampleSeed, opts?.name || fn.name))
             return fn(...args);
         const recorder = new TraceRecorder({
             name: opts?.name || fn.name || "anonymous",

package/dist/replay.d.ts

@@ -25,18 +25,21 @@ export interface ReplayCommand {
     cassette: CassetteEntry[];
 }
 /**
- * Check if a replay is currently active.
+ * Check if a replay is currently active in this async context.
  */
 export declare function isReplaying(): boolean;
 /**
  * Get the next cassette entry matching a span name and type.
  * Uses sequential matching with name-based fallback for deterministic replay.
+ * Thread-safe: each async context has its own pointer.
  */
 export declare function consumeCassetteEntry(name: string, spanType: string): CassetteEntry | null;
 /**
  * Handle a replay command from the server.
+ * Returns a Promise that resolves when replay completes or rejects on failure.
+ * Uses AsyncLocalStorage for per-context cassette isolation.
  */
-export declare function handleReplay(command: ReplayCommand): boolean;
+export declare function handleReplay(command: ReplayCommand): Promise<boolean>;
 export declare function parseReplayMessage(msg: {
     type: string;
     data?: unknown;

package/dist/replay.js

@@ -10,50 +10,50 @@
  * This enables one-click reproduction of any production trace locally.
  */
 import { getResumable } from "./resume.js";
-// Global cassette state for the current replay session
-let activeCassette = null;
-let cassettePointer = 0;
+import { AsyncLocalStorage } from "async_hooks";
+const cassetteStorage = new AsyncLocalStorage();
 /**
- * Check if a replay is currently active.
+ * Check if a replay is currently active in this async context.
  */
 export function isReplaying() {
-    return activeCassette !== null;
+    return cassetteStorage.getStore() !== undefined;
 }
 /**
  * Get the next cassette entry matching a span name and type.
  * Uses sequential matching with name-based fallback for deterministic replay.
+ * Thread-safe: each async context has its own pointer.
  */
 export function consumeCassetteEntry(name, spanType) {
-    if (!activeCassette)
+    const ctx = cassetteStorage.getStore();
+    if (!ctx)
         return null;
     // Primary: sequential pointer (deterministic order)
-    if (cassettePointer < activeCassette.length) {
-        const entry = activeCassette[cassettePointer];
+    if (ctx.pointer < ctx.cassette.length) {
+        const entry = ctx.cassette[ctx.pointer];
         if (entry.name === name && entry.span_type === spanType) {
-            cassettePointer++;
+            ctx.pointer++;
             return entry;
         }
     }
     // Fallback: search by name + type from current pointer forward
-    for (let i = cassettePointer; i < activeCassette.length; i++) {
-        if (activeCassette[i].name === name && activeCassette[i].span_type === spanType) {
-            cassettePointer = i + 1;
-            return activeCassette[i];
+    for (let i = ctx.pointer; i < ctx.cassette.length; i++) {
+        if (ctx.cassette[i].name === name && ctx.cassette[i].span_type === spanType) {
+            ctx.pointer = i + 1;
+            return ctx.cassette[i];
         }
     }
     return null;
 }
 /**
  * Handle a replay command from the server.
+ * Returns a Promise that resolves when replay completes or rejects on failure.
+ * Uses AsyncLocalStorage for per-context cassette isolation.
  */
-export function handleReplay(command) {
+export async function handleReplay(command) {
     const fn = getResumable(command.traceName);
     if (!fn)
         return false;
-    // Set up cassette
-    activeCassette = command.cassette;
-    cassettePointer = 0;
-    (async () => {
+    return cassetteStorage.run({ cassette: command.cassette, pointer: 0 }, async () => {
         try {
             const { TraceRecorder } = await import("./recorder.js");
             const { TraceStatus } = await import("./trace.js");
@@ -72,17 +72,13 @@ export function handleReplay(command) {
                 : Array.isArray(command.input) ? command.input : [command.input];
             const result = await Promise.resolve(fn(...args));
             recorder.end(result, TraceStatus.COMPLETED);
+            return true;
         }
         catch (err) {
             console.error("[retrace] Deterministic replay failed:", err);
+            return false;
         }
-        finally {
-            // Clean up cassette state
-            activeCassette = null;
-            cassettePointer = 0;
-        }
-    })();
-    return true;
+    });
 }
 export function parseReplayMessage(msg) {
     if (msg.type !== "replay" || !msg.data)

package/dist/traceparent.d.ts

@@ -0,0 +1,28 @@
+/**
+ * W3C Trace Context (traceparent) propagation.
+ * Format: 00-{trace_id_32hex}-{parent_id_16hex}-{flags_2hex}
+ *
+ * This enables distributed tracing across service boundaries.
+ * When a traced function makes HTTP calls, the traceparent header
+ * is injected so downstream services can correlate their spans.
+ */
+/** Set the active trace context for outgoing requests. */
+export declare function setTraceContext(traceId: string, spanId: string): void;
+/** Clear the active trace context. */
+export declare function clearTraceContext(): void;
+/** Get the current traceparent header value, or null if no active trace. */
+export declare function getTraceparent(): string | null;
+/**
+ * Inject traceparent into a headers object (for fetch/axios/http calls).
+ * Returns the headers with traceparent added if a trace is active.
+ */
+export declare function injectTraceparent(headers?: Record<string, string>): Record<string, string>;
+/**
+ * Parse an incoming traceparent header.
+ * Returns { traceId, parentId, sampled } or null if invalid.
+ */
+export declare function parseTraceparent(header: string): {
+    traceId: string;
+    parentId: string;
+    sampled: boolean;
+} | null;

package/dist/traceparent.js

@@ -0,0 +1,56 @@
+/**
+ * W3C Trace Context (traceparent) propagation.
+ * Format: 00-{trace_id_32hex}-{parent_id_16hex}-{flags_2hex}
+ *
+ * This enables distributed tracing across service boundaries.
+ * When a traced function makes HTTP calls, the traceparent header
+ * is injected so downstream services can correlate their spans.
+ */
+let _currentTraceId = null;
+let _currentSpanId = null;
+/** Set the active trace context for outgoing requests. */
+export function setTraceContext(traceId, spanId) {
+    // Convert UUID format to 32-hex (remove dashes)
+    _currentTraceId = traceId.replace(/-/g, "");
+    // Take first 16 chars of span ID as parent span
+    _currentSpanId = spanId.replace(/-/g, "").slice(0, 16);
+}
+/** Clear the active trace context. */
+export function clearTraceContext() {
+    _currentTraceId = null;
+    _currentSpanId = null;
+}
+/** Get the current traceparent header value, or null if no active trace. */
+export function getTraceparent() {
+    if (!_currentTraceId || !_currentSpanId)
+        return null;
+    // version-trace_id-parent_id-flags (01 = sampled)
+    return `00-${_currentTraceId}-${_currentSpanId}-01`;
+}
+/**
+ * Inject traceparent into a headers object (for fetch/axios/http calls).
+ * Returns the headers with traceparent added if a trace is active.
+ */
+export function injectTraceparent(headers = {}) {
+    const tp = getTraceparent();
+    if (tp) {
+        headers["traceparent"] = tp;
+    }
+    return headers;
+}
+/**
+ * Parse an incoming traceparent header.
+ * Returns { traceId, parentId, sampled } or null if invalid.
+ */
+export function parseTraceparent(header) {
+    const parts = header.split("-");
+    if (parts.length !== 4 || parts[0] !== "00")
+        return null;
+    if (parts[1].length !== 32 || parts[2].length !== 16)
+        return null;
+    return {
+        traceId: parts[1],
+        parentId: parts[2],
+        sampled: parts[3] === "01",
+    };
+}

package/dist/utils.d.ts

@@ -1,4 +1,16 @@
 export declare function genId(): string;
 export declare function nowIso(): string;
 export declare function utcNow(): Date;
+/**
+ * Deterministic sampling decision using FNV-1a hash.
+ * When a seed is provided, the same (seed + key) always produces the same decision.
+ * Without a seed, falls back to Math.random() for backward compatibility.
+ */
+export declare function shouldSample(rate: number, seed?: string, key?: string): boolean;
 export declare function truncateJson(obj: unknown, maxBytes?: number): unknown;
+/** Configure per-span-type truncation limits. */
+export declare function setTruncationLimits(limits: Record<string, number>): void;
+/** Get the truncation limit for a given span type. */
+export declare function getTruncationLimit(spanType: string): number;
+/** Truncate payload based on span type. */
+export declare function truncateForSpanType(obj: unknown, spanType: string): unknown;

package/dist/utils.js

@@ -8,6 +8,27 @@ export function nowIso() {
 export function utcNow() {
     return new Date();
 }
+/**
+ * Deterministic sampling decision using FNV-1a hash.
+ * When a seed is provided, the same (seed + key) always produces the same decision.
+ * Without a seed, falls back to Math.random() for backward compatibility.
+ */
+export function shouldSample(rate, seed, key) {
+    if (rate >= 1)
+        return true;
+    if (rate <= 0)
+        return false;
+    if (!seed)
+        return Math.random() < rate;
+    // FNV-1a hash of seed+key → deterministic float in [0,1)
+    const input = `${seed}:${key || Date.now()}`;
+    let hash = 2166136261;
+    for (let i = 0; i < input.length; i++) {
+        hash ^= input.charCodeAt(i);
+        hash = Math.imul(hash, 16777619);
+    }
+    return ((hash >>> 0) / 4294967296) < rate;
+}
 export function truncateJson(obj, maxBytes = 10240) {
     try {
         const s = JSON.stringify(obj);
@@ -19,3 +40,25 @@ export function truncateJson(obj, maxBytes = 10240) {
         return String(obj).slice(0, maxBytes);
     }
 }
+/** Default per-span-type truncation limits (bytes). */
+const DEFAULT_TRUNCATION_LIMITS = {
+    llm_call: 51200, // 50KB — LLM prompts can be large
+    tool_call: 10240, // 10KB
+    tool_result: 10240, // 10KB
+    reasoning: 20480, // 20KB
+    action: 5120, // 5KB
+    error: 5120, // 5KB
+};
+let customTruncationLimits = {};
+/** Configure per-span-type truncation limits. */
+export function setTruncationLimits(limits) {
+    customTruncationLimits = limits;
+}
+/** Get the truncation limit for a given span type. */
+export function getTruncationLimit(spanType) {
+    return customTruncationLimits[spanType] || DEFAULT_TRUNCATION_LIMITS[spanType] || 10240;
+}
+/** Truncate payload based on span type. */
+export function truncateForSpanType(obj, spanType) {
+    return truncateJson(obj, getTruncationLimit(spanType));
+}

package/package.json

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