@bitfab/sdk 0.23.3 → 0.24.1

package/dist/{chunk-CG6LVLBK.js → chunk-J4D6PRM4.js}

@@ -5,16 +5,26 @@ import {
   deserializeValue,
   getReplayContext,
   isAsyncStorageInitDone,
+  randomUuid,
   serializeValue,
-  toJsonSafe
-} from "./chunk-EQI6ZJC3.js";
+  toJsonSafe,
+  warnOnce
+} from "./chunk-26MUT4IP.js";
 
 // 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/unrefTimer.ts
+function unrefTimer(timer) {
+  const handle = timer;
+  if (typeof handle.unref === "function") {
+    handle.unref();
+  }
+}
+
 // src/http.ts
 function serializePayloadBody(payload) {
   try {
@@ -60,11 +70,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;
@@ -109,10 +128,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;
@@ -508,7 +537,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;
@@ -533,7 +562,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;
   }
@@ -647,7 +676,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;
@@ -677,10 +706,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,
@@ -821,7 +850,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;
@@ -1508,7 +1537,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
       };
@@ -1803,6 +1832,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",
@@ -2611,7 +2654,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",
@@ -2860,11 +2916,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);
@@ -2940,200 +3011,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", {
@@ -3350,7 +3450,7 @@ var Bitfab = class {
         `Function is wrapped with trace function key '${wrappedKey}' but replay was called with '${traceFunctionKey}'. Pass matching keys, or pass the unwrapped function to replay it under the explicit key.`
       );
     }
-    const { replay: doReplay } = await import("./replay-V6RPJYXZ.js");
+    const { replay: doReplay } = await import("./replay-NMQA7XY6.js");
     return doReplay(
       this.httpClient,
       this.serviceUrl,
@@ -3480,4 +3580,4 @@ export {
   BitfabFunction,
   finalizers
 };
-//# sourceMappingURL=chunk-CG6LVLBK.js.map
+//# sourceMappingURL=chunk-J4D6PRM4.js.map