bitfab 0.11.0 → 0.11.5

package/dist/index.d.cts

@@ -165,6 +165,24 @@ declare class BitfabError extends Error {
  * @param timeoutMs - Maximum time to wait in milliseconds (default: 5000)
  */
 declare function flushTraces(timeoutMs?: number): 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;
+}
 
 /**
  * LangGraph/LangChain callback handler for Bitfab tracing.
@@ -231,6 +249,61 @@ declare class BitfabLangGraphCallbackHandler {
     handleRetrieverError(error: unknown, runId: string): Promise<void>;
 }
 
+/**
+ * Replay historical traces through a function and create a test run.
+ *
+ * The replay flow has three phases:
+ * 1. Start — fetches historical traces from the server and creates a test run
+ * 2. Execute — re-runs each trace's inputs through the provided function locally
+ * 3. Complete — marks the test run as completed on the server
+ */
+
+interface ReplayOptions {
+    /** Maximum number of traces to replay (1–100, default 5). */
+    limit?: number;
+    /** Optional list of specific trace IDs to replay. */
+    traceIds?: string[];
+    /** Maximum number of items to process in parallel. 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.
+     */
+    codeChangeDescription?: string;
+    /**
+     * 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`).
+     */
+    codeChangeFiles?: CodeChangeFile[];
+}
+interface ReplayItem<T> {
+    /** Deserialized inputs from the original trace. */
+    input: unknown[];
+    /** The result returned by the function during replay, or undefined on error. */
+    result: T | undefined;
+    /** The original output from the historical trace. */
+    originalOutput: unknown;
+    /** Error message if the function threw, or null on success. */
+    error: string | null;
+    /** Original trace duration in milliseconds, or null if timestamps are missing. */
+    durationMs: number | null;
+    /** Token usage from the original trace, or null if not captured. */
+    tokens: TokenUsage | null;
+    /** Model name from the original trace, or null if not captured. */
+    model: string | null;
+}
+
+interface ReplayResult<T> {
+    /** Individual replay items with inputs, results, and comparison data. */
+    items: ReplayItem<T>[];
+    /** The test run ID created on the server. */
+    testRunId: string;
+    /** Full URL to view the test run in the dashboard. */
+    testRunUrl: string;
+}
+
 /**
  * Tracing utilities for external trace submission to Bitfab.
  *
@@ -665,16 +738,9 @@ declare class Bitfab {
         limit?: number;
         traceIds?: string[];
         maxConcurrency?: number;
-    }): Promise<{
-        items: Array<{
-            input: unknown[];
-            result: TReturn | undefined;
-            originalOutput: unknown;
-            error: string | null;
-        }>;
-        testRunId: string;
-        testRunUrl: string;
-    }>;
+        codeChangeDescription?: string;
+        codeChangeFiles?: CodeChangeFile[];
+    }): Promise<ReplayResult<TReturn>>;
 }
 /**
  * Represents a Bitfab function that can wrap user functions for tracing.
@@ -737,7 +803,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.11.0";
+declare const __version__ = "0.11.5";
 
 /**
  * Constants for the Bitfab SDK.
@@ -747,40 +813,4 @@ declare const __version__ = "0.11.0";
  */
 declare const DEFAULT_SERVICE_URL = "https://bitfab.ai";
 
-/**
- * Replay historical traces through a function and create a test run.
- *
- * The replay flow has three phases:
- * 1. Start — fetches historical traces from the server and creates a test run
- * 2. Execute — re-runs each trace's inputs through the provided function locally
- * 3. Complete — marks the test run as completed on the server
- */
-
-interface ReplayOptions {
-    /** Maximum number of traces to replay (1–100, default 5). */
-    limit?: number;
-    /** Optional list of specific trace IDs to replay. */
-    traceIds?: string[];
-    /** Maximum number of items to process in parallel. Set to 1 for sequential. Default 10. */
-    maxConcurrency?: number;
-}
-interface ReplayItem<T> {
-    /** Deserialized inputs from the original trace. */
-    input: unknown[];
-    /** The result returned by the function during replay, or undefined on error. */
-    result: T | undefined;
-    /** The original output from the historical trace. */
-    originalOutput: unknown;
-    /** Error message if the function threw, or null on success. */
-    error: string | null;
-}
-interface ReplayResult<T> {
-    /** Individual replay items with inputs, results, and comparison data. */
-    items: ReplayItem<T>[];
-    /** The test run ID created on the server. */
-    testRunId: string;
-    /** Full URL to view the test run in the dashboard. */
-    testRunUrl: string;
-}
-
-export { type ActiveSpanContext, type AllowedEnvVars, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler, BitfabOpenAITracingProcessor, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type ProviderDefinition, type ReplayItem, type ReplayOptions, type ReplayResult, type SpanOptions, type SpanType, type TraceResponse, type TracingProcessor, type WrapBAMLOptions, type WrappedBamlFn, __version__, flushTraces, getCurrentSpan, getCurrentTrace };
+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 ProviderDefinition, type ReplayItem, type ReplayOptions, type ReplayResult, type SpanOptions, type SpanType, type TokenUsage, type TraceResponse, type TracingProcessor, type WrapBAMLOptions, type WrappedBamlFn, __version__, flushTraces, getCurrentSpan, getCurrentTrace };

package/dist/index.d.ts

@@ -165,6 +165,24 @@ declare class BitfabError extends Error {
  * @param timeoutMs - Maximum time to wait in milliseconds (default: 5000)
  */
 declare function flushTraces(timeoutMs?: number): 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;
+}
 
 /**
  * LangGraph/LangChain callback handler for Bitfab tracing.
@@ -231,6 +249,61 @@ declare class BitfabLangGraphCallbackHandler {
     handleRetrieverError(error: unknown, runId: string): Promise<void>;
 }
 
+/**
+ * Replay historical traces through a function and create a test run.
+ *
+ * The replay flow has three phases:
+ * 1. Start — fetches historical traces from the server and creates a test run
+ * 2. Execute — re-runs each trace's inputs through the provided function locally
+ * 3. Complete — marks the test run as completed on the server
+ */
+
+interface ReplayOptions {
+    /** Maximum number of traces to replay (1–100, default 5). */
+    limit?: number;
+    /** Optional list of specific trace IDs to replay. */
+    traceIds?: string[];
+    /** Maximum number of items to process in parallel. 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.
+     */
+    codeChangeDescription?: string;
+    /**
+     * 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`).
+     */
+    codeChangeFiles?: CodeChangeFile[];
+}
+interface ReplayItem<T> {
+    /** Deserialized inputs from the original trace. */
+    input: unknown[];
+    /** The result returned by the function during replay, or undefined on error. */
+    result: T | undefined;
+    /** The original output from the historical trace. */
+    originalOutput: unknown;
+    /** Error message if the function threw, or null on success. */
+    error: string | null;
+    /** Original trace duration in milliseconds, or null if timestamps are missing. */
+    durationMs: number | null;
+    /** Token usage from the original trace, or null if not captured. */
+    tokens: TokenUsage | null;
+    /** Model name from the original trace, or null if not captured. */
+    model: string | null;
+}
+
+interface ReplayResult<T> {
+    /** Individual replay items with inputs, results, and comparison data. */
+    items: ReplayItem<T>[];
+    /** The test run ID created on the server. */
+    testRunId: string;
+    /** Full URL to view the test run in the dashboard. */
+    testRunUrl: string;
+}
+
 /**
  * Tracing utilities for external trace submission to Bitfab.
  *
@@ -665,16 +738,9 @@ declare class Bitfab {
         limit?: number;
         traceIds?: string[];
         maxConcurrency?: number;
-    }): Promise<{
-        items: Array<{
-            input: unknown[];
-            result: TReturn | undefined;
-            originalOutput: unknown;
-            error: string | null;
-        }>;
-        testRunId: string;
-        testRunUrl: string;
-    }>;
+        codeChangeDescription?: string;
+        codeChangeFiles?: CodeChangeFile[];
+    }): Promise<ReplayResult<TReturn>>;
 }
 /**
  * Represents a Bitfab function that can wrap user functions for tracing.
@@ -737,7 +803,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.11.0";
+declare const __version__ = "0.11.5";
 
 /**
  * Constants for the Bitfab SDK.
@@ -747,40 +813,4 @@ declare const __version__ = "0.11.0";
  */
 declare const DEFAULT_SERVICE_URL = "https://bitfab.ai";
 
-/**
- * Replay historical traces through a function and create a test run.
- *
- * The replay flow has three phases:
- * 1. Start — fetches historical traces from the server and creates a test run
- * 2. Execute — re-runs each trace's inputs through the provided function locally
- * 3. Complete — marks the test run as completed on the server
- */
-
-interface ReplayOptions {
-    /** Maximum number of traces to replay (1–100, default 5). */
-    limit?: number;
-    /** Optional list of specific trace IDs to replay. */
-    traceIds?: string[];
-    /** Maximum number of items to process in parallel. Set to 1 for sequential. Default 10. */
-    maxConcurrency?: number;
-}
-interface ReplayItem<T> {
-    /** Deserialized inputs from the original trace. */
-    input: unknown[];
-    /** The result returned by the function during replay, or undefined on error. */
-    result: T | undefined;
-    /** The original output from the historical trace. */
-    originalOutput: unknown;
-    /** Error message if the function threw, or null on success. */
-    error: string | null;
-}
-interface ReplayResult<T> {
-    /** Individual replay items with inputs, results, and comparison data. */
-    items: ReplayItem<T>[];
-    /** The test run ID created on the server. */
-    testRunId: string;
-    /** Full URL to view the test run in the dashboard. */
-    testRunUrl: string;
-}
-
-export { type ActiveSpanContext, type AllowedEnvVars, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler, BitfabOpenAITracingProcessor, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type ProviderDefinition, type ReplayItem, type ReplayOptions, type ReplayResult, type SpanOptions, type SpanType, type TraceResponse, type TracingProcessor, type WrapBAMLOptions, type WrappedBamlFn, __version__, flushTraces, getCurrentSpan, getCurrentTrace };
+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 ProviderDefinition, type ReplayItem, type ReplayOptions, type ReplayResult, type SpanOptions, type SpanType, type TokenUsage, type TraceResponse, type TracingProcessor, type WrapBAMLOptions, type WrappedBamlFn, __version__, flushTraces, getCurrentSpan, getCurrentTrace };

package/dist/index.js

@@ -6,13 +6,13 @@ import {
   BitfabOpenAITracingProcessor,
   getCurrentSpan,
   getCurrentTrace
-} from "./chunk-6EZCV5TU.js";
+} from "./chunk-GWHHP5PL.js";
 import {
   BitfabError,
   DEFAULT_SERVICE_URL,
   __version__,
   flushTraces
-} from "./chunk-C4KRLEXZ.js";
+} from "./chunk-KSUI74KL.js";
 export {
   Bitfab,
   BitfabClaudeAgentHandler,

package/dist/node.cjs

@@ -81,7 +81,7 @@ var __version__;
 var init_version_generated = __esm({
   "src/version.generated.ts"() {
     "use strict";
-    __version__ = "0.11.0";
+    __version__ = "0.11.5";
   }
 });
 
@@ -285,11 +285,17 @@ var init_http = __esm({
        * Start a replay session by fetching historical traces.
        * Blocking call — creates a test run and returns lightweight item references.
        */
-      async startReplay(traceFunctionKey, limit, traceIds) {
+      async startReplay(traceFunctionKey, limit, traceIds, codeChangeDescription, codeChangeFiles) {
         const payload = { traceFunctionKey, limit };
         if (traceIds) {
           payload.traceIds = traceIds;
         }
+        if (codeChangeDescription !== void 0) {
+          payload.codeChangeDescription = codeChangeDescription;
+        }
+        if (codeChangeFiles !== void 0) {
+          payload.codeChangeFiles = codeChangeFiles;
+        }
         return this.request("/api/sdk/replay/start", payload, {
           timeout: 3e4
         });
@@ -441,7 +447,15 @@ async function processItem(httpClient, serverItem, fn, testRunId) {
   } catch (e) {
     error = e instanceof Error ? e.message : String(e);
   }
-  return { input: inputs, result, originalOutput, error };
+  return {
+    input: inputs,
+    result,
+    originalOutput,
+    error,
+    durationMs: serverItem.durationMs ?? null,
+    tokens: serverItem.tokens ?? null,
+    model: serverItem.model ?? null
+  };
 }
 async function mapWithConcurrency(tasks, maxConcurrency) {
   const results = new Array(tasks.length);
@@ -468,7 +482,9 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options) {
   } = await httpClient.startReplay(
     traceFunctionKey,
     options?.limit ?? 5,
-    options?.traceIds
+    options?.traceIds,
+    options?.codeChangeDescription,
+    options?.codeChangeFiles
   );
   const maxConcurrency = options?.maxConcurrency ?? 10;
   const tasks = serverItems.map(
@@ -1995,6 +2011,65 @@ function runWithSpanStack(stack, fn) {
     throw error;
   }
 }
+function isAsyncGenerator(value) {
+  if (value === null || typeof value !== "object") {
+    return false;
+  }
+  const candidate = value;
+  return typeof candidate.next === "function" && typeof candidate.return === "function" && typeof candidate.throw === "function" && typeof candidate[Symbol.asyncIterator] === "function";
+}
+function wrapAsyncGenerator(source, spanStack, sendSpan) {
+  const yielded = [];
+  let returnValue;
+  let finalized = false;
+  const finalize = (errorMsg) => {
+    if (finalized) {
+      return;
+    }
+    finalized = true;
+    void sendSpan({
+      result: { yielded, return: returnValue },
+      ...errorMsg && { error: errorMsg }
+    });
+  };
+  const step = (method, arg) => runWithSpanStack(spanStack, () => {
+    const op = source[method];
+    return op.call(source, arg);
+  });
+  const handle = async (method, arg) => {
+    try {
+      const result = await step(method, arg);
+      if (result.done) {
+        returnValue = result.value;
+        finalize();
+      } else {
+        yielded.push(result.value);
+      }
+      return result;
+    } catch (error) {
+      finalize(error instanceof Error ? error.message : String(error));
+      throw error;
+    }
+  };
+  const wrapped = {
+    next(arg) {
+      return handle("next", arg);
+    },
+    return(value) {
+      return handle("return", value);
+    },
+    throw(err) {
+      return handle("throw", err);
+    },
+    [Symbol.asyncIterator]() {
+      return wrapped;
+    },
+    [Symbol.asyncDispose]() {
+      return handle("return", void 0).then(() => void 0);
+    }
+  };
+  return wrapped;
+}
 var cachedCollectorClass;
 async function loadCollectorClass() {
   if (cachedCollectorClass !== void 0) {
@@ -2487,10 +2562,14 @@ var Bitfab = class {
       const inputs = args;
       const startedAt = (/* @__PURE__ */ new Date()).toISOString();
       if (isRootSpan && !activeTraceStates.has(traceId)) {
+        const replayCtxAtRoot = getReplayContext();
         activeTraceStates.set(traceId, {
           traceId,
           startedAt,
-          contexts: []
+          contexts: [],
+          ...replayCtxAtRoot?.testRunId && {
+            testRunId: replayCtxAtRoot.testRunId
+          }
         });
         pendingSpanPromises.set(traceId, []);
       }
@@ -2537,7 +2616,8 @@ var Bitfab = class {
               endedAt,
               sessionId: traceState?.sessionId,
               metadata: traceState?.metadata,
-              contexts: traceState?.contexts ?? []
+              contexts: traceState?.contexts ?? [],
+              testRunId: traceState?.testRunId
             });
             activeTraceStates.delete(traceId);
           } else {
@@ -2565,6 +2645,9 @@ var Bitfab = class {
             throw error;
           });
         }
+        if (isAsyncGenerator(result)) {
+          return wrapAsyncGenerator(result, newStack, sendSpan);
+        }
         void sendSpan({ result });
         return result;
       };
@@ -2617,7 +2700,8 @@ var Bitfab = class {
       traceFunctionKey: params.traceFunctionKey,
       externalTrace: rawTrace,
       completed: true,
-      ...params.sessionId && { sessionId: params.sessionId }
+      ...params.sessionId && { sessionId: params.sessionId },
+      ...params.testRunId && { testRunId: params.testRunId }
     });
   }
   /**