@bitfab/sdk 0.16.2 → 0.18.0

package/dist/index.d.cts

@@ -147,9 +147,12 @@ declare class BitfabClaudeAgentHandler {
 /**
  * Per-trace database snapshot ref capture.
  *
- * When the customer configures `dbSnapshot`, every root span carries a
- * `DbSnapshotRef` that pins the DB state at trace open by wall-clock
- * timestamp. The Bitfab service uses that timestamp at replay time to
+ * 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"];
@@ -159,14 +162,19 @@ interface DbSnapshotConfig {
     provider: DbSnapshotProvider;
 }
 interface DbSnapshotRef {
-    provider: DbSnapshotProvider;
     /**
      * 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.
+     * 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;
 }
 
 /**
@@ -970,11 +978,15 @@ declare class Bitfab {
      * Fetches the last N traces for the given trace function key, re-runs each
      * through the provided function, and returns comparison data.
      *
-     * The function must have been wrapped with `withSpan` — replay injects
-     * `testRunId` via async context so new spans are linked to the test run.
+     * 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 test run. 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 replay (must be the return value of `withSpan`)
+     * @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.
@@ -1043,7 +1055,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.16.2";
+declare const __version__ = "0.18.0";
 
 /**
  * Constants for the Bitfab SDK.

package/dist/index.d.ts

@@ -147,9 +147,12 @@ declare class BitfabClaudeAgentHandler {
 /**
  * Per-trace database snapshot ref capture.
  *
- * When the customer configures `dbSnapshot`, every root span carries a
- * `DbSnapshotRef` that pins the DB state at trace open by wall-clock
- * timestamp. The Bitfab service uses that timestamp at replay time to
+ * 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"];
@@ -159,14 +162,19 @@ interface DbSnapshotConfig {
     provider: DbSnapshotProvider;
 }
 interface DbSnapshotRef {
-    provider: DbSnapshotProvider;
     /**
      * 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.
+     * 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;
 }
 
 /**
@@ -970,11 +978,15 @@ declare class Bitfab {
      * Fetches the last N traces for the given trace function key, re-runs each
      * through the provided function, and returns comparison data.
      *
-     * The function must have been wrapped with `withSpan` — replay injects
-     * `testRunId` via async context so new spans are linked to the test run.
+     * 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 test run. 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 replay (must be the return value of `withSpan`)
+     * @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.
@@ -1043,7 +1055,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.16.2";
+declare const __version__ = "0.18.0";
 
 /**
  * Constants for the Bitfab SDK.

package/dist/index.js

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

package/dist/node.cjs

@@ -447,7 +447,7 @@ registerAsyncLocalStorageClass(
 );
 
 // src/version.generated.ts
-var __version__ = "0.16.2";
+var __version__ = "0.18.0";
 
 // src/constants.ts
 var DEFAULT_SERVICE_URL = "https://bitfab.ai";
@@ -1562,8 +1562,8 @@ function validateDbSnapshotConfig(config) {
 }
 function buildSnapshotRef(config, sdkWallClockBeforeFn) {
   return {
-    provider: config.provider,
-    sdkWallClockBeforeFn
+    sdkWallClockBeforeFn,
+    ...config && { provider: config.provider }
   };
 }
 
@@ -2938,7 +2938,7 @@ var Bitfab = class {
       const startedAt = (/* @__PURE__ */ new Date()).toISOString();
       if (isRootSpan && !activeTraceStates.has(traceId)) {
         const replayCtxAtRoot = getReplayContext();
-        const dbSnapshotRef = self.dbSnapshot ? buildSnapshotRef(self.dbSnapshot, startedAt) : void 0;
+        const dbSnapshotRef = buildSnapshotRef(self.dbSnapshot, startedAt);
         activeTraceStates.set(traceId, {
           traceId,
           startedAt,
@@ -2949,7 +2949,7 @@ var Bitfab = class {
           ...replayCtxAtRoot?.inputSourceTraceId && {
             inputSourceTraceId: replayCtxAtRoot.inputSourceTraceId
           },
-          ...dbSnapshotRef && { dbSnapshotRef }
+          dbSnapshotRef
         });
         pendingSpanPromises.set(traceId, []);
       }
@@ -3079,6 +3079,9 @@ var Bitfab = class {
       };
       return runWithSpanStack(newStack, executeWithContext);
     };
+    Object.defineProperty(wrappedFn, "_bitfabTraceFunctionKey", {
+      value: traceFunctionKey
+    });
     return wrappedFn;
   }
   /**
@@ -3250,23 +3253,40 @@ var Bitfab = class {
    * Fetches the last N traces for the given trace function key, re-runs each
    * through the provided function, and returns comparison data.
    *
-   * The function must have been wrapped with `withSpan` — replay injects
-   * `testRunId` via async context so new spans are linked to the test run.
+   * 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 test run. 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 replay (must be the return value of `withSpan`)
+   * @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, testRunId, and testRunUrl
    */
   async replay(traceFunctionKey, fn, options) {
+    const wrappedKey = fn._bitfabTraceFunctionKey;
+    let replayFn = fn;
+    if (wrappedKey === void 0) {
+      replayFn = this.withSpan(
+        traceFunctionKey,
+        { name: fn.name || "Replay", type: "agent" },
+        fn
+      );
+    } else if (wrappedKey !== traceFunctionKey) {
+      throw new BitfabError(
+        `Function is wrapped with trace function key '${wrappedKey}' but replay was called with '${traceFunctionKey}'. Pass matching keys, or pass the unwrapped function to replay it under the explicit key.`
+      );
+    }
     const { replay: doReplay } = await Promise.resolve().then(() => (init_replay(), replay_exports));
     return doReplay(
       this.httpClient,
       this.serviceUrl,
       traceFunctionKey,
-      fn,
+      replayFn,
       options
     );
   }