@bitfab/sdk 0.42.0 → 0.43.0

package/dist/{chunk-BC5OYWAM.js → chunk-5BBJ5BQD.js}

@@ -14,14 +14,14 @@ import {
   serializeValue,
   toJsonSafe,
   toJsonSafeReport
-} from "./chunk-BG3A5HNC.js";
+} from "./chunk-BXBRVWWW.js";
 import {
   BitfabError,
   DEFAULT_SERVICE_URL,
   HttpClient,
   getReplayContext,
   warnOnce
-} from "./chunk-UGFTBSGS.js";
+} from "./chunk-6EM2S5H5.js";
 import {
   __privateAdd,
   __privateGet,
@@ -1902,7 +1902,8 @@ var BitfabLangGraphIntegration = class {
                 type: "function",
                 captureWhen: "nested",
                 mockOnReplay: shouldMock,
-                finalize: finalizeToolResult
+                finalize: finalizeToolResult,
+                surface: "inherit"
               },
               async (_args) => await originalInvoke(input, ...rest)
             );
@@ -1945,7 +1946,7 @@ var BitfabLangGraphIntegration = class {
   wrapInvoke(fn) {
     return this.client.withSpan(
       this.traceFunctionKey,
-      { name: this.traceFunctionKey, type: "agent" },
+      { name: this.traceFunctionKey, type: "agent", surface: "inherit" },
       fn
     );
   }
@@ -1995,7 +1996,11 @@ var BitfabOpenAIAgentHandler = class {
       }
       return res?.finalOutput;
     };
-    const options_ = { type: "agent", finalize };
+    const options_ = {
+      type: "agent",
+      finalize,
+      surface: "inherit"
+    };
     const traced = this.withSpanFn(
       this.traceFunctionKey,
       options_,
@@ -2054,6 +2059,35 @@ var ReplayBranch = class {
 _url = new WeakMap();
 _context = new WeakMap();
 
+// src/seedContext.ts
+var seedContextStorage = null;
+var SEED_CONTEXT_STORAGE_SYMBOL = /* @__PURE__ */ Symbol.for("bitfab.seedContextStorage");
+var seedContextReady = asyncStorageReady.then(() => {
+  const shared = globalThis;
+  const existing = shared[SEED_CONTEXT_STORAGE_SYMBOL];
+  if (existing) {
+    seedContextStorage = existing;
+    return;
+  }
+  const created = createAsyncLocalStorage();
+  if (created) {
+    shared[SEED_CONTEXT_STORAGE_SYMBOL] = created;
+    seedContextStorage = created;
+  }
+});
+function getSeedContext() {
+  return seedContextStorage?.getStore() ?? null;
+}
+function inSeedScope() {
+  return getSeedContext() !== null;
+}
+function runWithSeedContext(ctx, fn) {
+  if (seedContextStorage) {
+    return seedContextStorage.run(ctx, fn);
+  }
+  return fn();
+}
+
 // src/tracing.ts
 var BitfabOpenAITracingProcessor = class {
   /**
@@ -2384,7 +2418,8 @@ var BitfabVercelAiHandler = class {
           key,
           {
             type: "llm",
-            finalize: (result) => summarizeGenerate(result ?? {}, label)
+            finalize: (result) => summarizeGenerate(result ?? {}, label),
+            surface: "inherit"
           },
           () => doGenerate()
         );
@@ -2402,7 +2437,7 @@ var BitfabVercelAiHandler = class {
           // The wrapped fn returns immediately with the live stream, so the span
           // output cannot be read from the return value. `finalize` instead
           // awaits the summary the accumulator resolves once the stream drains.
-          { type: "llm", finalize: () => summary },
+          { type: "llm", finalize: () => summary, surface: "inherit" },
           async () => {
             const result = await doStream();
             const stream = result.stream.pipeThrough(
@@ -2418,6 +2453,18 @@ var BitfabVercelAiHandler = class {
 };
 
 // src/client.ts
+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");
@@ -2781,7 +2828,13 @@ var Bitfab = class {
     this.serviceUrl = config.serviceUrl ?? DEFAULT_SERVICE_URL;
     this.timeout = config.timeout ?? 12e4;
     this.envVars = config.envVars ?? {};
-    this.explicitlyEnabled = config.enabled ?? true;
+    if (config.enabled !== void 0) {
+      warnOnce(
+        "deprecated-enabled-option",
+        "Bitfab({ enabled }) is deprecated; pass captureEnabled instead."
+      );
+    }
+    this.captureConfigured = (config.captureEnabled ?? true) && (config.enabled ?? true);
     this.strict = config.strict ?? false;
     this.bamlClient = config.bamlClient ?? null;
     if (config.dbSnapshot) {
@@ -2817,9 +2870,6 @@ var Bitfab = class {
         if (!descriptor || typeof descriptor.value !== "function") {
           throw new BitfabError("@bitfab.trace can only decorate methods");
         }
-        if (!this.explicitlyEnabled) {
-          return;
-        }
         descriptor.value = this.createAutoTraceRoot(
           traceFunctionKey,
           String(propertyKey),
@@ -2833,9 +2883,6 @@ var Bitfab = class {
       if (typeof method !== "function" || context?.kind !== "method" || context.name === void 0) {
         throw new BitfabError("@bitfab.trace can only decorate methods");
       }
-      if (!this.explicitlyEnabled) {
-        return method;
-      }
       return this.createAutoTraceRoot(
         traceFunctionKey,
         String(context.name),
@@ -2851,9 +2898,6 @@ var Bitfab = class {
     if (!fn) {
       throw new BitfabError("bitfab.withTrace requires a function");
     }
-    if (!this.explicitlyEnabled) {
-      return fn;
-    }
     const name = fn.name !== "" ? fn.name : traceFunctionKey;
     return this.createAutoTraceRoot(traceFunctionKey, name, options, fn);
   }
@@ -2877,9 +2921,6 @@ var Bitfab = class {
         if (!descriptor || typeof descriptor.value !== "function") {
           throw new BitfabError("@bitfab.node can only decorate methods");
         }
-        if (!this.explicitlyEnabled) {
-          return;
-        }
         descriptor.value = this.createAutoTraceNode(
           configuration,
           descriptor.value,
@@ -2892,9 +2933,6 @@ var Bitfab = class {
       if (typeof method !== "function" || context?.kind !== "method") {
         throw new BitfabError("@bitfab.node can only decorate methods");
       }
-      if (!this.explicitlyEnabled) {
-        return method;
-      }
       return this.createAutoTraceNode(
         configuration,
         method,
@@ -2910,9 +2948,6 @@ var Bitfab = class {
       throw new BitfabError("bitfab.withNode requires a function");
     }
     const configuration = this.resolveNodeConfiguration(options);
-    if (!this.explicitlyEnabled) {
-      return fn;
-    }
     const functionName = internalFunctionName ?? fn.name;
     if (functionName === "") {
       throw new BitfabError(
@@ -2965,9 +3000,14 @@ var Bitfab = class {
     );
     const excluded = new Set(options.exclude ?? []);
     const includeWrappers = options.includeWrappers ?? false;
+    const rootOptions = {
+      name: options.name ?? name,
+      type: options.type ?? "custom",
+      surface: "opt-out"
+    };
     const tracedRoot = this.withSpan(
       traceFunctionKey,
-      { name: options.name ?? name, type: options.type ?? "custom" },
+      rootOptions,
       function(...args) {
         const capturePolicy = getAutoTraceCapturePolicy(self, traceFunctionKey);
         self.refreshAutoTraceCapturePolicy(traceFunctionKey);
@@ -3011,6 +3051,7 @@ var Bitfab = class {
               name: nodeConfiguration?.name ?? definition.name,
               type: nodeConfiguration?.type ?? "function",
               captureWhen: "nested",
+              surface: "opt-out",
               functionId: definition.id,
               captureContent: nodeConfiguration !== void 0 || capturePolicy === void 0 || capturePolicy.has(definition.id),
               autoTraceDefinition: definition,
@@ -3048,7 +3089,7 @@ var Bitfab = class {
       }
     );
     const autoTraceRoot = function(...args) {
-      if (!self.isTracingEnabled()) {
+      if (!self.shouldRecord()) {
         return fn.apply(this, args);
       }
       return tracedRoot.apply(this, args);
@@ -3056,6 +3097,7 @@ var Bitfab = class {
     Object.defineProperty(autoTraceRoot, "_bitfabTraceFunctionKey", {
       value: traceFunctionKey
     });
+    Object.defineProperty(autoTraceRoot, "_bitfabWrappedFn", { value: fn });
     return autoTraceRoot;
   }
   refreshAutoTraceCapturePolicy(traceFunctionKey) {
@@ -3139,7 +3181,7 @@ var Bitfab = class {
         "Bitfab: no API key resolved. Set BITFAB_API_KEY or pass apiKey to new Bitfab(). If a script loads env with dotenv, load it before the module that constructs the client is imported (e.g. `node --env-file=.env script.ts`), or pass `apiKey: () => process.env.BITFAB_API_KEY`."
       );
     }
-    if (this.explicitlyEnabled && !this.apiKeyWarned) {
+    if (this.captureConfigured && !this.apiKeyWarned) {
       this.apiKeyWarned = true;
       console.warn(
         "Bitfab: apiKey is empty - tracing is disabled. Provide a valid API key to enable tracing."
@@ -3147,17 +3189,21 @@ var Bitfab = class {
     }
     return void 0;
   }
-  /**
-   * Whether tracing should run, decided lazily at call time (not frozen at
-   * construction). An explicit `enabled: false` short-circuits without ever
-   * touching the key.
-   */
-  isTracingEnabled() {
-    if (!this.explicitlyEnabled) {
+  isCaptureEnabled() {
+    if (!this.captureConfigured) {
+      return false;
+    }
+    return this.resolveApiKey() !== void 0;
+  }
+  shouldRecord() {
+    if (!this.captureConfigured && !getReplayContext() && !inSeedScope()) {
       return false;
     }
     return this.resolveApiKey() !== void 0;
   }
+  get captureEnabled() {
+    return this.isCaptureEnabled();
+  }
   /**
    * Fetch the function with its current version and BAML prompt from the server.
    *
@@ -3569,9 +3615,6 @@ var Bitfab = class {
    * @returns A wrapped function with the same signature that creates spans for inputs and outputs
    */
   withSpan(traceFunctionKey, optionsOrFn, maybeFn) {
-    if (!this.explicitlyEnabled) {
-      return typeof optionsOrFn === "function" ? optionsOrFn : maybeFn;
-    }
     const options = typeof optionsOrFn === "function" ? {} : optionsOrFn;
     const fn = typeof optionsOrFn === "function" ? optionsOrFn : maybeFn;
     const self = this;
@@ -3585,7 +3628,7 @@ var Bitfab = class {
       }
     })();
     const wrappedFn = function(...args) {
-      if (!self.isTracingEnabled()) {
+      if (!self.shouldRecord()) {
         return fn.apply(this, args);
       }
       initializeAsyncContext();
@@ -3633,11 +3676,26 @@ var Bitfab = class {
         const currentStack = getSpanStack();
         const parentContext = currentStack[currentStack.length - 1];
         const replayCtxForTraceId = parentContext ? null : getReplayContext();
-        const traceId = parentContext?.traceId ?? replayCtxForTraceId?.traceId ?? randomUuid();
+        const seedCtxForTraceId = parentContext ? null : getSeedContext();
+        const traceId = parentContext?.traceId ?? replayCtxForTraceId?.traceId ?? seedCtxForTraceId?.traceId ?? randomUuid();
         const spanId = randomUuid();
         const parentSpanId = parentContext?.spanId ?? null;
         const isRootSpan = parentSpanId === null;
-        const newContext = { traceId, spanId, contexts: [] };
+        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 newContext = {
+          traceId,
+          spanId,
+          contexts: [],
+          surface
+        };
         newStack = [...currentStack, newContext];
         const inputs = args;
         const startedAt = nowIsoTimestamp();
@@ -3919,7 +3977,7 @@ var Bitfab = class {
         if (registeredTraceId) {
           activeTraceStates.delete(registeredTraceId);
         }
-        if (getReplayContext()) {
+        if (getReplayContext() || inSeedScope()) {
           throw setupError;
         }
         warnOnce(
@@ -3994,7 +4052,7 @@ var Bitfab = class {
     return {
       traceId,
       addContext: (context) => {
-        if (!this.isTracingEnabled()) {
+        if (!this.shouldRecord()) {
           return Promise.resolve();
         }
         if (typeof context !== "object" || context === null) {
@@ -4005,7 +4063,7 @@ var Bitfab = class {
         });
       },
       setMetadata: (metadata) => {
-        if (!this.isTracingEnabled()) {
+        if (!this.shouldRecord()) {
           return Promise.resolve();
         }
         if (typeof metadata !== "object" || metadata === null) {
@@ -4014,7 +4072,7 @@ var Bitfab = class {
         return this.httpClient.patchTrace(traceId, { mergeMetadata: metadata });
       },
       setSessionId: (sessionId) => {
-        if (!this.isTracingEnabled()) {
+        if (!this.shouldRecord()) {
           return Promise.resolve();
         }
         if (typeof sessionId !== "string" || sessionId.length === 0) {
@@ -4023,7 +4081,7 @@ var Bitfab = class {
         return this.httpClient.patchTrace(traceId, { setSessionId: sessionId });
       },
       setName: (name) => {
-        if (!this.isTracingEnabled()) {
+        if (!this.shouldRecord()) {
           return Promise.resolve();
         }
         if (typeof name !== "string" || name.length === 0) {
@@ -4259,22 +4317,13 @@ var Bitfab = class {
   clearMockOverrides() {
     this.mockOverrides.length = 0;
   }
-  /**
-   * Write a replayable trace from a case, without running anything.
-   *
-   * Use this to turn a corpus you already hold (a Braintrust dataset, a
-   * spreadsheet, hand-written cases) into traces that {@link replay} can
-   * select. The recorded root span carries `input` as its input and `expected`
-   * as its output, so replay reports each item against the value you expected
-   * rather than against a previous run.
-   *
-   * A seeded trace has no child spans and no database pin, so replay mocking
-   * has nothing recorded to substitute and `dbBranch` refuses it. Pass
-   * `mockOverride` at replay time for calls that must not run.
-   *
-   * @returns The trace ID, usable with `replay({ traceIds: [...] })`.
-   */
-  seedTrace(traceFunctionKey, options) {
+  seedTrace(traceFunctionKey, optionsOrFn, runOptions) {
+    if (typeof optionsOrFn === "function") {
+      return this.seedTraceByRunning(traceFunctionKey, optionsOrFn, runOptions);
+    }
+    return this.seedTraceFromCase(traceFunctionKey, optionsOrFn);
+  }
+  seedTraceFromCase(traceFunctionKey, options) {
     const { input } = options;
     const fn = options.fn?._bitfabWrappedFn ?? options.fn;
     if (fn && input.length < fn.length) {
@@ -4323,6 +4372,50 @@ var Bitfab = class {
     }
     return traceId;
   }
+  async seedTraceByRunning(traceFunctionKey, fn, options) {
+    const wrappedKey = fn._bitfabTraceFunctionKey;
+    let target = fn;
+    if (wrappedKey === void 0) {
+      target = this.withSpan(
+        traceFunctionKey,
+        { name: traceFunctionKey, type: "agent" },
+        fn
+      );
+    } else if (wrappedKey !== traceFunctionKey) {
+      throw new BitfabError(
+        `Function is wrapped with trace function key '${wrappedKey}' but seedTrace was called with '${traceFunctionKey}'. Pass matching keys, or pass the unwrapped function to seed it under the explicit key.`
+      );
+    }
+    await seedContextReady;
+    const traceId = randomUuid();
+    activeTraceStates.set(traceId, {
+      traceId,
+      startedAt: nowIsoTimestamp(),
+      contexts: [],
+      ingestionType: "seeded",
+      ...options?.sessionId !== void 0 && { sessionId: options.sessionId },
+      ...options?.name !== void 0 && { name: options.name },
+      ...options?.metadata !== void 0 && { metadata: options.metadata }
+    });
+    const args = options?.args ?? [];
+    let unrecorded = true;
+    try {
+      await runWithSeedContext({ traceId }, async () => target(...args));
+    } finally {
+      try {
+        const { flushTraces: flushTraces2 } = await import("./http-IO3Y7ROJ.js");
+        await flushTraces2(3e4);
+      } finally {
+        unrecorded = activeTraceStates.delete(traceId);
+      }
+    }
+    if (unrecorded) {
+      throw new BitfabError(
+        `seedTrace recorded nothing for '${traceFunctionKey}': the call finished without a root span. Check that an API key resolves (BITFAB_API_KEY or apiKey), and that fn is a regular or async function rather than a generator.`
+      );
+    }
+    return traceId;
+  }
   async replay(traceFunctionKey, fn, options) {
     const wrappedKey = fn._bitfabTraceFunctionKey;
     let replayFn = fn;
@@ -4337,7 +4430,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-PLACY77M.js");
+    const { replay: doReplay } = await import("./replay-LM4GIDVD.js");
     return doReplay(
       this.httpClient,
       this.serviceUrl,
@@ -4573,7 +4666,7 @@ var finalizers = {
 function defineReplayRegistry(registry) {
   return registry;
 }
-async function seedFromRegistry(registry, pipeline, cases) {
+async function seedFromRegistry(registry, pipeline, cases, options = {}) {
   const registration = registry[pipeline];
   if (registration === void 0) {
     throw new BitfabError(
@@ -4581,6 +4674,19 @@ async function seedFromRegistry(registry, pipeline, cases) {
     );
   }
   const traceFunctionKey = resolveTraceFunctionKey(registration);
+  if (options.run === true) {
+    const traceIds2 = [];
+    for (const seedCase of cases) {
+      traceIds2.push(
+        await registration.client.seedTrace(traceFunctionKey, registration.fn, {
+          args: seedCase.input,
+          metadata: seedCase.metadata,
+          sessionId: seedCase.sessionId
+        })
+      );
+    }
+    return { pipeline, traceFunctionKey, traceIds: traceIds2 };
+  }
   const traceIds = cases.map(
     (seedCase) => registration.client.seedTrace(traceFunctionKey, {
       input: seedCase.input,
@@ -4590,7 +4696,7 @@ async function seedFromRegistry(registry, pipeline, cases) {
       sessionId: seedCase.sessionId
     })
   );
-  const { flushTraces: flushTraces2 } = await import("./http-F5L466DI.js");
+  const { flushTraces: flushTraces2 } = await import("./http-IO3Y7ROJ.js");
   await flushTraces2(3e4);
   return { pipeline, traceFunctionKey, traceIds };
 }
@@ -4623,4 +4729,4 @@ export {
   defineReplayRegistry,
   seedFromRegistry
 };
-//# sourceMappingURL=chunk-BC5OYWAM.js.map
+//# sourceMappingURL=chunk-5BBJ5BQD.js.map