@bitfab/sdk 0.23.3 → 0.24.1

package/dist/index.cjs

@@ -45,6 +45,54 @@ var init_errors = __esm({
   }
 });
 
+// src/warnOnce.ts
+function warnOnce(key, message) {
+  if (warned.has(key)) {
+    return;
+  }
+  warned.add(key);
+  try {
+    console.warn(`[bitfab] ${message}`);
+  } catch {
+  }
+}
+var warned;
+var init_warnOnce = __esm({
+  "src/warnOnce.ts"() {
+    "use strict";
+    warned = /* @__PURE__ */ new Set();
+  }
+});
+
+// src/randomUuid.ts
+function randomUuid() {
+  const globalCrypto = globalThis.crypto;
+  if (typeof globalCrypto?.randomUUID === "function") {
+    try {
+      return globalCrypto.randomUUID();
+    } catch {
+    }
+  }
+  warnOnce(
+    "crypto-unavailable",
+    "global crypto.randomUUID is unavailable; using a non-cryptographic fallback for trace/span ids. Tracing works normally (ids are correlation-only, not security-sensitive)."
+  );
+  return fallbackUuidV4();
+}
+function fallbackUuidV4() {
+  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (char) => {
+    const rand = Math.random() * 16 | 0;
+    const value = char === "x" ? rand : rand & 3 | 8;
+    return value.toString(16);
+  });
+}
+var init_randomUuid = __esm({
+  "src/randomUuid.ts"() {
+    "use strict";
+    init_warnOnce();
+  }
+});
+
 // src/serialize.ts
 function describeValue(value) {
   try {
@@ -57,6 +105,10 @@ function describeValue(value) {
   return typeof value;
 }
 function unserializableStub(value, reason) {
+  warnOnce(
+    `serialize:${reason.replace(/\d+/g, "N")}`,
+    `a value could not be fully serialized for a span (${reason}); it was replaced with a placeholder. The span still ships, but its captured input/output is incomplete.`
+  );
   let summary;
   try {
     summary = `<unserializable: ${describeValue(value)} (${reason})>`;
@@ -96,7 +148,19 @@ function deserializeValue(serialized) {
   });
 }
 function toJsonSafe(value) {
-  return toJsonSafeInner(value, 0, /* @__PURE__ */ new WeakSet());
+  const safe = toJsonSafeInner(value, 0, /* @__PURE__ */ new WeakSet());
+  try {
+    const size = JSON.stringify(safe)?.length ?? 0;
+    if (size > MAX_FRAMEWORK_SERIALIZED_BYTES) {
+      warnOnce(
+        "toJsonSafe:too_large",
+        `a framework payload exceeded ${MAX_FRAMEWORK_SERIALIZED_BYTES} bytes and was replaced with a placeholder so the span still ships. The captured state for this span is incomplete.`
+      );
+      return `<unserializable: too_large_${size}_bytes>`;
+    }
+  } catch {
+  }
+  return safe;
 }
 function toJsonSafeInner(value, depth, seen) {
   if (value === null || value === void 0) {
@@ -149,12 +213,14 @@ function toJsonSafeInner(value, depth, seen) {
   seen.delete(value);
   return result;
 }
-var import_superjson, MAX_SERIALIZED_BYTES, MAX_SAFE_DEPTH;
+var import_superjson, MAX_SERIALIZED_BYTES, MAX_FRAMEWORK_SERIALIZED_BYTES, MAX_SAFE_DEPTH;
 var init_serialize = __esm({
   "src/serialize.ts"() {
     "use strict";
     import_superjson = __toESM(require("superjson"), 1);
+    init_warnOnce();
     MAX_SERIALIZED_BYTES = 512e3;
+    MAX_FRAMEWORK_SERIALIZED_BYTES = 2e6;
     MAX_SAFE_DEPTH = 6;
   }
 });
@@ -279,7 +345,7 @@ async function processItem(httpClient, serverItem, fn, testRunId, mockStrategy,
   let originalOutput;
   let result;
   let error = null;
-  const replayedTraceId = crypto.randomUUID();
+  const replayedTraceId = randomUuid();
   const pendingPersistence = [];
   try {
     const span = await httpClient.getExternalSpan(serverItem.externalSpanId);
@@ -339,7 +405,10 @@ async function processItem(httpClient, serverItem, fn, testRunId, mockStrategy,
     originalOutput,
     error,
     durationMs: serverItem.durationMs ?? null,
-    tokens: serverItem.tokens ?? null,
+    // Filled in by replay() from the complete-replay response once the
+    // replay traces are persisted and their spans aggregated server-side.
+    // Null here (and on older servers) means "replay tokens not known".
+    tokens: null,
     model: serverItem.model ?? null,
     dbSnapshotRef: serverItem.dbSnapshotRef ?? null
   };
@@ -413,6 +482,7 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options) {
   const resultItems = await mapWithConcurrency(tasks, maxConcurrency);
   const completeResult = await httpClient.completeReplay(testRunId);
   const serverTraceIds = completeResult.traceIds;
+  const replayTokens = completeResult.tokens;
   if (serverTraceIds === void 0) {
     try {
       console.warn(
@@ -435,6 +505,9 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options) {
             missing.push(item.traceId);
           }
         }
+        if (mapped !== void 0) {
+          item.tokens = replayTokens?.[mapped] ?? null;
+        }
         item.traceId = mapped ?? null;
       }
     }
@@ -463,6 +536,7 @@ var init_replay = __esm({
   "src/replay.ts"() {
     "use strict";
     init_errors();
+    init_randomUuid();
     init_replayContext();
     init_serialize();
   }
@@ -492,13 +566,24 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/version.generated.ts
-var __version__ = "0.23.3";
+var __version__ = "0.24.1";
 
 // src/constants.ts
 var DEFAULT_SERVICE_URL = "https://bitfab.ai";
 
 // src/http.ts
 init_errors();
+
+// src/unrefTimer.ts
+function unrefTimer(timer) {
+  const handle = timer;
+  if (typeof handle.unref === "function") {
+    handle.unref();
+  }
+}
+
+// src/http.ts
+init_warnOnce();
 function serializePayloadBody(payload) {
   try {
     return { body: JSON.stringify(payload), dropped: [] };
@@ -543,11 +628,20 @@ function serializePayloadBody(payload) {
           result = `<unserializable: ${className}>`;
         }
       } else {
-        const out = {};
-        for (const [k, v] of Object.entries(obj)) {
-          out[k] = sanitize(v, seen);
+        try {
+          const out = {};
+          for (const [k, v] of Object.entries(obj)) {
+            out[k] = sanitize(v, seen);
+          }
+          result = out;
+        } catch {
+          warnOnce(
+            "payload:field-getter-threw",
+            "a value with a throwing getter/proxy could not be serialized into a span payload; it was replaced with a placeholder. The span still ships with its other fields intact."
+          );
+          dropped.push(className);
+          result = `<unserializable: ${className}>`;
         }
-        result = out;
       }
       seen.delete(obj);
       return result;
@@ -592,10 +686,20 @@ async function flushTraces(timeoutMs = 5e3) {
   if (pendingTracePromises.size === 0) {
     return;
   }
-  await Promise.race([
-    Promise.allSettled(Array.from(pendingTracePromises)),
-    new Promise((resolve) => setTimeout(resolve, timeoutMs))
-  ]);
+  let timer;
+  try {
+    await Promise.race([
+      Promise.allSettled(Array.from(pendingTracePromises)),
+      new Promise((resolve) => {
+        timer = setTimeout(resolve, timeoutMs);
+        unrefTimer(timer);
+      })
+    ]);
+  } finally {
+    if (timer) {
+      clearTimeout(timer);
+    }
+  }
 }
 if (typeof process !== "undefined" && process.versions != null && process.versions.node != null) {
   let isFlushing = false;
@@ -905,6 +1009,7 @@ var HttpClient = class {
 };
 
 // src/claudeAgentSdk.ts
+init_randomUuid();
 init_serialize();
 function nowIso() {
   return (/* @__PURE__ */ new Date()).toISOString();
@@ -992,7 +1097,7 @@ var BitfabClaudeAgentHandler = class {
     if (this.activeContext) {
       this.traceId = this.activeContext.traceId;
     } else {
-      this.traceId = crypto.randomUUID();
+      this.traceId = randomUuid();
     }
     this.traceStartedAt = nowIso();
     return this.traceId;
@@ -1017,7 +1122,7 @@ var BitfabClaudeAgentHandler = class {
     if (this.activeContext !== null) {
       return;
     }
-    const spanId = crypto.randomUUID();
+    const spanId = randomUuid();
     this.startSpan(spanId, this.traceFunctionKey, "agent", this.rootInput, null);
     this.rootSpanId = spanId;
   }
@@ -1131,7 +1236,7 @@ var BitfabClaudeAgentHandler = class {
   // ── hook callbacks ───────────────────────────────────────────
   async preToolUseHook(inputData, toolUseId, _context) {
     try {
-      const sid = inputData.tool_use_id ?? toolUseId ?? crypto.randomUUID();
+      const sid = inputData.tool_use_id ?? toolUseId ?? randomUuid();
       const toolName = inputData.tool_name ?? "tool";
       const toolInput = inputData.tool_input ?? {};
       const agentId = inputData.agent_id;
@@ -1161,10 +1266,10 @@ var BitfabClaudeAgentHandler = class {
   }
   async subagentStartHook(inputData, _toolUseId, _context) {
     try {
-      const agentId = inputData.agent_id ?? crypto.randomUUID();
+      const agentId = inputData.agent_id ?? randomUuid();
       const agentType = inputData.agent_type ?? "subagent";
       const parentId = this.getParentId();
-      const spanId = crypto.randomUUID();
+      const spanId = randomUuid();
       this.activeSubagentSpans.set(agentId, spanId);
       this.startSpan(
         spanId,
@@ -1305,7 +1410,7 @@ var BitfabClaudeAgentHandler = class {
       this.flushLlmTurn();
       this.conversationHistory.push(...this.pendingMessages);
       this.pendingMessages = [];
-      this.currentLlmSpanId = crypto.randomUUID();
+      this.currentLlmSpanId = randomUuid();
       this.currentLlmMessageId = messageId ?? null;
       this.currentLlmContent = [];
       this.currentLlmModel = inner.model ?? null;
@@ -1749,6 +1854,7 @@ function buildSnapshotRef(config, sdkWallClockBeforeFn) {
 }
 
 // src/langgraph.ts
+init_randomUuid();
 init_serialize();
 var LANGSMITH_HIDDEN_TAG = "langsmith:hidden";
 var LANGGRAPH_METADATA_KEYS = [
@@ -1997,7 +2103,7 @@ var BitfabLangGraphCallbackHandler = class {
     } else {
       const activeContext = this.getActiveSpanContext?.() ?? null;
       invocation = {
-        traceId: activeContext ? activeContext.traceId : crypto.randomUUID(),
+        traceId: activeContext ? activeContext.traceId : randomUuid(),
         activeContext,
         rootRunId: runId
       };
@@ -2292,6 +2398,20 @@ var BitfabOpenAIAgentHandler = class {
     this.withSpanFn = config.withSpan;
     this.getActiveSpanContext = config.getActiveSpanContext;
   }
+  /**
+   * Drop-in replacement for the OpenAI Agents SDK's `run()` that records a
+   * replayable root `agent` span.
+   *
+   * The `input` is captured as the root span's input (as a single positional
+   * argument, so `replay(key, fn)` re-feeds it), and the run's `finalOutput`
+   * is recorded as the root output. For streaming runs (`{ stream: true }`),
+   * the result is handed back immediately and the final output is recorded
+   * once the stream completes — first-byte latency is untouched.
+   *
+   * The process-wide tracing processor (`getOpenAiTracingProcessor`) must still
+   * be registered: it captures the LLM/tool/handoff spans that nest beneath
+   * this root.
+   */
   async wrapRun(agent, input, options) {
     const { run } = await importOptionalPeer([
       "@openai",
@@ -2330,6 +2450,7 @@ var BitfabOpenAIAgentHandler = class {
 };
 
 // src/client.ts
+init_randomUuid();
 init_replayContext();
 
 // src/replayEnvironment.ts
@@ -2749,6 +2870,7 @@ var BitfabVercelAiHandler = class {
 };
 
 // src/client.ts
+init_warnOnce();
 var activeTraceStates = /* @__PURE__ */ new Map();
 var pendingSpanPromises = /* @__PURE__ */ new Map();
 var asyncLocalStorage = null;
@@ -3107,7 +3229,20 @@ var Bitfab = class {
         functionVersion.providers,
         this.envVars
       );
-      const resultStr = typeof executionResult.result === "string" ? executionResult.result : JSON.stringify(executionResult.result);
+      let resultStr;
+      if (typeof executionResult.result === "string") {
+        resultStr = executionResult.result;
+      } else {
+        try {
+          resultStr = JSON.stringify(executionResult.result) ?? String(executionResult.result);
+        } catch {
+          warnOnce(
+            "call-result-serialize",
+            "a local execution result could not be JSON-serialized; storing its String() form instead. The call still returns its real value."
+          );
+          resultStr = String(executionResult.result);
+        }
+      }
       this.httpClient.sendInternalTrace(functionVersion.id, {
         result: resultStr,
         source: "typescript-sdk",
@@ -3356,11 +3491,26 @@ var Bitfab = class {
         return await bamlClient[methodName](...args);
       }
       const collector = new CollectorClass("bitfab-baml-tracing");
-      const trackedClient = bamlClient.withOptions({ collector });
-      const trackedMethod = trackedClient[methodName];
-      const result = await trackedMethod.bind(
-        trackedClient
-      )(...args);
+      let trackedClient;
+      let trackedMethod;
+      try {
+        trackedClient = bamlClient.withOptions({ collector });
+        const method2 = trackedClient[methodName];
+        if (typeof method2 !== "function") {
+          throw new BitfabError(
+            "bamlClient.withOptions did not return the wrapped method"
+          );
+        }
+        trackedMethod = method2;
+      } catch {
+        warnOnce(
+          `wrapBAML-setup:${methodName}`,
+          `BAML tracing setup failed for "${methodName}" (incompatible bamlClient or BAML version); calling it untraced. The call still runs; no span is recorded.`
+        );
+        wrappedFn.collector = null;
+        return await bamlClient[methodName](...args);
+      }
+      const result = await trackedMethod.bind(trackedClient)(...args);
       wrappedFn.collector = collector;
       try {
         const prompt = extractPromptFromCollector(collector);
@@ -3436,200 +3586,229 @@ var Bitfab = class {
           () => wrappedFn.apply(this, args)
         );
       }
-      const currentStack = getSpanStack();
-      const parentContext = currentStack[currentStack.length - 1];
-      const replayCtxForTraceId = parentContext ? null : getReplayContext();
-      const traceId = parentContext?.traceId ?? replayCtxForTraceId?.traceId ?? crypto.randomUUID();
-      const spanId = crypto.randomUUID();
-      const parentSpanId = parentContext?.spanId ?? null;
-      const isRootSpan = parentSpanId === null;
-      const newContext = { traceId, spanId, contexts: [] };
-      const newStack = [...currentStack, newContext];
-      const inputs = args;
-      const startedAt = (/* @__PURE__ */ new Date()).toISOString();
-      if (isRootSpan && !activeTraceStates.has(traceId)) {
-        const replayCtxAtRoot = getReplayContext();
-        const dbSnapshotRef = buildSnapshotRef(self.dbSnapshot, startedAt);
-        activeTraceStates.set(traceId, {
+      let newStack;
+      let executeWithContext;
+      let registeredTraceId;
+      try {
+        const currentStack = getSpanStack();
+        const parentContext = currentStack[currentStack.length - 1];
+        const replayCtxForTraceId = parentContext ? null : getReplayContext();
+        const traceId = parentContext?.traceId ?? replayCtxForTraceId?.traceId ?? randomUuid();
+        const spanId = randomUuid();
+        const parentSpanId = parentContext?.spanId ?? null;
+        const isRootSpan = parentSpanId === null;
+        const newContext = { traceId, spanId, contexts: [] };
+        newStack = [...currentStack, newContext];
+        const inputs = args;
+        const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+        if (isRootSpan && !activeTraceStates.has(traceId)) {
+          const replayCtxAtRoot = getReplayContext();
+          const dbSnapshotRef = buildSnapshotRef(self.dbSnapshot, startedAt);
+          activeTraceStates.set(traceId, {
+            traceId,
+            startedAt,
+            contexts: [],
+            ...replayCtxAtRoot?.testRunId && {
+              testRunId: replayCtxAtRoot.testRunId
+            },
+            ...replayCtxAtRoot?.inputSourceTraceId && {
+              inputSourceTraceId: replayCtxAtRoot.inputSourceTraceId
+            },
+            dbSnapshotRef
+          });
+          pendingSpanPromises.set(traceId, []);
+          registeredTraceId = traceId;
+        }
+        const functionName = fn.name !== "" ? fn.name : void 0;
+        const baseSpanParams = {
+          traceFunctionKey,
+          functionName,
+          spanName: options.name ?? functionName ?? traceFunctionKey,
           traceId,
+          spanId,
+          parentSpanId,
+          inputs,
           startedAt,
-          contexts: [],
-          ...replayCtxAtRoot?.testRunId && {
-            testRunId: replayCtxAtRoot.testRunId
-          },
-          ...replayCtxAtRoot?.inputSourceTraceId && {
-            inputSourceTraceId: replayCtxAtRoot.inputSourceTraceId
-          },
-          dbSnapshotRef
-        });
-        pendingSpanPromises.set(traceId, []);
-      }
-      const functionName = fn.name !== "" ? fn.name : void 0;
-      const baseSpanParams = {
-        traceFunctionKey,
-        functionName,
-        spanName: options.name ?? functionName ?? traceFunctionKey,
-        traceId,
-        spanId,
-        parentSpanId,
-        inputs,
-        startedAt,
-        spanType: options.type ?? "custom"
-      };
-      const sendSpan = async (params, spanOpts) => {
-        const replayCtx = getReplayContext();
-        const persistenceCollector = isRootSpan ? replayCtx?.pendingPersistence : void 0;
-        let resolvePersistence;
-        if (persistenceCollector && !spanOpts?.skipPersistenceRegistration) {
-          persistenceCollector.push(
-            new Promise((resolve) => {
-              resolvePersistence = resolve;
-            })
-          );
-        }
-        try {
-          const endedAt = (/* @__PURE__ */ new Date()).toISOString();
-          const spanPromise = self.sendWrapperSpan({
-            ...baseSpanParams,
-            ...params,
-            contexts: newContext.contexts,
-            prompt: newContext.prompt,
-            endedAt,
-            ...replayCtx?.testRunId && { testRunId: replayCtx.testRunId },
-            ...replayCtx?.inputSourceSpanId && {
-              inputSourceSpanId: replayCtx.inputSourceSpanId
-            }
-          });
-          if (isRootSpan) {
-            const pending = pendingSpanPromises.get(traceId) ?? [];
-            pending.push(spanPromise);
-            if (persistenceCollector) {
-              await Promise.allSettled(pending);
-            } else {
-              await Promise.race([
-                Promise.allSettled(pending),
-                new Promise((resolve) => setTimeout(resolve, 5e3))
-              ]);
-            }
-            pendingSpanPromises.delete(traceId);
-            const traceState = activeTraceStates.get(traceId);
-            const completionPromise = self.sendTraceCompletion({
-              traceFunctionKey,
-              traceId,
-              startedAt: traceState?.startedAt ?? startedAt,
+          spanType: options.type ?? "custom"
+        };
+        const sendSpan = async (params, spanOpts) => {
+          const replayCtx = getReplayContext();
+          const persistenceCollector = isRootSpan ? replayCtx?.pendingPersistence : void 0;
+          let resolvePersistence;
+          if (persistenceCollector && !spanOpts?.skipPersistenceRegistration) {
+            persistenceCollector.push(
+              new Promise((resolve) => {
+                resolvePersistence = resolve;
+              })
+            );
+          }
+          try {
+            const endedAt = (/* @__PURE__ */ new Date()).toISOString();
+            const spanPromise = self.sendWrapperSpan({
+              ...baseSpanParams,
+              ...params,
+              contexts: newContext.contexts,
+              prompt: newContext.prompt,
               endedAt,
-              sessionId: traceState?.sessionId,
-              metadata: traceState?.metadata,
-              contexts: traceState?.contexts ?? [],
-              testRunId: traceState?.testRunId,
-              inputSourceTraceId: traceState?.inputSourceTraceId,
-              dbSnapshotRef: traceState?.dbSnapshotRef,
-              // Built AFTER the wrapped fn finished, so `accessed` reflects
-              // whether customer code obtained the branch URL during this
-              // item. Omitted entirely when no lease was attached, so the
-              // server can distinguish "no branch" from "branch ignored".
-              ...replayCtx?.dbBranchLease && {
-                dbSnapshotUsage: {
-                  neonBranchId: replayCtx.dbBranchLease.neonBranchId,
-                  snapshotTimestamp: replayCtx.dbBranchLease.snapshotTimestamp,
-                  sourceTraceId: replayCtx.sourceBitfabTraceId,
-                  accessed: replayCtx.dbSnapshotAccessed === true
-                }
+              ...replayCtx?.testRunId && { testRunId: replayCtx.testRunId },
+              ...replayCtx?.inputSourceSpanId && {
+                inputSourceSpanId: replayCtx.inputSourceSpanId
               }
             });
-            activeTraceStates.delete(traceId);
-            if (persistenceCollector) {
-              await completionPromise;
-            }
-          } else {
-            const pending = pendingSpanPromises.get(traceId);
-            if (pending) {
+            if (isRootSpan) {
+              const pending = pendingSpanPromises.get(traceId) ?? [];
               pending.push(spanPromise);
+              if (persistenceCollector) {
+                await Promise.allSettled(pending);
+              } else {
+                let raceTimer;
+                try {
+                  await Promise.race([
+                    Promise.allSettled(pending),
+                    new Promise((resolve) => {
+                      raceTimer = setTimeout(resolve, 5e3);
+                      unrefTimer(raceTimer);
+                    })
+                  ]);
+                } finally {
+                  if (raceTimer) {
+                    clearTimeout(raceTimer);
+                  }
+                }
+              }
+              pendingSpanPromises.delete(traceId);
+              const traceState = activeTraceStates.get(traceId);
+              const completionPromise = self.sendTraceCompletion({
+                traceFunctionKey,
+                traceId,
+                startedAt: traceState?.startedAt ?? startedAt,
+                endedAt,
+                sessionId: traceState?.sessionId,
+                metadata: traceState?.metadata,
+                contexts: traceState?.contexts ?? [],
+                testRunId: traceState?.testRunId,
+                inputSourceTraceId: traceState?.inputSourceTraceId,
+                dbSnapshotRef: traceState?.dbSnapshotRef,
+                // Built AFTER the wrapped fn finished, so `accessed` reflects
+                // whether customer code obtained the branch URL during this
+                // item. Omitted entirely when no lease was attached, so the
+                // server can distinguish "no branch" from "branch ignored".
+                ...replayCtx?.dbBranchLease && {
+                  dbSnapshotUsage: {
+                    neonBranchId: replayCtx.dbBranchLease.neonBranchId,
+                    snapshotTimestamp: replayCtx.dbBranchLease.snapshotTimestamp,
+                    sourceTraceId: replayCtx.sourceBitfabTraceId,
+                    accessed: replayCtx.dbSnapshotAccessed === true
+                  }
+                }
+              });
+              activeTraceStates.delete(traceId);
+              if (persistenceCollector) {
+                await completionPromise;
+              }
             } else {
-              pendingSpanPromises.set(traceId, [spanPromise]);
+              const pending = pendingSpanPromises.get(traceId);
+              if (pending) {
+                pending.push(spanPromise);
+              } else {
+                pendingSpanPromises.set(traceId, [spanPromise]);
+              }
             }
+          } catch {
+          } finally {
+            resolvePersistence?.();
           }
-        } catch {
-        } finally {
-          resolvePersistence?.();
-        }
-      };
-      const replayCtxForMock = getReplayContext();
-      if (replayCtxForMock?.mockTree && !isRootSpan) {
-        const counters = replayCtxForMock.callCounters;
-        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
-              });
-            }
-            void sendSpan({ result: output });
-            if (fnReturnsPromise) {
-              return Promise.resolve(output);
+        };
+        const replayCtxForMock = getReplayContext();
+        if (replayCtxForMock?.mockTree && !isRootSpan) {
+          const counters = replayCtxForMock.callCounters;
+          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
+                });
+              }
+              void sendSpan({ result: output });
+              if (fnReturnsPromise) {
+                return Promise.resolve(output);
+              }
+              return output;
             }
-            return output;
           }
         }
-      }
-      const recordSpan = (result) => {
-        if (options.finalize) {
-          const replayCtx = getReplayContext();
-          const persistenceCollector = isRootSpan ? replayCtx?.pendingPersistence : void 0;
-          let resolvePersistence;
-          if (persistenceCollector) {
-            persistenceCollector.push(
-              new Promise((resolve) => {
-                resolvePersistence = resolve;
-              })
-            );
+        const recordSpan = (result) => {
+          if (options.finalize) {
+            const replayCtx = getReplayContext();
+            const persistenceCollector = isRootSpan ? replayCtx?.pendingPersistence : void 0;
+            let resolvePersistence;
+            if (persistenceCollector) {
+              persistenceCollector.push(
+                new Promise((resolve) => {
+                  resolvePersistence = resolve;
+                })
+              );
+            }
+            void Promise.resolve().then(() => options.finalize(result)).then(
+              (output) => sendSpan(
+                { result: output },
+                { skipPersistenceRegistration: true }
+              )
+            ).catch(
+              (error) => sendSpan(
+                {
+                  result: void 0,
+                  error: error instanceof Error ? `finalize failed: ${error.message}` : `finalize failed: ${String(error)}`
+                },
+                { skipPersistenceRegistration: true }
+              )
+            ).finally(() => resolvePersistence?.());
+          } else {
+            void sendSpan({ result });
           }
-          void Promise.resolve().then(() => options.finalize(result)).then(
-            (output) => sendSpan(
-              { result: output },
-              { skipPersistenceRegistration: true }
-            )
-          ).catch(
-            (error) => sendSpan(
-              {
+        };
+        executeWithContext = () => {
+          const result = fn(...args);
+          if (result instanceof Promise) {
+            return result.then((resolvedResult) => {
+              recordSpan(resolvedResult);
+              return resolvedResult;
+            }).catch((error) => {
+              void sendSpan({
                 result: void 0,
-                error: error instanceof Error ? `finalize failed: ${error.message}` : `finalize failed: ${String(error)}`
-              },
-              { skipPersistenceRegistration: true }
-            )
-          ).finally(() => resolvePersistence?.());
-        } else {
-          void sendSpan({ result });
-        }
-      };
-      const executeWithContext = () => {
-        const result = fn(...args);
-        if (result instanceof Promise) {
-          return result.then((resolvedResult) => {
-            recordSpan(resolvedResult);
-            return resolvedResult;
-          }).catch((error) => {
-            void sendSpan({
-              result: void 0,
-              error: error instanceof Error ? error.message : String(error)
+                error: error instanceof Error ? error.message : String(error)
+              });
+              throw error;
             });
-            throw error;
-          });
+          }
+          if (isAsyncGenerator(result)) {
+            return wrapAsyncGenerator(result, newStack, sendSpan);
+          }
+          recordSpan(result);
+          return result;
+        };
+      } catch (setupError) {
+        if (registeredTraceId) {
+          activeTraceStates.delete(registeredTraceId);
+          pendingSpanPromises.delete(registeredTraceId);
         }
-        if (isAsyncGenerator(result)) {
-          return wrapAsyncGenerator(result, newStack, sendSpan);
+        if (getReplayContext()) {
+          throw setupError;
         }
-        recordSpan(result);
-        return result;
-      };
+        warnOnce(
+          `withSpan-setup:${traceFunctionKey}`,
+          `tracing setup failed for "${traceFunctionKey}"; running it untraced. The function still runs and returns normally; no span is recorded.`
+        );
+        return fn(...args);
+      }
       return runWithSpanStack(newStack, executeWithContext);
     };
     Object.defineProperty(wrappedFn, "_bitfabTraceFunctionKey", {