@bitfab/sdk 0.13.0

package/dist/index.d.ts

@@ -0,0 +1,888 @@
+import { Trace, Span } from '@openai/agents';
+
+/**
+ * BAML execution utilities for the Bitfab TypeScript SDK.
+ * This module provides functions to execute BAML prompts dynamically on the client side.
+ */
+/**
+ * Provider definition from the server.
+ */
+interface ProviderDefinition {
+    provider: string;
+    apiKeyEnv: string;
+    models: Array<{
+        model: string;
+        description: string;
+    }>;
+}
+/**
+ * Result of a BAML function execution with raw collector data.
+ */
+interface BamlExecutionResult {
+    /** The parsed result of the function */
+    result: unknown;
+    /** Raw collector data for the server to parse */
+    rawCollector: Record<string, unknown> | null;
+}
+/**
+ * Type for allowed environment variables.
+ * Only OPENAI_API_KEY is currently supported.
+ */
+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.
+ *
+ * This module provides:
+ * - HttpClient class for making API requests
+ * - awaitOnExit helper for fire-and-forget operations that must complete before process exit
+ */
+/**
+ * Error class for Bitfab API errors.
+ */
+declare class BitfabError extends Error {
+    readonly url?: string | undefined;
+    constructor(message: string, url?: string | undefined);
+}
+/**
+ * Wait for all pending fire-and-forget operations (spans, traces) to complete.
+ * Useful in tests and scripts to ensure all data has been sent before asserting or exiting.
+ *
+ * @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;
+}
+/**
+ * Describes a single file edited as part of a code change.
+ *
+ * - `path`: file path (relative to the repo root, or any consistent root)
+ * - `before`: file contents before the change ("" for newly created files)
+ * - `after`: file contents after the change ("" for deleted files)
+ */
+interface CodeChangeFile {
+    path: string;
+    before: string;
+    after: string;
+}
+
+/**
+ * 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
+ */
+
+type MockStrategy = "none" | "all" | "marked";
+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;
+    /**
+     * Description of the code change being tested in this replay. Stored on
+     * the resulting experiment so the change can be reviewed alongside results.
+     */
+    codeChangeDescription?: string;
+    /**
+     * 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`).
+     */
+    codeChangeFiles?: CodeChangeFile[];
+    /**
+     * Mock strategy for child spans during replay.
+     * - "none": everything runs real code (default)
+     * - "all": every child withSpan returns historical output
+     * - "marked": only spans tagged with { mockOnReplay: true } in SpanOptions are mocked
+     */
+    mock?: MockStrategy;
+}
+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.
+ *
+ * This module provides utilities for sending external traces (e.g., from OpenAI API calls)
+ * to Bitfab for monitoring and analysis.
+ */
+
+interface TraceResponse {
+    traceId: string;
+    status: "success";
+}
+interface ActiveSpanContext {
+    traceId: string;
+    spanId: string;
+}
+/**
+ * TracingProcessor interface from OpenAI Agents SDK v0.3.7
+ */
+interface TracingProcessor {
+    onTraceStart(trace: Trace): Promise<void>;
+    onTraceEnd(trace: Trace): Promise<void>;
+    onSpanStart(span: Span<any>): Promise<void>;
+    onSpanEnd(span: Span<any>): Promise<void>;
+    forceFlush(): Promise<void>;
+    shutdown(timeout?: number): Promise<void>;
+}
+/**
+ * Tracing processor for OpenAI Agents SDK integration.
+ *
+ * Implements the TracingProcessor interface from the OpenAI Agents SDK to
+ * automatically capture traces and spans and send them to Bitfab for
+ * monitoring and analysis.
+ *
+ * Example usage:
+ * ```typescript
+ * import { Bitfab } from 'bitfab';
+ * import { addTraceProcessor } from '@openai/agents';
+ *
+ * const client = new Bitfab({ apiKey: 'your-api-key' });
+ * const processor = client.getOpenAiTracingProcessor();
+ * addTraceProcessor(processor);
+ * ```
+ */
+declare class BitfabOpenAITracingProcessor implements TracingProcessor {
+    private readonly httpClient;
+    private activeTraces;
+    private readonly getActiveSpanContext;
+    private activeSpanMappings;
+    /**
+     * Initialize the tracing processor.
+     *
+     * @param config - Configuration options
+     */
+    constructor(config: {
+        apiKey?: string;
+        serviceUrl?: string;
+        timeout?: number;
+        getActiveSpanContext?: () => ActiveSpanContext | null;
+    });
+    /**
+     * Called when a trace is started.
+     * If there's an active withSpan context, the trace ID is remapped to the
+     * outer trace and sent to pre-create the external_traces row on the server.
+     */
+    onTraceStart(trace: Trace): Promise<void>;
+    /**
+     * Called when a trace is ended.
+     * If mapped to a withSpan trace, sends with remapped ID and completed=false
+     * since the parent withSpan handles completion.
+     */
+    onTraceEnd(trace: Trace): Promise<void>;
+    /**
+     * Called when a span is started.
+     */
+    onSpanStart(span: Span<any>): Promise<void>;
+    /**
+     * Called when a span is ended.
+     *
+     * Send all spans to Bitfab for complete trace capture.
+     */
+    onSpanEnd(span: Span<any>): Promise<void>;
+    /**
+     * Called when a trace is being flushed.
+     */
+    forceFlush(): Promise<void>;
+    /**
+     * Called when the trace processor is shutting down.
+     */
+    shutdown(_timeout?: number): Promise<void>;
+    /**
+     * Send trace to Bitfab API (fire-and-forget).
+     * When traceIdOverride is provided, the trace ID is remapped to link
+     * the OpenAI trace into an outer withSpan trace.
+     */
+    private sendTrace;
+    /**
+     * Export span to JSON object, collecting any errors.
+     */
+    private exportSpan;
+    /**
+     * Extract and add input/response to serialized span, updating errors list.
+     */
+    private extractSpanInputResponse;
+    /**
+     * If the span's trace is mapped to a withSpan trace, rewrite trace_id and parent_id.
+     */
+    private applySpanOverrides;
+    /**
+     * Build span payload for the external spans API.
+     */
+    private buildSpanPayload;
+    /**
+     * Send span to Bitfab API (fire-and-forget).
+     * If the span belongs to a trace mapped to a withSpan trace, the trace_id
+     * and parent_id are rewritten to link the span into the withSpan tree.
+     */
+    private sendSpan;
+}
+
+/**
+ * Bitfab client for provider-based API calls.
+ */
+
+/**
+ * Options for wrapBAML.
+ */
+interface WrapBAMLOptions {
+    /** Called after each BAML invocation with the Collector instance. */
+    onCollector?: (collector: unknown) => void;
+}
+/**
+ * A function returned by wrapBAML that exposes the BAML collector from the last call.
+ */
+interface WrappedBamlFn<TArgs extends unknown[], TReturn> {
+    (...args: TArgs): Promise<TReturn>;
+    /** The BAML Collector instance from the most recent call. `null` before the first call or if @boundaryml/baml is unavailable. */
+    collector: unknown | null;
+}
+/**
+ * A handle to the current active span, allowing context to be added.
+ */
+interface CurrentSpan {
+    /** The trace ID for the current span. */
+    readonly traceId: string;
+    /**
+     * Add a context entry to this span. Each call appends to the contexts array.
+     * Context entries are stored in span_data.contexts as [{key, value}, ...].
+     */
+    addContext(context: Record<string, unknown>): void;
+    /**
+     * Set the prompt for this span. Stored in span_data.prompt.
+     * Calling multiple times overwrites the previous value.
+     */
+    setPrompt(prompt: string): void;
+}
+/**
+ * A detached handle to a previously-created trace, looked up by its
+ * caller-supplied id (the same id passed when the trace was started).
+ *
+ * Unlike `getCurrentTrace()`, this handle is not tied to AsyncLocalStorage —
+ * each method sends to the server immediately. Useful for adding context
+ * to a trace from a different process, request, or thread (e.g. a forked
+ * agent that wants to annotate the original conversation's trace).
+ */
+interface DetachedTrace {
+    /** The caller-supplied trace id this handle resolves. */
+    readonly traceId: string;
+    /**
+     * Append a context entry to this trace. Each call adds one entry to the
+     * server-side contexts array; existing entries are preserved.
+     *
+     * Returns a promise that the caller may await for confirmation, or ignore
+     * to fire-and-forget. The pending request is tracked so `flushTraces()`
+     * waits for it.
+     */
+    addContext(context: Record<string, unknown>): Promise<unknown>;
+    /**
+     * Merge metadata into this trace. Server-side shallow-merges the new keys
+     * into the existing metadata object; existing keys are preserved unless
+     * overwritten by the new values.
+     */
+    setMetadata(metadata: Record<string, unknown>): Promise<unknown>;
+    /**
+     * Set the sessionId for this trace. Replaces any existing sessionId.
+     */
+    setSessionId(sessionId: string): Promise<unknown>;
+}
+/**
+ * A handle to the current active trace, allowing trace-level context to be set.
+ */
+interface CurrentTrace {
+    /**
+     * Set the session ID for this trace. Stored in the database session_id column.
+     */
+    setSessionId(sessionId: string): void;
+    /**
+     * Set metadata for this trace. Stored in rawData.metadata.
+     * Subsequent calls merge with existing metadata, with later values taking precedence.
+     */
+    setMetadata(metadata: Record<string, unknown>): void;
+    /**
+     * Add a context entry to this trace. Each call appends to the contexts array.
+     * Context entries are stored in rawData.contexts as [{key, value}, ...].
+     */
+    addContext(context: Record<string, unknown>): void;
+}
+/**
+ * Get a handle to the current active span.
+ *
+ * Call this from inside a traced function (wrapped with `withSpan`) to get
+ * a span handle that allows adding context at runtime.
+ *
+ * Returns a no-op object if called outside of a span context (methods do nothing).
+ */
+declare function getCurrentSpan(): CurrentSpan;
+/**
+ * Get a handle to the current active trace.
+ *
+ * Call this from inside a traced function (wrapped with `withSpan`) to get
+ * a trace handle that allows setting trace-level context at runtime.
+ *
+ * Returns a no-op object if called outside of a span context (methods do nothing).
+ */
+declare function getCurrentTrace(): CurrentTrace;
+interface BitfabConfig {
+    /** The API key for Bitfab API authentication. When undefined or empty, tracing is disabled. */
+    apiKey?: string;
+    /** The base URL for the Bitfab API (default: https://bitfab.ai) */
+    serviceUrl?: string;
+    /** Request timeout in milliseconds (default: 120000) */
+    timeout?: number;
+    /** Environment variables for LLM provider API keys (only OPENAI_API_KEY is supported) */
+    envVars?: AllowedEnvVars;
+    /** Whether the client is enabled. Defaults to true. When false, withSpan returns the original function unwrapped. */
+    enabled?: boolean;
+    /** The generated BAML client instance (e.g., `b` from your baml_client). Used by wrapBAML() when no explicit client is passed. */
+    bamlClient?: unknown;
+}
+/**
+ * Span types matching the backend enum.
+ * - llm: LLM API calls
+ * - agent: Autonomous orchestrators
+ * - function: Tool implementations
+ * - guardrail: Safety/validation checks
+ * - handoff: Agent-to-agent transfers
+ * - custom: Application-specific tracing (default)
+ */
+type SpanType = "llm" | "agent" | "function" | "guardrail" | "handoff" | "custom";
+/**
+ * Options for configuring span behavior.
+ */
+interface SpanOptions {
+    /**
+     * The name of the span. Defaults to the function name if available,
+     * otherwise falls back to the trace function key.
+     */
+    name?: string;
+    /**
+     * The type of span. Defaults to "custom" if not specified.
+     */
+    type?: SpanType;
+    /**
+     * When true, replay will reuse this span's historical output instead of
+     * executing the wrapped function. Read by the "marked" replay strategy;
+     * ignored outside replay and under the "all"/"none" strategies.
+     *
+     * Use this for child spans that are expensive (paid LLM/API calls),
+     * slow, or non-deterministic — the root function still runs real code,
+     * only the marked descendants return their recorded output.
+     */
+    mockOnReplay?: boolean;
+}
+
+/**
+ * Client for making provider-based API calls via BAML.
+ */
+declare class Bitfab {
+    private readonly apiKey;
+    private readonly serviceUrl;
+    private readonly timeout;
+    private readonly envVars;
+    private readonly enabled;
+    private readonly httpClient;
+    private readonly bamlClient;
+    /**
+     * Initialize the Bitfab client.
+     *
+     * @param config - Configuration options for the client
+     */
+    constructor(config: BitfabConfig);
+    /**
+     * Fetch the function with its current version and BAML prompt from the server.
+     *
+     * @param methodName - The name of the method to fetch
+     * @returns The function with current version, BAML prompt, and provider definitions
+     * @throws {BitfabError} If the function is not found or an error occurs
+     */
+    private fetchFunctionVersion;
+    /**
+     * Call a method with the given named arguments via BAML execution.
+     *
+     * @param methodName - The name of the method to call
+     * @param inputs - Named arguments to pass to the method
+     * @returns The result of the BAML function execution
+     * @throws {BitfabError} If service_url is not set, or if an error occurs
+     */
+    call<T = unknown>(methodName: string, inputs?: Record<string, unknown>): Promise<T>;
+    /**
+     * Get a tracing processor for OpenAI Agents SDK integration.
+     *
+     * This processor automatically captures traces and spans from the OpenAI Agents SDK
+     * and sends them to Bitfab for monitoring and analysis.
+     *
+     * Example usage:
+     * ```typescript
+     * import { addTraceProcessor } from '@openai/agents';
+     *
+     * const client = new Bitfab({ apiKey: 'your-api-key' });
+     * const processor = client.getOpenAiTracingProcessor();
+     * addTraceProcessor(processor);
+     * ```
+     *
+     * @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.
+     *
+     * Creates a BAML Collector, calls the method through a tracked client,
+     * then extracts rendered messages and token usage — calling setPrompt()
+     * and addContext() on the current span automatically.
+     *
+     * The BAML client can be provided in the constructor or passed explicitly:
+     *
+     * ```typescript
+     * // Option 1: bamlClient in constructor (use wrapBAML with just the method)
+     * const client = new Bitfab({ apiKey: 'your-api-key', bamlClient: b });
+     * const traced = client.withSpan('classify', { type: 'llm' },
+     *   client.wrapBAML(b.ClassifyText)
+     * );
+     *
+     * // Option 2: pass bamlClient at call site
+     * const client = new Bitfab({ apiKey: 'your-api-key' });
+     * const traced = client.withSpan('classify', { type: 'llm' },
+     *   client.wrapBAML(b, b.ClassifyText)
+     * );
+     * ```
+     *
+     * @param methodOrClient - Either a BAML method (uses constructor bamlClient) or the BAML client instance
+     * @param maybeMethodOrOptions - The BAML method when the first argument is a client, or WrapBAMLOptions when the first argument is the method
+     * @param maybeOptions - WrapBAMLOptions when using the two-argument (client, method) form
+     * @returns An async function with the same signature that instruments the BAML call
+     */
+    wrapBAML<TArgs extends unknown[], TReturn>(methodOrClient: unknown, maybeMethodOrOptions?: ((...args: TArgs) => Promise<TReturn>) | WrapBAMLOptions, maybeOptions?: WrapBAMLOptions): WrappedBamlFn<TArgs, TReturn>;
+    /**
+     * Wrap a function to automatically create a span for its inputs and outputs.
+     *
+     * The wrapped function behaves identically to the original, but sends
+     * span data to Bitfab in the background after each call.
+     *
+     * Example usage:
+     * ```typescript
+     * const client = new Bitfab({ apiKey: 'your-api-key' });
+     *
+     * async function processOrder(orderId: string, items: string[]): Promise<{ total: number }> {
+     *   // ... process order
+     *   return { total: 100 };
+     * }
+     *
+     * // Basic usage (defaults to "custom" span type)
+     * const tracedProcessOrder = client.withSpan('order-processing', processOrder);
+     *
+     * // With explicit span type
+     * const tracedProcessOrder = client.withSpan('order-processing', { type: 'function' }, processOrder);
+     *
+     * // Call the wrapped function normally
+     * const result = await tracedProcessOrder('order-123', ['item-1', 'item-2']);
+     * // Span is automatically sent to Bitfab
+     * ```
+     *
+     * @param traceFunctionKey - A string identifier for grouping spans (e.g., 'order-processing', 'user-auth')
+     * @param optionsOrFn - Either SpanOptions or the function to wrap
+     * @param maybeFn - The function to wrap if options were provided
+     * @returns A wrapped function with the same signature that creates spans for inputs and outputs
+     */
+    withSpan<TArgs extends unknown[], TReturn>(traceFunctionKey: string, optionsOrFn: SpanOptions | ((...args: TArgs) => TReturn), maybeFn?: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
+    /**
+     * Get a detached handle to a previously-created trace, looked up by the
+     * caller-supplied id (the same id passed at trace creation).
+     *
+     * The returned handle is not tied to AsyncLocalStorage — each method sends
+     * to the server immediately. Useful for adding context to a trace from a
+     * different process or thread than the one that created it.
+     *
+     * Throws synchronously if `traceId` is malformed (empty, too long, or
+     * contains characters outside `[a-zA-Z0-9_\-.:]`). Server returns 404 if
+     * no trace exists with that id in the org; the failure surfaces as a
+     * logged warning (fire-and-forget) or via the awaited promise.
+     *
+     * Example:
+     * ```typescript
+     * const trace = client.getTrace("order_abc_123");
+     * await trace.addContext({ refund_status: "approved" });
+     * await trace.setMetadata({ region: "us-west" });
+     * ```
+     */
+    getTrace(traceId: string): DetachedTrace;
+    /**
+     * Get a function wrapper for a specific trace function key.
+     *
+     * This provides a fluent API alternative to calling withSpan directly,
+     * allowing you to bind the traceFunctionKey once and wrap multiple functions.
+     *
+     * Example usage:
+     * ```typescript
+     * const client = new Bitfab({ apiKey: 'your-api-key' });
+     *
+     * const orderFunc = client.getFunction('order-processing');
+     * const tracedProcessOrder = orderFunc.withSpan(processOrder);
+     * const tracedValidateOrder = orderFunc.withSpan(validateOrder);
+     * ```
+     *
+     * @param traceFunctionKey - A string identifier for grouping spans
+     * @returns A BitfabFunction instance for wrapping functions
+     */
+    getFunction(traceFunctionKey: string): BitfabFunction;
+    /**
+     * Send trace completion when a root span ends.
+     * Internal method to record trace completion with end time.
+     * Fire-and-forget - sends to externalTraces endpoint via httpClient.
+     */
+    private sendTraceCompletion;
+    /**
+     * Send a wrapper span from function execution.
+     * Internal method to record spans when using withSpan.
+     * Fire-and-forget - sends to externalSpans endpoint via httpClient.
+     */
+    private sendWrapperSpan;
+    /**
+     * Replay historical traces through a function and create a test run.
+     *
+     * Fetches the last N traces for the given trace function key, re-runs each
+     * through the provided function, and returns comparison data.
+     *
+     * The function must have been wrapped with `withSpan` — replay injects
+     * `testRunId` via async context so new spans are linked to the test run.
+     *
+     * @param traceFunctionKey - The trace function key to replay
+     * @param fn - The function to replay (must be the return value of `withSpan`)
+     * @param options - Optional replay options (limit, traceIds)
+     * @returns ReplayResult with items, testRunId, and testRunUrl
+     */
+    replay<TReturn>(traceFunctionKey: string, fn: (...args: any[]) => TReturn | Promise<TReturn>, options?: {
+        limit?: number;
+        traceIds?: string[];
+        maxConcurrency?: number;
+        codeChangeDescription?: string;
+        codeChangeFiles?: CodeChangeFile[];
+        mock?: "none" | "all" | "marked";
+    }): Promise<ReplayResult<TReturn>>;
+}
+/**
+ * Represents a Bitfab function that can wrap user functions for tracing.
+ *
+ * This provides a fluent API for binding a traceFunctionKey once and
+ * then wrapping multiple functions with that key.
+ *
+ * Example usage:
+ * ```typescript
+ * const client = new Bitfab({ apiKey: 'your-api-key' });
+ *
+ * const orderFunc = client.getFunction('order-processing');
+ * const tracedProcessOrder = orderFunc.withSpan(processOrder);
+ * const tracedValidateOrder = orderFunc.withSpan(validateOrder);
+ * ```
+ */
+declare class BitfabFunction {
+    private readonly client;
+    private readonly traceFunctionKey;
+    constructor(client: Bitfab, traceFunctionKey: string);
+    /**
+     * Wrap a function to automatically create a span for its inputs and outputs.
+     *
+     * The wrapped function behaves identically to the original, but sends
+     * span data to Bitfab in the background after each call.
+     *
+     * Example usage:
+     * ```typescript
+     * const orderFunc = client.getFunction('order-processing');
+     *
+     * // Basic usage (defaults to "custom" span type)
+     * const tracedProcessOrder = orderFunc.withSpan(processOrder);
+     *
+     * // With explicit span type
+     * const tracedProcessOrder = orderFunc.withSpan({ type: 'function' }, processOrder);
+     * ```
+     *
+     * @param optionsOrFn - Either SpanOptions or the function to wrap
+     * @param maybeFn - The function to wrap if options were provided
+     * @returns A wrapped function with the same signature that creates spans
+     */
+    withSpan<TArgs extends unknown[], TReturn>(optionsOrFn: SpanOptions | ((...args: TArgs) => TReturn), maybeFn?: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
+    /**
+     * Wrap a BAML client method to automatically capture prompt and LLM metadata.
+     * Delegates to the parent client's wrapBAML method.
+     *
+     * @param methodOrClient - Either a BAML method (uses constructor bamlClient) or the BAML client instance
+     * @param maybeMethodOrOptions - The BAML method when the first argument is a client, or WrapBAMLOptions when the first argument is the method
+     * @param maybeOptions - WrapBAMLOptions when using the two-argument (client, method) form
+     * @returns An async function with the same signature that instruments the BAML call
+     */
+    wrapBAML<TArgs extends unknown[], TReturn>(methodOrClient: unknown, maybeMethodOrOptions?: ((...args: TArgs) => Promise<TReturn>) | WrapBAMLOptions, maybeOptions?: WrapBAMLOptions): WrappedBamlFn<TArgs, TReturn>;
+}
+
+/**
+ * Auto-generated version file.
+ * This file is generated by scripts/generate-version.ts during build.
+ * DO NOT EDIT MANUALLY.
+ */
+/**
+ * SDK version from package.json (injected at build time)
+ */
+declare const __version__ = "0.13.0";
+
+/**
+ * Constants for the Bitfab SDK.
+ */
+/**
+ * Default service URL for Bitfab API.
+ */
+declare const DEFAULT_SERVICE_URL = "https://bitfab.ai";
+
+export { type ActiveSpanContext, type AllowedEnvVars, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler, BitfabOpenAITracingProcessor, type CodeChangeFile, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type DetachedTrace, type MockStrategy, 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 };