@bitfab/sdk 0.36.1 → 0.36.3

package/dist/index.cjs

@@ -42,7 +42,7 @@ var __version__;
 var init_version_generated = __esm({
   "src/version.generated.ts"() {
     "use strict";
-    __version__ = "0.36.1";
+    __version__ = "0.36.3";
   }
 });
 
@@ -1521,9 +1521,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 {
@@ -1561,9 +1563,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);
@@ -2042,8 +2053,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;
@@ -2066,11 +2080,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;
@@ -2128,25 +2190,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);
@@ -2166,7 +2244,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);
@@ -2188,7 +2267,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 ?? {}
           )
@@ -2197,25 +2276,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 {
@@ -2244,6 +2329,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.
@@ -2368,6 +2455,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
@@ -2424,6 +2512,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,
@@ -2434,8 +2524,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) {
@@ -2458,9 +2558,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 {
@@ -2474,7 +2581,7 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
   const result = {
     items: resultItems,
     testRunId,
-    testRunUrl: `${serviceUrl}${testRunUrl}`
+    testRunUrl: fullTestRunUrl
   };
   await writeReplayResultFile(result);
   try {
@@ -2502,7 +2609,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 {
@@ -2513,7 +2620,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";
@@ -2528,6 +2635,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";
+      }
+    };
   }
 });
 
@@ -2545,7 +2671,9 @@ __export(index_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,
@@ -2553,7 +2681,8 @@ __export(index_exports, {
   getCurrentReplayBranch: () => getCurrentReplayBranch,
   getCurrentSpan: () => getCurrentSpan,
   getCurrentTrace: () => getCurrentTrace,
-  reportReplayProgress: () => reportReplayProgress
+  reportReplayProgress: () => reportReplayProgress,
+  serializeReplayResult: () => serializeReplayResult
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -6134,7 +6263,9 @@ init_replay();
   BitfabOpenAITracingProcessor,
   BitfabVercelAiHandler,
   DEFAULT_SERVICE_URL,
+  DbBranchReplayError,
   HttpClient,
+  ReplayError,
   SUPPORTED_PROVIDERS,
   __version__,
   finalizers,
@@ -6142,6 +6273,7 @@ init_replay();
   getCurrentReplayBranch,
   getCurrentSpan,
   getCurrentTrace,
-  reportReplayProgress
+  reportReplayProgress,
+  serializeReplayResult
 });
 //# sourceMappingURL=index.cjs.map