@bitfab/sdk 0.61.3 → 0.61.5

package/dist/index.d.cts

@@ -697,7 +697,7 @@ declare class HttpClient {
      * Start a replay session by fetching historical traces.
      * 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, experimentalSelectiveReplay?: SelectiveReplayOptions): Promise<StartReplayResponse>;
+    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, experimentalSelectiveReplay?: SelectiveReplayOptions, notes?: string): Promise<StartReplayResponse>;
     resumeReplay(experimentId: string, traceFunctionKey: string, codeChangeFiles?: CodeChangeFile[] | null, force?: boolean): Promise<ResumeReplayResponse>;
     /**
      * Fetch an external span by ID.
@@ -733,6 +733,8 @@ declare class HttpClient {
      * Blocking call.
      */
     completeReplay(experimentId: string): Promise<CompleteReplayResponse>;
+    interruptReplay(experimentId: string): Promise<boolean>;
+    heartbeatReplay(experimentId: string): Promise<void>;
     getReseedSource(traceId: string): Promise<ReseedSourceResponse>;
     reseedTrace(traceId: string, runTraceId: string): Promise<ReseedTraceResponse>;
     /**
@@ -1951,6 +1953,14 @@ declare class OrganizationMembersClient {
     list(): Promise<OrganizationMember[]>;
 }
 
+type ReplayInterruptSignal = "SIGINT" | "SIGTERM";
+interface ReplayInterrupt {
+    experimentId: string;
+    experimentUrl: string;
+    signal: ReplayInterruptSignal;
+    markedInterrupted: boolean;
+}
+
 /**
  * Replay historical traces through a function and create an experiment.
  *
@@ -2018,8 +2028,17 @@ interface ReplayOptions {
      * it selects by ID with no dataset attribution.
      */
     traceIds?: string[];
-    /** Optional display name for the resulting experiment. */
+    /**
+     * What this run is testing, in a few words, such as 'baseline' or 'shorter
+     * system prompt'. Bitfab records the commit, branch, tree state, datasets,
+     * and who ran it with every experiment, so do not repeat them here.
+     */
     name?: string;
+    /**
+     * Run conditions Bitfab cannot see on its own, such as an environment
+     * override or a forced feature flag. Kept on the experiment next to its name.
+     */
+    notes?: string;
     /** Positive integer limiting parallel items. Set to 1 for sequential. Default 10. */
     maxConcurrency?: number;
     /**
@@ -2174,6 +2193,7 @@ interface ReplayOptions {
      * callback never crashes the run.
      */
     onExperimentStart?: (experiment: ReplayExperiment) => void;
+    onInterrupt?: (interrupt: ReplayInterrupt) => void;
     resume?: string;
     force?: boolean;
 }
@@ -3862,7 +3882,7 @@ interface CommitRef {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.61.3";
+declare const __version__ = "0.61.5";
 
 /**
  * Constants for the Bitfab SDK.
@@ -4001,4 +4021,4 @@ declare function seedFromRegistry(registry: ReplayRegistry, pipeline: string, ca
     run?: boolean;
 }): Promise<SeedResult>;
 
-export { type ActiveSpanContext, type AdaptContext, type AdaptInputsFn, type AddDatasetGradersResult, type AddDatasetTracesResult, type AllowedEnvVars, type ApprovalFields, type ApprovalState, type Approver, type ArchiveAssertionsParams, AssertionCategoriesClient, type AssertionCategory, type AssertionCategorySummary, type AssertionEvidenceParameter, type AssertionGeneration, AssertionGenerationError, type AssertionGenerationStatus, AssertionGenerationTimeoutError, type AssertionLabelEvidence, type AssertionVerdict, type Assignee, BITFAB_PROGRESS_PREFIX, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler as BitfabLangChainCallbackHandler, BitfabLangGraphCallbackHandler, BitfabLangGraphIntegration, type BitfabLanguageModelMiddleware, BitfabOpenAIAgentHandler, BitfabOpenAITracingProcessor, BitfabRivetIntegration, BitfabVercelAiHandler, type CaptureSurface, type CaptureWhen, type CapturedSpan, type CodeChangeFile, type CommitRef, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type Dataset, type DatasetGraderRef, type DatasetTraceIds, DatasetsClient, type DbBranchOptions, DbBranchReplayError, type DbBranchTimings, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, type GenerateAssertionsOptions, type GetGraderLabelsParams, type GraderLabel, type GraderLabelSource, type GraderRerun, GraderRerunError, type GraderRerunProgress, type GraderRerunResult, type GraderRerunStatus, GraderRerunTimeoutError, GradersClient, HttpClient, type HumanLabelOutcome, type HumanLabelUpdate, type Justification, type JustificationSpan, type LabelAction, type LabelConfidence, type LabelOutcome, type LabelSource, type LabelStatus, type LabelTarget, type LabelUpdate, LabelsClient, type LangGraphIntegrationOptions, type ListDatasetsParams, MixedTracingError, type MockOverride, type MockOverrideCtx, type MockOverrideInput, type MockOverrideResolver, type MockStrategy, type MockValue, NO_MOCK_OVERRIDE, type NodeMatcher, type NodeMethodDecorator, type NodeOptions, type OrganizationMember, OrganizationMembersClient, type ProviderDefinition, type RemoveDatasetGradersResult, type RemoveDatasetTracesResult, ReplayBranch, ReplayError, type ReplayExperiment, type ReplayItem, type ReplayItemFinishProgress, type ReplayItemStartProgress, type ReplayNodeIdentity, type ReplayOptions, type ReplayOptionsFactory, type ReplayProgress, type ReplayProgressItem, type ReplayRegistration, type ReplayRegistry, type ReplayRegistryContext, type ReplayRegistryOptions, type ReplayResult, type RerunGradersOptions, type RerunGradersResult, type ReseedOptions, type ReseedRegistryResult, type ReseedResult, type RivetContextLike, type RivetEffectType, type RivetIntegrationOptions, SUPPORTED_PROVIDERS, type SaveAssertion, type SaveAssertionCategoryParams, type SaveAssertionsAllParams, type SaveAssertionsParams, type SaveDatasetParams, type SaveDatasetResult, type SeedCase, type SeedCaseOptions, type SeedResult, type SeedRunOptions, type SelectiveReplayDecision, type SelectiveReplayOptions, type SelectiveReplayReport, type SpanLookup, type SpanMethodDecorator, type SpanMethodDecoratorContext, type SpanNodeMeta, type SpanOccurrence, type SpanOptions, type SpanType, type TokenUsage, type TraceAssertion, type TraceAssertionSource, type TraceAssertionsResult, type TraceAssertionsUpdate, type TraceIngestionType, type TraceLabels, type TraceOutline, type TraceOutlineSpan, type TraceOutlineSpanError, type TraceResponse, type TraceSearchFilters, type TraceSearchParams, type TraceSearchResult, type TraceTarget, type TraceTargetOccurrence, TracesClient, type TracingProcessor, type VercelCallParams, type VercelGenerateResult, type VercelStreamResult, type WrapBAMLOptions, type WrappedBamlFn, __version__, defineReplayRegistry, finalizers, flushTraces, getCurrentReplayBranch, getCurrentSpan, getCurrentTrace, reportReplayProgress, reseedFromRegistry, seedFromRegistry, serializeReplayResult };
+export { type ActiveSpanContext, type AdaptContext, type AdaptInputsFn, type AddDatasetGradersResult, type AddDatasetTracesResult, type AllowedEnvVars, type ApprovalFields, type ApprovalState, type Approver, type ArchiveAssertionsParams, AssertionCategoriesClient, type AssertionCategory, type AssertionCategorySummary, type AssertionEvidenceParameter, type AssertionGeneration, AssertionGenerationError, type AssertionGenerationStatus, AssertionGenerationTimeoutError, type AssertionLabelEvidence, type AssertionVerdict, type Assignee, BITFAB_PROGRESS_PREFIX, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler as BitfabLangChainCallbackHandler, BitfabLangGraphCallbackHandler, BitfabLangGraphIntegration, type BitfabLanguageModelMiddleware, BitfabOpenAIAgentHandler, BitfabOpenAITracingProcessor, BitfabRivetIntegration, BitfabVercelAiHandler, type CaptureSurface, type CaptureWhen, type CapturedSpan, type CodeChangeFile, type CommitRef, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type Dataset, type DatasetGraderRef, type DatasetTraceIds, DatasetsClient, type DbBranchOptions, DbBranchReplayError, type DbBranchTimings, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, type GenerateAssertionsOptions, type GetGraderLabelsParams, type GraderLabel, type GraderLabelSource, type GraderRerun, GraderRerunError, type GraderRerunProgress, type GraderRerunResult, type GraderRerunStatus, GraderRerunTimeoutError, GradersClient, HttpClient, type HumanLabelOutcome, type HumanLabelUpdate, type Justification, type JustificationSpan, type LabelAction, type LabelConfidence, type LabelOutcome, type LabelSource, type LabelStatus, type LabelTarget, type LabelUpdate, LabelsClient, type LangGraphIntegrationOptions, type ListDatasetsParams, MixedTracingError, type MockOverride, type MockOverrideCtx, type MockOverrideInput, type MockOverrideResolver, type MockStrategy, type MockValue, NO_MOCK_OVERRIDE, type NodeMatcher, type NodeMethodDecorator, type NodeOptions, type OrganizationMember, OrganizationMembersClient, type ProviderDefinition, type RemoveDatasetGradersResult, type RemoveDatasetTracesResult, ReplayBranch, ReplayError, type ReplayExperiment, type ReplayInterrupt, type ReplayInterruptSignal, type ReplayItem, type ReplayItemFinishProgress, type ReplayItemStartProgress, type ReplayNodeIdentity, type ReplayOptions, type ReplayOptionsFactory, type ReplayProgress, type ReplayProgressItem, type ReplayRegistration, type ReplayRegistry, type ReplayRegistryContext, type ReplayRegistryOptions, type ReplayResult, type RerunGradersOptions, type RerunGradersResult, type ReseedOptions, type ReseedRegistryResult, type ReseedResult, type RivetContextLike, type RivetEffectType, type RivetIntegrationOptions, SUPPORTED_PROVIDERS, type SaveAssertion, type SaveAssertionCategoryParams, type SaveAssertionsAllParams, type SaveAssertionsParams, type SaveDatasetParams, type SaveDatasetResult, type SeedCase, type SeedCaseOptions, type SeedResult, type SeedRunOptions, type SelectiveReplayDecision, type SelectiveReplayOptions, type SelectiveReplayReport, type SpanLookup, type SpanMethodDecorator, type SpanMethodDecoratorContext, type SpanNodeMeta, type SpanOccurrence, type SpanOptions, type SpanType, type TokenUsage, type TraceAssertion, type TraceAssertionSource, type TraceAssertionsResult, type TraceAssertionsUpdate, type TraceIngestionType, type TraceLabels, type TraceOutline, type TraceOutlineSpan, type TraceOutlineSpanError, type TraceResponse, type TraceSearchFilters, type TraceSearchParams, type TraceSearchResult, type TraceTarget, type TraceTargetOccurrence, TracesClient, type TracingProcessor, type VercelCallParams, type VercelGenerateResult, type VercelStreamResult, type WrapBAMLOptions, type WrappedBamlFn, __version__, defineReplayRegistry, finalizers, flushTraces, getCurrentReplayBranch, getCurrentSpan, getCurrentTrace, reportReplayProgress, reseedFromRegistry, seedFromRegistry, serializeReplayResult };

package/dist/index.d.ts

@@ -697,7 +697,7 @@ declare class HttpClient {
      * Start a replay session by fetching historical traces.
      * 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, experimentalSelectiveReplay?: SelectiveReplayOptions): Promise<StartReplayResponse>;
+    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, experimentalSelectiveReplay?: SelectiveReplayOptions, notes?: string): Promise<StartReplayResponse>;
     resumeReplay(experimentId: string, traceFunctionKey: string, codeChangeFiles?: CodeChangeFile[] | null, force?: boolean): Promise<ResumeReplayResponse>;
     /**
      * Fetch an external span by ID.
@@ -733,6 +733,8 @@ declare class HttpClient {
      * Blocking call.
      */
     completeReplay(experimentId: string): Promise<CompleteReplayResponse>;
+    interruptReplay(experimentId: string): Promise<boolean>;
+    heartbeatReplay(experimentId: string): Promise<void>;
     getReseedSource(traceId: string): Promise<ReseedSourceResponse>;
     reseedTrace(traceId: string, runTraceId: string): Promise<ReseedTraceResponse>;
     /**
@@ -1951,6 +1953,14 @@ declare class OrganizationMembersClient {
     list(): Promise<OrganizationMember[]>;
 }
 
+type ReplayInterruptSignal = "SIGINT" | "SIGTERM";
+interface ReplayInterrupt {
+    experimentId: string;
+    experimentUrl: string;
+    signal: ReplayInterruptSignal;
+    markedInterrupted: boolean;
+}
+
 /**
  * Replay historical traces through a function and create an experiment.
  *
@@ -2018,8 +2028,17 @@ interface ReplayOptions {
      * it selects by ID with no dataset attribution.
      */
     traceIds?: string[];
-    /** Optional display name for the resulting experiment. */
+    /**
+     * What this run is testing, in a few words, such as 'baseline' or 'shorter
+     * system prompt'. Bitfab records the commit, branch, tree state, datasets,
+     * and who ran it with every experiment, so do not repeat them here.
+     */
     name?: string;
+    /**
+     * Run conditions Bitfab cannot see on its own, such as an environment
+     * override or a forced feature flag. Kept on the experiment next to its name.
+     */
+    notes?: string;
     /** Positive integer limiting parallel items. Set to 1 for sequential. Default 10. */
     maxConcurrency?: number;
     /**
@@ -2174,6 +2193,7 @@ interface ReplayOptions {
      * callback never crashes the run.
      */
     onExperimentStart?: (experiment: ReplayExperiment) => void;
+    onInterrupt?: (interrupt: ReplayInterrupt) => void;
     resume?: string;
     force?: boolean;
 }
@@ -3862,7 +3882,7 @@ interface CommitRef {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.61.3";
+declare const __version__ = "0.61.5";
 
 /**
  * Constants for the Bitfab SDK.
@@ -4001,4 +4021,4 @@ declare function seedFromRegistry(registry: ReplayRegistry, pipeline: string, ca
     run?: boolean;
 }): Promise<SeedResult>;
 
-export { type ActiveSpanContext, type AdaptContext, type AdaptInputsFn, type AddDatasetGradersResult, type AddDatasetTracesResult, type AllowedEnvVars, type ApprovalFields, type ApprovalState, type Approver, type ArchiveAssertionsParams, AssertionCategoriesClient, type AssertionCategory, type AssertionCategorySummary, type AssertionEvidenceParameter, type AssertionGeneration, AssertionGenerationError, type AssertionGenerationStatus, AssertionGenerationTimeoutError, type AssertionLabelEvidence, type AssertionVerdict, type Assignee, BITFAB_PROGRESS_PREFIX, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler as BitfabLangChainCallbackHandler, BitfabLangGraphCallbackHandler, BitfabLangGraphIntegration, type BitfabLanguageModelMiddleware, BitfabOpenAIAgentHandler, BitfabOpenAITracingProcessor, BitfabRivetIntegration, BitfabVercelAiHandler, type CaptureSurface, type CaptureWhen, type CapturedSpan, type CodeChangeFile, type CommitRef, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type Dataset, type DatasetGraderRef, type DatasetTraceIds, DatasetsClient, type DbBranchOptions, DbBranchReplayError, type DbBranchTimings, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, type GenerateAssertionsOptions, type GetGraderLabelsParams, type GraderLabel, type GraderLabelSource, type GraderRerun, GraderRerunError, type GraderRerunProgress, type GraderRerunResult, type GraderRerunStatus, GraderRerunTimeoutError, GradersClient, HttpClient, type HumanLabelOutcome, type HumanLabelUpdate, type Justification, type JustificationSpan, type LabelAction, type LabelConfidence, type LabelOutcome, type LabelSource, type LabelStatus, type LabelTarget, type LabelUpdate, LabelsClient, type LangGraphIntegrationOptions, type ListDatasetsParams, MixedTracingError, type MockOverride, type MockOverrideCtx, type MockOverrideInput, type MockOverrideResolver, type MockStrategy, type MockValue, NO_MOCK_OVERRIDE, type NodeMatcher, type NodeMethodDecorator, type NodeOptions, type OrganizationMember, OrganizationMembersClient, type ProviderDefinition, type RemoveDatasetGradersResult, type RemoveDatasetTracesResult, ReplayBranch, ReplayError, type ReplayExperiment, type ReplayItem, type ReplayItemFinishProgress, type ReplayItemStartProgress, type ReplayNodeIdentity, type ReplayOptions, type ReplayOptionsFactory, type ReplayProgress, type ReplayProgressItem, type ReplayRegistration, type ReplayRegistry, type ReplayRegistryContext, type ReplayRegistryOptions, type ReplayResult, type RerunGradersOptions, type RerunGradersResult, type ReseedOptions, type ReseedRegistryResult, type ReseedResult, type RivetContextLike, type RivetEffectType, type RivetIntegrationOptions, SUPPORTED_PROVIDERS, type SaveAssertion, type SaveAssertionCategoryParams, type SaveAssertionsAllParams, type SaveAssertionsParams, type SaveDatasetParams, type SaveDatasetResult, type SeedCase, type SeedCaseOptions, type SeedResult, type SeedRunOptions, type SelectiveReplayDecision, type SelectiveReplayOptions, type SelectiveReplayReport, type SpanLookup, type SpanMethodDecorator, type SpanMethodDecoratorContext, type SpanNodeMeta, type SpanOccurrence, type SpanOptions, type SpanType, type TokenUsage, type TraceAssertion, type TraceAssertionSource, type TraceAssertionsResult, type TraceAssertionsUpdate, type TraceIngestionType, type TraceLabels, type TraceOutline, type TraceOutlineSpan, type TraceOutlineSpanError, type TraceResponse, type TraceSearchFilters, type TraceSearchParams, type TraceSearchResult, type TraceTarget, type TraceTargetOccurrence, TracesClient, type TracingProcessor, type VercelCallParams, type VercelGenerateResult, type VercelStreamResult, type WrapBAMLOptions, type WrappedBamlFn, __version__, defineReplayRegistry, finalizers, flushTraces, getCurrentReplayBranch, getCurrentSpan, getCurrentTrace, reportReplayProgress, reseedFromRegistry, seedFromRegistry, serializeReplayResult };
+export { type ActiveSpanContext, type AdaptContext, type AdaptInputsFn, type AddDatasetGradersResult, type AddDatasetTracesResult, type AllowedEnvVars, type ApprovalFields, type ApprovalState, type Approver, type ArchiveAssertionsParams, AssertionCategoriesClient, type AssertionCategory, type AssertionCategorySummary, type AssertionEvidenceParameter, type AssertionGeneration, AssertionGenerationError, type AssertionGenerationStatus, AssertionGenerationTimeoutError, type AssertionLabelEvidence, type AssertionVerdict, type Assignee, BITFAB_PROGRESS_PREFIX, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler as BitfabLangChainCallbackHandler, BitfabLangGraphCallbackHandler, BitfabLangGraphIntegration, type BitfabLanguageModelMiddleware, BitfabOpenAIAgentHandler, BitfabOpenAITracingProcessor, BitfabRivetIntegration, BitfabVercelAiHandler, type CaptureSurface, type CaptureWhen, type CapturedSpan, type CodeChangeFile, type CommitRef, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type Dataset, type DatasetGraderRef, type DatasetTraceIds, DatasetsClient, type DbBranchOptions, DbBranchReplayError, type DbBranchTimings, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, type GenerateAssertionsOptions, type GetGraderLabelsParams, type GraderLabel, type GraderLabelSource, type GraderRerun, GraderRerunError, type GraderRerunProgress, type GraderRerunResult, type GraderRerunStatus, GraderRerunTimeoutError, GradersClient, HttpClient, type HumanLabelOutcome, type HumanLabelUpdate, type Justification, type JustificationSpan, type LabelAction, type LabelConfidence, type LabelOutcome, type LabelSource, type LabelStatus, type LabelTarget, type LabelUpdate, LabelsClient, type LangGraphIntegrationOptions, type ListDatasetsParams, MixedTracingError, type MockOverride, type MockOverrideCtx, type MockOverrideInput, type MockOverrideResolver, type MockStrategy, type MockValue, NO_MOCK_OVERRIDE, type NodeMatcher, type NodeMethodDecorator, type NodeOptions, type OrganizationMember, OrganizationMembersClient, type ProviderDefinition, type RemoveDatasetGradersResult, type RemoveDatasetTracesResult, ReplayBranch, ReplayError, type ReplayExperiment, type ReplayInterrupt, type ReplayInterruptSignal, type ReplayItem, type ReplayItemFinishProgress, type ReplayItemStartProgress, type ReplayNodeIdentity, type ReplayOptions, type ReplayOptionsFactory, type ReplayProgress, type ReplayProgressItem, type ReplayRegistration, type ReplayRegistry, type ReplayRegistryContext, type ReplayRegistryOptions, type ReplayResult, type RerunGradersOptions, type RerunGradersResult, type ReseedOptions, type ReseedRegistryResult, type ReseedResult, type RivetContextLike, type RivetEffectType, type RivetIntegrationOptions, SUPPORTED_PROVIDERS, type SaveAssertion, type SaveAssertionCategoryParams, type SaveAssertionsAllParams, type SaveAssertionsParams, type SaveDatasetParams, type SaveDatasetResult, type SeedCase, type SeedCaseOptions, type SeedResult, type SeedRunOptions, type SelectiveReplayDecision, type SelectiveReplayOptions, type SelectiveReplayReport, type SpanLookup, type SpanMethodDecorator, type SpanMethodDecoratorContext, type SpanNodeMeta, type SpanOccurrence, type SpanOptions, type SpanType, type TokenUsage, type TraceAssertion, type TraceAssertionSource, type TraceAssertionsResult, type TraceAssertionsUpdate, type TraceIngestionType, type TraceLabels, type TraceOutline, type TraceOutlineSpan, type TraceOutlineSpanError, type TraceResponse, type TraceSearchFilters, type TraceSearchParams, type TraceSearchResult, type TraceTarget, type TraceTargetOccurrence, TracesClient, type TracingProcessor, type VercelCallParams, type VercelGenerateResult, type VercelStreamResult, type WrapBAMLOptions, type WrappedBamlFn, __version__, defineReplayRegistry, finalizers, flushTraces, getCurrentReplayBranch, getCurrentSpan, getCurrentTrace, reportReplayProgress, reseedFromRegistry, seedFromRegistry, serializeReplayResult };

package/dist/index.js

@@ -26,7 +26,7 @@ import {
   getCurrentTrace,
   reseedFromRegistry,
   seedFromRegistry
-} from "./chunk-TZSTKVZF.js";
+} from "./chunk-NISRFSN2.js";
 import "./chunk-K4XCWQBC.js";
 import {
   BITFAB_PROGRESS_PREFIX,
@@ -35,7 +35,7 @@ import {
   ReplayError,
   reportReplayProgress,
   serializeReplayResult
-} from "./chunk-34UFYAE6.js";
+} from "./chunk-44KG6B5D.js";
 import {
   BitfabError,
   DEFAULT_SERVICE_URL,
@@ -43,7 +43,7 @@ import {
   MixedTracingError,
   __version__,
   flushTraces
-} from "./chunk-65QKCHI2.js";
+} from "./chunk-ZPVWVXWC.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.3";
+    __version__ = "0.61.5";
     __packageName__ = "@bitfab/sdk";
   }
 });
@@ -2284,7 +2284,7 @@ function warnDroppedExternalTrace(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 REPLAY_DB_BRANCH_REQUEST_TIMEOUT_MS, REPLAY_COMPLETE_REQUEST_TIMEOUT_MS, REPLAY_INTERRUPT_REQUEST_TIMEOUT_MS, REPLAY_HEARTBEAT_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"() {
     "use strict";
@@ -2303,6 +2303,8 @@ var init_http = __esm({
     init_warnOnce();
     REPLAY_DB_BRANCH_REQUEST_TIMEOUT_MS = 3e5;
     REPLAY_COMPLETE_REQUEST_TIMEOUT_MS = 12e4;
+    REPLAY_INTERRUPT_REQUEST_TIMEOUT_MS = 5e3;
+    REPLAY_HEARTBEAT_REQUEST_TIMEOUT_MS = 5e3;
     OTLP_TRACES_ENDPOINT = "/api/sdk/otel/v1/traces";
     RETRYABLE_STATUSES = /* @__PURE__ */ new Set([429, 500, 502, 503, 504]);
     EXIT_FLUSH_TIMEOUT_MS = 5e3;
@@ -2890,7 +2892,7 @@ var init_http = __esm({
        * Start a replay session by fetching historical traces.
        * 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, experimentalSelectiveReplay) {
+      async startReplay(traceFunctionKey, limit, traceIds, name, codeChangeDescription, codeChangeFiles, includeDbBranchLease, experimentGroupId, datasetIds, graderIds, dbBranchSettings, attempts, includeOriginalMetadata, onlyWithAssertions, judgeAssertions, experimentalSelectiveReplay, notes) {
         const payload = { traceFunctionKey };
         if (experimentalSelectiveReplay !== void 0) {
           payload.experimentalSelectiveReplay = experimentalSelectiveReplay;
@@ -2904,6 +2906,9 @@ var init_http = __esm({
         if (name !== void 0) {
           payload.name = name;
         }
+        if (notes !== void 0) {
+          payload.notes = notes;
+        }
         if (codeChangeDescription !== void 0) {
           payload.codeChangeDescription = codeChangeDescription;
         }
@@ -3115,6 +3120,28 @@ var init_http = __esm({
           { timeout: REPLAY_COMPLETE_REQUEST_TIMEOUT_MS }
         );
       }
+      async interruptReplay(experimentId) {
+        try {
+          await this.request(
+            "/api/sdk/replay/interrupt",
+            experimentIdWireFields(experimentId),
+            { timeout: REPLAY_INTERRUPT_REQUEST_TIMEOUT_MS }
+          );
+          return true;
+        } catch {
+          return false;
+        }
+      }
+      async heartbeatReplay(experimentId) {
+        try {
+          await this.request(
+            "/api/sdk/replay/heartbeat",
+            experimentIdWireFields(experimentId),
+            { timeout: REPLAY_HEARTBEAT_REQUEST_TIMEOUT_MS }
+          );
+        } catch {
+        }
+      }
       async getReseedSource(traceId) {
         return this.get(
           `/api/sdk/traces/${encodeURIComponent(traceId)}/reseedSource`
@@ -3618,6 +3645,114 @@ var init_integrationFixture = __esm({
   }
 });
 
+// src/replayHeartbeat.ts
+function startReplayHeartbeat(send) {
+  let stopped = false;
+  let inFlight;
+  const timer = setInterval(() => {
+    if (stopped || inFlight !== void 0) {
+      return;
+    }
+    inFlight = send().catch(() => void 0).finally(() => {
+      inFlight = void 0;
+    });
+  }, REPLAY_HEARTBEAT_INTERVAL_MS);
+  unrefTimer(timer);
+  return {
+    stop: async () => {
+      stopped = true;
+      clearInterval(timer);
+      await inFlight;
+    }
+  };
+}
+var REPLAY_HEARTBEAT_INTERVAL_MS;
+var init_replayHeartbeat = __esm({
+  "src/replayHeartbeat.ts"() {
+    "use strict";
+    init_unrefTimer();
+    REPLAY_HEARTBEAT_INTERVAL_MS = 6e4;
+  }
+});
+
+// src/replayInterrupt.ts
+function signalCapableProcess() {
+  if (typeof process === "undefined" || typeof process.on !== "function") {
+    return void 0;
+  }
+  return process;
+}
+function describeReplayInterrupt(experimentId, markedInterrupted) {
+  if (markedInterrupted) {
+    return `[replay] Experiment ${experimentId} interrupted.`;
+  }
+  return `[replay] Experiment ${experimentId} stopped, but Bitfab could not mark it interrupted. It will be marked interrupted within 15 minutes. A resume in the next two minutes may be refused as still running.`;
+}
+function reportInterrupted(experimentId, markedInterrupted) {
+  try {
+    console.error(describeReplayInterrupt(experimentId, markedInterrupted));
+  } catch {
+  }
+}
+function installReplayInterruptHandlers(target) {
+  const host = signalCapableProcess();
+  if (host === void 0) {
+    return { remove: () => {
+    }, interrupted: () => false };
+  }
+  const handlers = /* @__PURE__ */ new Map();
+  const removeHandlers = () => {
+    for (const [signal, handler] of handlers) {
+      host.removeListener(signal, handler);
+    }
+    handlers.clear();
+  };
+  let interrupting = false;
+  const handleSignal = async (signal) => {
+    const hostHandlesSignal = host.listenerCount(signal) > 1;
+    const markedInterrupted = await target.interrupt();
+    removeHandlers();
+    if (target.onInterrupt !== void 0) {
+      try {
+        target.onInterrupt({
+          experimentId: target.experimentId,
+          experimentUrl: target.experimentUrl,
+          signal,
+          markedInterrupted
+        });
+      } catch {
+      }
+      return;
+    }
+    reportInterrupted(target.experimentId, markedInterrupted);
+    if (!hostHandlesSignal) {
+      host.kill(host.pid, signal);
+    }
+  };
+  for (const signal of REPLAY_INTERRUPT_SIGNALS) {
+    const handler = () => {
+      if (interrupting) {
+        return;
+      }
+      interrupting = true;
+      void handleSignal(signal);
+    };
+    handlers.set(signal, handler);
+    host.on(signal, handler);
+  }
+  return { remove: removeHandlers, interrupted: () => interrupting };
+}
+var REPLAY_INTERRUPT_SIGNALS;
+var init_replayInterrupt = __esm({
+  "src/replayInterrupt.ts"() {
+    "use strict";
+    REPLAY_INTERRUPT_SIGNALS = [
+      "SIGINT",
+      "SIGTERM"
+    ];
+  }
+});
+
 // src/selectiveReplay.ts
 function replayNodeKey(node) {
   return JSON.stringify([node.traceFunctionKey, node.spanName]);
@@ -4527,7 +4662,7 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
   const includeDbBranchLease = dbBranchEnabled(options?.dbBranch) && options?.dryRun !== true;
   let session;
   if (options?.resume === void 0) {
-    const started2 = await httpClient.startReplay(
+    const started = await httpClient.startReplay(
       traceFunctionKey,
       // limit is meaningless with explicit traceIds (the ID list determines
       // the count), so it's omitted from the request entirely.
@@ -4548,9 +4683,10 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
       options?.adaptInputs !== void 0,
       options?.onlyWithAssertions,
       options?.judgeAssertions,
-      options?.experimentalSelectiveReplay
+      options?.experimentalSelectiveReplay,
+      options?.notes
     );
-    if (started2.items.length === 0) {
+    if (started.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.`
@@ -4559,10 +4695,10 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
       }
     }
     session = {
-      experimentId: started2.experimentId,
-      experimentUrl: started2.experimentUrl,
+      experimentId: started.experimentId,
+      experimentUrl: started.experimentUrl,
       attempts: requestedAttempts,
-      work: expandReplayWork(started2.items, requestedAttempts),
+      work: expandReplayWork(started.items, requestedAttempts),
       finished: [],
       includeDbBranchLease,
       dbBranchSettings: resolveDbBranchSettings(options?.dbBranch)
@@ -4577,9 +4713,68 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
       options.dbBranch
     );
   }
-  const { experimentId, experimentUrl, attempts } = session;
+  const { experimentId } = session;
+  const fullExperimentUrl = `${serviceUrl}${session.experimentUrl}`;
+  const heartbeat = startReplayHeartbeat(
+    () => httpClient.heartbeatReplay(experimentId)
+  );
+  const interruptReplay = async () => {
+    await heartbeat.stop();
+    return httpClient.interruptReplay(experimentId);
+  };
+  const interruptHandlers = installReplayInterruptHandlers({
+    experimentId,
+    experimentUrl: fullExperimentUrl,
+    interrupt: interruptReplay,
+    onInterrupt: options?.onInterrupt
+  });
+  let completeReturned = false;
+  const markCompleteReturned = () => {
+    completeReturned = true;
+    void heartbeat.stop();
+  };
+  try {
+    return await runReplaySession(
+      httpClient,
+      fn,
+      session,
+      fullExperimentUrl,
+      maxConcurrency,
+      interruptHandlers.remove,
+      markCompleteReturned,
+      interruptHandlers.interrupted,
+      options,
+      registeredOverrides
+    );
+  } catch (error) {
+    if (!completeReturned && !interruptHandlers.interrupted()) {
+      await interruptReplay();
+    }
+    throw error;
+  } finally {
+    interruptHandlers.remove();
+    await heartbeat.stop();
+  }
+}
+function throwIfInterrupted(interrupted, items, experimentId, experimentUrl) {
+  if (!interrupted()) {
+    return;
+  }
+  const cause = new BitfabError(
+    `Experiment ${experimentId} was interrupted, so it was not completed or graded. Resume it by passing { resume: "${experimentId}" } to replay, or with bitfab-replay --resume ${experimentId}.`,
+    experimentUrl
+  );
+  throw new ReplayError(
+    cause.message,
+    items,
+    experimentId,
+    experimentUrl,
+    cause
+  );
+}
+async function runReplaySession(httpClient, fn, session, fullExperimentUrl, maxConcurrency, stopInterruptingOnSignal, markCompleteReturned, interrupted, options, registeredOverrides) {
+  const { experimentId, attempts } = session;
   const mockStrategy = options?.mock ?? "marked";
-  const fullExperimentUrl = `${serviceUrl}${experimentUrl}`;
   try {
     options?.onExperimentStart?.({
       experimentId,
@@ -4729,7 +4924,15 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
   );
   const resultItems = [...carriedOverItems, ...ranItems];
   if (options?.dryRun === true) {
+    throwIfInterrupted(
+      interrupted,
+      resultItems,
+      experimentId,
+      fullExperimentUrl
+    );
+    stopInterruptingOnSignal();
     await httpClient.completeReplay(experimentId).catch(() => void 0);
+    markCompleteReturned();
     const dryResult = {
       items: resultItems,
       experimentId,
@@ -4754,12 +4957,15 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
       ranItems[index].traceId = readBack;
     }
   }
+  throwIfInterrupted(interrupted, resultItems, experimentId, fullExperimentUrl);
+  stopInterruptingOnSignal();
   const completeResult = await preserveReplayFailure(
     () => httpClient.completeReplay(experimentId),
     resultItems,
     experimentId,
     fullExperimentUrl
   );
+  markCompleteReturned();
   const serverTraceIds = completeResult.traceIds;
   const replayTokens = completeResult.tokens;
   if (serverTraceIds !== void 0) {
@@ -4863,6 +5069,8 @@ var init_replay = __esm({
     init_mockOverride();
     init_randomUuid();
     init_replayContext();
+    init_replayHeartbeat();
+    init_replayInterrupt();
     init_selectiveReplayRuntime();
     init_serialize();
     REPLAY_PERSISTENCE_TIMEOUT_MS = 3e4;
@@ -11646,6 +11854,7 @@ init_replay();
 // src/replayRegistry.ts
 init_errors();
 init_replay();
+init_replayInterrupt();
 function defineReplayRegistry(registry) {
   return registry;
 }