bitfab 0.36.1 → 0.36.3

package/dist/index.d.cts

@@ -457,8 +457,11 @@ declare class HttpClient {
     /**
      * Fetch an external span by ID.
      * Blocking GET request.
+     * The replay view limits rawData to input/output serialization fields.
      */
-    getExternalSpan(spanId: string): Promise<ExternalSpanResponse>;
+    getExternalSpan(spanId: string, options?: {
+        view?: "full" | "replay";
+    }): Promise<ExternalSpanResponse>;
     /**
      * Fetch the span tree for a root span.
      * Blocking GET request.
@@ -466,9 +469,11 @@ declare class HttpClient {
      * Pass `includeOutputs: false` for a payload-free tree (structure +
      * `externalSpanId` only), so recorded outputs are fetched lazily per mocked
      * span instead of all up front. Omit it (default eager) for `mock: "all"`.
+     * Pass `includeRootOutput: false` when the root was already fetched.
      */
     getSpanTree(externalSpanId: string, options?: {
         includeOutputs?: boolean;
+        includeRootOutput?: boolean;
     }): Promise<SpanTreeResponse>;
     /**
      * Read which of a replay run's traces the server has fully persisted.
@@ -1237,9 +1242,9 @@ interface ReplayProgress {
     completed: number;
     /** Total number of items in this replay run. */
     total: number;
-    /** Of the completed items, how many ran the function without throwing. */
+    /** Of the completed items, how many finished without a code or replay error. */
     succeeded: number;
-    /** Of the completed items, how many threw (their `item.error` is set). */
+    /** 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
@@ -1267,7 +1272,12 @@ interface ReplayProgress {
         result?: unknown;
         /** The original output from the historical trace. */
         originalOutput?: unknown;
+        /** Backward-compatible message for either error kind. */
         error: string | null;
+        /** The actual value thrown by the replayed customer function. */
+        traceError: unknown | null;
+        /** The actual value thrown while Bitfab prepared this replay item. */
+        replayError: unknown | null;
         durationMs: number | null;
         tokens?: TokenUsage | null;
         model?: string | null;
@@ -1345,8 +1355,18 @@ interface ReplayItem<T> {
     result: T | undefined;
     /** The original output from the historical trace. */
     originalOutput: unknown;
-    /** Error message if the function threw, or null on success. */
+    /**
+     * Backward-compatible message for either error kind. Prefer `traceError` and
+     * `replayError` when callers need the original exception and its source.
+     */
     error: string | null;
+    /** The actual value thrown by the replayed customer function. */
+    traceError: unknown | null;
+    /**
+     * The actual value thrown by replay setup before the customer function ran,
+     * such as database warmup, input hydration, or mock preparation.
+     */
+    replayError: unknown | null;
     /** Original trace duration in milliseconds, or null if timestamps are missing. */
     durationMs: number | null;
     /**
@@ -1376,6 +1396,37 @@ interface ReplayResult<T> {
     /** Full URL to view the test run in the dashboard. */
     testRunUrl: string;
 }
+/**
+ * Whole-run replay failure that preserves every item collected before the run
+ * failed. The original whole-run exception is available as `cause`.
+ */
+declare class ReplayError<T = unknown> extends BitfabError {
+    readonly items: ReplayItem<T>[];
+    readonly testRunId: string;
+    readonly testRunUrl: string;
+    readonly cause: unknown;
+    constructor(message: string, items: ReplayItem<T>[], testRunId: string, testRunUrl: string, cause: unknown);
+}
+/**
+ * A database branch requested for one replay item could not be resolved.
+ *
+ * The server's resolver code and message are retained as structured fields so
+ * callers can handle failures such as `branch_create_failed` and
+ * `snapshot_from_replaced_origin` without parsing the compatible `item.error`
+ * string.
+ */
+declare class DbBranchReplayError extends BitfabError {
+    readonly code: string;
+    readonly originalTraceId: string;
+    readonly cause?: unknown | undefined;
+    constructor(code: string, message: string, originalTraceId: string, cause?: unknown | undefined);
+}
+/**
+ * Serialize a replay result as JSON while retaining structured trace and replay
+ * errors. Use this for direct-run stdout instead of raw `JSON.stringify`, which
+ * drops the useful fields on JavaScript `Error` objects.
+ */
+declare function serializeReplayResult<T>(result: ReplayResult<T>): string;
 
 /**
  * The database branch a single replay item runs against.
@@ -2348,7 +2399,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.36.1";
+declare const __version__ = "0.36.3";
 
 /**
  * Constants for the Bitfab SDK.
@@ -2416,4 +2467,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, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, HttpClient, type MockOverride, type MockOverrideCtx, type MockStrategy, type MockValue, type NodeMatcher, type ProviderDefinition, ReplayBranch, type ReplayItem, type ReplayOptions, type ReplayProgress, type ReplayResult, SUPPORTED_PROVIDERS, type SpanLookup, 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 };
+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 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

@@ -457,8 +457,11 @@ declare class HttpClient {
     /**
      * Fetch an external span by ID.
      * Blocking GET request.
+     * The replay view limits rawData to input/output serialization fields.
      */
-    getExternalSpan(spanId: string): Promise<ExternalSpanResponse>;
+    getExternalSpan(spanId: string, options?: {
+        view?: "full" | "replay";
+    }): Promise<ExternalSpanResponse>;
     /**
      * Fetch the span tree for a root span.
      * Blocking GET request.
@@ -466,9 +469,11 @@ declare class HttpClient {
      * Pass `includeOutputs: false` for a payload-free tree (structure +
      * `externalSpanId` only), so recorded outputs are fetched lazily per mocked
      * span instead of all up front. Omit it (default eager) for `mock: "all"`.
+     * Pass `includeRootOutput: false` when the root was already fetched.
      */
     getSpanTree(externalSpanId: string, options?: {
         includeOutputs?: boolean;
+        includeRootOutput?: boolean;
     }): Promise<SpanTreeResponse>;
     /**
      * Read which of a replay run's traces the server has fully persisted.
@@ -1237,9 +1242,9 @@ interface ReplayProgress {
     completed: number;
     /** Total number of items in this replay run. */
     total: number;
-    /** Of the completed items, how many ran the function without throwing. */
+    /** Of the completed items, how many finished without a code or replay error. */
     succeeded: number;
-    /** Of the completed items, how many threw (their `item.error` is set). */
+    /** 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
@@ -1267,7 +1272,12 @@ interface ReplayProgress {
         result?: unknown;
         /** The original output from the historical trace. */
         originalOutput?: unknown;
+        /** Backward-compatible message for either error kind. */
         error: string | null;
+        /** The actual value thrown by the replayed customer function. */
+        traceError: unknown | null;
+        /** The actual value thrown while Bitfab prepared this replay item. */
+        replayError: unknown | null;
         durationMs: number | null;
         tokens?: TokenUsage | null;
         model?: string | null;
@@ -1345,8 +1355,18 @@ interface ReplayItem<T> {
     result: T | undefined;
     /** The original output from the historical trace. */
     originalOutput: unknown;
-    /** Error message if the function threw, or null on success. */
+    /**
+     * Backward-compatible message for either error kind. Prefer `traceError` and
+     * `replayError` when callers need the original exception and its source.
+     */
     error: string | null;
+    /** The actual value thrown by the replayed customer function. */
+    traceError: unknown | null;
+    /**
+     * The actual value thrown by replay setup before the customer function ran,
+     * such as database warmup, input hydration, or mock preparation.
+     */
+    replayError: unknown | null;
     /** Original trace duration in milliseconds, or null if timestamps are missing. */
     durationMs: number | null;
     /**
@@ -1376,6 +1396,37 @@ interface ReplayResult<T> {
     /** Full URL to view the test run in the dashboard. */
     testRunUrl: string;
 }
+/**
+ * Whole-run replay failure that preserves every item collected before the run
+ * failed. The original whole-run exception is available as `cause`.
+ */
+declare class ReplayError<T = unknown> extends BitfabError {
+    readonly items: ReplayItem<T>[];
+    readonly testRunId: string;
+    readonly testRunUrl: string;
+    readonly cause: unknown;
+    constructor(message: string, items: ReplayItem<T>[], testRunId: string, testRunUrl: string, cause: unknown);
+}
+/**
+ * A database branch requested for one replay item could not be resolved.
+ *
+ * The server's resolver code and message are retained as structured fields so
+ * callers can handle failures such as `branch_create_failed` and
+ * `snapshot_from_replaced_origin` without parsing the compatible `item.error`
+ * string.
+ */
+declare class DbBranchReplayError extends BitfabError {
+    readonly code: string;
+    readonly originalTraceId: string;
+    readonly cause?: unknown | undefined;
+    constructor(code: string, message: string, originalTraceId: string, cause?: unknown | undefined);
+}
+/**
+ * Serialize a replay result as JSON while retaining structured trace and replay
+ * errors. Use this for direct-run stdout instead of raw `JSON.stringify`, which
+ * drops the useful fields on JavaScript `Error` objects.
+ */
+declare function serializeReplayResult<T>(result: ReplayResult<T>): string;
 
 /**
  * The database branch a single replay item runs against.
@@ -2348,7 +2399,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.36.1";
+declare const __version__ = "0.36.3";
 
 /**
  * Constants for the Bitfab SDK.
@@ -2416,4 +2467,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, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, HttpClient, type MockOverride, type MockOverrideCtx, type MockStrategy, type MockValue, type NodeMatcher, type ProviderDefinition, ReplayBranch, type ReplayItem, type ReplayOptions, type ReplayProgress, type ReplayResult, SUPPORTED_PROVIDERS, type SpanLookup, 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 };
+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 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

@@ -20,16 +20,19 @@ import {
   getCurrentReplayBranch,
   getCurrentSpan,
   getCurrentTrace
-} from "./chunk-HD4DRDRE.js";
+} from "./chunk-4CTDZMG5.js";
 import {
   BITFAB_PROGRESS_PREFIX,
   BitfabError,
   DEFAULT_SERVICE_URL,
+  DbBranchReplayError,
   HttpClient,
+  ReplayError,
   __version__,
   flushTraces,
-  reportReplayProgress
-} from "./chunk-6ZBZBR5K.js";
+  reportReplayProgress,
+  serializeReplayResult
+} from "./chunk-M2GISXGV.js";
 export {
   BITFAB_PROGRESS_PREFIX,
   Bitfab,
@@ -42,7 +45,9 @@ export {
   BitfabOpenAITracingProcessor,
   BitfabVercelAiHandler,
   DEFAULT_SERVICE_URL,
+  DbBranchReplayError,
   HttpClient,
+  ReplayError,
   SUPPORTED_PROVIDERS,
   __version__,
   finalizers,
@@ -50,6 +55,7 @@ export {
   getCurrentReplayBranch,
   getCurrentSpan,
   getCurrentTrace,
-  reportReplayProgress
+  reportReplayProgress,
+  serializeReplayResult
 };
 //# sourceMappingURL=index.js.map

package/dist/node.cjs

@@ -97,7 +97,7 @@ var __version__;
 var init_version_generated = __esm({
   "src/version.generated.ts"() {
     "use strict";
-    __version__ = "0.36.1";
+    __version__ = "0.36.3";
   }
 });
 
@@ -1537,9 +1537,11 @@ var init_http = __esm({
       /**
        * Fetch an external span by ID.
        * Blocking GET request.
+       * The replay view limits rawData to input/output serialization fields.
        */
-      async getExternalSpan(spanId) {
-        const url = `${this.serviceUrl}/api/sdk/externalSpans/${spanId}`;
+      async getExternalSpan(spanId, options) {
+        const query = options?.view === "replay" ? "?view=replay" : "";
+        const url = `${this.serviceUrl}/api/sdk/externalSpans/${spanId}${query}`;
         const controller = new AbortController();
         const timeoutId = setTimeout(() => controller.abort(), 3e4);
         try {
@@ -1577,9 +1579,18 @@ var init_http = __esm({
        * Pass `includeOutputs: false` for a payload-free tree (structure +
        * `externalSpanId` only), so recorded outputs are fetched lazily per mocked
        * span instead of all up front. Omit it (default eager) for `mock: "all"`.
+       * Pass `includeRootOutput: false` when the root was already fetched.
        */
       async getSpanTree(externalSpanId, options) {
-        const query = options?.includeOutputs === false ? "?includeOutputs=false" : "";
+        const searchParams = new URLSearchParams();
+        if (options?.includeOutputs === false) {
+          searchParams.set("includeOutputs", "false");
+        }
+        if (options?.includeRootOutput === false) {
+          searchParams.set("includeRootOutput", "false");
+        }
+        const encodedQuery = searchParams.toString();
+        const query = encodedQuery ? `?${encodedQuery}` : "";
         const url = `${this.serviceUrl}/api/sdk/replay/spanTree/${externalSpanId}${query}`;
         const controller = new AbortController();
         const timeoutId = setTimeout(() => controller.abort(), 3e4);
@@ -2058,8 +2069,11 @@ var init_codeChange = __esm({
 var replay_exports = {};
 __export(replay_exports, {
   BITFAB_PROGRESS_PREFIX: () => BITFAB_PROGRESS_PREFIX,
+  DbBranchReplayError: () => DbBranchReplayError,
+  ReplayError: () => ReplayError,
   replay: () => replay,
-  reportReplayProgress: () => reportReplayProgress
+  reportReplayProgress: () => reportReplayProgress,
+  serializeReplayResult: () => serializeReplayResult
 });
 function dbBranchEnabled(dbBranch) {
   return dbBranch !== void 0 && dbBranch !== false;
@@ -2082,11 +2096,59 @@ function reportReplayProgress(progress) {
     return;
   }
   try {
-    stderr.write(`${BITFAB_PROGRESS_PREFIX}${JSON.stringify(progress)}
-`);
+    stderr.write(
+      `${BITFAB_PROGRESS_PREFIX}${JSON.stringify(progress, replayJsonReplacer)}
+`
+    );
   } catch {
   }
 }
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function replayItemErrorMessage(error) {
+  if (error instanceof DbBranchReplayError) {
+    return `Replay requested a database branch for trace ${error.originalTraceId} but it could not be resolved (${error.code}): ${error.message}. The function was not run, because replaying it against the live database would produce a result that looks valid but did not use the historical data you asked for.`;
+  }
+  return errorMessage(error);
+}
+function replayJsonReplacer(_key, value) {
+  if (value instanceof Error) {
+    const serialized = {
+      name: value.name,
+      message: value.message,
+      stack: value.stack
+    };
+    if (value instanceof DbBranchReplayError) {
+      serialized.code = value.code;
+      serialized.originalTraceId = value.originalTraceId;
+      if (value.cause !== void 0) {
+        serialized.cause = value.cause;
+      }
+    }
+    return serialized;
+  }
+  return value;
+}
+function serializeReplayResult(result) {
+  return JSON.stringify(result, replayJsonReplacer, 2);
+}
+async function preserveReplayFailure(operation, items, testRunId, testRunUrl) {
+  try {
+    return await operation();
+  } catch (cause) {
+    if (cause instanceof ReplayError) {
+      throw cause;
+    }
+    throw new ReplayError(
+      errorMessage(cause),
+      items,
+      testRunId,
+      testRunUrl,
+      cause
+    );
+  }
+}
 function deserializeInputs(spanData) {
   const inputMeta = spanData.input_meta;
   const rawInput = spanData.input;
@@ -2144,25 +2206,41 @@ async function processItem(httpClient, serverItem, fn, testRunId, mockStrategy,
   let originalOutput;
   let result;
   let error = null;
+  let traceError = null;
+  let replayError = null;
   const originalTraceId = serverItem.originalTraceId ?? serverItem.sourceTraceId;
   const originalSpanId = serverItem.originalSpanId ?? serverItem.sourceSpanId;
   try {
     if (includeDbBranchLease && !lease && !leaseError) {
-      const resolved = await httpClient.resolveDbBranchLease(
-        testRunId,
-        originalTraceId,
-        dbBranchSettings
-      );
+      let resolved;
+      try {
+        resolved = await httpClient.resolveDbBranchLease(
+          testRunId,
+          originalTraceId,
+          dbBranchSettings
+        );
+      } catch (cause) {
+        throw new DbBranchReplayError(
+          "lease_request_failed",
+          `Bitfab could not request the database branch: ${errorMessage(cause)}`,
+          originalTraceId,
+          cause
+        );
+      }
       lease = resolved.lease ?? void 0;
       leaseError = resolved.leaseError ?? void 0;
       dbSnapshotRef = resolved.dbSnapshotRef ?? dbSnapshotRef;
     }
     if (leaseError) {
-      throw new BitfabError(
-        `Replay requested a database branch for trace ${originalTraceId} but it could not be resolved (${leaseError.code}): ${leaseError.message}. The function was not run, because replaying it against the live database would produce a result that looks valid but did not use the historical data you asked for.`
+      throw new DbBranchReplayError(
+        leaseError.code,
+        leaseError.message,
+        originalTraceId
       );
     }
-    const span = await httpClient.getExternalSpan(originalSpanId);
+    const span = await httpClient.getExternalSpan(originalSpanId, {
+      view: "replay"
+    });
     const spanData = span.rawData?.span_data ?? {};
     inputs = deserializeInputs(spanData);
     originalOutput = deserializeOutput(spanData);
@@ -2182,7 +2260,8 @@ async function processItem(httpClient, serverItem, fn, testRunId, mockStrategy,
     if (needTree) {
       try {
         const treeResponse = await httpClient.getSpanTree(originalSpanId, {
-          includeOutputs
+          includeOutputs,
+          includeRootOutput: false
         });
         if (treeResponse.root) {
           mockTree = buildMockTree(treeResponse.root);
@@ -2204,7 +2283,7 @@ async function processItem(httpClient, serverItem, fn, testRunId, mockStrategy,
     const fetchSpanOutput = mockTree && !includeOutputs ? (externalSpanId) => {
       let pending = outputCache.get(externalSpanId);
       if (!pending) {
-        pending = httpClient.getExternalSpan(externalSpanId).then(
+        pending = httpClient.getExternalSpan(externalSpanId, { view: "replay" }).then(
           (s) => deserializeOutput(
             s.rawData?.span_data ?? {}
           )
@@ -2213,25 +2292,31 @@ async function processItem(httpClient, serverItem, fn, testRunId, mockStrategy,
       }
       return pending;
     } : void 0;
-    const maybePromise = runWithReplayContext(
-      {
-        testRunId,
-        traceId: replayedTraceId,
-        inputSourceSpanId: span.id,
-        inputSourceTraceId: span.externalTraceId,
-        sourceBitfabTraceId: originalTraceId,
-        mockTree,
-        callCounters: mockTree ? /* @__PURE__ */ new Map() : void 0,
-        mockStrategy,
-        mockOverrides: hasOverrides ? resolvedOverrides : void 0,
-        fetchSpanOutput,
-        dbBranchLease: lease
-      },
-      () => fn(...inputs)
-    );
-    result = maybePromise instanceof Promise ? await maybePromise : maybePromise;
+    try {
+      const maybePromise = runWithReplayContext(
+        {
+          testRunId,
+          traceId: replayedTraceId,
+          inputSourceSpanId: span.id,
+          inputSourceTraceId: span.externalTraceId,
+          sourceBitfabTraceId: originalTraceId,
+          mockTree,
+          callCounters: mockTree ? /* @__PURE__ */ new Map() : void 0,
+          mockStrategy,
+          mockOverrides: hasOverrides ? resolvedOverrides : void 0,
+          fetchSpanOutput,
+          dbBranchLease: lease
+        },
+        () => fn(...inputs)
+      );
+      result = maybePromise instanceof Promise ? await maybePromise : maybePromise;
+    } catch (e) {
+      traceError = e;
+      error = errorMessage(e);
+    }
   } catch (e) {
-    error = e instanceof Error ? e.message : String(e);
+    replayError = e;
+    error = replayItemErrorMessage(e);
   } finally {
     if (lease) {
       try {
@@ -2260,6 +2345,8 @@ async function processItem(httpClient, serverItem, fn, testRunId, mockStrategy,
     result,
     originalOutput,
     error,
+    traceError,
+    replayError,
     durationMs: serverItem.durationMs ?? null,
     // Filled in by replay() from the complete-replay response once the
     // replay traces are persisted and their spans aggregated server-side.
@@ -2384,6 +2471,7 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
   );
   const mockStrategy = options?.mock ?? "marked";
   const maxConcurrency = options?.maxConcurrency ?? 10;
+  const fullTestRunUrl = `${serviceUrl}${testRunUrl}`;
   const resolvedOverrides = [
     ...normalizeMockOverrides(options?.mockOverride),
     ...registeredOverrides
@@ -2440,6 +2528,8 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
             result: item.result,
             originalOutput: item.originalOutput,
             error: item.error,
+            traceError: item.traceError,
+            replayError: item.replayError,
             durationMs: item.durationMs,
             tokens: item.tokens,
             model: item.model,
@@ -2450,8 +2540,18 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
       }
     } : void 0
   );
-  await waitForReplayPersistence(httpClient, testRunId, replayedTraceIds);
-  const completeResult = await httpClient.completeReplay(testRunId);
+  await preserveReplayFailure(
+    () => waitForReplayPersistence(httpClient, testRunId, replayedTraceIds),
+    resultItems,
+    testRunId,
+    fullTestRunUrl
+  );
+  const completeResult = await preserveReplayFailure(
+    () => httpClient.completeReplay(testRunId),
+    resultItems,
+    testRunId,
+    fullTestRunUrl
+  );
   const serverTraceIds = completeResult.traceIds;
   const replayTokens = completeResult.tokens;
   if (serverTraceIds !== void 0) {
@@ -2474,9 +2574,16 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
     }
     if (completedCount > 0 && missing.length === completedCount) {
       const serverCount = completeResult.traceCount !== void 0 ? ` The server persisted ${completeResult.traceCount} trace(s) for this run.` : "";
-      throw new BitfabError(
+      const cause = new BitfabError(
         `Replay completed but the server has no persisted trace for any of the ${completedCount} completed item(s) (testRunId ${testRunId}).${serverCount} Trace uploads were awaited, so either the uploads failed (check for "Bitfab: Failed to create" errors above) or the replayed function is not wrapped with withSpan.`
       );
+      throw new ReplayError(
+        cause.message,
+        resultItems,
+        testRunId,
+        fullTestRunUrl,
+        cause
+      );
     }
     if (missing.length > 0) {
       try {
@@ -2490,7 +2597,7 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
   const result = {
     items: resultItems,
     testRunId,
-    testRunUrl: `${serviceUrl}${testRunUrl}`
+    testRunUrl: fullTestRunUrl
   };
   await writeReplayResultFile(result);
   try {
@@ -2518,7 +2625,7 @@ async function writeReplayResultFile(result) {
       import("fs/promises")
     ]);
     await mkdir(dirname(resultPath), { recursive: true });
-    await writeFile(resultPath, `${JSON.stringify(result, null, 2)}
+    await writeFile(resultPath, `${serializeReplayResult(result)}
 `);
   } catch (err) {
     try {
@@ -2529,7 +2636,7 @@ async function writeReplayResultFile(result) {
     }
   }
 }
-var REPLAY_PERSISTENCE_TIMEOUT_MS, BITFAB_PROGRESS_PREFIX;
+var REPLAY_PERSISTENCE_TIMEOUT_MS, BITFAB_PROGRESS_PREFIX, ReplayError, DbBranchReplayError;
 var init_replay = __esm({
   "src/replay.ts"() {
     "use strict";
@@ -2544,6 +2651,25 @@ var init_replay = __esm({
     init_unrefTimer();
     REPLAY_PERSISTENCE_TIMEOUT_MS = 3e4;
     BITFAB_PROGRESS_PREFIX = "@@bitfab:progress ";
+    ReplayError = class extends BitfabError {
+      constructor(message, items, testRunId, testRunUrl, cause) {
+        super(message, testRunUrl);
+        this.items = items;
+        this.testRunId = testRunId;
+        this.testRunUrl = testRunUrl;
+        this.cause = cause;
+        this.name = "ReplayError";
+      }
+    };
+    DbBranchReplayError = class extends BitfabError {
+      constructor(code, message, originalTraceId, cause) {
+        super(message);
+        this.code = code;
+        this.originalTraceId = originalTraceId;
+        this.cause = cause;
+        this.name = "DbBranchReplayError";
+      }
+    };
   }
 });
 
@@ -2561,7 +2687,9 @@ __export(node_exports, {
   BitfabOpenAITracingProcessor: () => BitfabOpenAITracingProcessor,
   BitfabVercelAiHandler: () => BitfabVercelAiHandler,
   DEFAULT_SERVICE_URL: () => DEFAULT_SERVICE_URL,
+  DbBranchReplayError: () => DbBranchReplayError,
   HttpClient: () => HttpClient,
+  ReplayError: () => ReplayError,
   SUPPORTED_PROVIDERS: () => SUPPORTED_PROVIDERS,
   __version__: () => __version__,
   finalizers: () => finalizers,
@@ -2569,7 +2697,8 @@ __export(node_exports, {
   getCurrentReplayBranch: () => getCurrentReplayBranch,
   getCurrentSpan: () => getCurrentSpan,
   getCurrentTrace: () => getCurrentTrace,
-  reportReplayProgress: () => reportReplayProgress
+  reportReplayProgress: () => reportReplayProgress,
+  serializeReplayResult: () => serializeReplayResult
 });
 module.exports = __toCommonJS(node_exports);
 
@@ -6161,7 +6290,9 @@ assertAsyncStorageRegistered();
   BitfabOpenAITracingProcessor,
   BitfabVercelAiHandler,
   DEFAULT_SERVICE_URL,
+  DbBranchReplayError,
   HttpClient,
+  ReplayError,
   SUPPORTED_PROVIDERS,
   __version__,
   finalizers,
@@ -6169,6 +6300,7 @@ assertAsyncStorageRegistered();
   getCurrentReplayBranch,
   getCurrentSpan,
   getCurrentTrace,
-  reportReplayProgress
+  reportReplayProgress,
+  serializeReplayResult
 });
 //# sourceMappingURL=node.cjs.map