@bitfab/sdk 0.21.0 → 0.21.2

package/dist/index.d.cts

@@ -52,9 +52,14 @@ interface ActiveSpanContext$2 {
  * Captures LLM turns, tool invocations, and subagent execution as
  * Bitfab spans with proper parent-child hierarchy.
  *
+ * The TypeScript Claude Agent SDK exposes a single `query()` entry point (there
+ * is no `ClaudeSDKClient` class — that exists only in the Python SDK). Wrap the
+ * `query()` async iterator with `wrapQuery`; tool and subagent spans come from
+ * the hooks injected by `instrumentOptions`.
+ *
  * ```typescript
  * import { Bitfab } from "@bitfab/sdk";
- * import { ClaudeSDKClient } from "@anthropic-ai/claude-agent-sdk";
+ * import { query } from "@anthropic-ai/claude-agent-sdk";
  *
  * const bitfab = new Bitfab({ apiKey: "..." });
  * const handler = bitfab.getClaudeAgentHandler("my-agent");
@@ -63,11 +68,9 @@ interface ActiveSpanContext$2 {
  *   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())) {
+ * for await (const message of handler.wrapQuery(
+ *   query({ prompt: "Do something", options })
+ * )) {
  *   // process messages normally
  * }
  * ```
@@ -91,6 +94,9 @@ declare class BitfabClaudeAgentHandler {
     private currentLlmStartedAt;
     private currentLlmHistorySnapshot;
     private activeSubagentSpans;
+    private hasRootInput;
+    private rootInput;
+    private rootOutput;
     constructor(config: {
         apiKey?: string;
         traceFunctionKey: string;
@@ -100,6 +106,8 @@ declare class BitfabClaudeAgentHandler {
     });
     private ensureTrace;
     private getParentId;
+    private maybeStartRootSpan;
+    private completeRootSpan;
     private startSpan;
     private completeSpan;
     private sendSpan;
@@ -122,19 +130,38 @@ declare class BitfabClaudeAgentHandler {
      */
     instrumentOptions<T extends Record<string, unknown>>(options: T): T;
     /**
-     * Wrap a `ClaudeSDKClient.receiveResponse()` stream to capture LLM turns.
+     * Wrap any Claude Agent SDK message stream to capture LLM turns.
      *
-     * Yields every message unchanged while capturing AssistantMessage
-     * content as LLM turn spans.
+     * Yields every message unchanged while capturing assistant message
+     * content as LLM turn spans. Kept for naming symmetry with the Python
+     * SDK's `wrapResponse` (which wraps `ClaudeSDKClient.receiveResponse()`);
+     * in TypeScript, prefer `wrapQuery` around `query()`.
+     *
+     * Pass `{ input }` (the prompt) to record a replayable root span — see
+     * `wrapQuery`.
      */
-    wrapResponse(stream: AsyncIterable<unknown>): AsyncIterable<unknown>;
+    wrapResponse(stream: AsyncIterable<unknown>, opts?: {
+        input?: 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).
+     * Tool and subagent spans are captured separately via the hooks injected
+     * by `instrumentOptions` into the `options` passed to `query()`.
+     *
+     * Pass `{ input }` — the prompt (or the serializable args that produced it)
+     * — to make a handler-only run replayable: the handler records a root `agent`
+     * span with that input, so `replay(key, fn)` can re-feed it. Omit it only
+     * when an enclosing `withSpan` already supplies the replayable root.
+     *
+     * ```typescript
+     * handler.wrapQuery(query({ prompt, options }), { input: prompt })
+     * ```
      */
-    wrapQuery(stream: AsyncIterable<unknown>): AsyncIterable<unknown>;
+    wrapQuery(stream: AsyncIterable<unknown>, opts?: {
+        input?: unknown;
+    }): AsyncIterable<unknown>;
+    private setRootInput;
     private processStream;
     private processMessage;
     private handleAssistantMessage;
@@ -877,14 +904,15 @@ declare class Bitfab {
      * execution as Bitfab spans with proper parent-child hierarchy.
      *
      * ```typescript
+     * import { query } from "@anthropic-ai/claude-agent-sdk";
+     *
      * 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())) {
+     * for await (const msg of handler.wrapQuery(
+     *   query({ prompt: "Do something", options })
+     * )) {
      *   // process messages
      * }
      * ```
@@ -1089,7 +1117,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.21.0";
+declare const __version__ = "0.21.2";
 
 /**
  * Constants for the Bitfab SDK.

package/dist/index.d.ts

@@ -52,9 +52,14 @@ interface ActiveSpanContext$2 {
  * Captures LLM turns, tool invocations, and subagent execution as
  * Bitfab spans with proper parent-child hierarchy.
  *
+ * The TypeScript Claude Agent SDK exposes a single `query()` entry point (there
+ * is no `ClaudeSDKClient` class — that exists only in the Python SDK). Wrap the
+ * `query()` async iterator with `wrapQuery`; tool and subagent spans come from
+ * the hooks injected by `instrumentOptions`.
+ *
  * ```typescript
  * import { Bitfab } from "@bitfab/sdk";
- * import { ClaudeSDKClient } from "@anthropic-ai/claude-agent-sdk";
+ * import { query } from "@anthropic-ai/claude-agent-sdk";
  *
  * const bitfab = new Bitfab({ apiKey: "..." });
  * const handler = bitfab.getClaudeAgentHandler("my-agent");
@@ -63,11 +68,9 @@ interface ActiveSpanContext$2 {
  *   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())) {
+ * for await (const message of handler.wrapQuery(
+ *   query({ prompt: "Do something", options })
+ * )) {
  *   // process messages normally
  * }
  * ```
@@ -91,6 +94,9 @@ declare class BitfabClaudeAgentHandler {
     private currentLlmStartedAt;
     private currentLlmHistorySnapshot;
     private activeSubagentSpans;
+    private hasRootInput;
+    private rootInput;
+    private rootOutput;
     constructor(config: {
         apiKey?: string;
         traceFunctionKey: string;
@@ -100,6 +106,8 @@ declare class BitfabClaudeAgentHandler {
     });
     private ensureTrace;
     private getParentId;
+    private maybeStartRootSpan;
+    private completeRootSpan;
     private startSpan;
     private completeSpan;
     private sendSpan;
@@ -122,19 +130,38 @@ declare class BitfabClaudeAgentHandler {
      */
     instrumentOptions<T extends Record<string, unknown>>(options: T): T;
     /**
-     * Wrap a `ClaudeSDKClient.receiveResponse()` stream to capture LLM turns.
+     * Wrap any Claude Agent SDK message stream to capture LLM turns.
      *
-     * Yields every message unchanged while capturing AssistantMessage
-     * content as LLM turn spans.
+     * Yields every message unchanged while capturing assistant message
+     * content as LLM turn spans. Kept for naming symmetry with the Python
+     * SDK's `wrapResponse` (which wraps `ClaudeSDKClient.receiveResponse()`);
+     * in TypeScript, prefer `wrapQuery` around `query()`.
+     *
+     * Pass `{ input }` (the prompt) to record a replayable root span — see
+     * `wrapQuery`.
      */
-    wrapResponse(stream: AsyncIterable<unknown>): AsyncIterable<unknown>;
+    wrapResponse(stream: AsyncIterable<unknown>, opts?: {
+        input?: 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).
+     * Tool and subagent spans are captured separately via the hooks injected
+     * by `instrumentOptions` into the `options` passed to `query()`.
+     *
+     * Pass `{ input }` — the prompt (or the serializable args that produced it)
+     * — to make a handler-only run replayable: the handler records a root `agent`
+     * span with that input, so `replay(key, fn)` can re-feed it. Omit it only
+     * when an enclosing `withSpan` already supplies the replayable root.
+     *
+     * ```typescript
+     * handler.wrapQuery(query({ prompt, options }), { input: prompt })
+     * ```
      */
-    wrapQuery(stream: AsyncIterable<unknown>): AsyncIterable<unknown>;
+    wrapQuery(stream: AsyncIterable<unknown>, opts?: {
+        input?: unknown;
+    }): AsyncIterable<unknown>;
+    private setRootInput;
     private processStream;
     private processMessage;
     private handleAssistantMessage;
@@ -877,14 +904,15 @@ declare class Bitfab {
      * execution as Bitfab spans with proper parent-child hierarchy.
      *
      * ```typescript
+     * import { query } from "@anthropic-ai/claude-agent-sdk";
+     *
      * 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())) {
+     * for await (const msg of handler.wrapQuery(
+     *   query({ prompt: "Do something", options })
+     * )) {
      *   // process messages
      * }
      * ```
@@ -1089,7 +1117,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.21.0";
+declare const __version__ = "0.21.2";
 
 /**
  * Constants for the Bitfab SDK.

package/dist/index.js

@@ -12,7 +12,7 @@ import {
   flushTraces,
   getCurrentSpan,
   getCurrentTrace
-} from "./chunk-UO3CIQ7R.js";
+} from "./chunk-3YKMCCDV.js";
 import {
   BitfabError
 } from "./chunk-EQI6ZJC3.js";

package/dist/node.cjs

@@ -504,7 +504,7 @@ registerAsyncLocalStorageClass(
 );
 
 // src/version.generated.ts
-var __version__ = "0.21.0";
+var __version__ = "0.21.2";
 
 // src/constants.ts
 var DEFAULT_SERVICE_URL = "https://bitfab.ai";
@@ -975,6 +975,13 @@ var BitfabClaudeAgentHandler = class {
     this.currentLlmHistorySnapshot = [];
     // Subagent tracking
     this.activeSubagentSpans = /* @__PURE__ */ new Map();
+    // Synthetic root span (handler-only replay). When an `input` is supplied to
+    // wrapQuery/wrapResponse, the handler emits a root `agent` span carrying that
+    // input, so a handler-instrumented run is replayable WITHOUT an enclosing
+    // withSpan — matching the LangGraph handler, which records the graph input as
+    // its root. The prompt is not present anywhere in the message stream, so it
+    // must be handed in explicitly.
+    this.hasRootInput = false;
     this.httpClient = new HttpClient({
       apiKey: config.apiKey,
       serviceUrl: config.serviceUrl ?? DEFAULT_SERVICE_URL,
@@ -1009,7 +1016,30 @@ var BitfabClaudeAgentHandler = class {
         return subagentSpanId;
       }
     }
-    return this.activeContext?.spanId ?? this.rootSpanId ?? null;
+    return this.rootSpanId ?? this.activeContext?.spanId ?? null;
+  }
+  // Emit the synthetic root `agent` span once, before any child spans. No-op
+  // unless an `input` was supplied AND there is no enclosing withSpan (in which
+  // case that outer span is already the replayable root).
+  maybeStartRootSpan() {
+    if (!this.hasRootInput || this.rootSpanId !== null) {
+      return;
+    }
+    this.ensureTrace();
+    if (this.activeContext !== null) {
+      return;
+    }
+    const spanId = crypto.randomUUID();
+    this.startSpan(spanId, this.traceFunctionKey, "agent", this.rootInput, null);
+    this.rootSpanId = spanId;
+  }
+  completeRootSpan() {
+    if (this.rootSpanId === null) {
+      return;
+    }
+    const spanId = this.rootSpanId;
+    this.rootSpanId = null;
+    this.completeSpan(spanId, this.rootOutput);
   }
   // ── span helpers ─────────────────────────────────────────────
   startSpan(spanId, name, spanType, inputData, parentId) {
@@ -1205,26 +1235,53 @@ var BitfabClaudeAgentHandler = class {
     return options;
   }
   /**
-   * Wrap a `ClaudeSDKClient.receiveResponse()` stream to capture LLM turns.
+   * Wrap any Claude Agent SDK message stream to capture LLM turns.
+   *
+   * Yields every message unchanged while capturing assistant message
+   * content as LLM turn spans. Kept for naming symmetry with the Python
+   * SDK's `wrapResponse` (which wraps `ClaudeSDKClient.receiveResponse()`);
+   * in TypeScript, prefer `wrapQuery` around `query()`.
    *
-   * Yields every message unchanged while capturing AssistantMessage
-   * content as LLM turn spans.
+   * Pass `{ input }` (the prompt) to record a replayable root span — see
+   * `wrapQuery`.
    */
-  async *wrapResponse(stream) {
+  async *wrapResponse(stream, opts) {
+    this.setRootInput(opts);
     yield* this.processStream(stream);
   }
   /**
    * 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).
+   * Tool and subagent spans are captured separately via the hooks injected
+   * by `instrumentOptions` into the `options` passed to `query()`.
+   *
+   * Pass `{ input }` — the prompt (or the serializable args that produced it)
+   * — to make a handler-only run replayable: the handler records a root `agent`
+   * span with that input, so `replay(key, fn)` can re-feed it. Omit it only
+   * when an enclosing `withSpan` already supplies the replayable root.
+   *
+   * ```typescript
+   * handler.wrapQuery(query({ prompt, options }), { input: prompt })
+   * ```
    */
-  async *wrapQuery(stream) {
+  async *wrapQuery(stream, opts) {
+    this.setRootInput(opts);
     yield* this.processStream(stream);
   }
+  setRootInput(opts) {
+    if (opts && opts.input !== void 0) {
+      this.hasRootInput = true;
+      this.rootInput = opts.input;
+    } else {
+      this.hasRootInput = false;
+      this.rootInput = void 0;
+    }
+    this.rootOutput = void 0;
+  }
   // ── stream processing ────────────────────────────────────────
   async *processStream(stream) {
     try {
+      this.maybeStartRootSpan();
       for await (const message of stream) {
         try {
           this.processMessage(message);
@@ -1235,6 +1292,7 @@ var BitfabClaudeAgentHandler = class {
     } finally {
       try {
         this.flushLlmTurn();
+        this.completeRootSpan();
         this.sendTraceCompletion();
       } catch {
       }
@@ -1242,18 +1300,19 @@ var BitfabClaudeAgentHandler = class {
     }
   }
   processMessage(message) {
-    const typeName = message.constructor?.name ?? "";
-    if (typeName === "AssistantMessage") {
+    const typeName = message.type;
+    if (typeName === "assistant") {
       this.handleAssistantMessage(message);
-    } else if (typeName === "UserMessage") {
+    } else if (typeName === "user") {
       this.handleUserMessage(message);
-    } else if (typeName === "ResultMessage") {
+    } else if (typeName === "result") {
       this.handleResultMessage(message);
     }
   }
   handleAssistantMessage(message) {
     this.ensureTrace();
-    const messageId = message.message_id;
+    const inner = message.message ?? {};
+    const messageId = inner.id ?? message.uuid;
     if (messageId !== this.currentLlmMessageId) {
       this.flushLlmTurn();
       this.conversationHistory.push(...this.pendingMessages);
@@ -1261,26 +1320,27 @@ var BitfabClaudeAgentHandler = class {
       this.currentLlmSpanId = crypto.randomUUID();
       this.currentLlmMessageId = messageId ?? null;
       this.currentLlmContent = [];
-      this.currentLlmModel = message.model ?? null;
+      this.currentLlmModel = inner.model ?? null;
       this.currentLlmUsage = {};
       this.currentLlmStartedAt = nowIso();
       this.currentLlmHistorySnapshot = [...this.conversationHistory];
     }
-    const content = message.content;
+    const content = inner.content;
     if (Array.isArray(content)) {
       this.currentLlmContent.push(...extractContentBlocks(content));
     }
-    const usage = extractUsage(message);
+    const usage = extractUsage(inner);
     if (Object.keys(usage).length > 0) {
       Object.assign(this.currentLlmUsage, usage);
     }
-    const model = message.model;
+    const model = inner.model;
     if (model) {
       this.currentLlmModel = model;
     }
   }
   handleUserMessage(message) {
-    const content = message.content;
+    const inner = message.message ?? {};
+    const content = inner.content;
     const toolUseResult = message.tool_use_result;
     if (toolUseResult !== void 0) {
       this.pendingMessages.push({
@@ -1297,6 +1357,10 @@ var BitfabClaudeAgentHandler = class {
   }
   handleResultMessage(message) {
     this.flushLlmTurn();
+    if (message.result !== void 0) {
+      this.rootOutput = message.result;
+    }
+    this.completeRootSpan();
     const metadata = {};
     for (const attr of [
       "num_turns",
@@ -1360,6 +1424,9 @@ var BitfabClaudeAgentHandler = class {
     this.runToSpan.clear();
     this.traceId = null;
     this.rootSpanId = null;
+    this.hasRootInput = false;
+    this.rootInput = void 0;
+    this.rootOutput = void 0;
     this.activeContext = null;
     this.traceStartedAt = null;
     this.conversationHistory = [];
@@ -2437,9 +2504,15 @@ var BitfabOpenAITracingProcessor = class {
    * Extract and add input/response to serialized span, updating errors list.
    */
   extractSpanInputResponse(span, serializedSpan, errors) {
+    if (span.spanData?.type !== "response") {
+      return;
+    }
     const spanData = serializedSpan.span_data;
     try {
-      spanData.input = span.spanData?._input || [];
+      const input = span.spanData?._input;
+      if (input !== void 0) {
+        spanData.input = input;
+      }
     } catch (error) {
       errors.push({
         source: "sdk",
@@ -2448,7 +2521,10 @@ var BitfabOpenAITracingProcessor = class {
       });
     }
     try {
-      spanData.response = span.spanData?._response || null;
+      const response = span.spanData?._response;
+      if (response !== void 0) {
+        spanData.response = response;
+      }
     } catch (error) {
       errors.push({
         source: "sdk",
@@ -2956,14 +3032,15 @@ var Bitfab = class {
    * execution as Bitfab spans with proper parent-child hierarchy.
    *
    * ```typescript
+   * import { query } from "@anthropic-ai/claude-agent-sdk";
+   *
    * 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())) {
+   * for await (const msg of handler.wrapQuery(
+   *   query({ prompt: "Do something", options })
+   * )) {
    *   // process messages
    * }
    * ```