bitfab 0.9.2 → 0.11.0

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.
  *
@@ -54,6 +166,71 @@ declare class BitfabError extends Error {
  */
 declare function flushTraces(timeoutMs?: number): Promise<void>;
 
+/**
+ * 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>;
+}
+
 /**
  * Tracing utilities for external trace submission to Bitfab.
  *
@@ -89,7 +266,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 +514,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.
      *
@@ -519,7 +737,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.9.2";
+declare const __version__ = "0.11.0";
 
 /**
  * Constants for the Bitfab SDK.
@@ -565,4 +783,4 @@ interface ReplayResult<T> {
     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 TraceResponse, type TracingProcessor, type WrapBAMLOptions, type WrappedBamlFn, __version__, flushTraces, getCurrentSpan, getCurrentTrace };

package/dist/index.d.ts

@@ -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.
  *
@@ -54,6 +166,71 @@ declare class BitfabError extends Error {
  */
 declare function flushTraces(timeoutMs?: number): Promise<void>;
 
+/**
+ * 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>;
+}
+
 /**
  * Tracing utilities for external trace submission to Bitfab.
  *
@@ -89,7 +266,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 +514,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.
      *
@@ -519,7 +737,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.9.2";
+declare const __version__ = "0.11.0";
 
 /**
  * Constants for the Bitfab SDK.
@@ -565,4 +783,4 @@ interface ReplayResult<T> {
     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 TraceResponse, type TracingProcessor, type WrapBAMLOptions, type WrappedBamlFn, __version__, flushTraces, getCurrentSpan, getCurrentTrace };

package/dist/index.js

@@ -1,20 +1,24 @@
 import {
   Bitfab,
+  BitfabClaudeAgentHandler,
   BitfabFunction,
+  BitfabLangGraphCallbackHandler,
   BitfabOpenAITracingProcessor,
   getCurrentSpan,
   getCurrentTrace
-} from "./chunk-WUJR72QY.js";
+} from "./chunk-6EZCV5TU.js";
 import {
   BitfabError,
   DEFAULT_SERVICE_URL,
   __version__,
   flushTraces
-} from "./chunk-VGALEXKQ.js";
+} from "./chunk-C4KRLEXZ.js";
 export {
   Bitfab,
+  BitfabClaudeAgentHandler,
   BitfabError,
   BitfabFunction,
+  BitfabLangGraphCallbackHandler,
   BitfabOpenAITracingProcessor,
   DEFAULT_SERVICE_URL,
   __version__,