@bitfab/sdk 0.24.1 → 0.26.0

package/dist/index.cjs

@@ -413,13 +413,15 @@ async function processItem(httpClient, serverItem, fn, testRunId, mockStrategy,
     dbSnapshotRef: serverItem.dbSnapshotRef ?? null
   };
 }
-async function mapWithConcurrency(tasks, maxConcurrency) {
+async function mapWithConcurrency(tasks, maxConcurrency, onSettled) {
   const results = new Array(tasks.length);
   let nextIndex = 0;
   async function worker() {
     while (nextIndex < tasks.length) {
       const index = nextIndex++;
-      results[index] = await tasks[index]();
+      const result = await tasks[index]();
+      results[index] = result;
+      onSettled?.(result, index);
     }
   }
   const workers = Array.from(
@@ -479,7 +481,26 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options) {
       options?.adaptInputs
     )
   );
-  const resultItems = await mapWithConcurrency(tasks, maxConcurrency);
+  const total = tasks.length;
+  let completed = 0;
+  let succeeded = 0;
+  let errored = 0;
+  const resultItems = await mapWithConcurrency(
+    tasks,
+    maxConcurrency,
+    options?.onProgress ? (item) => {
+      completed += 1;
+      if (item.error === null) {
+        succeeded += 1;
+      } else {
+        errored += 1;
+      }
+      try {
+        options?.onProgress?.({ completed, total, succeeded, errored });
+      } catch {
+      }
+    } : void 0
+  );
   const completeResult = await httpClient.completeReplay(testRunId);
   const serverTraceIds = completeResult.traceIds;
   const replayTokens = completeResult.tokens;
@@ -566,7 +587,7 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/version.generated.ts
-var __version__ = "0.24.1";
+var __version__ = "0.26.0";
 
 // src/constants.ts
 var DEFAULT_SERVICE_URL = "https://bitfab.ai";
@@ -4072,10 +4093,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