bitfab 0.54.13 → 0.57.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.54.13";
+    __version__ = "0.57.0";
     __packageName__ = "bitfab";
   }
 });
@@ -972,19 +972,6 @@ var init_spanOrigin = __esm({
   }
 });
 
-// src/unrefTimer.ts
-function unrefTimer(timer) {
-  const handle = timer;
-  if (typeof handle.unref === "function") {
-    handle.unref();
-  }
-}
-var init_unrefTimer = __esm({
-  "src/unrefTimer.ts"() {
-    "use strict";
-  }
-});
-
 // src/simulationPlan.ts
 function planWaitSliceMs(timeoutMs) {
   return Math.min(SIMULATION_PLAN_READ_TIMEOUT_MS, Math.max(timeoutMs, 0) / 2);
@@ -1057,6 +1044,10 @@ function simulationPlanEnvDisabled() {
 function missingSimulationPlanEndpoint(error) {
   return error instanceof BitfabError && error.status === 404;
 }
+function isTraceRootSpan(payload) {
+  const parentId = rawSpanOf(payload)?.parent_id;
+  return parentId === void 0 || parentId === null;
+}
 var SIMULATION_PLAN_REFRESH_MS, SIMULATION_PLAN_RETRY_MS, SIMULATION_PLAN_READ_TIMEOUT_MS, SIMULATION_PLAN_MAX_HELD, DISABLE_SIMULATION_PLAN_ENV, ROOT_TRACE_FUNCTION_KEY_FIELD, CONTENT_OFF_KEY, CONTENT_KEYS, SimulationPlan;
 var init_simulationPlan = __esm({
   "src/simulationPlan.ts"() {
@@ -1065,7 +1056,6 @@ var init_simulationPlan = __esm({
     init_policyRefresh();
     init_readEnv();
     init_spanOrigin();
-    init_unrefTimer();
     init_warnOnce();
     SIMULATION_PLAN_REFRESH_MS = 6e4;
     SIMULATION_PLAN_RETRY_MS = 1e4;
@@ -1080,14 +1070,16 @@ var init_simulationPlan = __esm({
         this.source = source;
         this.enabled = enabled;
         this.policyRefresh = new PolicyRefresh();
-        this.retryPending = false;
-        this.waitingForFirstLoad = 0;
+        this.firstReadOver = false;
+        this.rootWaitOver = false;
         this.held = [];
-        this.droppedWhileHolding = 0;
         this.stopped = false;
         this.loaded = new Promise((resolve) => {
           this.resolveLoaded = resolve;
         });
+        this.firstReadEnded = new Promise((resolve) => {
+          this.resolveFirstReadEnded = resolve;
+        });
       }
       disabled() {
         return !this.enabled || simulationPlanEnvDisabled();
@@ -1105,19 +1097,21 @@ var init_simulationPlan = __esm({
                 "sim-plan-unreadable",
                 "the sim plan response was not understood"
               );
-              return;
+            } else {
+              this.markLoaded(parsed);
             }
-            this.markLoaded(parsed);
+            this.endFirstRead();
           },
           (error) => {
             if (missingSimulationPlanEndpoint(error)) {
               this.markLoaded(/* @__PURE__ */ new Map());
-              return;
+            } else {
+              this.scheduleRetry(
+                "sim-plan-unavailable",
+                `could not read the sim plan: ${error instanceof Error ? error.message : String(error)}`
+              );
             }
-            this.scheduleRetry(
-              "sim-plan-unavailable",
-              `could not read the sim plan: ${error instanceof Error ? error.message : String(error)}`
-            );
+            this.endFirstRead();
           }
         );
       }
@@ -1127,11 +1121,8 @@ var init_simulationPlan = __esm({
         }
         this.contentOffByKey = parsed;
         this.policyRefresh.hold(SIMULATION_PLAN_REFRESH_MS);
-        this.retryPending = false;
-        this.clearRetryTimer();
         this.resolveLoaded?.();
         this.resolveLoaded = void 0;
-        this.releaseHeld();
       }
       scheduleRetry(warnKey, reason) {
         if (this.stopped) {
@@ -1141,39 +1132,50 @@ var init_simulationPlan = __esm({
         if (this.contentOffByKey !== void 0) {
           return;
         }
-        this.retryPending = true;
         warnOnce(
           warnKey,
-          `${reason}. Spans are held until the first read succeeds; while a record is held it is retried every ${SIMULATION_PLAN_RETRY_MS / 1e3}s, otherwise on the next span.`
+          `${reason}. Until a read succeeds, spans are sent without their inputs and outputs, except each trace's root span and spans recorded by a framework integration. The read is retried on the next span after ${SIMULATION_PLAN_RETRY_MS / 1e3}s.`
         );
-        this.armRetry();
       }
-      holdsWork() {
-        return this.held.length > 0 || this.waitingForFirstLoad > 0;
-      }
-      armRetry() {
-        if (this.stopped || !this.retryPending || this.retryTimer !== void 0 || !this.holdsWork()) {
-          return;
+      endFirstRead() {
+        this.endRootWait();
+        if (!this.firstReadOver) {
+          this.firstReadOver = true;
+          this.resolveFirstReadEnded?.();
+          this.resolveFirstReadEnded = void 0;
         }
-        const timer = setTimeout(() => {
-          this.retryTimer = void 0;
-          this.policyRefresh.releaseHold();
-          this.refresh();
-        }, SIMULATION_PLAN_RETRY_MS);
-        unrefTimer(timer);
-        this.retryTimer = timer;
+        this.releaseHeld();
       }
-      clearRetryTimer() {
-        if (this.retryTimer !== void 0) {
-          clearTimeout(this.retryTimer);
-          this.retryTimer = void 0;
+      endRootWait() {
+        this.rootWaitOver = true;
+        if (this.rootWaitTimer !== void 0) {
+          clearTimeout(this.rootWaitTimer);
+          this.rootWaitTimer = void 0;
         }
+        this.resolveRootWait?.();
+        this.resolveRootWait = void 0;
       }
-      syncRetryTimer() {
-        if (this.holdsWork()) {
-          return;
+      waitForFirstRead() {
+        this.refresh();
+        if (this.rootWaitOver || this.disabled() || !this.holdingForFirstRead()) {
+          return void 0;
         }
-        this.clearRetryTimer();
+        if (this.rootWait === void 0) {
+          this.rootWait = new Promise((resolve) => {
+            this.resolveRootWait = resolve;
+          });
+          this.rootWaitTimer = setTimeout(
+            () => this.endRootWait(),
+            SIMULATION_PLAN_READ_TIMEOUT_MS
+          );
+        }
+        return this.rootWait;
+      }
+      holdingForFirstRead() {
+        return this.contentOffByKey === void 0 && !this.firstReadOver && !this.stopped;
+      }
+      unavailableNow() {
+        return !this.disabled() && this.contentOffByKey === void 0 && this.firstReadOver;
       }
       firstLoad() {
         if (this.contentOffByKey !== void 0 || this.stopped || this.disabled()) {
@@ -1183,19 +1185,20 @@ var init_simulationPlan = __esm({
       }
       send(payload, traceFunctionKey, submit) {
         this.refresh();
-        if (this.stopped || this.disabled() || traceFunctionKey === void 0 || spanNameOf(payload) === void 0 || recordedByFramework(payload)) {
+        if (this.disabled() || traceFunctionKey === void 0 || spanNameOf(payload) === void 0 || recordedByFramework(payload)) {
           submit(payload);
           return;
         }
-        if (this.contentOffByKey === void 0) {
-          this.hold({ payload, traceFunctionKey, submit });
+        const entry = { payload, traceFunctionKey, submit };
+        if (this.holdingForFirstRead()) {
+          this.hold(entry);
           return;
         }
-        this.submitEntry({ payload, traceFunctionKey, submit });
+        this.submitEntry(entry);
       }
       sendTrace(payload, submit) {
         this.refresh();
-        if (this.stopped || this.disabled() || this.contentOffByKey !== void 0 || !this.holdsSpanOfTrace(traceIdOf(payload))) {
+        if (this.disabled() || !this.holdingForFirstRead() || !this.holdsSpanOfTrace(traceIdOf(payload))) {
           submit(payload);
           return;
         }
@@ -1211,17 +1214,34 @@ var init_simulationPlan = __esm({
       }
       hold(entry) {
         this.held.push(entry);
+        let overflowed = false;
         while (this.held.length > SIMULATION_PLAN_MAX_HELD) {
-          this.held.shift();
-          this.droppedWhileHolding += 1;
+          const oldest = this.held.shift();
+          this.submitEntry(oldest);
+          overflowed = true;
+        }
+        if (overflowed) {
+          warnOnce(
+            "sim-plan-held-overflow",
+            `more than ${SIMULATION_PLAN_MAX_HELD} records were waiting for the sim plan, so the oldest were sent without their inputs and outputs.`
+          );
+        }
+      }
+      payloadToSend(entry) {
+        if (entry.traceFunctionKey === void 0) {
+          return entry.payload;
+        }
+        if (this.contentOffByKey !== void 0) {
+          return this.apply(entry.payload, entry.traceFunctionKey);
         }
-        this.armRetry();
+        if (recordedByFramework(entry.payload) || isTraceRootSpan(entry.payload)) {
+          return entry.payload;
+        }
+        return stripContent(entry.payload);
       }
       submitEntry(entry) {
         try {
-          entry.submit(
-            entry.traceFunctionKey === void 0 ? entry.payload : this.apply(entry.payload, entry.traceFunctionKey)
-          );
+          entry.submit(this.payloadToSend(entry));
         } catch (error) {
           warnOnce(
             "sim-plan-held-span-dropped",
@@ -1232,62 +1252,38 @@ var init_simulationPlan = __esm({
       releaseHeld() {
         const held = this.held;
         this.held = [];
-        this.syncRetryTimer();
-        this.warnDropped();
         for (const entry of held) {
           this.submitEntry(entry);
         }
       }
-      warnDropped() {
-        if (this.droppedWhileHolding === 0) {
-          return;
-        }
-        const dropped = this.droppedWhileHolding;
-        this.droppedWhileHolding = 0;
-        warnOnce(
-          "sim-plan-held-overflow",
-          `${dropped} record(s) were dropped while the sim plan was still loading; at most ${SIMULATION_PLAN_MAX_HELD} are held per client.`
-        );
-      }
-      warnNeverLoaded() {
+      releaseHeldWithoutPlan() {
         if (this.held.length === 0) {
           return;
         }
-        warnOnce(
-          "sim-plan-never-loaded",
-          `${this.held.length} record(s) were not sent because the sim plan never loaded`
-        );
+        if (this.contentOffByKey === void 0) {
+          warnOnce(
+            "sim-plan-not-loaded-at-release",
+            `${this.held.length} record(s) were sent without their inputs and outputs because the sim plan had not loaded`
+          );
+        }
+        this.releaseHeld();
       }
       async release(timeoutMs) {
         this.refresh();
-        if (this.holdsWork()) {
-          await this.waitForFirstLoad(timeoutMs);
+        if (this.held.length > 0) {
+          await this.waitForFirstReadEnd(timeoutMs);
         }
-        this.warnNeverLoaded();
-        this.warnDropped();
+        this.releaseHeldWithoutPlan();
       }
-      waitForFirstLoad(timeoutMs) {
-        const firstLoad = this.firstLoad();
-        if (firstLoad === void 0) {
+      waitForFirstReadEnd(timeoutMs) {
+        if (this.firstReadOver) {
           return Promise.resolve();
         }
-        this.waitingForFirstLoad += 1;
-        this.armRetry();
         return new Promise((resolve) => {
-          let settled2 = false;
-          const finish = () => {
-            if (settled2) {
-              return;
-            }
-            settled2 = true;
-            this.waitingForFirstLoad -= 1;
-            this.syncRetryTimer();
-            resolve();
-          };
-          const timer = setTimeout(finish, Math.max(timeoutMs, 0));
-          void firstLoad.then(() => {
+          const timer = setTimeout(resolve, Math.max(timeoutMs, 0));
+          void this.firstReadEnded.then(() => {
             clearTimeout(timer);
-            finish();
+            resolve();
           });
         });
       }
@@ -1295,16 +1291,16 @@ var init_simulationPlan = __esm({
         if (this.stopped) {
           return;
         }
+        this.releaseHeldWithoutPlan();
         this.stopped = true;
-        this.retryPending = false;
-        this.clearRetryTimer();
-        this.warnNeverLoaded();
-        this.held = [];
-        this.warnDropped();
+        this.endFirstRead();
       }
       contentOff(traceFunctionKey, spanName) {
         return this.contentOffByKey?.get(traceFunctionKey)?.has(spanName) === true;
       }
+      contentOffNow(traceFunctionKey, spanName) {
+        return !this.stopped && !this.disabled() && this.contentOff(traceFunctionKey, spanName);
+      }
       apply(payload, traceFunctionKey) {
         if (recordedByFramework(payload)) {
           return payload;
@@ -1435,6 +1431,19 @@ var init_transportTypes = __esm({
   }
 });
 
+// src/unrefTimer.ts
+function unrefTimer(timer) {
+  const handle = timer;
+  if (typeof handle.unref === "function") {
+    handle.unref();
+  }
+}
+var init_unrefTimer = __esm({
+  "src/unrefTimer.ts"() {
+    "use strict";
+  }
+});
+
 // src/otel.ts
 function readBoundedIntEnv(name, max, fallback, warnKey) {
   const raw = readEnv(name);
@@ -2087,9 +2096,14 @@ __export(http_exports, {
 });
 async function releaseHeldExternalSpans(timeoutMs) {
   const deadline = Date.now() + Math.max(timeoutMs, 0);
+  let released = true;
   for (const client of [...liveHttpClients]) {
-    await client.releaseHeldExternalSpans?.(Math.max(0, deadline - Date.now()));
+    const result = await client.releaseHeldExternalSpans?.(
+      Math.max(0, deadline - Date.now())
+    );
+    released = result !== false && released;
   }
+  return released;
 }
 function stopSimulationPlans() {
   for (const client of [...liveHttpClients]) {
@@ -2106,14 +2120,15 @@ function awaitOnExit(promise) {
 }
 async function flushTraces(timeoutMs = 5e3) {
   const deadline = Date.now() + Math.max(timeoutMs, 0);
-  await releaseHeldExternalSpans(planWaitSliceMs(timeoutMs));
+  const released = await releaseHeldExternalSpans(planWaitSliceMs(timeoutMs));
   const requestsFlushed = await awaitPendingRequests(
     Math.max(0, deadline - Date.now())
   );
+  const releasedAfterDeferred = await releaseHeldExternalSpans(0);
   const transportsFlushed = await flushTraceTransports(
     Math.max(0, deadline - Date.now())
   );
-  return requestsFlushed && transportsFlushed;
+  return released && releasedAfterDeferred && requestsFlushed && transportsFlushed;
 }
 async function awaitPendingRequests(timeoutMs = DEFAULT_LIFECYCLE_TIMEOUT_MS2) {
   await replayContextReady.catch(() => {
@@ -2523,13 +2538,17 @@ var init_http = __esm({
        */
       async settleDeferredWork(timeoutMs = DEFAULT_LIFECYCLE_TIMEOUT_MS2) {
         const deadline = Date.now() + Math.max(timeoutMs, 0);
-        await this.releaseHeldExternalSpans?.(planWaitSliceMs(timeoutMs));
+        const released = await this.releaseHeldExternalSpans?.(
+          planWaitSliceMs(timeoutMs)
+        );
         await replayContextReady.catch(() => {
         });
-        return waitForPromises(
+        const settled2 = await waitForPromises(
           Array.from(this.deferredWork),
           Math.max(0, deadline - Date.now())
         );
+        const releasedAfterDeferred = await this.releaseHeldExternalSpans?.(0);
+        return released !== false && releasedAfterDeferred !== false && settled2;
       }
       /**
        * Wait for spans queued by this client to be delivered, within one deadline.
@@ -2554,7 +2573,9 @@ var init_http = __esm({
         }
         const deadline = Date.now() + Math.max(timeoutMs, 0);
         this.closing = (async () => {
-          await this.releaseHeldExternalSpans?.(planWaitSliceMs(timeoutMs));
+          const released = await this.releaseHeldExternalSpans?.(
+            planWaitSliceMs(timeoutMs)
+          );
           this.stopSimulationPlan?.();
           this.externalSpanTransform = void 0;
           this.externalTraceTransform = void 0;
@@ -2568,7 +2589,7 @@ var init_http = __esm({
           const transport = this.traceTransport;
           this.traceTransport = void 0;
           const shutdownOk = await transport?.shutdown(Math.max(0, deadline - Date.now())) ?? true;
-          return settled2 && shutdownOk;
+          return released !== false && settled2 && shutdownOk;
         })();
         return this.closing;
       }
@@ -4002,6 +4023,12 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
     }
   }
   const attempts = resolveAttempts(options?.attempts);
+  const maxConcurrency = options?.maxConcurrency ?? 10;
+  if (!Number.isInteger(maxConcurrency) || maxConcurrency < 1) {
+    throw new BitfabError(
+      `maxConcurrency must be a positive integer (got ${maxConcurrency}).`
+    );
+  }
   await replayContextReady;
   let codeChangeDescription = options?.codeChangeDescription;
   let codeChangeFiles = options?.codeChangeFiles;
@@ -4048,7 +4075,6 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
     }
   }
   const mockStrategy = options?.mock ?? "marked";
-  const maxConcurrency = options?.maxConcurrency ?? 10;
   const fullTestRunUrl = `${serviceUrl}${testRunUrl}`;
   const resolvedOverrides = [
     ...normalizeMockOverrides(options?.mockOverride),
@@ -4145,6 +4171,7 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
             originalDurationMs: item.originalDurationMs,
             originalTokens: item.originalTokens,
             originalModel: item.originalModel,
+            ingestionType: item.ingestionType,
             tokens: item.tokens,
             model: item.model,
             dbSnapshotRef: item.dbSnapshotRef,
@@ -5978,6 +6005,14 @@ var LabelsClient = class {
     );
     return response.labels;
   }
+  /** Withhold a verdict for a trace or replay attempt whose check did not run. */
+  async skip(target, testRunId) {
+    return this.save({ ...target, skip: true }, testRunId);
+  }
+  /** Clear a previous verdict for a trace, replay attempt, or assertion. */
+  async archive(target, testRunId) {
+    return this.save({ ...target, archive: true }, testRunId);
+  }
   async saveHuman(update) {
     const [outcome] = await this.saveHumanAll([update]);
     return outcome;
@@ -6896,6 +6931,15 @@ var BitfabLangGraphIntegration = class {
 // src/client.ts
 init_mockOverride();
 
+// src/streamFinalizationError.ts
+var StreamFinalizationError = class extends Error {
+  constructor(message, output) {
+    super(message);
+    this.output = output;
+    this.name = "StreamFinalizationError";
+  }
+};
+
 // src/openaiAgentSdk.ts
 var BitfabOpenAIAgentHandler = class {
   constructor(config) {
@@ -6935,7 +6979,11 @@ var BitfabOpenAIAgentHandler = class {
       if (isStreaming && res?.completed) {
         try {
           await res.completed;
-        } catch {
+        } catch (error) {
+          throw new StreamFinalizationError(
+            error instanceof Error ? error.message : String(error),
+            res.finalOutput
+          );
         }
       }
       return res?.finalOutput;
@@ -7693,17 +7741,6 @@ function runWithSeedContext(ctx, fn) {
 init_serialize();
 init_simulationPlan();
 init_spanOrigin();
-
-// src/streamFinalizationError.ts
-var StreamFinalizationError = class extends Error {
-  constructor(message, output) {
-    super(message);
-    this.output = output;
-    this.name = "StreamFinalizationError";
-  }
-};
-
-// src/client.ts
 init_traceMetadata();
 
 // src/traces.ts
@@ -8243,6 +8280,25 @@ var BitfabVercelAiHandler = class {
 // src/client.ts
 init_warnOnce();
 var activeTraceStates = /* @__PURE__ */ new Map();
+function fitsTraceSpanBudget(payload) {
+  if (!recordedByFramework(payload)) {
+    return true;
+  }
+  const traceId = traceIdOf(payload);
+  const spanBudget = traceId === void 0 ? void 0 : activeTraceStates.get(traceId)?.spanBudget;
+  if (spanBudget === void 0) {
+    return true;
+  }
+  if (spanBudget.spansUsed >= spanBudget.maxSpans) {
+    spanBudget.truncate();
+    return false;
+  }
+  spanBudget.spansUsed += 1;
+  return true;
+}
+function rootTraceFunctionKeyOfTrace(traceId, fallback) {
+  return activeTraceStates.get(traceId)?.traceFunctionKey ?? fallback;
+}
 function rootTraceFunctionKeyOf(payload) {
   const captured = payload[ROOT_TRACE_FUNCTION_KEY_FIELD];
   if (typeof captured === "string") {
@@ -8618,7 +8674,8 @@ function readBooleanEnv(name) {
   return void 0;
 }
 var DEFAULT_AUTO_TRACE_MAX_DEPTH = 30;
-var DEFAULT_AUTO_TRACE_MAX_SPANS = 500;
+var DEFAULT_AUTO_TRACE_MAX_SPANS = 2048;
+var DEFAULT_AUTO_TRACE_MAX_CAPTURED_SUBTREE_SPANS = 512;
 var AUTO_TRACE_PROTOCOL = "ts-auto-v1";
 function spanOwnerName(receiver) {
   if (typeof receiver === "function") {
@@ -8689,6 +8746,9 @@ var Bitfab = class {
     this.httpClient.externalTraceTransform = (payload, submit) => this.simulationPlan.sendTrace(payload, submit);
     this.httpClient.releaseHeldExternalSpans = (timeoutMs) => this.simulationPlan.release(timeoutMs);
     this.httpClient.stopSimulationPlan = () => this.simulationPlan.stop();
+    if (this.findApiKey(false) !== void 0) {
+      this.simulationPlan.refresh();
+    }
     this.datasets = new DatasetsClient(this.httpClient);
     this.assertionCategories = new AssertionCategoriesClient(this.httpClient);
     this.traces = new TracesClient(this.httpClient);
@@ -8845,10 +8905,23 @@ var Bitfab = class {
       options.maxDepth,
       DEFAULT_AUTO_TRACE_MAX_DEPTH
     );
+    if (options.maxSpans !== void 0 && options.maxSpans < 1) {
+      throw new BitfabError(
+        `maxSpans must be at least 1 because the root span counts toward it (got ${options.maxSpans})`
+      );
+    }
     const maxSpans = autoTraceLimit(
       options.maxSpans,
       DEFAULT_AUTO_TRACE_MAX_SPANS
     );
+    const maxCapturedSubtreeSpans = Math.min(
+      autoTraceLimit(
+        options.maxCapturedSubtreeSpans,
+        DEFAULT_AUTO_TRACE_MAX_CAPTURED_SUBTREE_SPANS
+      ),
+      maxSpans
+    );
+    const rootIsAsync = fn.constructor.name === "AsyncFunction";
     const excluded = new Set(options.exclude ?? []);
     const includeWrappers = options.includeWrappers ?? false;
     const rootNameFor = (receiver) => options.name ?? (fn.name !== "" ? qualifiedSpanName(receiver, name) ?? name : name);
@@ -8864,7 +8937,7 @@ var Bitfab = class {
       spanOptions,
       function(...args) {
         self.simulationPlan.refresh();
-        let spansUsed = 0;
+        let capturedSubtreeCount = 0;
         let truncated = false;
         const warnTruncated = () => {
           if (!truncated) {
@@ -8874,15 +8947,27 @@ var Bitfab = class {
                 protocol: AUTO_TRACE_PROTOCOL,
                 truncated: true,
                 maxDepth,
-                maxSpans
+                maxSpans,
+                maxCapturedSubtreeSpans
               }
             });
           }
           warnOnce(
             `auto-trace-truncated:${traceFunctionKey}`,
-            `"${traceFunctionKey}" hit an automatic subtree capture limit (maxDepth=${maxDepth}, maxSpans=${maxSpans}); its trace is incomplete. Raise the limits or narrow the subtree with exclude.`
+            `"${traceFunctionKey}" hit an automatic subtree capture limit (maxDepth=${maxDepth}, maxCapturedSubtreeSpans=${maxCapturedSubtreeSpans}, maxSpans=${maxSpans}); its trace is incomplete. Raise the limits, declare the calls you need with node(), or narrow the subtree with exclude.`
           );
         };
+        const rootSpanStack = getSpanStack();
+        const spanBudget = {
+          spansUsed: 1,
+          maxSpans,
+          truncate: () => runWithSpanStack(rootSpanStack, warnTruncated)
+        };
+        const rootSpan = rootSpanStack[rootSpanStack.length - 1];
+        const rootTraceState = rootSpan === void 0 ? void 0 : activeTraceStates.get(rootSpan.traceId);
+        if (rootTraceState !== void 0 && rootTraceState.spanBudget === void 0) {
+          rootTraceState.spanBudget = spanBudget;
+        }
         const spanStackOf = (entry) => entry.spanStack;
         const openChild = (entry, childOptions, inputs, isAsync, invokeFn) => {
           const runInside = () => runWithAutoTraceEntry(
@@ -8911,12 +8996,25 @@ var Bitfab = class {
             return tracedChild(...inputs);
           });
         };
-        const overBudget = (entry) => {
-          if (entry.depth < maxDepth && spansUsed < maxSpans) {
-            return false;
+        const rootTraceFunctionKeyOfEntry = (entry) => {
+          const stack = spanStackOf(entry);
+          const innermost = stack[stack.length - 1];
+          return innermost === void 0 ? traceFunctionKey : rootTraceFunctionKeyOfTrace(innermost.traceId, traceFunctionKey);
+        };
+        const recordsSpan = (entry, spanName, declared) => {
+          const countsTowardCapturedSubtree = !declared && !self.simulationPlan.contentOffNow(
+            rootTraceFunctionKeyOfEntry(entry),
+            spanName
+          );
+          if (entry.depth < maxDepth && spanBudget.spansUsed < maxSpans && (!countsTowardCapturedSubtree || capturedSubtreeCount < maxCapturedSubtreeSpans)) {
+            spanBudget.spansUsed += 1;
+            if (countsTowardCapturedSubtree) {
+              capturedSubtreeCount += 1;
+            }
+            return true;
           }
           runWithSpanStack(spanStackOf(entry), warnTruncated);
-          return true;
+          return false;
         };
         const autoTraceContext = {
           traceFunctionKey,
@@ -8930,13 +9028,13 @@ var Bitfab = class {
             if (nodeConfiguration?.capture === false) {
               return clearAutoTraceNodeConfiguration(invokeFn);
             }
-            if (overBudget(entry)) {
+            const spanName = nodeConfiguration?.name ?? definition.name;
+            if (!recordsSpan(entry, spanName, nodeConfiguration !== void 0)) {
               return invokeWithoutNode();
             }
-            spansUsed += 1;
             const mockOnReplay = nodeConfiguration?.mockOnReplay ?? options.mockOnReplayDefault;
             const childOptions = {
-              name: nodeConfiguration?.name ?? definition.name,
+              name: spanName,
               type: nodeConfiguration?.type ?? "function",
               captureWhen: "nested",
               surface: "opt-out",
@@ -8963,10 +9061,9 @@ var Bitfab = class {
             );
           },
           invokeNestedRoot(nestedName, nestedFunctionName, inputs, invokeFn, entry, link) {
-            if (excluded.has(nestedName) || excluded.has(nestedFunctionName) || overBudget(entry)) {
+            if (excluded.has(nestedName) || excluded.has(nestedFunctionName) || !recordsSpan(entry, nestedName, true)) {
               return invokeFn();
             }
-            spansUsed += 1;
             const childOptions = {
               name: nestedName,
               type: "function",
@@ -8993,6 +9090,12 @@ var Bitfab = class {
       }
       const enclosing = currentAutoTraceEntries();
       if (enclosing.length === 0) {
+        const firstPlanRead = rootIsAsync ? self.simulationPlan.waitForFirstRead() : void 0;
+        if (firstPlanRead !== void 0) {
+          return firstPlanRead.then(
+            () => tracedRoot.apply(this, args)
+          );
+        }
         return tracedRoot.apply(this, args);
       }
       const link = getReplayContext() || inSeedScope() ? void 0 : { traceFunctionKey };
@@ -9039,6 +9142,9 @@ var Bitfab = class {
     return autoTraceRoot;
   }
   applySimulationPlan(payload, submit) {
+    if (!fitsTraceSpanBudget(payload)) {
+      return;
+    }
     this.simulationPlan.send(payload, rootTraceFunctionKeyOf(payload), submit);
   }
   /**
@@ -9073,15 +9179,24 @@ var Bitfab = class {
    * from the environment. Once a non-empty key is found it is cached, so an
    * early resolve that found nothing never poisons a later one.
    */
-  resolveApiKey() {
+  findApiKey(callsKeyFunction) {
     if (this.resolvedApiKey !== void 0) {
       return this.resolvedApiKey;
     }
+    if (typeof this.apiKeyConfig === "function" && !callsKeyFunction) {
+      return void 0;
+    }
     const fromConfig = typeof this.apiKeyConfig === "function" ? this.apiKeyConfig() : this.apiKeyConfig;
     const candidate = fromConfig && fromConfig.trim() !== "" ? fromConfig : readEnv2("BITFAB_API_KEY");
     const key = candidate && candidate.trim() !== "" ? candidate : void 0;
     if (key) {
       this.resolvedApiKey = key;
+    }
+    return key;
+  }
+  resolveApiKey() {
+    const key = this.findApiKey(true);
+    if (key) {
       return key;
     }
     if (this.strict) {
@@ -9701,7 +9816,10 @@ var Bitfab = class {
         self.httpClient.traceCompletion.start(traceId, spanId);
         startedSpan = { traceId, spanId };
         const functionName = fn.name !== "" ? fn.name : void 0;
-        const rootTraceFunctionKey = activeTraceStates.get(traceId)?.traceFunctionKey ?? traceFunctionKey;
+        const rootTraceFunctionKey = rootTraceFunctionKeyOfTrace(
+          traceId,
+          traceFunctionKey
+        );
         const baseSpanParams = {
           traceFunctionKey,
           rootTraceFunctionKey,
@@ -10223,14 +10341,25 @@ var Bitfab = class {
       ...params.testRunId && { testRunId: params.testRunId }
     });
   }
+  contentOffBySimulationPlan(params) {
+    if (params.rootTraceFunctionKey === void 0 || isFrameworkInstrumentation(params.instrumentation)) {
+      return false;
+    }
+    return this.simulationPlan.contentOffNow(
+      params.rootTraceFunctionKey,
+      params.spanName
+    ) || params.parentSpanId !== null && this.simulationPlan.unavailableNow();
+  }
   /**
    * Send a wrapper span from function execution.
    * Internal method to record spans when using withSpan.
    * Queued on the client's span transport; delivery is the transport's job.
    */
   sendWrapperSpan(params) {
-    const serializedInputs = params.captureContent ? serializeValue(params.inputs) : void 0;
-    const serializedResult = params.captureContent ? serializeValue(params.result) : void 0;
+    const contentOff = this.contentOffBySimulationPlan(params);
+    const buildsContent = params.captureContent && !contentOff;
+    const serializedInputs = buildsContent ? serializeValue(params.inputs) : void 0;
+    const serializedResult = buildsContent ? serializeValue(params.result) : void 0;
     const externalSpan = {
       id: params.spanId,
       trace_id: params.traceId,
@@ -10281,7 +10410,8 @@ var Bitfab = class {
         ...params.captureContent && params.contexts && params.contexts.length > 0 && {
           contexts: params.contexts
         },
-        ...params.captureContent && params.prompt !== void 0 && { prompt: params.prompt }
+        ...params.captureContent && params.prompt !== void 0 && { prompt: params.prompt },
+        ...contentOff && { [CONTENT_OFF_KEY]: true }
       }
     };
     if (params.parentSpanId) {