@bitfab/sdk 0.42.0 → 0.43.0

package/dist/index.cjs

@@ -42,7 +42,7 @@ var __version__, __packageName__;
 var init_version_generated = __esm({
   "src/version.generated.ts"() {
     "use strict";
-    __version__ = "0.42.0";
+    __version__ = "0.43.0";
     __packageName__ = "@bitfab/sdk";
   }
 });
@@ -1841,7 +1841,7 @@ var init_http = __esm({
        * Start a replay session by fetching historical traces.
        * Blocking call - creates a test run and returns lightweight item references.
        */
-      async startReplay(traceFunctionKey, limit, traceIds, name, codeChangeDescription, codeChangeFiles, includeDbBranchLease, experimentGroupId, datasetId, graderIds, dbBranchSettings, attempts) {
+      async startReplay(traceFunctionKey, limit, traceIds, name, codeChangeDescription, codeChangeFiles, includeDbBranchLease, experimentGroupId, datasetId, graderIds, dbBranchSettings, attempts, includeOriginalMetadata) {
         const payload = { traceFunctionKey };
         if (limit !== void 0) {
           payload.limit = limit;
@@ -1877,6 +1877,9 @@ var init_http = __esm({
         if (attempts !== void 0 && attempts > 1) {
           payload.attempts = attempts;
         }
+        if (includeOriginalMetadata) {
+          payload.includeOriginalMetadata = true;
+        }
         const timeout = includeDbBranchLease ? REPLAY_DB_BRANCH_REQUEST_TIMEOUT_MS : 3e4;
         return this.request("/api/sdk/replay/start", payload, {
           timeout
@@ -2490,6 +2493,9 @@ function reportReplayProgress(progress) {
   } catch {
   }
 }
+function isPlainRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 function errorMessage(error) {
   return error instanceof Error ? error.message : String(error);
 }
@@ -2637,12 +2643,14 @@ async function processItem(httpClient, serverItem, fn, testRunId, mockStrategy,
     inputs = deserializeInputs(spanData);
     originalOutput = deserializeOutput(spanData);
     if (adaptInputs) {
+      const originalMetadata = serverItem.originalMetadata;
       inputs = adaptInputs(inputs, {
         originalTraceId,
         originalSpanId,
         // Deprecated aliases for originalTraceId/originalSpanId.
         sourceTraceId: originalTraceId,
-        sourceSpanId: originalSpanId
+        sourceSpanId: originalSpanId,
+        metadata: isPlainRecord(originalMetadata) ? { ...originalMetadata } : {}
       });
     }
     const hasOverrides = resolvedOverrides.length > 0;
@@ -2932,7 +2940,8 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
     options?.datasetId,
     options?.graderIds,
     resolveDbBranchSettings(options?.dbBranch),
-    attempts
+    attempts,
+    options?.adaptInputs !== void 0
   );
   if (serverItems.length === 0) {
     try {
@@ -5286,7 +5295,8 @@ var BitfabLangGraphIntegration = class {
                 type: "function",
                 captureWhen: "nested",
                 mockOnReplay: shouldMock,
-                finalize: finalizeToolResult
+                finalize: finalizeToolResult,
+                surface: "inherit"
               },
               async (_args) => await originalInvoke(input, ...rest)
             );
@@ -5329,7 +5339,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
     );
   }
@@ -5382,7 +5392,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_,
@@ -5446,6 +5460,38 @@ _context = new WeakMap();
 
 // src/client.ts
 init_replayContext();
+
+// src/seedContext.ts
+init_asyncStorage();
+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/client.ts
 init_serialize();
 
 // src/tracing.ts
@@ -5781,7 +5827,8 @@ var BitfabVercelAiHandler = class {
           key,
           {
             type: "llm",
-            finalize: (result) => summarizeGenerate(result ?? {}, label)
+            finalize: (result) => summarizeGenerate(result ?? {}, label),
+            surface: "inherit"
           },
           () => doGenerate()
         );
@@ -5799,7 +5846,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(
@@ -5816,6 +5863,18 @@ 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");
@@ -6179,7 +6238,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) {
@@ -6215,9 +6280,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),
@@ -6231,9 +6293,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),
@@ -6249,9 +6308,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);
   }
@@ -6275,9 +6331,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,
@@ -6290,9 +6343,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,
@@ -6308,9 +6358,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(
@@ -6363,9 +6410,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);
@@ -6409,6 +6461,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,
@@ -6446,7 +6499,7 @@ var Bitfab = class {
       }
     );
     const autoTraceRoot = function(...args) {
-      if (!self.isTracingEnabled()) {
+      if (!self.shouldRecord()) {
         return fn.apply(this, args);
       }
       return tracedRoot.apply(this, args);
@@ -6454,6 +6507,7 @@ var Bitfab = class {
     Object.defineProperty(autoTraceRoot, "_bitfabTraceFunctionKey", {
       value: traceFunctionKey
     });
+    Object.defineProperty(autoTraceRoot, "_bitfabWrappedFn", { value: fn });
     return autoTraceRoot;
   }
   refreshAutoTraceCapturePolicy(traceFunctionKey) {
@@ -6537,7 +6591,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."
@@ -6545,17 +6599,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.
    *
@@ -6967,9 +7025,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;
@@ -6983,7 +7038,7 @@ var Bitfab = class {
       }
     })();
     const wrappedFn = function(...args) {
-      if (!self.isTracingEnabled()) {
+      if (!self.shouldRecord()) {
         return fn.apply(this, args);
       }
       initializeAsyncContext();
@@ -7031,11 +7086,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();
@@ -7317,7 +7387,7 @@ var Bitfab = class {
         if (registeredTraceId) {
           activeTraceStates.delete(registeredTraceId);
         }
-        if (getReplayContext()) {
+        if (getReplayContext() || inSeedScope()) {
           throw setupError;
         }
         warnOnce(
@@ -7392,7 +7462,7 @@ var Bitfab = class {
     return {
       traceId,
       addContext: (context) => {
-        if (!this.isTracingEnabled()) {
+        if (!this.shouldRecord()) {
           return Promise.resolve();
         }
         if (typeof context !== "object" || context === null) {
@@ -7403,7 +7473,7 @@ var Bitfab = class {
         });
       },
       setMetadata: (metadata) => {
-        if (!this.isTracingEnabled()) {
+        if (!this.shouldRecord()) {
           return Promise.resolve();
         }
         if (typeof metadata !== "object" || metadata === null) {
@@ -7412,7 +7482,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) {
@@ -7421,7 +7491,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) {
@@ -7657,22 +7727,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) {
@@ -7721,6 +7782,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 Promise.resolve().then(() => (init_http(), http_exports));
+        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;
@@ -7981,7 +8086,7 @@ init_replay();
 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(
@@ -7989,6 +8094,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,