@bitfab/sdk 0.27.0 → 0.27.2

package/dist/index.d.cts

@@ -411,18 +411,19 @@ declare class BitfabLangGraphCallbackHandler {
     private completeSpan;
     private sendSpan;
     private sendTraceCompletion;
-    handleChainStart(chain: Record<string, unknown>, inputs: Record<string, unknown>, runId: string, parentRunId?: string, tags?: string[], metadata?: Record<string, unknown>): Promise<void>;
+    private sendTraceStart;
+    handleChainStart(chain: Record<string, unknown> | null | undefined, inputs: Record<string, unknown>, runId: string, parentRunIdOrRunType?: string, tags?: string[], metadata?: Record<string, unknown>, runTypeOrRunName?: string, runNameOrParentRunId?: string): Promise<void>;
     handleChainEnd(outputs: Record<string, unknown>, runId: string): Promise<void>;
     handleChainError(error: unknown, runId: string): Promise<void>;
-    handleChatModelStart(llm: Record<string, unknown>, messages: unknown[][], runId: string, parentRunId?: string, _extraParams?: Record<string, unknown>, tags?: string[], metadata?: Record<string, unknown>): Promise<void>;
-    handleLLMStart(llm: Record<string, unknown>, prompts: string[], runId: string, parentRunId?: string, _extraParams?: Record<string, unknown>, tags?: string[], metadata?: Record<string, unknown>): Promise<void>;
+    handleChatModelStart(llm: Record<string, unknown> | null | undefined, messages: unknown[][], runId: string, parentRunId?: string, _extraParams?: Record<string, unknown>, tags?: string[], metadata?: Record<string, unknown>, runName?: string): Promise<void>;
+    handleLLMStart(llm: Record<string, unknown> | null | undefined, prompts: string[], runId: string, parentRunId?: string, _extraParams?: Record<string, unknown>, tags?: string[], metadata?: Record<string, unknown>, runName?: string): Promise<void>;
     handleLLMEnd(output: Record<string, unknown>, runId: string): Promise<void>;
     handleLLMError(error: unknown, runId: string): Promise<void>;
     handleLLMNewToken(): Promise<void>;
-    handleToolStart(tool: Record<string, unknown>, input: string, runId: string, parentRunId?: string, tags?: string[], metadata?: Record<string, unknown>): Promise<void>;
+    handleToolStart(tool: Record<string, unknown> | null | undefined, input: string, runId: string, parentRunId?: string, tags?: string[], metadata?: Record<string, unknown>, runName?: string): Promise<void>;
     handleToolEnd(output: unknown, runId: string): Promise<void>;
     handleToolError(error: unknown, runId: string): Promise<void>;
-    handleRetrieverStart(retriever: Record<string, unknown>, query: string, runId: string, parentRunId?: string, tags?: string[], metadata?: Record<string, unknown>): Promise<void>;
+    handleRetrieverStart(retriever: Record<string, unknown> | null | undefined, query: string, runId: string, parentRunId?: string, tags?: string[], metadata?: Record<string, unknown>, runName?: string): Promise<void>;
     handleRetrieverEnd(documents: unknown, runId: string): Promise<void>;
     handleRetrieverError(error: unknown, runId: string): Promise<void>;
 }
@@ -594,6 +595,8 @@ interface ReplayOptions {
     limit?: number;
     /** Optional list of specific trace IDs to replay (max 100). */
     traceIds?: string[];
+    /** Optional display name for the resulting experiment/test run. */
+    name?: string;
     /** Maximum number of items to process in parallel. Set to 1 for sequential. Default 10. */
     maxConcurrency?: number;
     /**
@@ -1528,7 +1531,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.27.0";
+declare const __version__ = "0.27.2";
 
 /**
  * Constants for the Bitfab SDK.

package/dist/index.d.ts

@@ -411,18 +411,19 @@ declare class BitfabLangGraphCallbackHandler {
     private completeSpan;
     private sendSpan;
     private sendTraceCompletion;
-    handleChainStart(chain: Record<string, unknown>, inputs: Record<string, unknown>, runId: string, parentRunId?: string, tags?: string[], metadata?: Record<string, unknown>): Promise<void>;
+    private sendTraceStart;
+    handleChainStart(chain: Record<string, unknown> | null | undefined, inputs: Record<string, unknown>, runId: string, parentRunIdOrRunType?: string, tags?: string[], metadata?: Record<string, unknown>, runTypeOrRunName?: string, runNameOrParentRunId?: string): Promise<void>;
     handleChainEnd(outputs: Record<string, unknown>, runId: string): Promise<void>;
     handleChainError(error: unknown, runId: string): Promise<void>;
-    handleChatModelStart(llm: Record<string, unknown>, messages: unknown[][], runId: string, parentRunId?: string, _extraParams?: Record<string, unknown>, tags?: string[], metadata?: Record<string, unknown>): Promise<void>;
-    handleLLMStart(llm: Record<string, unknown>, prompts: string[], runId: string, parentRunId?: string, _extraParams?: Record<string, unknown>, tags?: string[], metadata?: Record<string, unknown>): Promise<void>;
+    handleChatModelStart(llm: Record<string, unknown> | null | undefined, messages: unknown[][], runId: string, parentRunId?: string, _extraParams?: Record<string, unknown>, tags?: string[], metadata?: Record<string, unknown>, runName?: string): Promise<void>;
+    handleLLMStart(llm: Record<string, unknown> | null | undefined, prompts: string[], runId: string, parentRunId?: string, _extraParams?: Record<string, unknown>, tags?: string[], metadata?: Record<string, unknown>, runName?: string): Promise<void>;
     handleLLMEnd(output: Record<string, unknown>, runId: string): Promise<void>;
     handleLLMError(error: unknown, runId: string): Promise<void>;
     handleLLMNewToken(): Promise<void>;
-    handleToolStart(tool: Record<string, unknown>, input: string, runId: string, parentRunId?: string, tags?: string[], metadata?: Record<string, unknown>): Promise<void>;
+    handleToolStart(tool: Record<string, unknown> | null | undefined, input: string, runId: string, parentRunId?: string, tags?: string[], metadata?: Record<string, unknown>, runName?: string): Promise<void>;
     handleToolEnd(output: unknown, runId: string): Promise<void>;
     handleToolError(error: unknown, runId: string): Promise<void>;
-    handleRetrieverStart(retriever: Record<string, unknown>, query: string, runId: string, parentRunId?: string, tags?: string[], metadata?: Record<string, unknown>): Promise<void>;
+    handleRetrieverStart(retriever: Record<string, unknown> | null | undefined, query: string, runId: string, parentRunId?: string, tags?: string[], metadata?: Record<string, unknown>, runName?: string): Promise<void>;
     handleRetrieverEnd(documents: unknown, runId: string): Promise<void>;
     handleRetrieverError(error: unknown, runId: string): Promise<void>;
 }
@@ -594,6 +595,8 @@ interface ReplayOptions {
     limit?: number;
     /** Optional list of specific trace IDs to replay (max 100). */
     traceIds?: string[];
+    /** Optional display name for the resulting experiment/test run. */
+    name?: string;
     /** Maximum number of items to process in parallel. Set to 1 for sequential. Default 10. */
     maxConcurrency?: number;
     /**
@@ -1528,7 +1531,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.27.0";
+declare const __version__ = "0.27.2";
 
 /**
  * Constants for the Bitfab SDK.

package/dist/index.js

@@ -14,12 +14,12 @@ import {
   flushTraces,
   getCurrentSpan,
   getCurrentTrace
-} from "./chunk-PFV4MPNS.js";
+} from "./chunk-DW246LVL.js";
 import {
   BITFAB_PROGRESS_PREFIX,
   BitfabError,
   reportReplayProgress
-} from "./chunk-RNTDM6WM.js";
+} from "./chunk-MD4XQGAF.js";
 export {
   BITFAB_PROGRESS_PREFIX,
   Bitfab,

package/dist/node.cjs

@@ -499,6 +499,7 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options) {
     // the count), so it's omitted from the request entirely.
     options?.traceIds ? void 0 : options?.limit ?? 5,
     options?.traceIds,
+    options?.name,
     options?.codeChangeDescription,
     options?.codeChangeFiles,
     options?.environment !== void 0,
@@ -649,7 +650,7 @@ registerAsyncLocalStorageClass(
 );
 
 // src/version.generated.ts
-var __version__ = "0.27.0";
+var __version__ = "0.27.2";
 
 // src/constants.ts
 var DEFAULT_SERVICE_URL = "https://bitfab.ai";
@@ -957,7 +958,7 @@ var HttpClient = class {
    * Start a replay session by fetching historical traces.
    * Blocking call — creates a test run and returns lightweight item references.
    */
-  async startReplay(traceFunctionKey, limit, traceIds, codeChangeDescription, codeChangeFiles, includeDbBranchLease, experimentGroupId, datasetId) {
+  async startReplay(traceFunctionKey, limit, traceIds, name, codeChangeDescription, codeChangeFiles, includeDbBranchLease, experimentGroupId, datasetId) {
     const payload = { traceFunctionKey };
     if (limit !== void 0) {
       payload.limit = limit;
@@ -965,6 +966,9 @@ var HttpClient = class {
     if (traceIds) {
       payload.traceIds = traceIds;
     }
+    if (name !== void 0) {
+      payload.name = name;
+    }
     if (codeChangeDescription !== void 0) {
       payload.codeChangeDescription = codeChangeDescription;
     }
@@ -2006,6 +2010,7 @@ function buildSnapshotRef(config, sdkWallClockBeforeFn) {
 init_randomUuid();
 init_serialize();
 var LANGSMITH_HIDDEN_TAG = "langsmith:hidden";
+var CHAIN_RUN_TYPES = /* @__PURE__ */ new Set(["chain", "parser", "prompt"]);
 var LANGGRAPH_METADATA_KEYS = [
   "langgraph_step",
   "langgraph_node",
@@ -2016,6 +2021,18 @@ var LANGGRAPH_METADATA_KEYS = [
 function nowIso2() {
   return (/* @__PURE__ */ new Date()).toISOString();
 }
+function normalizeChainStartArgs(parentRunIdOrRunType, runTypeOrRunName, runNameOrParentRunId) {
+  if (parentRunIdOrRunType && CHAIN_RUN_TYPES.has(parentRunIdOrRunType)) {
+    return {
+      parentRunId: runNameOrParentRunId,
+      runName: runTypeOrRunName
+    };
+  }
+  return {
+    parentRunId: parentRunIdOrRunType,
+    runName: runNameOrParentRunId
+  };
+}
 function convertMessage(message) {
   if (typeof message !== "object" || message === null) {
     return { role: "unknown", content: String(message) };
@@ -2227,6 +2244,7 @@ var BitfabLangGraphCallbackHandler = class {
     const willHide = tags?.includes(LANGSMITH_HIDDEN_TAG) === true;
     let invocation;
     let effectiveParentId;
+    let isRootInvocation = false;
     if (parentSpan) {
       const existing = this.invocations.get(parentSpan.rootRunId);
       if (existing) {
@@ -2257,6 +2275,7 @@ var BitfabLangGraphCallbackHandler = class {
       };
       this.invocations.set(runId, invocation);
       effectiveParentId = activeContext?.spanId ?? null;
+      isRootInvocation = true;
     }
     const lgMetadata = extractLangGraphMetadata(metadata);
     const contexts = Object.keys(lgMetadata).length > 0 ? [lgMetadata] : [];
@@ -2279,6 +2298,9 @@ var BitfabLangGraphCallbackHandler = class {
       spanInfo.hidden = true;
     }
     this.runToSpan.set(runId, spanInfo);
+    if (isRootInvocation) {
+      this.sendTraceStart(spanInfo);
+    }
     return spanInfo;
   }
   completeSpan(runId, output, error, extraContexts) {
@@ -2369,11 +2391,35 @@ var BitfabLangGraphCallbackHandler = class {
     } catch {
     }
   }
+  sendTraceStart(rootSpan) {
+    const traceData = {
+      type: "sdk-function",
+      source: "typescript-sdk-langgraph",
+      traceFunctionKey: this.traceFunctionKey,
+      externalTrace: {
+        id: rootSpan.traceId,
+        started_at: rootSpan.startedAt,
+        workflow_name: this.traceFunctionKey
+      },
+      completed: false
+    };
+    const finalized = finalizeTracePayload(traceData);
+    try {
+      this.httpClient.sendExternalTrace(finalized);
+    } catch {
+    }
+  }
   // ── chain callbacks (graph nodes) ─────────────────────────────
-  async handleChainStart(chain, inputs, runId, parentRunId, tags, metadata) {
+  async handleChainStart(chain, inputs, runId, parentRunIdOrRunType, tags, metadata, runTypeOrRunName, runNameOrParentRunId) {
     try {
-      const idArr = chain.id;
-      const name = chain.name ?? idArr?.[idArr.length - 1] ?? "chain";
+      const { parentRunId, runName } = normalizeChainStartArgs(
+        parentRunIdOrRunType,
+        runTypeOrRunName,
+        runNameOrParentRunId
+      );
+      const serialized = chain ?? {};
+      const idArr = serialized.id;
+      const name = runName ?? serialized.name ?? idArr?.[idArr.length - 1] ?? "chain";
       this.startSpan(
         runId,
         parentRunId,
@@ -2408,11 +2454,12 @@ var BitfabLangGraphCallbackHandler = class {
     }
   }
   // ── LLM callbacks ─────────────────────────────────────────────
-  async handleChatModelStart(llm, messages, runId, parentRunId, _extraParams, tags, metadata) {
+  async handleChatModelStart(llm, messages, runId, parentRunId, _extraParams, tags, metadata, runName) {
     try {
-      const model = extractModelName(llm, metadata);
-      const idArr = llm.id;
-      const name = model ?? idArr?.[idArr.length - 1] ?? "llm";
+      const serialized = llm ?? {};
+      const model = extractModelName(serialized, metadata);
+      const idArr = serialized.id;
+      const name = runName ?? model ?? idArr?.[idArr.length - 1] ?? "llm";
       const converted = messages.map((batch) => batch.map(convertMessage));
       const spanInfo = this.startSpan(
         runId,
@@ -2427,11 +2474,12 @@ var BitfabLangGraphCallbackHandler = class {
     } catch {
     }
   }
-  async handleLLMStart(llm, prompts, runId, parentRunId, _extraParams, tags, metadata) {
+  async handleLLMStart(llm, prompts, runId, parentRunId, _extraParams, tags, metadata, runName) {
     try {
-      const model = extractModelName(llm, metadata);
-      const idArr = llm.id;
-      const name = model ?? idArr?.[idArr.length - 1] ?? "llm";
+      const serialized = llm ?? {};
+      const model = extractModelName(serialized, metadata);
+      const idArr = serialized.id;
+      const name = runName ?? model ?? idArr?.[idArr.length - 1] ?? "llm";
       const spanInfo = this.startSpan(
         runId,
         parentRunId,
@@ -2484,9 +2532,10 @@ var BitfabLangGraphCallbackHandler = class {
   async handleLLMNewToken() {
   }
   // ── tool callbacks ────────────────────────────────────────────
-  async handleToolStart(tool, input, runId, parentRunId, tags, metadata) {
+  async handleToolStart(tool, input, runId, parentRunId, tags, metadata, runName) {
     try {
-      const name = tool.name ?? "tool";
+      const serialized = tool ?? {};
+      const name = runName ?? serialized.name ?? "tool";
       this.startSpan(
         runId,
         parentRunId,
@@ -2516,9 +2565,10 @@ var BitfabLangGraphCallbackHandler = class {
     }
   }
   // ── retriever callbacks ───────────────────────────────────────
-  async handleRetrieverStart(retriever, query, runId, parentRunId, tags, metadata) {
+  async handleRetrieverStart(retriever, query, runId, parentRunId, tags, metadata, runName) {
     try {
-      const name = retriever.name ?? "retriever";
+      const serialized = retriever ?? {};
+      const name = runName ?? serialized.name ?? "retriever";
       this.startSpan(
         runId,
         parentRunId,