@bitfab/sdk 0.15.0 → 0.16.1

package/dist/index.d.cts

@@ -343,9 +343,9 @@ declare class ReplayEnvironment {
 type MockStrategy = "none" | "all" | "marked";
 interface ReplayOptions {
     /**
-     * Maximum number of traces to replay (1–100, default 5). Mutually
-     * exclusive with `traceIds` — an explicit ID list already determines how
-     * many traces replay, so passing both throws.
+     * Maximum number of traces to replay (1-100, default 5). Ignored when
+     * `traceIds` is passed (with a warning): an explicit ID list already
+     * determines how many traces replay.
      */
     limit?: number;
     /** Optional list of specific trace IDs to replay (max 100). */
@@ -380,7 +380,46 @@ interface ReplayOptions {
     environment?: ReplayEnvironment;
     /** Group ID to associate this replay with an experiment group for live streaming in Studio. */
     experimentGroupId?: string;
+    /**
+     * 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[];
+}
+/** Per-trace context passed to {@link ReplayOptions.adaptInputs}. */
+interface AdaptContext {
+    /** Bitfab trace ID of the historical trace being replayed. */
+    traceId: string;
+    /** External span ID the recorded inputs were read from. */
+    sourceSpanId: string;
 }
+/**
+ * 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> {
     /** Trace ID of the new trace created during replay. */
     traceId: string | null;
@@ -920,9 +959,9 @@ declare class Bitfab {
      *
      * @param traceFunctionKey - The trace function key to replay
      * @param fn - The function to replay (must be the return value of `withSpan`)
-     * @param options - Optional replay options. `limit` and `traceIds` are
-     *   mutually exclusive — an explicit ID list already determines how many
-     *   traces replay, so passing both throws a BitfabError.
+     * @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, testRunId, and testRunUrl
      */
     replay<TReturn>(traceFunctionKey: string, fn: (...args: any[]) => TReturn | Promise<TReturn>, options?: ReplayOptions): Promise<ReplayResult<TReturn>>;
@@ -988,7 +1027,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.15.0";
+declare const __version__ = "0.16.1";
 
 /**
  * Constants for the Bitfab SDK.
@@ -998,4 +1037,4 @@ declare const __version__ = "0.15.0";
  */
 declare const DEFAULT_SERVICE_URL = "https://bitfab.ai";
 
-export { type ActiveSpanContext, type AllowedEnvVars, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler, BitfabOpenAITracingProcessor, type CodeChangeFile, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, type MockStrategy, type ProviderDefinition, ReplayEnvironment, type ReplayEnvironmentSnapshot, type ReplayItem, type ReplayOptions, type ReplayResult, SUPPORTED_PROVIDERS, type SpanOptions, type SpanType, type TokenUsage, type TraceResponse, type TracingProcessor, type WrapBAMLOptions, type WrappedBamlFn, __version__, flushTraces, getCurrentSpan, getCurrentTrace };
+export { type ActiveSpanContext, type AdaptContext, type AdaptInputsFn, type AllowedEnvVars, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler, BitfabOpenAITracingProcessor, type CodeChangeFile, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, type MockStrategy, type ProviderDefinition, ReplayEnvironment, type ReplayEnvironmentSnapshot, type ReplayItem, type ReplayOptions, type ReplayResult, SUPPORTED_PROVIDERS, type SpanOptions, type SpanType, type TokenUsage, type TraceResponse, type TracingProcessor, type WrapBAMLOptions, type WrappedBamlFn, __version__, flushTraces, getCurrentSpan, getCurrentTrace };

package/dist/index.d.ts

@@ -343,9 +343,9 @@ declare class ReplayEnvironment {
 type MockStrategy = "none" | "all" | "marked";
 interface ReplayOptions {
     /**
-     * Maximum number of traces to replay (1–100, default 5). Mutually
-     * exclusive with `traceIds` — an explicit ID list already determines how
-     * many traces replay, so passing both throws.
+     * Maximum number of traces to replay (1-100, default 5). Ignored when
+     * `traceIds` is passed (with a warning): an explicit ID list already
+     * determines how many traces replay.
      */
     limit?: number;
     /** Optional list of specific trace IDs to replay (max 100). */
@@ -380,7 +380,46 @@ interface ReplayOptions {
     environment?: ReplayEnvironment;
     /** Group ID to associate this replay with an experiment group for live streaming in Studio. */
     experimentGroupId?: string;
+    /**
+     * 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[];
+}
+/** Per-trace context passed to {@link ReplayOptions.adaptInputs}. */
+interface AdaptContext {
+    /** Bitfab trace ID of the historical trace being replayed. */
+    traceId: string;
+    /** External span ID the recorded inputs were read from. */
+    sourceSpanId: string;
 }
+/**
+ * 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> {
     /** Trace ID of the new trace created during replay. */
     traceId: string | null;
@@ -920,9 +959,9 @@ declare class Bitfab {
      *
      * @param traceFunctionKey - The trace function key to replay
      * @param fn - The function to replay (must be the return value of `withSpan`)
-     * @param options - Optional replay options. `limit` and `traceIds` are
-     *   mutually exclusive — an explicit ID list already determines how many
-     *   traces replay, so passing both throws a BitfabError.
+     * @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, testRunId, and testRunUrl
      */
     replay<TReturn>(traceFunctionKey: string, fn: (...args: any[]) => TReturn | Promise<TReturn>, options?: ReplayOptions): Promise<ReplayResult<TReturn>>;
@@ -988,7 +1027,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.15.0";
+declare const __version__ = "0.16.1";
 
 /**
  * Constants for the Bitfab SDK.
@@ -998,4 +1037,4 @@ declare const __version__ = "0.15.0";
  */
 declare const DEFAULT_SERVICE_URL = "https://bitfab.ai";
 
-export { type ActiveSpanContext, type AllowedEnvVars, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler, BitfabOpenAITracingProcessor, type CodeChangeFile, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, type MockStrategy, type ProviderDefinition, ReplayEnvironment, type ReplayEnvironmentSnapshot, type ReplayItem, type ReplayOptions, type ReplayResult, SUPPORTED_PROVIDERS, type SpanOptions, type SpanType, type TokenUsage, type TraceResponse, type TracingProcessor, type WrapBAMLOptions, type WrappedBamlFn, __version__, flushTraces, getCurrentSpan, getCurrentTrace };
+export { type ActiveSpanContext, type AdaptContext, type AdaptInputsFn, type AllowedEnvVars, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler, BitfabOpenAITracingProcessor, type CodeChangeFile, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, type MockStrategy, type ProviderDefinition, ReplayEnvironment, type ReplayEnvironmentSnapshot, type ReplayItem, type ReplayOptions, type ReplayResult, SUPPORTED_PROVIDERS, type SpanOptions, type SpanType, type TokenUsage, type TraceResponse, type TracingProcessor, type WrapBAMLOptions, type WrappedBamlFn, __version__, flushTraces, getCurrentSpan, getCurrentTrace };

package/dist/index.js

@@ -11,7 +11,7 @@ import {
   flushTraces,
   getCurrentSpan,
   getCurrentTrace
-} from "./chunk-YPG3XIG4.js";
+} from "./chunk-P4WFJ5O3.js";
 import {
   BitfabError
 } from "./chunk-QT7HWOKU.js";

package/dist/node.cjs

@@ -225,7 +225,7 @@ function buildMockTree(rootNode) {
   }
   return { spans };
 }
-async function processItem(httpClient, serverItem, fn, testRunId, mockStrategy, environment) {
+async function processItem(httpClient, serverItem, fn, testRunId, mockStrategy, environment, adaptInputs) {
   const lease = environment ? serverItem.dbBranchLease : void 0;
   let inputs = [];
   let originalOutput;
@@ -238,6 +238,12 @@ async function processItem(httpClient, serverItem, fn, testRunId, mockStrategy,
     const spanData = span.rawData?.span_data ?? {};
     inputs = deserializeInputs(spanData);
     originalOutput = deserializeOutput(spanData);
+    if (adaptInputs) {
+      inputs = adaptInputs(inputs, {
+        traceId: serverItem.traceId,
+        sourceSpanId: serverItem.externalSpanId
+      });
+    }
     let mockTree;
     if (mockStrategy === "all" || mockStrategy === "marked") {
       const treeResponse = await httpClient.getSpanTree(
@@ -318,9 +324,12 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options) {
     }
   }
   if (options?.limit !== void 0 && options?.traceIds !== void 0) {
-    throw new BitfabError(
-      "Pass either limit or traceIds, not both: an explicit trace ID list already determines how many traces replay."
-    );
+    try {
+      console.warn(
+        "Bitfab: limit is ignored when traceIds is passed: the explicit trace ID list already determines how many traces replay."
+      );
+    } catch {
+    }
   }
   await replayContextReady;
   const {
@@ -348,7 +357,8 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options) {
       fn,
       testRunId,
       mockStrategy,
-      options?.environment
+      options?.environment,
+      options?.adaptInputs
     )
   );
   const resultItems = await mapWithConcurrency(tasks, maxConcurrency);
@@ -436,7 +446,7 @@ registerAsyncLocalStorageClass(
 );
 
 // src/version.generated.ts
-var __version__ = "0.15.0";
+var __version__ = "0.16.1";
 
 // src/constants.ts
 var DEFAULT_SERVICE_URL = "https://bitfab.ai";
@@ -3226,9 +3236,9 @@ var Bitfab = class {
    *
    * @param traceFunctionKey - The trace function key to replay
    * @param fn - The function to replay (must be the return value of `withSpan`)
-   * @param options - Optional replay options. `limit` and `traceIds` are
-   *   mutually exclusive — an explicit ID list already determines how many
-   *   traces replay, so passing both throws a BitfabError.
+   * @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, testRunId, and testRunUrl
    */
   async replay(traceFunctionKey, fn, options) {