@bitfab/sdk 0.26.2 → 0.27.1

package/dist/index.d.cts

@@ -579,9 +579,9 @@ declare class ReplayEnvironment {
  * Replay historical traces through a function and create a test run.
  *
  * The replay flow has three phases:
- * 1. Start — fetches historical traces from the server and creates a test run
- * 2. Execute — re-runs each trace's inputs through the provided function locally
- * 3. Complete — marks the test run as completed on the server
+ * 1. Start: fetches historical traces from the server and creates a test run
+ * 2. Execute: re-runs each trace's inputs through the provided function locally
+ * 3. Complete: marks the test run as completed on the server
  */
 
 type MockStrategy = "none" | "all" | "marked";
@@ -594,6 +594,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;
     /**
@@ -603,7 +605,7 @@ interface ReplayOptions {
     codeChangeDescription?: string;
     /**
      * Files edited as part of this code change. Each entry holds the file path
-     * and the full `before`/`after` contents — the agent reads each file before
+     * and the full `before`/`after` contents. The agent reads each file before
      * and after editing and passes the two strings. Use `""` for newly created
      * files (`before`) or deleted files (`after`).
      */
@@ -675,7 +677,44 @@ interface ReplayProgress {
     succeeded: number;
     /** Of the completed items, how many threw (their `item.error` is set). */
     errored: number;
+    /**
+     * The single item that just settled to produce this event. `traceId` is the
+     * source (historical) trace that was replayed (so a UI can identify or link
+     * it); `error` is its replay error, or null when it ran ok; `durationMs` is how
+     * long this one trace took to replay. Lets a progress UI show per-trace
+     * pass/fail and timing as the run streams, without waiting for the full
+     * {@link ReplayResult}.
+     */
+    item?: {
+        traceId: string | null;
+        error: string | null;
+        durationMs: number | null;
+    };
 }
+/**
+ * Wire prefix the Bitfab plugin scans for. Each line {@link reportReplayProgress}
+ * writes is this prefix followed by the JSON of the running totals (plus the
+ * settled `item`). The plugin polls these lines to report live progress while a
+ * replay runs in the background; keep the SDK emitter and the plugin parser in
+ * sync.
+ */
+declare const BITFAB_PROGRESS_PREFIX = "@@bitfab:progress ";
+/**
+ * A ready-made {@link ReplayOptions.onProgress} callback for replay scripts.
+ * Pass it straight in:
+ *
+ * ```ts
+ * await bitfab.replay("my-fn", fn, { limit, onProgress: reportReplayProgress })
+ * ```
+ *
+ * It writes one `@@bitfab:progress` line per trace to stderr, which the Bitfab
+ * plugin polls to report live progress while the replay runs in the background,
+ * so scripts never hand-format the wire protocol.
+ * stdout is left untouched for the ReplayResult JSON. Outside Node (no
+ * `process.stderr`, e.g. a browser) it is a no-op, and a write failure is
+ * swallowed so progress can never crash a run.
+ */
+declare function reportReplayProgress(progress: ReplayProgress): void;
 /** Per-trace context passed to {@link ReplayOptions.adaptInputs}. */
 interface AdaptContext {
     /** Bitfab trace ID of the historical trace being replayed. */
@@ -1491,7 +1530,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.26.2";
+declare const __version__ = "0.27.1";
 
 /**
  * Constants for the Bitfab SDK.
@@ -1559,4 +1598,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 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 };
+export { type ActiveSpanContext, type AdaptContext, type AdaptInputsFn, type AllowedEnvVars, BITFAB_PROGRESS_PREFIX, 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, reportReplayProgress };

package/dist/index.d.ts

@@ -579,9 +579,9 @@ declare class ReplayEnvironment {
  * Replay historical traces through a function and create a test run.
  *
  * The replay flow has three phases:
- * 1. Start — fetches historical traces from the server and creates a test run
- * 2. Execute — re-runs each trace's inputs through the provided function locally
- * 3. Complete — marks the test run as completed on the server
+ * 1. Start: fetches historical traces from the server and creates a test run
+ * 2. Execute: re-runs each trace's inputs through the provided function locally
+ * 3. Complete: marks the test run as completed on the server
  */
 
 type MockStrategy = "none" | "all" | "marked";
@@ -594,6 +594,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;
     /**
@@ -603,7 +605,7 @@ interface ReplayOptions {
     codeChangeDescription?: string;
     /**
      * Files edited as part of this code change. Each entry holds the file path
-     * and the full `before`/`after` contents — the agent reads each file before
+     * and the full `before`/`after` contents. The agent reads each file before
      * and after editing and passes the two strings. Use `""` for newly created
      * files (`before`) or deleted files (`after`).
      */
@@ -675,7 +677,44 @@ interface ReplayProgress {
     succeeded: number;
     /** Of the completed items, how many threw (their `item.error` is set). */
     errored: number;
+    /**
+     * The single item that just settled to produce this event. `traceId` is the
+     * source (historical) trace that was replayed (so a UI can identify or link
+     * it); `error` is its replay error, or null when it ran ok; `durationMs` is how
+     * long this one trace took to replay. Lets a progress UI show per-trace
+     * pass/fail and timing as the run streams, without waiting for the full
+     * {@link ReplayResult}.
+     */
+    item?: {
+        traceId: string | null;
+        error: string | null;
+        durationMs: number | null;
+    };
 }
+/**
+ * Wire prefix the Bitfab plugin scans for. Each line {@link reportReplayProgress}
+ * writes is this prefix followed by the JSON of the running totals (plus the
+ * settled `item`). The plugin polls these lines to report live progress while a
+ * replay runs in the background; keep the SDK emitter and the plugin parser in
+ * sync.
+ */
+declare const BITFAB_PROGRESS_PREFIX = "@@bitfab:progress ";
+/**
+ * A ready-made {@link ReplayOptions.onProgress} callback for replay scripts.
+ * Pass it straight in:
+ *
+ * ```ts
+ * await bitfab.replay("my-fn", fn, { limit, onProgress: reportReplayProgress })
+ * ```
+ *
+ * It writes one `@@bitfab:progress` line per trace to stderr, which the Bitfab
+ * plugin polls to report live progress while the replay runs in the background,
+ * so scripts never hand-format the wire protocol.
+ * stdout is left untouched for the ReplayResult JSON. Outside Node (no
+ * `process.stderr`, e.g. a browser) it is a no-op, and a write failure is
+ * swallowed so progress can never crash a run.
+ */
+declare function reportReplayProgress(progress: ReplayProgress): void;
 /** Per-trace context passed to {@link ReplayOptions.adaptInputs}. */
 interface AdaptContext {
     /** Bitfab trace ID of the historical trace being replayed. */
@@ -1491,7 +1530,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.26.2";
+declare const __version__ = "0.27.1";
 
 /**
  * Constants for the Bitfab SDK.
@@ -1559,4 +1598,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 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 };
+export { type ActiveSpanContext, type AdaptContext, type AdaptInputsFn, type AllowedEnvVars, BITFAB_PROGRESS_PREFIX, 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, reportReplayProgress };

package/dist/index.js

@@ -14,11 +14,14 @@ import {
   flushTraces,
   getCurrentSpan,
   getCurrentTrace
-} from "./chunk-DW7VTEO2.js";
+} from "./chunk-H5QQ54UI.js";
 import {
-  BitfabError
-} from "./chunk-IDGR2OIX.js";
+  BITFAB_PROGRESS_PREFIX,
+  BitfabError,
+  reportReplayProgress
+} from "./chunk-MD4XQGAF.js";
 export {
+  BITFAB_PROGRESS_PREFIX,
   Bitfab,
   BitfabClaudeAgentHandler,
   BitfabError,
@@ -35,6 +38,7 @@ export {
   finalizers,
   flushTraces,
   getCurrentSpan,
-  getCurrentTrace
+  getCurrentTrace,
+  reportReplayProgress
 };
 //# sourceMappingURL=index.js.map

package/dist/node.cjs

@@ -314,8 +314,21 @@ var init_replayContext = __esm({
 // src/replay.ts
 var replay_exports = {};
 __export(replay_exports, {
-  replay: () => replay
+  BITFAB_PROGRESS_PREFIX: () => BITFAB_PROGRESS_PREFIX,
+  replay: () => replay,
+  reportReplayProgress: () => reportReplayProgress
 });
+function reportReplayProgress(progress) {
+  const stderr = typeof process !== "undefined" ? process.stderr : void 0;
+  if (!stderr) {
+    return;
+  }
+  try {
+    stderr.write(`${BITFAB_PROGRESS_PREFIX}${JSON.stringify(progress)}
+`);
+  } catch {
+  }
+}
 function deserializeInputs(spanData) {
   const inputMeta = spanData.input_meta;
   const rawInput = spanData.input;
@@ -486,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,
@@ -513,7 +527,7 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options) {
   const resultItems = await mapWithConcurrency(
     tasks,
     maxConcurrency,
-    options?.onProgress ? (item) => {
+    options?.onProgress ? (item, index) => {
       completed += 1;
       if (item.error === null) {
         succeeded += 1;
@@ -521,7 +535,20 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options) {
         errored += 1;
       }
       try {
-        options?.onProgress?.({ completed, total, succeeded, errored });
+        options?.onProgress?.({
+          completed,
+          total,
+          succeeded,
+          errored,
+          item: {
+            // Source (historical) trace id, so a UI can identify the trace
+            // that just settled. The item's own traceId is the new replay
+            // trace and is assigned later (below), so use the server item.
+            traceId: serverItems[index]?.traceId ?? null,
+            error: item.error,
+            durationMs: item.durationMs
+          }
+        });
       } catch {
       }
     } : void 0
@@ -578,6 +605,7 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options) {
     testRunUrl: `${serviceUrl}${testRunUrl}`
   };
 }
+var BITFAB_PROGRESS_PREFIX;
 var init_replay = __esm({
   "src/replay.ts"() {
     "use strict";
@@ -585,12 +613,14 @@ var init_replay = __esm({
     init_randomUuid();
     init_replayContext();
     init_serialize();
+    BITFAB_PROGRESS_PREFIX = "@@bitfab:progress ";
   }
 });
 
 // src/node.ts
 var node_exports = {};
 __export(node_exports, {
+  BITFAB_PROGRESS_PREFIX: () => BITFAB_PROGRESS_PREFIX,
   Bitfab: () => Bitfab,
   BitfabClaudeAgentHandler: () => BitfabClaudeAgentHandler,
   BitfabError: () => BitfabError,
@@ -607,7 +637,8 @@ __export(node_exports, {
   finalizers: () => finalizers,
   flushTraces: () => flushTraces,
   getCurrentSpan: () => getCurrentSpan,
-  getCurrentTrace: () => getCurrentTrace
+  getCurrentTrace: () => getCurrentTrace,
+  reportReplayProgress: () => reportReplayProgress
 });
 module.exports = __toCommonJS(node_exports);
 
@@ -619,7 +650,7 @@ registerAsyncLocalStorageClass(
 );
 
 // src/version.generated.ts
-var __version__ = "0.26.2";
+var __version__ = "0.27.1";
 
 // src/constants.ts
 var DEFAULT_SERVICE_URL = "https://bitfab.ai";
@@ -927,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;
@@ -935,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;
     }
@@ -4361,11 +4395,15 @@ var finalizers = {
   readableStream
 };
 
+// src/index.ts
+init_replay();
+
 // src/node.ts
 init_asyncStorage();
 assertAsyncStorageRegistered();
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  BITFAB_PROGRESS_PREFIX,
   Bitfab,
   BitfabClaudeAgentHandler,
   BitfabError,
@@ -4382,6 +4420,7 @@ assertAsyncStorageRegistered();
   finalizers,
   flushTraces,
   getCurrentSpan,
-  getCurrentTrace
+  getCurrentTrace,
+  reportReplayProgress
 });
 //# sourceMappingURL=node.cjs.map