@bitfab/sdk 0.36.5 → 0.36.7

package/dist/index.d.cts

@@ -408,6 +408,7 @@ declare class HttpClient {
         timeout?: number;
         method?: "POST" | "PATCH" | "PUT";
     }): Promise<T>;
+    private sendPrepared;
     /**
      * Look up a function by name.
      * Blocks until complete - needed for function execution.
@@ -1213,31 +1214,56 @@ interface ReplayOptions {
      * distinguish items whose function ran (`succeeded`) from items that threw
      * (`errored`).
      *
-     * Invoked synchronously right after each item settles, so keep it cheap. A
+     * Invoked synchronously right after each item finishes, 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 {
+    onItemFinish?: (progress: ReplayItemFinishProgress) => void;
     /**
-     * Event kind. Omitted (or `"item"`) for the per-trace settle events streamed
-     * during the run. `"complete"` marks the single terminal event emitted once
-     * the run has settled and been enriched server-side; it carries the full
-     * {@link ReplayProgress.result} and has no `item`. The Bitfab plugin reads
-     * that terminal event to build the run's final result without parsing stdout.
+     * @deprecated Use {@link onItemFinish}. This compatibility callback receives
+     * the same per-item finish events plus the legacy whole-run `"complete"`
+     * event. It is ignored when `onItemFinish` is also provided.
      */
-    type?: "item" | "complete";
+    onProgress?: (progress: ReplayProgress) => void;
     /**
-     * The full {@link ReplayResult}, present only on the terminal `"complete"`
-     * event. Lets the plugin ingest the enriched result (server-aggregated tokens,
-     * server trace ids) over the same channel as progress, so a dependency logging
-     * to stdout can never block it.
+     * Called once when each replay item begins processing, before input loading,
+     * mock preparation, database branching, or the customer function runs. Use
+     * it with {@link onItemFinish} to distinguish queued items from items that
+     * are still in flight. A throwing callback never crashes the run.
      */
-    result?: ReplayResult<unknown>;
+    onItemStart?: (progress: ReplayItemStartProgress) => void;
+}
+/** Emitted through {@link ReplayOptions.onItemStart} when a worker starts an item. */
+interface ReplayItemStartProgress {
+    type: "started";
     /** Test run ID created for this replay. */
-    testRunId?: string;
+    testRunId: string;
+    /** Items whose processing has started so far. */
+    started: number;
+    /** 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 finished without a code or replay error. */
+    succeeded: number;
+    /** Of the completed items, how many finished with an error. */
+    errored: number;
+    /** The historical trace and span whose replay processing just started. */
+    item: {
+        originalTraceId: string;
+        originalSpanId: string;
+        /** @deprecated alias for `originalTraceId`. */
+        sourceTraceId: string;
+        /** @deprecated alias for `originalSpanId`. */
+        sourceSpanId: string;
+    };
+}
+/** Running totals reported to {@link ReplayOptions.onItemFinish} as replay proceeds. */
+interface ReplayItemFinishProgress {
+    /** Event kind, omitted for backward-compatible per-item events. */
+    type?: "item";
+    /** Test run ID created for this replay. */
+    testRunId: string;
     /** Items that have finished so far, whether they succeeded or errored. */
     completed: number;
     /** Total number of items in this replay run. */
@@ -1247,7 +1273,7 @@ interface ReplayProgress {
     /** Of the completed items, how many have `item.error` set. */
     errored: number;
     /**
-     * The single item that just settled to produce this event. `traceId` is null
+     * The single item that just finished to produce this event. `traceId` is null
      * at this stage (the server replay id isn't known until the run completes);
      * `originalTraceId` is the original (historical) trace that was replayed (so
      * a UI can identify or link it); `error` is its replay error, or null when it
@@ -1255,7 +1281,7 @@ interface ReplayProgress {
      * progress UI show per-trace pass/fail and timing as the run streams, without
      * waiting for the full {@link ReplayResult}.
      */
-    item?: {
+    item: {
         /** Trace ID of the new replay trace (null during the run; the server id arrives at completion). */
         traceId?: string | null;
         /** Bitfab trace ID of the original (historical) trace being replayed. */
@@ -1284,30 +1310,49 @@ interface ReplayProgress {
         dbSnapshotRef?: DbSnapshotRef | null;
     };
 }
+/**
+ * @deprecated Use {@link ReplayItemFinishProgress}. This legacy shape also
+ * represents the item-less terminal `"complete"` event emitted by
+ * {@link ReplayOptions.onProgress}.
+ */
+interface ReplayProgress {
+    type?: "item" | "complete";
+    result?: ReplayResult<unknown>;
+    testRunId?: string;
+    completed: number;
+    total: number;
+    succeeded: number;
+    errored: number;
+    item?: ReplayItemFinishProgress["item"];
+}
 /**
  * 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
+ * finished `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.
+ * A ready-made replay lifecycle callback for replay scripts.
  * Pass it straight in:
  *
  * ```ts
- * await bitfab.replay("my-fn", fn, { limit, onProgress: reportReplayProgress })
+ * await bitfab.replay("my-fn", fn, {
+ *   limit,
+ *   onItemStart: reportReplayProgress,
+ *   onItemFinish: 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,
+ * It writes `@@bitfab:progress` lines to stderr, which the Bitfab plugin polls
+ * to report in-flight and finished items while replay runs in the background,
  * so scripts never hand-format the wire protocol.
  * stdout is left untouched for direct-run 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;
+declare function reportReplayProgress(progress: ReplayItemFinishProgress | ReplayItemStartProgress | ReplayProgress): void;
 /** Per-trace context passed to {@link ReplayOptions.adaptInputs}. */
 interface AdaptContext {
     /** Bitfab trace ID of the original (historical) trace being replayed. */
@@ -2464,7 +2509,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.36.5";
+declare const __version__ = "0.36.7";
 
 /**
  * Constants for the Bitfab SDK.
@@ -2532,4 +2577,4 @@ declare const finalizers: {
     readableStream: typeof readableStream;
 };
 
-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 CaptureWhen, type CapturedSpan, type CodeChangeFile, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type DbBranchOptions, DbBranchReplayError, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, HttpClient, type MockOverride, type MockOverrideCtx, type MockStrategy, type MockValue, type NodeMatcher, type ProviderDefinition, ReplayBranch, ReplayError, type ReplayItem, type ReplayOptions, type ReplayProgress, type ReplayResult, SUPPORTED_PROVIDERS, type SpanLookup, type SpanMethodDecorator, type SpanMethodDecoratorContext, type SpanNodeMeta, type SpanOccurrence, type SpanOptions, type SpanType, type TokenUsage, type TraceResponse, type TracingProcessor, type VercelCallParams, type VercelGenerateResult, type VercelStreamResult, type WrapBAMLOptions, type WrappedBamlFn, __version__, finalizers, flushTraces, getCurrentReplayBranch, getCurrentSpan, getCurrentTrace, reportReplayProgress, serializeReplayResult };
+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 CaptureWhen, type CapturedSpan, type CodeChangeFile, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type DbBranchOptions, DbBranchReplayError, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, HttpClient, type MockOverride, type MockOverrideCtx, type MockStrategy, type MockValue, type NodeMatcher, type ProviderDefinition, ReplayBranch, ReplayError, type ReplayItem, type ReplayItemFinishProgress, type ReplayItemStartProgress, type ReplayOptions, type ReplayProgress, type ReplayResult, SUPPORTED_PROVIDERS, type SpanLookup, type SpanMethodDecorator, type SpanMethodDecoratorContext, type SpanNodeMeta, type SpanOccurrence, type SpanOptions, type SpanType, type TokenUsage, type TraceResponse, type TracingProcessor, type VercelCallParams, type VercelGenerateResult, type VercelStreamResult, type WrapBAMLOptions, type WrappedBamlFn, __version__, finalizers, flushTraces, getCurrentReplayBranch, getCurrentSpan, getCurrentTrace, reportReplayProgress, serializeReplayResult };

package/dist/index.d.ts

@@ -408,6 +408,7 @@ declare class HttpClient {
         timeout?: number;
         method?: "POST" | "PATCH" | "PUT";
     }): Promise<T>;
+    private sendPrepared;
     /**
      * Look up a function by name.
      * Blocks until complete - needed for function execution.
@@ -1213,31 +1214,56 @@ interface ReplayOptions {
      * distinguish items whose function ran (`succeeded`) from items that threw
      * (`errored`).
      *
-     * Invoked synchronously right after each item settles, so keep it cheap. A
+     * Invoked synchronously right after each item finishes, 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 {
+    onItemFinish?: (progress: ReplayItemFinishProgress) => void;
     /**
-     * Event kind. Omitted (or `"item"`) for the per-trace settle events streamed
-     * during the run. `"complete"` marks the single terminal event emitted once
-     * the run has settled and been enriched server-side; it carries the full
-     * {@link ReplayProgress.result} and has no `item`. The Bitfab plugin reads
-     * that terminal event to build the run's final result without parsing stdout.
+     * @deprecated Use {@link onItemFinish}. This compatibility callback receives
+     * the same per-item finish events plus the legacy whole-run `"complete"`
+     * event. It is ignored when `onItemFinish` is also provided.
      */
-    type?: "item" | "complete";
+    onProgress?: (progress: ReplayProgress) => void;
     /**
-     * The full {@link ReplayResult}, present only on the terminal `"complete"`
-     * event. Lets the plugin ingest the enriched result (server-aggregated tokens,
-     * server trace ids) over the same channel as progress, so a dependency logging
-     * to stdout can never block it.
+     * Called once when each replay item begins processing, before input loading,
+     * mock preparation, database branching, or the customer function runs. Use
+     * it with {@link onItemFinish} to distinguish queued items from items that
+     * are still in flight. A throwing callback never crashes the run.
      */
-    result?: ReplayResult<unknown>;
+    onItemStart?: (progress: ReplayItemStartProgress) => void;
+}
+/** Emitted through {@link ReplayOptions.onItemStart} when a worker starts an item. */
+interface ReplayItemStartProgress {
+    type: "started";
     /** Test run ID created for this replay. */
-    testRunId?: string;
+    testRunId: string;
+    /** Items whose processing has started so far. */
+    started: number;
+    /** 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 finished without a code or replay error. */
+    succeeded: number;
+    /** Of the completed items, how many finished with an error. */
+    errored: number;
+    /** The historical trace and span whose replay processing just started. */
+    item: {
+        originalTraceId: string;
+        originalSpanId: string;
+        /** @deprecated alias for `originalTraceId`. */
+        sourceTraceId: string;
+        /** @deprecated alias for `originalSpanId`. */
+        sourceSpanId: string;
+    };
+}
+/** Running totals reported to {@link ReplayOptions.onItemFinish} as replay proceeds. */
+interface ReplayItemFinishProgress {
+    /** Event kind, omitted for backward-compatible per-item events. */
+    type?: "item";
+    /** Test run ID created for this replay. */
+    testRunId: string;
     /** Items that have finished so far, whether they succeeded or errored. */
     completed: number;
     /** Total number of items in this replay run. */
@@ -1247,7 +1273,7 @@ interface ReplayProgress {
     /** Of the completed items, how many have `item.error` set. */
     errored: number;
     /**
-     * The single item that just settled to produce this event. `traceId` is null
+     * The single item that just finished to produce this event. `traceId` is null
      * at this stage (the server replay id isn't known until the run completes);
      * `originalTraceId` is the original (historical) trace that was replayed (so
      * a UI can identify or link it); `error` is its replay error, or null when it
@@ -1255,7 +1281,7 @@ interface ReplayProgress {
      * progress UI show per-trace pass/fail and timing as the run streams, without
      * waiting for the full {@link ReplayResult}.
      */
-    item?: {
+    item: {
         /** Trace ID of the new replay trace (null during the run; the server id arrives at completion). */
         traceId?: string | null;
         /** Bitfab trace ID of the original (historical) trace being replayed. */
@@ -1284,30 +1310,49 @@ interface ReplayProgress {
         dbSnapshotRef?: DbSnapshotRef | null;
     };
 }
+/**
+ * @deprecated Use {@link ReplayItemFinishProgress}. This legacy shape also
+ * represents the item-less terminal `"complete"` event emitted by
+ * {@link ReplayOptions.onProgress}.
+ */
+interface ReplayProgress {
+    type?: "item" | "complete";
+    result?: ReplayResult<unknown>;
+    testRunId?: string;
+    completed: number;
+    total: number;
+    succeeded: number;
+    errored: number;
+    item?: ReplayItemFinishProgress["item"];
+}
 /**
  * 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
+ * finished `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.
+ * A ready-made replay lifecycle callback for replay scripts.
  * Pass it straight in:
  *
  * ```ts
- * await bitfab.replay("my-fn", fn, { limit, onProgress: reportReplayProgress })
+ * await bitfab.replay("my-fn", fn, {
+ *   limit,
+ *   onItemStart: reportReplayProgress,
+ *   onItemFinish: 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,
+ * It writes `@@bitfab:progress` lines to stderr, which the Bitfab plugin polls
+ * to report in-flight and finished items while replay runs in the background,
  * so scripts never hand-format the wire protocol.
  * stdout is left untouched for direct-run 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;
+declare function reportReplayProgress(progress: ReplayItemFinishProgress | ReplayItemStartProgress | ReplayProgress): void;
 /** Per-trace context passed to {@link ReplayOptions.adaptInputs}. */
 interface AdaptContext {
     /** Bitfab trace ID of the original (historical) trace being replayed. */
@@ -2464,7 +2509,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.36.5";
+declare const __version__ = "0.36.7";
 
 /**
  * Constants for the Bitfab SDK.
@@ -2532,4 +2577,4 @@ declare const finalizers: {
     readableStream: typeof readableStream;
 };
 
-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 CaptureWhen, type CapturedSpan, type CodeChangeFile, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type DbBranchOptions, DbBranchReplayError, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, HttpClient, type MockOverride, type MockOverrideCtx, type MockStrategy, type MockValue, type NodeMatcher, type ProviderDefinition, ReplayBranch, ReplayError, type ReplayItem, type ReplayOptions, type ReplayProgress, type ReplayResult, SUPPORTED_PROVIDERS, type SpanLookup, type SpanMethodDecorator, type SpanMethodDecoratorContext, type SpanNodeMeta, type SpanOccurrence, type SpanOptions, type SpanType, type TokenUsage, type TraceResponse, type TracingProcessor, type VercelCallParams, type VercelGenerateResult, type VercelStreamResult, type WrapBAMLOptions, type WrappedBamlFn, __version__, finalizers, flushTraces, getCurrentReplayBranch, getCurrentSpan, getCurrentTrace, reportReplayProgress, serializeReplayResult };
+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 CaptureWhen, type CapturedSpan, type CodeChangeFile, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type DbBranchOptions, DbBranchReplayError, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, HttpClient, type MockOverride, type MockOverrideCtx, type MockStrategy, type MockValue, type NodeMatcher, type ProviderDefinition, ReplayBranch, ReplayError, type ReplayItem, type ReplayItemFinishProgress, type ReplayItemStartProgress, type ReplayOptions, type ReplayProgress, type ReplayResult, SUPPORTED_PROVIDERS, type SpanLookup, type SpanMethodDecorator, type SpanMethodDecoratorContext, type SpanNodeMeta, type SpanOccurrence, type SpanOptions, type SpanType, type TokenUsage, type TraceResponse, type TracingProcessor, type VercelCallParams, type VercelGenerateResult, type VercelStreamResult, type WrapBAMLOptions, type WrappedBamlFn, __version__, finalizers, flushTraces, getCurrentReplayBranch, getCurrentSpan, getCurrentTrace, reportReplayProgress, serializeReplayResult };

package/dist/index.js

@@ -11,7 +11,7 @@ import {
   getCurrentReplayBranch,
   getCurrentSpan,
   getCurrentTrace
-} from "./chunk-IYHBVIPJ.js";
+} from "./chunk-EDOZ3DP3.js";
 import {
   BITFAB_PROGRESS_PREFIX,
   BitfabError,
@@ -23,7 +23,7 @@ import {
   flushTraces,
   reportReplayProgress,
   serializeReplayResult
-} from "./chunk-FLP6CNRE.js";
+} from "./chunk-CFECTUDU.js";
 export {
   BITFAB_PROGRESS_PREFIX,
   Bitfab,