@bitfab/sdk 0.43.1 → 0.44.1

package/dist/index.cjs

@@ -42,7 +42,7 @@ var __version__, __packageName__;
 var init_version_generated = __esm({
   "src/version.generated.ts"() {
     "use strict";
-    __version__ = "0.43.1";
+    __version__ = "0.44.1";
     __packageName__ = "@bitfab/sdk";
   }
 });
@@ -164,7 +164,7 @@ var init_compress = __esm({
 });
 
 // src/errors.ts
-var BitfabError;
+var BitfabError, MixedTracingError;
 var init_errors = __esm({
   "src/errors.ts"() {
     "use strict";
@@ -177,6 +177,12 @@ var init_errors = __esm({
         this.name = "BitfabError";
       }
     };
+    MixedTracingError = class extends Error {
+      constructor(message) {
+        super(message);
+        this.name = "MixedTracingError";
+      }
+    };
   }
 });
 
@@ -2713,7 +2719,9 @@ async function processItem(httpClient, serverItem, fn, testRunId, mockStrategy,
         tokens: null,
         model: serverItem.originalModel ?? serverItem.model ?? null,
         dbSnapshotRef: dbSnapshotRef ?? null,
-        dbBranchTimings: dbBranchTimings ?? null
+        dbBranchTimings: dbBranchTimings ?? null,
+        traceOutline: null,
+        originalTraceOutline: null
       };
     }
     try {
@@ -2797,7 +2805,9 @@ async function processItem(httpClient, serverItem, fn, testRunId, mockStrategy,
     tokens: null,
     model: originalModel,
     dbSnapshotRef: dbSnapshotRef ?? null,
-    dbBranchTimings: dbBranchTimings ?? null
+    dbBranchTimings: dbBranchTimings ?? null,
+    traceOutline: null,
+    originalTraceOutline: null
   };
 }
 async function waitForReplayPersistence(httpClient, testRunId, replayedTraceIds) {
@@ -3052,7 +3062,9 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
             tokens: item.tokens,
             model: item.model,
             dbSnapshotRef: item.dbSnapshotRef,
-            dbBranchTimings: item.dbBranchTimings
+            dbBranchTimings: item.dbBranchTimings,
+            traceOutline: item.traceOutline,
+            originalTraceOutline: item.originalTraceOutline
           }
         });
       } catch {
@@ -3132,7 +3144,9 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
       }
       if (mapped !== void 0) {
         item.tokens = replayTokens?.[mapped] ?? null;
+        item.traceOutline = completeResult.traceOutlines?.[mapped] ?? null;
       }
+      item.originalTraceOutline = completeResult.originalTraceOutlines?.[item.originalTraceId] ?? null;
     }
     if (completedCount > 0 && missing.length === completedCount) {
       const serverCount = completeResult.traceCount !== void 0 ? ` The server persisted ${completeResult.traceCount} trace(s) for this run.` : "";
@@ -3255,6 +3269,7 @@ __export(index_exports, {
   DatasetsClient: () => DatasetsClient,
   DbBranchReplayError: () => DbBranchReplayError,
   HttpClient: () => HttpClient,
+  MixedTracingError: () => MixedTracingError,
   NO_MOCK_OVERRIDE: () => NO_MOCK_OVERRIDE,
   ReplayError: () => ReplayError,
   SUPPORTED_PROVIDERS: () => SUPPORTED_PROVIDERS,
@@ -4328,6 +4343,50 @@ async function runFunctionWithBaml(bamlSource, inputs, providers, envVars) {
   };
 }
 
+// src/captureSurface.ts
+init_errors();
+var DEFAULT_SURFACE = "opt-in";
+var SURFACE_API = {
+  "opt-in": "withSpan()",
+  "opt-out": "withTrace()"
+};
+var MIXED_SURFACE_REMEDY = {
+  "opt-in": "Inside a withTrace/trace subtree, configure a discovered call with node()/withNode() instead, or trace this workflow with withSpan() only.",
+  "opt-out": "Wrap the caller with withTrace()/trace() as well, or wrap this function with withSpan()."
+};
+function resolveSurface(requested, parentSurface) {
+  if (requested === "neutral") {
+    return void 0;
+  }
+  if (requested === "inherit") {
+    return parentSurface ?? DEFAULT_SURFACE;
+  }
+  return requested;
+}
+function mixedTracingError(enteredApi, entered, enclosing, traceFunctionKey) {
+  const subject = traceFunctionKey === void 0 ? "" : ` for "${traceFunctionKey}"`;
+  return new MixedTracingError(
+    `opt-in and opt-out tracing can't be mixed in one call stack: ${enteredApi} (${entered})${subject} was entered inside a ${SURFACE_API[enclosing]} call (${enclosing}). ${MIXED_SURFACE_REMEDY[entered]}`
+  );
+}
+function assertSurfacesCompatible(requested, resolved, parentSurface, traceFunctionKey) {
+  if (requested === "inherit" || requested === "neutral") {
+    return;
+  }
+  if (resolved === void 0 || parentSurface === void 0) {
+    return;
+  }
+  if (parentSurface === resolved) {
+    return;
+  }
+  throw mixedTracingError(
+    SURFACE_API[resolved],
+    resolved,
+    parentSurface,
+    traceFunctionKey
+  );
+}
+
 // src/client.ts
 init_constants();
 
@@ -4474,6 +4533,7 @@ function buildSnapshotRef(config, sdkWallClockBeforeFn) {
 }
 
 // src/client.ts
+init_errors();
 init_http();
 
 // src/langgraph.ts
@@ -5863,18 +5923,6 @@ var BitfabVercelAiHandler = class {
 
 // src/client.ts
 init_warnOnce();
-var MIXED_SURFACE_REMEDY = {
-  "opt-in": "Inside a withTrace/trace subtree, configure a discovered call with node()/withNode() instead, or trace this workflow with withSpan() only.",
-  "opt-out": "Wrap the caller with withTrace()/trace() as well, or wrap this function with withSpan()."
-};
-function warnMixedTracingSurfaces(traceFunctionKey, entered, enclosing) {
-  const enteredApi = entered === "opt-in" ? "withSpan()" : "withTrace()";
-  const enclosingApi = enclosing === "opt-in" ? "withSpan()" : "withTrace()";
-  warnOnce(
-    `mixed-tracing-surface:${traceFunctionKey}:${entered}`,
-    `opt-in and opt-out tracing are mixed in one call stack: ${enteredApi} (${entered}) for "${traceFunctionKey}" was entered inside a ${enclosingApi} call (${enclosing}). Both are recorded, and the spans nest as written. ${MIXED_SURFACE_REMEDY[entered]}`
-  );
-}
 var activeTraceStates = /* @__PURE__ */ new Map();
 var asyncLocalStorage = null;
 var SPAN_CONTEXT_STORAGE_SYMBOL = /* @__PURE__ */ Symbol.for("bitfab.spanContextStorage");
@@ -5904,6 +5952,10 @@ function getSpanStack() {
   }
   return browserSpanStack;
 }
+function enclosingSurface() {
+  const stack = getSpanStack();
+  return stack[stack.length - 1]?.surface;
+}
 function runWithSpanStack(stack, fn) {
   if (asyncLocalStorage) {
     return asyncLocalStorage.run(stack, fn);
@@ -6390,6 +6442,9 @@ var Bitfab = class {
     const nodeConfiguration = { ...configuration, functionName };
     return function(...args) {
       if (!__bitfabAutoTraceActive()) {
+        if (enclosingSurface() === "opt-in") {
+          throw mixedTracingError("node()", "opt-out", "opt-in");
+        }
         return fn.apply(this, args);
       }
       return runWithAutoTraceNodeConfiguration(
@@ -7091,20 +7146,19 @@ var Bitfab = class {
         const spanId = randomUuid();
         const parentSpanId = parentContext?.spanId ?? null;
         const isRootSpan = parentSpanId === null;
-        const requestedSurface = options.surface ?? "opt-in";
-        const surface = requestedSurface === "inherit" ? parentContext?.surface ?? "opt-in" : requestedSurface;
-        if (requestedSurface !== "inherit" && parentContext?.surface !== void 0 && parentContext.surface !== surface) {
-          warnMixedTracingSurfaces(
-            traceFunctionKey,
-            surface,
-            parentContext.surface
-          );
-        }
+        const requestedSurface = options.surface ?? DEFAULT_SURFACE;
+        const surface = resolveSurface(requestedSurface, parentContext?.surface);
+        assertSurfacesCompatible(
+          requestedSurface,
+          surface,
+          parentContext?.surface,
+          traceFunctionKey
+        );
         const newContext = {
           traceId,
           spanId,
           contexts: [],
-          surface
+          ...surface !== void 0 && { surface }
         };
         newStack = [...currentStack, newContext];
         const inputs = args;
@@ -7387,6 +7441,9 @@ var Bitfab = class {
         if (registeredTraceId) {
           activeTraceStates.delete(registeredTraceId);
         }
+        if (setupError instanceof MixedTracingError) {
+          throw setupError;
+        }
         if (getReplayContext() || inSeedScope()) {
           throw setupError;
         }
@@ -7786,9 +7843,14 @@ var Bitfab = class {
     const wrappedKey = fn._bitfabTraceFunctionKey;
     let target = fn;
     if (wrappedKey === void 0) {
+      const seedRootOptions = {
+        name: traceFunctionKey,
+        type: "agent",
+        surface: "neutral"
+      };
       target = this.withSpan(
         traceFunctionKey,
-        { name: traceFunctionKey, type: "agent" },
+        seedRootOptions,
         fn
       );
     } else if (wrappedKey !== traceFunctionKey) {
@@ -7830,11 +7892,12 @@ var Bitfab = class {
     const wrappedKey = fn._bitfabTraceFunctionKey;
     let replayFn = fn;
     if (wrappedKey === void 0) {
-      replayFn = this.withSpan(
-        traceFunctionKey,
-        { name: traceFunctionKey, type: "agent" },
-        fn
-      );
+      const replayRootOptions = {
+        name: traceFunctionKey,
+        type: "agent",
+        surface: "neutral"
+      };
+      replayFn = this.withSpan(traceFunctionKey, replayRootOptions, fn);
     } else if (wrappedKey !== traceFunctionKey) {
       throw new BitfabError(
         `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.`
@@ -8147,6 +8210,7 @@ function resolveTraceFunctionKey(registration) {
   DatasetsClient,
   DbBranchReplayError,
   HttpClient,
+  MixedTracingError,
   NO_MOCK_OVERRIDE,
   ReplayError,
   SUPPORTED_PROVIDERS,