bitfab 0.9.2 → 0.11.4

package/dist/index.d.cts

@@ -32,6 +32,118 @@ type AllowedEnvVars = {
     OPENAI_API_KEY?: string;
 };
 
+/**
+ * Claude Agent SDK handler for Bitfab tracing.
+ *
+ * Hooks into the Claude Agent SDK's lifecycle to capture LLM turns,
+ * tool invocations, and subagent execution as Bitfab spans.
+ *
+ * Uses two integration surfaces:
+ *   1. SDK hooks (PreToolUse, PostToolUse, etc.) for tool/subagent lifecycle
+ *   2. Stream wrapping for LLM turn capture from the message stream
+ */
+interface ActiveSpanContext$2 {
+    traceId: string;
+    spanId: string;
+}
+/**
+ * Claude Agent SDK handler that sends traces to Bitfab.
+ *
+ * Captures LLM turns, tool invocations, and subagent execution as
+ * Bitfab spans with proper parent-child hierarchy.
+ *
+ * ```typescript
+ * import { Bitfab } from "bitfab";
+ * import { ClaudeSDKClient } from "@anthropic-ai/claude-agent-sdk";
+ *
+ * const bitfab = new Bitfab({ apiKey: "..." });
+ * const handler = bitfab.getClaudeAgentHandler("my-agent");
+ *
+ * const options = handler.instrumentOptions({
+ *   model: "claude-sonnet-4-5-...",
+ * });
+ *
+ * const client = new ClaudeSDKClient(options);
+ * await client.connect();
+ * await client.query("Do something");
+ *
+ * for await (const message of handler.wrapResponse(client.receiveResponse())) {
+ *   // process messages normally
+ * }
+ * ```
+ */
+declare class BitfabClaudeAgentHandler {
+    private readonly httpClient;
+    private readonly traceFunctionKey;
+    private readonly getActiveSpanContext;
+    private runToSpan;
+    private traceId;
+    private rootSpanId;
+    private activeContext;
+    private traceStartedAt;
+    private conversationHistory;
+    private pendingMessages;
+    private currentLlmSpanId;
+    private currentLlmMessageId;
+    private currentLlmContent;
+    private currentLlmModel;
+    private currentLlmUsage;
+    private currentLlmStartedAt;
+    private currentLlmHistorySnapshot;
+    private activeSubagentSpans;
+    constructor(config: {
+        apiKey?: string;
+        traceFunctionKey: string;
+        serviceUrl?: string;
+        timeout?: number;
+        getActiveSpanContext?: () => ActiveSpanContext$2 | null;
+    });
+    private ensureTrace;
+    private getParentId;
+    private startSpan;
+    private completeSpan;
+    private sendSpan;
+    private sendTraceCompletion;
+    private preToolUseHook;
+    private postToolUseHook;
+    private postToolUseFailureHook;
+    private subagentStartHook;
+    private subagentStopHook;
+    /**
+     * Inject Bitfab tracing hooks into Claude Agent SDK options.
+     *
+     * Modifies the options object and returns it for convenience.
+     * The SDK's `HookMatcher` is constructed as a plain object
+     * (`{ matcher: null, hooks: [callback] }`) to avoid requiring
+     * `@anthropic-ai/claude-agent-sdk` as a dependency.
+     *
+     * @param options - Options object with a `hooks` property
+     * @returns The modified options object with Bitfab hooks injected
+     */
+    instrumentOptions<T extends Record<string, unknown>>(options: T): T;
+    /**
+     * Wrap a `ClaudeSDKClient.receiveResponse()` stream to capture LLM turns.
+     *
+     * Yields every message unchanged while capturing AssistantMessage
+     * content as LLM turn spans.
+     */
+    wrapResponse(stream: AsyncIterable<unknown>): AsyncIterable<unknown>;
+    /**
+     * Wrap a `query()` async iterator to capture LLM turns.
+     *
+     * Same as `wrapResponse` but for the simpler `query()` API
+     * which does not support hooks (no tool/subagent spans).
+     */
+    wrapQuery(stream: AsyncIterable<unknown>): AsyncIterable<unknown>;
+    private processStream;
+    private processMessage;
+    private handleAssistantMessage;
+    private handleUserMessage;
+    private handleResultMessage;
+    private flushLlmTurn;
+    private resetState;
+}
+
 /**
  * HTTP client utilities for Bitfab API requests.
  *
@@ -53,6 +165,120 @@ declare class BitfabError extends Error {
  * @param timeoutMs - Maximum time to wait in milliseconds (default: 5000)
  */
 declare function flushTraces(timeoutMs?: number): Promise<void>;
+interface TokenUsage {
+    input: number | null;
+    output: number | null;
+    cached: number | null;
+    total: number | null;
+}
+
+/**
+ * LangGraph/LangChain callback handler for Bitfab tracing.
+ *
+ * Hooks into LangGraph's callback system to capture graph node execution,
+ * LLM calls, and tool invocations as Bitfab spans — without requiring users
+ * to wrap their functions with withSpan (which fails on non-serializable args).
+ *
+ * Duck-typed to match LangChain.js's BaseCallbackHandler interface.
+ * No @langchain/core dependency required.
+ */
+interface ActiveSpanContext$1 {
+    traceId: string;
+    spanId: string;
+}
+/**
+ * LangChain/LangGraph callback handler that sends traces to Bitfab.
+ *
+ * Duck-typed to match LangChain.js's BaseCallbackHandler — no
+ * `@langchain/core` dependency required. Pass as a callback:
+ *
+ * ```typescript
+ * const handler = bitfab.getLangGraphCallbackHandler("my-agent");
+ * const result = await agent.invoke(
+ *   { messages: [...] },
+ *   { callbacks: [handler] },
+ * );
+ * ```
+ */
+declare class BitfabLangGraphCallbackHandler {
+    name: string;
+    ignoreRetriever: boolean;
+    ignoreRetry: boolean;
+    ignoreCustomEvent: boolean;
+    private readonly httpClient;
+    private readonly traceFunctionKey;
+    private readonly getActiveSpanContext;
+    private runToSpan;
+    private invocations;
+    constructor(config: {
+        apiKey?: string;
+        traceFunctionKey: string;
+        serviceUrl?: string;
+        timeout?: number;
+        getActiveSpanContext?: () => ActiveSpanContext$1 | null;
+    });
+    private startSpan;
+    private completeSpan;
+    private sendSpan;
+    private sendTraceCompletion;
+    handleChainStart(chain: Record<string, unknown>, inputs: Record<string, unknown>, runId: string, parentRunId?: string, tags?: string[], metadata?: Record<string, unknown>): Promise<void>;
+    handleChainEnd(outputs: Record<string, unknown>, runId: string): Promise<void>;
+    handleChainError(error: unknown, runId: string): Promise<void>;
+    handleChatModelStart(llm: Record<string, unknown>, messages: unknown[][], runId: string, parentRunId?: string, _extraParams?: Record<string, unknown>, tags?: string[], metadata?: Record<string, unknown>): Promise<void>;
+    handleLLMStart(llm: Record<string, unknown>, prompts: string[], runId: string, parentRunId?: string, _extraParams?: Record<string, unknown>, tags?: string[], metadata?: Record<string, unknown>): Promise<void>;
+    handleLLMEnd(output: Record<string, unknown>, runId: string): Promise<void>;
+    handleLLMError(error: unknown, runId: string): Promise<void>;
+    handleLLMNewToken(): Promise<void>;
+    handleToolStart(tool: Record<string, unknown>, input: string, runId: string, parentRunId?: string, tags?: string[], metadata?: Record<string, unknown>): Promise<void>;
+    handleToolEnd(output: unknown, runId: string): Promise<void>;
+    handleToolError(error: unknown, runId: string): Promise<void>;
+    handleRetrieverStart(retriever: Record<string, unknown>, query: string, runId: string, parentRunId?: string, tags?: string[], metadata?: Record<string, unknown>): Promise<void>;
+    handleRetrieverEnd(documents: unknown, runId: string): Promise<void>;
+    handleRetrieverError(error: unknown, runId: string): Promise<void>;
+}
+
+/**
+ * Replay historical traces through a function and create a test run.
+ *
+ * The replay flow has three phases:
+ * 1. Start — fetches historical traces from the server and creates a test run
+ * 2. Execute — re-runs each trace's inputs through the provided function locally
+ * 3. Complete — marks the test run as completed on the server
+ */
+
+interface ReplayOptions {
+    /** Maximum number of traces to replay (1–100, default 5). */
+    limit?: number;
+    /** Optional list of specific trace IDs to replay. */
+    traceIds?: string[];
+    /** Maximum number of items to process in parallel. Set to 1 for sequential. Default 10. */
+    maxConcurrency?: number;
+}
+interface ReplayItem<T> {
+    /** Deserialized inputs from the original trace. */
+    input: unknown[];
+    /** The result returned by the function during replay, or undefined on error. */
+    result: T | undefined;
+    /** The original output from the historical trace. */
+    originalOutput: unknown;
+    /** Error message if the function threw, or null on success. */
+    error: string | null;
+    /** Original trace duration in milliseconds, or null if timestamps are missing. */
+    durationMs: number | null;
+    /** Token usage from the original trace, or null if not captured. */
+    tokens: TokenUsage | null;
+    /** Model name from the original trace, or null if not captured. */
+    model: string | null;
+}
+
+interface ReplayResult<T> {
+    /** Individual replay items with inputs, results, and comparison data. */
+    items: ReplayItem<T>[];
+    /** The test run ID created on the server. */
+    testRunId: string;
+    /** Full URL to view the test run in the dashboard. */
+    testRunUrl: string;
+}
 
 /**
  * Tracing utilities for external trace submission to Bitfab.
@@ -89,7 +315,7 @@ interface TracingProcessor {
  *
  * Example usage:
  * ```typescript
- * import { Bitfab } from '@goharvest/bitfab';
+ * import { Bitfab } from 'bitfab';
  * import { addTraceProcessor } from '@openai/agents';
  *
  * const client = new Bitfab({ apiKey: 'your-api-key' });
@@ -337,6 +563,47 @@ declare class Bitfab {
      * @returns A BitfabOpenAITracingProcessor instance configured for this client
      */
     getOpenAiTracingProcessor(): BitfabOpenAITracingProcessor;
+    /**
+     * Get a LangGraph/LangChain callback handler for tracing.
+     *
+     * The handler captures graph node execution, LLM calls, and tool
+     * invocations as Bitfab spans with proper parent-child hierarchy.
+     *
+     * ```typescript
+     * const handler = client.getLangGraphCallbackHandler("my-agent");
+     * const result = await agent.invoke(
+     *   { messages: [...] },
+     *   { callbacks: [handler] },
+     * );
+     * ```
+     *
+     * @param traceFunctionKey - Groups traces under this key in Bitfab
+     * @returns A BitfabLangGraphCallbackHandler configured for this client
+     */
+    getLangGraphCallbackHandler(traceFunctionKey: string): BitfabLangGraphCallbackHandler;
+    /**
+     * Get a Claude Agent SDK handler for tracing.
+     *
+     * The handler captures LLM turns, tool invocations, and subagent
+     * execution as Bitfab spans with proper parent-child hierarchy.
+     *
+     * ```typescript
+     * const handler = client.getClaudeAgentHandler("my-agent");
+     * const options = handler.instrumentOptions({
+     *   model: "claude-sonnet-4-5-...",
+     * });
+     * const sdkClient = new ClaudeSDKClient(options);
+     * await sdkClient.connect();
+     * await sdkClient.query("Do something");
+     * for await (const msg of handler.wrapResponse(sdkClient.receiveResponse())) {
+     *   // process messages
+     * }
+     * ```
+     *
+     * @param traceFunctionKey - Groups traces under this key in Bitfab
+     * @returns A BitfabClaudeAgentHandler configured for this client
+     */
+    getClaudeAgentHandler(traceFunctionKey: string): BitfabClaudeAgentHandler;
     /**
      * Wrap a BAML client method to automatically capture prompt and LLM metadata.
      *
@@ -447,16 +714,7 @@ declare class Bitfab {
         limit?: number;
         traceIds?: string[];
         maxConcurrency?: number;
-    }): Promise<{
-        items: Array<{
-            input: unknown[];
-            result: TReturn | undefined;
-            originalOutput: unknown;
-            error: string | null;
-        }>;
-        testRunId: string;
-        testRunUrl: string;
-    }>;
+    }): Promise<ReplayResult<TReturn>>;
 }
 /**
  * Represents a Bitfab function that can wrap user functions for tracing.
@@ -519,7 +777,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.9.2";
+declare const __version__ = "0.11.4";
 
 /**
  * Constants for the Bitfab SDK.
@@ -529,40 +787,4 @@ declare const __version__ = "0.9.2";
  */
 declare const DEFAULT_SERVICE_URL = "https://bitfab.ai";
 
-/**
- * Replay historical traces through a function and create a test run.
- *
- * The replay flow has three phases:
- * 1. Start — fetches historical traces from the server and creates a test run
- * 2. Execute — re-runs each trace's inputs through the provided function locally
- * 3. Complete — marks the test run as completed on the server
- */
-
-interface ReplayOptions {
-    /** Maximum number of traces to replay (1–100, default 5). */
-    limit?: number;
-    /** Optional list of specific trace IDs to replay. */
-    traceIds?: string[];
-    /** Maximum number of items to process in parallel. Set to 1 for sequential. Default 10. */
-    maxConcurrency?: number;
-}
-interface ReplayItem<T> {
-    /** Deserialized inputs from the original trace. */
-    input: unknown[];
-    /** The result returned by the function during replay, or undefined on error. */
-    result: T | undefined;
-    /** The original output from the historical trace. */
-    originalOutput: unknown;
-    /** Error message if the function threw, or null on success. */
-    error: string | null;
-}
-interface ReplayResult<T> {
-    /** Individual replay items with inputs, results, and comparison data. */
-    items: ReplayItem<T>[];
-    /** The test run ID created on the server. */
-    testRunId: string;
-    /** Full URL to view the test run in the dashboard. */
-    testRunUrl: string;
-}
-
-export { type ActiveSpanContext, type AllowedEnvVars, type BamlExecutionResult, Bitfab, type BitfabConfig, BitfabError, BitfabFunction, BitfabOpenAITracingProcessor, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type ProviderDefinition, type ReplayItem, type ReplayOptions, type ReplayResult, type SpanOptions, type SpanType, type TraceResponse, type TracingProcessor, type WrapBAMLOptions, type WrappedBamlFn, __version__, flushTraces, getCurrentSpan, getCurrentTrace };
+export { type ActiveSpanContext, type AllowedEnvVars, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler, BitfabOpenAITracingProcessor, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type ProviderDefinition, type ReplayItem, type ReplayOptions, type ReplayResult, type SpanOptions, type SpanType, type TokenUsage, type TraceResponse, type TracingProcessor, type WrapBAMLOptions, type WrappedBamlFn, __version__, flushTraces, getCurrentSpan, getCurrentTrace };