bitfab 0.11.6 → 0.12.0

package/dist/index.d.cts

@@ -258,6 +258,7 @@ declare class BitfabLangGraphCallbackHandler {
  * 3. Complete — marks the test run as completed on the server
  */
 
+type MockStrategy = "none" | "all" | "marked";
 interface ReplayOptions {
     /** Maximum number of traces to replay (1–100, default 5). */
     limit?: number;
@@ -277,6 +278,13 @@ interface ReplayOptions {
      * files (`before`) or deleted files (`after`).
      */
     codeChangeFiles?: CodeChangeFile[];
+    /**
+     * Mock strategy for child spans during replay.
+     * - "none": everything runs real code (default)
+     * - "all": every child withSpan returns historical output
+     * - "marked": only spans tagged with { mockOnReplay: true } in SpanOptions are mocked
+     */
+    mock?: MockStrategy;
 }
 interface ReplayItem<T> {
     /** Deserialized inputs from the original trace. */
@@ -533,6 +541,16 @@ interface SpanOptions {
      * The type of span. Defaults to "custom" if not specified.
      */
     type?: SpanType;
+    /**
+     * 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.
+     */
+    mockOnReplay?: boolean;
 }
 
 /**
@@ -740,6 +758,7 @@ declare class Bitfab {
         maxConcurrency?: number;
         codeChangeDescription?: string;
         codeChangeFiles?: CodeChangeFile[];
+        mock?: "none" | "all" | "marked";
     }): Promise<ReplayResult<TReturn>>;
 }
 /**
@@ -803,7 +822,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.11.6";
+declare const __version__ = "0.12.0";
 
 /**
  * Constants for the Bitfab SDK.
@@ -813,4 +832,4 @@ declare const __version__ = "0.11.6";
  */
 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 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 };
+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 MockStrategy, 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

@@ -258,6 +258,7 @@ declare class BitfabLangGraphCallbackHandler {
  * 3. Complete — marks the test run as completed on the server
  */
 
+type MockStrategy = "none" | "all" | "marked";
 interface ReplayOptions {
     /** Maximum number of traces to replay (1–100, default 5). */
     limit?: number;
@@ -277,6 +278,13 @@ interface ReplayOptions {
      * files (`before`) or deleted files (`after`).
      */
     codeChangeFiles?: CodeChangeFile[];
+    /**
+     * Mock strategy for child spans during replay.
+     * - "none": everything runs real code (default)
+     * - "all": every child withSpan returns historical output
+     * - "marked": only spans tagged with { mockOnReplay: true } in SpanOptions are mocked
+     */
+    mock?: MockStrategy;
 }
 interface ReplayItem<T> {
     /** Deserialized inputs from the original trace. */
@@ -533,6 +541,16 @@ interface SpanOptions {
      * The type of span. Defaults to "custom" if not specified.
      */
     type?: SpanType;
+    /**
+     * 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.
+     */
+    mockOnReplay?: boolean;
 }
 
 /**
@@ -740,6 +758,7 @@ declare class Bitfab {
         maxConcurrency?: number;
         codeChangeDescription?: string;
         codeChangeFiles?: CodeChangeFile[];
+        mock?: "none" | "all" | "marked";
     }): Promise<ReplayResult<TReturn>>;
 }
 /**
@@ -803,7 +822,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.11.6";
+declare const __version__ = "0.12.0";
 
 /**
  * Constants for the Bitfab SDK.
@@ -813,4 +832,4 @@ declare const __version__ = "0.11.6";
  */
 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 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 };
+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 MockStrategy, 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-MTHBHBOD.js";
+} from "./chunk-QUCK3IU2.js";
 import {
   BitfabError,
   DEFAULT_SERVICE_URL,
   __version__,
   flushTraces
-} from "./chunk-VOSASRED.js";
+} from "./chunk-VMJPNYAG.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.6";
+    __version__ = "0.12.0";
   }
 });
 
@@ -336,6 +336,42 @@ var init_http = __esm({
           clearTimeout(timeoutId);
         }
       }
+      /**
+       * Fetch the span tree for a root span.
+       * Blocking GET request.
+       */
+      async getSpanTree(externalSpanId) {
+        const url = `${this.serviceUrl}/api/sdk/replay/spanTree/${externalSpanId}`;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), 3e4);
+        try {
+          const response = await fetch(url, {
+            method: "GET",
+            headers: { Authorization: `Bearer ${this.apiKey}` },
+            signal: controller.signal
+          });
+          if (!response.ok) {
+            const errorText = await response.text();
+            throw new BitfabError(
+              `HTTP ${response.status}: ${errorText.slice(0, 500)}`
+            );
+          }
+          return await response.json();
+        } catch (error) {
+          if (error instanceof BitfabError) {
+            throw error;
+          }
+          if (error instanceof Error) {
+            if (error.name === "AbortError") {
+              throw new BitfabError("Request timed out after 30000ms");
+            }
+            throw new BitfabError(error.message);
+          }
+          throw new BitfabError("Unknown error occurred");
+        } finally {
+          clearTimeout(timeoutId);
+        }
+      }
       /**
        * Mark a replay test run as completed.
        * Blocking call.
@@ -431,11 +467,39 @@ function deserializeOutput(spanData) {
   }
   return rawOutput;
 }
-async function processItem(httpClient, serverItem, fn, testRunId) {
+function buildMockTree(rootNode) {
+  const spans = /* @__PURE__ */ new Map();
+  const counters = /* @__PURE__ */ new Map();
+  function walk(node) {
+    const key = node.traceFunctionKey;
+    if (key) {
+      const index = counters.get(key) ?? 0;
+      counters.set(key, index + 1);
+      spans.set(`${key}:${index}`, {
+        sourceSpanId: node.sourceSpanId,
+        output: node.output,
+        outputMeta: node.outputMeta
+      });
+    }
+    for (const child of node.children) {
+      walk(child);
+    }
+  }
+  for (const child of rootNode.children) {
+    walk(child);
+  }
+  return { spans };
+}
+async function processItem(httpClient, serverItem, fn, testRunId, mockStrategy) {
   const span = await httpClient.getExternalSpan(serverItem.externalSpanId);
   const spanData = span.rawData?.span_data ?? {};
   const inputs = deserializeInputs(spanData);
   const originalOutput = deserializeOutput(spanData);
+  let mockTree;
+  if (mockStrategy === "all" || mockStrategy === "marked") {
+    const treeResponse = await httpClient.getSpanTree(serverItem.externalSpanId);
+    mockTree = buildMockTree(treeResponse.root);
+  }
   let result;
   let error = null;
   try {
@@ -443,7 +507,10 @@ async function processItem(httpClient, serverItem, fn, testRunId) {
       {
         testRunId,
         inputSourceSpanId: span.id,
-        inputSourceTraceId: span.externalTraceId
+        inputSourceTraceId: span.externalTraceId,
+        mockTree,
+        callCounters: mockTree ? /* @__PURE__ */ new Map() : void 0,
+        mockStrategy
       },
       () => fn(...inputs)
     );
@@ -490,9 +557,10 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options) {
     options?.codeChangeDescription,
     options?.codeChangeFiles
   );
+  const mockStrategy = options?.mock ?? "none";
   const maxConcurrency = options?.maxConcurrency ?? 10;
   const tasks = serverItems.map(
-    (serverItem) => () => processItem(httpClient, serverItem, fn, testRunId)
+    (serverItem) => () => processItem(httpClient, serverItem, fn, testRunId, mockStrategy)
   );
   const resultItems = await mapWithConcurrency(tasks, maxConcurrency);
   await flushTraces();
@@ -2639,6 +2707,28 @@ var Bitfab = class {
         } catch {
         }
       };
+      const replayCtxForMock = getReplayContext();
+      if (replayCtxForMock?.mockTree && !isRootSpan) {
+        const counters = replayCtxForMock.callCounters;
+        const callIndex = counters.get(traceFunctionKey) ?? 0;
+        counters.set(traceFunctionKey, callIndex + 1);
+        const shouldMock = replayCtxForMock.mockStrategy === "all" || replayCtxForMock.mockStrategy === "marked" && options.mockOnReplay === true;
+        if (shouldMock) {
+          const mockKey = `${traceFunctionKey}:${callIndex}`;
+          const mockSpan = replayCtxForMock.mockTree.spans.get(mockKey);
+          if (mockSpan) {
+            let output = mockSpan.output;
+            if (mockSpan.outputMeta !== void 0 && mockSpan.outputMeta !== null) {
+              output = deserializeValue({
+                json: mockSpan.output,
+                meta: mockSpan.outputMeta
+              });
+            }
+            void sendSpan({ result: output });
+            return output;
+          }
+        }
+      }
       const executeWithContext = () => {
         const result = fn(...args);
         if (result instanceof Promise) {