@bitfab/sdk 0.33.2 → 0.33.4

package/dist/index.d.cts

@@ -794,15 +794,20 @@ interface ReplayOptions {
     /**
      * Description of the code change being tested in this replay. Stored on
      * the resulting experiment so the change can be reviewed alongside results.
+     * Supplying a description without `codeChangeFiles` preserves this text
+     * while the SDK automatically captures the files.
+     * Pass `null` when the replay should have no description; use
+     * `codeChangeFiles: null` to suppress automatic file capture.
      */
-    codeChangeDescription?: string;
+    codeChangeDescription?: string | null;
     /**
      * Files edited as part of this code change. Each entry holds the file path
      * and the full `before`/`after` contents. The agent reads each file before
      * and after editing and passes the two strings. Use `""` for newly created
-     * files (`before`) or deleted files (`after`).
+     * files (`before`) or deleted files (`after`). Omit this field to capture
+     * automatically, or pass `null` to suppress file capture for this replay.
      */
-    codeChangeFiles?: CodeChangeFile[];
+    codeChangeFiles?: CodeChangeFile[] | null;
     /**
      * Mock strategy for child spans during replay.
      * - "marked": only spans tagged with { mockOnReplay: true } in SpanOptions are mocked (default)
@@ -1414,6 +1419,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.
  */
@@ -1427,6 +1438,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;
@@ -1963,7 +1982,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.33.2";
+declare const __version__ = "0.33.4";
 
 /**
  * Constants for the Bitfab SDK.
@@ -2031,4 +2050,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

@@ -794,15 +794,20 @@ interface ReplayOptions {
     /**
      * Description of the code change being tested in this replay. Stored on
      * the resulting experiment so the change can be reviewed alongside results.
+     * Supplying a description without `codeChangeFiles` preserves this text
+     * while the SDK automatically captures the files.
+     * Pass `null` when the replay should have no description; use
+     * `codeChangeFiles: null` to suppress automatic file capture.
      */
-    codeChangeDescription?: string;
+    codeChangeDescription?: string | null;
     /**
      * Files edited as part of this code change. Each entry holds the file path
      * and the full `before`/`after` contents. The agent reads each file before
      * and after editing and passes the two strings. Use `""` for newly created
-     * files (`before`) or deleted files (`after`).
+     * files (`before`) or deleted files (`after`). Omit this field to capture
+     * automatically, or pass `null` to suppress file capture for this replay.
      */
-    codeChangeFiles?: CodeChangeFile[];
+    codeChangeFiles?: CodeChangeFile[] | null;
     /**
      * Mock strategy for child spans during replay.
      * - "marked": only spans tagged with { mockOnReplay: true } in SpanOptions are mocked (default)
@@ -1414,6 +1419,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.
  */
@@ -1427,6 +1438,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;
@@ -1963,7 +1982,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.33.2";
+declare const __version__ = "0.33.4";
 
 /**
  * Constants for the Bitfab SDK.
@@ -2031,4 +2050,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-A3WLV5VS.js";
+} from "./chunk-OMW6EFXC.js";
 import {
   BITFAB_PROGRESS_PREFIX,
   BitfabError,
   reportReplayProgress
-} from "./chunk-GT2GSQM2.js";
+} from "./chunk-HWQB73HK.js";
 export {
   BITFAB_PROGRESS_PREFIX,
   Bitfab,

package/dist/node.cjs

@@ -797,11 +797,13 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
   await replayContextReady;
   let codeChangeDescription = options?.codeChangeDescription;
   let codeChangeFiles = options?.codeChangeFiles;
-  if (codeChangeDescription === void 0 && codeChangeFiles === void 0) {
+  if (codeChangeFiles === void 0) {
     const captured = await resolveAutoCodeChange(options?.name);
     if (captured) {
-      codeChangeDescription = captured.description;
       codeChangeFiles = captured.files;
+      if (codeChangeDescription === void 0) {
+        codeChangeDescription = captured.description;
+      }
     }
   }
   const {
@@ -1017,7 +1019,7 @@ registerAsyncLocalStorageClass(
 );
 
 // src/version.generated.ts
-var __version__ = "0.33.2";
+var __version__ = "0.33.4";
 
 // src/constants.ts
 var DEFAULT_SERVICE_URL = "https://bitfab.ai";
@@ -4316,6 +4318,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;