@bitfab/sdk 0.65.4 → 0.65.6

package/dist/index-CFOLQ1IF.d.cts

@@ -0,0 +1,4410 @@
+//#region src/approval.d.ts
+/** One span the justification rests on, with what that span shows. */
+type JustificationSpan = {
+  spanId: string;
+  text: string;
+};
+/** Evidence for an assertion decision: one entry per span relied on. */
+type Justification = JustificationSpan[];
+/** Whether a person has reviewed an assertion decision. */
+type ApprovalState = "pending" | "approved" | "rejected";
+type Approver = {
+  id: string;
+  fullName: string | null;
+  email: string | null;
+  imageUrl: string | null;
+};
+/** The organization member on the hook for reviewing an assertion. */
+type Assignee = Approver;
+/** Read-only on this client: only a person in Bitfab sets these. */
+type ApprovalFields = {
+  approvalState: ApprovalState;
+  approvedBy: Approver | null;
+  approvedAt: string | null;
+};
+//#endregion
+//#region src/baml.d.ts
+/**
+ * BAML execution utilities for the Bitfab TypeScript SDK.
+ * This module provides functions to execute BAML prompts dynamically on the client side.
+ */
+/**
+ * Provider definition from the server.
+ */
+interface ProviderDefinition {
+  provider: string;
+  apiKeyEnv: string;
+  models: Array<{
+    model: string;
+    description: string;
+  }>;
+}
+/**
+ * Result of a BAML function execution with raw collector data.
+ */
+interface BamlExecutionResult {
+  /** The parsed result of the function */
+  result: unknown;
+  /** Raw collector data for the server to parse */
+  rawCollector: Record<string, unknown> | null;
+}
+/**
+ * Type for allowed environment variables.
+ * Only OPENAI_API_KEY is currently supported.
+ */
+type AllowedEnvVars = {
+  OPENAI_API_KEY?: string;
+};
+//#endregion
+//#region src/selectiveReplay.d.ts
+/** A node is identified by its workflow key and span name, never its display label. */
+interface ReplayNodeIdentity {
+  traceFunctionKey: string;
+  spanName: string;
+}
+/** Experimental, explicit policy for the TypeScript selective replay prototype. */
+interface SelectiveReplayOptions {
+  /** Subtrees that must execute: changed code and unchanged code with required effects. */
+  mustRun: ReplayNodeIdentity[];
+}
+interface SelectiveReplayNode extends ReplayNodeIdentity {
+  id: string;
+  parentId: string | null;
+  mustRun: boolean;
+  reusable: boolean;
+  reason: "root" | "must-run" | "ancestor" | "assertion" | "unresolved-must-run" | "eligible" | "not-reusable" | "missing-recording";
+  recording?: {
+    input: unknown[];
+    kwargs?: Record<string, unknown>;
+    output: unknown;
+  };
+}
+interface SelectiveReplayAssertion {
+  id: string;
+  target: null | {
+    kind: "output";
+  } | {
+    kind: "span";
+    name: string;
+    occurrence?: "first" | "last" | number;
+  };
+}
+interface SelectiveReplayPlan {
+  version: 4;
+  rootId: string;
+  options: SelectiveReplayOptions;
+  unresolvedMustRun: ReplayNodeIdentity[];
+  nodes: SelectiveReplayNode[];
+  assertions: SelectiveReplayAssertion[];
+}
+interface SelectiveReplayDecision extends ReplayNodeIdentity {
+  originalSpanId: string | null;
+  action: "run" | "mock" | "blocked";
+  reason: string;
+}
+/** Per-item execution evidence. A node not reached is not claimed as tested. */
+interface SelectiveReplayReport {
+  decisions: SelectiveReplayDecision[];
+  mustRunNotReached: ReplayNodeIdentity[];
+  unresolvedMustRun: ReplayNodeIdentity[];
+  /** Assertion IDs loaded for planning; these are not verdicts. */
+  assertionIds: string[];
+  /** Assertion IDs whose span target was absent/out of range in the recording. */
+  unresolvedAssertions: string[];
+  /** Assertion IDs whose requested span occurrence was not reached in this replay. */
+  assertionTargetsNotReached: string[];
+}
+//#endregion
+//#region src/traceCompletion.d.ts
+declare class TraceCompletion {
+  private readonly traces;
+  private readonly closed;
+  private state;
+  start(traceId: string, spanId: string): void;
+  open(traceId: string): void;
+  hold(traceId: string, key: string): void;
+  record(traceId: string, spanId: string): void;
+  end(traceId: string, spanId: string): void;
+  abort(traceId: string, spanId: string): void;
+  close(traceId: string, complete: (count: number) => void, dropped?: boolean): void;
+  private drain;
+}
+//#endregion
+//#region src/dbSnapshot.d.ts
+/**
+ * Per-trace database snapshot ref capture.
+ *
+ * Every root span carries a `DbSnapshotRef` that pins the DB state at trace
+ * open by wall-clock timestamp. Capturing the timestamp is free (no IO) and
+ * harmless, so it happens on every trace regardless of configuration: that
+ * lets any trace be replayed against a historical branch later. A `provider`
+ * is attached only when the customer configured `dbSnapshot`; when absent it
+ * is resolved at replay time. The Bitfab service uses the timestamp to
+ * materialize an ephemeral branch from `customer-main`.
+ */
+declare const SUPPORTED_PROVIDERS: readonly ["neon"];
+type DbSnapshotProvider = (typeof SUPPORTED_PROVIDERS)[number];
+interface DbSnapshotConfig {
+  /** Discriminator for the server-side resolver. */
+  provider: DbSnapshotProvider;
+}
+interface DbSnapshotRef {
+  /**
+   * The wall-clock ISO timestamp the SDK observed immediately before
+   * invoking the wrapped function. The name encodes its provenance:
+   * SDK-observed, wall clock (not monotonic), captured before user code
+   * began executing. Always present.
+   */
+  sdkWallClockBeforeFn: string;
+  /**
+   * The configured provider for server-side branch resolution. Only set when
+   * the customer configured `dbSnapshot`; otherwise the provider is resolved
+   * at replay time.
+   */
+  provider?: DbSnapshotProvider;
+}
+//#endregion
+//#region src/errors.d.ts
+/**
+ * Shared error type for Bitfab SDK runtime errors. Lives in its own
+ * module to avoid import cycles between `http.ts` and modules that need
+ * to throw structured errors (e.g. `dbSnapshot.ts` validation).
+ */
+declare class BitfabError extends Error {
+  readonly url?: string | undefined;
+  /**
+   * HTTP status the request failed with, when it failed with one. The
+   * transport's retry policy needs the code itself (retry 408/425/429/5xx,
+   * never a 4xx the server will reject again), which a formatted message
+   * cannot supply. Absent for network failures and non-HTTP errors.
+   */
+  readonly status?: number | undefined;
+  /**
+   * `Retry-After` in milliseconds, when the server sent one. A 429 or 503
+   * carries the server's own instruction about when to come back; retrying
+   * on our own schedule ignores it and keeps the pressure on.
+   */
+  readonly retryAfterMs?: number | undefined;
+  constructor(message: string, url?: string | undefined,
+  /**
+   * HTTP status the request failed with, when it failed with one. The
+   * transport's retry policy needs the code itself (retry 408/425/429/5xx,
+   * never a 4xx the server will reject again), which a formatted message
+   * cannot supply. Absent for network failures and non-HTTP errors.
+   */
+  status?: number | undefined,
+  /**
+   * `Retry-After` in milliseconds, when the server sent one. A 429 or 503
+   * carries the server's own instruction about when to come back; retrying
+   * on our own schedule ignores it and keeps the pressure on.
+   */
+  retryAfterMs?: number | undefined);
+}
+declare class MixedTracingError extends Error {
+  constructor(message: string);
+}
+//#endregion
+//#region src/mockOverride.d.ts
+/**
+ * Selective mock overrides for replay.
+ *
+ * A mock override injects a custom value into a specific span (node) during
+ * replay: the matched span short-circuits its real execution and returns the
+ * value you supply, so downstream real code runs against the substituted
+ * output. This is a third mock mode alongside "run real code" and "replay
+ * recorded output" (see {@link MockStrategy}).
+ *
+ * The matcher and value are deliberately separate so matching stays cheap
+ * (structural metadata only, no output fetch) and the recorded output is
+ * fetched lazily - and only if the value function actually asks for it via
+ * {@link MockOverrideCtx.getOriginalOutput}.
+ */
+/**
+ * Structural identity of a span during replay, passed to a {@link NodeMatcher}.
+ * Carries no output payload - matching must not depend on the recorded output,
+ * so the output fetch stays lazy and gated.
+ */
+interface SpanNodeMeta {
+  /** The `withSpan` key of the executing span (its code-side identity). */
+  traceFunctionKey: string;
+  /** Resolved span name: `options.name ?? fn.name ?? traceFunctionKey`. */
+  spanName: string;
+  /** Span type, e.g. "llm", "agent", "tool", "custom". */
+  type: string;
+  /**
+   * The id of this span in the original (replayed) trace, when it exists in
+   * that trace's tree. Undefined when the live span has no recorded
+   * counterpart (e.g. a span the changed code newly introduced).
+   */
+  originalSpanId?: string;
+}
+/** Context passed to a {@link MockValue} function for a matched span. */
+interface MockOverrideCtx {
+  /** The matched span's structural metadata. */
+  node: SpanNodeMeta;
+  /** The live replay args passed to the wrapped function this run. */
+  inputs: unknown[];
+  /**
+   * Lazily fetch this span's ORIGINAL recorded output (deserialized). The fetch
+   * happens only when called and is memoized per replay item, so a purely flat
+   * override that never calls it triggers zero output round trips. Rejects if
+   * the span has no recorded counterpart. Being async, it is only usable for
+   * spans wrapping async functions.
+   */
+  getOriginalOutput: () => Promise<unknown>;
+}
+/**
+ * Return this from a mock override resolver to decline the override for the
+ * current span. Resolution continues with the next override, then the replay's
+ * base mock strategy.
+ */
+declare const NO_MOCK_OVERRIDE: unique symbol;
+/** Selects which spans an override applies to. Runs on structural metadata. */
+type NodeMatcher = (node: SpanNodeMeta) => boolean;
+/** The function form of {@link MockValue}, receiving the override context. */
+type MockValueFn = (ctx: MockOverrideCtx) => unknown | Promise<unknown>;
+/**
+ * A client-wide, keyed, or per-replay resolver. A global resolver can route on
+ * `ctx.node.traceFunctionKey`; a keyed resolver is only invoked for spans with
+ * its registered key. Return {@link NO_MOCK_OVERRIDE} for spans the resolver
+ * does not want to override.
+ */
+type MockOverrideResolver = (ctx: MockOverrideCtx) => unknown | Promise<unknown>;
+/**
+ * The value injected for a matched span: either a flat value used as-is, or a
+ * function of the {@link MockOverrideCtx} that returns one (or a Promise of
+ * one). Full replacement - the value IS the span's output, no merge with the
+ * recorded output.
+ *
+ * The flat side is spelled out (rather than `unknown`) so an inline function
+ * still gets a typed `ctx`: `unknown | Fn` would collapse to `unknown` and drop
+ * the contextual type. To inject a value that is itself a function, wrap it:
+ * `value: () => theFunction`.
+ */
+type MockValue = MockValueFn | string | number | boolean | bigint | symbol | object | null | undefined;
+/** One (match, value) pair. */
+interface MockOverride {
+  match: NodeMatcher;
+  value: MockValue;
+}
+/** Accepted shape for one mock override declaration. */
+type MockOverrideInput = MockOverride | MockOverrideResolver;
+//#endregion
+//#region src/selectiveReplayRuntime.d.ts
+declare class SelectiveReplayRuntime {
+  private readonly plan;
+  private readonly options;
+  private readonly nodes;
+  private readonly children;
+  private readonly runtimeParents;
+  private readonly consumed;
+  private readonly required;
+  private readonly requiredScopes;
+  private readonly recordings;
+  private readonly reached;
+  private readonly decisions;
+  private readonly assertionNames;
+  private readonly assertionScopes;
+  private readonly observedNames;
+  private readonly unresolvedAssertions;
+  private readonly fullTraceForAssertions;
+  private failure?;
+  constructor(plan: SelectiveReplayPlan, options: SelectiveReplayOptions);
+  enter(params: ReplayNodeIdentity & {
+    spanId: string;
+    parentSpanId: string | null;
+    inputs: unknown[];
+    safetyMock: boolean;
+    canReuseOutput: boolean;
+    reuseAllowed: boolean;
+  }): {
+    mock: false;
+  } | {
+    mock: true;
+    output: unknown;
+  };
+  assertNoSafetyConflict(): void;
+  report(): SelectiveReplayReport;
+}
+//#endregion
+//#region src/replayContext.d.ts
+/**
+ * A single span entry in the mock tree.
+ *
+ * Under the eager path (`mock: "all"`) `output`/`outputMeta` are populated
+ * inline, even when overrides are present. Under a non-`all` path that needs a
+ * tree (`marked`, or `none` with overrides), they are absent and the recorded
+ * output is fetched on demand via `externalSpanId` - see
+ * {@link ReplayContext.fetchSpanOutput}.
+ */
+interface MockSpan {
+  sourceSpanId: string;
+  /** Row id accepted by `getExternalSpan`, for the lazy per-span output fetch. */
+  externalSpanId?: string;
+  output?: unknown;
+  outputMeta?: unknown;
+}
+/**
+ * Per-item DB branch resolved by the Bitfab service from the source
+ * trace's `dbSnapshotRef`. Carried on the replay context so that
+ * customer code reads `databaseUrl` through `getCurrentReplayBranch()`, and so
+ * the process-isolated replay runner can materialize it into a `.env`
+ * overlay file before customer code initializes its DB client.
+ *
+ * `neonBranchId` is the literal Neon branch id; passing it to
+ * `releaseDbBranchLease` deletes that branch.
+ */
+interface DbBranchLease {
+  neonBranchId: string;
+  /** Env var name the customer's app reads, e.g. "DATABASE_URL". */
+  envKey: string;
+  databaseUrl: string;
+  expiresAt: string;
+  /**
+   * The instant the branch was pinned to (the source trace's wall clock).
+   * Echoed back in `db_snapshot_usage` on the replayed trace's completion.
+   */
+  snapshotTimestamp?: string;
+  providerConsoleUrl?: string;
+  readOnly?: boolean;
+  /**
+   * The branch's region, e.g. `aws-us-east-1`. A compute runs in its project's
+   * region, so a runner elsewhere pays that round trip on every query.
+   */
+  region?: string;
+}
+/**
+ * How long each phase of provisioning one replay branch took, measured
+ * server-side. A runner in another region sees these plus its own round trip.
+ *
+ * Durations, not instants: an instant is approximately `startedAt` plus the
+ * running sum, and per-phase wall-clock stamps would make clock skew between
+ * the server and your runner look like latency. Approximately, because
+ * `totalMs` is the resolve's true wall time and covers a little work no phase
+ * owns, so the phases account for it without summing to it exactly.
+ *
+ * `startedAt` and `totalMs` are always present. The phases are optional
+ * because a failed resolve reports only the ones it reached, and `totalMs` is
+ * then time-to-failure. On success every phase is present except `warmupMs`,
+ * which is absent when no warm-up SQL was supplied.
+ */
+interface DbBranchTimings {
+  /** When the resolve began, ISO. */
+  startedAt: string;
+  /** Resolving the project, plus its retention and region reads. */
+  projectResolveMs?: number;
+  /** Creating the branch, through its provider operations reaching terminal. */
+  branchCreateMs?: number;
+  /** Resolving the connection URI. 0 when the provider returns one inline. */
+  connectionUriMs?: number;
+  /** The compute accepting a connection. */
+  computeConnectMs?: number;
+  /** The branch answering a readiness query. */
+  baseProbeMs?: number;
+  /** Your warm-up SQL. Absent when you supplied none. */
+  warmupMs?: number;
+  /** The whole resolve, or time-to-failure when it threw. */
+  totalMs: number;
+}
+/**
+ * Wire shape of the caller's `ReplayOptions.dbBranch`, sent to
+ * `/api/sdk/replay/start` and applied per lease.
+ */
+interface DbBranchSettings {
+  minCu?: number;
+  maxCu?: number;
+  warmupSql?: string;
+}
+/**
+ * Pre-built lookup table of historical span outputs.
+ * Keys are `${traceFunctionKey}:${spanName}:${callIndex}` so that repeated
+ * calls with the same (key, name) are matched by call order, but spans
+ * sharing only the traceFunctionKey (different name) do not collide.
+ */
+interface MockTree {
+  spans: Map<string, MockSpan>;
+}
+interface ReplayContext {
+  experimentId: string;
+  selectiveReplay?: SelectiveReplayRuntime;
+  traceId?: string;
+  inputSourceSpanId?: string;
+  /**
+   * External trace ID from `external_traces.id`. Used for span-chain
+   * lookup against the source platform's trace tree (Braintrust, etc.).
+   * NOT the same as the Bitfab `traceId` - see `sourceBitfabTraceId`.
+   */
+  inputSourceTraceId?: string;
+  /**
+   * The Bitfab `traces.id` of the historical trace that produced this
+   * replay item's input. This is what customer-facing surfaces (e.g.
+   * `ReplayBranch.traceId`) should expose, since it's the ID the
+   * customer sees in the Bitfab dashboard.
+   */
+  sourceBitfabTraceId?: string;
+  replayAttempt?: number;
+  mockTree?: MockTree;
+  callCounters?: Map<string, number>;
+  mockStrategy?: "none" | "all" | "marked";
+  /**
+   * Resolved override chain for this replay, per-call overrides first then
+   * registered ones (first matcher wins). Empty/absent when no overrides apply.
+   */
+  mockOverrides?: MockOverride[];
+  /**
+   * Memoized lazy fetch of a span's recorded output (deserialized), keyed by
+   * `externalSpanId`. Present ONLY on a non-`all` path that needs a tree
+   * (`marked`, or `none` with overrides); absent under `mock: "all"`, where
+   * outputs are inline even when overrides are present. Its presence is the
+   * signal that outputs must be fetched rather than read inline.
+   */
+  fetchSpanOutput?: (externalSpanId: string) => Promise<unknown>;
+  /** Internal framework state captured on the historical root span. */
+  integrationFixtures?: Map<string, unknown>;
+  dbBranchLease?: DbBranchLease;
+  /**
+   * Server-measured provisioning timings for this item's branch, echoed back
+   * on the trace completion so the trace records what it cost to set up. Kept
+   * off `ReplayBranch`: customer code reads that mid-replay to reach the
+   * branch, and provisioning latency is a property of the run, not of the
+   * connection.
+   */
+  dbBranchTimings?: DbBranchTimings;
+  /**
+   * Set to true by `ReplayBranch` the first time customer code actually
+   * obtains `databaseUrl` for this item. Reported on the trace completion inside
+   * `db_snapshot_usage` so the server can distinguish "branch was
+   * provisioned and exposed" from "branch URL was actually consumed".
+   * Only an explicit `databaseUrl` read may set it. A path that hands the URL
+   * over by other means (e.g. a process-isolated runner writing an env
+   * overlay) must leave it alone: setting it there would make every such
+   * replay report `accessed` for free, and the flag would stop separating
+   * "branch was used" from "branch was offered".
+   */
+  dbSnapshotAccessed?: boolean;
+}
+//#endregion
+//#region src/replayInvocation.d.ts
+type FlagScalar = string | number | boolean | null;
+type FlagValue = FlagScalar | FlagScalar[];
+type ReplayEnvironment = "local" | "ci" | "cloud_replay";
+interface ReplayInvocation {
+  flags: Record<string, FlagValue>;
+  sdk: {
+    language: "typescript";
+    version: string;
+  };
+  environment: ReplayEnvironment;
+}
+//#endregion
+//#region src/simulationPlan.d.ts
+interface SimulationPlanNode {
+  traceFunctionKey: string;
+  name: string;
+  captureContent: boolean;
+}
+interface SimulationPlanResponse {
+  nodes: SimulationPlanNode[];
+}
+type SimulationPlanSubmit = (payload: Record<string, unknown>) => void;
+//#endregion
+//#region src/http.d.ts
+/**
+ * Wait for pending fire-and-forget requests AND every live span transport to
+ * deliver, within one total deadline. Useful in tests and scripts to ensure all
+ * data has been sent before asserting or exiting.
+ *
+ * Returns `false` when delivery failed or the deadline expired, so a caller
+ * that depends on persistence (replay does) can react instead of assuming a
+ * drained queue means the server has the data.
+ *
+ * @param timeoutMs - Maximum total time to wait in milliseconds (default: 5000)
+ */
+declare function flushTraces(timeoutMs?: number): Promise<boolean>;
+/**
+ * How the API key is supplied internally: either a literal string or a
+ * function resolved each time the key is needed (at request/send time). The
+ * function form is what defers key resolution past module-load construction
+ * so an env var loaded after the client is built (the ESM dotenv-hoisting
+ * case) is still picked up.
+ */
+type ApiKeyInput = string | (() => string | undefined);
+interface HttpClientConfig {
+  apiKey?: ApiKeyInput;
+  serviceUrl: string;
+  timeout?: number;
+}
+type SpanOccurrence = "first" | "last" | number;
+declare const SPAN_TYPES: readonly ["llm", "agent", "function", "guardrail", "handoff", "custom"];
+/**
+ * Span types matching the backend enum.
+ * - llm: LLM API calls
+ * - agent: Autonomous orchestrators
+ * - function: Tool implementations
+ * - guardrail: Safety/validation checks
+ * - handoff: Agent-to-agent transfers
+ * - custom: Application-specific tracing (default)
+ */
+type SpanType = (typeof SPAN_TYPES)[number];
+/**
+ * Which span `getTraceSpan` returns: `id` alone, or `name` and/or `type`
+ * with an optional `occurrence` (`"first"`, `"last"` by default, or a
+ * zero-based index into the matches in the order they ran).
+ */
+type SpanLookup = {
+  id: string;
+  name?: never;
+  type?: never;
+  occurrence?: never;
+} | {
+  name: string;
+  type?: SpanType;
+  id?: never;
+  occurrence?: SpanOccurrence;
+} | {
+  type: SpanType;
+  name?: string;
+  id?: never;
+  occurrence?: SpanOccurrence;
+};
+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;
+}
+/** What a caller learns about one tracked trace once it takes it back. */
+interface DeliveryReport {
+  spanCount: number;
+  /** A closing carrier was submitted, so the expected set is final. */
+  closed: boolean;
+  /** Every carrier submitted under this trace came back accepted. */
+  delivered: boolean;
+  /**
+   * The server's assigned `traces.id`, read back from the OTLP ingest response.
+   * Absent when talking to a server that predates this field, or before any
+   * carrier for the trace has been acked.
+   */
+  serverTraceId?: string;
+}
+declare class HttpClient {
+  private readonly apiKey;
+  private readonly serviceUrl;
+  private readonly timeout;
+  private traceTransport;
+  private readonly traceDeliveries;
+  private readonly deferredWork;
+  readonly traceCompletion: TraceCompletion;
+  private closed;
+  private closing;
+  externalSpanTransform: ((payload: Record<string, unknown>, submit: SimulationPlanSubmit, drop: () => void) => void) | undefined;
+  externalTraceTransform: ((payload: Record<string, unknown>, submit: SimulationPlanSubmit) => void) | undefined;
+  releaseHeldExternalSpans: ((timeoutMs: number) => Promise<boolean> | Promise<void>) | undefined;
+  stopSimulationPlan: (() => void) | undefined;
+  constructor(config: HttpClientConfig);
+  /**
+   * Resolve the API key at the moment it is needed (request time), invoking
+   * the function form if one was supplied. Never read at construction.
+   */
+  private resolveApiKey;
+  /** @internal Whether this client currently has credentials for trace delivery. */
+  hasApiKey(): boolean;
+  /**
+   * This client's span transport, built on first use.
+   *
+   * Lazy on purpose: a client that never sends a span must never start a batch
+   * worker. Every framework integration created from a `Bitfab` client shares
+   * the owning client's `HttpClient`, so handlers reuse this one worker instead
+   * of each spinning up their own.
+   */
+  private getTraceTransport;
+  /**
+   * Post one encoded batch and decide what the server's answer means, so the
+   * transport never reads a response. Rejections and permanent statuses come
+   * back as a non-retryable {@link DeliveryError}; anything the server might
+   * still accept on a second try comes back retryable.
+   */
+  private deliverCarriers;
+  /**
+   * Start tracking delivery for `traceIds`. Nothing is recorded for a trace
+   * that was never tracked, so ordinary tracing costs no bookkeeping at all.
+   */
+  trackTraceDeliveries(traceIds: string[]): void;
+  /**
+   * The server's assigned `traces.id` for a tracked trace if it has already
+   * been read back off an ingest response, without stopping tracking. Lets a
+   * replay surface the id mid-run for items whose spans already landed.
+   */
+  peekServerTraceId(traceId: string): string | undefined;
+  /** Whether any tracked trace has had its closing carrier submitted. */
+  hasClosedDeliveries(traceIds: string[]): boolean;
+  /**
+   * Report what each tracked trace submitted and whether the server confirmed
+   * it, and stop tracking them. Every id passed is freed, so a caller cannot
+   * leak a record for a trace that never closed.
+   *
+   * `delivered` is only meaningful once a flush has settled: acks land before
+   * an export resolves, so a flush that reported success has already collected
+   * every ack it is going to collect.
+   */
+  takeTraceDeliveries(traceIds: string[]): Record<string, DeliveryReport>;
+  /** Build a carrier's meta and record what it adds to its trace's expected set. */
+  private recordedMeta;
+  private recordSubmittedCarrier;
+  /**
+   * Ingestion commits every carrier in a request before it answers, so a
+   * delivered ref is proof its row exists: the same fact the replay status
+   * endpoint would report, already in hand.
+   */
+  /**
+   * Record the server's assigned `traces.id` for each tracked source trace,
+   * read back from the OTLP ingest response. Keyed by source trace id, the same
+   * key the delivery ledger uses. Untracked ids are ignored.
+   */
+  private recordServerTraceIds;
+  private recordDeliveredCarriers;
+  /**
+   * Track deferred span work so this client's own lifecycle waits for it, and
+   * so the process-wide flush and exit hook do too.
+   */
+  trackDeferred<T>(promise: Promise<T>): Promise<T>;
+  /**
+   * Settle only THIS client's deferred span work. Scoped deliberately: the
+   * global set can contain another client's long-running finalize, and
+   * attributing its timeout here would fail a client whose own work succeeded.
+   */
+  settleDeferredWork(timeoutMs?: number): Promise<boolean>;
+  /**
+   * Wait for spans queued by this client to be delivered, within one deadline.
+   * Returns false on delivery failure or timeout.
+   */
+  waitForPendingRequests(timeoutMs?: number): Promise<boolean>;
+  /**
+   * Flush and permanently close this client's tracing transport. Idempotent:
+   * a second call joins the first rather than tearing down a pipeline the
+   * first call already owns.
+   */
+  close(timeoutMs?: number): Promise<boolean>;
+  /**
+   * Make an HTTP request to the Bitfab API. Defaults to POST; pass
+   * `options.method` to use a different verb (e.g. "PATCH").
+   *
+   * @param endpoint - The API endpoint (without base URL)
+   * @param payload - The request body
+   * @param options - Optional request options
+   * @returns The parsed JSON response
+   * @throws {BitfabError} If the request fails
+   */
+  request<T>(endpoint: string, payload: Record<string, unknown>, options?: {
+    timeout?: number;
+    method?: "POST" | "PATCH" | "PUT" | "DELETE";
+  }): Promise<T>;
+  /**
+   * POST an already-encoded body. The span transport encodes its own batches,
+   * so routing them back through {@link HttpClient.request} would encode the
+   * same data twice.
+   */
+  sendEncoded<T>(endpoint: string, body: string, options?: {
+    timeout?: number;
+    method?: "POST" | "PATCH" | "PUT" | "DELETE";
+  }): Promise<T>;
+  private sendPrepared;
+  /**
+   * Look up a function by name.
+   * Blocks until complete - needed for function execution.
+   */
+  lookupFunction<T>(name: string): Promise<T>;
+  getSimulationPlan(): Promise<SimulationPlanResponse>;
+  getTraceSpan(traceId: string, lookup: SpanLookup): Promise<CapturedSpan | null>;
+  getSpan(spanId: string): Promise<CapturedSpan | null>;
+  /**
+   * GET a JSON endpoint on the service with the client's API key. Throws a
+   * `BitfabError` carrying the status text for any non-2xx response.
+   */
+  get<T>(endpoint: string, timeoutMs?: number, extraHeaders?: Record<string, string>): Promise<T>;
+  /**
+   * Queue an internal trace (from local BAML execution via `call()`) onto this
+   * client's batching transport. `functionId` moves into the payload because
+   * the OTLP carrier has no path to carry it.
+   */
+  sendInternalTrace(functionId: string, payload: Record<string, unknown>): void;
+  sendExternalSpan(payload: Record<string, unknown>): void;
+  submitExternalSpan(payload: Record<string, unknown>): void;
+  /**
+   * Queue an external trace completion (from OpenAI tracing) onto this
+   * client's batching transport. Fire-and-forget for the same reason as
+   * {@link HttpClient.sendExternalSpan}; replay confirms persistence with the
+   * server-authoritative barrier in `replay.ts`, not by awaiting this call.
+   */
+  sendExternalTrace(rawPayload: Record<string, unknown>): void;
+  private sendCountedExternalTrace;
+  submitExternalTrace(payload: Record<string, unknown>): void;
+  /**
+   * Partial update of an existing trace identified by its Bitfab trace ID.
+   * Used by the detached `client.getTrace(id)` handle.
+   *
+   * Blocking, like the other trace-API calls: it resolves once the server has
+   * applied the change and rejects if the server refused it. A patch targets a
+   * trace that is already closed, so there is no batch for it to ride along
+   * with and no later signal that would reveal a silent failure.
+   */
+  patchTrace(traceId: string, payload: {
+    appendContexts?: Record<string, unknown>[];
+    mergeMetadata?: Record<string, unknown>;
+    setSessionId?: string;
+    setName?: string;
+  }): Promise<void>;
+  /**
+   * 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, skipAssertionJudging?: boolean, experimentalSelectiveReplay?: SelectiveReplayOptions, notes?: string, metadata?: Record<string, string>, dryRun?: boolean, experimentGroupName?: string, invocation?: ReplayInvocation): Promise<StartReplayResponse>;
+  resumeReplay(experimentId: string, traceFunctionKey: string, codeChangeFiles?: CodeChangeFile[] | null, force?: boolean): Promise<ResumeReplayResponse>;
+  /**
+   * Fetch an external span by ID.
+   * Blocking GET request.
+   * The replay view limits rawData to input/output serialization fields.
+   */
+  getExternalSpan(spanId: string, options?: {
+    view?: "full" | "replay";
+  }): Promise<ExternalSpanResponse>;
+  /**
+   * Fetch the span tree for a root span.
+   * Blocking GET request.
+   *
+   * Pass `includeOutputs: false` for a payload-free tree (structure +
+   * `externalSpanId` only), so recorded outputs are fetched lazily per mocked
+   * span instead of all up front. Omit it (default eager) for `mock: "all"`.
+   * Pass `includeRootOutput: false` when the root was already fetched.
+   */
+  getSpanTree(externalSpanId: string, options?: {
+    includeOutputs?: boolean;
+    includeRootOutput?: boolean;
+  }): Promise<SpanTreeResponse>;
+  /**
+   * Read which of a replay run's traces the server has fully persisted.
+   *
+   * With `expectedSpanCounts`, a trace appears in the response only once it
+   * 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.
+   */
+  getReplayStatus(experimentId: string, expectedSpanCounts: Record<string, number>): Promise<ReplayStatusResponse>;
+  /**
+   * Mark a replay experiment as completed.
+   * 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>;
+  /**
+   * Ask the server to materialize a per-trace DB branch lease from a
+   * captured `dbSnapshotRef`. Blocking - the resolver creates a Neon
+   * snapshot + preview branch and polls operations to readiness, which
+   * can take seconds.
+   */
+  resolveDbBranchLease(experimentId: string, traceId: string, dbBranchSettings?: DbBranchSettings, attempt?: number): Promise<{
+    dbSnapshotRef: DbSnapshotRef | null;
+    lease: DbBranchLease | null;
+    leaseError: {
+      code: string;
+      message: string;
+    } | null;
+    timings: DbBranchTimings | null;
+  }>;
+  /** Release a previously-resolved DB branch by deleting its Neon branch. Idempotent server-side. */
+  releaseDbBranchLease(neonBranchId: string): Promise<void>;
+}
+interface TokenUsage {
+  input: number | null;
+  output: number | null;
+  cached: number | null;
+  total: number | null;
+}
+/**
+ * Describes a single file edited as part of a code change.
+ *
+ * - `path`: file path (relative to the repo root, or any consistent root)
+ * - `before`: file contents before the change ("" for newly created files)
+ * - `after`: file contents after the change ("" for deleted files)
+ */
+interface CodeChangeFile {
+  path: string;
+  before: string;
+  after: string;
+}
+interface StartReplayResponse {
+  /** Null for a dry run, which the server records no experiment for. */
+  experimentId: string | null;
+  experimentUrl: string | null;
+  attempts?: number;
+  items: Array<{
+    selectiveReplayPlan?: SelectiveReplayPlan;
+    /** Bitfab trace ID of the original (historical) trace being replayed. */
+    originalTraceId?: string;
+    /** External span ID the recorded inputs were read from (the original root span). */
+    originalSpanId?: string;
+    /** @deprecated alias for `originalTraceId`; the only key emitted by servers that predate the rename. */
+    sourceTraceId: string;
+    /** @deprecated alias for `originalSpanId`; the only key emitted by servers that predate the rename. */
+    sourceSpanId: string;
+    durationMs: number | null;
+    tokens: TokenUsage | null;
+    model: string | null;
+    /**
+     * The DB snapshot ref captured by the SDK at trace open. Surfaced so
+     * the SDK can pass it to the lease-resolver step (or report when no
+     * snapshot was captured for this trace).
+     */
+    dbSnapshotRef?: DbSnapshotRef;
+    /**
+     * Populated once the server-side resolver has materialized a per-item
+     * branch from `dbSnapshotRef`. The SDK exposes this to customer code
+     * via `getCurrentReplayBranch()`. Absent until the resolver lands.
+     */
+    dbBranchLease?: DbBranchLease;
+    /**
+     * Why the branch could not be resolved, when one was requested and the
+     * attempt failed. Distinct from both fields being absent, which means the
+     * trace carried no snapshot ref so nothing was attempted.
+     */
+    dbBranchLeaseError?: {
+      code: string;
+      message: string;
+    };
+    /**
+     * How long provisioning took, per phase. Sits beside the two fields above
+     * rather than inside either: it is reported on both outcomes, complete on
+     * success and partial up to the failing phase on error. Absent from
+     * servers that predate it.
+     */
+    dbBranchTimings?: DbBranchTimings;
+    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;
+  rawData: {
+    span_data: {
+      input: unknown;
+      output: unknown;
+      input_meta?: unknown;
+      output_meta?: unknown;
+      input_serialized?: {
+        json: unknown;
+        meta: unknown;
+      };
+      output_serialized?: {
+        json: unknown;
+        meta: unknown;
+      };
+    };
+  };
+}
+interface ReplayStatusResponse {
+  /**
+   * Local replay trace id -> server trace row id, for the traces the server
+   * considers fully persisted. Traces still short of their expected span count
+   * are simply absent.
+   */
+  traceIds?: Record<string, string>;
+}
+interface CompleteReplayResponse {
+  id: string;
+  status: string;
+  traceIds?: Record<string, string>;
+  /**
+   * Per-replay-trace token usage, keyed by the server trace id (the values of
+   * `traceIds`). Aggregated server-side from the freshly-uploaded replay spans,
+   * so it's the REPLAYED run's tokens (the same source the dashboard reads), not the
+   * original trace's. The SDK maps each item onto this to set
+   * `ReplayItem.tokens`. Absent on servers that predate this field.
+   */
+  tokens?: Record<string, TokenUsage | null>;
+  /**
+   * Number of traces the server has persisted for this experiment at
+   * completion time. Lets the SDK distinguish "uploads failed" from
+   * "server never saw them" when the trace-ID mapping is incomplete.
+   */
+  traceCount?: number;
+}
+interface ReseedSourceResponse {
+  traceId: string;
+  traceFunctionKey: string;
+  ingestionType: string;
+  name: string | null;
+  sessionId: string | null;
+  metadata: Record<string, unknown>;
+  input: unknown;
+  inputMeta: unknown;
+  inputSerialized: unknown;
+}
+interface ReseedTraceResponse {
+  traceId: string;
+  previousRunTraceId: string;
+}
+interface SpanTreeNode {
+  /** Upstream platform span id. Stable structural identity; NOT the row id. */
+  sourceSpanId: string;
+  /**
+   * The `externalSpans` row id, accepted by {@link HttpClient.getExternalSpan}.
+   * Distinct from `sourceSpanId`; used to lazily fetch this node's output when
+   * the tree was fetched with `includeOutputs: false`. Optional so trees from
+   * older servers (which omit it) still deserialize.
+   */
+  externalSpanId?: string;
+  traceFunctionKey: string;
+  spanName: string;
+  type: string;
+  /** Omitted when the tree was fetched payload-free (`includeOutputs: false`). */
+  output?: unknown;
+  outputMeta?: unknown;
+  children: SpanTreeNode[];
+}
+interface SpanTreeResponse {
+  root: SpanTreeNode;
+}
+//#endregion
+//#region src/categories.d.ts
+type CategorySummary = {
+  id: string;
+  title: string;
+  description: string;
+};
+type Category = CategorySummary & {
+  organizationId: string;
+  createdAt: string;
+  updatedAt: string;
+};
+type SaveCategoryParams = {
+  id?: string;
+  title: string;
+  description?: string;
+};
+/** @deprecated Use {@link CategorySummary}. Same shape. */
+type AssertionCategorySummary = CategorySummary;
+/** @deprecated Use {@link Category}. Same shape. */
+type AssertionCategory = Category;
+/** @deprecated Use {@link SaveCategoryParams}. Same shape. */
+type SaveAssertionCategoryParams = SaveCategoryParams;
+/** Organization-scoped groupings for assertions and scenarios. */
+declare class CategoriesClient {
+  private readonly httpClient;
+  constructor(httpClient: HttpClient);
+  /** Create a category, or update it by ID. Omitted descriptions are preserved. */
+  save(params: SaveCategoryParams): Promise<Category>;
+  /** Read one category in the API key's organization. */
+  get(id: string): Promise<Category>;
+  /** List the organization's categories ordered by title. */
+  list(): Promise<Category[]>;
+  /** Delete a category and clear its assignments, preserving assertions and verdicts. */
+  delete(id: string): Promise<Category>;
+}
+/**
+ * @deprecated Use {@link CategoriesClient}. Same class.
+ * @alias
+ */
+declare const AssertionCategoriesClient: typeof CategoriesClient;
+/**
+ * @deprecated Use {@link CategoriesClient}. Same class.
+ * @alias
+ */
+type AssertionCategoriesClient = CategoriesClient;
+//#endregion
+//#region src/claudeAgentSdk.d.ts
+interface ActiveSpanContext$2 {
+  traceId: string;
+  spanId: string;
+}
+/**
+ * Claude Agent SDK handler that sends traces to Bitfab.
+ *
+ * Captures LLM turns, tool invocations, and subagent execution as
+ * Bitfab spans with proper parent-child hierarchy.
+ *
+ * The TypeScript Claude Agent SDK exposes a single `query()` entry point (there
+ * is no `ClaudeSDKClient` class - that exists only in the Python SDK). Wrap the
+ * `query()` async iterator with `wrapQuery`; tool and subagent spans come from
+ * the hooks injected by `instrumentOptions`.
+ *
+ * ```typescript
+ * import { Bitfab } from "@bitfab/sdk";
+ * import { query } from "@anthropic-ai/claude-agent-sdk";
+ *
+ * const bitfab = new Bitfab({ apiKey: "..." });
+ * const handler = bitfab.getClaudeAgentHandler("my-agent");
+ *
+ * const options = handler.instrumentOptions({
+ *   model: "claude-sonnet-4-5-...",
+ * });
+ *
+ * for await (const message of handler.wrapQuery(
+ *   query({ prompt: "Do something", options })
+ * )) {
+ *   // process messages normally
+ * }
+ * ```
+ */
+declare class BitfabClaudeAgentHandler {
+  private readonly httpClient;
+  private readonly ownsHttpClient;
+  private readonly traceFunctionKey;
+  private readonly getActiveSpanContext;
+  private readonly shouldRecord;
+  private runToSpan;
+  private traceId;
+  private rootSpanId;
+  private activeContext;
+  private traceStartedAt;
+  private conversationHistory;
+  private pendingMessages;
+  private currentLlmSpanId;
+  private currentLlmMessageId;
+  private currentLlmContent;
+  private currentLlmModel;
+  private currentLlmUsage;
+  private currentLlmStartedAt;
+  private currentLlmHistorySnapshot;
+  private activeSubagentSpans;
+  private hasRootInput;
+  private rootInput;
+  private rootOutput;
+  constructor(config: {
+    apiKey?: ApiKeyInput;
+    traceFunctionKey: string;
+    serviceUrl?: string;
+    timeout?: number;
+    getActiveSpanContext?: () => ActiveSpanContext$2 | null;
+    shouldRecord?: () => boolean;
+    /**
+     * The owning `Bitfab` client's HTTP client. Supplied by
+     * `getClaudeAgentHandler()` so this handler shares that client's single
+     * span-transport worker instead of starting a second one.
+     * @internal
+     */
+    _httpClient?: HttpClient;
+  });
+  /**
+   * Flush and release the span transport this handler started. A no-op when
+   * the handler borrowed a `Bitfab` client's HTTP client: that client's
+   * `close()` owns the worker's lifetime.
+   */
+  close(timeoutMs?: number): Promise<boolean>;
+  private ensureTrace;
+  private getParentId;
+  private maybeStartRootSpan;
+  private completeRootSpan;
+  private startSpan;
+  private completeSpan;
+  private sendSpan;
+  private sendTraceCompletion;
+  private preToolUseHook;
+  private postToolUseHook;
+  private postToolUseFailureHook;
+  private subagentStartHook;
+  private subagentStopHook;
+  /**
+   * Inject Bitfab tracing hooks into Claude Agent SDK options.
+   *
+   * Modifies the options object and returns it for convenience.
+   * The SDK's `HookMatcher` is constructed as a plain object
+   * (`{ matcher: null, hooks: [callback] }`) to avoid requiring
+   * `@anthropic-ai/claude-agent-sdk` as a dependency.
+   *
+   * @param options - Options object with a `hooks` property
+   * @returns The modified options object with Bitfab hooks injected
+   */
+  instrumentOptions<T extends Record<string, unknown>>(options: T): T;
+  /**
+   * Wrap any Claude Agent SDK message stream to capture LLM turns.
+   *
+   * Yields every message unchanged while capturing assistant message
+   * content as LLM turn spans. Kept for naming symmetry with the Python
+   * SDK's `wrapResponse` (which wraps `ClaudeSDKClient.receiveResponse()`);
+   * in TypeScript, prefer `wrapQuery` around `query()`.
+   *
+   * Pass `{ input }` (the prompt) to record a replayable root span - see
+   * `wrapQuery`.
+   */
+  wrapResponse(stream: AsyncIterable<unknown>, opts?: {
+    input?: unknown;
+  }): AsyncIterable<unknown>;
+  /**
+   * Wrap a `query()` async iterator to capture LLM turns.
+   *
+   * Tool and subagent spans are captured separately via the hooks injected
+   * by `instrumentOptions` into the `options` passed to `query()`.
+   *
+   * Pass `{ input }` - the prompt (or the serializable args that produced it)
+   * - to make a handler-only run replayable: the handler records a root `agent`
+   * span with that input, so `replay(key, fn)` can re-feed it. Omit it only
+   * when an enclosing `withSpan` already supplies the replayable root.
+   *
+   * ```typescript
+   * handler.wrapQuery(query({ prompt, options }), { input: prompt })
+   * ```
+   */
+  wrapQuery(stream: AsyncIterable<unknown>, opts?: {
+    input?: unknown;
+  }): AsyncIterable<unknown>;
+  private setRootInput;
+  private processStream;
+  private processMessage;
+  private handleAssistantMessage;
+  private handleUserMessage;
+  private handleResultMessage;
+  private flushLlmTurn;
+  private resetState;
+}
+//#endregion
+//#region src/vercelAiSdk.d.ts
+/**
+ * Vercel AI SDK integration for Bitfab tracing.
+ *
+ * The Vercel AI SDK (`ai`) routes every `generateText` / `streamText` /
+ * `generateObject` / `streamObject` call through a language model. Bitfab hooks
+ * that model with a *language-model middleware* (`wrapLanguageModel`), so each
+ * model call is captured as a keyed `llm` span with no hand-written `withSpan`:
+ *
+ * ```typescript
+ * import { Bitfab } from "@bitfab/sdk";
+ * import { wrapLanguageModel, streamText } from "ai";
+ * import { openai } from "@ai-sdk/openai";
+ *
+ * const bitfab = new Bitfab({ apiKey: "..." });
+ *
+ * const model = wrapLanguageModel({
+ *   model: openai("gpt-4o"),
+ *   middleware: bitfab.getVercelAiMiddleware("chat-turn"),
+ * });
+ *
+ * const result = streamText({ model, messages });
+ * return result.toUIMessageStreamResponse(); // live stream untouched
+ * ```
+ *
+ * The span records the call parameters (the prompt/messages) as its input and a
+ * serializable summary (`{ text, toolCalls, usage, finishReason }`) as its
+ * output. Streaming is handled by passing the model's stream through a
+ * reader that accumulates text and usage as the caller consumes it. Parts,
+ * upstream errors, and cancellation propagate to the caller unchanged; the
+ * span finalizes on completion, error, or cancellation with partial output.
+ *
+ * The middleware is fully duck-typed (no static or dynamic `ai` import), so it
+ * adds no dependency and is browser-safe. It works with `ai` v5 and v6.
+ */
+type LlmSpanOptions = {
+  type: "llm";
+  finalize: (result: unknown) => unknown | Promise<unknown>;
+  surface: "inherit";
+  instrumentation: "vercel-ai";
+};
+type WithSpanFn$1 = <TArgs extends unknown[], TReturn>(traceFunctionKey: string, options: LlmSpanOptions, fn: (...args: TArgs) => TReturn) => (...args: TArgs) => TReturn;
+/**
+ * Duck-typed subset of the Vercel AI SDK language-model call parameters. The
+ * only field we read for the span input is `prompt` (the messages), but the
+ * whole object is recorded so the call is reconstructable on replay.
+ */
+interface VercelCallParams {
+  prompt?: unknown;
+  [key: string]: unknown;
+}
+/** A content part of a non-streaming `doGenerate` result. */
+interface VercelContentPart {
+  type: string;
+  text?: string;
+  toolCallId?: string;
+  toolName?: string;
+  input?: unknown;
+  args?: unknown;
+}
+/** Duck-typed subset of a non-streaming `doGenerate` result. */
+interface VercelGenerateResult {
+  content?: VercelContentPart[];
+  text?: string;
+  usage?: unknown;
+  finishReason?: unknown;
+  [key: string]: unknown;
+}
+/** Duck-typed subset of a single streaming part from `doStream`. */
+interface VercelStreamPart {
+  type: string;
+  error?: unknown;
+  delta?: string;
+  textDelta?: string;
+  toolCallId?: string;
+  toolName?: string;
+  input?: unknown;
+  args?: unknown;
+  usage?: unknown;
+  finishReason?: unknown;
+}
+/** Duck-typed subset of a streaming `doStream` result. */
+interface VercelStreamResult {
+  stream: ReadableStream<VercelStreamPart>;
+  [key: string]: unknown;
+}
+interface MiddlewareCall<TResult> {
+  doGenerate: () => PromiseLike<VercelGenerateResult>;
+  doStream: () => PromiseLike<VercelStreamResult>;
+  params: VercelCallParams;
+  model: unknown;
+  __result?: TResult;
+}
+/**
+ * The structural shape of a Vercel AI SDK language-model middleware. Matches
+ * `LanguageModelV3Middleware` from `@ai-sdk/provider` without importing it, so
+ * the SDK stays dependency-free. `wrapLanguageModel` only reads the method
+ * fields (it ignores `specificationVersion`), so this object drops straight in.
+ */
+interface BitfabLanguageModelMiddleware {
+  specificationVersion: "v3";
+  wrapGenerate: (options: MiddlewareCall<VercelGenerateResult>) => Promise<any>;
+  wrapStream: (options: MiddlewareCall<VercelStreamResult>) => Promise<any>;
+}
+/**
+ * Vercel AI SDK middleware that records each language-model call as a keyed
+ * `llm` span. Obtain it from {@link BitfabClient.getVercelAiMiddleware} rather
+ * than constructing it directly.
+ */
+declare class BitfabVercelAiHandler {
+  private readonly traceFunctionKey;
+  private readonly withSpanFn;
+  constructor(config: {
+    traceFunctionKey: string;
+    withSpan: WithSpanFn$1;
+  });
+  /** The `wrapLanguageModel` middleware object for this trace function key. */
+  get middleware(): BitfabLanguageModelMiddleware;
+}
+//#endregion
+//#region src/datasets.d.ts
+interface DatasetGraderRef {
+  id: string;
+  name: string | null;
+}
+interface Dataset {
+  id: string;
+  traceFunctionKey: string;
+  name: string;
+  description: string | null;
+  traceCount: number;
+  graders: DatasetGraderRef[];
+  /**
+   * Whether the dataset is marked golden for the whole organization, as a
+   * trusted reference set. Golden datasets are listed first in the Bitfab app.
+   * Reported as `false` by servers that predate golden datasets.
+   */
+  golden: boolean;
+  createdAt: string;
+  updatedAt: string;
+}
+interface SaveDatasetParams {
+  traceFunctionKey: string;
+  name: string;
+  description?: string;
+  /**
+   * `true` marks the dataset as golden for the whole organization, `false`
+   * unmarks it, and omitting it leaves it as it is (a new dataset starts not
+   * golden).
+   */
+  golden?: boolean;
+}
+interface UpdateDatasetParams {
+  name?: string;
+  description?: string;
+  /**
+   * `true` marks the dataset as golden for the whole organization, `false`
+   * unmarks it, and omitting it leaves it as it is.
+   */
+  golden?: boolean;
+}
+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 GraderRerunProgress {
+  completedTraces: number;
+  totalTraces: number;
+  graderCount: number;
+}
+interface GraderRerunResult {
+  tracesGraded: number;
+  gradersRun: number;
+}
+interface GraderRerun {
+  id: string;
+  status: GraderRerunStatus;
+  graderIds: string[];
+  progress: GraderRerunProgress | null;
+  result: GraderRerunResult | null;
+  error: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+interface RerunGradersOptions {
+  graderIds?: string[];
+  timeoutMs?: number;
+}
+interface RerunGradersResult {
+  run: GraderRerun;
+  joinedExisting: boolean;
+}
+declare class GraderRerunError extends Error {
+  readonly run: GraderRerun;
+  constructor(message: string, run: GraderRerun);
+}
+declare class GraderRerunTimeoutError extends GraderRerunError {
+  constructor(datasetId: string, run: GraderRerun, timeoutMs: number);
+}
+/**
+ * Dataset operations for the authenticated organization, reached as
+ * `client.datasets`. A dataset is a named bucket of traces scoped to one trace
+ * function. Experiments replay against it and its graders score its members.
+ */
+declare class DatasetsClient {
+  private readonly httpClient;
+  constructor(httpClient: HttpClient);
+  /**
+   * Create a dataset, or update the one already named this way under the same
+   * trace function. `created` reports which happened. An omitted description
+   * leaves an existing one untouched.
+   */
+  save(params: SaveDatasetParams): Promise<SaveDatasetResult>;
+  /**
+   * Rename a dataset or change its description in place. The dataset keeps its
+   * id, traces, and graders. An empty `description` clears it. Rejects with a
+   * 400 `BitfabError` when the new name is already used by another dataset on
+   * the same trace function, and a 404 when the dataset is not in this
+   * organization.
+   */
+  update(datasetId: string, params: UpdateDatasetParams): Promise<Dataset>;
+  /**
+   * List datasets, scoped to one trace function when `traceFunctionKey` is
+   * given and organization-wide otherwise. Fetches all pages automatically.
+   */
+  list(params?: ListDatasetsParams): Promise<Dataset[]>;
+  /** Fetch one dataset by id. Rejects with a 404 `BitfabError` when it is not in this organization. */
+  get(datasetId: string): Promise<Dataset>;
+  /** Fetches all trace-ID pages, the same membership a replay with `datasetId` selects. */
+  listTraces(datasetId: string): Promise<DatasetTraceIds>;
+  /**
+   * Add traces to the dataset (1 to 100 ids per call). Traces outside the
+   * organization or under another trace function are reported in
+   * `skippedTraceIds` rather than failing the call.
+   */
+  addTraces(datasetId: string, traceIds: string[]): Promise<AddDatasetTracesResult>;
+  /** Remove traces from the dataset. The traces themselves are never deleted. */
+  removeTraces(datasetId: string, traceIds: string[]): Promise<RemoveDatasetTracesResult>;
+  /**
+   * Assign graders to the dataset (1 to 100 ids per call). Graders outside the
+   * organization or under another trace function are reported in
+   * `skippedGraderIds` rather than failing the call.
+   */
+  addGraders(datasetId: string, graderIds: string[]): Promise<AddDatasetGradersResult>;
+  /** Unassign graders from the dataset. */
+  removeGraders(datasetId: string, graderIds: string[]): Promise<RemoveDatasetGradersResult>;
+  rerunGraders(datasetId: string, options?: RerunGradersOptions): Promise<RerunGradersResult>;
+  /**
+   * The dataset's active grader re-run, or the run named by `runId`. Returns
+   * `null` when nothing is active or the run does not belong to this dataset.
+   */
+  getGraderRerun(datasetId: string, runId?: string): Promise<GraderRerun | null>;
+}
+//#endregion
+//#region src/experiments.d.ts
+type ExperimentStatus = "pending" | "completed" | "failed" | "interrupted";
+type ExperimentRunBy = {
+  id: string;
+  fullName: string | null;
+  email: string | null;
+  imageUrl: string | null;
+};
+type ExperimentCodeChangeTotals = {
+  files: number;
+  added: number;
+  removed: number;
+};
+type Experiment = {
+  id: string;
+  name: string | null;
+  notes: string | null;
+  status: ExperimentStatus;
+  traceFunctionKey: string | null;
+  createdAt: string;
+  completedAt: string | null;
+  codeChangeDescription: string | null;
+  codeChangeTotals: ExperimentCodeChangeTotals | null;
+  experimentGroupId: string | null;
+  experimentGroupName: string | null;
+  datasetId: string | null;
+  datasetName: string | null;
+  datasetIds: string[];
+  datasetNames: string[];
+  attempts: number;
+  plannedTraceCount: number | null;
+  runBy: ExperimentRunBy | null;
+  githubEmail: string | null;
+  gitBranch: string | null;
+  commitSha: string | null;
+  baseSha: string | null;
+  experimentSha: string | null;
+  metadata: Record<string, string>;
+};
+type ExperimentPage = {
+  experiments: Experiment[];
+  nextCursor: string | null;
+  hasMore: boolean;
+};
+type ListExperimentsParams = {
+  datasetId?: string;
+  traceFunctionKey?: string;
+  gitBranch?: string;
+  experimentGroupId?: string;
+  status?: ExperimentStatus;
+  metadata?: Record<string, string>;
+  createdAfter?: Date | string;
+  createdBefore?: Date | string;
+  cursor?: string;
+  limit?: number;
+};
+type ExperimentTally = {
+  fixed: number;
+  stillPassing: number;
+  regressed: number;
+  stillFailing: number;
+  originalUnlabeled: number;
+  unpaired: number;
+  classified: number;
+  passing: number;
+  failing: number;
+  /** Failing verdicts where the judge abstained on every attempt because it could not find the evidence. */
+  abstained: number;
+};
+type ExperimentTotals = {
+  total: number;
+  traces: number;
+  succeeded: number;
+  failed: number;
+  pending: number;
+  awaitingLabels: number;
+  errored: number;
+  withErrors: number;
+  ungradable: number;
+  judging: number;
+  skipped: number;
+};
+type ExperimentCategoryTally = {
+  category: CategorySummary;
+  labels: ExperimentTally;
+};
+type ExperimentJitter = {
+  disagreeing: number;
+  attempts: number;
+  traces: number;
+};
+type ExperimentRollup = {
+  traces: ExperimentTally;
+  skippedTraces: number;
+  labels: ExperimentTally;
+  checks: ExperimentTally;
+  categories: ExperimentCategoryTally[];
+  jitter: ExperimentJitter;
+};
+type ExperimentRollupResult = {
+  experimentId: string;
+  totals: ExperimentTotals;
+  rollup: ExperimentRollup;
+};
+declare class ExperimentsClient {
+  private readonly httpClient;
+  constructor(httpClient: HttpClient);
+  list(params?: ListExperimentsParams): Promise<ExperimentPage>;
+  get(id: string): Promise<Experiment>;
+  getRollup(id: string): Promise<ExperimentRollupResult>;
+  getRollupAll(ids: string[]): Promise<ExperimentRollupResult[]>;
+}
+//#endregion
+//#region src/traces.d.ts
+type TraceTargetOccurrence = "first" | "last" | number;
+type TraceTarget = {
+  kind: "output";
+} | {
+  kind: "span";
+  name: string;
+  occurrence?: TraceTargetOccurrence;
+};
+type TraceAssertionSource = "human" | "agent";
+type TraceSearchFilters = {
+  callerMetadata?: Record<string, string>;
+  name?: string;
+  nameContains?: string;
+  /** Only the replay traces this experiment produced. */
+  experimentId?: string;
+};
+type TraceSearchParams = TraceSearchFilters & ({
+  callerMetadata: Record<string, string>;
+} | {
+  name: string;
+} | {
+  nameContains: string;
+} | {
+  experimentId: string;
+}) & {
+  traceFunctionKey?: string;
+  cursor?: string | null;
+  limit?: number;
+};
+type TraceSearchResult = {
+  traces: Array<{
+    id: string;
+    traceFunctionKey: string | null;
+    name: string | null;
+    status: "pending" | "completed" | "failed" | "dropped";
+    createdAt: string;
+    callerMetadata: Record<string, string>;
+    /** The experiment that produced this trace, or null for a captured trace. */
+    experimentId: string | null;
+    /** Wall-clock time of the whole trace, or null when it has no end time. */
+    durationMs: number | null;
+    /** Token usage summed across the trace, or null when none was recorded. */
+    tokens: TokenUsage | null;
+  }>;
+  nextCursor: string | null;
+  hasMore: boolean;
+};
+type TraceAssertion = {
+  id: string;
+  traceId: string;
+  assertion: string;
+  humanNote: string | null;
+  category_id: string | null;
+  /** @deprecated Use {@link category_id}. Same value. */
+  category_assertion_id: string | null;
+  category: CategorySummary | null;
+  passCriteria: string | null;
+  failCriteria: string | null;
+  targetOnEvaluatedTrace: TraceTarget | null;
+  source: TraceAssertionSource;
+  /** Why this assertion is right for its trace, span by span. */
+  justification: Justification | null;
+  /** Why its assigned category is the right one, span by span. */
+  categoryJustification: Justification | null;
+  /** Who is on the hook for reviewing this assertion, or null for nobody. */
+  assignee: Assignee | null;
+  createdAt: string;
+  updatedAt: string;
+} & ApprovalFields;
+type AssertionEvidenceParameter = {
+  name: string;
+  type: "string" | "number" | "boolean" | "object" | "array" | "null" | "unknown";
+};
+type AssertionLabelEvidence = {
+  spanId: string;
+  text: string;
+  sourceField: string;
+  spanName: string | null;
+  parameters: AssertionEvidenceParameter[];
+  spanType: "llm" | "agent" | "function" | "guardrail" | "handoff" | "custom";
+  isMocked: boolean;
+};
+type SaveAssertion = {
+  /** Omit to preserve the category, or pass null to clear it. */
+  category_id?: string | null;
+  /** @deprecated Use {@link category_id}. Ignored when `category_id` is also set. */
+  category_assertion_id?: string | null;
+  id?: string;
+  assertion: string;
+  humanNote?: string | null;
+  passCriteria?: string | null;
+  failCriteria?: string | null;
+  targetOnEvaluatedTrace?: TraceTarget | null;
+  /**
+   * Why this assertion is right for this trace, one entry per span it rests on.
+   * Cite spans on this trace only. Omit on an edit to preserve it.
+   */
+  justification?: Justification | null;
+  /**
+   * Why `category_id` is the right category. Changing the category
+   * clears it. Omit on an edit to preserve it.
+   */
+  categoryJustification?: Justification | null;
+  /**
+   * Email of the organization member who should review this assertion. Routing
+   * only, so it leaves the approval state alone. Omit on an edit to preserve
+   * the current assignee, or pass null to leave it to nobody.
+   */
+  assigneeEmail?: string | null;
+};
+type ScenarioSource = {
+  spanId: string;
+  sourceField: "input" | "output";
+  text: string;
+};
+type ScenarioTrigger = {
+  inputId: number | null;
+  inputType: string;
+  channel: string;
+  from: string;
+  to: string | null;
+  cc: string | null;
+  subject: string | null;
+  type: string;
+  eventTime: string;
+  eventTimeSource: "message date" | "run start";
+  source: "request" | "run instructions";
+  content: string;
+  contentPassages: string[];
+  contentIsWholeMessage: boolean;
+  sources: ScenarioSource[];
+};
+type ScenarioDataOrigin = {
+  section: string;
+  channel: string | null;
+  from: string | null;
+  to: string | null;
+  cc: string | null;
+  subject: string | null;
+  sentAtText: string | null;
+};
+type ScenarioHistoryEntry = {
+  role: "thread start" | "fact";
+  kind: string;
+  quote: string;
+  summary: string | null;
+  origin: ScenarioDataOrigin | null;
+  sentAt: string | null;
+  weekday: string | null;
+  sincePrevious: string | null;
+  source: ScenarioSource | null;
+};
+type ScenarioData = {
+  hasHistory: boolean;
+  topic: string;
+  history: ScenarioHistoryEntry[];
+  missing: string[];
+};
+/** One thing the run did, such as sending a message or calling a tool. */
+type ScenarioAction = {
+  /** The action, for example `"send_sms_message"`. */
+  name: string;
+  /** The arguments the action was called with. */
+  details: Record<string, unknown>;
+  /** What came back from the action, or null when nothing did. */
+  result: string | null;
+  /** True when the action did not go through. */
+  failed: boolean;
+  /** When the action happened, as an ISO 8601 time, or null when unknown. */
+  at: string | null;
+};
+/**
+ * What the run actually did in this scenario, one example of a response. It
+ * never says what the run should have done. Bitfab never fills it in. The
+ * caller saves it with `saveScenario`.
+ */
+type ScenarioActualOutcome = {
+  /** What the run did, in a few sentences. */
+  summary: string;
+  /** The actions the run took, in order. */
+  actions: ScenarioAction[];
+  /**
+   * The span the outcome was read from, on a trace linked to this scenario,
+   * or null when it was not read from one.
+   */
+  source: ScenarioSource | null;
+};
+type Scenario = {
+  id: string;
+  createdAt: string;
+  updatedAt: string;
+  organizationId: string;
+  traceFunctionId: string;
+  sourceTraceId: string;
+  extractor: "noah";
+  name: string;
+  description: string;
+  trigger: ScenarioTrigger;
+  data: ScenarioData;
+  triggerSummary: string;
+  dataSummary: string;
+  /** What the run actually did, or null when none has been saved. */
+  actualOutcome: ScenarioActualOutcome | null;
+  /** Every category the scenario is filed under, sorted by title. */
+  categories: CategorySummary[];
+};
+type SaveScenarioHistoryEntry = Omit<ScenarioHistoryEntry, "source"> & {
+  source?: ScenarioSource | null;
+};
+type SaveScenarioData = Omit<ScenarioData, "history"> & {
+  history: SaveScenarioHistoryEntry[];
+};
+/**
+ * What the run actually did, as sent to `saveScenario`. `source` may be left
+ * out, which saves it as null.
+ */
+type SaveScenarioActualOutcome = Omit<ScenarioActualOutcome, "source"> & {
+  source?: ScenarioSource | null;
+};
+type ScenarioDataAppend = {
+  history?: SaveScenarioHistoryEntry[];
+  missing?: string[];
+};
+type SaveScenarioParams = {
+  traceId: string;
+  name?: string;
+  description?: string;
+  trigger?: ScenarioTrigger;
+  /**
+   * What the run actually did, never what it should have done. Replaces the
+   * saved value whole. Pass null to clear it, or leave it out to keep it.
+   * Sending only this field, null included, is a valid save.
+   */
+  actualOutcome?: SaveScenarioActualOutcome | null;
+  /**
+   * Categories to file the scenario under. Replaces the whole set. Leave it
+   * out to keep the current set, or pass an empty array to clear it. An id
+   * outside the organization fails the save.
+   */
+  categoryIds?: string[];
+} & ({
+  data?: SaveScenarioData;
+  appendData?: never;
+} | {
+  appendData: ScenarioDataAppend;
+  data?: never;
+}) & ({
+  name: string;
+} | {
+  description: string;
+} | {
+  trigger: ScenarioTrigger;
+} | {
+  data: SaveScenarioData;
+} | {
+  appendData: ScenarioDataAppend;
+} | {
+  actualOutcome: SaveScenarioActualOutcome | null;
+} | {
+  categoryIds: string[];
+});
+type AssertionGenerationStatus = "running" | "completed" | "failed";
+type AssertionGeneration = {
+  status: AssertionGenerationStatus;
+  error: string | null;
+  assertionIds: string[];
+  startedAt: string;
+  finishedAt: string | null;
+};
+type TraceAssertionsResult = {
+  assertions: TraceAssertion[];
+  inheritedFrom: string | null;
+  generation: AssertionGeneration | null;
+};
+type TraceAssertionsUpdate = {
+  traceId: string;
+  assertions: SaveAssertion[];
+};
+type SaveAssertionsParams = {
+  traceId: string;
+  assertions: SaveAssertion[];
+  source?: TraceAssertionSource;
+};
+type SaveAssertionsAllParams = {
+  updates: TraceAssertionsUpdate[];
+  source?: TraceAssertionSource;
+};
+type ArchiveAssertionsParams = {
+  traceId: string;
+  assertionIds: string[];
+};
+type GenerateAssertionsOptions = {
+  guidance?: string;
+  categoryIds?: string[];
+  regenerate?: boolean;
+  timeoutMs?: number;
+};
+declare class AssertionGenerationError extends Error {
+  readonly traceId: string;
+  constructor(message: string, traceId: string);
+}
+declare class AssertionGenerationTimeoutError extends AssertionGenerationError {
+  constructor(traceId: string, timeoutMs: number);
+}
+declare class TracesClient {
+  private readonly httpClient;
+  constructor(httpClient: HttpClient);
+  search(params: TraceSearchParams): Promise<TraceSearchResult>;
+  getAssertions(traceId: string): Promise<TraceAssertionsResult>;
+  saveAssertions(params: SaveAssertionsParams): Promise<TraceAssertion[]>;
+  saveAssertionsAll(params: SaveAssertionsAllParams): Promise<TraceAssertion[]>;
+  generateAssertions(traceId: string, options?: GenerateAssertionsOptions): Promise<TraceAssertion[]>;
+  archiveAssertions(params: ArchiveAssertionsParams): Promise<string[]>;
+  getScenario(traceId: string): Promise<Scenario>;
+  saveScenario({ traceId, ...edit }: SaveScenarioParams): Promise<Scenario>;
+}
+//#endregion
+//#region src/labels.d.ts
+type LabelConfidence = "VeryLow" | "Low" | "Medium" | "High" | "VeryHigh";
+type LabelAction = "set" | "archived" | "no-active-label" | "skipped" | "abstained";
+type LabelStatus = "labeled" | "skipped" | "unlabeled";
+type LabelSource = "human" | "agent";
+/** An assertion verdict. `abstained` means the judge could not find the evidence the assertion needs; it counts as a fail. */
+type Verdict = "pass" | "fail" | "abstained";
+type LabelAddress = {
+  traceId: string;
+  originalTraceId?: never;
+  attempt?: never;
+} | {
+  originalTraceId: string;
+  attempt?: number;
+  traceId?: never;
+};
+type LabelTarget = LabelAddress & {
+  assertionId: string;
+};
+type ArchiveLabelTarget = LabelAddress & {
+  assertionId?: string;
+};
+type LabelVerdict = {
+  label: boolean;
+  annotation: string;
+  confidence?: LabelConfidence;
+  evidence?: Justification | null;
+} | {
+  skip: true;
+  annotation?: string;
+} | {
+  abstain: true;
+  annotation?: string;
+};
+type LabelUpdate = (LabelTarget & LabelVerdict) | (ArchiveLabelTarget & {
+  archive: true;
+});
+type LabelOutcome = {
+  key: string;
+  traceId: string;
+  action: LabelAction;
+};
+type HumanLabelUpdate = {
+  traceId: string;
+  assertionId: string;
+  label: boolean;
+  annotation: string;
+  confidence?: LabelConfidence;
+  evidence?: Justification | null;
+};
+type HumanLabelOutcome = {
+  traceId: string;
+  assertionId: string | null;
+  label: boolean;
+  action: "set";
+};
+type AssertionVerdict = {
+  assertionId: string;
+  assertion: string | null;
+  labelStatus: LabelStatus;
+  label: boolean | null;
+  /** The verdict, or null when there is none. `label` carries the same verdict as a boolean, false for both fail and abstained. */
+  verdict: Verdict | null;
+  annotation: string | null;
+  evidence: Justification | null;
+  confidence: LabelConfidence | null;
+  labelSource: LabelSource;
+  approved: boolean;
+};
+type TraceLabels = {
+  traceId: string;
+  labelStatus: LabelStatus;
+  label: boolean | null;
+  annotation: string | null;
+  evidence: Justification | null;
+  approved: boolean;
+  passed: number;
+  failed: number;
+  /** How many of the failed assertion verdicts are abstentions, where the judge could not find the evidence. */
+  abstained: number;
+  assertions: AssertionVerdict[];
+};
+declare class LabelsClient {
+  private readonly httpClient;
+  constructor(httpClient: HttpClient);
+  save(update: LabelUpdate, experimentId?: string): Promise<LabelOutcome>;
+  saveAll(updates: LabelUpdate[], experimentId?: string): Promise<LabelOutcome[]>;
+  skip(target: LabelTarget & {
+    annotation?: string;
+  }, experimentId?: string): Promise<LabelOutcome>;
+  /**
+   * Record that the evidence does not show the part of the run this assertion
+   * checks, so there was nothing to judge. Counted as a fail in every pass
+   * rate, but stored and read back as an abstention, apart from a fail. Pass
+   * `annotation` to say what the evidence would have had to show.
+   */
+  abstain(target: LabelTarget & {
+    annotation?: string;
+  }, experimentId?: string): Promise<LabelOutcome>;
+  archive(target: ArchiveLabelTarget, experimentId?: string): Promise<LabelOutcome>;
+  saveHuman(update: HumanLabelUpdate): Promise<HumanLabelOutcome>;
+  saveHumanAll(updates: HumanLabelUpdate[]): Promise<HumanLabelOutcome[]>;
+  get(traceId: string): Promise<TraceLabels | null>;
+  getAll(traceIds: string[]): Promise<TraceLabels[]>;
+  /** Generate suggested evidence for an assertion on an original or replay trace. */
+  generateLabelEvidence(traceId: string, assertionId: string): Promise<AssertionLabelEvidence[]>;
+}
+//#endregion
+//#region src/graders.d.ts
+type GraderLabelSource = "human" | "live_grader";
+type GraderLabel = {
+  traceId: string;
+  graderId: string;
+  graderName: string | null;
+  graderStatus: string;
+  graderType: string;
+  label: boolean | null;
+  labelReason: string | null;
+  failureDiagnostic: string | null;
+  labelConfidence: LabelConfidence | null;
+  source: GraderLabelSource;
+  evaluatedAt: string | null;
+};
+type GetGraderLabelsParams = {
+  traceIds?: string[];
+  graderId?: string;
+  limit?: number;
+};
+type GraderLabelUpdate = {
+  graderId: string;
+  traceId: string;
+  label: boolean;
+  reason?: string;
+  failureDiagnostic?: string;
+  confidence?: LabelConfidence;
+};
+type GraderLabelOutcome = {
+  graderId: string;
+  traceId: string;
+  label: boolean;
+  action: "set";
+};
+declare class GradersClient {
+  private readonly httpClient;
+  constructor(httpClient: HttpClient);
+  getLabels(params: GetGraderLabelsParams): Promise<GraderLabel[]>;
+  saveLabel(update: GraderLabelUpdate): Promise<GraderLabelOutcome>;
+  saveLabelAll(updates: GraderLabelUpdate[]): Promise<GraderLabelOutcome[]>;
+}
+//#endregion
+//#region src/langgraph.d.ts
+interface ActiveSpanContext$1 {
+  traceId: string;
+  spanId: string;
+}
+/**
+ * LangChain/LangGraph callback handler that sends traces to Bitfab.
+ *
+ * Duck-typed to match LangChain.js's BaseCallbackHandler, so no
+ * `@langchain/core` dependency is required. Pass as a callback:
+ *
+ * ```typescript
+ * const handler = bitfab.getLangGraphCallbackHandler("my-agent");
+ * const result = await agent.invoke(
+ *   { messages: [...] },
+ *   { callbacks: [handler] },
+ * );
+ * ```
+ */
+declare class BitfabLangGraphCallbackHandler {
+  name: string;
+  ignoreRetry: boolean;
+  ignoreRetriever: boolean;
+  ignoreCustomEvent: boolean;
+  private readonly httpClient;
+  private readonly ownsHttpClient;
+  private readonly traceFunctionKey;
+  private readonly getActiveSpanContext;
+  private readonly shouldRecord;
+  private readonly captureTools;
+  private runToSpan;
+  private invocations;
+  constructor(config: {
+    apiKey?: ApiKeyInput;
+    traceFunctionKey: string;
+    serviceUrl?: string;
+    timeout?: number;
+    getActiveSpanContext?: () => ActiveSpanContext$1 | null;
+    shouldRecord?: () => boolean;
+    /** Whether callback tool events should emit spans. Defaults to true. */
+    captureTools?: boolean;
+    /**
+     * The owning `Bitfab` client's HTTP client. Supplied by
+     * `getLangGraphCallbackHandler()` so this handler shares that client's
+     * single span-transport worker instead of starting a second one.
+     * @internal
+     */
+    _httpClient?: HttpClient;
+  });
+  /**
+   * Flush and release the span transport this handler started. A no-op when
+   * the handler borrowed a `Bitfab` client's HTTP client: that client's
+   * `close()` owns the worker's lifetime.
+   */
+  close(timeoutMs?: number): Promise<boolean>;
+  private startSpan;
+  private completeSpan;
+  private sendSpan;
+  private sendTraceCompletion;
+  private sendTraceStart;
+  handleChainStart(chain: Record<string, unknown> | null | undefined, inputs: Record<string, unknown>, runId: string, parentRunIdOrRunType?: string, tags?: string[], metadata?: Record<string, unknown>, runTypeOrRunName?: string, runNameOrParentRunId?: string): Promise<void>;
+  handleChainEnd(outputs: Record<string, unknown>, runId: string): Promise<void>;
+  handleChainError(error: unknown, runId: string): Promise<void>;
+  handleChatModelStart(llm: Record<string, unknown> | null | undefined, messages: unknown[][], runId: string, parentRunId?: string, _extraParams?: Record<string, unknown>, tags?: string[], metadata?: Record<string, unknown>, runName?: string): Promise<void>;
+  handleLLMStart(llm: Record<string, unknown> | null | undefined, prompts: string[], runId: string, parentRunId?: string, _extraParams?: Record<string, unknown>, tags?: string[], metadata?: Record<string, unknown>, runName?: string): Promise<void>;
+  handleLLMEnd(output: Record<string, unknown>, runId: string): Promise<void>;
+  handleLLMError(error: unknown, runId: string): Promise<void>;
+  handleLLMNewToken(): Promise<void>;
+  handleToolStart(tool: Record<string, unknown> | null | undefined, input: string, runId: string, parentRunId?: string, tags?: string[], metadata?: Record<string, unknown>, runName?: string): Promise<void>;
+  handleToolEnd(output: unknown, runId: string): Promise<void>;
+  handleToolError(error: unknown, runId: string): Promise<void>;
+  handleRetrieverStart(retriever: Record<string, unknown> | null | undefined, query: string, runId: string, parentRunId?: string, tags?: string[], metadata?: Record<string, unknown>, runName?: string): Promise<void>;
+  handleRetrieverEnd(documents: unknown, runId: string): Promise<void>;
+  handleRetrieverError(error: unknown, runId: string): Promise<void>;
+}
+//#endregion
+//#region src/langgraphIntegration.d.ts
+interface SpanClient {
+  withSpan<TArgs extends unknown[], TReturn>(traceFunctionKey: string, options: {
+    name?: string;
+    type?: "agent" | "function";
+    captureWhen?: "always" | "nested";
+    mockOnReplay?: boolean;
+    finalize?: (result: unknown) => unknown | Promise<unknown>;
+    surface?: "inherit";
+    instrumentation?: "langgraph";
+  }, fn: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
+}
+interface LangGraphTool {
+  readonly name?: string;
+  invoke(input: unknown, ...rest: unknown[]): unknown;
+}
+interface ConfiguredLangGraphRunnable<TInput, TConfig, TReturn> {
+  invoke(input: TInput, config?: TConfig): TReturn;
+}
+interface LangGraphRunnable<TInput, TConfig, TReturn> {
+  withConfig(config: {
+    callbacks: unknown[];
+  }): ConfiguredLangGraphRunnable<TInput, TConfig, TReturn>;
+}
+/**
+ * Options for first-class LangGraph ToolNode replay interception.
+ *
+ * @experimental This API may change before it is stable.
+ */
+interface LangGraphIntegrationOptions {
+  /**
+   * Tools marked for recorded-output mocking under replay's default
+   * `mock: "marked"` strategy. Defaults to every wrapped tool. Pass a list to
+   * mark only those tool names, or `false` to require `mock: "all"` or an
+   * override.
+   */
+  mockToolsOnReplay?: boolean | readonly string[];
+}
+/**
+ * First-class LangGraph integration for callback tracing and replayable
+ * `ToolNode` tools.
+ *
+ * @experimental This API may change before it is stable.
+ */
+declare class BitfabLangGraphIntegration {
+  /** Callback handler for the compiled graph's invocation config. */
+  readonly callbackHandler: any;
+  private readonly client;
+  private readonly traceFunctionKey;
+  private readonly mockToolsOnReplay;
+  constructor(config: {
+    client: SpanClient;
+    traceFunctionKey: string;
+    callbackHandler: BitfabLangGraphCallbackHandler;
+    options?: LangGraphIntegrationOptions;
+  });
+  /**
+   * Wrap tools before passing the same returned array to both
+   * `model.bindTools()` and `new ToolNode()`. Each invocation becomes an
+   * independently mockable child span.
+   */
+  wrapTools<T extends readonly LangGraphTool[]>(tools: T): T;
+  /**
+   * Create the normal graph entry point. The returned function adds Bitfab's
+   * callback handler, preserves invocation config, and records only the graph
+   * input as the replayable root input.
+   *
+   * @experimental This API may change before it is stable.
+   */
+  createInvoker<TInput, TConfig, TReturn>(graph: LangGraphRunnable<TInput, TConfig, TReturn>): (input: TInput, config?: TConfig) => TReturn;
+  private wrapTool;
+  private assertReplayToolResultExists;
+  /** Wrap the function that invokes the compiled graph as the replay root. */
+  wrapInvoke<TArgs extends unknown[], TReturn>(fn: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
+}
+//#endregion
+//#region src/openaiAgentSdk.d.ts
+/**
+ * OpenAI Agents SDK handler for Bitfab tracing.
+ *
+ * The OpenAI Agents SDK is instrumented in two layers:
+ *
+ *   1. A process-wide `TracingProcessor` (see `getOpenAiTracingProcessor` /
+ *      `BitfabOpenAITracingProcessor`) registered once with `addTraceProcessor`.
+ *      It captures everything *inside* a run - LLM calls, tool calls, handoffs -
+ *      as Bitfab spans.
+ *   2. This handler's `wrapRun`, which owns the *root*. The processor never sees
+ *      the caller's input (the SDK's trace events don't carry it), so a
+ *      processor-only run records a root span with an empty input and is not
+ *      replayable. `wrapRun` is a thin drop-in for `run()` that opens a
+ *      `withSpan` root carrying the input and final output, so the run is
+ *      replayable with no hand-written `withSpan`. The processor's spans nest
+ *      underneath it automatically (it remaps onto the active span context).
+ *
+ * When `wrapRun` runs inside an enclosing Bitfab span (the replay auto-wrap, or
+ * a caller's own `withSpan`), that span is already the replayable root: the
+ * handler skips opening a second one and lets the processor nest the run's spans
+ * under the existing root. This mirrors the Claude Agent SDK and LangGraph
+ * handlers, which no-op their root span under an enclosing span, and keeps a
+ * replayed run's span tree identical to the original (no doubled root agent
+ * span).
+ *
+ * Use both together: register the processor once at startup, then call
+ * `handler.wrapRun(agent, input)` instead of `run(agent, input)`.
+ */
+type AgentLike = any;
+type RunInput = string | unknown[] | Record<string, unknown>;
+type RunOptions = {
+  stream?: boolean;
+} & Record<string, unknown>;
+type RunResultLike = {
+  finalOutput?: unknown;
+  completed?: Promise<void>;
+};
+type RootSpanOptions = {
+  type: "agent";
+  finalize: (result: unknown) => unknown | Promise<unknown>;
+  surface: "inherit";
+  instrumentation: "openai-agents";
+};
+type WithSpanFn = <TArgs extends unknown[], TReturn>(traceFunctionKey: string, options: RootSpanOptions, fn: (...args: TArgs) => TReturn) => (...args: TArgs) => TReturn;
+type GetActiveSpanContextFn = () => unknown | null;
+/**
+ * OpenAI Agents SDK handler that records a replayable root span around a run.
+ *
+ * ```typescript
+ * import { Bitfab } from "@bitfab/sdk";
+ * import { addTraceProcessor, Agent, run } from "@openai/agents";
+ *
+ * const bitfab = new Bitfab({ apiKey: "..." });
+ * addTraceProcessor(bitfab.getOpenAiTracingProcessor()); // captures internals
+ *
+ * const agent = new Agent({ name: "Researcher", instructions: "..." });
+ * const handler = bitfab.getOpenAiAgentHandler("research-topic");
+ *
+ * // Swap run(agent, input) -> handler.wrapRun(agent, input)
+ * const result = await handler.wrapRun(agent, "Find X");
+ * return result.finalOutput;
+ * ```
+ */
+declare class BitfabOpenAIAgentHandler {
+  private readonly traceFunctionKey;
+  private readonly withSpanFn;
+  private readonly getActiveSpanContext?;
+  constructor(config: {
+    traceFunctionKey: string;
+    withSpan: WithSpanFn;
+    getActiveSpanContext?: GetActiveSpanContextFn;
+  });
+  /**
+   * Drop-in replacement for the OpenAI Agents SDK's `run()` that records a
+   * replayable root `agent` span.
+   *
+   * The `input` is captured as the root span's input (as a single positional
+   * argument, so `replay(key, fn)` re-feeds it), and the run's `finalOutput`
+   * is recorded as the root output. For streaming runs (`{ stream: true }`),
+   * the result is handed back immediately and the final output is recorded
+   * once the stream completes - first-byte latency is untouched.
+   *
+   * The process-wide tracing processor (`getOpenAiTracingProcessor`) must still
+   * be registered: it captures the LLM/tool/handoff spans that nest beneath
+   * this root.
+   */
+  wrapRun(agent: AgentLike, input: RunInput, options?: RunOptions): Promise<RunResultLike>;
+}
+//#endregion
+//#region src/organizationMembers.d.ts
+type OrganizationMember = {
+  id: string;
+  fullName: string | null;
+  email: string | null;
+  imageUrl: string | null;
+};
+/** The people in the API key's organization. */
+declare class OrganizationMembersClient {
+  private readonly httpClient;
+  constructor(httpClient: HttpClient);
+  /**
+   * List the organization's members, ordered by name. Read it to find the
+   * address to pass as an assertion's `assigneeEmail`.
+   */
+  list(): Promise<OrganizationMember[]>;
+}
+//#endregion
+//#region src/replayInterrupt.d.ts
+type ReplayInterruptSignal = "SIGINT" | "SIGTERM";
+interface ReplayInterrupt {
+  experimentId: string;
+  experimentUrl: string;
+  signal: ReplayInterruptSignal;
+  markedInterrupted: boolean;
+}
+//#endregion
+//#region src/replay.d.ts
+type MockStrategy = "none" | "all" | "marked";
+type TraceIngestionType = "captured" | "seeded";
+/**
+ * How the DB-snapshot branch each replay item runs against is sized and warmed.
+ *
+ * Every field is optional, so this object is only worth passing when you want
+ * to override the mirror project's own sizing. To branch with those defaults,
+ * pass `dbBranch: true` instead of an empty object.
+ */
+interface DbBranchOptions {
+  /**
+   * Autoscaling floor for the branch's compute, in Neon Compute Units (0.25 to
+   * 56). Omit to keep the mirror project's own default. Raise it when the
+   * mirror is provisioned smaller than the database it stands in for, so
+   * replay latency reflects your code rather than a cold, undersized branch.
+   */
+  minCu?: number;
+  /**
+   * Autoscaling ceiling for the branch's compute, in Neon Compute Units.
+   * Setting it equal to `minCu` pins the size, which keeps items comparable:
+   * otherwise a later item can run against an endpoint that has already
+   * scaled up and post a better number for the same code.
+   */
+  maxCu?: number;
+  /**
+   * SQL that warms the branch's cache. The server appends it to the branch's
+   * readiness check, so it runs BEFORE your function sees the branch and its
+   * time is not charged to the replayed call. Invalid SQL fails the branch
+   * rather than silently leaving it cold.
+   */
+  warmupSql?: string;
+}
+interface ReplayOptions {
+  /**
+   * Experimental selective replay. Explicit required nodes
+   * always execute; eligible output-only nodes reuse JSON recordings only
+   * when runtime inputs match. Requires a compatible server, mock: "marked",
+   * and no mock overrides or resume. Does not infer changes from codeChangeFiles.
+   * The server reads active/inherited assertions and protects their scoped
+   * execution evidence. Coverage in item.selectiveReplay is not a verdict.
+   */
+  experimentalSelectiveReplay?: SelectiveReplayOptions;
+  /**
+   * Maximum number of traces to replay (1-5,000, default 5). Ignored when
+   * `traceIds` is passed (with a warning), or when `datasetId` / `datasetIds`
+   * is passed, because either source already determines how many traces replay.
+   * To replay part of a dataset selection, name the members to run in
+   * `traceIds` rather than bounding it here.
+   */
+  limit?: number;
+  attempts?: number;
+  /**
+   * Optional list of specific trace IDs to replay (max 100). Passed alongside
+   * `datasetId` or `datasetIds` it pins which members of that selection replay,
+   * and the server rejects any ID none of those datasets contains. On its own
+   * it selects by ID with no dataset attribution.
+   */
+  traceIds?: string[];
+  /**
+   * 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;
+  metadata?: Record<string, string>;
+  /** Positive integer limiting parallel items. Set to 1 for sequential. Default 10. */
+  maxConcurrency?: number;
+  /**
+   * Description of the code change being tested in this replay. Stored on
+   * the resulting experiment so the change can be reviewed alongside results.
+   * Supplying a description without `codeChangeFiles` preserves this text
+   * while the SDK automatically captures the files.
+   * Pass `null` when the replay should have no description; use
+   * `codeChangeFiles: null` to suppress automatic file capture.
+   */
+  codeChangeDescription?: string | null;
+  /**
+   * Files edited as part of this code change. Each entry holds the file path
+   * and the full `before`/`after` contents. The agent reads each file before
+   * and after editing and passes the two strings. Use `""` for newly created
+   * files (`before`) or deleted files (`after`). Omit this field to capture
+   * automatically, or pass `null` to suppress file capture for this replay.
+   */
+  codeChangeFiles?: CodeChangeFile[] | null;
+  /**
+   * Mock strategy for child spans during replay.
+   * - "marked": only spans tagged with { mockOnReplay: true } in SpanOptions are mocked (default)
+   * - "none": everything runs real code
+   * - "all": every matched recorded child withSpan returns historical output;
+   *   a missing occurrence fails the replay item closed
+   */
+  mock?: MockStrategy;
+  /**
+   * Selective mock overrides: inject custom values into specific spans during
+   * replay, so downstream real code runs against the substituted output. Each
+   * Pass `{ match, value }` pairs, or one resolver invoked for every child span.
+   * A resolver can route on `ctx.node.traceFunctionKey` and return
+   * `NO_MOCK_OVERRIDE` to continue to the next override and base strategy.
+   * Per-call overrides take precedence over registrations on the client.
+   */
+  mockOverride?: MockOverrideInput | MockOverrideInput[];
+  /**
+   * Run each item against a database branch restored to the state its source
+   * trace saw. Pass `true` to branch with the mirror project's own sizing, or a
+   * {@link DbBranchOptions} object to tune how each branch is sized and warmed.
+   * `false` and omission leave branching off. Inside `fn`, read the resolved
+   * branch with `getCurrentReplayBranch()`.
+   *
+   * Items whose source trace carried no DB snapshot reference get no branch and
+   * use the app's normal database path. Unsafe calls on that path still require
+   * replay mocking. An item whose branch was requested but could not be resolved
+   * fails instead of running, so replay never silently reports a result that did
+   * not use the historical data you asked for.
+   */
+  dbBranch?: DbBranchOptions | boolean;
+  /**
+   * Experiment group this replay joins, shown together on the experiments
+   * page. An ID with no group yet creates the group.
+   */
+  experimentGroupId?: string;
+  /**
+   * Name for the experiment group in `experimentGroupId`. Applied when this
+   * replay creates the group, or when the group exists without a name. A group
+   * that already has a name keeps it. Requires `experimentGroupId`.
+   */
+  experimentGroupName?: string;
+  /**
+   * Dataset this replay runs against. Mutually exclusive with `datasetIds`.
+   * Alone it replays the dataset's full membership, and with `traceIds` it
+   * replays only those members. When set, the resulting experiment is
+   * durably attributed to the dataset (stored on the experiment), so it appears
+   * under the dataset's experiments even if the trace lineage can't be
+   * reconstructed. Validated server-side against the org.
+   */
+  datasetId?: string;
+  datasetIds?: string[];
+  /**
+   * Graders to attach directly to this experiment, independent of any
+   * graders already on the dataset. The resulting experiment is graded by the
+   * union of these and the dataset's runnable graders at completion, so use this
+   * to grade a single run with a check you don't want to add to the dataset
+   * permanently. Each id must be an active/live grader belonging to the same
+   * organization and trace function, otherwise the server rejects the replay.
+   */
+  graderIds?: string[];
+  /**
+   * Replay only the selected traces that carry at least one approved assertion.
+   *
+   * Narrows whatever `limit`, `traceIds` or `datasetIds` selected, so a run that
+   * measures assertion outcomes does not pay to re-execute traces nothing can
+   * grade. The server applies it as part of selection, which is what makes it
+   * compose with `limit`: `{ limit: 10, onlyWithAssertions: true }` is the ten
+   * most recent traces that HAVE approved assertions, not the ten most recent
+   * filtered down to however few do. An archived assertion does not count, and
+   * neither does one still awaiting review: a replay is only ever judged
+   * against assertions a person has approved, so a trace carrying nothing but
+   * drafts has nothing here to measure. A selection that narrows to nothing
+   * replays nothing.
+   */
+  onlyWithAssertions?: boolean;
+  skipAssertionJudging?: boolean;
+  judgeAssertions?: boolean;
+  /**
+   * Reshape recorded inputs before they are spread into `fn`.
+   *
+   * Replay pulls each trace's inputs exactly as they were captured against the
+   * function's signature AT TRACE TIME. When the function's shape has since
+   * changed (params renamed, reordered, collapsed into an options object, etc.),
+   * the recorded inputs no longer line up and `fn(...inputs)` throws. This hook
+   * lets a caller map the recorded inputs onto the current signature so replay
+   * can still run.
+   *
+   * Receives the deserialized recorded inputs and a per-trace {@link AdaptContext}
+   * (so a table-driven adapter can look up the adapted inputs by `traceId`), and
+   * returns the array actually spread into `fn`. The returned array is also what
+   * `ReplayItem.input` reports, so the experiment shows what was really run.
+   *
+   * Runs per item, inside the same try/catch as `fn`: if the adapter throws, the
+   * failure is surfaced on that item's `error` rather than crashing the run.
+   * Omit it to spread the recorded inputs unchanged.
+   */
+  adaptInputs?: (inputs: unknown[], ctx: AdaptContext) => unknown[];
+  /**
+   * Resolve every item's inputs and stop, without calling the function.
+   *
+   * Selection, span fetch, deserialization, and `adaptInputs` all run, so each
+   * item reports the exact arguments the function would have received. Nothing
+   * executes and no replay traces are produced, which is the cheap way to check
+   * that recorded inputs still fit the current signature. No experiment is
+   * created either, so the result's `experimentId` and `experimentUrl` are null
+   * and `onExperimentStart` is not called.
+   */
+  dryRun?: boolean;
+  /**
+   * Called once per item as it finishes, in completion order (not input
+   * order), with running totals for the whole run. Use it to render replay
+   * progress, for example a terminal progress bar. Replay does not know
+   * pass/fail at this point (verdicts are assigned later), so the totals only
+   * distinguish items whose function ran (`succeeded`) from items that threw
+   * (`errored`).
+   *
+   * Invoked synchronously right after each item finishes, so keep it cheap. A
+   * throwing callback never crashes the run: the error is swallowed so progress
+   * UI can't break replay.
+   */
+  onItemFinish?: (progress: ReplayItemFinishProgress) => void;
+  /**
+   * @deprecated Use {@link onItemFinish}. This compatibility callback receives
+   * the same per-item finish events plus the legacy whole-run `"complete"`
+   * event. It is ignored when `onItemFinish` is also provided.
+   */
+  onProgress?: (progress: ReplayProgress) => void;
+  /**
+   * Called once when each replay item begins processing, before input loading,
+   * mock preparation, database branching, or the customer function runs. Use
+   * it with {@link onItemFinish} to distinguish queued items from items that
+   * are still in flight. A throwing callback never crashes the run.
+   */
+  onItemStart?: (progress: ReplayItemStartProgress) => void;
+  /**
+   * Called once, right after the server creates the experiment and before any
+   * item runs, with the experiment ID and its dashboard URL. Use it to show
+   * where results will appear while the replay is still running. A throwing
+   * callback never crashes the run.
+   */
+  onExperimentStart?: (experiment: ReplayExperiment) => void;
+  onInterrupt?: (interrupt: ReplayInterrupt) => void;
+  resume?: string;
+  force?: boolean;
+}
+/** The experiment a replay records into, passed to {@link ReplayOptions.onExperimentStart}. */
+interface ReplayExperiment {
+  /** Experiment ID created for this replay. */
+  experimentId: string;
+  /** Full URL to view the experiment in the dashboard. */
+  experimentUrl: string;
+}
+/** Emitted through {@link ReplayOptions.onItemStart} when a worker starts an item. */
+interface ReplayItemStartProgress {
+  type: "started";
+  /** Experiment ID created for this replay. Null for a dry run, which creates none. */
+  experimentId: string | null;
+  /** @deprecated Use {@link experimentId}. Same value. */
+  testRunId: string | null;
+  /** Items whose processing has started so far. */
+  started: number;
+  /** Items that have finished so far, whether they succeeded or errored. */
+  completed: number;
+  /** Total number of items in this replay run. */
+  total: number;
+  /** Of the completed items, how many finished without a code or replay error. */
+  succeeded: number;
+  /** Of the completed items, how many finished with an error. */
+  errored: number;
+  /** The historical trace and span whose replay processing just started. */
+  item: {
+    originalTraceId: string;
+    originalSpanId: string;
+    /** @deprecated alias for `originalTraceId`. */
+    sourceTraceId: string;
+    /** @deprecated alias for `originalSpanId`. */
+    sourceSpanId: string;
+    attempt: number;
+  };
+}
+/** Running totals reported to {@link ReplayOptions.onItemFinish} as replay proceeds. */
+interface ReplayItemFinishProgress {
+  /** Event kind, omitted for backward-compatible per-item events. */
+  type?: "item";
+  /** Experiment ID created for this replay. Null for a dry run, which creates none. */
+  experimentId: string | null;
+  /** @deprecated Use {@link experimentId}. Same value. */
+  testRunId: string | null;
+  /** Items that have finished so far, whether they succeeded or errored. */
+  completed: number;
+  /** Total number of items in this replay run. */
+  total: number;
+  /** Of the completed items, how many finished without a code or replay error. */
+  succeeded: number;
+  /** Of the completed items, how many have `item.error` set. */
+  errored: number;
+  /**
+   * The single item that just finished to produce this event. Field-for-field
+   * the same shape and meaning as {@link ReplayItem}, so a progress UI and a
+   * final-result UI read one contract. `traceId` is null at this stage (the
+   * server replay id arrives at completion), and `tokens` is null for the same
+   * reason: the replayed run's usage is aggregated server-side by
+   * completeReplay. `durationMs` is how long this item took to replay; the
+   * `original*` fields describe the trace it replayed.
+   */
+  item: ReplayProgressItem;
+}
+/** See {@link ReplayItemFinishProgress.item}. Mirrors {@link ReplayItem}. */
+interface ReplayProgressItem {
+  selectiveReplay?: SelectiveReplayReport;
+  /** Trace ID of the new replay trace (null during the run; the server id arrives at completion). */
+  traceId?: string | null;
+  /** Bitfab trace ID of the original (historical) trace being replayed. */
+  originalTraceId: string | null;
+  /** External span ID the recorded inputs were read from (the original root span). */
+  originalSpanId?: string | null;
+  /** @deprecated alias for `originalTraceId`. */
+  sourceTraceId: string | null;
+  /** @deprecated alias for `originalSpanId`. */
+  sourceSpanId?: string | null;
+  attempt: number;
+  /** Deserialized inputs from the original trace. */
+  input?: unknown[];
+  /** The result returned by the replayed function, or undefined on error. */
+  result?: unknown;
+  /** The original output from the historical trace. */
+  originalOutput?: unknown;
+  /** Backward-compatible message for either error kind. */
+  error: string | null;
+  /** The actual value thrown by the replayed customer function. */
+  traceError?: unknown | null;
+  /** The actual value thrown while Bitfab prepared this replay item. */
+  replayError?: unknown | null;
+  /** How long the replayed function took on this run. */
+  durationMs?: number | null;
+  /** The original trace's duration, tokens, and model. */
+  originalDurationMs?: number | null;
+  originalTokens?: TokenUsage | null;
+  originalModel?: string | null;
+  ingestionType?: TraceIngestionType;
+  /** Always null here: the replayed run's usage is only known at completion. */
+  tokens?: TokenUsage | null;
+  /** @deprecated renamed to `originalModel`. */
+  model?: string | null;
+  dbSnapshotRef?: DbSnapshotRef | null;
+  dbBranchTimings?: DbBranchTimings | null;
+}
+/**
+ * @deprecated Use {@link ReplayItemFinishProgress}. This legacy shape also
+ * represents the item-less terminal `"complete"` event emitted by
+ * {@link ReplayOptions.onProgress}.
+ */
+interface ReplayProgress {
+  type?: "item" | "complete";
+  result?: ReplayResult<unknown>;
+  /** Null for a dry run, which creates no experiment. */
+  experimentId?: string | null;
+  /** @deprecated Use {@link experimentId}. Same value. */
+  testRunId?: string | null;
+  completed: number;
+  total: number;
+  succeeded: number;
+  errored: number;
+  item?: ReplayItemFinishProgress["item"];
+}
+/**
+ * Wire prefix the Bitfab plugin scans for. Each line {@link reportReplayProgress}
+ * writes is this prefix followed by the JSON of the running totals (plus the
+ * finished `item`). The plugin polls these lines to report live progress while a
+ * replay runs in the background; keep the SDK emitter and the plugin parser in
+ * sync.
+ */
+declare const BITFAB_PROGRESS_PREFIX = "@@bitfab:progress ";
+/**
+ * A ready-made replay lifecycle callback for replay scripts.
+ * Pass it straight in:
+ *
+ * ```ts
+ * await bitfab.replay("my-fn", fn, {
+ *   limit,
+ *   onItemStart: reportReplayProgress,
+ *   onItemFinish: reportReplayProgress,
+ * })
+ * ```
+ *
+ * It writes `@@bitfab:progress` lines to stderr, which the Bitfab plugin polls
+ * to report in-flight and finished items while replay runs in the background,
+ * so scripts never hand-format the wire protocol.
+ * stdout is left untouched for direct-run ReplayResult JSON. Outside Node (no
+ * `process.stderr`, e.g. a browser) it is a no-op, and a write failure is
+ * swallowed so progress can never crash a run.
+ */
+declare function reportReplayProgress(progress: ReplayItemFinishProgress | ReplayItemStartProgress | ReplayProgress): void;
+/** Per-trace context passed to {@link ReplayOptions.adaptInputs}. */
+interface AdaptContext {
+  /** Bitfab trace ID of the original (historical) trace being replayed. */
+  originalTraceId: string;
+  /** External span ID the recorded inputs were read from. */
+  originalSpanId: string;
+  /** @deprecated alias for {@link AdaptContext.originalTraceId}. */
+  sourceTraceId: string;
+  /** @deprecated alias for {@link AdaptContext.originalSpanId}. */
+  sourceSpanId: string;
+  metadata: Record<string, unknown>;
+}
+/**
+ * The shape an adapter module must export as `adaptInputs`.
+ *
+ * Author an adapter in its own file (e.g. `scripts/replay-adapters/<name>.ts`),
+ * import it in your replay script, and pass it to `replay({ adaptInputs })`:
+ *
+ * ```ts
+ * import type { AdaptInputsFn } from "@bitfab/sdk"
+ * export const adaptInputs: AdaptInputsFn = (inputs, ctx) => [reshape(inputs)]
+ * ```
+ */
+type AdaptInputsFn = (inputs: unknown[], ctx: AdaptContext) => unknown[];
+interface ReplayItem<T> {
+  /** Decisions and changed-code coverage for experimental selective replay. */
+  selectiveReplay?: SelectiveReplayReport;
+  /**
+   * Server trace ID of the new replay trace this item produced. Written in by
+   * `replay()` from the complete-replay response once the server has minted the
+   * trace row; the client-side id used to correlate spans during the run is
+   * never surfaced here. Null until completion, on older servers that omit the
+   * mapping, or if the item produced no trace. Not the verdict-persistence key:
+   * that is the original-trace lineage (`originalTraceId` + `experimentId`).
+   */
+  traceId: string | null;
+  /** Bitfab trace ID of the original (historical) trace being replayed. */
+  originalTraceId: string;
+  /** External span ID the recorded inputs were read from (the original root span). */
+  originalSpanId: string;
+  /** @deprecated alias for {@link ReplayItem.originalTraceId}. */
+  sourceTraceId: string;
+  /** @deprecated alias for {@link ReplayItem.originalSpanId}. */
+  sourceSpanId: string;
+  attempt: number;
+  /** Deserialized inputs from the original trace. */
+  input: unknown[];
+  /** The result returned by the function during replay, or undefined on error. */
+  result: T | undefined;
+  originalOutput: unknown;
+  /**
+   * How the source trace came to exist. Absent on servers that predate the
+   * field, which only ever served captured traces.
+   */
+  ingestionType?: TraceIngestionType;
+  /**
+   * Backward-compatible message for either error kind. Prefer `traceError` and
+   * `replayError` when callers need the original exception and its source.
+   */
+  error: string | null;
+  /** The actual value thrown by the replayed customer function. */
+  traceError: unknown | null;
+  /**
+   * The actual value thrown by replay setup before the customer function ran,
+   * such as database warmup, input hydration, or mock preparation.
+   */
+  replayError: unknown | null;
+  /**
+   * How long the replayed function took on this run, in ms. Null if the item
+   * failed before it ran. Compare against
+   * {@link ReplayItem.originalDurationMs} for the before/after.
+   */
+  durationMs: number | null;
+  /** The original trace's duration in ms, or null if its timestamps are missing. */
+  originalDurationMs: number | null;
+  /**
+   * Token usage recorded on the original trace, or null if it captured none.
+   * The "old" side of a token delta; {@link ReplayItem.tokens} is the new one.
+   */
+  originalTokens: TokenUsage | null;
+  /** Model name from the original trace, or null if not captured. */
+  originalModel: string | null;
+  /**
+   * Token usage from the REPLAYED run (this item's new execution), aggregated
+   * server-side from the spans it produced, or null if the run captured no
+   * token data. Compare against {@link ReplayItem.originalTokens} to see how
+   * the code change moved cost. Matches what the experiments page shows.
+   *
+   * Unprefixed because the replay is this item's subject: anything describing
+   * the trace being replayed carries `original`.
+   */
+  tokens: TokenUsage | null;
+  /** @deprecated renamed to {@link ReplayItem.originalModel}. */
+  model: string | null;
+  /**
+   * The DB snapshot ref the SDK captured at trace open. Useful for debugging
+   * ("what state was this trace pinned to?") and for customers building
+   * their own resolvers. Undefined when the source trace was captured
+   * without `dbSnapshot` configured.
+   */
+  dbSnapshotRef: DbSnapshotRef | null;
+  /**
+   * How long this item's DB branch took to provision, per phase, measured
+   * server-side. Present whenever a branch was attempted, on both outcomes:
+   * complete on success, partial up to the failing phase when the resolve
+   * failed. Null when no branch was asked for, when the source trace carried
+   * no snapshot ref, or against a server that predates timings.
+   */
+  dbBranchTimings: DbBranchTimings | null;
+  carriedOver?: boolean;
+}
+interface ReplayResult<T> {
+  /** Individual replay items with inputs, results, and comparison data. */
+  items: ReplayItem<T>[];
+  /**
+   * The experiment ID created on the server. Null for a dry run, which
+   * executes nothing and so creates no experiment.
+   */
+  experimentId: string | null;
+  /** Full URL to view the experiment in the dashboard. Null for a dry run. */
+  experimentUrl: string | null;
+  /** @deprecated Use {@link experimentId}. Same value. */
+  testRunId: string | null;
+  /** @deprecated Use {@link experimentUrl}. Same value. */
+  testRunUrl: string | null;
+  attempts: number;
+}
+/**
+ * Whole-run replay failure that preserves every item collected before the run
+ * failed. The original whole-run exception is available as `cause`.
+ */
+declare class ReplayError<T = unknown> extends BitfabError {
+  readonly items: ReplayItem<T>[];
+  readonly experimentId: string;
+  readonly experimentUrl: string;
+  readonly cause: unknown;
+  /** @deprecated Use {@link experimentId}. Same value. */
+  readonly testRunId: string;
+  /** @deprecated Use {@link experimentUrl}. Same value. */
+  readonly testRunUrl: string;
+  constructor(message: string, items: ReplayItem<T>[], experimentId: string, experimentUrl: string, cause: unknown);
+}
+/**
+ * A database branch requested for one replay item could not be resolved.
+ *
+ * The server's resolver code and message are retained as structured fields so
+ * callers can handle failures such as `branch_create_failed` and
+ * `snapshot_from_replaced_origin` without parsing the compatible `item.error`
+ * string.
+ */
+declare class DbBranchReplayError extends BitfabError {
+  readonly code: string;
+  readonly originalTraceId: string;
+  readonly cause?: unknown;
+  constructor(code: string, message: string, originalTraceId: string, cause?: unknown);
+}
+/**
+ * Serialize a replay result as JSON while retaining structured trace and replay
+ * errors. Use this for direct-run stdout instead of raw `JSON.stringify`, which
+ * drops the useful fields on JavaScript `Error` objects.
+ */
+declare function serializeReplayResult<T>(result: ReplayResult<T>): string;
+//#endregion
+//#region src/replayBranch.d.ts
+declare class ReplayBranch implements Omit<DbBranchLease, "databaseUrl"> {
+  #private;
+  /** The provider's own id for this branch, e.g. for correlating with its console. */
+  readonly neonBranchId: string;
+  /** Env var name the customer's app reads, e.g. `DATABASE_URL`. */
+  readonly envKey: string;
+  /** When this branch's URL stops being valid. ISO-8601. */
+  readonly expiresAt: string;
+  /**
+   * The instant this branch is pinned to: the source trace's wall clock, read
+   * just before the traced function ran. Compare it against the trace you meant
+   * to replay to confirm the branch is the right point in history.
+   */
+  readonly snapshotTimestamp?: string;
+  /** Deep link to the branch in the provider console, if available. */
+  readonly providerConsoleUrl?: string;
+  /**
+   * True if the branch is read-only. Use it to skip write operations during
+   * replay when the provider returned a read-only lease.
+   */
+  readonly readOnly?: boolean;
+  /**
+   * The branch's region, e.g. `aws-us-east-1`. A compute runs in its project's
+   * region, so a replay runner elsewhere pays that round trip on every query.
+   */
+  readonly region?: string;
+  /** The historical trace ID that produced the input for this replay item. */
+  readonly traceId: string;
+  /** @internal Built by `getCurrentReplayBranch()`; never constructed by callers. */
+  constructor(lease: DbBranchLease, traceId: string, context: ReplayContext);
+  /**
+   * Connection string for this item's branch. Point your database client at it
+   * instead of the live database for the duration of the replayed call.
+   *
+   * Reading it records on the trace that the replayed code obtained the branch
+   * URL, which is what separates "a branch was provisioned" from "the branch
+   * was actually used". The other fields inspect the lease without exposing the
+   * connection string, so they deliberately do not record anything. That is
+   * also why this is a getter and not a plain field: the URL is absent from
+   * `JSON.stringify(branch)` and from logging the object.
+   */
+  get databaseUrl(): string;
+}
+//#endregion
+//#region src/rivetIntegration.d.ts
+declare const RIVET_GROUP_EFFECT_METHODS: {
+  readonly db: readonly ["execute", "nativeMetrics", "close"];
+  readonly kv: readonly ["get", "put", "delete", "batchPut", "batchGet", "batchDelete", "deleteRange", "listPrefix", "listRange", "list"];
+  readonly schedule: readonly ["after", "at", "cancel", "get", "list"];
+  readonly cron: readonly ["set", "every", "get", "list", "delete", "history"];
+  readonly queue: readonly ["send", "next", "nextBatch", "waitForNames", "waitForAvailable", "complete", "enqueueAndWait", "tryNext", "tryNextBatch"];
+  readonly run: readonly ["setWakeAt"];
+};
+declare const RIVET_TOP_LEVEL_EFFECTS: readonly ["broadcast", "saveState", "sleep", "destroy", "step", "tryStep", "try", "loop", "sleepUntil", "rollbackCheckpoint", "join", "race", "removed", "getVersion"];
+type RivetGroup = keyof typeof RIVET_GROUP_EFFECT_METHODS;
+type RivetGroupEffectType = { [TGroup in RivetGroup]: `${TGroup}.${(typeof RIVET_GROUP_EFFECT_METHODS)[TGroup][number]}`; }[RivetGroup];
+/** Rivet context operations supported as replay effects. */
+type RivetEffectType = RivetGroupEffectType | (typeof RIVET_TOP_LEVEL_EFFECTS)[number] | "db.transaction.execute" | "queue.message.complete";
+/** Configuration for {@link BitfabRivetIntegration}. */
+interface RivetIntegrationOptions {
+  /**
+   * Context operations whose recorded outputs replay should serve instead of
+   * executing against a live actor or workflow. Nothing is marked by default.
+   */
+  mockOnReplay?: readonly RivetEffectType[];
+}
+/** Minimal structural context type used when callers do not supply Rivet's type. */
+interface RivetContextLike {
+  state: unknown;
+  readonly db: {
+    execute(...args: unknown[]): Promise<unknown>;
+  };
+  broadcast(name: string, ...args: unknown[]): void;
+  readonly actorId?: string;
+  readonly name?: string;
+  readonly key?: readonly string[];
+  readonly region?: string;
+}
+interface RivetIntegrationRuntime {
+  wrapEffect<TArgs extends unknown[], TReturn>(effect: RivetEffectType, mockOnReplay: boolean, fn: (...args: TArgs) => TReturn, replayOutput?: () => unknown): (...args: TArgs) => TReturn;
+  recordRootFixture(context: Record<string, unknown>, recordedRoots: Set<string>): void;
+}
+/**
+ * Binds a live Rivet actor or workflow context to an existing traced function
+ * and exposes replay-aware proxies for supported context operations.
+ *
+ * The integration never creates a trace root. Use it with the same
+ * `BitfabFunction` handle whose `withTrace()` wrapper is the production and
+ * replay root.
+ */
+declare class BitfabRivetIntegration<TContext extends object = RivetContextLike> {
+  private readonly traceFunctionKey;
+  private readonly runtime;
+  private readonly markedEffects;
+  private readonly replayProxies;
+  /** @internal Constructed by `Bitfab.getRivetIntegration()`. */
+  constructor(traceFunctionKey: string, runtime: RivetIntegrationRuntime, options?: RivetIntegrationOptions);
+  /**
+   * Run a callback with a live Rivet context bound to the current async chain.
+   * This binds context only; it creates no trace or span.
+   */
+  withContext<TReturn>(context: TContext, fn: () => TReturn): TReturn;
+  /**
+   * Adapt a traced function into a Rivet handler whose first argument is the
+   * live actor or workflow context. The context is not added to the traced
+   * root's inputs.
+   */
+  bind<This, TArgs extends unknown[], TReturn>(fn: (this: This, ...args: TArgs) => TReturn): (this: This, context: TContext, ...args: TArgs) => TReturn;
+  /**
+   * Return the current Rivet context proxy. In production it delegates to the
+   * bound live context. During replay it hydrates recorded actor state and
+   * intercepts supported effects without requiring a live Rivet actor or
+   * workflow.
+   */
+  getContext(): TContext;
+  private createContextProxy;
+  private createDbProxy;
+  private createGroupProxy;
+  private createMethodProxy;
+  private createEffect;
+  private createTransaction;
+  private decorateQueueMessages;
+  private decorateQueueMessage;
+  private queueCallIsCompletable;
+  private createQueueIterator;
+}
+//#endregion
+//#region src/spans.d.ts
+type SpanListField = "input" | "output" | "reasoning" | "content" | "errors" | "contexts";
+type SpanListParams = {
+  spanType?: SpanType;
+  spanName?: string;
+  fields?: SpanListField[];
+  cursor?: string | null;
+  /** Spans per page, 1 to 200, or at most 50 when `fields` is set. The server defaults to 50. */
+  limit?: number;
+};
+type ListedSpan = {
+  id: string;
+  traceId: string;
+  parentSpanId: string | null;
+  name: string | null;
+  type: string | null;
+  startedAt: string | null;
+  endedAt: string | null;
+  input?: unknown;
+  output?: unknown;
+  reasoning?: unknown;
+  content?: unknown;
+  errors?: unknown;
+  contexts?: unknown;
+};
+type SpanListResult = {
+  spans: ListedSpan[];
+  nextCursor: string | null;
+  hasMore: boolean;
+};
+declare class SpansClient {
+  private readonly httpClient;
+  constructor(httpClient: HttpClient);
+  /**
+   * List one trace's spans in the order they ran, one page at a time. No
+   * filter is required: omit `spanType` and `spanName` to page through every
+   * span. Each span carries one extra key per requested `fields` entry. Pass
+   * the returned `nextCursor` back as `cursor` for the next page. Throws a
+   * `BitfabError` with status 404 when the trace is not in your organization.
+   */
+  list(traceId: string, params?: SpanListParams): Promise<SpanListResult>;
+}
+//#endregion
+//#region src/tracing.d.ts
+interface Trace {
+  traceId: string;
+  toJSON(): unknown;
+}
+interface Span<_T = any> {
+  spanId?: string;
+  traceId?: string;
+  parentId?: string | null;
+  toJSON(): unknown;
+  spanData?: {
+    type?: string;
+    _input?: unknown;
+    _response?: unknown;
+  } | null;
+}
+interface TraceResponse {
+  traceId: string;
+  status: "success";
+}
+interface ActiveSpanContext {
+  traceId: string;
+  spanId: string;
+}
+/**
+ * TracingProcessor interface from OpenAI Agents SDK v0.3.7
+ */
+interface TracingProcessor {
+  onTraceStart(trace: Trace): Promise<void>;
+  onTraceEnd(trace: Trace): Promise<void>;
+  onSpanStart(span: Span<any>): Promise<void>;
+  onSpanEnd(span: Span<any>): Promise<void>;
+  forceFlush(): Promise<void>;
+  shutdown(timeout?: number): Promise<void>;
+}
+/**
+ * Tracing processor for OpenAI Agents SDK integration.
+ *
+ * Implements the TracingProcessor interface from the OpenAI Agents SDK to
+ * automatically capture traces and spans and send them to Bitfab for
+ * monitoring and analysis.
+ *
+ * Example usage:
+ * ```typescript
+ * import { Bitfab } from 'bitfab';
+ * import { addTraceProcessor } from '@openai/agents';
+ *
+ * const client = new Bitfab({ apiKey: 'your-api-key' });
+ * const processor = client.getOpenAiTracingProcessor();
+ * addTraceProcessor(processor);
+ * ```
+ */
+declare class BitfabOpenAITracingProcessor implements TracingProcessor {
+  private readonly httpClient;
+  private readonly ownsHttpClient;
+  private activeTraces;
+  private readonly getActiveSpanContext;
+  private readonly shouldRecord;
+  private activeSpanMappings;
+  private canonicalTraceIds;
+  private getCanonicalTraceId;
+  /**
+   * Initialize the tracing processor.
+   *
+   * @param config - Configuration options
+   */
+  constructor(config: {
+    apiKey?: ApiKeyInput;
+    serviceUrl?: string;
+    timeout?: number;
+    getActiveSpanContext?: () => ActiveSpanContext | null;
+    shouldRecord?: () => boolean;
+    /**
+     * The owning `Bitfab` client's HTTP client. Supplied by
+     * `getOpenAiTracingProcessor()` so this processor shares that client's
+     * single span-transport worker instead of starting a second one.
+     * @internal
+     */
+    _httpClient?: HttpClient;
+  });
+  /**
+   * Flush and release the span transport this processor started. A no-op when
+   * the processor borrowed a `Bitfab` client's HTTP client: that client's
+   * `close()` owns the worker's lifetime.
+   */
+  close(timeoutMs?: number): Promise<boolean>;
+  /**
+   * Called when a trace is started.
+   * If there's an active withSpan context, the trace ID is remapped to the
+   * outer trace and sent to pre-create the external_traces row on the server.
+   */
+  onTraceStart(trace: Trace): Promise<void>;
+  /**
+   * Called when a trace is ended.
+   * If mapped to a withSpan trace, sends with remapped ID and completed=false
+   * since the parent withSpan handles completion.
+   */
+  onTraceEnd(trace: Trace): Promise<void>;
+  private readonly startedSpans;
+  private readonly endedTraces;
+  private cleanupTrace;
+  /**
+   * Called when a span is started. Span payloads are authoritative completed
+   * snapshots, so start notifications do not cross the transport boundary.
+   */
+  onSpanStart(span: Span<any>): Promise<void>;
+  /**
+   * Called when a span is ended.
+   *
+   * Send the finalized span snapshot to Bitfab for complete trace capture.
+   */
+  onSpanEnd(span: Span<any>): Promise<void>;
+  /**
+   * Called when a trace is being flushed.
+   */
+  forceFlush(): Promise<void>;
+  /**
+   * Called when the trace processor is shutting down.
+   */
+  shutdown(timeout?: number): Promise<void>;
+  /**
+   * Send trace to Bitfab API (fire-and-forget).
+   * When traceIdOverride is provided, the trace ID is remapped to link
+   * the OpenAI trace into an outer withSpan trace.
+   */
+  private sendTrace;
+  /**
+   * Export span to JSON object, collecting any errors.
+   */
+  private exportSpan;
+  /**
+   * Extract and add input/response to serialized span, updating errors list.
+   */
+  private extractSpanInputResponse;
+  /**
+   * If the span's trace is mapped to a withSpan trace, rewrite trace_id and parent_id.
+   */
+  private applySpanOverrides;
+  /**
+   * Build span payload for the external spans API.
+   */
+  private buildSpanPayload;
+  /**
+   * Send span to Bitfab API (fire-and-forget).
+   * If the span belongs to a trace mapped to a withSpan trace, the trace_id
+   * and parent_id are rewritten to link the span into the withSpan tree.
+   */
+  private sendSpan;
+}
+//#endregion
+//#region src/captureSurface.d.ts
+type CaptureSurface = "opt-in" | "opt-out";
+//#endregion
+//#region src/client.d.ts
+/**
+ * Options for wrapBAML.
+ */
+interface WrapBAMLOptions {
+  /** Called after each BAML invocation with the Collector instance. */
+  onCollector?: (collector: unknown) => void;
+}
+/**
+ * A function returned by wrapBAML that exposes the BAML collector from the last call.
+ */
+interface WrappedBamlFn<TArgs extends unknown[], TReturn> {
+  (...args: TArgs): Promise<TReturn>;
+  /** The BAML Collector instance from the most recent call. `null` before the first call or if @boundaryml/baml is unavailable. */
+  collector: unknown | null;
+}
+/**
+ * A handle to the current active span, allowing context to be added.
+ */
+interface CurrentSpan {
+  /** The Bitfab ID for the current span. */
+  readonly id: string;
+  /** The trace ID for the current span. */
+  readonly traceId: string;
+  /**
+   * Add a context entry to this span. Each call appends to the contexts array.
+   * Context entries are stored in span_data.contexts as [{key, value}, ...].
+   */
+  addContext(context: Record<string, unknown>): void;
+  /**
+   * Set the prompt for this span. Stored in span_data.prompt.
+   * Calling multiple times overwrites the previous value.
+   */
+  setPrompt(prompt: string): void;
+}
+/**
+ * A detached handle to a previously-created trace, looked up by its
+ * canonical Bitfab trace ID.
+ *
+ * Unlike `getCurrentTrace()`, this handle is not tied to AsyncLocalStorage -
+ * each method sends to the server immediately. Useful for adding context
+ * to a trace from a different process, request, or thread (e.g. a forked
+ * agent that wants to annotate the original conversation's trace). Its methods
+ * write whether or not capture is on.
+ */
+interface DetachedTrace {
+  /** The canonical Bitfab trace ID this handle resolves. */
+  readonly traceId: string;
+  /**
+   * Append a context entry to this trace. Each call adds one entry to the
+   * server-side contexts array; existing entries are preserved.
+   *
+   * Resolves once the server has applied the change and REJECTS if the server
+   * refused it. A detached patch targets an already-closed trace, so it rides
+   * no batch and no later signal would reveal a silent failure - the caller is
+   * the only one who can react.
+   */
+  addContext(context: Record<string, unknown>): Promise<void>;
+  /**
+   * Merge metadata into this trace. Server-side shallow-merges the new keys
+   * into the existing metadata object; existing keys are preserved unless
+   * overwritten by the new values. Rejects if the server refused the update.
+   */
+  setMetadata(metadata: Record<string, unknown>): Promise<void>;
+  /**
+   * Set the sessionId for this trace. Replaces any existing sessionId.
+   * Rejects if the server refused the update.
+   */
+  setSessionId(sessionId: string): Promise<void>;
+  setName(name: string): Promise<void>;
+}
+/**
+ * A handle to the current active trace, allowing trace-level context to be set.
+ */
+interface CurrentTrace {
+  /**
+   * Set the session ID for this trace. Stored in the database session_id column.
+   */
+  setSessionId(sessionId: string): void;
+  setName(name: string): void;
+  /**
+   * Set metadata for this trace. Stored in rawData.metadata.
+   * Subsequent calls merge with existing metadata, with later values taking precedence.
+   */
+  setMetadata(metadata: Record<string, unknown>): void;
+  /**
+   * Add a context entry to this trace. Each call appends to the contexts array.
+   * Context entries are stored in rawData.contexts as [{key, value}, ...].
+   */
+  addContext(context: Record<string, unknown>): void;
+  /**
+   * Flag this trace to be dropped. Once flagged, spans that complete afterward
+   * are not uploaded at all, and when the trace completes the server scrubs any
+   * payloads that already raced out (trace, external trace, and sibling spans),
+   * marking it `dropped` instead of `completed` and retaining only a skeleton
+   * audit record. Use this to discard runs you never want stored (e.g. health
+   * checks, or a run you know contains sensitive data). Takes effect
+   * immediately for later spans; the server-side scrub takes effect at trace
+   * completion, so a trace that is flagged but never completes is not scrubbed.
+   */
+  drop(): void;
+}
+/**
+ * Get a handle to the current active span.
+ *
+ * Call this from inside a traced function (wrapped with `withSpan`) to get
+ * a span handle that allows adding context at runtime.
+ *
+ * Returns a no-op object if called outside of a span context (methods do nothing).
+ */
+declare function getCurrentSpan(): CurrentSpan;
+/**
+ * Get the database branch the current replay item is running against.
+ *
+ * Call this from inside a function being replayed with `replay({ dbBranch })`
+ * and point your database client at `branch.databaseUrl` so the replay reads
+ * the data as it was at trace time:
+ *
+ * ```ts
+ * const branch = getCurrentReplayBranch()
+ * const url = branch?.databaseUrl ?? process.env.DATABASE_URL
+ * ```
+ *
+ * Returns null outside a replay item, and for an item whose source trace
+ * carried no DB snapshot reference, so live request code takes the same path
+ * it always did.
+ */
+declare function getCurrentReplayBranch(): ReplayBranch | null;
+/**
+ * Get a handle to the current active trace.
+ *
+ * Call this from inside a traced function (wrapped with `withSpan`) to get
+ * a trace handle that allows setting trace-level context at runtime.
+ *
+ * Returns a no-op object if called outside of a span context (methods do nothing).
+ */
+declare function getCurrentTrace(): CurrentTrace;
+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;
+}
+interface ReseedOptions {
+  traceId: string;
+}
+interface ReseedResult {
+  traceId: string;
+  previousRunTraceId: string;
+}
+interface BitfabConfig {
+  /**
+   * The API key for Bitfab API authentication. Resolved lazily, the first
+   * time a span actually needs it, not at construction. When it resolves
+   * empty, tracing is disabled (a no-op, unless `strict` is set).
+   *
+   * Accepts either a string or a function returning the key. The function
+   * form is resolved at first use, so it survives the ESM trap where a shim
+   * built at module load runs before the script body's `dotenv.config()`:
+   * `apiKey: () => process.env.BITFAB_API_KEY`. When omitted (or it resolves
+   * empty), the SDK also falls back to reading `BITFAB_API_KEY` from the
+   * environment itself, again at first use.
+   */
+  apiKey?: string | (() => string | null | undefined);
+  /** The base URL for the Bitfab API (default: https://bitfab.ai) */
+  serviceUrl?: string;
+  /** Request timeout in milliseconds (default: 120000) */
+  timeout?: number;
+  /** Environment variables for LLM provider API keys (only OPENAI_API_KEY is supported) */
+  envVars?: AllowedEnvVars;
+  captureEnabled?: boolean;
+  enabled?: boolean;
+  /**
+   * Fail loud instead of degrading quietly. When true, the first traced call
+   * with no resolvable API key throws a `BitfabError` rather than silently
+   * disabling tracing. Off by default so a missing telemetry key never takes
+   * down the host app; turn it on in standalone scripts where a run that
+   * emits no traces is a failure you want surfaced immediately.
+   */
+  strict?: boolean;
+  /** The generated BAML client instance (e.g., `b` from your baml_client). Used by wrapBAML() when no explicit client is passed. */
+  bamlClient?: unknown;
+  /**
+   * Per-trace database snapshot config. When set, every root span captures
+   * a wall-clock timestamp (and, if `captureRef` is provided, a provider-
+   * specific point-in-time ref) so the trace can later be replayed against
+   * a branch materialized from that point.
+   */
+  dbSnapshot?: DbSnapshotConfig;
+  simulationPlan?: boolean;
+}
+/**
+ * Controls when a span is captured.
+ * - always: Capture the span even when it becomes the root of a new trace.
+ * - nested: Capture the span only when another Bitfab span is already active.
+ */
+type CaptureWhen = "always" | "nested";
+/**
+ * Options for configuring span behavior.
+ */
+interface SpanOptions {
+  /**
+   * The name of the span. Defaults to the function name if available,
+   * otherwise falls back to the trace function key.
+   */
+  name?: string;
+  /**
+   * The type of span. Defaults to "custom" if not specified.
+   */
+  type?: SpanType;
+  /**
+   * Controls whether this span may start a new trace. Defaults to "always".
+   *
+   * Use "nested" for reusable helpers that should appear inside an existing
+   * trace but should run untraced when called on their own.
+   * Unknown values warn once and default to "always".
+   */
+  captureWhen?: CaptureWhen;
+  /**
+   * When true, replay will reuse this span's historical output instead of
+   * executing the wrapped function. Read by the "marked" replay strategy;
+   * ignored outside replay and under the "all"/"none" strategies.
+   *
+   * Use this for child spans that are expensive (paid LLM/API calls),
+   * slow, or non-deterministic - the root function still runs real code,
+   * only the marked descendants return their recorded output. If a selected
+   * occurrence is unavailable, replay fails the item without executing the
+   * real child.
+   */
+  mockOnReplay?: boolean;
+  /**
+   * Experimental selective-replay eligibility, recorded with this span.
+   * Attests that the whole subtree is output-only with JSON value semantics:
+   * no hidden mutable reads, required effects, input mutations, or reliance
+   * on object identity. Include implementation/dependency changes in replay's
+   * mustRun. Both capture-time and current declarations must allow reuse.
+   * Does not affect ordinary replay or replace mockOnReplay safety protection.
+   */
+  replayReusable?: boolean;
+  /** Optional experiment ID included on the span and on the trace it starts. */
+  experimentId?: string;
+  /**
+   * @deprecated Use {@link experimentId}. Same meaning. Passing both with
+   * different values throws.
+   */
+  testRunId?: string;
+  /**
+   * Record a serializable view of a non-serializable result (e.g. a live
+   * stream object) as the span output.
+   *
+   * When set, the wrapped function's raw return value is handed back to the
+   * caller unchanged (so streaming and first-byte latency are untouched),
+   * but instead of serializing that raw value, the span records
+   * `await finalize(result)`. Use this to trace functions that return a live
+   * stream consumed by the caller (Vercel AI SDK `streamText`, a
+   * `ReadableStream`, an SSE response) while still capturing a serializable,
+   * replayable output such as `{ text, usage, toolCalls }`.
+   *
+   * Reading from a multi-consumer stream result (like the AI SDK's, which
+   * tees internally) does not disturb the caller's own consumption. For the
+   * Vercel AI SDK shape, pass the prebuilt `finalizers.aiSdk` helper.
+   *
+   * Ignored for async-generator results, which are captured automatically.
+   */
+  finalize?: (result: any) => unknown | Promise<unknown>;
+}
+/**
+ * The standard method context passed to a decorator.
+ *
+ * Defined structurally instead of referencing TypeScript's built-in
+ * `ClassMethodDecoratorContext`, which was added in TypeScript 5.0. This keeps
+ * the SDK's non-decorator APIs consumable by projects on older compilers.
+ */
+interface SpanMethodDecoratorContext<TThis, TValue> {
+  readonly kind: "method";
+  readonly name: string | symbol;
+  readonly static: boolean;
+  readonly private: boolean;
+  readonly access: {
+    has(object: TThis): boolean;
+    get(object: TThis): TValue;
+  };
+  addInitializer(initializer: (this: TThis) => void): void;
+  readonly metadata?: Record<PropertyKey, unknown>;
+}
+/** A standard ECMAScript method decorator produced by {@link Bitfab.span}. */
+type SpanMethodDecorator = <TThis, TArgs extends unknown[], TReturn>(originalMethod: (this: TThis, ...args: TArgs) => TReturn, context: SpanMethodDecoratorContext<TThis, (this: TThis, ...args: TArgs) => TReturn>) => (this: TThis, ...args: TArgs) => TReturn;
+/** Trace-owned configuration for a function discovered beneath `trace()`. */
+interface NodeOptions extends Omit<SpanOptions, "captureWhen"> {
+  /** Whether the enclosing trace captures this call. Defaults to true. */
+  capture?: boolean;
+}
+type StandardNodeMethodDecorator = SpanMethodDecorator;
+type LegacyNodeMethodDecorator = <TThis, TArgs extends unknown[], TReturn>(target: object, propertyKey: string | symbol, descriptor: TypedPropertyDescriptor<(this: TThis, ...args: TArgs) => TReturn>) => void;
+/** A method decorator produced by {@link Bitfab.node}. */
+type NodeMethodDecorator = StandardNodeMethodDecorator & LegacyNodeMethodDecorator;
+/** Options for experimental automatic subtree tracing. */
+interface TraceOptions {
+  /** Root span name. Defaults to the decorated or wrapped function name. */
+  name?: string;
+  /** Root span type. Descendants are always `function` spans. */
+  type?: SpanType;
+  /**
+   * Default replay-mocking policy for automatically captured descendants.
+   * When true, those descendants are mocked by the default "marked" strategy
+   * unless a node explicitly sets `mockOnReplay: false`. Defaults to false.
+   */
+  mockOnReplayDefault?: boolean;
+  /** Maximum number of recorded descendant levels. Defaults to 30. */
+  maxDepth?: number;
+  maxCapturedSubtreeSpans?: number;
+  /** Qualified or simple function names to leave out of the subtree. */
+  exclude?: readonly string[] | ReadonlySet<string>;
+  /** Record rest-argument wrapper functions. Defaults to false. */
+  includeWrappers?: boolean;
+}
+type StandardTraceMethodDecorator = <This, TArgs extends unknown[], TReturn>(method: (this: This, ...args: TArgs) => TReturn, context: {
+  kind: "method";
+  name: string | symbol;
+}) => (this: This, ...args: TArgs) => TReturn;
+type LegacyTraceMethodDecorator = <This, TArgs extends unknown[], TReturn>(target: object, propertyKey: string | symbol, descriptor: TypedPropertyDescriptor<(this: This, ...args: TArgs) => TReturn>) => void;
+type TraceMethodDecorator = StandardTraceMethodDecorator & LegacyTraceMethodDecorator;
+/**
+ * Client for making provider-based API calls via BAML.
+ */
+declare class Bitfab {
+  private readonly apiKeyConfig;
+  /** Cached only once a non-empty key is found, so an early resolve (before env loaded) can't poison a later one. */
+  private resolvedApiKey;
+  /** Gate the empty-key warning to fire at most once. */
+  private apiKeyWarned;
+  private readonly serviceUrl;
+  private readonly timeout;
+  private readonly envVars;
+  private readonly captureConfiguredInCode;
+  private captureConfiguredFromEnv;
+  private readonly strict;
+  private readonly httpClient;
+  /** Dataset operations for the authenticated organization. */
+  readonly datasets: DatasetsClient;
+  /** Organization-scoped groupings for assertions and scenarios. */
+  readonly categories: CategoriesClient;
+  /** @deprecated Use {@link categories}. Same client. */
+  readonly assertionCategories: CategoriesClient;
+  readonly organizationMembers: OrganizationMembersClient;
+  readonly traces: TracesClient;
+  readonly spans: SpansClient;
+  readonly labels: LabelsClient;
+  readonly graders: GradersClient;
+  readonly experiments: ExperimentsClient;
+  private readonly bamlClient;
+  private readonly dbSnapshot;
+  private readonly simulationPlan;
+  /**
+   * Mock overrides registered via {@link Bitfab.registerMockOverride}, applied
+   * to every `replay` on this client (after any per-call `mockOverride`). In
+   * registration order; first matcher wins within this list.
+   */
+  private readonly mockOverrides;
+  /**
+   * Initialize the Bitfab client.
+   *
+   * @param config - Configuration options for the client
+   */
+  constructor(config: BitfabConfig);
+  /**
+   * Decorate a class method as an automatically expanded trace root.
+   *
+   * Build instrumentation turns repository functions called beneath this
+   * method into nested spans that capture inputs, outputs, and errors by
+   * default. Source exclusions and sim-plan capture-off decisions are explicit
+   * opt-outs from that default.
+   * Without a compatible build transform, this still records the decorated
+   * method as a normal rich root span but cannot discover child calls.
+   *
+   * @param traceFunctionKey - Groups traces and their capture controls.
+   * @param options - Root presentation, subtree bounds, and exclusions.
+   * @experimental Automatic child-call instrumentation is experimental.
+   */
+  trace(traceFunctionKey: string, options?: TraceOptions): TraceMethodDecorator;
+  /**
+   * Wrap a function as an automatically expanded trace root.
+   *
+   * This is the function-oriented equivalent of {@link Bitfab.trace}. Build
+   * instrumentation turns repository functions called beneath the wrapped
+   * function into nested spans that capture inputs, outputs, and errors by
+   * default. Source exclusions and sim-plan capture-off decisions are explicit
+   * opt-outs from that default. Without a compatible transform, this still
+   * records one normal rich root span and runs the function unchanged.
+   *
+   * @param traceFunctionKey - Groups traces and their capture controls.
+   * @param optionsOrFn - Options or the workflow entrypoint to wrap.
+   * @param maybeFn - Workflow entrypoint when options are provided.
+   * @experimental Automatic child-call instrumentation is experimental.
+   */
+  withTrace<This, TArgs extends unknown[], TReturn>(traceFunctionKey: string, fn: (this: This, ...args: TArgs) => TReturn): (this: This, ...args: TArgs) => TReturn;
+  withTrace<This, TArgs extends unknown[], TReturn>(traceFunctionKey: string, options: TraceOptions, fn: (this: This, ...args: TArgs) => TReturn): (this: This, ...args: TArgs) => TReturn;
+  /**
+   * Configure a transformed class method when it is discovered beneath a
+   * {@link Bitfab.trace} root.
+   *
+   * The decorator creates no span or trace by itself. Beneath an active trace,
+   * it can rename or retype the discovered call, capture its contents, mark it
+   * for recorded-output replay, finalize its output, or omit it while leaving
+   * captured descendants attached to the nearest captured parent.
+   *
+   * @param options - Trace-owned call configuration.
+   * @experimental Automatic child-call instrumentation is experimental.
+   */
+  node(options?: NodeOptions): NodeMethodDecorator;
+  /**
+   * Configure a transformed standalone function when it is discovered beneath
+   * a {@link Bitfab.trace} or {@link Bitfab.withTrace} root.
+   *
+   * This is the function-oriented equivalent of {@link Bitfab.node}. Without
+   * an active automatic trace, the returned function runs normally and never
+   * creates a span or trace. The function must be named so configuration can
+   * be bound to its transformed definition without leaking to a descendant.
+   *
+   * @param optionsOrFn - Node options or the function to configure.
+   * @param maybeFn - Function to configure when options are provided.
+   * @experimental Automatic child-call instrumentation is experimental.
+   */
+  withNode<This, TArgs extends unknown[], TReturn>(fn: (this: This, ...args: TArgs) => TReturn): (this: This, ...args: TArgs) => TReturn;
+  withNode<This, TArgs extends unknown[], TReturn>(options: NodeOptions, fn: (this: This, ...args: TArgs) => TReturn): (this: This, ...args: TArgs) => TReturn;
+  private resolveNodeConfiguration;
+  private createAutoTraceNode;
+  private createAutoTraceRoot;
+  private applySimulationPlan;
+  /**
+   * Flush and permanently close this client's tracing resources: its pending
+   * requests and the single span-transport worker shared by its decorators and
+   * framework handlers.
+   *
+   * Resolves `false` when delivery failed or the deadline expired. Long-lived
+   * processes never need this (the transport batches in the background and the
+   * exit hook drains it); scripts and tests that want a hard guarantee should
+   * await it.
+   *
+   * Deliberately not a `Symbol.asyncDispose` method: the SDK targets runtimes
+   * where that symbol may be absent, and a computed key on a missing symbol
+   * throws at class-definition time, taking the whole SDK down on load.
+   */
+  close(timeoutMs?: number): Promise<boolean>;
+  /**
+   * Resolve the API key lazily, the first time a span actually needs it.
+   *
+   * The key is intentionally NOT read at construction. In ESM, a shim that
+   * does `new Bitfab({ apiKey: process.env.BITFAB_API_KEY })` is hoisted and
+   * evaluated before the importing script's body runs `dotenv.config()`, so
+   * the key would be empty at construction even though it is set moments
+   * later. Resolving here (at first `withSpan` call / first request) reads
+   * the key after env loading has run.
+   *
+   * Resolution order: the configured value (string, or function called each
+   * time it is still unresolved), then a fallback read of `BITFAB_API_KEY`
+   * from the environment. Once a non-empty key is found it is cached, so an
+   * early resolve that found nothing never poisons a later one.
+   */
+  private findApiKey;
+  private resolveApiKey;
+  private isCaptureConfigured;
+  private isCaptureEnabled;
+  private shouldRecord;
+  private prepareFrameworkIntegration;
+  get captureEnabled(): boolean;
+  /**
+   * Fetch the function with its current version and BAML prompt from the server.
+   *
+   * @param methodName - The name of the method to fetch
+   * @returns The function with current version, BAML prompt, and provider definitions
+   * @throws {BitfabError} If the function is not found or an error occurs
+   */
+  private fetchFunctionVersion;
+  /**
+   * Call a method with the given named arguments via BAML execution.
+   *
+   * @param methodName - The name of the method to call
+   * @param inputs - Named arguments to pass to the method
+   * @returns The result of the BAML function execution
+   * @throws {BitfabError} If service_url is not set, or if an error occurs
+   */
+  call<T = unknown>(methodName: string, inputs?: Record<string, unknown>): Promise<T>;
+  /**
+   * Get a tracing processor for OpenAI Agents SDK integration.
+   *
+   * This processor automatically captures traces and spans from the OpenAI Agents SDK
+   * and sends them to Bitfab for monitoring and analysis.
+   *
+   * Example usage:
+   * ```typescript
+   * import { addTraceProcessor } from '@openai/agents';
+   *
+   * const client = new Bitfab({ apiKey: 'your-api-key' });
+   * const processor = client.getOpenAiTracingProcessor();
+   * addTraceProcessor(processor);
+   * ```
+   *
+   * @returns A BitfabOpenAITracingProcessor instance configured for this client
+   */
+  getOpenAiTracingProcessor(): BitfabOpenAITracingProcessor;
+  /**
+   * Get an OpenAI Agents SDK handler that records a replayable root span.
+   *
+   * The processor from {@link getOpenAiTracingProcessor} captures everything
+   * inside a run (LLM calls, tools, handoffs) but never sees the caller's
+   * input, so a processor-only run records an empty-input root and is not
+   * replayable. This handler's `wrapRun` is a drop-in for `run()` that opens a
+   * `withSpan` root carrying the input and final output; the processor's spans
+   * nest beneath it. Register the processor once at startup, then call
+   * `handler.wrapRun(agent, input)` in place of `run(agent, input)`.
+   *
+   * ```typescript
+   * import { addTraceProcessor, Agent, run } from "@openai/agents";
+   *
+   * addTraceProcessor(client.getOpenAiTracingProcessor());
+   * const handler = client.getOpenAiAgentHandler("research-topic");
+   * const result = await handler.wrapRun(agent, "Find X");
+   * ```
+   *
+   * @param traceFunctionKey - Groups traces under this key in Bitfab
+   * @returns A BitfabOpenAIAgentHandler configured for this client
+   */
+  getOpenAiAgentHandler(traceFunctionKey: string): BitfabOpenAIAgentHandler;
+  /**
+   * Get a LangGraph/LangChain callback handler for tracing.
+   *
+   * The handler captures graph node execution, LLM calls, and tool
+   * invocations as Bitfab spans with proper parent-child hierarchy.
+   *
+   * ```typescript
+   * const handler = client.getLangGraphCallbackHandler("my-agent");
+   * const result = await agent.invoke(
+   *   { messages: [...] },
+   *   { callbacks: [handler] },
+   * );
+   * ```
+   *
+   * @param traceFunctionKey - Groups traces under this key in Bitfab
+   * @returns A BitfabLangGraphCallbackHandler configured for this client
+   */
+  getLangGraphCallbackHandler(traceFunctionKey: string): BitfabLangGraphCallbackHandler;
+  /**
+   * Get a LangChain callback handler for tracing.
+   *
+   * Alias of {@link getLangGraphCallbackHandler}: LangChain chains and
+   * LangGraph graphs share the same callback system, so one handler serves
+   * both.
+   *
+   * ```typescript
+   * const handler = client.getLangChainCallbackHandler("my-chain");
+   * const result = await chain.invoke(input, { callbacks: [handler] });
+   * ```
+   *
+   * @param traceFunctionKey - Groups traces under this key in Bitfab
+   * @returns A BitfabLangGraphCallbackHandler configured for this client
+   */
+  getLangChainCallbackHandler(traceFunctionKey: string): BitfabLangGraphCallbackHandler;
+  /**
+   * Get the first-class LangGraph integration for tracing and replaying tools
+   * executed by `ToolNode`.
+   *
+   * The integration combines `wrapTools()` for per-tool replay interception
+   * with `createInvoker()` for a callback-configured replayable graph entry
+   * point. Lower-level callback and root wrappers remain available.
+   *
+   * @param traceFunctionKey - Groups traces under this key in Bitfab
+   * @param options - Controls which tools are marked for replay mocking
+   * @experimental This API may change before it is stable.
+   */
+  getLangGraphIntegration(traceFunctionKey: string, options?: LangGraphIntegrationOptions): BitfabLangGraphIntegration;
+  /**
+   * Get the first-class Rivet actor/workflow-context integration for an
+   * existing trace root. The integration binds context and records effect
+   * spans; it never creates another root.
+   *
+   * @param traceFunctionKey - Key used by the enclosing `withTrace()` root
+   * @param options - Explicit per-context-path replay mocking policy
+   * @experimental This API may change before it is stable.
+   */
+  getRivetIntegration<TContext extends object = RivetContextLike>(traceFunctionKey: string, options?: RivetIntegrationOptions): BitfabRivetIntegration<TContext>;
+  /**
+   * Get a Claude Agent SDK handler for tracing.
+   *
+   * The handler captures LLM turns, tool invocations, and subagent
+   * execution as Bitfab spans with proper parent-child hierarchy.
+   *
+   * ```typescript
+   * import { query } from "@anthropic-ai/claude-agent-sdk";
+   *
+   * const handler = client.getClaudeAgentHandler("my-agent");
+   * const options = handler.instrumentOptions({
+   *   model: "claude-sonnet-4-5-...",
+   * });
+   * for await (const msg of handler.wrapQuery(
+   *   query({ prompt: "Do something", options })
+   * )) {
+   *   // process messages
+   * }
+   * ```
+   *
+   * @param traceFunctionKey - Groups traces under this key in Bitfab
+   * @returns A BitfabClaudeAgentHandler configured for this client
+   */
+  getClaudeAgentHandler(traceFunctionKey: string): BitfabClaudeAgentHandler;
+  /**
+   * Get a Vercel AI SDK language-model middleware for tracing.
+   *
+   * Pass it to the AI SDK's `wrapLanguageModel` and use the wrapped model with
+   * `generateText` / `streamText` / `generateObject` / `streamObject`. Every
+   * call through that model is captured as a keyed `llm` span carrying the call
+   * parameters (the prompt) as input and a serializable summary
+   * (`{ text, toolCalls, usage, finishReason }`) as output. Streaming is
+   * captured without disturbing the caller's live stream.
+   *
+   * ```typescript
+   * import { wrapLanguageModel, streamText } from "ai";
+   * import { openai } from "@ai-sdk/openai";
+   *
+   * const model = wrapLanguageModel({
+   *   model: openai("gpt-4o"),
+   *   middleware: client.getVercelAiMiddleware("chat-turn"),
+   * });
+   * const result = streamText({ model, messages });
+   * ```
+   *
+   * @param traceFunctionKey - Groups traces under this key in Bitfab
+   * @returns A Vercel AI SDK middleware configured for this client
+   */
+  getVercelAiMiddleware(traceFunctionKey: string): BitfabLanguageModelMiddleware;
+  /**
+   * Wrap a BAML client method to automatically capture prompt and LLM metadata.
+   *
+   * Creates a BAML Collector, calls the method through a tracked client,
+   * then extracts rendered messages and token usage - calling setPrompt()
+   * and addContext() on the current span automatically.
+   *
+   * The BAML client can be provided in the constructor or passed explicitly:
+   *
+   * ```typescript
+   * // Option 1: bamlClient in constructor (use wrapBAML with just the method)
+   * const client = new Bitfab({ apiKey: 'your-api-key', bamlClient: b });
+   * const traced = client.withSpan('classify', { type: 'llm' },
+   *   client.wrapBAML(b.ClassifyText)
+   * );
+   *
+   * // Option 2: pass bamlClient at call site
+   * const client = new Bitfab({ apiKey: 'your-api-key' });
+   * const traced = client.withSpan('classify', { type: 'llm' },
+   *   client.wrapBAML(b, b.ClassifyText)
+   * );
+   * ```
+   *
+   * @param methodOrClient - Either a BAML method (uses constructor bamlClient) or the BAML client instance
+   * @param maybeMethodOrOptions - The BAML method when the first argument is a client, or WrapBAMLOptions when the first argument is the method
+   * @param maybeOptions - WrapBAMLOptions when using the two-argument (client, method) form
+   * @returns An async function with the same signature that instruments the BAML call
+   */
+  wrapBAML<TArgs extends unknown[], TReturn>(methodOrClient: unknown, maybeMethodOrOptions?: ((...args: TArgs) => Promise<TReturn>) | WrapBAMLOptions, maybeOptions?: WrapBAMLOptions): WrappedBamlFn<TArgs, TReturn>;
+  /**
+   * Wrap a function to automatically create a span for its inputs and outputs.
+   *
+   * The wrapped function behaves identically to the original, but sends
+   * span data to Bitfab in the background after each call.
+   *
+   * Example usage:
+   * ```typescript
+   * const client = new Bitfab({ apiKey: 'your-api-key' });
+   *
+   * async function processOrder(orderId: string, items: string[]): Promise<{ total: number }> {
+   *   // ... process order
+   *   return { total: 100 };
+   * }
+   *
+   * // Basic usage (defaults to "custom" span type)
+   * const tracedProcessOrder = client.withSpan('order-processing', processOrder);
+   *
+   * // With explicit span type
+   * const tracedProcessOrder = client.withSpan('order-processing', { type: 'function' }, processOrder);
+   *
+   * // Call the wrapped function normally
+   * const result = await tracedProcessOrder('order-123', ['item-1', 'item-2']);
+   * // Span is automatically sent to Bitfab
+   * ```
+   *
+   * @param traceFunctionKey - A string identifier for grouping spans (e.g., 'order-processing', 'user-auth')
+   * @param optionsOrFn - Either SpanOptions or the function to wrap
+   * @param maybeFn - The function to wrap if options were provided
+   * @returns A wrapped function with the same signature that creates spans for inputs and outputs
+   */
+  withSpan<TArgs extends unknown[], TReturn>(traceFunctionKey: string, optionsOrFn: SpanOptions | ((...args: TArgs) => TReturn), maybeFn?: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
+  /**
+   * Create a standard ECMAScript method decorator that records each invocation
+   * as a span.
+   *
+   * It supports instance, static, and private methods; use
+   * {@link Bitfab.withSpan} for standalone functions, class fields, and
+   * accessors.
+   *
+   * @example
+   * ```typescript
+   * const bitfab = new Bitfab({ apiKey: process.env.BITFAB_API_KEY });
+   *
+   * class OrderService {
+   *   @bitfab.span("order-processing", { type: "agent" })
+   *   async process(orderId: string) {
+   *     return { orderId };
+   *   }
+   * }
+   * ```
+   *
+   * @param traceFunctionKey - A string identifier for grouping spans
+   * @param options - Span configuration applied to the decorated method
+   * @returns A standard ECMAScript method decorator
+   */
+  span(traceFunctionKey: string, options?: SpanOptions): SpanMethodDecorator;
+  /**
+   * Get a detached handle to a previously-created trace, looked up by the
+   * canonical Bitfab trace ID.
+   *
+   * The returned handle is not tied to AsyncLocalStorage - each method sends
+   * to the server immediately. Useful for adding context to a trace from a
+   * different process or thread than the one that created it.
+   *
+   * Throws synchronously if `traceId` is not a valid Bitfab trace ID. The
+   * server returns 404 if no trace exists with that ID in the org; the failure surfaces as a
+   * logged warning (fire-and-forget) or via the awaited promise.
+   *
+   * Example:
+   * ```typescript
+   * const trace = client.getTrace(traceId);
+   * await trace.addContext({ refund_status: "approved" });
+   * await trace.setMetadata({ region: "us-west" });
+   * ```
+   */
+  getTrace(traceId: string): DetachedTrace;
+  /**
+   * Fetch one persisted span from a trace without loading the full trace.
+   * Look up by `id` alone, or by `name` and/or `type` (both must match when
+   * both are given). Name and type lookups return the last matching span by
+   * default. Pass `occurrence` as `"first"` or a zero-based index to select a
+   * different match. Returns `null` when no span matches.
+   */
+  getTraceSpan(traceId: string, lookup: SpanLookup): Promise<CapturedSpan | null>;
+  getSpan(spanId: string): Promise<CapturedSpan | null>;
+  /**
+   * Get a function wrapper for a specific trace function key.
+   *
+   * This provides a fluent API alternative to calling withSpan directly,
+   * allowing you to bind the traceFunctionKey once and wrap multiple functions.
+   *
+   * Example usage:
+   * ```typescript
+   * const client = new Bitfab({ apiKey: 'your-api-key' });
+   *
+   * const orderFunc = client.getFunction('order-processing');
+   * const tracedProcessOrder = orderFunc.withSpan(processOrder);
+   * const tracedValidateOrder = orderFunc.withSpan(validateOrder);
+   * ```
+   *
+   * @param traceFunctionKey - A string identifier for grouping spans
+   * @returns A BitfabFunction instance for wrapping functions
+   */
+  getFunction(traceFunctionKey: string): BitfabFunction;
+  /**
+   * Send trace completion when a root span ends.
+   * Internal method to record trace completion with end time.
+   * Queued on the client's span transport; delivery is the transport's job.
+   */
+  private sendTraceCompletion;
+  private sendsSpanOnCompletion;
+  private nearestCapturedAncestorSpanIdOf;
+  private contentOffBySimulationPlan;
+  /**
+   * Send a wrapper span from function execution.
+   * Internal method to record spans when using withSpan.
+   * Queued on the client's span transport; delivery is the transport's job.
+   */
+  private sendWrapperSpan;
+  /**
+   * Replay historical traces through a function and create an experiment.
+   *
+   * Fetches the last N traces for the given trace function key, re-runs each
+   * through the provided function, and returns comparison data.
+   *
+   * Accepts either a `withSpan`-wrapped function (under the same key) or any
+   * plain callable: plain callables are wrapped internally so each replayed
+   * invocation records a trace tied to the experiment. The plain-callable form
+   * is how handler-instrumented workflows (LangGraph/LangChain, Claude Agent
+   * SDK) replay - those record traces under a key with no `withSpan`-wrapped
+   * root in the app.
+   *
+   * @param traceFunctionKey - The trace function key to replay
+   * @param fn - The function to run recorded inputs through
+   * @param options - Optional replay options. When `traceIds` is passed,
+   *   `limit` is ignored (with a warning): an explicit ID list already
+   *   determines how many traces replay.
+   * @returns ReplayResult with items, experimentId, and experimentUrl
+   */
+  /**
+   * Register a mock override applied to every subsequent `replay` on this
+   * client, so downstream real code runs against a value you supply for the
+   * matched span. Instance-scoped (no global state); call {@link clearMockOverrides}
+   * to reset. Per-call `replay({ mockOverride })` overrides take precedence, and
+   * both take precedence over the base `mock` strategy.
+   *
+   * ```ts
+   * // Object form (value is a flat value here)
+   * bitfab.registerMockOverride({
+   *   match: (node) => node.traceFunctionKey === "classify-intent",
+   *   value: { label: "refund" },
+   * })
+   * // Ordered form (equivalent); value may also be a function of the context
+   * bitfab.registerMockOverride(
+   *   (node) => node.traceFunctionKey === "classify-intent",
+   *   ({ inputs }) => ({ label: "refund" }),
+   * )
+   * // Keyed form: the resolver only sees spans for this trace function key.
+   * bitfab.registerMockOverride("classify-intent", ({ inputs }) => ({
+   *   label: String(inputs[0]),
+   * }))
+   * // Or one resolver for every child span:
+   * bitfab.registerMockOverride(({ node }) =>
+   *   node.traceFunctionKey === "classify-intent"
+   *     ? { label: "refund" }
+   *     : NO_MOCK_OVERRIDE,
+   * )
+   * ```
+   */
+  registerMockOverride(override: MockOverride): void;
+  registerMockOverride(resolver: MockOverrideResolver): void;
+  registerMockOverride(match: NodeMatcher, value: MockValue): void;
+  registerMockOverride(traceFunctionKey: string, override: MockOverride | MockOverrideResolver): void;
+  /** Remove all overrides registered via {@link registerMockOverride}. */
+  clearMockOverrides(): void;
+  seedTrace(traceFunctionKey: string, options: SeedCaseOptions): string;
+  seedTrace<TArgs extends unknown[], TReturn>(traceFunctionKey: string, fn: (...args: TArgs) => TReturn, options?: SeedRunOptions<TArgs>): Promise<string>;
+  private seedTraceFromCase;
+  private seedTraceByRunning;
+  reseedTrace(traceFunctionKey: string, fn: (...args: any[]) => unknown, options: ReseedOptions): Promise<ReseedResult>;
+  replay<TReturn>(traceFunctionKey: string, fn: (...args: any[]) => TReturn | Promise<TReturn>, options?: ReplayOptions): Promise<ReplayResult<TReturn>>;
+}
+/**
+ * Represents a Bitfab function that can wrap user functions for tracing.
+ *
+ * This provides a fluent API for binding a traceFunctionKey once and
+ * then wrapping multiple functions with that key.
+ *
+ * Example usage:
+ * ```typescript
+ * const client = new Bitfab({ apiKey: 'your-api-key' });
+ *
+ * const orderFunc = client.getFunction('order-processing');
+ * const tracedProcessOrder = orderFunc.withSpan(processOrder);
+ * const tracedValidateOrder = orderFunc.withSpan(validateOrder);
+ * ```
+ */
+declare class BitfabFunction {
+  private readonly client;
+  private readonly traceFunctionKey;
+  constructor(client: Bitfab, traceFunctionKey: string);
+  /**
+   * Wrap a function to automatically create a span for its inputs and outputs.
+   *
+   * The wrapped function behaves identically to the original, but sends
+   * span data to Bitfab in the background after each call.
+   *
+   * Example usage:
+   * ```typescript
+   * const orderFunc = client.getFunction('order-processing');
+   *
+   * // Basic usage (defaults to "custom" span type)
+   * const tracedProcessOrder = orderFunc.withSpan(processOrder);
+   *
+   * // With explicit span type
+   * const tracedProcessOrder = orderFunc.withSpan({ type: 'function' }, processOrder);
+   * ```
+   *
+   * @param optionsOrFn - Either SpanOptions or the function to wrap
+   * @param maybeFn - The function to wrap if options were provided
+   * @returns A wrapped function with the same signature that creates spans
+   */
+  withSpan<TArgs extends unknown[], TReturn>(optionsOrFn: SpanOptions | ((...args: TArgs) => TReturn), maybeFn?: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
+  /**
+   * Create a standard ECMAScript method decorator bound to this function key.
+   *
+   * @example
+   * ```typescript
+   * const orders = client.getFunction("order-processing");
+   *
+   * class OrderService {
+   *   @orders.span({ type: "agent" })
+   *   async process(orderId: string) {
+   *     return { orderId };
+   *   }
+   * }
+   * ```
+   *
+   * @param options - Span configuration applied to the decorated method
+   * @returns A standard ECMAScript method decorator
+   */
+  span(options?: SpanOptions): SpanMethodDecorator;
+  /**
+   * Wrap a function as an automatically expanded trace root bound to this
+   * function's key.
+   *
+   * Equivalent to `client.withTrace(key, options, fn)` but reuses the key
+   * bound on this handle.
+   *
+   * @param optionsOrFn - Trace options or the workflow entrypoint to wrap
+   * @param maybeFn - Workflow entrypoint when options are provided
+   * @returns A wrapped function with the same signature
+   * @experimental Automatic child-call instrumentation is experimental.
+   */
+  withTrace<This, TArgs extends unknown[], TReturn>(fn: (this: This, ...args: TArgs) => TReturn): (this: This, ...args: TArgs) => TReturn;
+  withTrace<This, TArgs extends unknown[], TReturn>(options: TraceOptions, fn: (this: This, ...args: TArgs) => TReturn): (this: This, ...args: TArgs) => TReturn;
+  /**
+   * Create a trace method decorator bound to this function's key.
+   *
+   * Equivalent to `client.trace(key, options)` but reuses the key bound on
+   * this handle.
+   *
+   * @param options - Trace configuration applied to the decorated method
+   * @returns A method decorator configured for this key
+   * @experimental Automatic child-call instrumentation is experimental.
+   */
+  trace(options?: TraceOptions): TraceMethodDecorator;
+  /**
+   * Get a Vercel AI SDK language-model middleware bound to this function's key.
+   *
+   * Equivalent to `client.getVercelAiMiddleware(key)` but reuses the key bound
+   * on this handle, so an outer `withSpan` root and the middleware-traced model
+   * calls share one key without repeating the string. With a matching key, the
+   * outer span is the replayable root and the model-call spans nest beneath it.
+   *
+   * Nesting is captured when the model is called, so keep the
+   * `generateText` / `streamText` call inside this handle's `withSpan`; the
+   * middleware object itself can be created anywhere.
+   *
+   * ```typescript
+   * const chatTurn = client.getFunction("chat-turn");
+   * const runChatTurn = chatTurn.withSpan(
+   *   { type: "agent", finalize: finalizers.aiSdk },
+   *   (messages) => streamText({ model, messages }),
+   * );
+   * const model = wrapLanguageModel({
+   *   model: openai("gpt-4o"),
+   *   middleware: chatTurn.getVercelAiMiddleware(),
+   * });
+   * ```
+   *
+   * @returns A Vercel AI SDK middleware configured for this client and key
+   */
+  getVercelAiMiddleware(): BitfabLanguageModelMiddleware;
+  /**
+   * Get a Claude Agent SDK handler bound to this function's key.
+   *
+   * Equivalent to `client.getClaudeAgentHandler(key)` but reuses the key bound
+   * on this handle, so an outer `withSpan` root and the handler share one key
+   * without repeating the string. With a matching key, the outer span is the
+   * replayable root and every handler span nests beneath it.
+   *
+   * Use the handler inside this handle's `withSpan` body so its spans capture
+   * the enclosing root; framework calls made with no active span record their
+   * own root instead.
+   *
+   * ```typescript
+   * const pipeline = client.getFunction("my-agent");
+   * const tracedRun = pipeline.withSpan({ type: "agent" }, async (prompt) => {
+   *   const handler = pipeline.getClaudeAgentHandler();
+   *   const options = handler.instrumentOptions({ model: "claude-sonnet-4-6" });
+   *   for await (const msg of handler.wrapQuery(query({ prompt, options }))) { ... }
+   * });
+   * ```
+   *
+   * @returns A Claude Agent SDK handler configured for this client and key
+   */
+  getClaudeAgentHandler(): BitfabClaudeAgentHandler;
+  /**
+   * Get a LangGraph/LangChain callback handler bound to this function's key.
+   *
+   * Equivalent to `client.getLangGraphCallbackHandler(key)` but reuses the key
+   * bound on this handle, so an outer `withSpan` root and the handler share one
+   * key without repeating the string. With a matching key, the outer span is
+   * the replayable root and the LangGraph spans nest beneath it.
+   *
+   * Use the handler inside this handle's `withSpan` body so its spans capture
+   * the enclosing root; framework calls made with no active span record their
+   * own root instead.
+   *
+   * ```typescript
+   * const pipeline = client.getFunction("my-pipeline");
+   * const tracedRun = pipeline.withSpan({ type: "agent" }, async (query) => {
+   *   const handler = pipeline.getLangGraphCallbackHandler();
+   *   return agent.invoke({ messages: [...] }, { callbacks: [handler] });
+   * });
+   * ```
+   *
+   * @returns A LangGraph/LangChain callback handler for this client and key
+   */
+  getLangGraphCallbackHandler(): BitfabLangGraphCallbackHandler;
+  /**
+   * Alias of {@link getLangGraphCallbackHandler} - LangChain and LangGraph
+   * share one callback system, so the same bound handler serves both.
+   *
+   * @returns A LangChain callback handler for this client and key
+   */
+  getLangChainCallbackHandler(): BitfabLangGraphCallbackHandler;
+  /**
+   * Get the first-class LangGraph tool replay integration bound to this key.
+   *
+   * @experimental This API may change before it is stable.
+   */
+  getLangGraphIntegration(options?: LangGraphIntegrationOptions): BitfabLangGraphIntegration;
+  /**
+   * Get the first-class Rivet actor-context integration bound to this key.
+   * Use its `bind()` or `withContext()` outside this handle's `withTrace()`
+   * root, then call `getContext()` inside the root.
+   *
+   * @param options - Explicit per-context-path replay mocking policy
+   * @experimental This API may change before it is stable.
+   */
+  getRivetIntegration<TContext extends object = RivetContextLike>(options?: RivetIntegrationOptions): BitfabRivetIntegration<TContext>;
+  /**
+   * Wrap a BAML client method to automatically capture prompt and LLM metadata.
+   * Delegates to the parent client's wrapBAML method.
+   *
+   * Unlike the other methods on this handle, `wrapBAML` does NOT use the bound
+   * key: it opens no span of its own. It enriches the *current* span (via
+   * `getCurrentSpan().setPrompt()` / `addContext()`), so call it inside a
+   * function wrapped by this handle's `withSpan` - the bound key keys that
+   * wrapper, and the BAML prompt/metadata attach to it.
+   *
+   * @param methodOrClient - Either a BAML method (uses constructor bamlClient) or the BAML client instance
+   * @param maybeMethodOrOptions - The BAML method when the first argument is a client, or WrapBAMLOptions when the first argument is the method
+   * @param maybeOptions - WrapBAMLOptions when using the two-argument (client, method) form
+   * @returns An async function with the same signature that instruments the BAML call
+   */
+  wrapBAML<TArgs extends unknown[], TReturn>(methodOrClient: unknown, maybeMethodOrOptions?: ((...args: TArgs) => Promise<TReturn>) | WrapBAMLOptions, maybeOptions?: WrapBAMLOptions): WrappedBamlFn<TArgs, TReturn>;
+}
+//#endregion
+//#region src/commitRef.d.ts
+interface CommitRef {
+  sha: string;
+  branch: string | null;
+  dirty: boolean | null;
+  remote: string | null;
+  rootSha: string | null;
+}
+//#endregion
+//#region src/version.generated.d.ts
+/**
+ * Auto-generated package metadata.
+ * This file is generated by scripts/generate-version.ts during build.
+ * DO NOT EDIT MANUALLY.
+ */
+/**
+ * SDK version from package.json (injected at build time)
+ */
+declare const __version__ = "0.65.6";
+//#endregion
+//#region src/constants.d.ts
+/**
+ * Constants for the Bitfab SDK.
+ */
+/**
+ * Default service URL for Bitfab API.
+ */
+declare const DEFAULT_SERVICE_URL = "https://bitfab.ai";
+//#endregion
+//#region src/finalizers.d.ts
+/**
+ * Prebuilt `finalize` helpers for `withSpan({ finalize }, fn)`.
+ *
+ * A streaming function returns a live stream object that the caller consumes
+ * directly (SSE, a UI message stream). `withSpan` hands that object back
+ * unchanged; a `finalize` function tells it what serializable view to record
+ * as the span output instead of the raw, non-serializable stream.
+ */
+/**
+ * Drain a Vercel AI SDK streaming result into a serializable, replayable
+ * span output: `{ text, usage, finishReason, toolCalls, toolResults }`.
+ *
+ * Pass it straight to `withSpan`:
+ *
+ * ```ts
+ * import { finalizers } from "@bitfab/sdk"
+ *
+ * const traced = bitfab.withSpan(
+ *   "chat-turn",
+ *   { type: "agent", finalize: finalizers.aiSdk },
+ *   () => streamText({ model, messages }),
+ * )
+ * const result = traced() // caller still gets the live StreamTextResult
+ * return result.toUIMessageStreamResponse()
+ * ```
+ *
+ * Never throws: any field that is absent or rejects is recorded as
+ * `undefined` so finalize never drops the span.
+ */
+declare function aiSdk(result: unknown): Promise<Record<string, unknown>>;
+/**
+ * Collect a `ReadableStream`'s chunks into an array for the span output,
+ * via a `tee()` so the caller's branch is untouched. The caller MUST use
+ * the returned stream, not the original, since a stream can only be read
+ * once:
+ *
+ * ```ts
+ * let live: ReadableStream
+ * const traced = bitfab.withSpan(
+ *   "render",
+ *   { finalize: (r) => finalizers.readableStream(r, (s) => { live = s }) },
+ *   () => makeReadableStream(),
+ * )
+ * traced()
+ * return new Response(live!)
+ * ```
+ *
+ * Prefer `aiSdk` for the Vercel AI SDK, whose result tees internally and
+ * needs no caller rewiring.
+ */
+declare function readableStream(stream: ReadableStream, onLive: (live: ReadableStream) => void): Promise<{
+  chunks: unknown[];
+}>;
+declare const finalizers: {
+  aiSdk: typeof aiSdk;
+  readableStream: typeof readableStream;
+};
+//#endregion
+//#region src/replayRegistry.d.ts
+type ReplayFunction = (...args: any[]) => unknown | Promise<unknown>;
+type ReplayRegistryOptions = Omit<ReplayOptions, "onItemStart" | "onItemFinish" | "onProgress" | "onExperimentStart">;
+interface ReplayRegistryContext {
+  /** Values supplied through `--params` and repeated `--param name=value`. */
+  params: Readonly<Record<string, unknown>>;
+}
+type ReplayOptionsFactory = (context: ReplayRegistryContext) => ReplayRegistryOptions | Promise<ReplayRegistryOptions>;
+interface ReplayRegistration {
+  /** Client instance used by the production traced function. */
+  client: Bitfab;
+  /** The exact traced function production calls. */
+  fn: ReplayFunction;
+  /**
+   * Required for handler-instrumented or otherwise plain callables. Omit for a
+   * `withSpan`-wrapped function and the registry reads the wrapper's key.
+   */
+  traceFunctionKey?: string;
+  /**
+   * Per-function replay behavior and defaults. Put executable configuration
+   * such as `mockOverride` and `adaptInputs` here; command-line values override
+   * overlapping scalar defaults such as `mock` and `maxConcurrency`.
+   */
+  options?: ReplayRegistryOptions;
+  /** Build executable replay behavior from caller-supplied CLI parameters. */
+  optionsFactory?: ReplayOptionsFactory;
+}
+type ReplayRegistry = Record<string, ReplayRegistration>;
+/**
+ * Define the project-owned list of replayable functions.
+ *
+ * The registry is deliberately data-only: the SDK owns the replay CLI, so an
+ * SDK upgrade can add replay features without regenerating the project file.
+ */
+declare function defineReplayRegistry<TRegistry extends ReplayRegistry>(registry: TRegistry): TRegistry;
+/** One case to seed, in the shape `--seed` reads from JSON or JSONL. */
+interface SeedCase {
+  /** Arguments spread into the registered function at replay. */
+  input: unknown[];
+  /** The output this case should produce. */
+  expected?: unknown;
+  /** Recorded on the trace, for tracing a seeded case back to its source row. */
+  metadata?: Record<string, unknown>;
+  sessionId?: string;
+}
+interface SeedResult {
+  pipeline: string;
+  traceFunctionKey: string;
+  traceIds: string[];
+}
+interface ReseedRegistryResult {
+  pipeline: string;
+  traceFunctionKey: string;
+  reseeded: {
+    traceId: string;
+    previousRunTraceId: string;
+  }[];
+}
+declare function reseedFromRegistry(registry: ReplayRegistry, pipeline: string, traceIds: readonly string[]): Promise<ReseedRegistryResult>;
+/**
+ * Seed cases through an already-registered pipeline.
+ *
+ * The registration is the whole point: it already holds the client, the exact
+ * function production calls, and the trace function key replay selects by, so
+ * a seeded case is guaranteed to line up with the replay that will read it.
+ * Passing the registered function to `seedTrace` also means a case that cannot
+ * supply its required arguments is rejected here rather than at replay.
+ */
+declare function seedFromRegistry(registry: ReplayRegistry, pipeline: string, cases: readonly SeedCase[], options?: {
+  run?: boolean;
+}): Promise<SeedResult>;
+//#endregion
+export { AdaptInputsFn as $, RerunGradersResult as $n, SaveAssertionsAllParams as $t, SpanMethodDecoratorContext as A, ExperimentRollupResult as An, MockValue as Ar, ArchiveLabelTarget as At, TraceResponse as B, DatasetGraderRef as Bn, ReplayNodeIdentity as Br, LabelUpdate as Bt, NodeMethodDecorator as C, TracesClient as Cn, TokenUsage as Cr, BitfabLangGraphCallbackHandler as Ct, SeedCaseOptions as D, ExperimentJitter as Dn, MockOverrideCtx as Dr, GraderLabelSource as Dt, ReseedResult as E, ExperimentCodeChangeTotals as En, MockOverride as Er, GraderLabelOutcome as Et, getCurrentSpan as F, ExperimentsClient as Fn, MixedTracingError as Fr, LabelConfidence as Ft, SpanListResult as G, GraderRerunProgress as Gn, BamlExecutionResult as Gr, AssertionEvidenceParameter as Gt, ListedSpan as H, DatasetsClient as Hn, SelectiveReplayOptions as Hr, TraceLabels as Ht, getCurrentTrace as I, ListExperimentsParams as In, DbSnapshotConfig as Ir, LabelOutcome as It, RivetContextLike as J, GraderRerunTimeoutError as Jn, ApprovalState as Jr, AssertionGenerationStatus as Jt, SpansClient as K, GraderRerunResult as Kn, ProviderDefinition as Kr, AssertionGeneration as Kt, CaptureSurface as L, AddDatasetGradersResult as Ln, DbSnapshotProvider as Lr, LabelSource as Lt, WrapBAMLOptions as M, ExperimentStatus as Mn, NodeMatcher as Mr, HumanLabelOutcome as Mt, WrappedBamlFn as N, ExperimentTally as Nn, SpanNodeMeta as Nr, HumanLabelUpdate as Nt, SeedRunOptions as O, ExperimentPage as On, MockOverrideInput as Or, GraderLabelUpdate as Ot, getCurrentReplayBranch as P, ExperimentTotals as Pn, BitfabError as Pr, LabelAction as Pt, AdaptContext as Q, RerunGradersOptions as Qn, JustificationSpan as Qr, SaveAssertion as Qt, ActiveSpanContext as R, AddDatasetTracesResult as Rn, DbSnapshotRef as Rr, LabelStatus as Rt, DetachedTrace as S, TraceTargetOccurrence as Sn, SpanType as Sr, LangGraphIntegrationOptions as St, ReseedOptions as T, ExperimentCategoryTally as Tn, DbBranchTimings as Tr, GraderLabel as Tt, SpanListField as U, GraderRerun as Un, SelectiveReplayReport as Ur, Verdict as Ut, TracingProcessor as V, DatasetTraceIds as Vn, SelectiveReplayDecision as Vr, LabelsClient as Vt, SpanListParams as W, GraderRerunError as Wn, AllowedEnvVars as Wr, ArchiveAssertionsParams as Wt, RivetIntegrationOptions as X, RemoveDatasetGradersResult as Xn, Assignee as Xr, AssertionLabelEvidence as Xt, RivetEffectType as Y, ListDatasetsParams as Yn, Approver as Yr, AssertionGenerationTimeoutError as Yt, ReplayBranch as Z, RemoveDatasetTracesResult as Zn, Justification as Zr, GenerateAssertionsOptions as Zt, BitfabConfig as _, TraceAssertionsUpdate as _n, CapturedSpan as _r, ReplayInterruptSignal as _t, ReplayRegistryOptions as a, Scenario as an, VercelCallParams as ar, ReplayExperiment as at, CurrentSpan as b, TraceSearchResult as bn, SpanLookup as br, BitfabOpenAIAgentHandler as bt, SeedResult as c, ScenarioData as cn, BitfabClaudeAgentHandler as cr, ReplayItemStartProgress as ct, seedFromRegistry as d, ScenarioHistoryEntry as dn, AssertionCategorySummary as dr, ReplayProgressItem as dt, SaveAssertionsParams as en, SaveDatasetParams as er, BITFAB_PROGRESS_PREFIX as et, finalizers as f, ScenarioSource as fn, CategoriesClient as fr, ReplayResult as ft, Bitfab as g, TraceAssertionsResult as gn, SaveCategoryParams as gr, ReplayInterrupt as gt, CommitRef as h, TraceAssertionSource as hn, SaveAssertionCategoryParams as hr, serializeReplayResult as ht, ReplayRegistryContext as i, SaveScenarioParams as in, BitfabVercelAiHandler as ir, ReplayError as it, SpanOptions as j, ExperimentRunBy as jn, NO_MOCK_OVERRIDE as jr, AssertionVerdict as jt, SpanMethodDecorator as k, ExperimentRollup as kn, MockOverrideResolver as kr, GradersClient as kt, defineReplayRegistry as l, ScenarioDataAppend as ln, AssertionCategoriesClient as lr, ReplayOptions as lt, __version__ as m, TraceAssertion as mn, CategorySummary as mr, reportReplayProgress as mt, ReplayRegistration as n, SaveScenarioData as nn, UpdateDatasetParams as nr, DbBranchReplayError as nt, ReseedRegistryResult as o, ScenarioAction as on, VercelGenerateResult as or, ReplayItem as ot, DEFAULT_SERVICE_URL as p, ScenarioTrigger as pn, Category as pr, TraceIngestionType as pt, BitfabRivetIntegration as q, GraderRerunStatus as qn, ApprovalFields as qr, AssertionGenerationError as qt, ReplayRegistry as r, SaveScenarioHistoryEntry as rn, BitfabLanguageModelMiddleware as rr, MockStrategy as rt, SeedCase as s, ScenarioActualOutcome as sn, VercelStreamResult as sr, ReplayItemFinishProgress as st, ReplayOptionsFactory as t, SaveScenarioActualOutcome as tn, SaveDatasetResult as tr, DbBranchOptions as tt, reseedFromRegistry as u, ScenarioDataOrigin as un, AssertionCategory as ur, ReplayProgress as ut, BitfabFunction as v, TraceSearchFilters as vn, CodeChangeFile as vr, OrganizationMember as vt, NodeOptions as w, Experiment as wn, flushTraces as wr, GetGraderLabelsParams as wt, CurrentTrace as x, TraceTarget as xn, SpanOccurrence as xr, BitfabLangGraphIntegration as xt, CaptureWhen as y, TraceSearchParams as yn, HttpClient as yr, OrganizationMembersClient as yt, BitfabOpenAITracingProcessor as z, Dataset as zn, SUPPORTED_PROVIDERS as zr, LabelTarget as zt };