@bitfab/sdk 0.25.0 → 0.26.0

package/dist/index.d.cts

@@ -1384,10 +1384,97 @@ declare class BitfabFunction {
      * @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;
+    /**
+     * Get a Vercel AI SDK language-model middleware bound to this function's key.
+     *
+     * Equivalent to `client.getVercelAiMiddleware(key)` but reuses the key bound
+     * on this handle, so an outer `withSpan` root and the middleware-traced model
+     * calls share one key without repeating the string. With a matching key, the
+     * outer span is the replayable root and the model-call spans nest beneath it.
+     *
+     * Nesting is captured when the model is called, so keep the
+     * `generateText` / `streamText` call inside this handle's `withSpan`; the
+     * middleware object itself can be created anywhere.
+     *
+     * ```typescript
+     * const chatTurn = client.getFunction("chat-turn");
+     * const runChatTurn = chatTurn.withSpan(
+     *   { type: "agent", finalize: finalizers.aiSdk },
+     *   (messages) => streamText({ model, messages }),
+     * );
+     * const model = wrapLanguageModel({
+     *   model: openai("gpt-4o"),
+     *   middleware: chatTurn.getVercelAiMiddleware(),
+     * });
+     * ```
+     *
+     * @returns A Vercel AI SDK middleware configured for this client and key
+     */
+    getVercelAiMiddleware(): BitfabLanguageModelMiddleware;
+    /**
+     * Get a Claude Agent SDK handler bound to this function's key.
+     *
+     * Equivalent to `client.getClaudeAgentHandler(key)` but reuses the key bound
+     * on this handle, so an outer `withSpan` root and the handler share one key
+     * without repeating the string. With a matching key, the outer span is the
+     * replayable root and every handler span nests beneath it.
+     *
+     * Use the handler inside this handle's `withSpan` body so its spans capture
+     * the enclosing root; framework calls made with no active span record their
+     * own root instead.
+     *
+     * ```typescript
+     * const pipeline = client.getFunction("my-agent");
+     * const tracedRun = pipeline.withSpan({ type: "agent" }, async (prompt) => {
+     *   const handler = pipeline.getClaudeAgentHandler();
+     *   const options = handler.instrumentOptions({ model: "claude-sonnet-4-6" });
+     *   for await (const msg of handler.wrapQuery(query({ prompt, options }))) { ... }
+     * });
+     * ```
+     *
+     * @returns A Claude Agent SDK handler configured for this client and key
+     */
+    getClaudeAgentHandler(): BitfabClaudeAgentHandler;
+    /**
+     * Get a LangGraph/LangChain callback handler bound to this function's key.
+     *
+     * Equivalent to `client.getLangGraphCallbackHandler(key)` but reuses the key
+     * bound on this handle, so an outer `withSpan` root and the handler share one
+     * key without repeating the string. With a matching key, the outer span is
+     * the replayable root and the LangGraph spans nest beneath it.
+     *
+     * Use the handler inside this handle's `withSpan` body so its spans capture
+     * the enclosing root; framework calls made with no active span record their
+     * own root instead.
+     *
+     * ```typescript
+     * const pipeline = client.getFunction("my-pipeline");
+     * const tracedRun = pipeline.withSpan({ type: "agent" }, async (query) => {
+     *   const handler = pipeline.getLangGraphCallbackHandler();
+     *   return agent.invoke({ messages: [...] }, { callbacks: [handler] });
+     * });
+     * ```
+     *
+     * @returns A LangGraph/LangChain callback handler for this client and key
+     */
+    getLangGraphCallbackHandler(): BitfabLangGraphCallbackHandler;
+    /**
+     * Alias of {@link getLangGraphCallbackHandler} — LangChain and LangGraph
+     * share one callback system, so the same bound handler serves both.
+     *
+     * @returns A LangChain callback handler for this client and key
+     */
+    getLangChainCallbackHandler(): BitfabLangGraphCallbackHandler;
     /**
      * Wrap a BAML client method to automatically capture prompt and LLM metadata.
      * Delegates to the parent client's wrapBAML method.
      *
+     * Unlike the other methods on this handle, `wrapBAML` does NOT use the bound
+     * key: it opens no span of its own. It enriches the *current* span (via
+     * `getCurrentSpan().setPrompt()` / `addContext()`), so call it inside a
+     * function wrapped by this handle's `withSpan` — the bound key keys that
+     * wrapper, and the BAML prompt/metadata attach to it.
+     *
      * @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
@@ -1404,7 +1491,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.25.0";
+declare const __version__ = "0.26.0";
 
 /**
  * Constants for the Bitfab SDK.

package/dist/index.d.ts

@@ -1384,10 +1384,97 @@ declare class BitfabFunction {
      * @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;
+    /**
+     * Get a Vercel AI SDK language-model middleware bound to this function's key.
+     *
+     * Equivalent to `client.getVercelAiMiddleware(key)` but reuses the key bound
+     * on this handle, so an outer `withSpan` root and the middleware-traced model
+     * calls share one key without repeating the string. With a matching key, the
+     * outer span is the replayable root and the model-call spans nest beneath it.
+     *
+     * Nesting is captured when the model is called, so keep the
+     * `generateText` / `streamText` call inside this handle's `withSpan`; the
+     * middleware object itself can be created anywhere.
+     *
+     * ```typescript
+     * const chatTurn = client.getFunction("chat-turn");
+     * const runChatTurn = chatTurn.withSpan(
+     *   { type: "agent", finalize: finalizers.aiSdk },
+     *   (messages) => streamText({ model, messages }),
+     * );
+     * const model = wrapLanguageModel({
+     *   model: openai("gpt-4o"),
+     *   middleware: chatTurn.getVercelAiMiddleware(),
+     * });
+     * ```
+     *
+     * @returns A Vercel AI SDK middleware configured for this client and key
+     */
+    getVercelAiMiddleware(): BitfabLanguageModelMiddleware;
+    /**
+     * Get a Claude Agent SDK handler bound to this function's key.
+     *
+     * Equivalent to `client.getClaudeAgentHandler(key)` but reuses the key bound
+     * on this handle, so an outer `withSpan` root and the handler share one key
+     * without repeating the string. With a matching key, the outer span is the
+     * replayable root and every handler span nests beneath it.
+     *
+     * Use the handler inside this handle's `withSpan` body so its spans capture
+     * the enclosing root; framework calls made with no active span record their
+     * own root instead.
+     *
+     * ```typescript
+     * const pipeline = client.getFunction("my-agent");
+     * const tracedRun = pipeline.withSpan({ type: "agent" }, async (prompt) => {
+     *   const handler = pipeline.getClaudeAgentHandler();
+     *   const options = handler.instrumentOptions({ model: "claude-sonnet-4-6" });
+     *   for await (const msg of handler.wrapQuery(query({ prompt, options }))) { ... }
+     * });
+     * ```
+     *
+     * @returns A Claude Agent SDK handler configured for this client and key
+     */
+    getClaudeAgentHandler(): BitfabClaudeAgentHandler;
+    /**
+     * Get a LangGraph/LangChain callback handler bound to this function's key.
+     *
+     * Equivalent to `client.getLangGraphCallbackHandler(key)` but reuses the key
+     * bound on this handle, so an outer `withSpan` root and the handler share one
+     * key without repeating the string. With a matching key, the outer span is
+     * the replayable root and the LangGraph spans nest beneath it.
+     *
+     * Use the handler inside this handle's `withSpan` body so its spans capture
+     * the enclosing root; framework calls made with no active span record their
+     * own root instead.
+     *
+     * ```typescript
+     * const pipeline = client.getFunction("my-pipeline");
+     * const tracedRun = pipeline.withSpan({ type: "agent" }, async (query) => {
+     *   const handler = pipeline.getLangGraphCallbackHandler();
+     *   return agent.invoke({ messages: [...] }, { callbacks: [handler] });
+     * });
+     * ```
+     *
+     * @returns A LangGraph/LangChain callback handler for this client and key
+     */
+    getLangGraphCallbackHandler(): BitfabLangGraphCallbackHandler;
+    /**
+     * Alias of {@link getLangGraphCallbackHandler} — LangChain and LangGraph
+     * share one callback system, so the same bound handler serves both.
+     *
+     * @returns A LangChain callback handler for this client and key
+     */
+    getLangChainCallbackHandler(): BitfabLangGraphCallbackHandler;
     /**
      * Wrap a BAML client method to automatically capture prompt and LLM metadata.
      * Delegates to the parent client's wrapBAML method.
      *
+     * Unlike the other methods on this handle, `wrapBAML` does NOT use the bound
+     * key: it opens no span of its own. It enriches the *current* span (via
+     * `getCurrentSpan().setPrompt()` / `addContext()`), so call it inside a
+     * function wrapped by this handle's `withSpan` — the bound key keys that
+     * wrapper, and the BAML prompt/metadata attach to it.
+     *
      * @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
@@ -1404,7 +1491,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.25.0";
+declare const __version__ = "0.26.0";
 
 /**
  * Constants for the Bitfab SDK.

package/dist/index.js

@@ -14,7 +14,7 @@ import {
   flushTraces,
   getCurrentSpan,
   getCurrentTrace
-} from "./chunk-GQLNEYSU.js";
+} from "./chunk-GCAJN5I7.js";
 import {
   BitfabError
 } from "./chunk-26MUT4IP.js";

package/dist/node.cjs

@@ -601,7 +601,7 @@ registerAsyncLocalStorageClass(
 );
 
 // src/version.generated.ts
-var __version__ = "0.25.0";
+var __version__ = "0.26.0";
 
 // src/constants.ts
 var DEFAULT_SERVICE_URL = "https://bitfab.ai";
@@ -4107,10 +4107,105 @@ var BitfabFunction = class {
     const fn = typeof optionsOrFn === "function" ? optionsOrFn : maybeFn;
     return this.client.withSpan(this.traceFunctionKey, options, fn);
   }
+  /**
+   * Get a Vercel AI SDK language-model middleware bound to this function's key.
+   *
+   * Equivalent to `client.getVercelAiMiddleware(key)` but reuses the key bound
+   * on this handle, so an outer `withSpan` root and the middleware-traced model
+   * calls share one key without repeating the string. With a matching key, the
+   * outer span is the replayable root and the model-call spans nest beneath it.
+   *
+   * Nesting is captured when the model is called, so keep the
+   * `generateText` / `streamText` call inside this handle's `withSpan`; the
+   * middleware object itself can be created anywhere.
+   *
+   * ```typescript
+   * const chatTurn = client.getFunction("chat-turn");
+   * const runChatTurn = chatTurn.withSpan(
+   *   { type: "agent", finalize: finalizers.aiSdk },
+   *   (messages) => streamText({ model, messages }),
+   * );
+   * const model = wrapLanguageModel({
+   *   model: openai("gpt-4o"),
+   *   middleware: chatTurn.getVercelAiMiddleware(),
+   * });
+   * ```
+   *
+   * @returns A Vercel AI SDK middleware configured for this client and key
+   */
+  getVercelAiMiddleware() {
+    return this.client.getVercelAiMiddleware(this.traceFunctionKey);
+  }
+  /**
+   * Get a Claude Agent SDK handler bound to this function's key.
+   *
+   * Equivalent to `client.getClaudeAgentHandler(key)` but reuses the key bound
+   * on this handle, so an outer `withSpan` root and the handler share one key
+   * without repeating the string. With a matching key, the outer span is the
+   * replayable root and every handler span nests beneath it.
+   *
+   * Use the handler inside this handle's `withSpan` body so its spans capture
+   * the enclosing root; framework calls made with no active span record their
+   * own root instead.
+   *
+   * ```typescript
+   * const pipeline = client.getFunction("my-agent");
+   * const tracedRun = pipeline.withSpan({ type: "agent" }, async (prompt) => {
+   *   const handler = pipeline.getClaudeAgentHandler();
+   *   const options = handler.instrumentOptions({ model: "claude-sonnet-4-6" });
+   *   for await (const msg of handler.wrapQuery(query({ prompt, options }))) { ... }
+   * });
+   * ```
+   *
+   * @returns A Claude Agent SDK handler configured for this client and key
+   */
+  getClaudeAgentHandler() {
+    return this.client.getClaudeAgentHandler(this.traceFunctionKey);
+  }
+  /**
+   * Get a LangGraph/LangChain callback handler bound to this function's key.
+   *
+   * Equivalent to `client.getLangGraphCallbackHandler(key)` but reuses the key
+   * bound on this handle, so an outer `withSpan` root and the handler share one
+   * key without repeating the string. With a matching key, the outer span is
+   * the replayable root and the LangGraph spans nest beneath it.
+   *
+   * Use the handler inside this handle's `withSpan` body so its spans capture
+   * the enclosing root; framework calls made with no active span record their
+   * own root instead.
+   *
+   * ```typescript
+   * const pipeline = client.getFunction("my-pipeline");
+   * const tracedRun = pipeline.withSpan({ type: "agent" }, async (query) => {
+   *   const handler = pipeline.getLangGraphCallbackHandler();
+   *   return agent.invoke({ messages: [...] }, { callbacks: [handler] });
+   * });
+   * ```
+   *
+   * @returns A LangGraph/LangChain callback handler for this client and key
+   */
+  getLangGraphCallbackHandler() {
+    return this.client.getLangGraphCallbackHandler(this.traceFunctionKey);
+  }
+  /**
+   * Alias of {@link getLangGraphCallbackHandler} — LangChain and LangGraph
+   * share one callback system, so the same bound handler serves both.
+   *
+   * @returns A LangChain callback handler for this client and key
+   */
+  getLangChainCallbackHandler() {
+    return this.client.getLangChainCallbackHandler(this.traceFunctionKey);
+  }
   /**
    * Wrap a BAML client method to automatically capture prompt and LLM metadata.
    * Delegates to the parent client's wrapBAML method.
    *
+   * Unlike the other methods on this handle, `wrapBAML` does NOT use the bound
+   * key: it opens no span of its own. It enriches the *current* span (via
+   * `getCurrentSpan().setPrompt()` / `addContext()`), so call it inside a
+   * function wrapped by this handle's `withSpan` — the bound key keys that
+   * wrapper, and the BAML prompt/metadata attach to it.
+   *
    * @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