bitfab 0.9.2 → 0.11.0

package/dist/index.cjs

@@ -30,51 +30,12 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
-// src/asyncStorage.ts
-function registerAsyncLocalStorageClass(cls) {
-  if (!AsyncLocalStorageClass) {
-    AsyncLocalStorageClass = cls;
-  }
-  initDone = true;
-}
-function isAsyncStorageInitDone() {
-  return initDone;
-}
-function createAsyncLocalStorage() {
-  return AsyncLocalStorageClass ? new AsyncLocalStorageClass() : null;
-}
-var AsyncLocalStorageClass, initDone, asyncStorageReady;
-var init_asyncStorage = __esm({
-  "src/asyncStorage.ts"() {
-    "use strict";
-    AsyncLocalStorageClass = null;
-    initDone = false;
-    asyncStorageReady = (typeof process !== "undefined" && process.versions?.node ? (
-      // The join trick hides "node:async_hooks" from static analysis so
-      // bundlers that ban Node.js built-ins don't fail at build time.
-      // webpackIgnore tells webpack/turbopack to emit a native import()
-      // so Node.js can resolve the module at runtime.
-      import(
-        /* webpackIgnore: true */
-        ["node", "async_hooks"].join(":")
-      ).then(
-        (mod) => {
-          registerAsyncLocalStorageClass(mod.AsyncLocalStorage);
-        }
-      ).catch(() => {
-      })
-    ) : Promise.resolve()).then(() => {
-      initDone = true;
-    });
-  }
-});
-
 // src/version.generated.ts
 var __version__;
 var init_version_generated = __esm({
   "src/version.generated.ts"() {
     "use strict";
-    __version__ = "0.9.2";
+    __version__ = "0.11.0";
   }
 });
 
@@ -338,6 +299,45 @@ var init_http = __esm({
   }
 });
 
+// src/asyncStorage.ts
+function registerAsyncLocalStorageClass(cls) {
+  if (!AsyncLocalStorageClass) {
+    AsyncLocalStorageClass = cls;
+  }
+  initDone = true;
+}
+function isAsyncStorageInitDone() {
+  return initDone;
+}
+function createAsyncLocalStorage() {
+  return AsyncLocalStorageClass ? new AsyncLocalStorageClass() : null;
+}
+var AsyncLocalStorageClass, initDone, asyncStorageReady;
+var init_asyncStorage = __esm({
+  "src/asyncStorage.ts"() {
+    "use strict";
+    AsyncLocalStorageClass = null;
+    initDone = false;
+    asyncStorageReady = (typeof process !== "undefined" && process.versions?.node ? (
+      // The join trick hides "node:async_hooks" from static analysis so
+      // bundlers that ban Node.js built-ins don't fail at build time.
+      // webpackIgnore tells webpack/turbopack to emit a native import()
+      // so Node.js can resolve the module at runtime.
+      import(
+        /* webpackIgnore: true */
+        ["node", "async_hooks"].join(":")
+      ).then(
+        (mod) => {
+          registerAsyncLocalStorageClass(mod.AsyncLocalStorage);
+        }
+      ).catch(() => {
+      })
+    ) : Promise.resolve()).then(() => {
+      initDone = true;
+    });
+  }
+});
+
 // src/replayContext.ts
 function getReplayContext() {
   return replayContextStorage?.getStore() ?? null;
@@ -496,8 +496,10 @@ var init_replay = __esm({
 var index_exports = {};
 __export(index_exports, {
   Bitfab: () => Bitfab,
+  BitfabClaudeAgentHandler: () => BitfabClaudeAgentHandler,
   BitfabError: () => BitfabError,
   BitfabFunction: () => BitfabFunction,
+  BitfabLangGraphCallbackHandler: () => BitfabLangGraphCallbackHandler,
   BitfabOpenAITracingProcessor: () => BitfabOpenAITracingProcessor,
   DEFAULT_SERVICE_URL: () => DEFAULT_SERVICE_URL,
   __version__: () => __version__,
@@ -507,6 +509,482 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/claudeAgentSdk.ts
+init_constants();
+init_http();
+function nowIso() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+function safeSerialize(value) {
+  if (value === null || value === void 0) {
+    return value;
+  }
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.map(safeSerialize);
+  }
+  if (typeof value === "object") {
+    if (typeof value.toJSON === "function") {
+      return value.toJSON();
+    }
+    const result = {};
+    for (const [k, v] of Object.entries(value)) {
+      if (!k.startsWith("_")) {
+        result[k] = safeSerialize(v);
+      }
+    }
+    return result;
+  }
+  return String(value);
+}
+function extractContentBlocks(content) {
+  if (!Array.isArray(content)) {
+    return [];
+  }
+  return content.map((block) => safeSerialize(block));
+}
+function extractUsage(message) {
+  const usageInfo = {};
+  const usage = message.usage;
+  if (!usage) {
+    return usageInfo;
+  }
+  const mapping = {
+    input_tokens: "inputTokens",
+    output_tokens: "outputTokens",
+    cache_read_input_tokens: "cacheReadTokens",
+    cache_creation_input_tokens: "cacheCreationTokens"
+  };
+  for (const [srcKey, dstKey] of Object.entries(mapping)) {
+    const val = usage[srcKey];
+    if (val !== void 0 && val !== null) {
+      usageInfo[dstKey] = val;
+    }
+  }
+  return usageInfo;
+}
+var BitfabClaudeAgentHandler = class {
+  constructor(config) {
+    // Span tracking
+    this.runToSpan = /* @__PURE__ */ new Map();
+    this.traceId = null;
+    this.rootSpanId = null;
+    this.activeContext = null;
+    this.traceStartedAt = null;
+    // LLM turn tracking
+    this.conversationHistory = [];
+    this.pendingMessages = [];
+    this.currentLlmSpanId = null;
+    this.currentLlmMessageId = null;
+    this.currentLlmContent = [];
+    this.currentLlmModel = null;
+    this.currentLlmUsage = {};
+    this.currentLlmStartedAt = null;
+    this.currentLlmHistorySnapshot = [];
+    // Subagent tracking
+    this.activeSubagentSpans = /* @__PURE__ */ new Map();
+    this.httpClient = new HttpClient({
+      apiKey: config.apiKey,
+      serviceUrl: config.serviceUrl ?? DEFAULT_SERVICE_URL,
+      timeout: config.timeout ?? 1e4
+    });
+    this.traceFunctionKey = config.traceFunctionKey;
+    this.getActiveSpanContext = config.getActiveSpanContext ?? null;
+    this.preToolUseHook = this.preToolUseHook.bind(this);
+    this.postToolUseHook = this.postToolUseHook.bind(this);
+    this.postToolUseFailureHook = this.postToolUseFailureHook.bind(this);
+    this.subagentStartHook = this.subagentStartHook.bind(this);
+    this.subagentStopHook = this.subagentStopHook.bind(this);
+  }
+  // ── trace lifecycle ──────────────────────────────────────────
+  ensureTrace() {
+    if (this.traceId !== null) {
+      return this.traceId;
+    }
+    this.activeContext = this.getActiveSpanContext?.() ?? null;
+    if (this.activeContext) {
+      this.traceId = this.activeContext.traceId;
+    } else {
+      this.traceId = crypto.randomUUID();
+    }
+    this.traceStartedAt = nowIso();
+    return this.traceId;
+  }
+  getParentId(agentId) {
+    if (agentId) {
+      const subagentSpanId = this.activeSubagentSpans.get(agentId);
+      if (subagentSpanId) {
+        return subagentSpanId;
+      }
+    }
+    return this.activeContext?.spanId ?? this.rootSpanId ?? null;
+  }
+  // ── span helpers ─────────────────────────────────────────────
+  startSpan(spanId, name, spanType, inputData, parentId) {
+    const traceId = this.ensureTrace();
+    const spanInfo = {
+      spanId,
+      traceId,
+      parentId: parentId ?? null,
+      startedAt: nowIso(),
+      name,
+      type: spanType,
+      input: safeSerialize(inputData),
+      contexts: []
+    };
+    this.runToSpan.set(spanId, spanInfo);
+    return spanInfo;
+  }
+  completeSpan(spanId, output, error, extraContexts) {
+    const spanInfo = this.runToSpan.get(spanId);
+    if (!spanInfo) {
+      return;
+    }
+    this.runToSpan.delete(spanId);
+    spanInfo.endedAt = nowIso();
+    spanInfo.output = safeSerialize(output);
+    if (error !== void 0) {
+      spanInfo.error = error;
+    }
+    if (extraContexts) {
+      spanInfo.contexts.push(extraContexts);
+    }
+    this.sendSpan(spanInfo);
+  }
+  sendSpan(spanInfo) {
+    const spanData = {
+      name: spanInfo.name,
+      type: spanInfo.type
+    };
+    if (spanInfo.input !== void 0) {
+      spanData.input = spanInfo.input;
+    }
+    if (spanInfo.output !== void 0) {
+      spanData.output = spanInfo.output;
+    }
+    if (spanInfo.error !== void 0) {
+      spanData.error = spanInfo.error;
+    }
+    if (spanInfo.contexts.length > 0) {
+      spanData.contexts = spanInfo.contexts;
+    }
+    const rawSpan = {
+      id: spanInfo.spanId,
+      trace_id: spanInfo.traceId,
+      started_at: spanInfo.startedAt,
+      ended_at: spanInfo.endedAt ?? nowIso(),
+      span_data: spanData
+    };
+    if (spanInfo.parentId !== null) {
+      rawSpan.parent_id = spanInfo.parentId;
+    }
+    const payload = {
+      type: "sdk-function",
+      source: "typescript-sdk-claude-agent-sdk",
+      traceFunctionKey: this.traceFunctionKey,
+      sourceTraceId: spanInfo.traceId,
+      rawSpan
+    };
+    try {
+      this.httpClient.sendExternalSpan(payload);
+    } catch {
+    }
+  }
+  sendTraceCompletion(endedAt, metadata) {
+    if (this.traceId === null) {
+      return;
+    }
+    const completed = this.activeContext === null;
+    const traceId = this.traceId;
+    this.traceId = null;
+    const externalTrace = {
+      id: traceId,
+      started_at: this.traceStartedAt ?? nowIso(),
+      ended_at: endedAt ?? nowIso(),
+      workflow_name: this.traceFunctionKey
+    };
+    if (metadata) {
+      externalTrace.metadata = metadata;
+    }
+    const traceData = {
+      type: "sdk-function",
+      source: "typescript-sdk-claude-agent-sdk",
+      traceFunctionKey: this.traceFunctionKey,
+      externalTrace,
+      completed
+    };
+    try {
+      this.httpClient.sendExternalTrace(traceData);
+    } catch {
+    }
+  }
+  // ── hook callbacks ───────────────────────────────────────────
+  async preToolUseHook(inputData, toolUseId, _context) {
+    try {
+      const sid = inputData.tool_use_id ?? toolUseId ?? crypto.randomUUID();
+      const toolName = inputData.tool_name ?? "tool";
+      const toolInput = inputData.tool_input ?? {};
+      const agentId = inputData.agent_id;
+      const parentId = this.getParentId(agentId);
+      this.startSpan(sid, toolName, "function", toolInput, parentId);
+    } catch {
+    }
+    return {};
+  }
+  async postToolUseHook(inputData, toolUseId, _context) {
+    try {
+      const sid = inputData.tool_use_id ?? toolUseId ?? "";
+      const toolResponse = inputData.tool_response;
+      this.completeSpan(sid, toolResponse);
+    } catch {
+    }
+    return {};
+  }
+  async postToolUseFailureHook(inputData, toolUseId, _context) {
+    try {
+      const sid = inputData.tool_use_id ?? toolUseId ?? "";
+      const error = String(inputData.error ?? "Unknown error");
+      this.completeSpan(sid, void 0, error);
+    } catch {
+    }
+    return {};
+  }
+  async subagentStartHook(inputData, _toolUseId, _context) {
+    try {
+      const agentId = inputData.agent_id ?? crypto.randomUUID();
+      const agentType = inputData.agent_type ?? "subagent";
+      const parentId = this.getParentId();
+      const spanId = crypto.randomUUID();
+      this.activeSubagentSpans.set(agentId, spanId);
+      this.startSpan(
+        spanId,
+        `Agent: ${agentType}`,
+        "agent",
+        void 0,
+        parentId
+      );
+    } catch {
+    }
+    return {};
+  }
+  async subagentStopHook(inputData, _toolUseId, _context) {
+    try {
+      const agentId = inputData.agent_id ?? "";
+      const spanId = this.activeSubagentSpans.get(agentId);
+      if (spanId) {
+        this.activeSubagentSpans.delete(agentId);
+        this.completeSpan(spanId);
+      }
+    } catch {
+    }
+    return {};
+  }
+  // ── public API ───────────────────────────────────────────────
+  /**
+   * Inject Bitfab tracing hooks into Claude Agent SDK options.
+   *
+   * Modifies the options object and returns it for convenience.
+   * The SDK's `HookMatcher` is constructed as a plain object
+   * (`{ matcher: null, hooks: [callback] }`) to avoid requiring
+   * `@anthropic-ai/claude-agent-sdk` as a dependency.
+   *
+   * @param options - Options object with a `hooks` property
+   * @returns The modified options object with Bitfab hooks injected
+   */
+  instrumentOptions(options) {
+    const hooks = options.hooks ?? {};
+    if (!options.hooks) {
+      ;
+      options.hooks = hooks;
+    }
+    const hookConfig = [
+      ["PreToolUse", this.preToolUseHook],
+      ["PostToolUse", this.postToolUseHook],
+      ["PostToolUseFailure", this.postToolUseFailureHook],
+      ["SubagentStart", this.subagentStartHook],
+      ["SubagentStop", this.subagentStopHook]
+    ];
+    for (const [event, callback] of hookConfig) {
+      if (!hooks[event]) {
+        hooks[event] = [];
+      }
+      hooks[event].push({ matcher: null, hooks: [callback] });
+    }
+    return options;
+  }
+  /**
+   * Wrap a `ClaudeSDKClient.receiveResponse()` stream to capture LLM turns.
+   *
+   * Yields every message unchanged while capturing AssistantMessage
+   * content as LLM turn spans.
+   */
+  async *wrapResponse(stream) {
+    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).
+   */
+  async *wrapQuery(stream) {
+    yield* this.processStream(stream);
+  }
+  // ── stream processing ────────────────────────────────────────
+  async *processStream(stream) {
+    try {
+      for await (const message of stream) {
+        try {
+          this.processMessage(message);
+        } catch {
+        }
+        yield message;
+      }
+    } finally {
+      try {
+        this.flushLlmTurn();
+        this.sendTraceCompletion();
+      } catch {
+      }
+      this.resetState();
+    }
+  }
+  processMessage(message) {
+    const typeName = message.constructor?.name ?? "";
+    if (typeName === "AssistantMessage") {
+      this.handleAssistantMessage(message);
+    } else if (typeName === "UserMessage") {
+      this.handleUserMessage(message);
+    } else if (typeName === "ResultMessage") {
+      this.handleResultMessage(message);
+    }
+  }
+  handleAssistantMessage(message) {
+    this.ensureTrace();
+    const messageId = message.message_id;
+    if (messageId !== this.currentLlmMessageId) {
+      this.flushLlmTurn();
+      this.conversationHistory.push(...this.pendingMessages);
+      this.pendingMessages = [];
+      this.currentLlmSpanId = crypto.randomUUID();
+      this.currentLlmMessageId = messageId ?? null;
+      this.currentLlmContent = [];
+      this.currentLlmModel = message.model ?? null;
+      this.currentLlmUsage = {};
+      this.currentLlmStartedAt = nowIso();
+      this.currentLlmHistorySnapshot = [...this.conversationHistory];
+    }
+    const content = message.content;
+    if (Array.isArray(content)) {
+      this.currentLlmContent.push(...extractContentBlocks(content));
+    }
+    const usage = extractUsage(message);
+    if (Object.keys(usage).length > 0) {
+      Object.assign(this.currentLlmUsage, usage);
+    }
+    const model = message.model;
+    if (model) {
+      this.currentLlmModel = model;
+    }
+  }
+  handleUserMessage(message) {
+    const content = message.content;
+    const toolUseResult = message.tool_use_result;
+    if (toolUseResult !== void 0) {
+      this.pendingMessages.push({
+        role: "tool",
+        content: safeSerialize(content),
+        tool_result: safeSerialize(toolUseResult)
+      });
+    } else {
+      this.pendingMessages.push({
+        role: "user",
+        content: safeSerialize(content)
+      });
+    }
+  }
+  handleResultMessage(message) {
+    this.flushLlmTurn();
+    const metadata = {};
+    for (const attr of [
+      "num_turns",
+      "total_cost_usd",
+      "duration_ms",
+      "duration_api_ms",
+      "session_id"
+    ]) {
+      const val = message[attr];
+      if (val !== void 0 && val !== null) {
+        metadata[attr] = val;
+      }
+    }
+    const usage = message.usage;
+    if (usage && typeof usage === "object") {
+      metadata.usage = safeSerialize(usage);
+    }
+    this.sendTraceCompletion(
+      void 0,
+      Object.keys(metadata).length > 0 ? metadata : void 0
+    );
+  }
+  flushLlmTurn() {
+    if (this.currentLlmSpanId === null) {
+      return;
+    }
+    const spanId = this.currentLlmSpanId;
+    const traceId = this.ensureTrace();
+    const parentId = this.getParentId();
+    const llmContext = {};
+    if (this.currentLlmModel) {
+      llmContext.model = this.currentLlmModel;
+    }
+    Object.assign(llmContext, this.currentLlmUsage);
+    const spanInfo = {
+      spanId,
+      traceId,
+      parentId,
+      startedAt: this.currentLlmStartedAt ?? nowIso(),
+      endedAt: nowIso(),
+      name: this.currentLlmModel ?? "llm",
+      type: "llm",
+      input: this.currentLlmHistorySnapshot,
+      output: this.currentLlmContent,
+      contexts: Object.keys(llmContext).length > 0 ? [llmContext] : []
+    };
+    this.sendSpan(spanInfo);
+    this.conversationHistory.push({
+      role: "assistant",
+      content: this.currentLlmContent
+    });
+    this.currentLlmSpanId = null;
+    this.currentLlmMessageId = null;
+    this.currentLlmContent = [];
+    this.currentLlmModel = null;
+    this.currentLlmUsage = {};
+    this.currentLlmStartedAt = null;
+    this.currentLlmHistorySnapshot = [];
+  }
+  resetState() {
+    this.runToSpan.clear();
+    this.traceId = null;
+    this.rootSpanId = null;
+    this.activeContext = null;
+    this.traceStartedAt = null;
+    this.conversationHistory = [];
+    this.pendingMessages = [];
+    this.currentLlmSpanId = null;
+    this.currentLlmMessageId = null;
+    this.currentLlmContent = [];
+    this.currentLlmModel = null;
+    this.currentLlmUsage = {};
+    this.currentLlmStartedAt = null;
+    this.currentLlmHistorySnapshot = [];
+    this.activeSubagentSpans.clear();
+  }
+};
+
 // src/client.ts
 init_asyncStorage();
 
@@ -801,6 +1279,484 @@ async function runFunctionWithBaml(bamlSource, inputs, providers, envVars) {
 // src/client.ts
 init_constants();
 init_http();
+
+// src/langgraph.ts
+init_constants();
+init_http();
+var LANGSMITH_HIDDEN_TAG = "langsmith:hidden";
+var LANGGRAPH_METADATA_KEYS = [
+  "langgraph_step",
+  "langgraph_node",
+  "langgraph_triggers",
+  "langgraph_path",
+  "langgraph_checkpoint_ns"
+];
+function nowIso2() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+var MAX_SERIALIZE_DEPTH = 6;
+function safeSerialize2(value) {
+  return safeSerializeInner(value, 0, /* @__PURE__ */ new WeakSet());
+}
+function safeSerializeInner(value, depth, seen) {
+  if (value === null || value === void 0) {
+    return value;
+  }
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return value;
+  }
+  const className = value?.constructor?.name ?? typeof value;
+  if (depth > MAX_SERIALIZE_DEPTH) {
+    return `<${className}>`;
+  }
+  if (typeof value === "object") {
+    if (seen.has(value)) {
+      return `<cycle ${className}>`;
+    }
+    seen.add(value);
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => safeSerializeInner(item, depth + 1, seen));
+  }
+  if (typeof value === "object") {
+    if (typeof value.toJSON === "function") {
+      try {
+        return value.toJSON();
+      } catch {
+        return `<${className}>`;
+      }
+    }
+    try {
+      const result = {};
+      for (const [k, v] of Object.entries(value)) {
+        if (!k.startsWith("_")) {
+          result[k] = safeSerializeInner(v, depth + 1, seen);
+        }
+      }
+      return result;
+    } catch {
+      return `<${className}>`;
+    }
+  }
+  try {
+    return String(value);
+  } catch {
+    return `<${className}>`;
+  }
+}
+function convertMessage(message) {
+  if (typeof message !== "object" || message === null) {
+    return { role: "unknown", content: String(message) };
+  }
+  const msg = message;
+  if (typeof msg.toDict === "function") {
+    return msg.toDict();
+  }
+  const typeToRole = {
+    human: "user",
+    ai: "assistant",
+    system: "system",
+    tool: "tool",
+    function: "function"
+  };
+  const result = {};
+  const msgType = msg._getType ? String(msg._getType()) : msg.type;
+  result.role = (msgType ? typeToRole[msgType] : void 0) ?? msg.role ?? "unknown";
+  result.content = msg.content ?? "";
+  if (msg.tool_calls) {
+    result.tool_calls = msg.tool_calls;
+  }
+  if (msg.tool_call_id) {
+    result.tool_call_id = msg.tool_call_id;
+  }
+  if (msg.name) {
+    result.name = msg.name;
+  }
+  return result;
+}
+function extractModelName(serialized, metadata) {
+  if (serialized) {
+    const kwargs = serialized.kwargs;
+    if (kwargs) {
+      const model = kwargs.model_name ?? kwargs.model ?? kwargs.model_id;
+      if (model) {
+        return String(model);
+      }
+    }
+  }
+  if (metadata) {
+    const lsModel = metadata.ls_model_name;
+    if (lsModel) {
+      return String(lsModel);
+    }
+  }
+  return void 0;
+}
+function extractUsage2(output) {
+  const usage = {};
+  const llmOutput = output.llmOutput;
+  const tokenUsage = llmOutput?.tokenUsage ?? llmOutput?.token_usage ?? llmOutput?.usage ?? {};
+  const inputTokens = tokenUsage.promptTokens ?? tokenUsage.prompt_tokens ?? tokenUsage.input_tokens;
+  const outputTokens = tokenUsage.completionTokens ?? tokenUsage.completion_tokens ?? tokenUsage.output_tokens;
+  const totalTokens = tokenUsage.totalTokens ?? tokenUsage.total_tokens;
+  if (inputTokens !== void 0 && inputTokens !== null) {
+    usage.inputTokens = inputTokens;
+  }
+  if (outputTokens !== void 0 && outputTokens !== null) {
+    usage.outputTokens = outputTokens;
+  }
+  if (totalTokens !== void 0 && totalTokens !== null) {
+    usage.totalTokens = totalTokens;
+  }
+  return usage;
+}
+function extractLangGraphMetadata(metadata) {
+  if (!metadata) {
+    return {};
+  }
+  const result = {};
+  for (const key of LANGGRAPH_METADATA_KEYS) {
+    if (key in metadata) {
+      result[key] = metadata[key];
+    }
+  }
+  return result;
+}
+var BitfabLangGraphCallbackHandler = class {
+  constructor(config) {
+    this.name = "BitfabLangGraphCallbackHandler";
+    this.ignoreRetriever = true;
+    this.ignoreRetry = true;
+    this.ignoreCustomEvent = true;
+    this.runToSpan = /* @__PURE__ */ new Map();
+    this.invocations = /* @__PURE__ */ new Map();
+    this.httpClient = new HttpClient({
+      apiKey: config.apiKey,
+      serviceUrl: config.serviceUrl ?? DEFAULT_SERVICE_URL,
+      timeout: config.timeout ?? 1e4
+    });
+    this.traceFunctionKey = config.traceFunctionKey;
+    this.getActiveSpanContext = config.getActiveSpanContext ?? null;
+  }
+  // ── lifecycle helpers ──────────────────────────────────────────
+  startSpan(runId, parentRunId, name, spanType, inputData, metadata, tags) {
+    const parentSpan = parentRunId ? this.runToSpan.get(parentRunId) : void 0;
+    const willHide = tags?.includes(LANGSMITH_HIDDEN_TAG) === true;
+    let invocation;
+    let effectiveParentId;
+    if (parentSpan) {
+      const existing = this.invocations.get(parentSpan.rootRunId);
+      if (existing) {
+        invocation = existing;
+      } else {
+        invocation = {
+          traceId: parentSpan.traceId,
+          activeContext: null,
+          rootRunId: parentSpan.rootRunId
+        };
+        this.invocations.set(invocation.rootRunId, invocation);
+      }
+      if (!willHide) {
+        let resolved = parentSpan;
+        while (resolved?.hidden === true) {
+          resolved = resolved.parentId ? this.runToSpan.get(resolved.parentId) : void 0;
+        }
+        effectiveParentId = resolved ? resolved.spanId : invocation.activeContext?.spanId ?? null;
+      } else {
+        effectiveParentId = parentRunId ?? null;
+      }
+    } else {
+      const activeContext = this.getActiveSpanContext?.() ?? null;
+      invocation = {
+        traceId: activeContext ? activeContext.traceId : crypto.randomUUID(),
+        activeContext,
+        rootRunId: runId
+      };
+      this.invocations.set(runId, invocation);
+      effectiveParentId = activeContext?.spanId ?? null;
+    }
+    const lgMetadata = extractLangGraphMetadata(metadata);
+    const contexts = Object.keys(lgMetadata).length > 0 ? [lgMetadata] : [];
+    const spanInfo = {
+      spanId: runId,
+      traceId: invocation.traceId,
+      rootRunId: invocation.rootRunId,
+      parentId: effectiveParentId,
+      startedAt: nowIso2(),
+      name,
+      type: spanType,
+      input: safeSerialize2(inputData),
+      contexts
+    };
+    if (willHide) {
+      spanInfo.hidden = true;
+    }
+    this.runToSpan.set(runId, spanInfo);
+    return spanInfo;
+  }
+  completeSpan(runId, output, error, extraContexts) {
+    const spanInfo = this.runToSpan.get(runId);
+    if (!spanInfo) {
+      return;
+    }
+    this.runToSpan.delete(runId);
+    spanInfo.endedAt = nowIso2();
+    spanInfo.output = safeSerialize2(output);
+    if (error !== void 0) {
+      spanInfo.error = error;
+    }
+    if (extraContexts && Object.keys(extraContexts).length > 0) {
+      spanInfo.contexts.push(extraContexts);
+    }
+    this.sendSpan(spanInfo);
+    if (runId === spanInfo.rootRunId) {
+      const invocation = this.invocations.get(runId);
+      this.sendTraceCompletion(spanInfo, invocation?.activeContext ?? null);
+      this.invocations.delete(runId);
+    }
+  }
+  sendSpan(spanInfo) {
+    const spanData = {
+      name: spanInfo.name,
+      type: spanInfo.type
+    };
+    if (spanInfo.input !== void 0) {
+      spanData.input = spanInfo.input;
+    }
+    if (spanInfo.output !== void 0) {
+      spanData.output = spanInfo.output;
+    }
+    if (spanInfo.error !== void 0) {
+      spanData.error = spanInfo.error;
+    }
+    if (spanInfo.contexts.length > 0) {
+      spanData.contexts = spanInfo.contexts;
+    }
+    if (spanInfo.hidden) {
+      spanData.hidden = true;
+    }
+    const rawSpan = {
+      id: spanInfo.spanId,
+      trace_id: spanInfo.traceId,
+      started_at: spanInfo.startedAt,
+      ended_at: spanInfo.endedAt ?? nowIso2(),
+      span_data: spanData
+    };
+    if (spanInfo.parentId !== null) {
+      rawSpan.parent_id = spanInfo.parentId;
+    }
+    const payload = {
+      type: "sdk-function",
+      source: "typescript-sdk-langgraph",
+      traceFunctionKey: this.traceFunctionKey,
+      sourceTraceId: spanInfo.traceId,
+      rawSpan
+    };
+    try {
+      this.httpClient.sendExternalSpan(payload);
+    } catch {
+    }
+  }
+  sendTraceCompletion(rootSpan, activeContext) {
+    const completed = activeContext === null;
+    const traceData = {
+      type: "sdk-function",
+      source: "typescript-sdk-langgraph",
+      traceFunctionKey: this.traceFunctionKey,
+      externalTrace: {
+        id: rootSpan.traceId,
+        started_at: rootSpan.startedAt,
+        ended_at: rootSpan.endedAt ?? nowIso2(),
+        workflow_name: this.traceFunctionKey
+      },
+      completed
+    };
+    try {
+      this.httpClient.sendExternalTrace(traceData);
+    } catch {
+    }
+  }
+  // ── chain callbacks (graph nodes) ─────────────────────────────
+  async handleChainStart(chain, inputs, runId, parentRunId, tags, metadata) {
+    try {
+      const idArr = chain.id;
+      const name = chain.name ?? idArr?.[idArr.length - 1] ?? "chain";
+      this.startSpan(
+        runId,
+        parentRunId,
+        String(name),
+        "agent",
+        inputs,
+        metadata,
+        tags
+      );
+    } catch {
+    }
+  }
+  async handleChainEnd(outputs, runId) {
+    try {
+      this.completeSpan(runId, outputs);
+    } catch {
+    }
+  }
+  async handleChainError(error, runId) {
+    try {
+      const errorObj = error;
+      if (errorObj?.constructor?.name === "GraphBubbleUp") {
+        this.completeSpan(runId, void 0, void 0);
+        return;
+      }
+      this.completeSpan(
+        runId,
+        void 0,
+        error instanceof Error ? error.message : String(error)
+      );
+    } catch {
+    }
+  }
+  // ── LLM callbacks ─────────────────────────────────────────────
+  async handleChatModelStart(llm, messages, runId, parentRunId, _extraParams, tags, metadata) {
+    try {
+      const model = extractModelName(llm, metadata);
+      const idArr = llm.id;
+      const name = model ?? idArr?.[idArr.length - 1] ?? "llm";
+      const converted = messages.map((batch) => batch.map(convertMessage));
+      const spanInfo = this.startSpan(
+        runId,
+        parentRunId,
+        String(name),
+        "llm",
+        converted,
+        metadata,
+        tags
+      );
+      spanInfo.model = model;
+    } catch {
+    }
+  }
+  async handleLLMStart(llm, prompts, runId, parentRunId, _extraParams, tags, metadata) {
+    try {
+      const model = extractModelName(llm, metadata);
+      const idArr = llm.id;
+      const name = model ?? idArr?.[idArr.length - 1] ?? "llm";
+      const spanInfo = this.startSpan(
+        runId,
+        parentRunId,
+        String(name),
+        "llm",
+        prompts,
+        metadata,
+        tags
+      );
+      spanInfo.model = model;
+    } catch {
+    }
+  }
+  async handleLLMEnd(output, runId) {
+    try {
+      let llmOutput;
+      const generations = output.generations;
+      if (generations?.length && generations[generations.length - 1]?.length) {
+        const gen = generations[generations.length - 1][generations[generations.length - 1].length - 1];
+        const msg = gen.message;
+        llmOutput = msg ? convertMessage(msg) : gen.text ?? String(gen);
+      }
+      const usage = extractUsage2(output);
+      const spanInfo = this.runToSpan.get(runId);
+      const model = spanInfo?.model;
+      const llmContext = {};
+      if (model) {
+        llmContext.model = model;
+      }
+      Object.assign(llmContext, usage);
+      this.completeSpan(
+        runId,
+        llmOutput,
+        void 0,
+        Object.keys(llmContext).length > 0 ? llmContext : void 0
+      );
+    } catch {
+    }
+  }
+  async handleLLMError(error, runId) {
+    try {
+      this.completeSpan(
+        runId,
+        void 0,
+        error instanceof Error ? error.message : String(error)
+      );
+    } catch {
+    }
+  }
+  async handleLLMNewToken() {
+  }
+  // ── tool callbacks ────────────────────────────────────────────
+  async handleToolStart(tool, input, runId, parentRunId, tags, metadata) {
+    try {
+      const name = tool.name ?? "tool";
+      this.startSpan(
+        runId,
+        parentRunId,
+        String(name),
+        "function",
+        input,
+        metadata,
+        tags
+      );
+    } catch {
+    }
+  }
+  async handleToolEnd(output, runId) {
+    try {
+      this.completeSpan(runId, output);
+    } catch {
+    }
+  }
+  async handleToolError(error, runId) {
+    try {
+      this.completeSpan(
+        runId,
+        void 0,
+        error instanceof Error ? error.message : String(error)
+      );
+    } catch {
+    }
+  }
+  // ── retriever callbacks ───────────────────────────────────────
+  async handleRetrieverStart(retriever, query, runId, parentRunId, tags, metadata) {
+    try {
+      const name = retriever.name ?? "retriever";
+      this.startSpan(
+        runId,
+        parentRunId,
+        String(name),
+        "function",
+        query,
+        metadata,
+        tags
+      );
+    } catch {
+    }
+  }
+  async handleRetrieverEnd(documents, runId) {
+    try {
+      this.completeSpan(runId, documents);
+    } catch {
+    }
+  }
+  async handleRetrieverError(error, runId) {
+    try {
+      this.completeSpan(
+        runId,
+        void 0,
+        error instanceof Error ? error.message : String(error)
+      );
+    } catch {
+    }
+  }
+};
+
+// src/client.ts
 init_replayContext();
 init_serialize();
 
@@ -1314,6 +2270,67 @@ var Bitfab = class {
       }
     });
   }
+  /**
+   * Get a LangGraph/LangChain callback handler for tracing.
+   *
+   * The handler captures graph node execution, LLM calls, and tool
+   * invocations as Bitfab spans with proper parent-child hierarchy.
+   *
+   * ```typescript
+   * const handler = client.getLangGraphCallbackHandler("my-agent");
+   * const result = await agent.invoke(
+   *   { messages: [...] },
+   *   { callbacks: [handler] },
+   * );
+   * ```
+   *
+   * @param traceFunctionKey - Groups traces under this key in Bitfab
+   * @returns A BitfabLangGraphCallbackHandler configured for this client
+   */
+  getLangGraphCallbackHandler(traceFunctionKey) {
+    return new BitfabLangGraphCallbackHandler({
+      apiKey: this.apiKey,
+      traceFunctionKey,
+      serviceUrl: this.serviceUrl,
+      getActiveSpanContext: () => {
+        const stack = getSpanStack();
+        return stack[stack.length - 1] ?? null;
+      }
+    });
+  }
+  /**
+   * Get a Claude Agent SDK handler for tracing.
+   *
+   * The handler captures LLM turns, tool invocations, and subagent
+   * execution as Bitfab spans with proper parent-child hierarchy.
+   *
+   * ```typescript
+   * 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())) {
+   *   // process messages
+   * }
+   * ```
+   *
+   * @param traceFunctionKey - Groups traces under this key in Bitfab
+   * @returns A BitfabClaudeAgentHandler configured for this client
+   */
+  getClaudeAgentHandler(traceFunctionKey) {
+    return new BitfabClaudeAgentHandler({
+      apiKey: this.apiKey,
+      traceFunctionKey,
+      serviceUrl: this.serviceUrl,
+      getActiveSpanContext: () => {
+        const stack = getSpanStack();
+        return stack[stack.length - 1] ?? null;
+      }
+    });
+  }
   /**
    * Wrap a BAML client method to automatically capture prompt and LLM metadata.
    *
@@ -1719,8 +2736,10 @@ init_http();
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Bitfab,
+  BitfabClaudeAgentHandler,
   BitfabError,
   BitfabFunction,
+  BitfabLangGraphCallbackHandler,
   BitfabOpenAITracingProcessor,
   DEFAULT_SERVICE_URL,
   __version__,