@bitfab/sdk 0.28.11 → 0.29.0

package/dist/index.d.cts

@@ -73,6 +73,76 @@ declare class BitfabError extends Error {
     constructor(message: string, url?: string | undefined);
 }
 
+/**
+ * Selective mock overrides for replay.
+ *
+ * A mock override injects a custom value into a specific span (node) during
+ * replay: the matched span short-circuits its real execution and returns the
+ * value you supply, so downstream real code runs against the substituted
+ * output. This is a third mock mode alongside "run real code" and "replay
+ * recorded output" (see {@link MockStrategy}).
+ *
+ * The matcher and value are deliberately separate so matching stays cheap
+ * (structural metadata only, no output fetch) and the recorded output is
+ * fetched lazily - and only if the value function actually asks for it via
+ * {@link MockOverrideCtx.getOriginalOutput}.
+ */
+/**
+ * Structural identity of a span during replay, passed to a {@link NodeMatcher}.
+ * Carries no output payload - matching must not depend on the recorded output,
+ * so the output fetch stays lazy and gated.
+ */
+interface SpanNodeMeta {
+    /** The `withSpan` key of the executing span (its code-side identity). */
+    traceFunctionKey: string;
+    /** Resolved span name: `options.name ?? fn.name ?? traceFunctionKey`. */
+    spanName: string;
+    /** Span type, e.g. "llm", "agent", "tool", "custom". */
+    type: string;
+    /**
+     * The id of this span in the original (replayed) trace, when it exists in
+     * that trace's tree. Undefined when the live span has no recorded
+     * counterpart (e.g. a span the changed code newly introduced).
+     */
+    originalSpanId?: string;
+}
+/** Context passed to a {@link MockValue} function for a matched span. */
+interface MockOverrideCtx {
+    /** The matched span's structural metadata. */
+    node: SpanNodeMeta;
+    /** The live replay args passed to the wrapped function this run. */
+    inputs: unknown[];
+    /**
+     * Lazily fetch this span's ORIGINAL recorded output (deserialized). The fetch
+     * happens only when called and is memoized per replay item, so a purely flat
+     * override that never calls it triggers zero output round trips. Rejects if
+     * the span has no recorded counterpart. Being async, it is only usable for
+     * spans wrapping async functions.
+     */
+    getOriginalOutput: () => Promise<unknown>;
+}
+/** Selects which spans an override applies to. Runs on structural metadata. */
+type NodeMatcher = (node: SpanNodeMeta) => boolean;
+/** The function form of {@link MockValue}, receiving the override context. */
+type MockValueFn = (ctx: MockOverrideCtx) => unknown | Promise<unknown>;
+/**
+ * The value injected for a matched span: either a flat value used as-is, or a
+ * function of the {@link MockOverrideCtx} that returns one (or a Promise of
+ * one). Full replacement - the value IS the span's output, no merge with the
+ * recorded output.
+ *
+ * The flat side is spelled out (rather than `unknown`) so an inline function
+ * still gets a typed `ctx`: `unknown | Fn` would collapse to `unknown` and drop
+ * the contextual type. To inject a value that is itself a function, wrap it:
+ * `value: () => theFunction`.
+ */
+type MockValue = MockValueFn | string | number | boolean | bigint | symbol | object | null | undefined;
+/** One (match, value) pair. */
+interface MockOverride {
+    match: NodeMatcher;
+    value: MockValue;
+}
+
 /**
  * HTTP client utilities for Bitfab API requests.
  *
@@ -654,6 +724,15 @@ interface ReplayOptions {
      * - "all": every child withSpan returns historical output
      */
     mock?: MockStrategy;
+    /**
+     * Selective mock overrides: inject custom values into specific spans during
+     * replay, so downstream real code runs against the substituted output. Each
+     * override is a `{ match, value }` pair; the first matcher that
+     * matches a span wins. These take precedence over any overrides registered on
+     * the client via `registerMockOverride`, and over the base `mock` strategy - a
+     * span no override matches falls back to that strategy. See {@link MockOverride}.
+     */
+    mockOverride?: MockOverride | MockOverride[];
     /**
      * Per-trace environment. When the source trace carries a DB branching
      * snapshot, the SDK populates `environment.databaseUrl` before invoking
@@ -1192,6 +1271,12 @@ declare class Bitfab {
     private readonly httpClient;
     private readonly bamlClient;
     private readonly dbSnapshot;
+    /**
+     * Mock overrides registered via {@link Bitfab.registerMockOverride}, applied
+     * to every `replay` on this client (after any per-call `mockOverride`). In
+     * registration order; first matcher wins within this list.
+     */
+    private readonly mockOverrides;
     /**
      * Initialize the Bitfab client.
      *
@@ -1499,6 +1584,30 @@ declare class Bitfab {
      *   determines how many traces replay.
      * @returns ReplayResult with items, testRunId, and testRunUrl
      */
+    /**
+     * Register a mock override applied to every subsequent `replay` on this
+     * client, so downstream real code runs against a value you supply for the
+     * matched span. Instance-scoped (no global state); call {@link clearMockOverrides}
+     * to reset. Per-call `replay({ mockOverride })` overrides take precedence, and
+     * both take precedence over the base `mock` strategy.
+     *
+     * ```ts
+     * // Object form (value is a flat value here)
+     * bitfab.registerMockOverride({
+     *   match: (node) => node.traceFunctionKey === "classify-intent",
+     *   value: { label: "refund" },
+     * })
+     * // Ordered form (equivalent); value may also be a function of the context
+     * bitfab.registerMockOverride(
+     *   (node) => node.traceFunctionKey === "classify-intent",
+     *   ({ inputs }) => ({ label: "refund" }),
+     * )
+     * ```
+     */
+    registerMockOverride(override: MockOverride): void;
+    registerMockOverride(match: NodeMatcher, value: MockValue): void;
+    /** Remove all overrides registered via {@link registerMockOverride}. */
+    clearMockOverrides(): void;
     replay<TReturn>(traceFunctionKey: string, fn: (...args: any[]) => TReturn | Promise<TReturn>, options?: ReplayOptions): Promise<ReplayResult<TReturn>>;
 }
 /**
@@ -1649,7 +1758,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.28.11";
+declare const __version__ = "0.29.0";
 
 /**
  * Constants for the Bitfab SDK.
@@ -1717,4 +1826,4 @@ declare const finalizers: {
     readableStream: typeof readableStream;
 };
 
-export { type ActiveSpanContext, type AdaptContext, type AdaptInputsFn, type AllowedEnvVars, BITFAB_PROGRESS_PREFIX, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler as BitfabLangChainCallbackHandler, BitfabLangGraphCallbackHandler, type BitfabLanguageModelMiddleware, BitfabOpenAIAgentHandler, BitfabOpenAITracingProcessor, BitfabVercelAiHandler, type CapturedSpan, type CodeChangeFile, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, type MockStrategy, type ProviderDefinition, ReplayEnvironment, type ReplayEnvironmentSnapshot, type ReplayItem, type ReplayOptions, type ReplayProgress, type ReplayResult, SUPPORTED_PROVIDERS, type SpanLookup, type SpanOccurrence, type SpanOptions, type SpanType, type TokenUsage, type TraceResponse, type TracingProcessor, type VercelCallParams, type VercelGenerateResult, type VercelStreamResult, type WrapBAMLOptions, type WrappedBamlFn, __version__, finalizers, flushTraces, getCurrentSpan, getCurrentTrace, reportReplayProgress };
+export { type ActiveSpanContext, type AdaptContext, type AdaptInputsFn, type AllowedEnvVars, BITFAB_PROGRESS_PREFIX, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler as BitfabLangChainCallbackHandler, BitfabLangGraphCallbackHandler, type BitfabLanguageModelMiddleware, BitfabOpenAIAgentHandler, BitfabOpenAITracingProcessor, BitfabVercelAiHandler, type CapturedSpan, type CodeChangeFile, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, type MockOverride, type MockOverrideCtx, type MockStrategy, type MockValue, type NodeMatcher, type ProviderDefinition, ReplayEnvironment, type ReplayEnvironmentSnapshot, type ReplayItem, type ReplayOptions, type ReplayProgress, type ReplayResult, SUPPORTED_PROVIDERS, type SpanLookup, type SpanNodeMeta, type SpanOccurrence, type SpanOptions, type SpanType, type TokenUsage, type TraceResponse, type TracingProcessor, type VercelCallParams, type VercelGenerateResult, type VercelStreamResult, type WrapBAMLOptions, type WrappedBamlFn, __version__, finalizers, flushTraces, getCurrentSpan, getCurrentTrace, reportReplayProgress };

package/dist/index.d.ts

@@ -73,6 +73,76 @@ declare class BitfabError extends Error {
     constructor(message: string, url?: string | undefined);
 }
 
+/**
+ * Selective mock overrides for replay.
+ *
+ * A mock override injects a custom value into a specific span (node) during
+ * replay: the matched span short-circuits its real execution and returns the
+ * value you supply, so downstream real code runs against the substituted
+ * output. This is a third mock mode alongside "run real code" and "replay
+ * recorded output" (see {@link MockStrategy}).
+ *
+ * The matcher and value are deliberately separate so matching stays cheap
+ * (structural metadata only, no output fetch) and the recorded output is
+ * fetched lazily - and only if the value function actually asks for it via
+ * {@link MockOverrideCtx.getOriginalOutput}.
+ */
+/**
+ * Structural identity of a span during replay, passed to a {@link NodeMatcher}.
+ * Carries no output payload - matching must not depend on the recorded output,
+ * so the output fetch stays lazy and gated.
+ */
+interface SpanNodeMeta {
+    /** The `withSpan` key of the executing span (its code-side identity). */
+    traceFunctionKey: string;
+    /** Resolved span name: `options.name ?? fn.name ?? traceFunctionKey`. */
+    spanName: string;
+    /** Span type, e.g. "llm", "agent", "tool", "custom". */
+    type: string;
+    /**
+     * The id of this span in the original (replayed) trace, when it exists in
+     * that trace's tree. Undefined when the live span has no recorded
+     * counterpart (e.g. a span the changed code newly introduced).
+     */
+    originalSpanId?: string;
+}
+/** Context passed to a {@link MockValue} function for a matched span. */
+interface MockOverrideCtx {
+    /** The matched span's structural metadata. */
+    node: SpanNodeMeta;
+    /** The live replay args passed to the wrapped function this run. */
+    inputs: unknown[];
+    /**
+     * Lazily fetch this span's ORIGINAL recorded output (deserialized). The fetch
+     * happens only when called and is memoized per replay item, so a purely flat
+     * override that never calls it triggers zero output round trips. Rejects if
+     * the span has no recorded counterpart. Being async, it is only usable for
+     * spans wrapping async functions.
+     */
+    getOriginalOutput: () => Promise<unknown>;
+}
+/** Selects which spans an override applies to. Runs on structural metadata. */
+type NodeMatcher = (node: SpanNodeMeta) => boolean;
+/** The function form of {@link MockValue}, receiving the override context. */
+type MockValueFn = (ctx: MockOverrideCtx) => unknown | Promise<unknown>;
+/**
+ * The value injected for a matched span: either a flat value used as-is, or a
+ * function of the {@link MockOverrideCtx} that returns one (or a Promise of
+ * one). Full replacement - the value IS the span's output, no merge with the
+ * recorded output.
+ *
+ * The flat side is spelled out (rather than `unknown`) so an inline function
+ * still gets a typed `ctx`: `unknown | Fn` would collapse to `unknown` and drop
+ * the contextual type. To inject a value that is itself a function, wrap it:
+ * `value: () => theFunction`.
+ */
+type MockValue = MockValueFn | string | number | boolean | bigint | symbol | object | null | undefined;
+/** One (match, value) pair. */
+interface MockOverride {
+    match: NodeMatcher;
+    value: MockValue;
+}
+
 /**
  * HTTP client utilities for Bitfab API requests.
  *
@@ -654,6 +724,15 @@ interface ReplayOptions {
      * - "all": every child withSpan returns historical output
      */
     mock?: MockStrategy;
+    /**
+     * Selective mock overrides: inject custom values into specific spans during
+     * replay, so downstream real code runs against the substituted output. Each
+     * override is a `{ match, value }` pair; the first matcher that
+     * matches a span wins. These take precedence over any overrides registered on
+     * the client via `registerMockOverride`, and over the base `mock` strategy - a
+     * span no override matches falls back to that strategy. See {@link MockOverride}.
+     */
+    mockOverride?: MockOverride | MockOverride[];
     /**
      * Per-trace environment. When the source trace carries a DB branching
      * snapshot, the SDK populates `environment.databaseUrl` before invoking
@@ -1192,6 +1271,12 @@ declare class Bitfab {
     private readonly httpClient;
     private readonly bamlClient;
     private readonly dbSnapshot;
+    /**
+     * Mock overrides registered via {@link Bitfab.registerMockOverride}, applied
+     * to every `replay` on this client (after any per-call `mockOverride`). In
+     * registration order; first matcher wins within this list.
+     */
+    private readonly mockOverrides;
     /**
      * Initialize the Bitfab client.
      *
@@ -1499,6 +1584,30 @@ declare class Bitfab {
      *   determines how many traces replay.
      * @returns ReplayResult with items, testRunId, and testRunUrl
      */
+    /**
+     * Register a mock override applied to every subsequent `replay` on this
+     * client, so downstream real code runs against a value you supply for the
+     * matched span. Instance-scoped (no global state); call {@link clearMockOverrides}
+     * to reset. Per-call `replay({ mockOverride })` overrides take precedence, and
+     * both take precedence over the base `mock` strategy.
+     *
+     * ```ts
+     * // Object form (value is a flat value here)
+     * bitfab.registerMockOverride({
+     *   match: (node) => node.traceFunctionKey === "classify-intent",
+     *   value: { label: "refund" },
+     * })
+     * // Ordered form (equivalent); value may also be a function of the context
+     * bitfab.registerMockOverride(
+     *   (node) => node.traceFunctionKey === "classify-intent",
+     *   ({ inputs }) => ({ label: "refund" }),
+     * )
+     * ```
+     */
+    registerMockOverride(override: MockOverride): void;
+    registerMockOverride(match: NodeMatcher, value: MockValue): void;
+    /** Remove all overrides registered via {@link registerMockOverride}. */
+    clearMockOverrides(): void;
     replay<TReturn>(traceFunctionKey: string, fn: (...args: any[]) => TReturn | Promise<TReturn>, options?: ReplayOptions): Promise<ReplayResult<TReturn>>;
 }
 /**
@@ -1649,7 +1758,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.28.11";
+declare const __version__ = "0.29.0";
 
 /**
  * Constants for the Bitfab SDK.
@@ -1717,4 +1826,4 @@ declare const finalizers: {
     readableStream: typeof readableStream;
 };
 
-export { type ActiveSpanContext, type AdaptContext, type AdaptInputsFn, type AllowedEnvVars, BITFAB_PROGRESS_PREFIX, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler as BitfabLangChainCallbackHandler, BitfabLangGraphCallbackHandler, type BitfabLanguageModelMiddleware, BitfabOpenAIAgentHandler, BitfabOpenAITracingProcessor, BitfabVercelAiHandler, type CapturedSpan, type CodeChangeFile, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, type MockStrategy, type ProviderDefinition, ReplayEnvironment, type ReplayEnvironmentSnapshot, type ReplayItem, type ReplayOptions, type ReplayProgress, type ReplayResult, SUPPORTED_PROVIDERS, type SpanLookup, type SpanOccurrence, type SpanOptions, type SpanType, type TokenUsage, type TraceResponse, type TracingProcessor, type VercelCallParams, type VercelGenerateResult, type VercelStreamResult, type WrapBAMLOptions, type WrappedBamlFn, __version__, finalizers, flushTraces, getCurrentSpan, getCurrentTrace, reportReplayProgress };
+export { type ActiveSpanContext, type AdaptContext, type AdaptInputsFn, type AllowedEnvVars, BITFAB_PROGRESS_PREFIX, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler as BitfabLangChainCallbackHandler, BitfabLangGraphCallbackHandler, type BitfabLanguageModelMiddleware, BitfabOpenAIAgentHandler, BitfabOpenAITracingProcessor, BitfabVercelAiHandler, type CapturedSpan, type CodeChangeFile, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, type MockOverride, type MockOverrideCtx, type MockStrategy, type MockValue, type NodeMatcher, type ProviderDefinition, ReplayEnvironment, type ReplayEnvironmentSnapshot, type ReplayItem, type ReplayOptions, type ReplayProgress, type ReplayResult, SUPPORTED_PROVIDERS, type SpanLookup, type SpanNodeMeta, type SpanOccurrence, type SpanOptions, type SpanType, type TokenUsage, type TraceResponse, type TracingProcessor, type VercelCallParams, type VercelGenerateResult, type VercelStreamResult, type WrapBAMLOptions, type WrappedBamlFn, __version__, finalizers, flushTraces, getCurrentSpan, getCurrentTrace, reportReplayProgress };

package/dist/index.js

@@ -14,12 +14,12 @@ import {
   flushTraces,
   getCurrentSpan,
   getCurrentTrace
-} from "./chunk-ZBWTCBVQ.js";
+} from "./chunk-2M5AWVVQ.js";
 import {
   BITFAB_PROGRESS_PREFIX,
   BitfabError,
   reportReplayProgress
-} from "./chunk-5E4BUIYA.js";
+} from "./chunk-V3XORTWI.js";
 export {
   BITFAB_PROGRESS_PREFIX,
   Bitfab,

package/dist/node.cjs

@@ -289,6 +289,22 @@ var init_randomUuid = __esm({
   }
 });
 
+// src/mockOverride.ts
+function resolveMockValue(value, ctx) {
+  return typeof value === "function" ? value(ctx) : value;
+}
+function normalizeMockOverrides(mockOverride) {
+  if (mockOverride === void 0) {
+    return [];
+  }
+  return Array.isArray(mockOverride) ? mockOverride : [mockOverride];
+}
+var init_mockOverride = __esm({
+  "src/mockOverride.ts"() {
+    "use strict";
+  }
+});
+
 // src/replayContext.ts
 function getReplayContext() {
   return replayContextStorage?.getStore() ?? null;
@@ -364,6 +380,7 @@ function buildMockTree(rootNode) {
       counters.set(counterKey, index + 1);
       spans.set(`${counterKey}:${index}`, {
         sourceSpanId: node.sourceSpanId,
+        externalSpanId: node.externalSpanId,
         output: node.output,
         outputMeta: node.outputMeta
       });
@@ -377,7 +394,7 @@ function buildMockTree(rootNode) {
   }
   return { spans };
 }
-async function processItem(httpClient, serverItem, fn, testRunId, mockStrategy, environment, adaptInputs) {
+async function processItem(httpClient, serverItem, fn, testRunId, mockStrategy, resolvedOverrides, environment, adaptInputs) {
   const lease = environment ? serverItem.dbBranchLease : void 0;
   let inputs = [];
   let originalOutput;
@@ -396,28 +413,45 @@ async function processItem(httpClient, serverItem, fn, testRunId, mockStrategy,
         sourceSpanId: serverItem.externalSpanId
       });
     }
+    const hasOverrides = resolvedOverrides.length > 0;
+    const needTree = mockStrategy === "all" || mockStrategy === "marked" || hasOverrides;
+    const includeOutputs = mockStrategy === "all";
     let mockTree;
-    if (mockStrategy === "all" || mockStrategy === "marked") {
+    if (needTree) {
       try {
         const treeResponse = await httpClient.getSpanTree(
-          serverItem.externalSpanId
+          serverItem.externalSpanId,
+          { includeOutputs }
         );
         if (treeResponse.root) {
           mockTree = buildMockTree(treeResponse.root);
-        } else if (mockStrategy === "all") {
+        } else if (mockStrategy === "all" || hasOverrides) {
           throw new BitfabError(
-            `Replay mock strategy "all" requires a span tree root for source span ${serverItem.externalSpanId}.`
+            `Replay mock strategy "${mockStrategy}"${hasOverrides ? " with overrides" : ""} requires a span tree root for source span ${serverItem.externalSpanId}.`
           );
         } else {
           mockTree = void 0;
         }
       } catch (e) {
-        if (mockStrategy === "all") {
+        if (mockStrategy === "all" || hasOverrides) {
           throw e;
         }
         mockTree = void 0;
       }
     }
+    const outputCache = /* @__PURE__ */ new Map();
+    const fetchSpanOutput = mockTree && !includeOutputs ? (externalSpanId) => {
+      let pending = outputCache.get(externalSpanId);
+      if (!pending) {
+        pending = httpClient.getExternalSpan(externalSpanId).then(
+          (s) => deserializeOutput(
+            s.rawData?.span_data ?? {}
+          )
+        );
+        outputCache.set(externalSpanId, pending);
+      }
+      return pending;
+    } : void 0;
     const maybePromise = runWithReplayContext(
       {
         testRunId,
@@ -428,6 +462,8 @@ async function processItem(httpClient, serverItem, fn, testRunId, mockStrategy,
         mockTree,
         callCounters: mockTree ? /* @__PURE__ */ new Map() : void 0,
         mockStrategy,
+        mockOverrides: hasOverrides ? resolvedOverrides : void 0,
+        fetchSpanOutput,
         dbBranchLease: lease,
         pendingPersistence
       },
@@ -484,7 +520,7 @@ async function mapWithConcurrency(tasks, maxConcurrency, onSettled) {
   await Promise.all(workers);
   return results;
 }
-async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options) {
+async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, registeredOverrides = []) {
   if (options?.traceIds !== void 0) {
     if (options.traceIds.length === 0) {
       throw new BitfabError("traceIds must contain at least one trace ID.");
@@ -524,6 +560,10 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options) {
   );
   const mockStrategy = options?.mock ?? "marked";
   const maxConcurrency = options?.maxConcurrency ?? 10;
+  const resolvedOverrides = [
+    ...normalizeMockOverrides(options?.mockOverride),
+    ...registeredOverrides
+  ];
   const tasks = serverItems.map(
     (serverItem) => () => processItem(
       httpClient,
@@ -531,6 +571,7 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options) {
       fn,
       testRunId,
       mockStrategy,
+      resolvedOverrides,
       options?.environment,
       options?.adaptInputs
     )
@@ -657,6 +698,7 @@ var init_replay = __esm({
   "src/replay.ts"() {
     "use strict";
     init_errors();
+    init_mockOverride();
     init_randomUuid();
     init_replayContext();
     init_serialize();
@@ -697,7 +739,7 @@ registerAsyncLocalStorageClass(
 );
 
 // src/version.generated.ts
-var __version__ = "0.28.11";
+var __version__ = "0.29.0";
 
 // src/constants.ts
 var DEFAULT_SERVICE_URL = "https://bitfab.ai";
@@ -1126,9 +1168,14 @@ var HttpClient = class {
   /**
    * Fetch the span tree for a root span.
    * Blocking GET request.
+   *
+   * Pass `includeOutputs: false` for a payload-free tree (structure +
+   * `externalSpanId` only), so recorded outputs are fetched lazily per mocked
+   * span instead of all up front. Omit it (default eager) for `mock: "all"`.
    */
-  async getSpanTree(externalSpanId) {
-    const url = `${this.serviceUrl}/api/sdk/replay/spanTree/${externalSpanId}`;
+  async getSpanTree(externalSpanId, options) {
+    const query = options?.includeOutputs === false ? "?includeOutputs=false" : "";
+    const url = `${this.serviceUrl}/api/sdk/replay/spanTree/${externalSpanId}${query}`;
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), 3e4);
     try {
@@ -2714,6 +2761,9 @@ var BitfabLangGraphCallbackHandler = class {
   }
 };
 
+// src/client.ts
+init_mockOverride();
+
 // src/openaiAgentSdk.ts
 var BitfabOpenAIAgentHandler = class {
   constructor(config) {
@@ -3529,6 +3579,12 @@ var Bitfab = class {
   constructor(config) {
     /** Gate the empty-key warning to fire at most once. */
     this.apiKeyWarned = false;
+    /**
+     * Mock overrides registered via {@link Bitfab.registerMockOverride}, applied
+     * to every `replay` on this client (after any per-call `mockOverride`). In
+     * registration order; first matcher wins within this list.
+     */
+    this.mockOverrides = [];
     this.apiKeyConfig = config.apiKey;
     this.serviceUrl = config.serviceUrl ?? DEFAULT_SERVICE_URL;
     this.timeout = config.timeout ?? 12e4;
@@ -4141,24 +4197,77 @@ var Bitfab = class {
           const counterKey = `${traceFunctionKey}:${baseSpanParams.spanName}`;
           const callIndex = counters.get(counterKey) ?? 0;
           counters.set(counterKey, callIndex + 1);
-          const shouldMock = replayCtxForMock.mockStrategy === "all" || replayCtxForMock.mockStrategy === "marked" && options.mockOnReplay === true;
-          if (shouldMock) {
-            const mockKey = `${counterKey}:${callIndex}`;
-            const mockSpan = replayCtxForMock.mockTree.spans.get(mockKey);
-            if (mockSpan) {
-              let output = mockSpan.output;
-              if (mockSpan.outputMeta !== void 0 && mockSpan.outputMeta !== null) {
-                output = deserializeValue({
-                  json: mockSpan.output,
-                  meta: mockSpan.outputMeta
-                });
-              }
+          const mockKey = `${counterKey}:${callIndex}`;
+          const mockSpan = replayCtxForMock.mockTree.spans.get(mockKey);
+          const emitMock = (output) => {
+            void sendSpan({ result: output, mocked: true });
+            if (fnReturnsPromise) {
+              return Promise.resolve(output);
+            }
+            return output;
+          };
+          const emitMockAsync = (pending) => {
+            if (!fnReturnsPromise) {
+              throw new BitfabError(
+                `Cannot mock synchronous span "${traceFunctionKey}" with an asynchronously-resolved value (lazy recorded-output fetch or an async value function). Make the wrapped function async, or use mock: "all" so recorded outputs are fetched eagerly.`
+              );
+            }
+            return (async () => {
+              const output = await pending;
               void sendSpan({ result: output, mocked: true });
-              if (fnReturnsPromise) {
-                return Promise.resolve(output);
-              }
               return output;
+            })();
+          };
+          const resolveRecordedOutput = () => {
+            const hasInlineOutput = mockSpan?.output !== void 0 || mockSpan?.outputMeta !== void 0;
+            if (!hasInlineOutput && replayCtxForMock.fetchSpanOutput && mockSpan?.externalSpanId) {
+              return replayCtxForMock.fetchSpanOutput(mockSpan.externalSpanId);
             }
+            if (!mockSpan) {
+              return Promise.reject(
+                new BitfabError(
+                  `No recorded span to source output for "${traceFunctionKey}".`
+                )
+              );
+            }
+            let output = mockSpan.output;
+            if (mockSpan.outputMeta !== void 0 && mockSpan.outputMeta !== null) {
+              output = deserializeValue({
+                json: mockSpan.output,
+                meta: mockSpan.outputMeta
+              });
+            }
+            return output;
+          };
+          if (replayCtxForMock.mockOverrides?.length) {
+            const nodeMeta = {
+              traceFunctionKey,
+              spanName: baseSpanParams.spanName,
+              type: options.type ?? "custom",
+              originalSpanId: mockSpan?.sourceSpanId
+            };
+            const override = replayCtxForMock.mockOverrides.find(
+              (o) => o.match(nodeMeta)
+            );
+            if (override) {
+              const injected = resolveMockValue(override.value, {
+                node: nodeMeta,
+                inputs: args,
+                getOriginalOutput: () => Promise.resolve(resolveRecordedOutput())
+              });
+              if (injected instanceof Promise) {
+                return emitMockAsync(injected);
+              }
+              return emitMock(injected);
+            }
+          }
+          const shouldMock = replayCtxForMock.mockStrategy === "all" || replayCtxForMock.mockStrategy === "marked" && options.mockOnReplay === true;
+          if (shouldMock && mockSpan) {
+            const recorded = resolveRecordedOutput();
+            if (recorded instanceof Promise) {
+              return emitMockAsync(recorded);
+            }
+            return emitMock(recorded);
           }
         }
         const recordSpan = (result) => {
@@ -4438,26 +4547,14 @@ var Bitfab = class {
       ...params.mocked && { mocked: true }
     });
   }
-  /**
-   * Replay historical traces through a function and create a test run.
-   *
-   * Fetches the last N traces for the given trace function key, re-runs each
-   * through the provided function, and returns comparison data.
-   *
-   * Accepts either a `withSpan`-wrapped function (under the same key) or any
-   * plain callable: plain callables are wrapped internally so each replayed
-   * invocation records a trace tied to the test run. The plain-callable form
-   * is how handler-instrumented workflows (LangGraph/LangChain, Claude Agent
-   * SDK) replay - those record traces under a key with no `withSpan`-wrapped
-   * root in the app.
-   *
-   * @param traceFunctionKey - The trace function key to replay
-   * @param fn - The function to run recorded inputs through
-   * @param options - Optional replay options. When `traceIds` is passed,
-   *   `limit` is ignored (with a warning): an explicit ID list already
-   *   determines how many traces replay.
-   * @returns ReplayResult with items, testRunId, and testRunUrl
-   */
+  registerMockOverride(overrideOrMatch, value) {
+    const override = typeof overrideOrMatch === "function" ? { match: overrideOrMatch, value } : overrideOrMatch;
+    this.mockOverrides.push(override);
+  }
+  /** Remove all overrides registered via {@link registerMockOverride}. */
+  clearMockOverrides() {
+    this.mockOverrides.length = 0;
+  }
   async replay(traceFunctionKey, fn, options) {
     const wrappedKey = fn._bitfabTraceFunctionKey;
     let replayFn = fn;
@@ -4478,7 +4575,8 @@ var Bitfab = class {
       this.serviceUrl,
       traceFunctionKey,
       replayFn,
-      options
+      options,
+      this.mockOverrides
     );
   }
 };