@bitfab/sdk 0.24.0 → 0.25.0

package/dist/index.d.cts

@@ -651,6 +651,30 @@ interface ReplayOptions {
      * Omit it to spread the recorded inputs unchanged.
      */
     adaptInputs?: (inputs: unknown[], ctx: AdaptContext) => unknown[];
+    /**
+     * Called once per item as it finishes, in completion order (not input
+     * order), with running totals for the whole run. Use it to render replay
+     * progress, for example a terminal progress bar. Replay does not know
+     * pass/fail at this point (verdicts are assigned later), so the totals only
+     * distinguish items whose function ran (`succeeded`) from items that threw
+     * (`errored`).
+     *
+     * Invoked synchronously right after each item settles, so keep it cheap. A
+     * throwing callback never crashes the run: the error is swallowed so progress
+     * UI can't break replay.
+     */
+    onProgress?: (progress: ReplayProgress) => void;
+}
+/** Running totals reported to {@link ReplayOptions.onProgress} as replay proceeds. */
+interface ReplayProgress {
+    /** Items that have finished so far, whether they succeeded or errored. */
+    completed: number;
+    /** Total number of items in this replay run. */
+    total: number;
+    /** Of the completed items, how many ran the function without throwing. */
+    succeeded: number;
+    /** Of the completed items, how many threw (their `item.error` is set). */
+    errored: number;
 }
 /** Per-trace context passed to {@link ReplayOptions.adaptInputs}. */
 interface AdaptContext {
@@ -684,7 +708,13 @@ interface ReplayItem<T> {
     error: string | null;
     /** Original trace duration in milliseconds, or null if timestamps are missing. */
     durationMs: number | null;
-    /** Token usage from the original trace, or null if not captured. */
+    /**
+     * Token usage from the REPLAYED run (this item's new execution), aggregated
+     * server-side from the spans it produced, or null if the run captured no
+     * token data. This is the "new" side of a token delta: compare it against
+     * the original trace's recorded usage to see how the code change moved cost.
+     * Matches what Studio's experiments view shows.
+     */
     tokens: TokenUsage | null;
     /** Model name from the original trace, or null if not captured. */
     model: string | null;
@@ -1374,7 +1404,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.24.0";
+declare const __version__ = "0.25.0";
 
 /**
  * Constants for the Bitfab SDK.
@@ -1442,4 +1472,4 @@ declare const finalizers: {
     readableStream: typeof readableStream;
 };
 
-export { type ActiveSpanContext, type AdaptContext, type AdaptInputsFn, type AllowedEnvVars, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler as BitfabLangChainCallbackHandler, BitfabLangGraphCallbackHandler, type BitfabLanguageModelMiddleware, BitfabOpenAIAgentHandler, BitfabOpenAITracingProcessor, BitfabVercelAiHandler, type CodeChangeFile, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, type MockStrategy, type ProviderDefinition, ReplayEnvironment, type ReplayEnvironmentSnapshot, type ReplayItem, type ReplayOptions, type ReplayResult, SUPPORTED_PROVIDERS, type SpanOptions, type SpanType, type TokenUsage, type TraceResponse, type TracingProcessor, type VercelCallParams, type VercelGenerateResult, type VercelStreamResult, type WrapBAMLOptions, type WrappedBamlFn, __version__, finalizers, flushTraces, getCurrentSpan, getCurrentTrace };
+export { type ActiveSpanContext, type AdaptContext, type AdaptInputsFn, type AllowedEnvVars, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler as BitfabLangChainCallbackHandler, BitfabLangGraphCallbackHandler, type BitfabLanguageModelMiddleware, BitfabOpenAIAgentHandler, BitfabOpenAITracingProcessor, BitfabVercelAiHandler, type CodeChangeFile, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, type MockStrategy, type ProviderDefinition, ReplayEnvironment, type ReplayEnvironmentSnapshot, type ReplayItem, type ReplayOptions, type ReplayProgress, type ReplayResult, SUPPORTED_PROVIDERS, type SpanOptions, type SpanType, type TokenUsage, type TraceResponse, type TracingProcessor, type VercelCallParams, type VercelGenerateResult, type VercelStreamResult, type WrapBAMLOptions, type WrappedBamlFn, __version__, finalizers, flushTraces, getCurrentSpan, getCurrentTrace };

package/dist/index.d.ts

@@ -651,6 +651,30 @@ interface ReplayOptions {
      * Omit it to spread the recorded inputs unchanged.
      */
     adaptInputs?: (inputs: unknown[], ctx: AdaptContext) => unknown[];
+    /**
+     * Called once per item as it finishes, in completion order (not input
+     * order), with running totals for the whole run. Use it to render replay
+     * progress, for example a terminal progress bar. Replay does not know
+     * pass/fail at this point (verdicts are assigned later), so the totals only
+     * distinguish items whose function ran (`succeeded`) from items that threw
+     * (`errored`).
+     *
+     * Invoked synchronously right after each item settles, so keep it cheap. A
+     * throwing callback never crashes the run: the error is swallowed so progress
+     * UI can't break replay.
+     */
+    onProgress?: (progress: ReplayProgress) => void;
+}
+/** Running totals reported to {@link ReplayOptions.onProgress} as replay proceeds. */
+interface ReplayProgress {
+    /** Items that have finished so far, whether they succeeded or errored. */
+    completed: number;
+    /** Total number of items in this replay run. */
+    total: number;
+    /** Of the completed items, how many ran the function without throwing. */
+    succeeded: number;
+    /** Of the completed items, how many threw (their `item.error` is set). */
+    errored: number;
 }
 /** Per-trace context passed to {@link ReplayOptions.adaptInputs}. */
 interface AdaptContext {
@@ -684,7 +708,13 @@ interface ReplayItem<T> {
     error: string | null;
     /** Original trace duration in milliseconds, or null if timestamps are missing. */
     durationMs: number | null;
-    /** Token usage from the original trace, or null if not captured. */
+    /**
+     * Token usage from the REPLAYED run (this item's new execution), aggregated
+     * server-side from the spans it produced, or null if the run captured no
+     * token data. This is the "new" side of a token delta: compare it against
+     * the original trace's recorded usage to see how the code change moved cost.
+     * Matches what Studio's experiments view shows.
+     */
     tokens: TokenUsage | null;
     /** Model name from the original trace, or null if not captured. */
     model: string | null;
@@ -1374,7 +1404,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.24.0";
+declare const __version__ = "0.25.0";
 
 /**
  * Constants for the Bitfab SDK.
@@ -1442,4 +1472,4 @@ declare const finalizers: {
     readableStream: typeof readableStream;
 };
 
-export { type ActiveSpanContext, type AdaptContext, type AdaptInputsFn, type AllowedEnvVars, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler as BitfabLangChainCallbackHandler, BitfabLangGraphCallbackHandler, type BitfabLanguageModelMiddleware, BitfabOpenAIAgentHandler, BitfabOpenAITracingProcessor, BitfabVercelAiHandler, type CodeChangeFile, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, type MockStrategy, type ProviderDefinition, ReplayEnvironment, type ReplayEnvironmentSnapshot, type ReplayItem, type ReplayOptions, type ReplayResult, SUPPORTED_PROVIDERS, type SpanOptions, type SpanType, type TokenUsage, type TraceResponse, type TracingProcessor, type VercelCallParams, type VercelGenerateResult, type VercelStreamResult, type WrapBAMLOptions, type WrappedBamlFn, __version__, finalizers, flushTraces, getCurrentSpan, getCurrentTrace };
+export { type ActiveSpanContext, type AdaptContext, type AdaptInputsFn, type AllowedEnvVars, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler as BitfabLangChainCallbackHandler, BitfabLangGraphCallbackHandler, type BitfabLanguageModelMiddleware, BitfabOpenAIAgentHandler, BitfabOpenAITracingProcessor, BitfabVercelAiHandler, type CodeChangeFile, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, type MockStrategy, type ProviderDefinition, ReplayEnvironment, type ReplayEnvironmentSnapshot, type ReplayItem, type ReplayOptions, type ReplayProgress, type ReplayResult, SUPPORTED_PROVIDERS, type SpanOptions, type SpanType, type TokenUsage, type TraceResponse, type TracingProcessor, type VercelCallParams, type VercelGenerateResult, type VercelStreamResult, type WrapBAMLOptions, type WrappedBamlFn, __version__, finalizers, flushTraces, getCurrentSpan, getCurrentTrace };

package/dist/index.js

@@ -14,7 +14,7 @@ import {
   flushTraces,
   getCurrentSpan,
   getCurrentTrace
-} from "./chunk-S3PN26RH.js";
+} from "./chunk-GQLNEYSU.js";
 import {
   BitfabError
 } from "./chunk-26MUT4IP.js";

package/dist/node.cjs

@@ -412,18 +412,23 @@ async function processItem(httpClient, serverItem, fn, testRunId, mockStrategy,
     originalOutput,
     error,
     durationMs: serverItem.durationMs ?? null,
-    tokens: serverItem.tokens ?? null,
+    // Filled in by replay() from the complete-replay response once the
+    // replay traces are persisted and their spans aggregated server-side.
+    // Null here (and on older servers) means "replay tokens not known".
+    tokens: null,
     model: serverItem.model ?? null,
     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(
@@ -483,9 +488,29 @@ 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;
   if (serverTraceIds === void 0) {
     try {
       console.warn(
@@ -508,6 +533,9 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options) {
             missing.push(item.traceId);
           }
         }
+        if (mapped !== void 0) {
+          item.tokens = replayTokens?.[mapped] ?? null;
+        }
         item.traceId = mapped ?? null;
       }
     }
@@ -573,7 +601,7 @@ registerAsyncLocalStorageClass(
 );
 
 // src/version.generated.ts
-var __version__ = "0.24.0";
+var __version__ = "0.25.0";
 
 // src/constants.ts
 var DEFAULT_SERVICE_URL = "https://bitfab.ai";