@bitfab/sdk 0.38.6 → 0.38.8

package/dist/index.d.cts

@@ -1072,6 +1072,7 @@ declare class BitfabLangGraphCallbackHandler {
     private readonly ownsHttpClient;
     private readonly traceFunctionKey;
     private readonly getActiveSpanContext;
+    private readonly captureTools;
     private runToSpan;
     private invocations;
     constructor(config: {
@@ -1080,6 +1081,8 @@ declare class BitfabLangGraphCallbackHandler {
         serviceUrl?: string;
         timeout?: number;
         getActiveSpanContext?: () => ActiveSpanContext$1 | null;
+        /** Whether callback tool events should emit spans. Defaults to true. */
+        captureTools?: boolean;
         /**
          * The owning `Bitfab` client's HTTP client. Supplied by
          * `getLangGraphCallbackHandler()` so this handler shares that client's
@@ -1115,6 +1118,79 @@ declare class BitfabLangGraphCallbackHandler {
     handleRetrieverError(error: unknown, runId: string): Promise<void>;
 }
 
+interface SpanClient {
+    withSpan<TArgs extends unknown[], TReturn>(traceFunctionKey: string, options: {
+        name?: string;
+        type?: "agent" | "function";
+        captureWhen?: "always" | "nested";
+        mockOnReplay?: boolean;
+        finalize?: (result: unknown) => unknown | Promise<unknown>;
+    }, fn: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
+}
+interface LangGraphTool {
+    readonly name?: string;
+    invoke(input: unknown, ...rest: unknown[]): unknown;
+}
+interface ConfiguredLangGraphRunnable<TInput, TConfig, TReturn> {
+    invoke(input: TInput, config?: TConfig): TReturn;
+}
+interface LangGraphRunnable<TInput, TConfig, TReturn> {
+    withConfig(config: {
+        callbacks: unknown[];
+    }): ConfiguredLangGraphRunnable<TInput, TConfig, TReturn>;
+}
+/**
+ * Options for first-class LangGraph ToolNode replay interception.
+ *
+ * @experimental This API may change before it is stable.
+ */
+interface LangGraphIntegrationOptions {
+    /**
+     * Tools marked for recorded-output mocking under replay's default
+     * `mock: "marked"` strategy. Defaults to every wrapped tool. Pass a list to
+     * mark only those tool names, or `false` to require `mock: "all"` or an
+     * override.
+     */
+    mockToolsOnReplay?: boolean | readonly string[];
+}
+/**
+ * First-class LangGraph integration for callback tracing and replayable
+ * `ToolNode` tools.
+ *
+ * @experimental This API may change before it is stable.
+ */
+declare class BitfabLangGraphIntegration {
+    /** Callback handler for the compiled graph's invocation config. */
+    readonly callbackHandler: any;
+    private readonly client;
+    private readonly traceFunctionKey;
+    private readonly mockToolsOnReplay;
+    constructor(config: {
+        client: SpanClient;
+        traceFunctionKey: string;
+        callbackHandler: BitfabLangGraphCallbackHandler;
+        options?: LangGraphIntegrationOptions;
+    });
+    /**
+     * Wrap tools before passing the same returned array to both
+     * `model.bindTools()` and `new ToolNode()`. Each invocation becomes an
+     * independently mockable child span.
+     */
+    wrapTools<T extends readonly LangGraphTool[]>(tools: T): T;
+    /**
+     * Create the normal graph entry point. The returned function adds Bitfab's
+     * callback handler, preserves invocation config, and records only the graph
+     * input as the replayable root input.
+     *
+     * @experimental This API may change before it is stable.
+     */
+    createInvoker<TInput, TConfig, TReturn>(graph: LangGraphRunnable<TInput, TConfig, TReturn>): (input: TInput, config?: TConfig) => TReturn;
+    private wrapTool;
+    private assertReplayToolResultExists;
+    /** Wrap the function that invokes the compiled graph as the replay root. */
+    wrapInvoke<TArgs extends unknown[], TReturn>(fn: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
+}
+
 /**
  * OpenAI Agents SDK handler for Bitfab tracing.
  *
@@ -1805,13 +1881,14 @@ declare class BitfabOpenAITracingProcessor implements TracingProcessor {
      */
     onTraceEnd(trace: Trace): Promise<void>;
     /**
-     * Called when a span is started.
+     * Called when a span is started. Span payloads are authoritative completed
+     * snapshots, so start notifications do not cross the transport boundary.
      */
-    onSpanStart(span: Span<any>): Promise<void>;
+    onSpanStart(_span: Span<any>): Promise<void>;
     /**
      * Called when a span is ended.
      *
-     * Send all spans to Bitfab for complete trace capture.
+     * Send the finalized span snapshot to Bitfab for complete trace capture.
      */
     onSpanEnd(span: Span<any>): Promise<void>;
     /**
@@ -2372,6 +2449,19 @@ declare class Bitfab {
      * @returns A BitfabLangGraphCallbackHandler configured for this client
      */
     getLangChainCallbackHandler(traceFunctionKey: string): BitfabLangGraphCallbackHandler;
+    /**
+     * Get the first-class LangGraph integration for tracing and replaying tools
+     * executed by `ToolNode`.
+     *
+     * The integration combines `wrapTools()` for per-tool replay interception
+     * with `createInvoker()` for a callback-configured replayable graph entry
+     * point. Lower-level callback and root wrappers remain available.
+     *
+     * @param traceFunctionKey - Groups traces under this key in Bitfab
+     * @param options - Controls which tools are marked for replay mocking
+     * @experimental This API may change before it is stable.
+     */
+    getLangGraphIntegration(traceFunctionKey: string, options?: LangGraphIntegrationOptions): BitfabLangGraphIntegration;
     /**
      * Get a Claude Agent SDK handler for tracing.
      *
@@ -2763,6 +2853,12 @@ declare class BitfabFunction {
      * @returns A LangChain callback handler for this client and key
      */
     getLangChainCallbackHandler(): BitfabLangGraphCallbackHandler;
+    /**
+     * Get the first-class LangGraph tool replay integration bound to this key.
+     *
+     * @experimental This API may change before it is stable.
+     */
+    getLangGraphIntegration(options?: LangGraphIntegrationOptions): BitfabLangGraphIntegration;
     /**
      * Wrap a BAML client method to automatically capture prompt and LLM metadata.
      * Delegates to the parent client's wrapBAML method.
@@ -2789,7 +2885,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.38.6";
+declare const __version__ = "0.38.8";
 
 /**
  * Constants for the Bitfab SDK.
@@ -2892,4 +2988,4 @@ type ReplayRegistry = Record<string, ReplayRegistration>;
  */
 declare function defineReplayRegistry<TRegistry extends ReplayRegistry>(registry: TRegistry): TRegistry;
 
-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, DbBranchReplayError, type DbBranchTimings, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, HttpClient, type MockOverride, type MockOverrideCtx, type MockOverrideInput, type MockOverrideResolver, type MockStrategy, type MockValue, NO_MOCK_OVERRIDE, type NodeMatcher, type NodeMethodDecorator, type NodeOptions, type ProviderDefinition, ReplayBranch, ReplayError, type ReplayItem, type ReplayItemFinishProgress, type ReplayItemStartProgress, type ReplayOptions, type ReplayOptionsFactory, type ReplayProgress, type ReplayProgressItem, type ReplayRegistration, type ReplayRegistry, type ReplayRegistryContext, type ReplayRegistryOptions, type ReplayResult, SUPPORTED_PROVIDERS, type SpanLookup, type SpanMethodDecorator, type SpanMethodDecoratorContext, 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__, defineReplayRegistry, finalizers, flushTraces, getCurrentReplayBranch, getCurrentSpan, getCurrentTrace, reportReplayProgress, serializeReplayResult };
+export { type ActiveSpanContext, type AdaptContext, type AdaptInputsFn, type AllowedEnvVars, BITFAB_PROGRESS_PREFIX, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler as BitfabLangChainCallbackHandler, BitfabLangGraphCallbackHandler, BitfabLangGraphIntegration, type BitfabLanguageModelMiddleware, BitfabOpenAIAgentHandler, BitfabOpenAITracingProcessor, BitfabVercelAiHandler, type CaptureWhen, type CapturedSpan, type CodeChangeFile, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type DbBranchOptions, DbBranchReplayError, type DbBranchTimings, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, HttpClient, type LangGraphIntegrationOptions, type MockOverride, type MockOverrideCtx, type MockOverrideInput, type MockOverrideResolver, type MockStrategy, type MockValue, NO_MOCK_OVERRIDE, type NodeMatcher, type NodeMethodDecorator, type NodeOptions, type ProviderDefinition, ReplayBranch, ReplayError, type ReplayItem, type ReplayItemFinishProgress, type ReplayItemStartProgress, type ReplayOptions, type ReplayOptionsFactory, type ReplayProgress, type ReplayProgressItem, type ReplayRegistration, type ReplayRegistry, type ReplayRegistryContext, type ReplayRegistryOptions, type ReplayResult, SUPPORTED_PROVIDERS, type SpanLookup, type SpanMethodDecorator, type SpanMethodDecoratorContext, 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__, defineReplayRegistry, finalizers, flushTraces, getCurrentReplayBranch, getCurrentSpan, getCurrentTrace, reportReplayProgress, serializeReplayResult };

package/dist/index.d.ts

@@ -1072,6 +1072,7 @@ declare class BitfabLangGraphCallbackHandler {
     private readonly ownsHttpClient;
     private readonly traceFunctionKey;
     private readonly getActiveSpanContext;
+    private readonly captureTools;
     private runToSpan;
     private invocations;
     constructor(config: {
@@ -1080,6 +1081,8 @@ declare class BitfabLangGraphCallbackHandler {
         serviceUrl?: string;
         timeout?: number;
         getActiveSpanContext?: () => ActiveSpanContext$1 | null;
+        /** Whether callback tool events should emit spans. Defaults to true. */
+        captureTools?: boolean;
         /**
          * The owning `Bitfab` client's HTTP client. Supplied by
          * `getLangGraphCallbackHandler()` so this handler shares that client's
@@ -1115,6 +1118,79 @@ declare class BitfabLangGraphCallbackHandler {
     handleRetrieverError(error: unknown, runId: string): Promise<void>;
 }
 
+interface SpanClient {
+    withSpan<TArgs extends unknown[], TReturn>(traceFunctionKey: string, options: {
+        name?: string;
+        type?: "agent" | "function";
+        captureWhen?: "always" | "nested";
+        mockOnReplay?: boolean;
+        finalize?: (result: unknown) => unknown | Promise<unknown>;
+    }, fn: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
+}
+interface LangGraphTool {
+    readonly name?: string;
+    invoke(input: unknown, ...rest: unknown[]): unknown;
+}
+interface ConfiguredLangGraphRunnable<TInput, TConfig, TReturn> {
+    invoke(input: TInput, config?: TConfig): TReturn;
+}
+interface LangGraphRunnable<TInput, TConfig, TReturn> {
+    withConfig(config: {
+        callbacks: unknown[];
+    }): ConfiguredLangGraphRunnable<TInput, TConfig, TReturn>;
+}
+/**
+ * Options for first-class LangGraph ToolNode replay interception.
+ *
+ * @experimental This API may change before it is stable.
+ */
+interface LangGraphIntegrationOptions {
+    /**
+     * Tools marked for recorded-output mocking under replay's default
+     * `mock: "marked"` strategy. Defaults to every wrapped tool. Pass a list to
+     * mark only those tool names, or `false` to require `mock: "all"` or an
+     * override.
+     */
+    mockToolsOnReplay?: boolean | readonly string[];
+}
+/**
+ * First-class LangGraph integration for callback tracing and replayable
+ * `ToolNode` tools.
+ *
+ * @experimental This API may change before it is stable.
+ */
+declare class BitfabLangGraphIntegration {
+    /** Callback handler for the compiled graph's invocation config. */
+    readonly callbackHandler: any;
+    private readonly client;
+    private readonly traceFunctionKey;
+    private readonly mockToolsOnReplay;
+    constructor(config: {
+        client: SpanClient;
+        traceFunctionKey: string;
+        callbackHandler: BitfabLangGraphCallbackHandler;
+        options?: LangGraphIntegrationOptions;
+    });
+    /**
+     * Wrap tools before passing the same returned array to both
+     * `model.bindTools()` and `new ToolNode()`. Each invocation becomes an
+     * independently mockable child span.
+     */
+    wrapTools<T extends readonly LangGraphTool[]>(tools: T): T;
+    /**
+     * Create the normal graph entry point. The returned function adds Bitfab's
+     * callback handler, preserves invocation config, and records only the graph
+     * input as the replayable root input.
+     *
+     * @experimental This API may change before it is stable.
+     */
+    createInvoker<TInput, TConfig, TReturn>(graph: LangGraphRunnable<TInput, TConfig, TReturn>): (input: TInput, config?: TConfig) => TReturn;
+    private wrapTool;
+    private assertReplayToolResultExists;
+    /** Wrap the function that invokes the compiled graph as the replay root. */
+    wrapInvoke<TArgs extends unknown[], TReturn>(fn: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
+}
+
 /**
  * OpenAI Agents SDK handler for Bitfab tracing.
  *
@@ -1805,13 +1881,14 @@ declare class BitfabOpenAITracingProcessor implements TracingProcessor {
      */
     onTraceEnd(trace: Trace): Promise<void>;
     /**
-     * Called when a span is started.
+     * Called when a span is started. Span payloads are authoritative completed
+     * snapshots, so start notifications do not cross the transport boundary.
      */
-    onSpanStart(span: Span<any>): Promise<void>;
+    onSpanStart(_span: Span<any>): Promise<void>;
     /**
      * Called when a span is ended.
      *
-     * Send all spans to Bitfab for complete trace capture.
+     * Send the finalized span snapshot to Bitfab for complete trace capture.
      */
     onSpanEnd(span: Span<any>): Promise<void>;
     /**
@@ -2372,6 +2449,19 @@ declare class Bitfab {
      * @returns A BitfabLangGraphCallbackHandler configured for this client
      */
     getLangChainCallbackHandler(traceFunctionKey: string): BitfabLangGraphCallbackHandler;
+    /**
+     * Get the first-class LangGraph integration for tracing and replaying tools
+     * executed by `ToolNode`.
+     *
+     * The integration combines `wrapTools()` for per-tool replay interception
+     * with `createInvoker()` for a callback-configured replayable graph entry
+     * point. Lower-level callback and root wrappers remain available.
+     *
+     * @param traceFunctionKey - Groups traces under this key in Bitfab
+     * @param options - Controls which tools are marked for replay mocking
+     * @experimental This API may change before it is stable.
+     */
+    getLangGraphIntegration(traceFunctionKey: string, options?: LangGraphIntegrationOptions): BitfabLangGraphIntegration;
     /**
      * Get a Claude Agent SDK handler for tracing.
      *
@@ -2763,6 +2853,12 @@ declare class BitfabFunction {
      * @returns A LangChain callback handler for this client and key
      */
     getLangChainCallbackHandler(): BitfabLangGraphCallbackHandler;
+    /**
+     * Get the first-class LangGraph tool replay integration bound to this key.
+     *
+     * @experimental This API may change before it is stable.
+     */
+    getLangGraphIntegration(options?: LangGraphIntegrationOptions): BitfabLangGraphIntegration;
     /**
      * Wrap a BAML client method to automatically capture prompt and LLM metadata.
      * Delegates to the parent client's wrapBAML method.
@@ -2789,7 +2885,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.38.6";
+declare const __version__ = "0.38.8";
 
 /**
  * Constants for the Bitfab SDK.
@@ -2892,4 +2988,4 @@ type ReplayRegistry = Record<string, ReplayRegistration>;
  */
 declare function defineReplayRegistry<TRegistry extends ReplayRegistry>(registry: TRegistry): TRegistry;
 
-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, DbBranchReplayError, type DbBranchTimings, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, HttpClient, type MockOverride, type MockOverrideCtx, type MockOverrideInput, type MockOverrideResolver, type MockStrategy, type MockValue, NO_MOCK_OVERRIDE, type NodeMatcher, type NodeMethodDecorator, type NodeOptions, type ProviderDefinition, ReplayBranch, ReplayError, type ReplayItem, type ReplayItemFinishProgress, type ReplayItemStartProgress, type ReplayOptions, type ReplayOptionsFactory, type ReplayProgress, type ReplayProgressItem, type ReplayRegistration, type ReplayRegistry, type ReplayRegistryContext, type ReplayRegistryOptions, type ReplayResult, SUPPORTED_PROVIDERS, type SpanLookup, type SpanMethodDecorator, type SpanMethodDecoratorContext, 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__, defineReplayRegistry, finalizers, flushTraces, getCurrentReplayBranch, getCurrentSpan, getCurrentTrace, reportReplayProgress, serializeReplayResult };
+export { type ActiveSpanContext, type AdaptContext, type AdaptInputsFn, type AllowedEnvVars, BITFAB_PROGRESS_PREFIX, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler as BitfabLangChainCallbackHandler, BitfabLangGraphCallbackHandler, BitfabLangGraphIntegration, type BitfabLanguageModelMiddleware, BitfabOpenAIAgentHandler, BitfabOpenAITracingProcessor, BitfabVercelAiHandler, type CaptureWhen, type CapturedSpan, type CodeChangeFile, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type DbBranchOptions, DbBranchReplayError, type DbBranchTimings, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, HttpClient, type LangGraphIntegrationOptions, type MockOverride, type MockOverrideCtx, type MockOverrideInput, type MockOverrideResolver, type MockStrategy, type MockValue, NO_MOCK_OVERRIDE, type NodeMatcher, type NodeMethodDecorator, type NodeOptions, type ProviderDefinition, ReplayBranch, ReplayError, type ReplayItem, type ReplayItemFinishProgress, type ReplayItemStartProgress, type ReplayOptions, type ReplayOptionsFactory, type ReplayProgress, type ReplayProgressItem, type ReplayRegistration, type ReplayRegistry, type ReplayRegistryContext, type ReplayRegistryOptions, type ReplayResult, SUPPORTED_PROVIDERS, type SpanLookup, type SpanMethodDecorator, type SpanMethodDecoratorContext, 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__, defineReplayRegistry, finalizers, flushTraces, getCurrentReplayBranch, getCurrentSpan, getCurrentTrace, reportReplayProgress, serializeReplayResult };

package/dist/index.js

@@ -3,6 +3,7 @@ import {
   BitfabClaudeAgentHandler,
   BitfabFunction,
   BitfabLangGraphCallbackHandler,
+  BitfabLangGraphIntegration,
   BitfabOpenAIAgentHandler,
   BitfabOpenAITracingProcessor,
   BitfabVercelAiHandler,
@@ -12,7 +13,7 @@ import {
   getCurrentReplayBranch,
   getCurrentSpan,
   getCurrentTrace
-} from "./chunk-P2MYK27A.js";
+} from "./chunk-CKOOG3TW.js";
 import "./chunk-ZUD7OFYB.js";
 import {
   BITFAB_PROGRESS_PREFIX,
@@ -26,7 +27,7 @@ import {
   flushTraces,
   reportReplayProgress,
   serializeReplayResult
-} from "./chunk-QTTKZMHM.js";
+} from "./chunk-VCGFTX2G.js";
 import "./chunk-H6LZRFMN.js";
 export {
   BITFAB_PROGRESS_PREFIX,
@@ -36,6 +37,7 @@ export {
   BitfabFunction,
   BitfabLangGraphCallbackHandler as BitfabLangChainCallbackHandler,
   BitfabLangGraphCallbackHandler,
+  BitfabLangGraphIntegration,
   BitfabOpenAIAgentHandler,
   BitfabOpenAITracingProcessor,
   BitfabVercelAiHandler,