@bitfab/sdk 0.33.3 → 0.33.5

package/dist/index.d.cts

@@ -752,8 +752,9 @@ type MockStrategy = "none" | "all" | "marked";
 /**
  * How the DB-snapshot branch each replay item runs against is sized and warmed.
  *
- * Passing this object at all is what turns database branching on, so `{}` means
- * "branch every item, with the mirror project's own defaults".
+ * Every field is optional, so this object is only worth passing when you want
+ * to override the mirror project's own sizing. To branch with those defaults,
+ * pass `dbBranch: true` instead of an empty object.
  */
 interface DbBranchOptions {
     /**
@@ -826,17 +827,17 @@ interface ReplayOptions {
     mockOverride?: MockOverride | MockOverride[];
     /**
      * Run each item against a database branch restored to the state its source
-     * trace saw. Passing this object at all turns branching on, so `{}` enables
-     * it with the mirror project's own sizing; the fields tune how each branch is
-     * sized and warmed. Inside `fn`, read the resolved branch with
-     * `getCurrentReplayBranch()`.
+     * trace saw. Pass `true` to branch with the mirror project's own sizing, or a
+     * {@link DbBranchOptions} object to tune how each branch is sized and warmed.
+     * `false` and omission leave branching off. Inside `fn`, read the resolved
+     * branch with `getCurrentReplayBranch()`.
      *
      * Items whose source trace carried no DB snapshot reference get no branch and
      * run against the live database. An item whose branch was requested but could
      * not be resolved fails instead of running, so a replay never silently
      * reports a result that did not use the historical data you asked for.
      */
-    dbBranch?: DbBranchOptions;
+    dbBranch?: DbBranchOptions | boolean;
     /** Group ID to associate this replay with an experiment group for live streaming in Studio. */
     experimentGroupId?: string;
     /**
@@ -1419,6 +1420,12 @@ interface BitfabConfig {
  * - custom: Application-specific tracing (default)
  */
 type SpanType = "llm" | "agent" | "function" | "guardrail" | "handoff" | "custom";
+/**
+ * Controls when a span is captured.
+ * - always: Capture the span even when it becomes the root of a new trace.
+ * - nested: Capture the span only when another Bitfab span is already active.
+ */
+type CaptureWhen = "always" | "nested";
 /**
  * Options for configuring span behavior.
  */
@@ -1432,6 +1439,14 @@ interface SpanOptions {
      * The type of span. Defaults to "custom" if not specified.
      */
     type?: SpanType;
+    /**
+     * Controls whether this span may start a new trace. Defaults to "always".
+     *
+     * Use "nested" for reusable helpers that should appear inside an existing
+     * trace but should run untraced when called on their own.
+     * Unknown values warn once and default to "always".
+     */
+    captureWhen?: CaptureWhen;
     /**
      * When true, replay will reuse this span's historical output instead of
      * executing the wrapped function. Read by the "marked" replay strategy;
@@ -1968,7 +1983,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.33.3";
+declare const __version__ = "0.33.5";
 
 /**
  * Constants for the Bitfab SDK.
@@ -2036,4 +2051,4 @@ declare const finalizers: {
     readableStream: typeof readableStream;
 };
 
-export { type ActiveSpanContext, type AdaptContext, type AdaptInputsFn, type AllowedEnvVars, BITFAB_PROGRESS_PREFIX, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler as BitfabLangChainCallbackHandler, BitfabLangGraphCallbackHandler, type BitfabLanguageModelMiddleware, BitfabOpenAIAgentHandler, BitfabOpenAITracingProcessor, BitfabVercelAiHandler, type CapturedSpan, type CodeChangeFile, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type DbBranchOptions, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, type MockOverride, type MockOverrideCtx, type MockStrategy, type MockValue, type NodeMatcher, type ProviderDefinition, ReplayBranch, type ReplayItem, type ReplayOptions, type ReplayProgress, type ReplayResult, SUPPORTED_PROVIDERS, type SpanLookup, type SpanNodeMeta, type SpanOccurrence, type SpanOptions, type SpanType, type TokenUsage, type TraceResponse, type TracingProcessor, type VercelCallParams, type VercelGenerateResult, type VercelStreamResult, type WrapBAMLOptions, type WrappedBamlFn, __version__, finalizers, flushTraces, getCurrentReplayBranch, getCurrentSpan, getCurrentTrace, reportReplayProgress };
+export { type ActiveSpanContext, type AdaptContext, type AdaptInputsFn, type AllowedEnvVars, BITFAB_PROGRESS_PREFIX, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler as BitfabLangChainCallbackHandler, BitfabLangGraphCallbackHandler, type BitfabLanguageModelMiddleware, BitfabOpenAIAgentHandler, BitfabOpenAITracingProcessor, BitfabVercelAiHandler, type CaptureWhen, type CapturedSpan, type CodeChangeFile, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type DbBranchOptions, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, type MockOverride, type MockOverrideCtx, type MockStrategy, type MockValue, type NodeMatcher, type ProviderDefinition, ReplayBranch, type ReplayItem, type ReplayOptions, type ReplayProgress, type ReplayResult, SUPPORTED_PROVIDERS, type SpanLookup, type SpanNodeMeta, type SpanOccurrence, type SpanOptions, type SpanType, type TokenUsage, type TraceResponse, type TracingProcessor, type VercelCallParams, type VercelGenerateResult, type VercelStreamResult, type WrapBAMLOptions, type WrappedBamlFn, __version__, finalizers, flushTraces, getCurrentReplayBranch, getCurrentSpan, getCurrentTrace, reportReplayProgress };

package/dist/index.d.ts

@@ -752,8 +752,9 @@ type MockStrategy = "none" | "all" | "marked";
 /**
  * How the DB-snapshot branch each replay item runs against is sized and warmed.
  *
- * Passing this object at all is what turns database branching on, so `{}` means
- * "branch every item, with the mirror project's own defaults".
+ * Every field is optional, so this object is only worth passing when you want
+ * to override the mirror project's own sizing. To branch with those defaults,
+ * pass `dbBranch: true` instead of an empty object.
  */
 interface DbBranchOptions {
     /**
@@ -826,17 +827,17 @@ interface ReplayOptions {
     mockOverride?: MockOverride | MockOverride[];
     /**
      * Run each item against a database branch restored to the state its source
-     * trace saw. Passing this object at all turns branching on, so `{}` enables
-     * it with the mirror project's own sizing; the fields tune how each branch is
-     * sized and warmed. Inside `fn`, read the resolved branch with
-     * `getCurrentReplayBranch()`.
+     * trace saw. Pass `true` to branch with the mirror project's own sizing, or a
+     * {@link DbBranchOptions} object to tune how each branch is sized and warmed.
+     * `false` and omission leave branching off. Inside `fn`, read the resolved
+     * branch with `getCurrentReplayBranch()`.
      *
      * Items whose source trace carried no DB snapshot reference get no branch and
      * run against the live database. An item whose branch was requested but could
      * not be resolved fails instead of running, so a replay never silently
      * reports a result that did not use the historical data you asked for.
      */
-    dbBranch?: DbBranchOptions;
+    dbBranch?: DbBranchOptions | boolean;
     /** Group ID to associate this replay with an experiment group for live streaming in Studio. */
     experimentGroupId?: string;
     /**
@@ -1419,6 +1420,12 @@ interface BitfabConfig {
  * - custom: Application-specific tracing (default)
  */
 type SpanType = "llm" | "agent" | "function" | "guardrail" | "handoff" | "custom";
+/**
+ * Controls when a span is captured.
+ * - always: Capture the span even when it becomes the root of a new trace.
+ * - nested: Capture the span only when another Bitfab span is already active.
+ */
+type CaptureWhen = "always" | "nested";
 /**
  * Options for configuring span behavior.
  */
@@ -1432,6 +1439,14 @@ interface SpanOptions {
      * The type of span. Defaults to "custom" if not specified.
      */
     type?: SpanType;
+    /**
+     * Controls whether this span may start a new trace. Defaults to "always".
+     *
+     * Use "nested" for reusable helpers that should appear inside an existing
+     * trace but should run untraced when called on their own.
+     * Unknown values warn once and default to "always".
+     */
+    captureWhen?: CaptureWhen;
     /**
      * When true, replay will reuse this span's historical output instead of
      * executing the wrapped function. Read by the "marked" replay strategy;
@@ -1968,7 +1983,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.33.3";
+declare const __version__ = "0.33.5";
 
 /**
  * Constants for the Bitfab SDK.
@@ -2036,4 +2051,4 @@ declare const finalizers: {
     readableStream: typeof readableStream;
 };
 
-export { type ActiveSpanContext, type AdaptContext, type AdaptInputsFn, type AllowedEnvVars, BITFAB_PROGRESS_PREFIX, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler as BitfabLangChainCallbackHandler, BitfabLangGraphCallbackHandler, type BitfabLanguageModelMiddleware, BitfabOpenAIAgentHandler, BitfabOpenAITracingProcessor, BitfabVercelAiHandler, type CapturedSpan, type CodeChangeFile, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type DbBranchOptions, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, type MockOverride, type MockOverrideCtx, type MockStrategy, type MockValue, type NodeMatcher, type ProviderDefinition, ReplayBranch, type ReplayItem, type ReplayOptions, type ReplayProgress, type ReplayResult, SUPPORTED_PROVIDERS, type SpanLookup, type SpanNodeMeta, type SpanOccurrence, type SpanOptions, type SpanType, type TokenUsage, type TraceResponse, type TracingProcessor, type VercelCallParams, type VercelGenerateResult, type VercelStreamResult, type WrapBAMLOptions, type WrappedBamlFn, __version__, finalizers, flushTraces, getCurrentReplayBranch, getCurrentSpan, getCurrentTrace, reportReplayProgress };
+export { type ActiveSpanContext, type AdaptContext, type AdaptInputsFn, type AllowedEnvVars, BITFAB_PROGRESS_PREFIX, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler as BitfabLangChainCallbackHandler, BitfabLangGraphCallbackHandler, type BitfabLanguageModelMiddleware, BitfabOpenAIAgentHandler, BitfabOpenAITracingProcessor, BitfabVercelAiHandler, type CaptureWhen, type CapturedSpan, type CodeChangeFile, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type DbBranchOptions, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, type MockOverride, type MockOverrideCtx, type MockStrategy, type MockValue, type NodeMatcher, type ProviderDefinition, ReplayBranch, type ReplayItem, type ReplayOptions, type ReplayProgress, type ReplayResult, SUPPORTED_PROVIDERS, type SpanLookup, type SpanNodeMeta, type SpanOccurrence, type SpanOptions, type SpanType, type TokenUsage, type TraceResponse, type TracingProcessor, type VercelCallParams, type VercelGenerateResult, type VercelStreamResult, type WrapBAMLOptions, type WrappedBamlFn, __version__, finalizers, flushTraces, getCurrentReplayBranch, getCurrentSpan, getCurrentTrace, reportReplayProgress };

package/dist/index.js

@@ -14,12 +14,12 @@ import {
   getCurrentReplayBranch,
   getCurrentSpan,
   getCurrentTrace
-} from "./chunk-NIFTE3J4.js";
+} from "./chunk-LRWH3H5T.js";
 import {
   BITFAB_PROGRESS_PREFIX,
   BitfabError,
   reportReplayProgress
-} from "./chunk-HWQB73HK.js";
+} from "./chunk-DPV6PBWE.js";
 export {
   BITFAB_PROGRESS_PREFIX,
   Bitfab,

package/dist/node.cjs

@@ -549,8 +549,11 @@ __export(replay_exports, {
   replay: () => replay,
   reportReplayProgress: () => reportReplayProgress
 });
+function dbBranchEnabled(dbBranch) {
+  return dbBranch !== void 0 && dbBranch !== false;
+}
 function resolveDbBranchSettings(dbBranch) {
-  if (!dbBranch) {
+  if (!dbBranch || dbBranch === true) {
     return void 0;
   }
   const { minCu, maxCu, warmupSql } = dbBranch;
@@ -819,7 +822,7 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
     options?.name,
     codeChangeDescription,
     codeChangeFiles,
-    options?.dbBranch !== void 0,
+    dbBranchEnabled(options?.dbBranch),
     // includeDbBranchLease
     options?.experimentGroupId,
     options?.datasetId,
@@ -842,7 +845,7 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
       mockStrategy,
       resolvedOverrides,
       replayedTraceIds[index],
-      options?.dbBranch !== void 0,
+      dbBranchEnabled(options?.dbBranch),
       resolveDbBranchSettings(options?.dbBranch),
       options?.adaptInputs
     )
@@ -1019,7 +1022,7 @@ registerAsyncLocalStorageClass(
 );
 
 // src/version.generated.ts
-var __version__ = "0.33.3";
+var __version__ = "0.33.5";
 
 // src/constants.ts
 var DEFAULT_SERVICE_URL = "https://bitfab.ai";
@@ -4318,6 +4321,38 @@ var Bitfab = class {
           () => wrappedFn.apply(this, args)
         );
       }
+      const captureWhen = options.captureWhen === void 0 ? "always" : options.captureWhen;
+      const resolvedCaptureWhen = captureWhen === "always" || captureWhen === "nested" ? captureWhen : "always";
+      if (resolvedCaptureWhen !== captureWhen) {
+        let invalidValue;
+        try {
+          invalidValue = String(captureWhen);
+        } catch {
+          invalidValue = "<unprintable>";
+        }
+        warnOnce(
+          `invalid-capture-when:${traceFunctionKey}`,
+          `unknown captureWhen value "${invalidValue}"; defaulting to "always". Valid values: "always", "nested".`
+        );
+      }
+      if (resolvedCaptureWhen === "nested") {
+        let hasParent = false;
+        try {
+          hasParent = getSpanStack().length > 0;
+        } catch (setupError) {
+          if (getReplayContext()) {
+            throw setupError;
+          }
+          warnOnce(
+            `withSpan-setup:${traceFunctionKey}`,
+            `tracing setup failed for "${traceFunctionKey}"; running it untraced. The function still runs and returns normally; no span is recorded.`
+          );
+          return fn.apply(this, args);
+        }
+        if (!hasParent) {
+          return fn.apply(this, args);
+        }
+      }
       let newStack;
       let executeWithContext;
       let registeredTraceId;