@bitfab/sdk 0.38.6 → 0.38.8

package/dist/index.cjs

@@ -42,7 +42,7 @@ var __version__, __packageName__;
 var init_version_generated = __esm({
   "src/version.generated.ts"() {
     "use strict";
-    __version__ = "0.38.6";
+    __version__ = "0.38.8";
     __packageName__ = "@bitfab/sdk";
   }
 });
@@ -498,8 +498,8 @@ function encodePayloadBody(payload) {
       const marker = { error: `payload_serialize_failed: ${message}` };
       return { body: JSON.stringify(marker), dropped, value: marker };
     }
-    const isRecord = typeof sanitized === "object" && sanitized !== null && !Array.isArray(sanitized);
-    if (dropped.length > 0 && isRecord) {
+    const isRecord2 = typeof sanitized === "object" && sanitized !== null && !Array.isArray(sanitized);
+    if (dropped.length > 0 && isRecord2) {
       const obj = sanitized;
       const existing = Array.isArray(obj.errors) ? obj.errors : [];
       obj.errors = [
@@ -516,7 +516,7 @@ function encodePayloadBody(payload) {
     return {
       body: JSON.stringify(sanitized),
       dropped,
-      value: isRecord ? sanitized : void 0
+      value: isRecord2 ? sanitized : void 0
     };
   }
 }
@@ -3132,6 +3132,7 @@ __export(index_exports, {
   BitfabFunction: () => BitfabFunction,
   BitfabLangChainCallbackHandler: () => BitfabLangGraphCallbackHandler,
   BitfabLangGraphCallbackHandler: () => BitfabLangGraphCallbackHandler,
+  BitfabLangGraphIntegration: () => BitfabLangGraphIntegration,
   BitfabOpenAIAgentHandler: () => BitfabOpenAIAgentHandler,
   BitfabOpenAITracingProcessor: () => BitfabOpenAITracingProcessor,
   BitfabVercelAiHandler: () => BitfabVercelAiHandler,
@@ -4456,6 +4457,7 @@ var BitfabLangGraphCallbackHandler = class {
     });
     this.traceFunctionKey = config.traceFunctionKey;
     this.getActiveSpanContext = config.getActiveSpanContext ?? null;
+    this.captureTools = config.captureTools ?? true;
   }
   /**
    * Flush and release the span transport this handler started. A no-op when
@@ -4764,6 +4766,9 @@ var BitfabLangGraphCallbackHandler = class {
   }
   // ── tool callbacks ────────────────────────────────────────────
   async handleToolStart(tool, input, runId, parentRunId, tags, metadata, runName) {
+    if (!this.captureTools) {
+      return;
+    }
     try {
       const serialized = tool ?? {};
       const name = runName ?? serialized.name ?? "tool";
@@ -4780,12 +4785,18 @@ var BitfabLangGraphCallbackHandler = class {
     }
   }
   async handleToolEnd(output, runId) {
+    if (!this.captureTools) {
+      return;
+    }
     try {
       this.completeSpan(runId, output);
     } catch {
     }
   }
   async handleToolError(error, runId) {
+    if (!this.captureTools) {
+      return;
+    }
     try {
       this.completeSpan(
         runId,
@@ -4830,6 +4841,258 @@ var BitfabLangGraphCallbackHandler = class {
   }
 };
 
+// src/langgraphIntegration.ts
+init_http();
+init_replayContext();
+var TOOL_RESULT_TAG = "__bitfabLangGraphToolResult";
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function isToolMessage(value) {
+  return isRecord(value) && value.lc_direct_tool_output === true && value.type === "tool" && (typeof value.content === "string" || Array.isArray(value.content));
+}
+function isCommand(value) {
+  return isRecord(value) && value.lg_name === "Command";
+}
+function encodeNested(value) {
+  if (isToolMessage(value) || isCommand(value)) {
+    return encodeNativeToolResult(value);
+  }
+  if (Array.isArray(value)) {
+    return value.map(encodeNested);
+  }
+  if (isRecord(value)) {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, entry]) => [key, encodeNested(entry)])
+    );
+  }
+  return value;
+}
+function encodeNativeToolResult(value) {
+  if (isToolMessage(value)) {
+    return {
+      [TOOL_RESULT_TAG]: "tool-message",
+      content: value.content,
+      name: typeof value.name === "string" ? value.name : void 0,
+      id: typeof value.id === "string" ? value.id : void 0,
+      status: value.status === "success" || value.status === "error" ? value.status : void 0,
+      artifact: encodeNested(value.artifact),
+      metadata: encodeNested(value.metadata),
+      additionalKwargs: encodeNested(value.additional_kwargs),
+      responseMetadata: encodeNested(value.response_metadata)
+    };
+  }
+  return {
+    [TOOL_RESULT_TAG]: "command",
+    graph: isRecord(value) && typeof value.graph === "string" ? value.graph : void 0,
+    update: isRecord(value) ? encodeNested(value.update) : void 0,
+    resume: isRecord(value) ? encodeNested(value.resume) : void 0,
+    goto: isRecord(value) ? encodeNested(value.goto) : void 0
+  };
+}
+function finalizeToolResult(value) {
+  return isToolMessage(value) || isCommand(value) ? encodeNativeToolResult(value) : value;
+}
+function isEncodedToolResult(value) {
+  return isRecord(value) && typeof value[TOOL_RESULT_TAG] === "string";
+}
+async function loadLangChainCore() {
+  try {
+    return await importOptionalPeer([
+      "@langchain",
+      "core",
+      "messages"
+    ]);
+  } catch {
+    throw new BitfabError(
+      "LangGraph tool replay requires @langchain/core. Install @langchain/langgraph before using getLangGraphIntegration().",
+      "https://docs.bitfab.ai/frameworks/langgraph"
+    );
+  }
+}
+async function loadLangGraph() {
+  try {
+    return await importOptionalPeer([
+      "@langchain",
+      "langgraph"
+    ]);
+  } catch {
+    throw new BitfabError(
+      "Replaying a LangGraph Command requires @langchain/langgraph.",
+      "https://docs.bitfab.ai/frameworks/langgraph"
+    );
+  }
+}
+async function reviveNested(value, toolCallId) {
+  if (isEncodedToolResult(value)) {
+    return reviveToolResult(value, toolCallId);
+  }
+  if (Array.isArray(value)) {
+    return Promise.all(value.map((entry) => reviveNested(entry, toolCallId)));
+  }
+  if (isRecord(value)) {
+    const entries = await Promise.all(
+      Object.entries(value).map(async ([key, entry]) => [
+        key,
+        await reviveNested(entry, toolCallId)
+      ])
+    );
+    return Object.fromEntries(entries);
+  }
+  return value;
+}
+async function reviveToolResult(value, toolCallId) {
+  if (value[TOOL_RESULT_TAG] === "tool-message") {
+    const { ToolMessage } = await loadLangChainCore();
+    return new ToolMessage({
+      content: value.content,
+      tool_call_id: toolCallId,
+      ...typeof value.name === "string" && { name: value.name },
+      ...typeof value.id === "string" && { id: value.id },
+      ...(value.status === "success" || value.status === "error") && {
+        status: value.status
+      },
+      ...value.artifact !== void 0 && {
+        artifact: await reviveNested(value.artifact, toolCallId)
+      },
+      ...isRecord(value.metadata) && {
+        metadata: await reviveNested(value.metadata, toolCallId)
+      },
+      ...isRecord(value.additionalKwargs) && {
+        additional_kwargs: await reviveNested(
+          value.additionalKwargs,
+          toolCallId
+        )
+      },
+      ...isRecord(value.responseMetadata) && {
+        response_metadata: await reviveNested(
+          value.responseMetadata,
+          toolCallId
+        )
+      }
+    });
+  }
+  const { Command } = await loadLangGraph();
+  return new Command({
+    ...typeof value.graph === "string" && { graph: value.graph },
+    ...value.update !== void 0 && {
+      update: await reviveNested(value.update, toolCallId)
+    },
+    ...value.resume !== void 0 && {
+      resume: await reviveNested(value.resume, toolCallId)
+    },
+    ...value.goto !== void 0 && {
+      goto: await reviveNested(value.goto, toolCallId)
+    }
+  });
+}
+var BitfabLangGraphIntegration = class {
+  constructor(config) {
+    this.client = config.client;
+    this.traceFunctionKey = config.traceFunctionKey;
+    this.callbackHandler = config.callbackHandler;
+    this.mockToolsOnReplay = config.options?.mockToolsOnReplay ?? true;
+  }
+  /**
+   * Wrap tools before passing the same returned array to both
+   * `model.bindTools()` and `new ToolNode()`. Each invocation becomes an
+   * independently mockable child span.
+   */
+  wrapTools(tools) {
+    return tools.map((tool) => this.wrapTool(tool));
+  }
+  /**
+   * Create the normal graph entry point. The returned function adds Bitfab's
+   * callback handler, preserves invocation config, and records only the graph
+   * input as the replayable root input.
+   *
+   * @experimental This API may change before it is stable.
+   */
+  createInvoker(graph) {
+    const configuredGraph = graph.withConfig({
+      callbacks: [this.callbackHandler]
+    });
+    return (input, config) => {
+      const invoke = this.wrapInvoke(
+        (rootInput) => configuredGraph.invoke(rootInput, config)
+      );
+      return invoke(input);
+    };
+  }
+  wrapTool(tool) {
+    const toolName = tool.name;
+    if (typeof toolName !== "string" || toolName.length === 0) {
+      throw new BitfabError(
+        "LangGraph replayable tools must have a name.",
+        "https://docs.bitfab.ai/frameworks/langgraph"
+      );
+    }
+    const mockToolsOnReplay = this.mockToolsOnReplay;
+    const shouldMock = typeof mockToolsOnReplay === "boolean" ? mockToolsOnReplay : mockToolsOnReplay.includes(toolName);
+    const originalInvoke = tool.invoke.bind(tool);
+    return new Proxy(tool, {
+      get: (target, property) => {
+        if (property === "invoke") {
+          return async (input, ...rest) => {
+            const toolCallId = isRecord(input) && typeof input.id === "string" ? input.id : "";
+            const args = isRecord(input) && "args" in input ? input.args : input;
+            this.assertReplayToolResultExists(toolName, shouldMock);
+            const execute = this.client.withSpan(
+              this.traceFunctionKey,
+              {
+                name: toolName,
+                type: "function",
+                captureWhen: "nested",
+                mockOnReplay: shouldMock,
+                finalize: finalizeToolResult
+              },
+              async (_args) => await originalInvoke(input, ...rest)
+            );
+            const result = await execute(args);
+            return isEncodedToolResult(result) ? await reviveToolResult(result, toolCallId) : result;
+          };
+        }
+        const value = Reflect.get(target, property, target);
+        return typeof value === "function" ? value.bind(target) : value;
+      }
+    });
+  }
+  assertReplayToolResultExists(toolName, shouldMock) {
+    const replayContext = getReplayContext();
+    if (!replayContext?.mockTree) {
+      return;
+    }
+    const counterKey = `${this.traceFunctionKey}:${toolName}`;
+    const callIndex = replayContext.callCounters?.get(counterKey) ?? 0;
+    const mockSpan = replayContext.mockTree.spans.get(
+      `${counterKey}:${callIndex}`
+    );
+    const hasMatchingOverride = replayContext.mockOverrides?.some(
+      (override) => override.match({
+        traceFunctionKey: this.traceFunctionKey,
+        spanName: toolName,
+        type: "function",
+        originalSpanId: mockSpan?.sourceSpanId
+      })
+    );
+    const expectsRecordedOutput = replayContext.mockStrategy === "all" || replayContext.mockStrategy === "marked" && shouldMock;
+    if (hasMatchingOverride !== true && expectsRecordedOutput && !mockSpan) {
+      throw new BitfabError(
+        `No recorded LangGraph tool result for "${toolName}" at call ${callIndex + 1}; refusing to execute the live tool during replay.`,
+        "https://docs.bitfab.ai/frameworks/langgraph"
+      );
+    }
+  }
+  /** Wrap the function that invokes the compiled graph as the replay root. */
+  wrapInvoke(fn) {
+    return this.client.withSpan(
+      this.traceFunctionKey,
+      { name: this.traceFunctionKey, type: "agent" },
+      fn
+    );
+  }
+};
+
 // src/client.ts
 init_mockOverride();
 
@@ -5017,16 +5280,16 @@ var BitfabOpenAITracingProcessor = class {
     delete this.activeTraces[trace.traceId];
   }
   /**
-   * Called when a span is started.
+   * Called when a span is started. Span payloads are authoritative completed
+   * snapshots, so start notifications do not cross the transport boundary.
    */
   // biome-ignore lint/suspicious/noExplicitAny: OpenAI Agents SDK uses any for span data
-  async onSpanStart(span) {
-    this.sendSpan(span);
+  async onSpanStart(_span) {
   }
   /**
    * Called when a span is ended.
    *
-   * Send all spans to Bitfab for complete trace capture.
+   * Send the finalized span snapshot to Bitfab for complete trace capture.
    */
   // biome-ignore lint/suspicious/noExplicitAny: OpenAI Agents SDK uses any for span data
   async onSpanEnd(span) {
@@ -6220,6 +6483,37 @@ var Bitfab = class {
   getLangChainCallbackHandler(traceFunctionKey) {
     return this.getLangGraphCallbackHandler(traceFunctionKey);
   }
+  /**
+   * Get the first-class LangGraph integration for tracing and replaying tools
+   * executed by `ToolNode`.
+   *
+   * The integration combines `wrapTools()` for per-tool replay interception
+   * with `createInvoker()` for a callback-configured replayable graph entry
+   * point. Lower-level callback and root wrappers remain available.
+   *
+   * @param traceFunctionKey - Groups traces under this key in Bitfab
+   * @param options - Controls which tools are marked for replay mocking
+   * @experimental This API may change before it is stable.
+   */
+  getLangGraphIntegration(traceFunctionKey, options) {
+    const callbackHandler = new BitfabLangGraphCallbackHandler({
+      apiKey: this.resolveApiKey(),
+      traceFunctionKey,
+      serviceUrl: this.serviceUrl,
+      getActiveSpanContext: () => {
+        const stack = getSpanStack();
+        return stack[stack.length - 1] ?? null;
+      },
+      captureTools: false,
+      _httpClient: this.httpClient
+    });
+    return new BitfabLangGraphIntegration({
+      client: this,
+      traceFunctionKey,
+      callbackHandler,
+      options
+    });
+  }
   /**
    * Get a Claude Agent SDK handler for tracing.
    *
@@ -7250,6 +7544,14 @@ var BitfabFunction = class {
   getLangChainCallbackHandler() {
     return this.client.getLangChainCallbackHandler(this.traceFunctionKey);
   }
+  /**
+   * Get the first-class LangGraph tool replay integration bound to this key.
+   *
+   * @experimental This API may change before it is stable.
+   */
+  getLangGraphIntegration(options) {
+    return this.client.getLangGraphIntegration(this.traceFunctionKey, options);
+  }
   /**
    * Wrap a BAML client method to automatically capture prompt and LLM metadata.
    * Delegates to the parent client's wrapBAML method.
@@ -7345,6 +7647,7 @@ function defineReplayRegistry(registry) {
   BitfabFunction,
   BitfabLangChainCallbackHandler,
   BitfabLangGraphCallbackHandler,
+  BitfabLangGraphIntegration,
   BitfabOpenAIAgentHandler,
   BitfabOpenAITracingProcessor,
   BitfabVercelAiHandler,