@bitfab/sdk 0.59.0 → 0.60.0

package/dist/node.cjs

@@ -88,7 +88,7 @@ var __version__, __packageName__;
 var init_version_generated = __esm({
   "src/version.generated.ts"() {
     "use strict";
-    __version__ = "0.59.0";
+    __version__ = "0.60.0";
     __packageName__ = "@bitfab/sdk";
   }
 });
@@ -2111,6 +2111,7 @@ __export(http_exports, {
   HttpClient: () => HttpClient,
   awaitOnExit: () => awaitOnExit,
   awaitPendingRequests: () => awaitPendingRequests,
+  experimentIdWireFields: () => experimentIdWireFields,
   flushTraces: () => flushTraces,
   parseRetryAfterMs: () => parseRetryAfterMs,
   serializePayloadBody: () => serializePayloadBody
@@ -2279,6 +2280,9 @@ function warnDroppedExternalTrace(error) {
     `a trace was dropped because the send step failed: ${describeError(error)}`
   );
 }
+function experimentIdWireFields(experimentId) {
+  return { experimentId, testRunId: experimentId };
+}
 var REPLAY_DB_BRANCH_REQUEST_TIMEOUT_MS, REPLAY_COMPLETE_REQUEST_TIMEOUT_MS, OTLP_TRACES_ENDPOINT, RETRYABLE_STATUSES, EXIT_FLUSH_TIMEOUT_MS, DEFAULT_LIFECYCLE_TIMEOUT_MS2, pendingTracePromises, liveHttpClients, carrierSeq, HttpClient;
 var init_http = __esm({
   "src/http.ts"() {
@@ -2883,7 +2887,7 @@ var init_http = __esm({
       }
       /**
        * Start a replay session by fetching historical traces.
-       * Blocking call - creates a test run and returns lightweight item references.
+       * Blocking call - creates an experiment and returns lightweight item references.
        */
       async startReplay(traceFunctionKey, limit, traceIds, name, codeChangeDescription, codeChangeFiles, includeDbBranchLease, experimentGroupId, datasetIds, graderIds, dbBranchSettings, attempts, includeOriginalMetadata, onlyWithAssertions, judgeAssertions) {
         const payload = { traceFunctionKey };
@@ -2939,9 +2943,20 @@ var init_http = __esm({
           payload.git = git;
         }
         const timeout = includeDbBranchLease ? REPLAY_DB_BRANCH_REQUEST_TIMEOUT_MS : 3e4;
-        return this.request("/api/sdk/replay/start", payload, {
-          timeout
-        });
+        const response = await this.request(
+          "/api/sdk/replay/start",
+          payload,
+          { timeout }
+        );
+        const { testRunId, testRunUrl, ...rest } = response;
+        const experimentId = response.experimentId ?? testRunId;
+        const experimentUrl = response.experimentUrl ?? testRunUrl;
+        if (experimentId === void 0 || experimentUrl === void 0) {
+          throw new BitfabError(
+            "Replay start response is missing the experiment ID or URL."
+          );
+        }
+        return { ...rest, experimentId, experimentUrl };
       }
       /**
        * Fetch an external span by ID.
@@ -3038,21 +3053,21 @@ var init_http = __esm({
        * has a final status AND at least that many persisted spans, which is what
        * makes this a real barrier rather than a "the row exists" check.
        */
-      async getReplayStatus(testRunId, expectedSpanCounts) {
+      async getReplayStatus(experimentId, expectedSpanCounts) {
         return this.request(
           "/api/sdk/replay/status",
-          { testRunId, expectedSpanCounts },
+          { ...experimentIdWireFields(experimentId), expectedSpanCounts },
           { timeout: 3e4 }
         );
       }
       /**
-       * Mark a replay test run as completed.
+       * Mark a replay experiment as completed.
        * Blocking call.
        */
-      async completeReplay(testRunId) {
+      async completeReplay(experimentId) {
         return this.request(
           "/api/sdk/replay/complete",
-          { testRunId },
+          experimentIdWireFields(experimentId),
           { timeout: REPLAY_COMPLETE_REQUEST_TIMEOUT_MS }
         );
       }
@@ -3074,11 +3089,11 @@ var init_http = __esm({
        * snapshot + preview branch and polls operations to readiness, which
        * can take seconds.
        */
-      async resolveDbBranchLease(testRunId, traceId, dbBranchSettings, attempt) {
+      async resolveDbBranchLease(experimentId, traceId, dbBranchSettings, attempt) {
         return this.request(
           "/api/sdk/replay/resolveDbBranchLease",
           {
-            testRunId,
+            ...experimentIdWireFields(experimentId),
             traceId,
             dbBranchSettings,
             ...attempt !== void 0 && attempt > 0 ? { attempt } : {}
@@ -3667,7 +3682,7 @@ function replayJsonReplacer(_key, value) {
 function serializeReplayResult(result) {
   return JSON.stringify(result, replayJsonReplacer, 2);
 }
-async function preserveReplayFailure(operation, items, testRunId, testRunUrl) {
+async function preserveReplayFailure(operation, items, experimentId, experimentUrl) {
   try {
     return await operation();
   } catch (cause) {
@@ -3677,8 +3692,8 @@ async function preserveReplayFailure(operation, items, testRunId, testRunUrl) {
     throw new ReplayError(
       errorMessage(cause),
       items,
-      testRunId,
-      testRunUrl,
+      experimentId,
+      experimentUrl,
       cause
     );
   }
@@ -3732,7 +3747,7 @@ function buildMockTree(rootNode) {
   }
   return { spans };
 }
-async function processItem(httpClient, serverItem, fn, testRunId, mockStrategy, resolvedOverrides, replayedTraceId, attempt, includeDbBranchLease, dbBranchSettings, adaptInputs, dryRun) {
+async function processItem(httpClient, serverItem, fn, experimentId, mockStrategy, resolvedOverrides, replayedTraceId, attempt, includeDbBranchLease, dbBranchSettings, adaptInputs, dryRun) {
   let lease = includeDbBranchLease ? serverItem.dbBranchLease : void 0;
   let leaseError = includeDbBranchLease ? serverItem.dbBranchLeaseError : void 0;
   let dbSnapshotRef = serverItem.dbSnapshotRef;
@@ -3752,7 +3767,7 @@ async function processItem(httpClient, serverItem, fn, testRunId, mockStrategy,
       let resolved2;
       try {
         resolved2 = await httpClient.resolveDbBranchLease(
-          testRunId,
+          experimentId,
           originalTraceId,
           dbBranchSettings,
           attempt
@@ -3864,7 +3879,7 @@ async function processItem(httpClient, serverItem, fn, testRunId, mockStrategy,
       replayStarted = performance.now();
       const maybePromise = runWithReplayContext(
         {
-          testRunId,
+          experimentId,
           traceId: replayedTraceId,
           inputSourceSpanId: span.id,
           inputSourceTraceId: span.externalTraceId,
@@ -3947,14 +3962,14 @@ async function processItem(httpClient, serverItem, fn, testRunId, mockStrategy,
     originalTraceOutline: null
   };
 }
-async function waitForReplayPersistence(httpClient, testRunId, replayedTraceIds) {
+async function waitForReplayPersistence(httpClient, experimentId, replayedTraceIds) {
   const deferredSettled = await httpClient.settleDeferredWork(
     REPLAY_PERSISTENCE_TIMEOUT_MS
   );
   if (!deferredSettled) {
     httpClient.takeTraceDeliveries(replayedTraceIds);
     throw new BitfabError(
-      `Replay could not settle deferred span work before the deadline, so the expected span counts are incomplete (testRunId ${testRunId}).`
+      `Replay could not settle deferred span work before the deadline, so the expected span counts are incomplete (experiment ${experimentId}).`
     );
   }
   if (!httpClient.hasClosedDeliveries(replayedTraceIds)) {
@@ -3983,7 +3998,7 @@ async function waitForReplayPersistence(httpClient, testRunId, replayedTraceIds)
   let missing = Object.keys(expectedSpanCounts).length;
   while (true) {
     const status = await httpClient.getReplayStatus(
-      testRunId,
+      experimentId,
       expectedSpanCounts
     );
     const ready = status.traceIds ?? {};
@@ -4002,7 +4017,7 @@ async function waitForReplayPersistence(httpClient, testRunId, replayedTraceIds)
   }
   const cause = flushed ? "" : " Delivery was also not confirmed before the flush deadline, so the spans likely never reached the server.";
   throw new BitfabError(
-    `Replay traces were not fully persisted before the delivery deadline (testRunId ${testRunId}, missing ${missing} of ${Object.keys(expectedSpanCounts).length} trace(s)).${cause}`
+    `Replay traces were not fully persisted before the delivery deadline (experiment ${experimentId}, missing ${missing} of ${Object.keys(expectedSpanCounts).length} trace(s)).${cause}`
   );
 }
 function sleepForReplayPersistence(ms) {
@@ -4069,8 +4084,8 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
     }
   }
   const {
-    testRunId,
-    testRunUrl,
+    experimentId,
+    experimentUrl,
     items: serverItems
   } = await httpClient.startReplay(
     traceFunctionKey,
@@ -4103,7 +4118,14 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
     }
   }
   const mockStrategy = options?.mock ?? "marked";
-  const fullTestRunUrl = `${serviceUrl}${testRunUrl}`;
+  const fullExperimentUrl = `${serviceUrl}${experimentUrl}`;
+  try {
+    options?.onExperimentStart?.({
+      experimentId,
+      experimentUrl: fullExperimentUrl
+    });
+  } catch {
+  }
   const resolvedOverrides = [
     ...normalizeMockOverrides(options?.mockOverride),
     ...registeredOverrides
@@ -4116,7 +4138,7 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
       httpClient,
       serverItem,
       fn,
-      testRunId,
+      experimentId,
       mockStrategy,
       resolvedOverrides,
       replayedTraceIds[index],
@@ -4171,7 +4193,8 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
       }
       try {
         onItemFinish?.({
-          testRunId,
+          experimentId,
+          testRunId: experimentId,
           completed,
           total,
           succeeded,
@@ -4219,7 +4242,8 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
       try {
         options.onItemStart?.({
           type: "started",
-          testRunId,
+          experimentId,
+          testRunId: experimentId,
           started,
           completed,
           total,
@@ -4238,21 +4262,23 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
     } : void 0
   );
   if (options?.dryRun === true) {
-    await httpClient.completeReplay(testRunId).catch(() => void 0);
+    await httpClient.completeReplay(experimentId).catch(() => void 0);
     const dryResult = {
       items: resultItems,
-      testRunId,
-      testRunUrl: fullTestRunUrl,
+      experimentId,
+      experimentUrl: fullExperimentUrl,
+      testRunId: experimentId,
+      testRunUrl: fullExperimentUrl,
       attempts
     };
     await writeReplayResultFile(dryResult);
     return dryResult;
   }
   const deliveredTraceIds = await preserveReplayFailure(
-    () => waitForReplayPersistence(httpClient, testRunId, replayedTraceIds),
+    () => waitForReplayPersistence(httpClient, experimentId, replayedTraceIds),
     resultItems,
-    testRunId,
-    fullTestRunUrl
+    experimentId,
+    fullExperimentUrl
   );
   for (let index = 0; index < resultItems.length; index += 1) {
     const localId = replayedTraceIds[index];
@@ -4262,10 +4288,10 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
     }
   }
   const completeResult = await preserveReplayFailure(
-    () => httpClient.completeReplay(testRunId),
+    () => httpClient.completeReplay(experimentId),
     resultItems,
-    testRunId,
-    fullTestRunUrl
+    experimentId,
+    fullExperimentUrl
   );
   const serverTraceIds = completeResult.traceIds;
   const replayTokens = completeResult.tokens;
@@ -4292,20 +4318,20 @@ 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.` : "";
       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.`
+        `Replay completed but the server has no persisted trace for any of the ${completedCount} completed item(s) (experiment ${experimentId}).${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,
+        experimentId,
+        fullExperimentUrl,
         cause
       );
     }
     if (missing.length > 0) {
       try {
         console.error(
-          `Bitfab: server has no persisted trace for ${missing.length} of ${completedCount} completed replay item(s) (testRunId ${testRunId}). Their replay token usage is unavailable and they cannot be labeled.`
+          `Bitfab: server has no persisted trace for ${missing.length} of ${completedCount} completed replay item(s) (experiment ${experimentId}). Their replay token usage is unavailable and they cannot be labeled.`
         );
       } catch {
       }
@@ -4313,8 +4339,10 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
   }
   const result = {
     items: resultItems,
-    testRunId,
-    testRunUrl: fullTestRunUrl,
+    experimentId,
+    experimentUrl: fullExperimentUrl,
+    testRunId: experimentId,
+    testRunUrl: fullExperimentUrl,
     attempts
   };
   await writeReplayResultFile(result);
@@ -4322,7 +4350,8 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
     try {
       options?.onProgress?.({
         type: "complete",
-        testRunId,
+        experimentId,
+        testRunId: experimentId,
         completed: total,
         total,
         succeeded,
@@ -4372,13 +4401,15 @@ var init_replay = __esm({
     MAX_REPLAY_ATTEMPTS = 100;
     BITFAB_PROGRESS_PREFIX = "@@bitfab:progress ";
     ReplayError = class extends BitfabError {
-      constructor(message, items, testRunId, testRunUrl, cause) {
-        super(message, testRunUrl);
+      constructor(message, items, experimentId, experimentUrl, cause) {
+        super(message, experimentUrl);
         this.items = items;
-        this.testRunId = testRunId;
-        this.testRunUrl = testRunUrl;
+        this.experimentId = experimentId;
+        this.experimentUrl = experimentUrl;
         this.cause = cause;
         this.name = "ReplayError";
+        this.testRunId = experimentId;
+        this.testRunUrl = experimentUrl;
       }
     };
     DbBranchReplayError = class extends BitfabError {
@@ -6071,6 +6102,7 @@ var GradersClient = class {
 init_http();
 
 // src/labels.ts
+init_http();
 var LABELS_PATH = "/api/sdk/traces/labels";
 var HUMAN_LABELS_PATH = "/api/sdk/traces/labels/human";
 function labelEvidencePath(traceId, assertionId) {
@@ -6080,27 +6112,27 @@ var LabelsClient = class {
   constructor(httpClient) {
     this.httpClient = httpClient;
   }
-  async save(update, testRunId) {
-    const [outcome] = await this.saveAll([update], testRunId);
+  async save(update, experimentId) {
+    const [outcome] = await this.saveAll([update], experimentId);
     return outcome;
   }
-  async saveAll(updates, testRunId) {
+  async saveAll(updates, experimentId) {
     const response = await this.httpClient.request(
       LABELS_PATH,
       {
         labels: updates,
-        ...testRunId === void 0 ? {} : { testRunId }
+        ...experimentId === void 0 ? {} : experimentIdWireFields(experimentId)
       }
     );
     return response.labels;
   }
   /** Withhold a verdict for a trace or replay attempt whose check did not run. */
-  async skip(target, testRunId) {
-    return this.save({ ...target, skip: true }, testRunId);
+  async skip(target, experimentId) {
+    return this.save({ ...target, skip: true }, experimentId);
   }
   /** Clear a previous verdict for a trace, replay attempt, or assertion. */
-  async archive(target, testRunId) {
-    return this.save({ ...target, archive: true }, testRunId);
+  async archive(target, experimentId) {
+    return this.save({ ...target, archive: true }, experimentId);
   }
   async saveHuman(update) {
     const [outcome] = await this.saveHumanAll([update]);
@@ -8458,6 +8490,15 @@ var BitfabVercelAiHandler = class {
 
 // src/client.ts
 init_warnOnce();
+function resolveSpanExperimentId(options) {
+  const { experimentId, testRunId } = options;
+  if (experimentId !== void 0 && testRunId !== void 0 && experimentId !== testRunId) {
+    throw new BitfabError(
+      `experimentId ("${experimentId}") and its deprecated alias testRunId ("${testRunId}") were both passed with different values. Pass only experimentId.`
+    );
+  }
+  return experimentId ?? testRunId;
+}
 var TRUNCATION_LIMIT_ORDER = [
   "max_depth",
   "max_captured_subtree_spans"
@@ -9047,13 +9088,12 @@ var Bitfab = class {
         "bitfab.node({ capture: false }) cannot use mockOnReplay: true because an uncaptured node has no recorded output."
       );
     }
+    const experimentId = resolveSpanExperimentId(options);
     return {
       capture,
       type: options.type ?? "custom",
       ...options.name !== void 0 && { name: options.name },
-      ...options.testRunId !== void 0 && {
-        testRunId: options.testRunId
-      },
+      ...experimentId !== void 0 && { experimentId },
       ...options.mockOnReplay !== void 0 && {
         mockOnReplay: options.mockOnReplay
       },
@@ -9188,6 +9228,7 @@ var Bitfab = class {
               return invokeWithoutNode();
             }
             const mockOnReplay = nodeConfiguration?.mockOnReplay ?? options.mockOnReplayDefault;
+            const nodeExperimentId = nodeConfiguration === void 0 ? void 0 : resolveSpanExperimentId(nodeConfiguration);
             const childOptions = {
               name: spanName,
               type: nodeConfiguration?.type ?? "function",
@@ -9198,8 +9239,8 @@ var Bitfab = class {
               captureContent: true,
               autoTraceDefinition: definition,
               ...declaredNode && { declaredNode },
-              ...nodeConfiguration?.testRunId !== void 0 && {
-                testRunId: nodeConfiguration.testRunId
+              ...nodeExperimentId !== void 0 && {
+                experimentId: nodeExperimentId
               },
               ...mockOnReplay !== void 0 && {
                 mockOnReplay
@@ -9860,6 +9901,7 @@ var Bitfab = class {
     const options = typeof optionsOrFn === "function" ? {} : optionsOrFn;
     const fn = typeof optionsOrFn === "function" ? optionsOrFn : maybeFn;
     const self = this;
+    const optionExperimentId = resolveSpanExperimentId(options);
     const fnIsAsyncFunction = fn.constructor.name === "AsyncFunction";
     const fnReturnsPromise = fnIsAsyncFunction || (() => {
       try {
@@ -9962,7 +10004,7 @@ var Bitfab = class {
         const inputs = args;
         const startedAt = nowIsoTimestamp();
         const replayCtxAtStart = getReplayContext();
-        const testRunId = replayCtxAtStart?.testRunId ?? options.testRunId;
+        const experimentId = replayCtxAtStart?.experimentId ?? optionExperimentId;
         if (isRootSpan && !activeTraceStates.has(traceId)) {
           const dbSnapshotRef = buildSnapshotRef(self.dbSnapshot, startedAt);
           self.simulationPlan.refresh();
@@ -9971,7 +10013,7 @@ var Bitfab = class {
             traceFunctionKey,
             startedAt,
             contexts: [],
-            ...testRunId !== void 0 && { testRunId },
+            ...experimentId !== void 0 && { experimentId },
             ...replayCtxAtStart?.inputSourceTraceId && {
               inputSourceTraceId: replayCtxAtStart.inputSourceTraceId
             },
@@ -10017,7 +10059,7 @@ var Bitfab = class {
                 contexts: newContext.contexts,
                 prompt: newContext.prompt,
                 endedAt,
-                ...testRunId !== void 0 && { testRunId },
+                ...experimentId !== void 0 && { experimentId },
                 ...replayCtx?.inputSourceSpanId && {
                   inputSourceSpanId: replayCtx.inputSourceSpanId
                 }
@@ -10038,7 +10080,7 @@ var Bitfab = class {
                 name: traceState?.name,
                 metadata: callerTraceMetadata(traceId),
                 contexts: traceState?.contexts ?? [],
-                testRunId: traceState?.testRunId,
+                experimentId: traceState?.experimentId,
                 inputSourceTraceId: traceState?.inputSourceTraceId,
                 replayAttempt: traceState?.replayAttempt,
                 dbSnapshotRef: traceState?.dbSnapshotRef,
@@ -10352,9 +10394,6 @@ var Bitfab = class {
     return {
       traceId,
       addContext: (context) => {
-        if (!this.shouldRecord()) {
-          return Promise.resolve();
-        }
         if (typeof context !== "object" || context === null) {
           return Promise.resolve();
         }
@@ -10363,27 +10402,18 @@ var Bitfab = class {
         });
       },
       setMetadata: (metadata) => {
-        if (!this.shouldRecord()) {
-          return Promise.resolve();
-        }
         if (typeof metadata !== "object" || metadata === null) {
           return Promise.resolve();
         }
         return this.httpClient.patchTrace(traceId, { mergeMetadata: metadata });
       },
       setSessionId: (sessionId) => {
-        if (!this.shouldRecord()) {
-          return Promise.resolve();
-        }
         if (typeof sessionId !== "string" || sessionId.length === 0) {
           return Promise.resolve();
         }
         return this.httpClient.patchTrace(traceId, { setSessionId: sessionId });
       },
       setName: (name) => {
-        if (!this.shouldRecord()) {
-          return Promise.resolve();
-        }
         if (typeof name !== "string" || name.length === 0) {
           return Promise.resolve();
         }
@@ -10509,7 +10539,7 @@ var Bitfab = class {
       completed: true,
       ...params.dropped && { dropped: true },
       ...params.sessionId && { sessionId: params.sessionId },
-      ...params.testRunId && { testRunId: params.testRunId }
+      ...params.experimentId !== void 0 && experimentIdWireFields(params.experimentId)
     });
   }
   sendsSpanOnCompletion(context) {
@@ -10621,7 +10651,7 @@ var Bitfab = class {
       },
       ...params.declaredNode === true && { [DECLARED_NODE_FIELD]: true },
       rawSpan: externalSpan,
-      ...params.testRunId && { testRunId: params.testRunId },
+      ...params.experimentId !== void 0 && experimentIdWireFields(params.experimentId),
       ...params.mocked && { mocked: true },
       ...params.mockTarget && { mockTarget: params.mockTarget },
       ...params.mockSource && { mockSource: params.mockSource }