@bitfab/sdk 0.61.0 → 0.61.2

package/dist/index.d.cts

@@ -603,6 +603,7 @@ declare class HttpClient {
      * Blocking call - creates an experiment and returns lightweight item references.
      */
     startReplay(traceFunctionKey: string, limit: number | undefined, traceIds?: string[], name?: string, codeChangeDescription?: string | null, codeChangeFiles?: CodeChangeFile[] | null, includeDbBranchLease?: boolean, experimentGroupId?: string, datasetIds?: string[], graderIds?: string[], dbBranchSettings?: DbBranchSettings, attempts?: number, includeOriginalMetadata?: boolean, onlyWithAssertions?: boolean, judgeAssertions?: boolean): Promise<StartReplayResponse>;
+    resumeReplay(experimentId: string, traceFunctionKey: string, codeChangeFiles?: CodeChangeFile[] | null, force?: boolean): Promise<ResumeReplayResponse>;
     /**
      * Fetch an external span by ID.
      * Blocking GET request.
@@ -748,6 +749,28 @@ interface StartReplayResponse {
         originalMetadata?: Record<string, unknown>;
     }>;
 }
+type StartReplayItem = StartReplayResponse["items"][number];
+interface ResumeReplayWorkPair {
+    itemIndex: number;
+    attempt: number;
+}
+interface ResumeReplayFinishedItem {
+    originalTraceId: string;
+    attempt: number;
+    traceId: string;
+    hasError: boolean;
+}
+interface ResumeReplayResponse {
+    experimentId: string;
+    experimentUrl: string;
+    attempts: number;
+    items: StartReplayItem[];
+    work: ResumeReplayWorkPair[];
+    finished: ResumeReplayFinishedItem[];
+    skippedOriginalTraceIds: string[];
+    includeDbBranchLease: boolean;
+    dbBranchSettings: DbBranchSettings | null;
+}
 interface ExternalSpanResponse {
     id: string;
     externalTraceId: string;
@@ -2046,6 +2069,8 @@ interface ReplayOptions {
      * callback never crashes the run.
      */
     onExperimentStart?: (experiment: ReplayExperiment) => void;
+    resume?: string;
+    force?: boolean;
 }
 /** The experiment a replay records into, passed to {@link ReplayOptions.onExperimentStart}. */
 interface ReplayExperiment {
@@ -2304,6 +2329,7 @@ interface ReplayItem<T> {
     dbBranchTimings: DbBranchTimings | null;
     traceOutline: TraceOutline | null;
     originalTraceOutline: TraceOutline | null;
+    carriedOver?: boolean;
 }
 
 interface ReplayResult<T> {
@@ -3719,7 +3745,7 @@ interface CommitRef {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.61.0";
+declare const __version__ = "0.61.2";
 
 /**
  * Constants for the Bitfab SDK.

package/dist/index.d.ts

@@ -603,6 +603,7 @@ declare class HttpClient {
      * Blocking call - creates an experiment and returns lightweight item references.
      */
     startReplay(traceFunctionKey: string, limit: number | undefined, traceIds?: string[], name?: string, codeChangeDescription?: string | null, codeChangeFiles?: CodeChangeFile[] | null, includeDbBranchLease?: boolean, experimentGroupId?: string, datasetIds?: string[], graderIds?: string[], dbBranchSettings?: DbBranchSettings, attempts?: number, includeOriginalMetadata?: boolean, onlyWithAssertions?: boolean, judgeAssertions?: boolean): Promise<StartReplayResponse>;
+    resumeReplay(experimentId: string, traceFunctionKey: string, codeChangeFiles?: CodeChangeFile[] | null, force?: boolean): Promise<ResumeReplayResponse>;
     /**
      * Fetch an external span by ID.
      * Blocking GET request.
@@ -748,6 +749,28 @@ interface StartReplayResponse {
         originalMetadata?: Record<string, unknown>;
     }>;
 }
+type StartReplayItem = StartReplayResponse["items"][number];
+interface ResumeReplayWorkPair {
+    itemIndex: number;
+    attempt: number;
+}
+interface ResumeReplayFinishedItem {
+    originalTraceId: string;
+    attempt: number;
+    traceId: string;
+    hasError: boolean;
+}
+interface ResumeReplayResponse {
+    experimentId: string;
+    experimentUrl: string;
+    attempts: number;
+    items: StartReplayItem[];
+    work: ResumeReplayWorkPair[];
+    finished: ResumeReplayFinishedItem[];
+    skippedOriginalTraceIds: string[];
+    includeDbBranchLease: boolean;
+    dbBranchSettings: DbBranchSettings | null;
+}
 interface ExternalSpanResponse {
     id: string;
     externalTraceId: string;
@@ -2046,6 +2069,8 @@ interface ReplayOptions {
      * callback never crashes the run.
      */
     onExperimentStart?: (experiment: ReplayExperiment) => void;
+    resume?: string;
+    force?: boolean;
 }
 /** The experiment a replay records into, passed to {@link ReplayOptions.onExperimentStart}. */
 interface ReplayExperiment {
@@ -2304,6 +2329,7 @@ interface ReplayItem<T> {
     dbBranchTimings: DbBranchTimings | null;
     traceOutline: TraceOutline | null;
     originalTraceOutline: TraceOutline | null;
+    carriedOver?: boolean;
 }
 
 interface ReplayResult<T> {
@@ -3719,7 +3745,7 @@ interface CommitRef {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.61.0";
+declare const __version__ = "0.61.2";
 
 /**
  * Constants for the Bitfab SDK.

package/dist/index.js

@@ -26,8 +26,8 @@ import {
   getCurrentTrace,
   reseedFromRegistry,
   seedFromRegistry
-} from "./chunk-PURSV2TW.js";
-import "./chunk-5DNB7EN7.js";
+} from "./chunk-HNEKBDI7.js";
+import "./chunk-BMJNDIVA.js";
 import {
   BITFAB_PROGRESS_PREFIX,
   DbBranchReplayError,
@@ -35,7 +35,7 @@ import {
   ReplayError,
   reportReplayProgress,
   serializeReplayResult
-} from "./chunk-UFGNWMWI.js";
+} from "./chunk-X5DRPZJJ.js";
 import {
   BitfabError,
   DEFAULT_SERVICE_URL,
@@ -43,7 +43,7 @@ import {
   MixedTracingError,
   __version__,
   flushTraces
-} from "./chunk-YELSIC3R.js";
+} from "./chunk-SJPMWVJ3.js";
 import "./chunk-BAOIRE5T.js";
 export {
   AssertionCategoriesClient,

package/dist/node.cjs

@@ -88,7 +88,7 @@ var __version__, __packageName__;
 var init_version_generated = __esm({
   "src/version.generated.ts"() {
     "use strict";
-    __version__ = "0.61.0";
+    __version__ = "0.61.2";
     __packageName__ = "@bitfab/sdk";
   }
 });
@@ -2958,6 +2958,46 @@ var init_http = __esm({
         }
         return { ...rest, experimentId, experimentUrl };
       }
+      async resumeReplay(experimentId, traceFunctionKey, codeChangeFiles, force) {
+        const payload = {
+          experimentId,
+          traceFunctionKey,
+          lazyDbBranchLease: true
+        };
+        if (force === true) {
+          payload.force = true;
+        }
+        if (codeChangeFiles !== void 0) {
+          payload.codeChangeFiles = codeChangeFiles;
+        }
+        const git = await resolvedGitState();
+        if (git && !isEmptyGitState(git)) {
+          payload.git = git;
+        }
+        const response = await this.request(
+          "/api/sdk/replay/resume",
+          payload,
+          { timeout: REPLAY_DB_BRANCH_REQUEST_TIMEOUT_MS }
+        );
+        const { testRunId, testRunUrl, ...rest } = response;
+        const resumedExperimentId = response.experimentId ?? testRunId;
+        const experimentUrl = response.experimentUrl ?? testRunUrl;
+        if (resumedExperimentId === void 0 || experimentUrl === void 0) {
+          throw new BitfabError(
+            "Replay resume response is missing the experiment ID or URL."
+          );
+        }
+        return {
+          ...rest,
+          experimentId: resumedExperimentId,
+          experimentUrl,
+          work: rest.work ?? [],
+          finished: rest.finished ?? [],
+          skippedOriginalTraceIds: rest.skippedOriginalTraceIds ?? [],
+          includeDbBranchLease: rest.includeDbBranchLease ?? false,
+          dbBranchSettings: rest.dbBranchSettings ?? null
+        };
+      }
       /**
        * Fetch an external span by ID.
        * Blocking GET request.
@@ -3593,6 +3633,88 @@ function expandReplayWork(serverItems, attempts) {
     (_, attempt) => serverItems.map((serverItem) => ({ serverItem, attempt }))
   ).flat();
 }
+function validateResume(resume, options) {
+  if (resume.trim().length === 0) {
+    throw new BitfabError("resume must be the ID of the experiment to resume.");
+  }
+  const conflicting = RESUME_CONFLICTING_OPTIONS.filter(
+    (name) => options[name] !== void 0 && options[name] !== false
+  );
+  if (conflicting.length > 0) {
+    throw new BitfabError(
+      `resume continues experiment ${resume} with the traces, attempts, and graders it started with, so it cannot be combined with ${conflicting.join(", ")}. Drop those options, or start a new replay without resume.`
+    );
+  }
+}
+async function resumeReplaySession(httpClient, experimentId, traceFunctionKey, codeChangeFiles, force, requestedDbBranch) {
+  const response = await httpClient.resumeReplay(
+    experimentId,
+    traceFunctionKey,
+    codeChangeFiles,
+    force
+  );
+  const work = response.work.map(({ itemIndex, attempt }) => {
+    const serverItem = response.items[itemIndex];
+    if (serverItem === void 0) {
+      throw new BitfabError(
+        `Replay resume for experiment ${response.experimentId} named item ${itemIndex}, but the server returned only ${response.items.length} item(s).`
+      );
+    }
+    return { serverItem, attempt };
+  });
+  if (response.skippedOriginalTraceIds.length > 0) {
+    try {
+      console.warn(
+        `Bitfab: ${response.skippedOriginalTraceIds.length} trace(s) selected when experiment ${response.experimentId} started no longer exist, so resume skips them: ${response.skippedOriginalTraceIds.join(", ")}`
+      );
+    } catch {
+    }
+  }
+  if (requestedDbBranch !== void 0 && dbBranchEnabled(requestedDbBranch) !== response.includeDbBranchLease) {
+    try {
+      console.warn(
+        `Bitfab: experiment ${response.experimentId} started with database branching ${response.includeDbBranchLease ? "on" : "off"}, so resume keeps it ${response.includeDbBranchLease ? "on" : "off"} and ignores the dbBranch option passed here.`
+      );
+    } catch {
+    }
+  }
+  return {
+    experimentId: response.experimentId,
+    experimentUrl: response.experimentUrl,
+    attempts: response.attempts,
+    work,
+    finished: response.finished,
+    includeDbBranchLease: response.includeDbBranchLease,
+    dbBranchSettings: response.dbBranchSettings ?? void 0
+  };
+}
+function carriedOverReplayItem(finished) {
+  return {
+    traceId: finished.traceId,
+    originalTraceId: finished.originalTraceId,
+    originalSpanId: "",
+    sourceTraceId: finished.originalTraceId,
+    sourceSpanId: "",
+    attempt: finished.attempt,
+    input: [],
+    result: void 0,
+    originalOutput: void 0,
+    error: finished.hasError ? CARRIED_OVER_ERROR : null,
+    traceError: null,
+    replayError: null,
+    durationMs: null,
+    originalDurationMs: null,
+    originalTokens: null,
+    originalModel: null,
+    tokens: null,
+    model: null,
+    dbSnapshotRef: null,
+    dbBranchTimings: null,
+    traceOutline: null,
+    originalTraceOutline: null,
+    carriedOver: true
+  };
+}
 function resolveAttempts(attempts) {
   if (attempts === void 0) {
     return 1;
@@ -4045,6 +4167,13 @@ async function mapWithConcurrency2(tasks, maxConcurrency, onSettled, onStarted)
   return results;
 }
 async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, registeredOverrides = []) {
+  if (options?.resume !== void 0) {
+    validateResume(options.resume, options);
+  } else if (options?.force === true) {
+    throw new BitfabError(
+      "force only applies when resuming an experiment. Pass it together with resume."
+    );
+  }
   if (options?.traceIds !== void 0) {
     if (options.traceIds.length === 0) {
       throw new BitfabError("traceIds must contain at least one trace ID.");
@@ -4064,7 +4193,7 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
     } catch {
     }
   }
-  const attempts = resolveAttempts(options?.attempts);
+  const requestedAttempts = resolveAttempts(options?.attempts);
   const maxConcurrency = options?.maxConcurrency ?? 10;
   if (!Number.isInteger(maxConcurrency) || maxConcurrency < 1) {
     throw new BitfabError(
@@ -4083,40 +4212,59 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
       }
     }
   }
-  const {
-    experimentId,
-    experimentUrl,
-    items: serverItems
-  } = await httpClient.startReplay(
-    traceFunctionKey,
-    // limit is meaningless with explicit traceIds (the ID list determines
-    // the count), so it's omitted from the request entirely.
-    options?.traceIds ? void 0 : options?.limit ?? 5,
-    options?.traceIds,
-    options?.name,
-    codeChangeDescription,
-    codeChangeFiles,
-    // A dry run executes nothing, so a branch would be provisioned (and billed)
-    // for code that never runs, and a seeded source's refusal would fail the item
-    // before it could report its resolved inputs.
-    dbBranchEnabled(options?.dbBranch) && options?.dryRun !== true,
-    options?.experimentGroupId,
-    datasetIds,
-    options?.graderIds,
-    resolveDbBranchSettings(options?.dbBranch),
-    attempts,
-    options?.adaptInputs !== void 0,
-    options?.onlyWithAssertions,
-    options?.judgeAssertions
-  );
-  if (serverItems.length === 0) {
-    try {
-      console.warn(
-        `Bitfab: no traces matched "${traceFunctionKey}", so this replay ran nothing. Capture a trace, or seed one with seedTrace, before replaying.`
-      );
-    } catch {
+  const includeDbBranchLease = dbBranchEnabled(options?.dbBranch) && options?.dryRun !== true;
+  let session;
+  if (options?.resume === void 0) {
+    const started2 = await httpClient.startReplay(
+      traceFunctionKey,
+      // limit is meaningless with explicit traceIds (the ID list determines
+      // the count), so it's omitted from the request entirely.
+      options?.traceIds ? void 0 : options?.limit ?? 5,
+      options?.traceIds,
+      options?.name,
+      codeChangeDescription,
+      codeChangeFiles,
+      // A dry run executes nothing, so a branch would be provisioned (and billed)
+      // for code that never runs, and a seeded source's refusal would fail the item
+      // before it could report its resolved inputs.
+      includeDbBranchLease,
+      options?.experimentGroupId,
+      datasetIds,
+      options?.graderIds,
+      resolveDbBranchSettings(options?.dbBranch),
+      requestedAttempts,
+      options?.adaptInputs !== void 0,
+      options?.onlyWithAssertions,
+      options?.judgeAssertions
+    );
+    if (started2.items.length === 0) {
+      try {
+        console.warn(
+          `Bitfab: no traces matched "${traceFunctionKey}", so this replay ran nothing. Capture a trace, or seed one with seedTrace, before replaying.`
+        );
+      } catch {
+      }
     }
+    session = {
+      experimentId: started2.experimentId,
+      experimentUrl: started2.experimentUrl,
+      attempts: requestedAttempts,
+      work: expandReplayWork(started2.items, requestedAttempts),
+      finished: [],
+      includeDbBranchLease,
+      dbBranchSettings: resolveDbBranchSettings(options?.dbBranch)
+    };
+  } else {
+    session = await resumeReplaySession(
+      httpClient,
+      options.resume,
+      traceFunctionKey,
+      codeChangeFiles,
+      options.force,
+      options.dbBranch
+    );
   }
+  const { experimentId, experimentUrl, attempts } = session;
   const mockStrategy = options?.mock ?? "marked";
   const fullExperimentUrl = `${serviceUrl}${experimentUrl}`;
   try {
@@ -4130,7 +4278,10 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
     ...normalizeMockOverrides(options?.mockOverride),
     ...registeredOverrides
   ];
-  const workItems = expandReplayWork(serverItems, attempts);
+  const workItems = session.work;
+  const carriedOverItems = session.finished.map(
+    (finished) => carriedOverReplayItem(finished)
+  );
   const replayedTraceIds = workItems.map(() => randomUuid());
   httpClient.trackTraceDeliveries(replayedTraceIds);
   const tasks = workItems.map(
@@ -4143,18 +4294,18 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
       resolvedOverrides,
       replayedTraceIds[index],
       attempt,
-      dbBranchEnabled(options?.dbBranch) && options?.dryRun !== true,
-      resolveDbBranchSettings(options?.dbBranch),
+      session.includeDbBranchLease,
+      session.dbBranchSettings,
       options?.adaptInputs,
       options?.dryRun === true
     )
   );
-  const total = tasks.length;
+  const total = tasks.length + carriedOverItems.length;
   const onItemFinish = options?.onItemFinish ?? options?.onProgress;
-  let completed = 0;
-  let started = 0;
-  let succeeded = 0;
-  let errored = 0;
+  let completed = carriedOverItems.length;
+  let started = carriedOverItems.length;
+  let errored = carriedOverItems.filter((item) => item.error !== null).length;
+  let succeeded = completed - errored;
   let flushInFlight = null;
   let flushPending = false;
   const flushFinishedItemTrace = () => {
@@ -4174,7 +4325,7 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
     }
     return flushInFlight;
   };
-  const resultItems = await mapWithConcurrency2(
+  const ranItems = await mapWithConcurrency2(
     tasks,
     maxConcurrency,
     async (item, index) => {
@@ -4261,6 +4412,7 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
       }
     } : void 0
   );
+  const resultItems = [...carriedOverItems, ...ranItems];
   if (options?.dryRun === true) {
     await httpClient.completeReplay(experimentId).catch(() => void 0);
     const dryResult = {
@@ -4280,11 +4432,11 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
     experimentId,
     fullExperimentUrl
   );
-  for (let index = 0; index < resultItems.length; index += 1) {
+  for (let index = 0; index < ranItems.length; index += 1) {
     const localId = replayedTraceIds[index];
     const readBack = localId ? deliveredTraceIds[localId] : void 0;
     if (readBack !== void 0) {
-      resultItems[index].traceId = readBack;
+      ranItems[index].traceId = readBack;
     }
   }
   const completeResult = await preserveReplayFailure(
@@ -4298,8 +4450,8 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
   if (serverTraceIds !== void 0) {
     const missing = [];
     let completedCount = 0;
-    for (let index = 0; index < resultItems.length; index += 1) {
-      const item = resultItems[index];
+    for (let index = 0; index < ranItems.length; index += 1) {
+      const item = ranItems[index];
       const localId = replayedTraceIds[index];
       const mapped = localId ? serverTraceIds[localId] : void 0;
       item.traceId = item.traceId ?? mapped ?? null;
@@ -4385,7 +4537,7 @@ async function writeReplayResultFile(result) {
     }
   }
 }
-var REPLAY_PERSISTENCE_TIMEOUT_MS, MAX_REPLAY_ATTEMPTS, BITFAB_PROGRESS_PREFIX, ReplayError, DbBranchReplayError;
+var REPLAY_PERSISTENCE_TIMEOUT_MS, MAX_REPLAY_ATTEMPTS, RESUME_CONFLICTING_OPTIONS, CARRIED_OVER_ERROR, BITFAB_PROGRESS_PREFIX, ReplayError, DbBranchReplayError;
 var init_replay = __esm({
   "src/replay.ts"() {
     "use strict";
@@ -4399,6 +4551,17 @@ var init_replay = __esm({
     init_serialize();
     REPLAY_PERSISTENCE_TIMEOUT_MS = 3e4;
     MAX_REPLAY_ATTEMPTS = 100;
+    RESUME_CONFLICTING_OPTIONS = [
+      "traceIds",
+      "limit",
+      "datasetId",
+      "datasetIds",
+      "attempts",
+      "graderIds",
+      "onlyWithAssertions",
+      "dryRun"
+    ];
+    CARRIED_OVER_ERROR = "This item errored in an earlier run of this experiment, before it was resumed.";
     BITFAB_PROGRESS_PREFIX = "@@bitfab:progress ";
     ReplayError = class extends BitfabError {
       constructor(message, items, experimentId, experimentUrl, cause) {
@@ -5231,7 +5394,7 @@ function settleAutoTraceRoot(context) {
   }
   warnOnce(
     "auto-trace-transform-missing",
-    `trace root "${context.traceFunctionKey}" recorded only its own span. No module in this build was compiled by @bitfab/transform, so calls beneath the root were not discovered. Install @bitfab/transform and add its adapter to the server build: ${SUBTREE_TRACING_DOCS_URL}`
+    `trace root "${context.traceFunctionKey}" recorded only its own span. No module in this build was compiled by @bitfab/sdk/transform, so calls beneath the root were not discovered. Add the SDK's transform adapter to the server build: ${SUBTREE_TRACING_DOCS_URL}`
   );
 }
 function runWithAutoTraceRootContext(context, spanStack, fn) {