bitfab 0.27.1 → 0.28.0

package/dist/index.d.cts

@@ -30,6 +30,91 @@ type AllowedEnvVars = {
     OPENAI_API_KEY?: string;
 };
 
+/**
+ * Per-trace database snapshot ref capture.
+ *
+ * Every root span carries a `DbSnapshotRef` that pins the DB state at trace
+ * open by wall-clock timestamp. Capturing the timestamp is free (no IO) and
+ * harmless, so it happens on every trace regardless of configuration: that
+ * lets any trace be replayed against a historical branch later. A `provider`
+ * is attached only when the customer configured `dbSnapshot`; when absent it
+ * is resolved at replay time. The Bitfab service uses the timestamp to
+ * materialize an ephemeral branch from `customer-main`.
+ */
+declare const SUPPORTED_PROVIDERS: readonly ["neon"];
+type DbSnapshotProvider = (typeof SUPPORTED_PROVIDERS)[number];
+interface DbSnapshotConfig {
+    /** Discriminator for the server-side resolver. */
+    provider: DbSnapshotProvider;
+}
+interface DbSnapshotRef {
+    /**
+     * The wall-clock ISO timestamp the SDK observed immediately before
+     * invoking the wrapped function. The name encodes its provenance:
+     * SDK-observed, wall clock (not monotonic), captured before user code
+     * began executing. Always present.
+     */
+    sdkWallClockBeforeFn: string;
+    /**
+     * The configured provider for server-side branch resolution. Only set when
+     * the customer configured `dbSnapshot`; otherwise the provider is resolved
+     * at replay time.
+     */
+    provider?: DbSnapshotProvider;
+}
+
+/**
+ * Shared error type for Bitfab SDK runtime errors. Lives in its own
+ * module to avoid import cycles between `http.ts` and modules that need
+ * to throw structured errors (e.g. `dbSnapshot.ts` validation).
+ */
+declare class BitfabError extends Error {
+    readonly url?: string | undefined;
+    constructor(message: string, url?: string | undefined);
+}
+
+/**
+ * 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
+ */
+
+/**
+ * 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>;
+/**
+ * How the API key is supplied internally: either a literal string or a
+ * function resolved each time the key is needed (at request/send time). The
+ * function form is what defers key resolution past module-load construction
+ * so an env var loaded after the client is built (the ESM dotenv-hoisting
+ * case) is still picked up.
+ */
+type ApiKeyInput = string | (() => string | undefined);
+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;
+}
+
 /**
  * Claude Agent SDK handler for Bitfab tracing.
  *
@@ -40,6 +125,7 @@ type AllowedEnvVars = {
  *   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;
@@ -96,7 +182,7 @@ declare class BitfabClaudeAgentHandler {
     private rootInput;
     private rootOutput;
     constructor(config: {
-        apiKey?: string;
+        apiKey?: ApiKeyInput;
         traceFunctionKey: string;
         serviceUrl?: string;
         timeout?: number;
@@ -285,83 +371,6 @@ declare class BitfabVercelAiHandler {
     get middleware(): BitfabLanguageModelMiddleware;
 }
 
-/**
- * Per-trace database snapshot ref capture.
- *
- * Every root span carries a `DbSnapshotRef` that pins the DB state at trace
- * open by wall-clock timestamp. Capturing the timestamp is free (no IO) and
- * harmless, so it happens on every trace regardless of configuration: that
- * lets any trace be replayed against a historical branch later. A `provider`
- * is attached only when the customer configured `dbSnapshot`; when absent it
- * is resolved at replay time. The Bitfab service uses the timestamp to
- * materialize an ephemeral branch from `customer-main`.
- */
-declare const SUPPORTED_PROVIDERS: readonly ["neon"];
-type DbSnapshotProvider = (typeof SUPPORTED_PROVIDERS)[number];
-interface DbSnapshotConfig {
-    /** Discriminator for the server-side resolver. */
-    provider: DbSnapshotProvider;
-}
-interface DbSnapshotRef {
-    /**
-     * The wall-clock ISO timestamp the SDK observed immediately before
-     * invoking the wrapped function. The name encodes its provenance:
-     * SDK-observed, wall clock (not monotonic), captured before user code
-     * began executing. Always present.
-     */
-    sdkWallClockBeforeFn: string;
-    /**
-     * The configured provider for server-side branch resolution. Only set when
-     * the customer configured `dbSnapshot`; otherwise the provider is resolved
-     * at replay time.
-     */
-    provider?: DbSnapshotProvider;
-}
-
-/**
- * Shared error type for Bitfab SDK runtime errors. Lives in its own
- * module to avoid import cycles between `http.ts` and modules that need
- * to throw structured errors (e.g. `dbSnapshot.ts` validation).
- */
-declare class BitfabError extends Error {
-    readonly url?: string | undefined;
-    constructor(message: string, url?: string | undefined);
-}
-
-/**
- * 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
- */
-
-/**
- * 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.
  *
@@ -372,6 +381,7 @@ interface CodeChangeFile {
  * Duck-typed to match LangChain.js's BaseCallbackHandler interface.
  * No @langchain/core dependency required.
  */
+
 interface ActiveSpanContext$1 {
     traceId: string;
     spanId: string;
@@ -401,7 +411,7 @@ declare class BitfabLangGraphCallbackHandler {
     private runToSpan;
     private invocations;
     constructor(config: {
-        apiKey?: string;
+        apiKey?: ApiKeyInput;
         traceFunctionKey: string;
         serviceUrl?: string;
         timeout?: number;
@@ -411,18 +421,19 @@ declare class BitfabLangGraphCallbackHandler {
     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>;
+    private sendTraceStart;
+    handleChainStart(chain: Record<string, unknown> | null | undefined, inputs: Record<string, unknown>, runId: string, parentRunIdOrRunType?: string, tags?: string[], metadata?: Record<string, unknown>, runTypeOrRunName?: string, runNameOrParentRunId?: string): 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>;
+    handleChatModelStart(llm: Record<string, unknown> | null | undefined, messages: unknown[][], runId: string, parentRunId?: string, _extraParams?: Record<string, unknown>, tags?: string[], metadata?: Record<string, unknown>, runName?: string): Promise<void>;
+    handleLLMStart(llm: Record<string, unknown> | null | undefined, prompts: string[], runId: string, parentRunId?: string, _extraParams?: Record<string, unknown>, tags?: string[], metadata?: Record<string, unknown>, runName?: string): 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>;
+    handleToolStart(tool: Record<string, unknown> | null | undefined, input: string, runId: string, parentRunId?: string, tags?: string[], metadata?: Record<string, unknown>, runName?: string): 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>;
+    handleRetrieverStart(retriever: Record<string, unknown> | null | undefined, query: string, runId: string, parentRunId?: string, tags?: string[], metadata?: Record<string, unknown>, runName?: string): Promise<void>;
     handleRetrieverEnd(documents: unknown, runId: string): Promise<void>;
     handleRetrieverError(error: unknown, runId: string): Promise<void>;
 }
@@ -781,6 +792,7 @@ interface ReplayResult<T> {
  * This module provides utilities for sending external traces (e.g., from OpenAI API calls)
  * to Bitfab for monitoring and analysis.
  */
+
 interface Trace {
     traceId: string;
     toJSON(): unknown;
@@ -841,7 +853,7 @@ declare class BitfabOpenAITracingProcessor implements TracingProcessor {
      * @param config - Configuration options
      */
     constructor(config: {
-        apiKey?: string;
+        apiKey?: ApiKeyInput;
         serviceUrl?: string;
         timeout?: number;
         getActiveSpanContext?: () => ActiveSpanContext | null;
@@ -1008,8 +1020,19 @@ declare function getCurrentSpan(): CurrentSpan;
  */
 declare function getCurrentTrace(): CurrentTrace;
 interface BitfabConfig {
-    /** The API key for Bitfab API authentication. When undefined or empty, tracing is disabled. */
-    apiKey?: string;
+    /**
+     * The API key for Bitfab API authentication. Resolved lazily, the first
+     * time a span actually needs it, not at construction. When it resolves
+     * empty, tracing is disabled (a no-op, unless `strict` is set).
+     *
+     * Accepts either a string or a function returning the key. The function
+     * form is resolved at first use, so it survives the ESM trap where a shim
+     * built at module load runs before the script body's `dotenv.config()`:
+     * `apiKey: () => process.env.BITFAB_API_KEY`. When omitted (or it resolves
+     * empty), the SDK also falls back to reading `BITFAB_API_KEY` from the
+     * environment itself, again at first use.
+     */
+    apiKey?: string | (() => string | null | undefined);
     /** The base URL for the Bitfab API (default: https://bitfab.ai) */
     serviceUrl?: string;
     /** Request timeout in milliseconds (default: 120000) */
@@ -1018,6 +1041,14 @@ interface BitfabConfig {
     envVars?: AllowedEnvVars;
     /** Whether the client is enabled. Defaults to true. When false, withSpan returns the original function unwrapped. */
     enabled?: boolean;
+    /**
+     * Fail loud instead of degrading quietly. When true, the first traced call
+     * with no resolvable API key throws a `BitfabError` rather than silently
+     * disabling tracing. Off by default so a missing telemetry key never takes
+     * down the host app; turn it on in standalone scripts where a run that
+     * emits no traces is a failure you want surfaced immediately.
+     */
+    strict?: boolean;
     /** The generated BAML client instance (e.g., `b` from your baml_client). Used by wrapBAML() when no explicit client is passed. */
     bamlClient?: unknown;
     /**
@@ -1092,11 +1123,17 @@ declare class Bitfab {
      * function to pick up the per-trace branch URL.
      */
     static readonly ReplayEnvironment: typeof ReplayEnvironment;
-    private readonly apiKey;
+    private readonly apiKeyConfig;
+    /** Cached only once a non-empty key is found, so an early resolve (before env loaded) can't poison a later one. */
+    private resolvedApiKey;
+    /** Gate the empty-key warning to fire at most once. */
+    private apiKeyWarned;
     private readonly serviceUrl;
     private readonly timeout;
     private readonly envVars;
-    private readonly enabled;
+    /** The user's on/off intent. The effective enabled state ANDs this with "a key resolved" (see isTracingEnabled). */
+    private readonly explicitlyEnabled;
+    private readonly strict;
     private readonly httpClient;
     private readonly bamlClient;
     private readonly dbSnapshot;
@@ -1106,6 +1143,28 @@ declare class Bitfab {
      * @param config - Configuration options for the client
      */
     constructor(config: BitfabConfig);
+    /**
+     * Resolve the API key lazily, the first time a span actually needs it.
+     *
+     * The key is intentionally NOT read at construction. In ESM, a shim that
+     * does `new Bitfab({ apiKey: process.env.BITFAB_API_KEY })` is hoisted and
+     * evaluated before the importing script's body runs `dotenv.config()`, so
+     * the key would be empty at construction even though it is set moments
+     * later. Resolving here (at first `withSpan` call / first request) reads
+     * the key after env loading has run.
+     *
+     * Resolution order: the configured value (string, or function called each
+     * time it is still unresolved), then a fallback read of `BITFAB_API_KEY`
+     * from the environment. Once a non-empty key is found it is cached, so an
+     * early resolve that found nothing never poisons a later one.
+     */
+    private resolveApiKey;
+    /**
+     * Whether tracing should run, decided lazily at call time (not frozen at
+     * construction). An explicit `enabled: false` short-circuits without ever
+     * touching the key.
+     */
+    private isTracingEnabled;
     /**
      * Fetch the function with its current version and BAML prompt from the server.
      *
@@ -1530,7 +1589,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.27.1";
+declare const __version__ = "0.28.0";
 
 /**
  * Constants for the Bitfab SDK.

package/dist/index.d.ts

@@ -30,6 +30,91 @@ type AllowedEnvVars = {
     OPENAI_API_KEY?: string;
 };
 
+/**
+ * Per-trace database snapshot ref capture.
+ *
+ * Every root span carries a `DbSnapshotRef` that pins the DB state at trace
+ * open by wall-clock timestamp. Capturing the timestamp is free (no IO) and
+ * harmless, so it happens on every trace regardless of configuration: that
+ * lets any trace be replayed against a historical branch later. A `provider`
+ * is attached only when the customer configured `dbSnapshot`; when absent it
+ * is resolved at replay time. The Bitfab service uses the timestamp to
+ * materialize an ephemeral branch from `customer-main`.
+ */
+declare const SUPPORTED_PROVIDERS: readonly ["neon"];
+type DbSnapshotProvider = (typeof SUPPORTED_PROVIDERS)[number];
+interface DbSnapshotConfig {
+    /** Discriminator for the server-side resolver. */
+    provider: DbSnapshotProvider;
+}
+interface DbSnapshotRef {
+    /**
+     * The wall-clock ISO timestamp the SDK observed immediately before
+     * invoking the wrapped function. The name encodes its provenance:
+     * SDK-observed, wall clock (not monotonic), captured before user code
+     * began executing. Always present.
+     */
+    sdkWallClockBeforeFn: string;
+    /**
+     * The configured provider for server-side branch resolution. Only set when
+     * the customer configured `dbSnapshot`; otherwise the provider is resolved
+     * at replay time.
+     */
+    provider?: DbSnapshotProvider;
+}
+
+/**
+ * Shared error type for Bitfab SDK runtime errors. Lives in its own
+ * module to avoid import cycles between `http.ts` and modules that need
+ * to throw structured errors (e.g. `dbSnapshot.ts` validation).
+ */
+declare class BitfabError extends Error {
+    readonly url?: string | undefined;
+    constructor(message: string, url?: string | undefined);
+}
+
+/**
+ * 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
+ */
+
+/**
+ * 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>;
+/**
+ * How the API key is supplied internally: either a literal string or a
+ * function resolved each time the key is needed (at request/send time). The
+ * function form is what defers key resolution past module-load construction
+ * so an env var loaded after the client is built (the ESM dotenv-hoisting
+ * case) is still picked up.
+ */
+type ApiKeyInput = string | (() => string | undefined);
+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;
+}
+
 /**
  * Claude Agent SDK handler for Bitfab tracing.
  *
@@ -40,6 +125,7 @@ type AllowedEnvVars = {
  *   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;
@@ -96,7 +182,7 @@ declare class BitfabClaudeAgentHandler {
     private rootInput;
     private rootOutput;
     constructor(config: {
-        apiKey?: string;
+        apiKey?: ApiKeyInput;
         traceFunctionKey: string;
         serviceUrl?: string;
         timeout?: number;
@@ -285,83 +371,6 @@ declare class BitfabVercelAiHandler {
     get middleware(): BitfabLanguageModelMiddleware;
 }
 
-/**
- * Per-trace database snapshot ref capture.
- *
- * Every root span carries a `DbSnapshotRef` that pins the DB state at trace
- * open by wall-clock timestamp. Capturing the timestamp is free (no IO) and
- * harmless, so it happens on every trace regardless of configuration: that
- * lets any trace be replayed against a historical branch later. A `provider`
- * is attached only when the customer configured `dbSnapshot`; when absent it
- * is resolved at replay time. The Bitfab service uses the timestamp to
- * materialize an ephemeral branch from `customer-main`.
- */
-declare const SUPPORTED_PROVIDERS: readonly ["neon"];
-type DbSnapshotProvider = (typeof SUPPORTED_PROVIDERS)[number];
-interface DbSnapshotConfig {
-    /** Discriminator for the server-side resolver. */
-    provider: DbSnapshotProvider;
-}
-interface DbSnapshotRef {
-    /**
-     * The wall-clock ISO timestamp the SDK observed immediately before
-     * invoking the wrapped function. The name encodes its provenance:
-     * SDK-observed, wall clock (not monotonic), captured before user code
-     * began executing. Always present.
-     */
-    sdkWallClockBeforeFn: string;
-    /**
-     * The configured provider for server-side branch resolution. Only set when
-     * the customer configured `dbSnapshot`; otherwise the provider is resolved
-     * at replay time.
-     */
-    provider?: DbSnapshotProvider;
-}
-
-/**
- * Shared error type for Bitfab SDK runtime errors. Lives in its own
- * module to avoid import cycles between `http.ts` and modules that need
- * to throw structured errors (e.g. `dbSnapshot.ts` validation).
- */
-declare class BitfabError extends Error {
-    readonly url?: string | undefined;
-    constructor(message: string, url?: string | undefined);
-}
-
-/**
- * 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
- */
-
-/**
- * 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.
  *
@@ -372,6 +381,7 @@ interface CodeChangeFile {
  * Duck-typed to match LangChain.js's BaseCallbackHandler interface.
  * No @langchain/core dependency required.
  */
+
 interface ActiveSpanContext$1 {
     traceId: string;
     spanId: string;
@@ -401,7 +411,7 @@ declare class BitfabLangGraphCallbackHandler {
     private runToSpan;
     private invocations;
     constructor(config: {
-        apiKey?: string;
+        apiKey?: ApiKeyInput;
         traceFunctionKey: string;
         serviceUrl?: string;
         timeout?: number;
@@ -411,18 +421,19 @@ declare class BitfabLangGraphCallbackHandler {
     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>;
+    private sendTraceStart;
+    handleChainStart(chain: Record<string, unknown> | null | undefined, inputs: Record<string, unknown>, runId: string, parentRunIdOrRunType?: string, tags?: string[], metadata?: Record<string, unknown>, runTypeOrRunName?: string, runNameOrParentRunId?: string): 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>;
+    handleChatModelStart(llm: Record<string, unknown> | null | undefined, messages: unknown[][], runId: string, parentRunId?: string, _extraParams?: Record<string, unknown>, tags?: string[], metadata?: Record<string, unknown>, runName?: string): Promise<void>;
+    handleLLMStart(llm: Record<string, unknown> | null | undefined, prompts: string[], runId: string, parentRunId?: string, _extraParams?: Record<string, unknown>, tags?: string[], metadata?: Record<string, unknown>, runName?: string): 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>;
+    handleToolStart(tool: Record<string, unknown> | null | undefined, input: string, runId: string, parentRunId?: string, tags?: string[], metadata?: Record<string, unknown>, runName?: string): 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>;
+    handleRetrieverStart(retriever: Record<string, unknown> | null | undefined, query: string, runId: string, parentRunId?: string, tags?: string[], metadata?: Record<string, unknown>, runName?: string): Promise<void>;
     handleRetrieverEnd(documents: unknown, runId: string): Promise<void>;
     handleRetrieverError(error: unknown, runId: string): Promise<void>;
 }
@@ -781,6 +792,7 @@ interface ReplayResult<T> {
  * This module provides utilities for sending external traces (e.g., from OpenAI API calls)
  * to Bitfab for monitoring and analysis.
  */
+
 interface Trace {
     traceId: string;
     toJSON(): unknown;
@@ -841,7 +853,7 @@ declare class BitfabOpenAITracingProcessor implements TracingProcessor {
      * @param config - Configuration options
      */
     constructor(config: {
-        apiKey?: string;
+        apiKey?: ApiKeyInput;
         serviceUrl?: string;
         timeout?: number;
         getActiveSpanContext?: () => ActiveSpanContext | null;
@@ -1008,8 +1020,19 @@ declare function getCurrentSpan(): CurrentSpan;
  */
 declare function getCurrentTrace(): CurrentTrace;
 interface BitfabConfig {
-    /** The API key for Bitfab API authentication. When undefined or empty, tracing is disabled. */
-    apiKey?: string;
+    /**
+     * The API key for Bitfab API authentication. Resolved lazily, the first
+     * time a span actually needs it, not at construction. When it resolves
+     * empty, tracing is disabled (a no-op, unless `strict` is set).
+     *
+     * Accepts either a string or a function returning the key. The function
+     * form is resolved at first use, so it survives the ESM trap where a shim
+     * built at module load runs before the script body's `dotenv.config()`:
+     * `apiKey: () => process.env.BITFAB_API_KEY`. When omitted (or it resolves
+     * empty), the SDK also falls back to reading `BITFAB_API_KEY` from the
+     * environment itself, again at first use.
+     */
+    apiKey?: string | (() => string | null | undefined);
     /** The base URL for the Bitfab API (default: https://bitfab.ai) */
     serviceUrl?: string;
     /** Request timeout in milliseconds (default: 120000) */
@@ -1018,6 +1041,14 @@ interface BitfabConfig {
     envVars?: AllowedEnvVars;
     /** Whether the client is enabled. Defaults to true. When false, withSpan returns the original function unwrapped. */
     enabled?: boolean;
+    /**
+     * Fail loud instead of degrading quietly. When true, the first traced call
+     * with no resolvable API key throws a `BitfabError` rather than silently
+     * disabling tracing. Off by default so a missing telemetry key never takes
+     * down the host app; turn it on in standalone scripts where a run that
+     * emits no traces is a failure you want surfaced immediately.
+     */
+    strict?: boolean;
     /** The generated BAML client instance (e.g., `b` from your baml_client). Used by wrapBAML() when no explicit client is passed. */
     bamlClient?: unknown;
     /**
@@ -1092,11 +1123,17 @@ declare class Bitfab {
      * function to pick up the per-trace branch URL.
      */
     static readonly ReplayEnvironment: typeof ReplayEnvironment;
-    private readonly apiKey;
+    private readonly apiKeyConfig;
+    /** Cached only once a non-empty key is found, so an early resolve (before env loaded) can't poison a later one. */
+    private resolvedApiKey;
+    /** Gate the empty-key warning to fire at most once. */
+    private apiKeyWarned;
     private readonly serviceUrl;
     private readonly timeout;
     private readonly envVars;
-    private readonly enabled;
+    /** The user's on/off intent. The effective enabled state ANDs this with "a key resolved" (see isTracingEnabled). */
+    private readonly explicitlyEnabled;
+    private readonly strict;
     private readonly httpClient;
     private readonly bamlClient;
     private readonly dbSnapshot;
@@ -1106,6 +1143,28 @@ declare class Bitfab {
      * @param config - Configuration options for the client
      */
     constructor(config: BitfabConfig);
+    /**
+     * Resolve the API key lazily, the first time a span actually needs it.
+     *
+     * The key is intentionally NOT read at construction. In ESM, a shim that
+     * does `new Bitfab({ apiKey: process.env.BITFAB_API_KEY })` is hoisted and
+     * evaluated before the importing script's body runs `dotenv.config()`, so
+     * the key would be empty at construction even though it is set moments
+     * later. Resolving here (at first `withSpan` call / first request) reads
+     * the key after env loading has run.
+     *
+     * Resolution order: the configured value (string, or function called each
+     * time it is still unresolved), then a fallback read of `BITFAB_API_KEY`
+     * from the environment. Once a non-empty key is found it is cached, so an
+     * early resolve that found nothing never poisons a later one.
+     */
+    private resolveApiKey;
+    /**
+     * Whether tracing should run, decided lazily at call time (not frozen at
+     * construction). An explicit `enabled: false` short-circuits without ever
+     * touching the key.
+     */
+    private isTracingEnabled;
     /**
      * Fetch the function with its current version and BAML prompt from the server.
      *
@@ -1530,7 +1589,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.27.1";
+declare const __version__ = "0.28.0";
 
 /**
  * Constants for the Bitfab SDK.