bitfab 0.28.10 → 0.29.0

package/dist/node.cjs

@@ -298,6 +298,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;
@@ -373,6 +389,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
       });
@@ -386,7 +403,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;
@@ -405,28 +422,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,
@@ -437,6 +471,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
       },
@@ -493,7 +529,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.");
@@ -533,6 +569,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,
@@ -540,6 +580,7 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options) {
       fn,
       testRunId,
       mockStrategy,
+      resolvedOverrides,
       options?.environment,
       options?.adaptInputs
     )
@@ -666,6 +707,7 @@ var init_replay = __esm({
   "src/replay.ts"() {
     "use strict";
     init_errors();
+    init_mockOverride();
     init_randomUuid();
     init_replayContext();
     init_serialize();
@@ -706,7 +748,7 @@ registerAsyncLocalStorageClass(
 );
 
 // src/version.generated.ts
-var __version__ = "0.28.10";
+var __version__ = "0.29.0";
 
 // src/constants.ts
 var DEFAULT_SERVICE_URL = "https://bitfab.ai";
@@ -946,6 +988,50 @@ var HttpClient = class {
   async lookupFunction(name) {
     return this.request("/api/sdk/functions/lookup", { name });
   }
+  async getTraceSpan(traceId, lookup) {
+    const searchParams = new URLSearchParams();
+    if (lookup.id !== void 0) {
+      searchParams.set("id", lookup.id);
+    } else {
+      searchParams.set("name", lookup.name);
+      searchParams.set("occurrence", String(lookup.occurrence ?? "last"));
+    }
+    const endpoint = `/api/sdk/traces/${encodeURIComponent(traceId)}/span?${searchParams.toString()}`;
+    const response = await this.get(endpoint);
+    return response.span;
+  }
+  async get(endpoint) {
+    const url = `${this.serviceUrl}${endpoint}`;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const response = await fetch(url, {
+        method: "GET",
+        headers: { Authorization: `Bearer ${this.resolveApiKey() ?? ""}` },
+        signal: controller.signal
+      });
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new BitfabError(
+          `HTTP ${response.status}: ${errorText.slice(0, 500)}`
+        );
+      }
+      return await response.json();
+    } catch (error) {
+      if (error instanceof BitfabError) {
+        throw error;
+      }
+      if (error instanceof Error) {
+        if (error.name === "AbortError") {
+          throw new BitfabError(`Request timed out after ${this.timeout}ms`);
+        }
+        throw new BitfabError(error.message);
+      }
+      throw new BitfabError("Unknown error occurred");
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
   /**
    * Send an internal trace (from BAML execution).
    * Fire-and-forget with awaitOnExit - doesn't block the caller.
@@ -1002,12 +1088,12 @@ var HttpClient = class {
     });
   }
   /**
-   * Partial update of an existing external trace identified by sourceTraceId.
+   * Partial update of an existing trace identified by its Bitfab trace ID.
    * Used by the detached `client.getTrace(id)` handle. Fire-and-forget;
    * returns a tracked promise that callers may optionally await.
    */
-  patchTrace(sourceTraceId, payload) {
-    const endpoint = `/api/sdk/externalTraces/${encodeURIComponent(sourceTraceId)}`;
+  patchTrace(traceId, payload) {
+    const endpoint = `/api/sdk/traces/${encodeURIComponent(traceId)}`;
     return awaitOnExit(
       this.request(endpoint, payload, { method: "PATCH" })
     ).catch((error) => {
@@ -1091,9 +1177,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 {
@@ -1345,6 +1436,7 @@ var BitfabClaudeAgentHandler = class {
     const traceId = this.ensureTrace();
     const { safe: safeInput, dropped: inputDropped } = toJsonSafeReport(inputData);
     const spanInfo = {
+      id: randomUuid(),
       spanId,
       traceId,
       parentId: parentId ?? null,
@@ -1408,6 +1500,8 @@ var BitfabClaudeAgentHandler = class {
       rawSpan.parent_id = spanInfo.parentId;
     }
     const payload = {
+      id: spanInfo.id,
+      traceId: spanInfo.traceId,
       type: "sdk-function",
       source: "typescript-sdk-claude-agent-sdk",
       traceFunctionKey: this.traceFunctionKey,
@@ -1437,6 +1531,7 @@ var BitfabClaudeAgentHandler = class {
       externalTrace.metadata = metadata;
     }
     const traceData = {
+      id: traceId,
       type: "sdk-function",
       source: "typescript-sdk-claude-agent-sdk",
       traceFunctionKey: this.traceFunctionKey,
@@ -1705,6 +1800,7 @@ var BitfabClaudeAgentHandler = class {
     }
     Object.assign(llmContext, this.currentLlmUsage);
     const spanInfo = {
+      id: randomUuid(),
       spanId,
       traceId,
       parentId,
@@ -2351,6 +2447,7 @@ var BitfabLangGraphCallbackHandler = class {
     const contexts = Object.keys(lgMetadata).length > 0 ? [lgMetadata] : [];
     const { safe: safeInput, dropped: inputDropped } = toJsonSafeReport(inputData);
     const spanInfo = {
+      id: randomUuid(),
       spanId: runId,
       traceId: invocation.traceId,
       rootRunId: invocation.rootRunId,
@@ -2429,6 +2526,8 @@ var BitfabLangGraphCallbackHandler = class {
       rawSpan.parent_id = spanInfo.parentId;
     }
     const payload = {
+      id: spanInfo.id,
+      traceId: spanInfo.traceId,
       type: "sdk-function",
       source: "typescript-sdk-langgraph",
       traceFunctionKey: this.traceFunctionKey,
@@ -2444,6 +2543,7 @@ var BitfabLangGraphCallbackHandler = class {
   sendTraceCompletion(rootSpan, activeContext) {
     const completed = activeContext === null;
     const traceData = {
+      id: rootSpan.traceId,
       type: "sdk-function",
       source: "typescript-sdk-langgraph",
       traceFunctionKey: this.traceFunctionKey,
@@ -2463,6 +2563,7 @@ var BitfabLangGraphCallbackHandler = class {
   }
   sendTraceStart(rootSpan) {
     const traceData = {
+      id: rootSpan.traceId,
       type: "sdk-function",
       source: "typescript-sdk-langgraph",
       traceFunctionKey: this.traceFunctionKey,
@@ -2669,6 +2770,9 @@ var BitfabLangGraphCallbackHandler = class {
   }
 };
 
+// src/client.ts
+init_mockOverride();
+
 // src/openaiAgentSdk.ts
 var BitfabOpenAIAgentHandler = class {
   constructor(config) {
@@ -2821,6 +2925,7 @@ var ReplayEnvironment = class {
 init_serialize();
 
 // src/tracing.ts
+init_randomUuid();
 var BitfabOpenAITracingProcessor = class {
   /**
    * Initialize the tracing processor.
@@ -2830,6 +2935,7 @@ var BitfabOpenAITracingProcessor = class {
   constructor(config) {
     this.activeTraces = {};
     this.activeSpanMappings = {};
+    this.canonicalTraceIds = {};
     this.httpClient = new HttpClient({
       apiKey: config.apiKey,
       serviceUrl: config.serviceUrl ?? DEFAULT_SERVICE_URL,
@@ -2837,6 +2943,15 @@ var BitfabOpenAITracingProcessor = class {
     });
     this.getActiveSpanContext = config.getActiveSpanContext ?? null;
   }
+  getCanonicalTraceId(sourceTraceId) {
+    const existing = this.canonicalTraceIds[sourceTraceId];
+    if (existing) {
+      return existing;
+    }
+    const created = randomUuid();
+    this.canonicalTraceIds[sourceTraceId] = created;
+    return created;
+  }
   /**
    * Called when a trace is started.
    * If there's an active withSpan context, the trace ID is remapped to the
@@ -2848,7 +2963,12 @@ var BitfabOpenAITracingProcessor = class {
     if (activeContext) {
       this.activeSpanMappings[trace.traceId] = activeContext;
     }
-    this.sendTrace(trace, activeContext ? { id: activeContext.traceId } : {});
+    const canonicalTraceId = activeContext?.traceId ?? this.getCanonicalTraceId(trace.traceId);
+    this.canonicalTraceIds[trace.traceId] = canonicalTraceId;
+    this.sendTrace(trace, {
+      id: canonicalTraceId,
+      sourceTraceId: activeContext?.traceId
+    });
   }
   /**
    * Called when a trace is ended.
@@ -2857,11 +2977,13 @@ var BitfabOpenAITracingProcessor = class {
    */
   async onTraceEnd(trace) {
     const mapping = this.activeSpanMappings[trace.traceId];
-    this.sendTrace(
-      trace,
-      mapping ? { id: mapping.traceId } : { completed: true }
-    );
+    this.sendTrace(trace, {
+      completed: mapping === void 0,
+      id: mapping?.traceId ?? this.getCanonicalTraceId(trace.traceId),
+      sourceTraceId: mapping?.traceId
+    });
     delete this.activeSpanMappings[trace.traceId];
+    delete this.canonicalTraceIds[trace.traceId];
     delete this.activeTraces[trace.traceId];
   }
   /**
@@ -2891,22 +3013,25 @@ var BitfabOpenAITracingProcessor = class {
   async shutdown(_timeout) {
     this.activeTraces = {};
     this.activeSpanMappings = {};
+    this.canonicalTraceIds = {};
   }
   /**
    * Send trace to Bitfab API (fire-and-forget).
    * When traceIdOverride is provided, the trace ID is remapped to link
    * the OpenAI trace into an outer withSpan trace.
    */
-  sendTrace(trace, overrides = {}) {
+  sendTrace(trace, options = {}) {
     try {
-      const { completed, ...traceOverrides } = overrides;
       const traceData = trace.toJSON();
-      Object.assign(traceData, traceOverrides);
+      if (options.sourceTraceId) {
+        traceData.id = options.sourceTraceId;
+      }
       this.httpClient.sendExternalTrace({
+        ...options.id && { id: options.id },
         type: "openai",
         source: "typescript-sdk-openai-tracing",
         externalTrace: traceData,
-        completed: completed ?? false
+        completed: options.completed ?? false
       });
     } catch {
     }
@@ -2992,6 +3117,7 @@ var BitfabOpenAITracingProcessor = class {
    */
   buildSpanPayload(serializedSpan, errors) {
     const payload = {
+      id: randomUuid(),
       type: "openai",
       source: "typescript-sdk-openai-tracing",
       sourceTraceId: serializedSpan.trace_id ?? "unknown",
@@ -3014,6 +3140,10 @@ var BitfabOpenAITracingProcessor = class {
     this.extractSpanInputResponse(span, serializedSpan, errors);
     this.applySpanOverrides(serializedSpan, span.traceId ?? "");
     const payload = this.buildSpanPayload(serializedSpan, errors);
+    const canonicalTraceId = span.traceId ? this.getCanonicalTraceId(span.traceId) : void 0;
+    if (canonicalTraceId) {
+      payload.traceId = canonicalTraceId;
+    }
     this.httpClient.sendExternalSpan(payload);
   }
 };
@@ -3330,24 +3460,19 @@ function extractContextFromCollector(collector) {
     return null;
   }
 }
-var TRACE_ID_PATTERN = /^[a-zA-Z0-9_\-.:]+$/;
-var TRACE_ID_MAX_LENGTH = 256;
+var UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 function validateTraceId(traceId) {
-  if (typeof traceId !== "string" || traceId.length === 0) {
-    throw new BitfabError("traceId is required and must be a non-empty string");
-  }
-  if (traceId.length > TRACE_ID_MAX_LENGTH) {
-    throw new BitfabError(
-      `traceId must be ${TRACE_ID_MAX_LENGTH} characters or fewer`
-    );
+  if (typeof traceId !== "string" || !UUID_PATTERN.test(traceId)) {
+    throw new BitfabError("traceId must be a valid Bitfab trace ID");
   }
-  if (!TRACE_ID_PATTERN.test(traceId)) {
-    throw new BitfabError(
-      `traceId may only contain letters, digits, "_", "-", ".", ":"`
-    );
+}
+function validateSpanId(id) {
+  if (typeof id !== "string" || !UUID_PATTERN.test(id)) {
+    throw new BitfabError("id must be a valid Bitfab span ID");
   }
 }
 var noOpSpan = {
+  id: "",
   traceId: "",
   addContext() {
   },
@@ -3371,6 +3496,7 @@ function getCurrentSpan() {
     return noOpSpan;
   }
   return {
+    id: current.spanId,
     traceId: current.traceId,
     addContext(context) {
       try {
@@ -3462,6 +3588,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;
@@ -4074,24 +4206,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) => {
@@ -4167,20 +4352,19 @@ var Bitfab = class {
   }
   /**
    * Get a detached handle to a previously-created trace, looked up by the
-   * caller-supplied id (the same id passed at trace creation).
+   * canonical Bitfab trace ID.
    *
    * The returned handle is not tied to AsyncLocalStorage - each method sends
    * to the server immediately. Useful for adding context to a trace from a
    * different process or thread than the one that created it.
    *
-   * Throws synchronously if `traceId` is malformed (empty, too long, or
-   * contains characters outside `[a-zA-Z0-9_\-.:]`). Server returns 404 if
-   * no trace exists with that id in the org; the failure surfaces as a
+   * Throws synchronously if `traceId` is not a valid Bitfab trace ID. The
+   * server returns 404 if no trace exists with that ID in the org; the failure surfaces as a
    * logged warning (fire-and-forget) or via the awaited promise.
    *
    * Example:
    * ```typescript
-   * const trace = client.getTrace("order_abc_123");
+   * const trace = client.getTrace(traceId);
    * await trace.addContext({ refund_status: "approved" });
    * await trace.setMetadata({ region: "us-west" });
    * ```
@@ -4220,6 +4404,33 @@ var Bitfab = class {
       }
     };
   }
+  /**
+   * Fetch one persisted span from a trace without loading the full trace.
+   * Name lookups return the last matching span by default. Pass `occurrence`
+   * as `"first"` or a zero-based index to select a different match.
+   */
+  async getTraceSpan(traceId, lookup) {
+    validateTraceId(traceId);
+    const hasId = lookup.id !== void 0;
+    const hasName = lookup.name !== void 0;
+    if (hasId === hasName) {
+      throw new BitfabError("Provide exactly one of id or name");
+    }
+    if (hasId) {
+      validateSpanId(lookup.id);
+    } else {
+      if (lookup.name.length === 0) {
+        throw new BitfabError("name must be a non-empty string");
+      }
+      const occurrence = lookup.occurrence ?? "last";
+      if (occurrence !== "first" && occurrence !== "last" && (!Number.isInteger(occurrence) || occurrence < 0)) {
+        throw new BitfabError(
+          'occurrence must be "first", "last", or a non-negative integer'
+        );
+      }
+    }
+    return this.httpClient.getTraceSpan(traceId, lookup);
+  }
   /**
    * Get a function wrapper for a specific trace function key.
    *
@@ -4278,6 +4489,7 @@ var Bitfab = class {
       };
     }
     return this.httpClient.sendExternalTrace({
+      id: params.traceId,
       type: "sdk-function",
       source: "typescript-sdk-function",
       traceFunctionKey: params.traceFunctionKey,
@@ -4333,6 +4545,8 @@ var Bitfab = class {
       externalSpan.input_source_span_id = params.inputSourceSpanId;
     }
     return this.httpClient.sendExternalSpan({
+      id: params.spanId,
+      traceId: params.traceId,
       type: "sdk-function",
       source: "typescript-sdk-function",
       sourceTraceId: params.traceId,
@@ -4342,26 +4556,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;
@@ -4382,7 +4584,8 @@ var Bitfab = class {
       this.serviceUrl,
       traceFunctionKey,
       replayFn,
-      options
+      options,
+      this.mockOverrides
     );
   }
 };