@bitfab/sdk 0.33.3 → 0.33.4

package/dist/index.d.cts

@@ -1419,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.
  */
@@ -1432,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;
@@ -1968,7 +1982,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.33.3";
+declare const __version__ = "0.33.4";
 
 /**
  * Constants for the Bitfab SDK.
@@ -2036,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

@@ -1419,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.
  */
@@ -1432,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;
@@ -1968,7 +1982,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.33.3";
+declare const __version__ = "0.33.4";
 
 /**
  * Constants for the Bitfab SDK.
@@ -2036,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,7 +14,7 @@ import {
   getCurrentReplayBranch,
   getCurrentSpan,
   getCurrentTrace
-} from "./chunk-NIFTE3J4.js";
+} from "./chunk-OMW6EFXC.js";
 import {
   BITFAB_PROGRESS_PREFIX,
   BitfabError,

package/dist/node.cjs

@@ -1019,7 +1019,7 @@ registerAsyncLocalStorageClass(
 );
 
 // src/version.generated.ts
-var __version__ = "0.33.3";
+var __version__ = "0.33.4";
 
 // src/constants.ts
 var DEFAULT_SERVICE_URL = "https://bitfab.ai";
@@ -4318,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;