retrace-sdk 0.11.7 → 0.13.1

package/README.md

@@ -88,11 +88,56 @@ When you fork at any span in the dashboard, the SDK re-executes the entire funct
 ## Error Handling
 
 ```typescript
-import { RetraceError, RetraceAuthError, RetraceCreditsExhaustedError, RetraceRateLimitError } from "retrace-sdk";
+import { RetraceError, RetraceAuthError, RetraceCreditsExhaustedError, RetraceRateLimitError, RetraceEnforcementError } from "retrace-sdk";
 ```
 
 Typed errors for auth failures, credit exhaustion, and rate limiting.
 
+## Enforcement (Circuit Breakers)
+
+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.
+
+```typescript
+import { configure, RetraceEnforcementError } from "retrace-sdk";
+
+configure({
+  apiKey: "rt_live_...",
+  maxStepsPerRun: 50,
+  maxUsdPerRun: 2.0,
+  serverEnforcement: true, // optional: also consult server policies
+});
+
+try {
+  await runAgent("...");
+} catch (e) {
+  if (e instanceof RetraceEnforcementError) console.log(e.verdict, e.reason);
+}
+```
+
+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
+
+Tag spans with an agent id/role so the dashboard can draw the agent topology and run inter-agent detectors:
+
+```typescript
+import { withAgent } from "retrace-sdk";
+
+await withAgent({ id: "planner", role: "planner" }, async () => {
+  await callPlanner(prompt);
+});
+```
+
+## Golden Cassettes (CI Regression Gates)
+
+Record a run as a golden cassette and gate on it offline in CI with `retrace ci replay`:
+
+```typescript
+import { writeGoldenCassette } from "retrace-sdk";
+
+writeGoldenCassette("golden.json", { recorder });
+```
+
 ## Sampling
 
 ```typescript
@@ -101,7 +146,12 @@ configure({ apiKey: "rt_live_...", sampleRate: 0.1 }); // Record 10% of traces
 
 ## Changelog
 
-### 0.3.0
+### 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
+
 
 - **Sessions** — `sessionId` option in `TraceRecorder` and `trace()` to group multi-turn conversations
 - **Multi-Agent** — `setAgentId()` on `SpanBuilder` for cross-agent tracing

package/dist/agents.d.ts

@@ -0,0 +1,16 @@
+export interface AgentContext {
+    agentId: string;
+    agentRole?: string;
+    parentAgentId?: string;
+}
+/** The agent context spans are currently tagged with, or undefined outside any `withAgent` scope. */
+export declare function currentAgent(): AgentContext | undefined;
+/**
+ * Scope every span created inside `fn` to `agent.id`. `parent` defaults to the enclosing
+ * `withAgent` scope's id (the handoff edge).
+ */
+export declare function withAgent<T>(agent: {
+    id: string;
+    role?: string;
+    parent?: string;
+}, fn: () => T): T;

package/dist/agents.js

@@ -0,0 +1,32 @@
+/**
+ * Multi-agent topology helpers — tag spans with the agent that produced them.
+ *
+ * Framework-agnostic: run a sub-agent's work inside `withAgent(...)` and every span recorded there
+ * (including auto-instrumented LLM calls) inherits the agent id / role / parent, so the trace page
+ * can draw the agent topology. Uses AsyncLocalStorage (the same isolation primitive `trace()` uses)
+ * so concurrent agents in one process never clobber each other's context. Nested `withAgent` calls
+ * set `parentAgentId` automatically — nesting expresses the delegation graph.
+ *
+ * Framework mapping (explicit — deep auto-detection would couple the SDK to each framework):
+ *   - LangGraph: use the node name as the agent id.
+ *   - CrewAI: use the agent's role as id + role.
+ */
+import { AsyncLocalStorage } from "async_hooks";
+const agentStore = new AsyncLocalStorage();
+/** The agent context spans are currently tagged with, or undefined outside any `withAgent` scope. */
+export function currentAgent() {
+    return agentStore.getStore();
+}
+/**
+ * Scope every span created inside `fn` to `agent.id`. `parent` defaults to the enclosing
+ * `withAgent` scope's id (the handoff edge).
+ */
+export function withAgent(agent, fn) {
+    const prev = agentStore.getStore();
+    const ctx = {
+        agentId: agent.id,
+        agentRole: agent.role,
+        parentAgentId: agent.parent ?? prev?.agentId,
+    };
+    return agentStore.run(ctx, fn);
+}

package/dist/cassette.d.ts

@@ -0,0 +1,15 @@
+import type { TraceRecorder } from "./recorder.js";
+export interface CassetteTolerance {
+    default?: "exact" | "ignore" | "semantic" | "judge";
+    steps?: Record<string, "exact" | "ignore" | "semantic" | "judge">;
+    semantic_threshold?: number;
+}
+/**
+ * Write the active (or given) recorder's run to `path` as a golden cassette. Returns the cassette.
+ * Throws if no recorder is active — call it inside/after your traced function, before the process
+ * exits. `tolerance` is written through for CI divergence budgets.
+ */
+export declare function writeGoldenCassette(path: string, opts?: {
+    recorder?: TraceRecorder;
+    tolerance?: CassetteTolerance;
+}): unknown;

package/dist/cassette.js

@@ -0,0 +1,24 @@
+/**
+ * Golden cassette writer for CI regression replay (Phase 4b).
+ *
+ * After recording a run, write its cassette to a file you commit to your repo; `retrace ci replay`
+ * diffs a fresh run against it in CI. The JSON shape is the cross-language contract in
+ * `@retrace/shared` (CassetteSchema) — keep this writer in sync with it.
+ */
+import { writeFileSync } from "node:fs";
+import { getActiveRecorder } from "./init.js";
+/**
+ * Write the active (or given) recorder's run to `path` as a golden cassette. Returns the cassette.
+ * Throws if no recorder is active — call it inside/after your traced function, before the process
+ * exits. `tolerance` is written through for CI divergence budgets.
+ */
+export function writeGoldenCassette(path, opts) {
+    const recorder = opts?.recorder ?? getActiveRecorder();
+    if (!recorder)
+        throw new Error("writeGoldenCassette: no active recorder — call inside a traced run");
+    const cassette = recorder.toCassette();
+    if (opts?.tolerance)
+        cassette.tolerance = opts.tolerance;
+    writeFileSync(path, JSON.stringify(cassette, null, 2));
+    return cassette;
+}

package/dist/config.d.ts

@@ -20,6 +20,18 @@ export interface Config {
      *  halt | error. Branch on `signal.code`; use `signal.retryable`/`signal.fatal` to decide
      *  behavior. Defaults to a throttled console warning so signals are never silently dropped. */
     onError?: (signal: import("./errors.js").RetraceServerSignal) => void;
+    /** Enforcement (circuit breakers). LOCAL ceilings are enforced offline with zero network — they
+     *  always apply; `undefined` = unset. Precedence: explicit configure() arg > env var > unset.
+     *  `serverEnforcement=true` additionally consults the server /check endpoint for centrally-managed
+     *  policies (best-effort from the SDK; authoritative at ingest). */
+    maxStepsPerRun?: number;
+    maxTokensPerRun?: number;
+    maxUsdPerRun?: number;
+    serverEnforcement: boolean;
+    /** On a server `hold` verdict, poll up to this many seconds for a human decision before applying
+     *  the fail-closed timeout verdict. 0 = trip immediately. (The auto path is synchronous, so the
+     *  poll runs in the background and a denial/timeout trips the NEXT span.) */
+    enforcementHoldWaitSeconds: number;
 }
 export declare function configure(opts: Partial<Config>): Config;
 export declare function requireApiKey(): string;

package/dist/config.js

@@ -8,6 +8,11 @@ const config = {
     sampleSeed: process.env.RETRACE_SAMPLE_SEED || undefined,
     transport: (["auto", "ws", "http"].includes(process.env.RETRACE_TRANSPORT || "") ? process.env.RETRACE_TRANSPORT : "auto"),
     strictReplay: ["true", "1"].includes((process.env.RETRACE_STRICT_REPLAY || "").toLowerCase()),
+    maxStepsPerRun: process.env.RETRACE_MAX_STEPS_PER_RUN ? parseInt(process.env.RETRACE_MAX_STEPS_PER_RUN, 10) : undefined,
+    maxTokensPerRun: process.env.RETRACE_MAX_TOKENS_PER_RUN ? parseInt(process.env.RETRACE_MAX_TOKENS_PER_RUN, 10) : undefined,
+    maxUsdPerRun: process.env.RETRACE_MAX_USD_PER_RUN ? parseFloat(process.env.RETRACE_MAX_USD_PER_RUN) : undefined,
+    serverEnforcement: ["true", "1", "yes"].includes((process.env.RETRACE_SERVER_ENFORCEMENT || "").toLowerCase()),
+    enforcementHoldWaitSeconds: process.env.RETRACE_ENFORCEMENT_HOLD_WAIT_SECONDS ? parseInt(process.env.RETRACE_ENFORCEMENT_HOLD_WAIT_SECONDS, 10) : 0,
 };
 config.wsUrl = config.baseUrl.replace("https://", "wss://").replace("http://", "ws://");
 export function configure(opts) {

package/dist/enforcement.d.ts

@@ -0,0 +1,33 @@
+import type { Config } from "./config.js";
+/** Stable short hash of tool arguments so raw args never leave the process for a loop/debounce check. */
+export declare function hashToolArgs(args: unknown): string;
+export declare class EnforcementGate {
+    private config;
+    private runId;
+    private steps;
+    private tokens;
+    private usd;
+    /** A server block resolved asynchronously; trips on the next span (best-effort, one-span lag). */
+    private pendingBlock;
+    constructor(config: Config, runId: string);
+    /** No-op fast path unless a local ceiling is set or server enforcement is enabled. */
+    get active(): boolean;
+    /**
+     * Accumulate this span's usage and enforce. Throws RetraceEnforcementError on a tripped local
+     * ceiling (synchronous) or a previously-resolved server block. Safe to call on every span.
+     */
+    recordAndCheck(opts: {
+        tokens?: number;
+        usd?: number;
+        traceId?: string;
+        toolName?: string;
+        toolArgsHash?: string;
+    }): void;
+    /** Best-effort server consult. Records a pending block on a block/hold verdict; never throws. */
+    private serverCheck;
+    /** A held action: poll for a human decision up to the configured wait, then trip on denial/timeout
+     *  (sets pendingBlock, which stops the next span). With wait=0 the hold trips immediately. */
+    private handleHold;
+    /** Read a hold's status; returns "pending" on any transport error so the loop keeps waiting. */
+    private pollHold;
+}

package/dist/enforcement.js

@@ -0,0 +1,146 @@
+/**
+ * Client-side enforcement gate (circuit breakers) — the TypeScript twin of the Python
+ * `EnforcementGate` (same names, same semantics).
+ *
+ * LOCAL ceilings (max steps / tokens / USD per run) are enforced entirely offline — zero network, so
+ * the breaker trips even when the API is unreachable, and it throws SYNCHRONOUSLY before the next
+ * call. When `serverEnforcement` is enabled the gate ALSO consults the server `/enforcement/check`
+ * endpoint; because auto-instrumentation routes spans synchronously, that call is best-effort and
+ * fire-and-forget — a server block trips the NEXT span (one-span lag) rather than the current one,
+ * and a transport failure is logged, never swallowed (server policy is authoritative at ingest).
+ */
+import { createHash } from "node:crypto";
+import { RetraceEnforcementError } from "./errors.js";
+/** Stable short hash of tool arguments so raw args never leave the process for a loop/debounce check. */
+export function hashToolArgs(args) {
+    let serialized;
+    try {
+        serialized = typeof args === "string" ? args : JSON.stringify(args, Object.keys(args ?? {}).sort());
+    }
+    catch {
+        serialized = String(args);
+    }
+    return createHash("sha256").update(serialized).digest("hex").slice(0, 32);
+}
+export class EnforcementGate {
+    config;
+    runId;
+    steps = 0;
+    tokens = 0;
+    usd = 0;
+    /** A server block resolved asynchronously; trips on the next span (best-effort, one-span lag). */
+    pendingBlock = null;
+    constructor(config, runId) {
+        this.config = config;
+        this.runId = runId;
+    }
+    /** No-op fast path unless a local ceiling is set or server enforcement is enabled. */
+    get active() {
+        const c = this.config;
+        return c.maxStepsPerRun !== undefined || c.maxTokensPerRun !== undefined || c.maxUsdPerRun !== undefined || c.serverEnforcement;
+    }
+    /**
+     * Accumulate this span's usage and enforce. Throws RetraceEnforcementError on a tripped local
+     * ceiling (synchronous) or a previously-resolved server block. Safe to call on every span.
+     */
+    recordAndCheck(opts) {
+        if (!this.active)
+            return;
+        // A server block resolved after the previous span trips here, before this call proceeds.
+        if (this.pendingBlock) {
+            const err = this.pendingBlock;
+            this.pendingBlock = null;
+            throw err;
+        }
+        this.steps += 1;
+        this.tokens += Math.max(0, opts.tokens ?? 0);
+        this.usd += Math.max(0, opts.usd ?? 0);
+        const c = this.config;
+        if (c.maxStepsPerRun !== undefined && this.steps > c.maxStepsPerRun) {
+            throw new RetraceEnforcementError(`Local step ceiling reached: ${this.steps} > ${c.maxStepsPerRun} per run.`);
+        }
+        if (c.maxTokensPerRun !== undefined && this.tokens > c.maxTokensPerRun) {
+            throw new RetraceEnforcementError(`Local token ceiling reached: ${this.tokens} > ${c.maxTokensPerRun} per run.`);
+        }
+        if (c.maxUsdPerRun !== undefined && this.usd > c.maxUsdPerRun) {
+            throw new RetraceEnforcementError(`Local USD ceiling reached: $${this.usd.toFixed(4)} > $${c.maxUsdPerRun} per run.`);
+        }
+        if (c.serverEnforcement)
+            void this.serverCheck(opts);
+    }
+    /** Best-effort server consult. Records a pending block on a block/hold verdict; never throws. */
+    async serverCheck(opts) {
+        const c = this.config;
+        if (!c.apiKey)
+            return;
+        const body = { run_id: this.runId, proposed_tokens: opts.tokens ?? 0, proposed_usd: opts.usd ?? 0 };
+        if (c.projectId)
+            body.project_id = c.projectId;
+        if (opts.traceId)
+            body.trace_id = opts.traceId;
+        if (opts.toolName)
+            body.tool_name = opts.toolName;
+        if (opts.toolArgsHash)
+            body.tool_args_hash = opts.toolArgsHash;
+        try {
+            const resp = await fetch(`${c.baseUrl}/api/v1/enforcement/check`, {
+                method: "POST",
+                headers: { "x-retrace-key": c.apiKey, "Content-Type": "application/json" },
+                body: JSON.stringify(body),
+                signal: AbortSignal.timeout(5000),
+            });
+            if (resp.status !== 200 && resp.status !== 202) {
+                console.warn(`[retrace] server enforcement check returned ${resp.status} (local limits still apply)`);
+                return;
+            }
+            const data = (await resp.json());
+            if (data.verdict === "block") {
+                this.pendingBlock = new RetraceEnforcementError(data.reason || "Blocked by server policy.", "block", data.policy_id);
+            }
+            else if (data.verdict === "hold") {
+                await this.handleHold(data);
+            }
+        }
+        catch (e) {
+            console.warn(`[retrace] server enforcement check unreachable (local limits still apply): ${e.message}`);
+        }
+    }
+    /** A held action: poll for a human decision up to the configured wait, then trip on denial/timeout
+     *  (sets pendingBlock, which stops the next span). With wait=0 the hold trips immediately. */
+    async handleHold(data) {
+        const c = this.config;
+        const err = new RetraceEnforcementError(data.reason || "Held by server policy.", "hold", data.policy_id);
+        if (!data.hold_id || c.enforcementHoldWaitSeconds <= 0) {
+            this.pendingBlock = err;
+            return;
+        }
+        const deadline = Date.now() + c.enforcementHoldWaitSeconds * 1000;
+        const interval = Math.min(2000, Math.max(500, (c.enforcementHoldWaitSeconds * 1000) / 10));
+        while (Date.now() < deadline) {
+            const status = await this.pollHold(data.hold_id);
+            if (status === "approved")
+                return; // released — no pending block
+            if (status === "denied" || status === "expired") {
+                this.pendingBlock = err;
+                return;
+            }
+            await new Promise((r) => setTimeout(r, interval));
+        }
+        this.pendingBlock = err; // timed out → fail-closed
+    }
+    /** Read a hold's status; returns "pending" on any transport error so the loop keeps waiting. */
+    async pollHold(holdId) {
+        try {
+            const resp = await fetch(`${this.config.baseUrl}/api/v1/enforcement/holds/${holdId}`, {
+                headers: { "x-retrace-key": this.config.apiKey },
+                signal: AbortSignal.timeout(5000),
+            });
+            if (resp.status === 200)
+                return (await resp.json()).status || "pending";
+        }
+        catch {
+            // transient — keep waiting
+        }
+        return "pending";
+    }
+}

package/dist/errors.d.ts

@@ -14,6 +14,21 @@ export declare class RetraceRateLimitError extends RetraceError {
     retryAfter: number;
     constructor(retryAfter: number);
 }
+/**
+ * An enforcement circuit breaker blocked (or held) the action. Thrown by the pre-call gate when a
+ * LOCAL limit (max steps / tokens / USD per run) is exceeded, or when an opt-in server-side policy
+ * returns a block/hold verdict. NEVER thrown silently — the agent loop stops here rather than
+ * continuing past a runaway condition. Mirrors the Python `RetraceEnforcementError`.
+ */
+export declare class RetraceEnforcementError extends RetraceError {
+    /** "block" or "hold". */
+    verdict: string;
+    /** The ceiling that tripped, or the server reason. */
+    reason: string;
+    /** The server policy that tripped, when the verdict came from the server (else undefined). */
+    policyId?: string;
+    constructor(reason: string, verdict?: string, policyId?: string);
+}
 /**
  * Structured server-originated signal handed to `onError`. Actionable WITHOUT string-matching:
  * branch on `code`, decide retry from `retryable`, decide whether recording is still alive from

package/dist/errors.js

@@ -14,6 +14,27 @@ export class RetraceRateLimitError extends RetraceError {
     retryAfter;
     constructor(retryAfter) { super(`Rate limited. Retry after ${retryAfter}s`); this.name = "RetraceRateLimitError"; this.retryAfter = retryAfter; }
 }
+/**
+ * An enforcement circuit breaker blocked (or held) the action. Thrown by the pre-call gate when a
+ * LOCAL limit (max steps / tokens / USD per run) is exceeded, or when an opt-in server-side policy
+ * returns a block/hold verdict. NEVER thrown silently — the agent loop stops here rather than
+ * continuing past a runaway condition. Mirrors the Python `RetraceEnforcementError`.
+ */
+export class RetraceEnforcementError extends RetraceError {
+    /** "block" or "hold". */
+    verdict;
+    /** The ceiling that tripped, or the server reason. */
+    reason;
+    /** The server policy that tripped, when the verdict came from the server (else undefined). */
+    policyId;
+    constructor(reason, verdict = "block", policyId) {
+        super(`Enforcement ${verdict}: ${reason}`);
+        this.name = "RetraceEnforcementError";
+        this.verdict = verdict;
+        this.reason = reason;
+        this.policyId = policyId;
+    }
+}
 /**
  * Map a raw server frame to a structured signal. Single source of truth for category + retryable +
  * fatal, shared by the WS dispatch. Kept here (not inline in the dispatch) so TS and Python classify

package/dist/index.d.ts

@@ -9,13 +9,17 @@ 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 { RetraceError, RetraceAuthError, RetraceCreditsExhaustedError, RetraceConnectionError, RetraceRateLimitError, RetraceEnforcementError } from "./errors.js";
 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, withTraceContext } from "./traceparent.js";
 export { markGolden } from "./golden.js";
+export { writeGoldenCassette } from "./cassette.js";
+export type { CassetteTolerance } from "./cassette.js";
+export { withAgent, currentAgent } from "./agents.js";
+export type { AgentContext } from "./agents.js";
 export { setTruncationLimits } from "./utils.js";
 export { createLangChainHandler } from "./adapters/langchain.js";
 export { retraceOnStepFinish, recordVercelStep } from "./adapters/vercel-ai.js";

package/dist/index.js

@@ -7,11 +7,13 @@ 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 { RetraceError, RetraceAuthError, RetraceCreditsExhaustedError, RetraceConnectionError, RetraceRateLimitError, RetraceEnforcementError } from "./errors.js";
 export { registerResumable, handleResume } from "./resume.js";
 export { isReplaying, consumeCassetteEntry, handleReplay } from "./replay.js";
 export { setTraceContext, clearTraceContext, getTraceparent, injectTraceparent, parseTraceparent, withTraceContext } from "./traceparent.js";
 export { markGolden } from "./golden.js";
+export { writeGoldenCassette } from "./cassette.js";
+export { withAgent, currentAgent } from "./agents.js";
 export { setTruncationLimits } from "./utils.js";
 // Framework adapters (5B) — drop-in instrumentation for LangChain/LangGraph + Vercel AI SDK.
 export { createLangChainHandler } from "./adapters/langchain.js";

package/dist/recorder.d.ts

@@ -26,8 +26,30 @@ export declare class TraceRecorder {
     private forkPointReached;
     private spanCounter;
     output: unknown;
+    private enforcement;
     constructor(opts?: RecordOptions);
     get traceId(): string;
+    /**
+     * Export this recorder's completed spans as a golden cassette (Phase 4b). The snapshot is the
+     * CI regression baseline — `retrace ci replay` diffs a fresh run against it. Capture AFTER the
+     * traced function returns so all spans are present.
+     */
+    toCassette(): {
+        version: 1;
+        name: string;
+        trace_id: string;
+        recorded_at: string;
+        status: string;
+        steps: {
+            index: number;
+            span_type: string;
+            name: string;
+            model?: string | null;
+            input?: unknown;
+            output?: unknown;
+            error?: string | null;
+        }[];
+    };
     start(name?: string, input?: unknown, opts?: {
         managed?: boolean;
     }): this;

package/dist/recorder.js

@@ -7,6 +7,8 @@ import { installOpenAIInterceptor } from "./interceptors/openai.js";
 import { installAnthropicInterceptor } from "./interceptors/anthropic.js";
 import { dispatchInterceptedSpan, runWithActiveRecorder, setActiveRecorderFallback, currentFallbackSink } from "./interceptors/_dispatch.js";
 import { withTraceContext, enterTraceContext, exitTraceContext } from "./traceparent.js";
+import { EnforcementGate, hashToolArgs } from "./enforcement.js";
+import { currentAgent } from "./agents.js";
 // Shared transport — stays open across multiple traces for resume/replay listening
 let sharedTransport = null;
 // Count of imperative (non-HOF) recorders currently between start() and end(). The bare imperative
@@ -59,6 +61,7 @@ export class TraceRecorder {
     forkPointReached = false;
     spanCounter = 0;
     output = undefined;
+    enforcement;
     constructor(opts) {
         requireApiKey();
         this.builder = new TraceBuilder();
@@ -69,6 +72,8 @@ export class TraceRecorder {
         // otherwise (normal recording, or a fork command without an index) emit everything.
         this.forkPointReached = !opts?.forkPointSpanId || opts?.forkPointIndex === undefined;
         const cfg = getConfig();
+        // Per-run circuit breaker (no-op unless a local ceiling or server enforcement is configured).
+        this.enforcement = new EnforcementGate(cfg, this.builder.id);
         if (cfg.projectId)
             this.builder.setProjectId(cfg.projectId);
         if (opts?.metadata)
@@ -80,6 +85,31 @@ export class TraceRecorder {
         }
     }
     get traceId() { return this.builder.id; }
+    /**
+     * Export this recorder's completed spans as a golden cassette (Phase 4b). The snapshot is the
+     * CI regression baseline — `retrace ci replay` diffs a fresh run against it. Capture AFTER the
+     * traced function returns so all spans are present.
+     */
+    toCassette() {
+        const data = this.builder.toDict();
+        const steps = (data.spans ?? []).map((s, index) => ({
+            index,
+            span_type: s.span_type,
+            name: s.name,
+            model: s.model ?? null,
+            input: s.input,
+            output: s.output,
+            error: s.error ?? null,
+        }));
+        return {
+            version: 1,
+            name: data.name ?? "trace",
+            trace_id: data.id,
+            recorded_at: new Date().toISOString(),
+            status: data.status,
+            steps,
+        };
+    }
     start(name, input, opts) {
         // Never-silent guard for the imperative path: if another imperative trace is already active when
         // this one starts, overlapping imperative record() use can cross-attribute spans/traceparent.
@@ -177,6 +207,15 @@ export class TraceRecorder {
             }
         }
         span.trace_id = this.builder.id;
+        const actx = currentAgent();
+        if (actx) {
+            if (!span.agent_id)
+                span.agent_id = actx.agentId;
+            if (!span.agent_role)
+                span.agent_role = actx.agentRole;
+            if (!span.parent_agent_id)
+                span.parent_agent_id = actx.parentAgentId;
+        }
         this.builder.addSpan(span);
         this.transport.send("span_started", span);
         if (span.ended_at) {
@@ -189,6 +228,19 @@ export class TraceRecorder {
                 error: span.error,
             });
         }
+        // Circuit breaker: record this span's usage and enforce BEFORE the next call. Throws
+        // RetraceEnforcementError on a tripped local ceiling (recording above is already done, so the
+        // trace keeps the offending span; only the run is stopped).
+        if (this.enforcement.active) {
+            const isTool = span.span_type === SpanType.TOOL_CALL;
+            this.enforcement.recordAndCheck({
+                tokens: (span.input_tokens ?? 0) + (span.output_tokens ?? 0),
+                usd: span.cost ?? 0,
+                traceId: this.builder.id,
+                toolName: isTool ? span.name : undefined,
+                toolArgsHash: isTool ? hashToolArgs(span.input) : undefined,
+            });
+        }
     }
     startSpan(name, spanType = SpanType.LLM_CALL, input, model, parentId) {
         const sb = new SpanBuilder(name, spanType).start();
@@ -199,6 +251,9 @@ export class TraceRecorder {
             sb.setModel(model);
         if (parentId)
             sb.setParentId(parentId);
+        const actx = currentAgent();
+        if (actx)
+            sb.setAgent({ id: actx.agentId, role: actx.agentRole, parentId: actx.parentAgentId });
         this.transport.send("span_started", sb.toData());
         return sb;
     }

package/dist/trace.d.ts

@@ -27,6 +27,8 @@ export interface SpanData {
     duration_ms?: number;
     metadata?: Record<string, unknown>;
     agent_id?: string;
+    parent_agent_id?: string;
+    agent_role?: string;
     started_at: string;
     ended_at?: string;
     error?: string;
@@ -60,6 +62,12 @@ export declare class SpanBuilder {
     setTraceId(id: string): this;
     setMetadata(m: Record<string, unknown>): this;
     setAgentId(id: string): this;
+    /** Multi-agent topology: who delegated to this agent + this agent's role/persona. */
+    setAgent(opts: {
+        id?: string;
+        parentId?: string;
+        role?: string;
+    }): this;
     start(): this;
     end(output?: unknown, error?: string): SpanData;
     get id(): string;

package/dist/trace.js

@@ -28,6 +28,16 @@ export class SpanBuilder {
     setTraceId(id) { this.data.trace_id = id; return this; }
     setMetadata(m) { this.data.metadata = m; return this; }
     setAgentId(id) { this.data.agent_id = id; return this; }
+    /** Multi-agent topology: who delegated to this agent + this agent's role/persona. */
+    setAgent(opts) {
+        if (opts.id !== undefined)
+            this.data.agent_id = opts.id;
+        if (opts.parentId !== undefined)
+            this.data.parent_agent_id = opts.parentId;
+        if (opts.role !== undefined)
+            this.data.agent_role = opts.role;
+        return this;
+    }
     start() {
         this._startTime = utcNow();
         this.data.started_at = this._startTime.toISOString();

package/dist/transport.js

@@ -1,6 +1,9 @@
 import WebSocket from "ws";
 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.13.1";
 export class WSTransport {
     ws = null;
     connected = false;
@@ -265,7 +268,7 @@ export class WSTransport {
                 try {
                     await fetch(`${cfg.baseUrl}/api/v1/traces`, {
                         method: "POST",
-                        headers: { "x-retrace-key": cfg.apiKey, "Content-Type": "application/json" },
+                        headers: { "x-retrace-key": cfg.apiKey, "Content-Type": "application/json", "x-retrace-client": CLIENT_ID },
                         body,
                         keepalive: true,
                         signal: ctrl.signal,
@@ -310,7 +313,7 @@ export class HTTPTransport {
             try {
                 const res = await fetch(url, {
                     method: "POST",
-                    headers: { "x-retrace-key": cfg.apiKey, "Content-Type": "application/json" },
+                    headers: { "x-retrace-key": cfg.apiKey, "Content-Type": "application/json", "x-retrace-client": CLIENT_ID },
                     body: payload,
                 });
                 if (res.ok)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "retrace-sdk",
-  "version": "0.11.7",
+  "version": "0.13.1",
   "description": "The execution replay engine for AI agents. Record, replay, fork, and share agent executions.",
   "type": "module",
   "main": "dist/index.js",
@@ -19,7 +19,11 @@
       "import": "./dist/adapters/vercel-ai.js"
     }
   },
-  "files": ["dist", "README.md", "LICENSE"],
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
   "license": "MIT",
   "author": "Yash Bogam",
   "repository": {
@@ -28,7 +32,17 @@
     "directory": "packages/sdk-typescript"
   },
   "homepage": "https://retrace.yashbogam.me/docs/sdk-typescript",
-  "keywords": ["ai", "agent", "tracing", "observability", "replay", "llm", "openai", "anthropic", "gemini"],
+  "keywords": [
+    "ai",
+    "agent",
+    "tracing",
+    "observability",
+    "replay",
+    "llm",
+    "openai",
+    "anthropic",
+    "gemini"
+  ],
   "engines": {
     "node": ">=20"
   },