bitfab 0.41.0 → 0.43.0

package/dist/index.cjs

@@ -51,7 +51,7 @@ var __version__, __packageName__;
 var init_version_generated = __esm({
   "src/version.generated.ts"() {
     "use strict";
-    __version__ = "0.41.0";
+    __version__ = "0.43.0";
     __packageName__ = "bitfab";
   }
 });
@@ -1346,7 +1346,7 @@ function sourceTraceIdOf(payload) {
   const id = rawTrace?.id;
   return typeof id === "string" ? id : void 0;
 }
-var REPLAY_DB_BRANCH_REQUEST_TIMEOUT_MS, OTLP_TRACES_ENDPOINT, RETRYABLE_STATUSES, EXIT_FLUSH_TIMEOUT_MS, DEFAULT_LIFECYCLE_TIMEOUT_MS2, pendingTracePromises, carrierSeq, HttpClient;
+var REPLAY_DB_BRANCH_REQUEST_TIMEOUT_MS, REPLAY_COMPLETE_REQUEST_TIMEOUT_MS, OTLP_TRACES_ENDPOINT, RETRYABLE_STATUSES, EXIT_FLUSH_TIMEOUT_MS, DEFAULT_LIFECYCLE_TIMEOUT_MS2, pendingTracePromises, carrierSeq, HttpClient;
 var init_http = __esm({
   "src/http.ts"() {
     "use strict";
@@ -1360,6 +1360,7 @@ var init_http = __esm({
     init_unrefTimer();
     init_warnOnce();
     REPLAY_DB_BRANCH_REQUEST_TIMEOUT_MS = 3e5;
+    REPLAY_COMPLETE_REQUEST_TIMEOUT_MS = 12e4;
     OTLP_TRACES_ENDPOINT = "/api/sdk/otel/v1/traces";
     RETRYABLE_STATUSES = /* @__PURE__ */ new Set([429, 500, 502, 503, 504]);
     EXIT_FLUSH_TIMEOUT_MS = 5e3;
@@ -1849,7 +1850,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) {
+      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;
@@ -1882,6 +1883,12 @@ var init_http = __esm({
         if (dbBranchSettings !== void 0) {
           payload.dbBranchSettings = dbBranchSettings;
         }
+        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
@@ -1997,7 +2004,7 @@ var init_http = __esm({
         return this.request(
           "/api/sdk/replay/complete",
           { testRunId },
-          { timeout: 3e4 }
+          { timeout: REPLAY_COMPLETE_REQUEST_TIMEOUT_MS }
         );
       }
       /**
@@ -2006,10 +2013,15 @@ var init_http = __esm({
        * snapshot + preview branch and polls operations to readiness, which
        * can take seconds.
        */
-      async resolveDbBranchLease(testRunId, traceId, dbBranchSettings) {
+      async resolveDbBranchLease(testRunId, traceId, dbBranchSettings, attempt) {
         return this.request(
           "/api/sdk/replay/resolveDbBranchLease",
-          { testRunId, traceId, dbBranchSettings },
+          {
+            testRunId,
+            traceId,
+            dbBranchSettings,
+            ...attempt !== void 0 && attempt > 0 ? { attempt } : {}
+          },
           { timeout: REPLAY_DB_BRANCH_REQUEST_TIMEOUT_MS }
         );
       }
@@ -2445,6 +2457,23 @@ __export(replay_exports, {
   sleepForReplayPersistence: () => sleepForReplayPersistence,
   waitForReplayPersistence: () => waitForReplayPersistence
 });
+function expandReplayWork(serverItems, attempts) {
+  return Array.from(
+    { length: attempts },
+    (_, attempt) => serverItems.map((serverItem) => ({ serverItem, attempt }))
+  ).flat();
+}
+function resolveAttempts(attempts) {
+  if (attempts === void 0) {
+    return 1;
+  }
+  if (!Number.isInteger(attempts) || attempts < 1 || attempts > MAX_REPLAY_ATTEMPTS) {
+    throw new BitfabError(
+      `attempts must be an integer from 1 to ${MAX_REPLAY_ATTEMPTS} (got ${attempts}).`
+    );
+  }
+  return attempts;
+}
 function dbBranchEnabled(dbBranch) {
   return dbBranch !== void 0 && dbBranch !== false;
 }
@@ -2473,6 +2502,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);
 }
@@ -2568,7 +2600,7 @@ function buildMockTree(rootNode) {
   }
   return { spans };
 }
-async function processItem(httpClient, serverItem, fn, testRunId, mockStrategy, resolvedOverrides, replayedTraceId, includeDbBranchLease, dbBranchSettings, adaptInputs, dryRun) {
+async function processItem(httpClient, serverItem, fn, testRunId, mockStrategy, resolvedOverrides, replayedTraceId, attempt, includeDbBranchLease, dbBranchSettings, adaptInputs, dryRun) {
   let lease = includeDbBranchLease ? serverItem.dbBranchLease : void 0;
   let leaseError = includeDbBranchLease ? serverItem.dbBranchLeaseError : void 0;
   let dbSnapshotRef = serverItem.dbSnapshotRef;
@@ -2590,7 +2622,8 @@ async function processItem(httpClient, serverItem, fn, testRunId, mockStrategy,
         resolved = await httpClient.resolveDbBranchLease(
           testRunId,
           originalTraceId,
-          dbBranchSettings
+          dbBranchSettings,
+          attempt
         );
       } catch (cause) {
         throw new DbBranchReplayError(
@@ -2619,12 +2652,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;
@@ -2670,6 +2705,7 @@ async function processItem(httpClient, serverItem, fn, testRunId, mockStrategy,
         originalSpanId,
         sourceTraceId: originalTraceId,
         sourceSpanId: originalSpanId,
+        attempt,
         input: inputs,
         result: void 0,
         originalOutput,
@@ -2698,6 +2734,7 @@ async function processItem(httpClient, serverItem, fn, testRunId, mockStrategy,
           inputSourceSpanId: span.id,
           inputSourceTraceId: span.externalTraceId,
           sourceBitfabTraceId: originalTraceId,
+          replayAttempt: attempt,
           mockTree,
           callCounters: mockTree ? /* @__PURE__ */ new Map() : void 0,
           mockStrategy,
@@ -2749,6 +2786,7 @@ async function processItem(httpClient, serverItem, fn, testRunId, mockStrategy,
     // Deprecated aliases for originalTraceId/originalSpanId.
     sourceTraceId: originalTraceId,
     sourceSpanId: originalSpanId,
+    attempt,
     input: inputs,
     result,
     originalOutput,
@@ -2877,6 +2915,7 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
     } catch {
     }
   }
+  const attempts = resolveAttempts(options?.attempts);
   await replayContextReady;
   let codeChangeDescription = options?.codeChangeDescription;
   let codeChangeFiles = options?.codeChangeFiles;
@@ -2909,7 +2948,9 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
     options?.experimentGroupId,
     options?.datasetId,
     options?.graderIds,
-    resolveDbBranchSettings(options?.dbBranch)
+    resolveDbBranchSettings(options?.dbBranch),
+    attempts,
+    options?.adaptInputs !== void 0
   );
   if (serverItems.length === 0) {
     try {
@@ -2926,10 +2967,11 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
     ...normalizeMockOverrides(options?.mockOverride),
     ...registeredOverrides
   ];
-  const replayedTraceIds = serverItems.map(() => randomUuid());
+  const workItems = expandReplayWork(serverItems, attempts);
+  const replayedTraceIds = workItems.map(() => randomUuid());
   httpClient.trackTraceDeliveries(replayedTraceIds);
-  const tasks = serverItems.map(
-    (serverItem, index) => () => processItem(
+  const tasks = workItems.map(
+    ({ serverItem, attempt }, index) => () => processItem(
       httpClient,
       serverItem,
       fn,
@@ -2937,6 +2979,7 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
       mockStrategy,
       resolvedOverrides,
       replayedTraceIds[index],
+      attempt,
       dbBranchEnabled(options?.dbBranch) && options?.dryRun !== true,
       resolveDbBranchSettings(options?.dbBranch),
       options?.adaptInputs,
@@ -3004,6 +3047,7 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
             // Deprecated aliases for originalTraceId/originalSpanId.
             sourceTraceId: item.originalTraceId ?? null,
             sourceSpanId: item.originalSpanId ?? null,
+            attempt: item.attempt,
             input: item.input,
             result: item.result,
             originalOutput: item.originalOutput,
@@ -3025,7 +3069,7 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
     },
     options?.onItemStart ? (index) => {
       started += 1;
-      const serverItem = serverItems[index];
+      const { serverItem, attempt } = workItems[index];
       const originalTraceId = serverItem.originalTraceId ?? serverItem.sourceTraceId;
       const originalSpanId = serverItem.originalSpanId ?? serverItem.sourceSpanId;
       try {
@@ -3041,7 +3085,8 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
             originalTraceId,
             originalSpanId,
             sourceTraceId: originalTraceId,
-            sourceSpanId: originalSpanId
+            sourceSpanId: originalSpanId,
+            attempt
           }
         });
       } catch {
@@ -3053,7 +3098,8 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
     const dryResult = {
       items: resultItems,
       testRunId,
-      testRunUrl: fullTestRunUrl
+      testRunUrl: fullTestRunUrl,
+      attempts
     };
     await writeReplayResultFile(dryResult);
     return dryResult;
@@ -3122,7 +3168,8 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
   const result = {
     items: resultItems,
     testRunId,
-    testRunUrl: fullTestRunUrl
+    testRunUrl: fullTestRunUrl,
+    attempts
   };
   await writeReplayResultFile(result);
   if (!options?.onItemFinish) {
@@ -3163,7 +3210,7 @@ async function writeReplayResultFile(result) {
     }
   }
 }
-var REPLAY_PERSISTENCE_TIMEOUT_MS, BITFAB_PROGRESS_PREFIX, ReplayError, DbBranchReplayError;
+var REPLAY_PERSISTENCE_TIMEOUT_MS, MAX_REPLAY_ATTEMPTS, BITFAB_PROGRESS_PREFIX, ReplayError, DbBranchReplayError;
 var init_replay = __esm({
   "src/replay.ts"() {
     "use strict";
@@ -3175,6 +3222,7 @@ var init_replay = __esm({
     init_replayContext();
     init_serialize();
     REPLAY_PERSISTENCE_TIMEOUT_MS = 3e4;
+    MAX_REPLAY_ATTEMPTS = 100;
     BITFAB_PROGRESS_PREFIX = "@@bitfab:progress ";
     ReplayError = class extends BitfabError {
       constructor(message, items, testRunId, testRunUrl, cause) {
@@ -5256,7 +5304,8 @@ var BitfabLangGraphIntegration = class {
                 type: "function",
                 captureWhen: "nested",
                 mockOnReplay: shouldMock,
-                finalize: finalizeToolResult
+                finalize: finalizeToolResult,
+                surface: "inherit"
               },
               async (_args) => await originalInvoke(input, ...rest)
             );
@@ -5299,7 +5348,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
     );
   }
@@ -5352,7 +5401,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_,
@@ -5416,6 +5469,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
@@ -5751,7 +5836,8 @@ var BitfabVercelAiHandler = class {
           key,
           {
             type: "llm",
-            finalize: (result) => summarizeGenerate(result ?? {}, label)
+            finalize: (result) => summarizeGenerate(result ?? {}, label),
+            surface: "inherit"
           },
           () => doGenerate()
         );
@@ -5769,7 +5855,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(
@@ -5786,6 +5872,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");
@@ -6149,7 +6247,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) {
@@ -6185,9 +6289,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),
@@ -6201,9 +6302,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),
@@ -6219,9 +6317,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);
   }
@@ -6245,9 +6340,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,
@@ -6260,9 +6352,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,
@@ -6278,9 +6367,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(
@@ -6333,9 +6419,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);
@@ -6379,6 +6470,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,
@@ -6416,7 +6508,7 @@ var Bitfab = class {
       }
     );
     const autoTraceRoot = function(...args) {
-      if (!self.isTracingEnabled()) {
+      if (!self.shouldRecord()) {
         return fn.apply(this, args);
       }
       return tracedRoot.apply(this, args);
@@ -6424,6 +6516,7 @@ var Bitfab = class {
     Object.defineProperty(autoTraceRoot, "_bitfabTraceFunctionKey", {
       value: traceFunctionKey
     });
+    Object.defineProperty(autoTraceRoot, "_bitfabWrappedFn", { value: fn });
     return autoTraceRoot;
   }
   refreshAutoTraceCapturePolicy(traceFunctionKey) {
@@ -6507,7 +6600,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."
@@ -6515,17 +6608,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.
    *
@@ -6937,9 +7034,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;
@@ -6953,7 +7047,7 @@ var Bitfab = class {
       }
     })();
     const wrappedFn = function(...args) {
-      if (!self.isTracingEnabled()) {
+      if (!self.shouldRecord()) {
         return fn.apply(this, args);
       }
       initializeAsyncContext();
@@ -7001,11 +7095,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();
@@ -7021,6 +7130,9 @@ var Bitfab = class {
             ...replayCtxAtStart?.inputSourceTraceId && {
               inputSourceTraceId: replayCtxAtStart.inputSourceTraceId
             },
+            ...replayCtxAtStart?.replayAttempt !== void 0 && {
+              replayAttempt: replayCtxAtStart.replayAttempt
+            },
             dbSnapshotRef
           });
           registeredTraceId = traceId;
@@ -7071,6 +7183,7 @@ var Bitfab = class {
                 contexts: traceState?.contexts ?? [],
                 testRunId: traceState?.testRunId,
                 inputSourceTraceId: traceState?.inputSourceTraceId,
+                replayAttempt: traceState?.replayAttempt,
                 dbSnapshotRef: traceState?.dbSnapshotRef,
                 dropped: traceState?.dropped,
                 ingestionType: traceState?.ingestionType,
@@ -7283,7 +7396,7 @@ var Bitfab = class {
         if (registeredTraceId) {
           activeTraceStates.delete(registeredTraceId);
         }
-        if (getReplayContext()) {
+        if (getReplayContext() || inSeedScope()) {
           throw setupError;
         }
         warnOnce(
@@ -7358,7 +7471,7 @@ var Bitfab = class {
     return {
       traceId,
       addContext: (context) => {
-        if (!this.isTracingEnabled()) {
+        if (!this.shouldRecord()) {
           return Promise.resolve();
         }
         if (typeof context !== "object" || context === null) {
@@ -7369,7 +7482,7 @@ var Bitfab = class {
         });
       },
       setMetadata: (metadata) => {
-        if (!this.isTracingEnabled()) {
+        if (!this.shouldRecord()) {
           return Promise.resolve();
         }
         if (typeof metadata !== "object" || metadata === null) {
@@ -7378,7 +7491,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) {
@@ -7387,7 +7500,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) {
@@ -7468,6 +7581,9 @@ var Bitfab = class {
     if (params.inputSourceTraceId) {
       rawTrace.input_source_trace_id = params.inputSourceTraceId;
     }
+    if (params.replayAttempt !== void 0) {
+      rawTrace.replay_attempt = params.replayAttempt;
+    }
     if (params.dbSnapshotRef) {
       rawTrace.db_snapshot_ref = params.dbSnapshotRef;
     }
@@ -7620,22 +7736,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) {
@@ -7684,6 +7791,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;
@@ -7944,7 +8095,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(
@@ -7952,6 +8103,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,