TypeScript SDK Reference

// Values
export { Bitfab, BitfabError, BitfabFunction, DbBranchReplayError, MixedTracingError, ReplayError, NO_MOCK_OVERRIDE, getCurrentReplayBranch, getCurrentSpan, getCurrentTrace } from "@bitfab/sdk"
export { BitfabClaudeAgentHandler, BitfabLangChainCallbackHandler, BitfabLangGraphCallbackHandler, BitfabLangGraphIntegration, BitfabOpenAIAgentHandler, BitfabOpenAITracingProcessor, BitfabVercelAiHandler } from "@bitfab/sdk"
export { DatasetsClient, HttpClient, LabelsClient, TracesClient, defineReplayRegistry, finalizers, flushTraces, reportReplayProgress, seedFromRegistry, serializeReplayResult } from "@bitfab/sdk"
export { __version__, DEFAULT_SERVICE_URL, BITFAB_PROGRESS_PREFIX, SUPPORTED_PROVIDERS } from "@bitfab/sdk"

// Types
export type {
  ActiveSpanContext,
  AdaptContext,
  AdaptInputsFn,
  AddDatasetGradersResult,
  AddDatasetTracesResult,
  AllowedEnvVars,
  ArchiveAssertionsParams,
  BamlExecutionResult,
  BitfabConfig,
  BitfabLanguageModelMiddleware,
  CaptureSurface,
  CaptureWhen,
  CapturedSpan,
  CodeChangeFile,
  CurrentSpan,
  CurrentTrace,
  Dataset,
  DatasetGraderRef,
  DatasetTraceIds,
  DbBranchOptions,
  DbBranchTimings,
  DbSnapshotConfig,
  DbSnapshotProvider,
  DbSnapshotRef,
  DetachedTrace,
  GraderRerun,
  GraderRerunProgress,
  GraderRerunResult,
  GraderRerunStatus,
  LabelAction,
  LabelConfidence,
  LabelOutcome,
  LabelUpdate,
  LangGraphIntegrationOptions,
  ListDatasetsParams,
  MockOverride,
  MockOverrideCtx,
  MockOverrideInput,
  MockOverrideResolver,
  MockStrategy,
  MockValue,
  NodeMatcher,
  NodeMethodDecorator,
  NodeOptions,
  ProviderDefinition,
  RemoveDatasetGradersResult,
  RemoveDatasetTracesResult,
  ReplayBranch,
  ReplayItem,
  ReplayItemFinishProgress,
  ReplayItemStartProgress,
  ReplayOptions,
  ReplayOptionsFactory,
  ReplayProgress,
  ReplayProgressItem,
  ReplayRegistration,
  ReplayRegistry,
  ReplayRegistryContext,
  ReplayRegistryOptions,
  ReplayResult,
  RerunGradersOptions,
  RerunGradersResult,
  SaveAssertion,
  SaveAssertionsAllParams,
  SaveAssertionsParams,
  SaveDatasetParams,
  SaveDatasetResult,
  SeedCase,
  SeedCaseOptions,
  SeedResult,
  SeedRunOptions,
  SpanLookup,
  SpanMethodDecorator,
  SpanMethodDecoratorContext,
  SpanNodeMeta,
  SpanOccurrence,
  SpanOptions,
  SpanType,
  TokenUsage,
  TraceIngestionType,
  TraceAssertion,
  TraceAssertionsResult,
  TraceAssertionSource,
  TraceAssertionsUpdate,
  TraceOutline,
  TraceOutlineSpan,
  TraceOutlineSpanError,
  TraceResponse,
  TraceTarget,
  TraceTargetOccurrence,
  TracingProcessor,
  VercelCallParams,
  VercelGenerateResult,
  VercelStreamResult,
  WrapBAMLOptions,
  WrappedBamlFn,
} from "@bitfab/sdk"

client.captureEnabled: boolean

withSpan<TArgs extends unknown[], TReturn>(
  traceFunctionKey: string,
  optionsOrFn: SpanOptions | ((...args: TArgs) => TReturn),
  maybeFn?: (...args: TArgs) => TReturn,
): (...args: TArgs) => TReturn

trace(traceFunctionKey: string, options?: TraceOptions): TraceMethodDecorator

withTrace<TArgs extends unknown[], TReturn>(
  traceFunctionKey: string,
  fn: (...args: TArgs) => TReturn,
): (...args: TArgs) => TReturn

withTrace<TArgs extends unknown[], TReturn>(
  traceFunctionKey: string,
  options: TraceOptions,
  fn: (...args: TArgs) => TReturn,
): (...args: TArgs) => TReturn

interface TraceOptions {
  name?: string
  type?: SpanType
  mockOnReplayDefault?: boolean
  maxDepth?: number
  maxSpans?: number
  exclude?: readonly string[] | ReadonlySet<string>
  includeWrappers?: boolean
}

span(
  traceFunctionKey: string,
  options?: SpanOptions,
): SpanMethodDecorator

node(options?: NodeOptions): NodeMethodDecorator

withNode<This, TArgs extends unknown[], TReturn>(
  optionsOrFn: NodeOptions | ((this: This, ...args: TArgs) => TReturn),
  maybeFn?: (this: This, ...args: TArgs) => TReturn,
): (this: This, ...args: TArgs) => TReturn

getFunction(traceFunctionKey: string): BitfabFunction

// Form 1: uses bamlClient from constructor
wrapBAML<TArgs, TReturn>(
  method: (...args: TArgs) => Promise<TReturn>,
  options?: WrapBAMLOptions,
): WrappedBamlFn<TArgs, TReturn>

// Form 2: explicit client
wrapBAML<TArgs, TReturn>(
  bamlClient: unknown,
  method: (...args: TArgs) => Promise<TReturn>,
  options?: WrapBAMLOptions,
): WrappedBamlFn<TArgs, TReturn>

getTrace(traceId: string): DetachedTrace

getTraceSpan(traceId: string, lookup: SpanLookup): Promise<CapturedSpan | null>

client.datasets.save(params: SaveDatasetParams): Promise<SaveDatasetResult>
client.datasets.list(params?: ListDatasetsParams): Promise<Dataset[]>
client.datasets.get(datasetId: string): Promise<Dataset>
client.datasets.listTraces(datasetId: string): Promise<DatasetTraceIds>
client.datasets.addTraces(datasetId: string, traceIds: string[]): Promise<AddDatasetTracesResult>
client.datasets.removeTraces(datasetId: string, traceIds: string[]): Promise<RemoveDatasetTracesResult>
client.datasets.addGraders(datasetId: string, graderIds: string[]): Promise<AddDatasetGradersResult>
client.datasets.removeGraders(datasetId: string, graderIds: string[]): Promise<RemoveDatasetGradersResult>
client.datasets.rerunGraders(datasetId: string, options?: RerunGradersOptions): Promise<RerunGradersResult>
client.datasets.getGraderRerun(datasetId: string, runId?: string): Promise<GraderRerun | null>

interface Dataset {
  id: string
  traceFunctionKey: string
  name: string
  description: string | null
  traceCount: number
  graders: { id: string; name: string | null }[]
  createdAt: string
  updatedAt: string
}

interface SaveDatasetParams {
  traceFunctionKey: string
  name: string
  description?: string
}

interface SaveDatasetResult { dataset: Dataset; created: boolean }
interface ListDatasetsParams { traceFunctionKey?: string }
interface DatasetTraceIds { datasetId: string; traceIds: string[] }

interface AddDatasetTracesResult {
  dataset: Dataset
  addedTraceIds: string[]
  alreadyPresentTraceIds: string[]
  skippedTraceIds: string[]
}

interface RemoveDatasetTracesResult {
  dataset: Dataset
  removedTraceIds: string[]
  notPresentTraceIds: string[]
}

interface AddDatasetGradersResult {
  dataset: Dataset
  addedGraderIds: string[]
  alreadyAssignedGraderIds: string[]
  skippedGraderIds: string[]
}

interface RemoveDatasetGradersResult {
  dataset: Dataset
  removedGraderIds: string[]
  notAssignedGraderIds: string[]
}

type GraderRerunStatus = "pending" | "running" | "completed" | "errored"

interface GraderRerun {
  id: string
  status: GraderRerunStatus
  graderIds: string[]
  progress: { completedTraces: number; totalTraces: number; graderCount: number } | null
  result: { tracesGraded: number; gradersRun: number } | null
  error: string | null
  createdAt: string
  updatedAt: string
}

interface RerunGradersOptions {
  graderIds?: string[]
  wait?: boolean
  timeoutMs?: number
  pollIntervalMs?: number
}

interface RerunGradersResult {
  run: GraderRerun
  joinedExisting: boolean
}

client.traces.getAssertions(traceId: string): Promise<TraceAssertionsResult>
client.traces.saveAssertions(params: SaveAssertionsParams): Promise<TraceAssertion[]>
client.traces.saveAssertionsAll(params: SaveAssertionsAllParams): Promise<TraceAssertion[]>
client.traces.archiveAssertions(params: ArchiveAssertionsParams): Promise<string[]>

await client.traces.saveAssertionsAll({
  updates: traceIds.map((traceId) => ({
    traceId,
    assertions: [{ assertion: "Departs before 9am" }],
  })),
})

type TraceTargetOccurrence = "first" | "last" | number
type TraceTarget =
  | { kind: "output" }
  | { kind: "span"; name: string; occurrence?: TraceTargetOccurrence }
type TraceAssertionSource = "human" | "agent"

type SaveAssertion = {
  id?: string
  assertion: string
  passCriteria?: string | null
  failCriteria?: string | null
  targetOnEvaluatedTrace?: TraceTarget | null
}

type SaveAssertionsParams = {
  traceId: string
  assertions: SaveAssertion[]
  source?: TraceAssertionSource
}

type TraceAssertionsUpdate = {
  traceId: string
  assertions: SaveAssertion[]
}

type SaveAssertionsAllParams = {
  updates: TraceAssertionsUpdate[]
  source?: TraceAssertionSource
}

type ArchiveAssertionsParams = {
  traceId: string
  assertionIds: string[]
}

type TraceAssertion = {
  id: string
  traceId: string
  assertion: string
  passCriteria: string | null
  failCriteria: string | null
  targetOnEvaluatedTrace: TraceTarget | null
  source: TraceAssertionSource
  createdAt: string
  updatedAt: string
}

type TraceAssertionsResult = {
  assertions: TraceAssertion[]
  inheritedFrom: string | null
}

client.labels.save(update: LabelUpdate, testRunId?: string): Promise<LabelOutcome>
client.labels.saveAll(updates: LabelUpdate[], testRunId?: string): Promise<LabelOutcome[]>
client.labels.saveHuman(update: HumanLabelUpdate): Promise<HumanLabelOutcome>
client.labels.saveHumanAll(updates: HumanLabelUpdate[]): Promise<HumanLabelOutcome[]>
client.labels.get(traceId: string): Promise<TraceLabels | null>
client.labels.getAll(traceIds: string[]): Promise<TraceLabels[]>

type LabelConfidence = "VeryLow" | "Low" | "Medium" | "High" | "VeryHigh"
type LabelAction = "set" | "archived" | "no-active-label" | "skipped"

type LabelUpdate =
  & ({ traceId: string } | { originalTraceId: string; attempt?: number })
  & { assertionId?: string }
  & (
    | { label: boolean; annotation: string; confidence?: LabelConfidence }
    | { skip: true }
    | { archive: true }
  )

type LabelOutcome = {
  key: string
  traceId: string
  action: LabelAction
}

type HumanLabelUpdate = {
  traceId: string
  assertionId?: string
  label: boolean
  annotation: string
  confidence?: LabelConfidence
}

type HumanLabelOutcome = {
  traceId: string
  assertionId: string | null
  label: boolean
  action: "set"
}

type LabelStatus = "labeled" | "skipped" | "unlabeled"
type LabelSource = "human" | "agent"

type AssertionVerdict = {
  assertionId: string
  assertion: string | null
  labelStatus: LabelStatus
  label: boolean | null
  annotation: string | null
  confidence: LabelConfidence | null
  labelSource: LabelSource
  approved: boolean
}

type TraceLabels = {
  traceId: string
  labelStatus: LabelStatus
  label: boolean | null
  annotation: string | null
  approved: boolean
  passed: number
  failed: number
  assertions: AssertionVerdict[]
}

client.graders.getLabels(params: GetGraderLabelsParams): Promise<GraderLabel[]>

type GetGraderLabelsParams = {
  traceIds?: string[]
  graderId?: string
  limit?: number
}

type GraderLabelSource = "human" | "live_grader"

type GraderLabel = {
  traceId: string
  graderId: string
  graderName: string | null
  graderStatus: string
  label: boolean | null
  labelReason: string | null
  failureDiagnostic: string | null
  labelConfidence: LabelConfidence | null
  source: GraderLabelSource
  evaluatedAt: string | null
}

export default defineReplayRegistry({
  checkout: { client: bitfab, fn: runCheckout },
  agent: {
    client: bitfab,
    fn: runAgent,
    traceFunctionKey: "support-agent",
    options: { mock: "marked", adaptInputs },
    optionsFactory: ({ params }) => ({
      mockOverride: createSupportAgentMock(params.scenario),
    }),
  },
})

seedTrace(
  traceFunctionKey: string,
  options: {
    input: unknown[]
    expected?: unknown
    fn?: (...args: any[]) => unknown
    metadata?: Record<string, unknown>
    sessionId?: string
    name?: string
    spanName?: string
    spanType?: SpanType
  },
): string

seedTrace<TArgs extends unknown[], TReturn>(
  traceFunctionKey: string,
  fn: (...args: TArgs) => TReturn,
  options?: {
    args?: TArgs
    metadata?: Record<string, unknown>
    sessionId?: string
    name?: string
  },
): Promise<string>

const bitfab = new Bitfab({ captureEnabled: false })

const traceId = await bitfab.seedTrace("agent-turn", runTicket, {
  args: ["T-1"],
  metadata: { caseUid: "c-1", suite: "smoke" },
  name: "T-1",
})

reseedTrace(
  traceFunctionKey: string,
  fn: (...args: any[]) => unknown,
  options: { traceId: string },
): Promise<{ traceId: string; previousRunTraceId: string }>

reseedFromRegistry(
  registry: ReplayRegistry,
  pipeline: string,
  traceIds: readonly string[],
): Promise<{
  pipeline: string
  traceFunctionKey: string
  reseeded: { traceId: string; previousRunTraceId: string }[]
}>

async function seedFromRegistry(
  registry: ReplayRegistry,
  pipeline: string,
  cases: readonly SeedCase[],
  options?: { run?: boolean },
): Promise<SeedResult>

registerMockOverride(override: MockOverride): void
registerMockOverride(resolver: MockOverrideResolver): void
registerMockOverride(match: NodeMatcher, value: MockValue): void
registerMockOverride(
  traceFunctionKey: string,
  override: MockOverride | MockOverrideResolver,
): void

clearMockOverrides(): void

async replay<TReturn>(
  traceFunctionKey: string,
  fn: (...args: any[]) => TReturn | Promise<TReturn>,
  options?: ReplayOptions,
): Promise<ReplayResult<TReturn>>

async call<T = unknown>(
  methodName: string,
  inputs?: Record<string, unknown>,
): Promise<T>

getLangGraphCallbackHandler(traceFunctionKey: string): BitfabLangGraphCallbackHandler

getLangGraphIntegration(
  traceFunctionKey: string,
  options?: LangGraphIntegrationOptions,
): BitfabLangGraphIntegration

interface LangGraphIntegrationOptions {
  mockToolsOnReplay?: boolean | readonly string[] // default true; a string[] marks only those tool names
}

integration.createInvoker<TInput, TConfig, TReturn>(
  graph: LangGraphRunnable<TInput, TConfig, TReturn>,
): (input: TInput, config?: TConfig) => TReturn

const integration = bitfab.getLangGraphIntegration("support-agent")
const tools = integration.wrapTools([lookupCustomer, searchDocs])
const graph = buildSupportGraph({ tools })
const runSupportAgent = integration.createInvoker(graph)

const result = await runSupportAgent(
  { messages: [{ role: "user", content: "Help with order 123" }] },
  { configurable: { thread_id: "customer-456" } },
)

await bitfab.replay("support-agent", runSupportAgent, { limit: 10 })

getOpenAiTracingProcessor(): BitfabOpenAITracingProcessor

getOpenAiAgentHandler(traceFunctionKey: string): BitfabOpenAIAgentHandler

getClaudeAgentHandler(traceFunctionKey: string): BitfabClaudeAgentHandler

getVercelAiMiddleware(traceFunctionKey: string): BitfabLanguageModelMiddleware

interface VercelCallParams {
  prompt?: unknown
  [key: string]: unknown
}

interface VercelGenerateResult {
  content?: { type: string; text?: string }[]
  text?: string          // some providers expose a flattened text; preferred when present
  usage?: unknown
  finishReason?: unknown
  [key: string]: unknown
}

interface VercelStreamResult {
  stream: ReadableStream
  [key: string]: unknown
}

withSpan<TArgs, TReturn>(
  optionsOrFn: SpanOptions | ((...args: TArgs) => TReturn),
  maybeFn?: (...args: TArgs) => TReturn,
): (...args: TArgs) => TReturn

span(options?: SpanOptions): SpanMethodDecorator

getVercelAiMiddleware(): BitfabLanguageModelMiddleware

getClaudeAgentHandler(): BitfabClaudeAgentHandler

getLangGraphCallbackHandler(): BitfabLangGraphCallbackHandler

getLangGraphIntegration(
  options?: LangGraphIntegrationOptions,
): BitfabLangGraphIntegration

class BitfabError extends Error {
  constructor(message: string, url?: string, status?: number, retryAfterMs?: number)
  readonly url?: string
  readonly status?: number
  readonly retryAfterMs?: number
}

class MixedTracingError extends Error {
  constructor(message: string)
}

finalizers.aiSdk(result: unknown): Promise<Record<string, unknown>>

finalizers.readableStream(
  stream: ReadableStream,
  onLive: (live: ReadableStream) => void,
): Promise<{ chunks: unknown[] }>

function getCurrentSpan(): CurrentSpan

function getCurrentTrace(): CurrentTrace

async function flushTraces(timeoutMs?: number): Promise<boolean>

close(timeoutMs?: number): Promise<boolean>

interface CommitRef {
  sha: string
  branch: string | null
  dirty: boolean | null
  remote: string | null
  rootSha: string | null
}

interface SpanOptions {
  name?: string               // defaults to the qualified function name (Order.process for a method), then traceFunctionKey
  type?: SpanType             // defaults to "custom"
  captureWhen?: CaptureWhen   // defaults to "always"
  mockOnReplay?: boolean      // selected by replay's default "marked" strategy
  testRunId?: string          // links the span and any trace it starts to a test run
  finalize?: (result: any) => unknown | Promise<unknown>
}

type CaptureWhen = "always" | "nested"

type SpanType = "llm" | "agent" | "function" | "guardrail" | "handoff" | "custom"

interface CurrentSpan {
  readonly id: string
  readonly traceId: string
  addContext(context: Record<string, unknown>): void
  setPrompt(prompt: string): void
}

interface CurrentTrace {
  setSessionId(sessionId: string): void
  setName(name: string): void
  setMetadata(metadata: Record<string, unknown>): void
  addContext(context: Record<string, unknown>): void
  drop(): void
}

interface DetachedTrace {
  readonly traceId: string
  addContext(context: Record<string, unknown>): Promise<void>
  setMetadata(metadata: Record<string, unknown>): Promise<void>
  setSessionId(sessionId: string): Promise<void>
  setName(name: string): Promise<void>
}

interface CapturedSpan {
  id: string
  traceId: string
  parentSpanId: string | null
  name: string | null
  type: string
  input: unknown
  output: unknown
  contexts: Record<string, unknown>[]
  prompt: string | null
  metadata: Record<string, unknown>
  metrics: Record<string, unknown> | null
  errors: unknown
  startedAt: string | null
  endedAt: string | null
}

interface WrapBAMLOptions {
  onCollector?: (collector: unknown) => void
}

interface WrappedBamlFn<TArgs extends unknown[], TReturn> {
  (...args: TArgs): Promise<TReturn>
  collector: unknown | null
}

interface ReplayOptions {
  limit?: number      // ignored (with a warning) when traceIds is passed
  traceIds?: string[] // max 100; the ID count determines how many traces replay
  name?: string       // display name for the resulting experiment/test run
  maxConcurrency?: number  // default 10
  attempts?: number        // default 1; 1-100; replays each trace this many times, attempt-major
  codeChangeDescription?: string | null
  codeChangeFiles?: CodeChangeFile[] | null // omit for Git diff capture; null disables it
  mock?: MockStrategy      // "marked" (default), "none", or "all"
  mockOverride?: MockOverrideInput | MockOverrideInput[]
  adaptInputs?: (inputs: unknown[], ctx: AdaptContext) => unknown[]
  dryRun?: boolean         // resolve inputs without calling the function
  experimentGroupId?: string
  dbBranch?: boolean | DbBranchOptions // true requests a DB branch per replay item
  datasetId?: string       // durably attributes the experiment to a dataset
  datasetIds?: string[]    // several datasets: replays their union, attributed to each
  graderIds?: string[]     // graders attached to this run, unioned with the dataset's at grading (max 100)
  onlyWithAssertions?: boolean // narrow the selection to traces carrying an assertion
  onItemStart?: (progress: ReplayItemStartProgress) => void // each item as processing starts
  onItemFinish?: (progress: ReplayItemFinishProgress) => void // each item as it finishes
  onProgress?: (progress: ReplayProgress) => void // deprecated compatibility callback
}

// dbBranch: true means "on, mirror defaults"; an object tunes the branch.
interface DbBranchOptions {
  minCu?: number     // autoscaling floor for the branch's compute, 0.25-56
  maxCu?: number     // autoscaling ceiling; equal to minCu pins the size.
                     // A range may not span >8 CU or exceed 16 CU; a pinned
                     // size is a fixed compute, allowed up to 56.
  warmupSql?: string // appended to the branch's readiness check, so it runs
                     // before your function sees the branch
}

interface ReplayItemFinishProgress {
  type?: "item"     // omitted on backward-compatible per-item events
  testRunId: string  // replay test run id
  completed: number  // items finished so far (succeeded or errored)
  total: number      // items in the run
  succeeded: number  // of completed, how many the fn ran without throwing
  errored: number    // of completed, how many threw
  item: ReplayProgressItem  // the single trace that just finished
}

interface ReplayProgressItem {
  traceId?: string | null        // null during the run; the server replay id arrives at completion
  originalTraceId: string | null // the original (historical) trace replayed
  originalSpanId?: string | null // the original root span the inputs were read from
  sourceTraceId: string | null   // deprecated alias for originalTraceId
  sourceSpanId?: string | null   // deprecated alias for originalSpanId
  attempt: number                // which attempt this item is, under `attempts`
  input?: unknown[]
  result?: unknown
  originalOutput?: unknown
  error: string | null           // compatible message for either error kind
  traceError?: unknown | null    // actual exception thrown while executing the replayed trace
  replayError?: unknown | null   // actual exception thrown by replay setup
  durationMs?: number | null     // how long this one trace took to replay
  originalDurationMs?: number | null
  originalTokens?: TokenUsage | null
  originalModel?: string | null
  ingestionType?: TraceIngestionType
  tokens?: TokenUsage | null     // null until completion aggregates it
  model?: string | null          // deprecated alias for originalModel
  dbSnapshotRef?: DbSnapshotRef | null
  dbBranchTimings?: DbBranchTimings | null
  traceOutline?: TraceOutline | null          // null until completion builds it
  originalTraceOutline?: TraceOutline | null  // null until completion builds it
}

/** @deprecated Use ReplayItemFinishProgress. */
interface ReplayProgress {
  type?: "item" | "complete"
  result?: ReplayResult<unknown> // terminal complete event only
  testRunId?: string
  completed: number
  total: number
  succeeded: number
  errored: number
  item?: ReplayItemFinishProgress["item"]
}

interface ReplayItemStartProgress {
  type: "started"
  testRunId: string
  started: number
  completed: number
  total: number
  succeeded: number
  errored: number
  item: {
    originalTraceId: string
    originalSpanId: string
    sourceTraceId: string // deprecated alias
    sourceSpanId: string  // deprecated alias
    attempt: number
  }
}

function getCurrentReplayBranch(): ReplayBranch | null

interface ReplayBranch {
  databaseUrl: string          // connection string for this item's branch
  neonBranchId: string         // the provider's own id for this branch
  envKey: string               // env var name your app reads, e.g. "DATABASE_URL"
  expiresAt: string            // ISO-8601
  snapshotTimestamp?: string   // ISO-8601, the instant the branch is pinned to
  providerConsoleUrl?: string
  readOnly?: boolean
  region?: string              // e.g. "aws-us-east-1"
  traceId: string              // the historical trace this item replays
}

interface ReplayResult<T> {
  items: ReplayItem<T>[]
  testRunId: string
  testRunUrl: string
  attempts: number
}

interface ReplayItem<T> {
  input: unknown[]
  result: T | undefined
  originalOutput: unknown
  error: string | null // compatible message for either error kind
  traceError: unknown | null // actual exception thrown while executing the replayed trace
  replayError: unknown | null // actual exception thrown before the function ran
  durationMs: number | null // how long THIS replay took
  originalDurationMs: number | null // the original trace's duration
  originalTokens: TokenUsage | null // the original trace's token usage
  originalModel: string | null // the original trace's model
  ingestionType?: TraceIngestionType // how the source trace came to exist ("captured" | "seeded"); absent on older servers, which only served captured traces
  tokens: TokenUsage | null // the replayed run's token usage (compare vs originalTokens)
  model: string | null // deprecated alias for originalModel
  traceId: string | null // the new replay trace's server id, written in after the run completes (null on older servers)
  originalTraceId: string // the original (historical) trace being replayed
  originalSpanId: string // the original root span the inputs were read from
  sourceTraceId: string // deprecated alias for originalTraceId
  sourceSpanId: string // deprecated alias for originalSpanId
  attempt: number // 1-based attempt number within this experiment
  dbSnapshotRef: DbSnapshotRef | null // the source trace's snapshot pin, if any
  dbBranchTimings: DbBranchTimings | null // per-phase branch provisioning timings
  traceOutline: TraceOutline | null // the replayed trace's span tree, no payloads
  originalTraceOutline: TraceOutline | null // the original trace's span tree, no payloads
}

interface TraceOutline {
  traceId: string             // server trace id of the outlined trace
  name: string | null
  status: string
  traceFunctionKey: string | null
  durationMs: number | null
  spanCount: number
  spans: TraceOutlineSpan[]   // root spans in start order
}

interface TraceOutlineSpan {
  spanId: string
  name: string | null
  type: string                // "llm" | "agent" | "function" | "guardrail" | "handoff" | "custom"
  traceFunctionKey: string | null
  durationMs: number | null
  tokens: TokenUsage | null
  model: string | null
  errors: TraceOutlineSpanError[] | null
  mocked: boolean             // served from the recorded output instead of re-executing
  children: TraceOutlineSpan[]
}

interface TraceOutlineSpanError {
  source: string              // "code" for the traced function, "sdk" for capture problems
  error: string
  step?: string
}

try {
  await bitfab.replay("document-pipeline", processDocument)
} catch (error) {
  if (error instanceof ReplayError) {
    console.error(error.cause)
    for (const item of error.items) {
      console.error(item.originalTraceId, item.traceError ?? item.replayError)
    }
  }
}

function serializeReplayResult<T>(result: ReplayResult<T>): string

interface AllowedEnvVars {
  OPENAI_API_KEY?: string
}

interface ActiveSpanContext {
  traceId: string
  spanId: string
}

interface SpanNodeMeta {
  traceFunctionKey: string
  spanName: string
  type: string
  originalSpanId?: string
}

interface MockOverrideCtx {
  node: SpanNodeMeta
  inputs: unknown[]
  getOriginalOutput: () => Promise<unknown>
}

type NodeMatcher = (node: SpanNodeMeta) => boolean
type MockValueFn = (ctx: MockOverrideCtx) => unknown | Promise<unknown>
type MockValue = MockValueFn | string | number | boolean | bigint | symbol | object | null | undefined
type MockOverrideResolver = (ctx: MockOverrideCtx) => unknown | Promise<unknown>

interface MockOverride {
  match: NodeMatcher
  value: MockValue
}

type MockOverrideInput = MockOverride | MockOverrideResolver

type MockStrategy = "none" | "all" | "marked"
type TraceIngestionType = "captured" | "seeded"
type AdaptInputsFn = (inputs: unknown[], ctx: AdaptContext) => unknown[]

interface CodeChangeFile {
  path: string
  before: string
  after: string
}

interface AdaptContext {
  originalTraceId: string
  originalSpanId: string
  sourceTraceId: string   // deprecated alias for originalTraceId
  sourceSpanId: string    // deprecated alias for originalSpanId
  metadata: Record<string, unknown>
}

type ReplayRegistryOptions = Omit<ReplayOptions, "onItemStart" | "onItemFinish" | "onProgress">

interface ReplayRegistryContext {
  params: Readonly<Record<string, unknown>>
}

type ReplayOptionsFactory = (
  context: ReplayRegistryContext,
) => ReplayRegistryOptions | Promise<ReplayRegistryOptions>

interface SeedCase {
  input: unknown[]
  expected?: unknown
  metadata?: Record<string, unknown>
  sessionId?: string
}

interface SeedResult {
  pipeline: string
  traceFunctionKey: string
  traceIds: string[]
}

interface SeedCaseOptions {
  input: unknown[]
  expected?: unknown
  fn?: (...args: any[]) => unknown
  metadata?: Record<string, unknown>
  sessionId?: string
  name?: string
  spanName?: string
  spanType?: SpanType
}

interface SeedRunOptions<TArgs extends unknown[]> {
  args?: TArgs
  metadata?: Record<string, unknown>
  sessionId?: string
  name?: string
}