retrace-sdk 0.1.3

package/README.md

@@ -0,0 +1,94 @@
+# retrace
+
+Record, replay, fork & share AI agent executions — TypeScript SDK.
+
+## Installation
+
+```bash
+npm install retrace
+```
+
+## Quick Start
+
+```typescript
+import { configure, record, trace, TraceStatus } from "retrace";
+
+configure({ apiKey: "rt_live_...", projectId: "your-project-id" });
+
+// Wrap a function with trace()
+const myAgent = trace((prompt: string) => {
+  // OpenAI calls are auto-captured
+  const response = await openai.chat.completions.create({
+    model: "gpt-4o",
+    messages: [{ role: "user", content: prompt }],
+  });
+  return response.choices[0].message.content;
+}, { name: "my-agent" });
+
+const result = myAgent("What is the meaning of life?");
+```
+
+## Configuration
+
+```typescript
+import { configure } from "retrace";
+
+configure({
+  apiKey: "rt_live_...",           // or RETRACE_API_KEY env var
+  baseUrl: "http://localhost:3001", // or RETRACE_BASE_URL env var
+  projectId: "...",                 // or RETRACE_PROJECT_ID env var
+});
+```
+
+Set `RETRACE_ENABLED=false` to disable recording without changing code.
+
+## OpenAI Auto-Capture
+
+```typescript
+import { record, TraceStatus } from "retrace";
+import OpenAI from "openai";
+
+const openai = new OpenAI();
+const recorder = record({ name: "chat-agent" });
+recorder.start();
+
+const response = await openai.chat.completions.create({
+  model: "gpt-4o",
+  messages: [{ role: "user", content: "Hello!" }],
+});
+// LLM call is automatically captured as a span
+
+recorder.end(response.choices[0].message.content);
+```
+
+## Manual Span Creation
+
+```typescript
+import { record, SpanType } from "retrace";
+
+const recorder = record({ name: "custom-agent" });
+recorder.start();
+
+const span = recorder.startSpan("web-search", SpanType.TOOL_CALL, { query: "latest news" });
+// ... do work ...
+recorder.endSpan(span, { results: ["..."] });
+
+recorder.end("Done");
+```
+
+## Transport Options
+
+The SDK uses WebSocket by default for real-time streaming. Falls back to HTTP if WS connection fails.
+
+```typescript
+import { createTransport } from "retrace/transport";
+
+// Force HTTP transport
+const transport = createTransport("http");
+
+// Force WebSocket
+const transport = createTransport("ws");
+
+// Auto-detect (default)
+const transport = createTransport("auto");
+```

package/dist/config.d.ts

@@ -0,0 +1,9 @@
+export interface Config {
+    apiKey: string;
+    baseUrl: string;
+    wsUrl: string;
+    projectId: string | undefined;
+    enabled: boolean;
+}
+export declare function configure(opts: Partial<Config>): Config;
+export declare function getConfig(): Config;

package/dist/config.js

@@ -0,0 +1,21 @@
+const config = {
+    apiKey: process.env.RETRACE_API_KEY || "",
+    baseUrl: process.env.RETRACE_BASE_URL || "http://localhost:3001",
+    wsUrl: "",
+    projectId: process.env.RETRACE_PROJECT_ID || undefined,
+    enabled: !["false", "0"].includes((process.env.RETRACE_ENABLED || "true").toLowerCase()),
+};
+config.wsUrl = config.baseUrl.replace("https://", "wss://").replace("http://", "ws://");
+export function configure(opts) {
+    if (opts.apiKey && !opts.apiKey.startsWith("rt_live_")) {
+        console.warn("[retrace] API key does not start with 'rt_live_'. This may be invalid.");
+    }
+    Object.assign(config, opts);
+    if (opts.baseUrl && !opts.wsUrl) {
+        config.wsUrl = config.baseUrl.replace("https://", "wss://").replace("http://", "ws://");
+    }
+    return config;
+}
+export function getConfig() {
+    return config;
+}

package/dist/config.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/config.test.js

@@ -0,0 +1,15 @@
+import { describe, it, expect } from "vitest";
+import { configure, getConfig } from "./config.js";
+describe("SDK config", () => {
+    it("has defaults", () => {
+        const c = getConfig();
+        expect(c.baseUrl).toBe("http://localhost:3001");
+        expect(c.enabled).toBe(true);
+    });
+    it("configures custom values", () => {
+        configure({ apiKey: "rt_live_test", baseUrl: "http://custom:3001" });
+        const c = getConfig();
+        expect(c.apiKey).toBe("rt_live_test");
+        expect(c.baseUrl).toBe("http://custom:3001");
+    });
+});

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { configure, getConfig } from "./config.js";
+export { record, trace, TraceRecorder } from "./recorder.js";
+export { SpanBuilder, TraceBuilder } from "./trace.js";
+export type { SpanData, TraceData } from "./trace.js";
+export { SpanType, TraceStatus } from "./trace.js";
+export { installGeminiInterceptor, uninstallGeminiInterceptor } from "./interceptors/gemini.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+export { configure, getConfig } from "./config.js";
+export { record, trace, TraceRecorder } from "./recorder.js";
+export { SpanBuilder, TraceBuilder } from "./trace.js";
+export { SpanType, TraceStatus } from "./trace.js";
+export { installGeminiInterceptor, uninstallGeminiInterceptor } from "./interceptors/gemini.js";

package/dist/interceptors/gemini.d.ts

@@ -0,0 +1,3 @@
+import { SpanData } from "../trace.js";
+export declare function installGeminiInterceptor(onSpan: (span: SpanData) => void): void;
+export declare function uninstallGeminiInterceptor(): void;

package/dist/interceptors/gemini.js

@@ -0,0 +1,82 @@
+import { SpanType } from "../trace.js";
+import { genId, nowIso, truncateJson } from "../utils.js";
+const PRICING = {
+    "gemini-3.1-pro-preview": [2.0, 12.0],
+    "gemini-2.5-pro": [1.25, 10.0],
+    "gemini-2.5-flash": [0.15, 0.60],
+    "gemini-2.0-flash": [0.10, 0.40],
+};
+function calcCost(model, inputTokens, outputTokens) {
+    const p = PRICING[model] || [0, 0];
+    return (inputTokens * p[0] + outputTokens * p[1]) / 1_000_000;
+}
+let originalGenerateContent = null;
+let installed = false;
+let onSpanCallback = null;
+export function installGeminiInterceptor(onSpan) {
+    if (installed) {
+        onSpanCallback = onSpan;
+        return;
+    }
+    onSpanCallback = onSpan;
+    import("@google/genai").then((genaiMod) => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const mod = genaiMod;
+        const modelsProto = mod?.Models?.prototype || mod?.default?.Models?.prototype;
+        if (!modelsProto?.generateContent)
+            return;
+        originalGenerateContent = modelsProto.generateContent;
+        modelsProto.generateContent = async function (...args) {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const opts = args[0] || {};
+            const model = opts.model || "unknown";
+            const contents = opts.contents;
+            const spanId = genId();
+            const startedAt = nowIso();
+            const startMs = Date.now();
+            try {
+                const result = await originalGenerateContent.apply(this, args);
+                const durationMs = Date.now() - startMs;
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                const res = result;
+                const inputTokens = res?.usageMetadata?.promptTokenCount || 0;
+                const outputTokens = res?.usageMetadata?.candidatesTokenCount || 0;
+                const span = {
+                    id: spanId, trace_id: "", parent_id: null,
+                    span_type: SpanType.LLM_CALL, name: "retrace.ai.generate", model,
+                    input: truncateJson(contents), output: truncateJson(res?.text || ""),
+                    input_tokens: inputTokens, output_tokens: outputTokens,
+                    cost: calcCost(model, inputTokens, outputTokens),
+                    duration_ms: durationMs, started_at: startedAt, ended_at: nowIso(),
+                };
+                onSpanCallback?.(span);
+                return result;
+            }
+            catch (err) {
+                const span = {
+                    id: spanId, trace_id: "", parent_id: null,
+                    span_type: SpanType.LLM_CALL, name: "retrace.ai.generate", model,
+                    input: truncateJson(contents), started_at: startedAt, ended_at: nowIso(),
+                    duration_ms: Date.now() - startMs,
+                    error: err instanceof Error ? err.message : String(err),
+                };
+                onSpanCallback?.(span);
+                throw err;
+            }
+        };
+        installed = true;
+    }).catch(() => { });
+}
+export function uninstallGeminiInterceptor() {
+    if (!installed || !originalGenerateContent)
+        return;
+    import("@google/genai").then((genaiMod) => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const mod = genaiMod;
+        const modelsProto = mod?.Models?.prototype || mod?.default?.Models?.prototype;
+        if (modelsProto)
+            modelsProto.generateContent = originalGenerateContent;
+    }).catch(() => { });
+    installed = false;
+    onSpanCallback = null;
+}

package/dist/interceptors/index.d.ts

@@ -0,0 +1 @@
+export { installGeminiInterceptor, uninstallGeminiInterceptor } from "./gemini.js";

package/dist/interceptors/index.js

@@ -0,0 +1 @@
+export { installGeminiInterceptor, uninstallGeminiInterceptor } from "./gemini.js";

package/dist/recorder.d.ts

@@ -0,0 +1,22 @@
+import { SpanBuilder, SpanData, SpanType, TraceStatus } from "./trace.js";
+export interface RecordOptions {
+    name?: string;
+    input?: unknown;
+    metadata?: Record<string, unknown>;
+}
+export declare class TraceRecorder {
+    private builder;
+    private transport;
+    private interceptorsInstalled;
+    output: unknown;
+    constructor(opts?: RecordOptions);
+    get traceId(): string;
+    start(name?: string, input?: unknown): this;
+    end(output?: unknown, status?: TraceStatus): void;
+    addSpan(span: SpanData): void;
+    startSpan(name: string, spanType?: SpanType, input?: unknown, model?: string, parentId?: string): SpanBuilder;
+    endSpan(spanBuilder: SpanBuilder, output?: unknown, error?: string): void;
+    private installInterceptors;
+}
+export declare function record(opts?: RecordOptions): TraceRecorder;
+export declare function trace<T>(fn: (...args: unknown[]) => T, opts?: RecordOptions): (...args: unknown[]) => T;

package/dist/recorder.js

@@ -0,0 +1,123 @@
+import { getConfig } from "./config.js";
+import { SpanBuilder, SpanType, TraceBuilder, TraceStatus } from "./trace.js";
+import { createTransport } from "./transport.js";
+import { installGeminiInterceptor } from "./interceptors/gemini.js";
+export class TraceRecorder {
+    builder;
+    transport;
+    interceptorsInstalled = false;
+    output = undefined;
+    constructor(opts) {
+        this.builder = new TraceBuilder();
+        this.transport = createTransport();
+        const cfg = getConfig();
+        if (cfg.projectId)
+            this.builder.setProjectId(cfg.projectId);
+        if (opts?.metadata)
+            this.builder.setMetadata(opts.metadata);
+        if (opts?.name || opts?.input) {
+            this.builder.start(opts.name, opts.input);
+        }
+    }
+    get traceId() { return this.builder.id; }
+    start(name, input) {
+        this.builder.start(name, input);
+        this.installInterceptors();
+        this.transport.send("trace_started", this.builder.toDict());
+        return this;
+    }
+    end(output, status = TraceStatus.COMPLETED) {
+        if (output !== undefined)
+            this.output = output;
+        const data = this.builder.end(this.output, status);
+        this.transport.send("trace_ended", {
+            id: data.id,
+            ended_at: data.ended_at,
+            output: data.output,
+            status: data.status,
+            total_tokens: data.total_tokens,
+            total_cost: data.total_cost,
+        });
+        this.transport.close();
+    }
+    addSpan(span) {
+        span.trace_id = this.builder.id;
+        this.builder.addSpan(span);
+        this.transport.send("span_started", span);
+        if (span.ended_at) {
+            this.transport.send("span_ended", {
+                id: span.id,
+                ended_at: span.ended_at,
+                output: span.output,
+                output_tokens: span.output_tokens,
+                cost: span.cost,
+                error: span.error,
+            });
+        }
+    }
+    startSpan(name, spanType = SpanType.LLM_CALL, input, model, parentId) {
+        const sb = new SpanBuilder(name, spanType).start();
+        sb.setTraceId(this.builder.id);
+        if (input !== undefined)
+            sb.setInput(input);
+        if (model)
+            sb.setModel(model);
+        if (parentId)
+            sb.setParentId(parentId);
+        this.transport.send("span_started", sb.toData());
+        return sb;
+    }
+    endSpan(spanBuilder, output, error) {
+        const span = spanBuilder.end(output, error);
+        span.trace_id = this.builder.id;
+        this.builder.addSpan(span);
+        this.transport.send("span_ended", {
+            id: span.id,
+            ended_at: span.ended_at,
+            output: span.output,
+            output_tokens: span.output_tokens,
+            cost: span.cost,
+            error: span.error,
+        });
+    }
+    installInterceptors() {
+        if (this.interceptorsInstalled)
+            return;
+        installGeminiInterceptor((span) => this.addSpan(span));
+        this.interceptorsInstalled = true;
+    }
+}
+export function record(opts) {
+    const cfg = getConfig();
+    if (!cfg.enabled) {
+        // Return a no-op recorder
+        return new TraceRecorder(opts);
+    }
+    return new TraceRecorder(opts);
+}
+export function trace(fn, opts) {
+    const cfg = getConfig();
+    return (...args) => {
+        if (!cfg.enabled)
+            return fn(...args);
+        const recorder = new TraceRecorder({
+            name: opts?.name || fn.name || "anonymous",
+            input: opts?.input ?? args,
+            metadata: opts?.metadata,
+        });
+        recorder.start(opts?.name || fn.name || "anonymous", opts?.input ?? args);
+        try {
+            const result = fn(...args);
+            // Handle async functions
+            if (result && typeof result.then === "function") {
+                return result.then((resolved) => { recorder.end(resolved, TraceStatus.COMPLETED); return resolved; }, (err) => { recorder.end(undefined, TraceStatus.FAILED); throw err; });
+            }
+            recorder.end(result, TraceStatus.COMPLETED);
+            return result;
+        }
+        catch (err) {
+            recorder.end(undefined, TraceStatus.FAILED);
+            throw err;
+        }
+    };
+}

package/dist/trace.d.ts

@@ -0,0 +1,74 @@
+export declare enum SpanType {
+    LLM_CALL = "llm_call",
+    TOOL_CALL = "tool_call",
+    TOOL_RESULT = "tool_result",
+    REASONING = "reasoning",
+    ACTION = "action",
+    ERROR = "error",
+    FORK_POINT = "fork_point"
+}
+export declare enum TraceStatus {
+    RUNNING = "running",
+    COMPLETED = "completed",
+    FAILED = "failed"
+}
+export interface SpanData {
+    id: string;
+    trace_id: string;
+    parent_id: string | null;
+    span_type: string;
+    name: string;
+    model?: string;
+    input?: unknown;
+    output?: unknown;
+    input_tokens?: number;
+    output_tokens?: number;
+    cost?: number;
+    duration_ms?: number;
+    metadata?: Record<string, unknown>;
+    started_at: string;
+    ended_at?: string;
+    error?: string;
+}
+export interface TraceData {
+    id: string;
+    name?: string;
+    input?: unknown;
+    output?: unknown;
+    status: string;
+    total_tokens: number;
+    total_cost: number;
+    total_duration_ms: number;
+    metadata?: Record<string, unknown>;
+    started_at: string;
+    ended_at?: string;
+    spans?: SpanData[];
+    project_id?: string;
+}
+export declare class SpanBuilder {
+    private data;
+    private _startTime?;
+    constructor(name: string, spanType: SpanType);
+    setModel(model: string): this;
+    setInput(input: unknown): this;
+    setOutput(output: unknown): this;
+    setParentId(id: string): this;
+    setTraceId(id: string): this;
+    setMetadata(m: Record<string, unknown>): this;
+    start(): this;
+    end(output?: unknown, error?: string): SpanData;
+    get id(): string;
+    toData(): SpanData;
+}
+export declare class TraceBuilder {
+    private data;
+    private _startTime?;
+    constructor();
+    start(name?: string, input?: unknown): this;
+    end(output?: unknown, status?: TraceStatus): TraceData;
+    addSpan(span: SpanData): void;
+    get id(): string;
+    setProjectId(id: string): void;
+    setMetadata(m: Record<string, unknown>): void;
+    toDict(): TraceData;
+}

package/dist/trace.js

@@ -0,0 +1,93 @@
+import { genId, nowIso, utcNow } from "./utils.js";
+export var SpanType;
+(function (SpanType) {
+    SpanType["LLM_CALL"] = "llm_call";
+    SpanType["TOOL_CALL"] = "tool_call";
+    SpanType["TOOL_RESULT"] = "tool_result";
+    SpanType["REASONING"] = "reasoning";
+    SpanType["ACTION"] = "action";
+    SpanType["ERROR"] = "error";
+    SpanType["FORK_POINT"] = "fork_point";
+})(SpanType || (SpanType = {}));
+export var TraceStatus;
+(function (TraceStatus) {
+    TraceStatus["RUNNING"] = "running";
+    TraceStatus["COMPLETED"] = "completed";
+    TraceStatus["FAILED"] = "failed";
+})(TraceStatus || (TraceStatus = {}));
+export class SpanBuilder {
+    data;
+    _startTime;
+    constructor(name, spanType) {
+        this.data = { id: genId(), span_type: spanType, name, trace_id: "", parent_id: null, started_at: nowIso() };
+    }
+    setModel(model) { this.data.model = model; return this; }
+    setInput(input) { this.data.input = input; return this; }
+    setOutput(output) { this.data.output = output; return this; }
+    setParentId(id) { this.data.parent_id = id; return this; }
+    setTraceId(id) { this.data.trace_id = id; return this; }
+    setMetadata(m) { this.data.metadata = m; return this; }
+    start() {
+        this._startTime = utcNow();
+        this.data.started_at = this._startTime.toISOString();
+        return this;
+    }
+    end(output, error) {
+        const now = utcNow();
+        this.data.ended_at = now.toISOString();
+        if (output !== undefined)
+            this.data.output = output;
+        if (error)
+            this.data.error = error;
+        if (this._startTime) {
+            this.data.duration_ms = now.getTime() - this._startTime.getTime();
+        }
+        return this.data;
+    }
+    get id() { return this.data.id; }
+    toData() { return this.data; }
+}
+export class TraceBuilder {
+    data;
+    _startTime;
+    constructor() {
+        this.data = {
+            id: genId(),
+            status: TraceStatus.RUNNING,
+            total_tokens: 0,
+            total_cost: 0,
+            total_duration_ms: 0,
+            started_at: nowIso(),
+            spans: [],
+        };
+    }
+    start(name, input) {
+        this._startTime = utcNow();
+        this.data.started_at = this._startTime.toISOString();
+        if (name)
+            this.data.name = name;
+        if (input !== undefined)
+            this.data.input = input;
+        return this;
+    }
+    end(output, status = TraceStatus.COMPLETED) {
+        const now = utcNow();
+        this.data.ended_at = now.toISOString();
+        this.data.status = status;
+        if (output !== undefined)
+            this.data.output = output;
+        if (this._startTime) {
+            this.data.total_duration_ms = now.getTime() - this._startTime.getTime();
+        }
+        return this.data;
+    }
+    addSpan(span) {
+        this.data.spans.push(span);
+        this.data.total_tokens += (span.input_tokens || 0) + (span.output_tokens || 0);
+        this.data.total_cost += span.cost || 0;
+    }
+    get id() { return this.data.id; }
+    setProjectId(id) { this.data.project_id = id; }
+    setMetadata(m) { this.data.metadata = m; }
+    toDict() { return this.data; }
+}

package/dist/transport.d.ts

@@ -0,0 +1,24 @@
+export interface Transport {
+    send(eventType: string, data: Record<string, unknown>): void;
+    close(): void;
+}
+export declare class WSTransport implements Transport {
+    private ws;
+    private connected;
+    private backoff;
+    private queue;
+    connect(): void;
+    private reconnect;
+    private flushQueue;
+    send(eventType: string, data: Record<string, unknown>): void;
+    close(): void;
+}
+export declare class HTTPTransport implements Transport {
+    private traceData;
+    private spans;
+    send(eventType: string, data: Record<string, unknown>): void;
+    flush(): void;
+    private buildSpans;
+    close(): void;
+}
+export declare function createTransport(mode?: "ws" | "http" | "auto"): Transport;