@bitfab/sdk 0.19.1 → 0.21.0

package/dist/index.d.cts

@@ -396,6 +396,13 @@ interface ReplayOptions {
     environment?: ReplayEnvironment;
     /** Group ID to associate this replay with an experiment group for live streaming in Studio. */
     experimentGroupId?: string;
+    /**
+     * Dataset this replay runs against. When set, the resulting experiment is
+     * durably attributed to the dataset (stored on the test run), 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;
     /**
      * Reshape recorded inputs before they are spread into `fn`.
      *
@@ -749,6 +756,25 @@ interface SpanOptions {
      * only the marked descendants return their recorded output.
      */
     mockOnReplay?: boolean;
+    /**
+     * 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>;
 }
 
 /**
@@ -1063,7 +1089,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.19.1";
+declare const __version__ = "0.21.0";
 
 /**
  * Constants for the Bitfab SDK.
@@ -1073,4 +1099,62 @@ declare const __version__ = "0.19.1";
  */
 declare const DEFAULT_SERVICE_URL = "https://bitfab.ai";
 
-export { type ActiveSpanContext, type AdaptContext, type AdaptInputsFn, type AllowedEnvVars, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler as BitfabLangChainCallbackHandler, 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 };
+/**
+ * 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;
+};
+
+export { type ActiveSpanContext, type AdaptContext, type AdaptInputsFn, type AllowedEnvVars, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler as BitfabLangChainCallbackHandler, 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__, finalizers, flushTraces, getCurrentSpan, getCurrentTrace };

package/dist/index.d.ts

@@ -396,6 +396,13 @@ interface ReplayOptions {
     environment?: ReplayEnvironment;
     /** Group ID to associate this replay with an experiment group for live streaming in Studio. */
     experimentGroupId?: string;
+    /**
+     * Dataset this replay runs against. When set, the resulting experiment is
+     * durably attributed to the dataset (stored on the test run), 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;
     /**
      * Reshape recorded inputs before they are spread into `fn`.
      *
@@ -749,6 +756,25 @@ interface SpanOptions {
      * only the marked descendants return their recorded output.
      */
     mockOnReplay?: boolean;
+    /**
+     * 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>;
 }
 
 /**
@@ -1063,7 +1089,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.19.1";
+declare const __version__ = "0.21.0";
 
 /**
  * Constants for the Bitfab SDK.
@@ -1073,4 +1099,62 @@ declare const __version__ = "0.19.1";
  */
 declare const DEFAULT_SERVICE_URL = "https://bitfab.ai";
 
-export { type ActiveSpanContext, type AdaptContext, type AdaptInputsFn, type AllowedEnvVars, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler as BitfabLangChainCallbackHandler, 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 };
+/**
+ * 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;
+};
+
+export { type ActiveSpanContext, type AdaptContext, type AdaptInputsFn, type AllowedEnvVars, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler as BitfabLangChainCallbackHandler, 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__, finalizers, flushTraces, getCurrentSpan, getCurrentTrace };

package/dist/index.js

@@ -8,10 +8,11 @@ import {
   ReplayEnvironment,
   SUPPORTED_PROVIDERS,
   __version__,
+  finalizers,
   flushTraces,
   getCurrentSpan,
   getCurrentTrace
-} from "./chunk-WZ72P5SX.js";
+} from "./chunk-UO3CIQ7R.js";
 import {
   BitfabError
 } from "./chunk-EQI6ZJC3.js";
@@ -27,6 +28,7 @@ export {
   ReplayEnvironment,
   SUPPORTED_PROVIDERS,
   __version__,
+  finalizers,
   flushTraces,
   getCurrentSpan,
   getCurrentTrace

package/dist/node.cjs

@@ -401,7 +401,8 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options) {
     options?.codeChangeFiles,
     options?.environment !== void 0,
     // includeDbBranchLease
-    options?.experimentGroupId
+    options?.experimentGroupId,
+    options?.datasetId
   );
   const mockStrategy = options?.mock ?? "none";
   const maxConcurrency = options?.maxConcurrency ?? 10;
@@ -488,6 +489,7 @@ __export(node_exports, {
   ReplayEnvironment: () => ReplayEnvironment,
   SUPPORTED_PROVIDERS: () => SUPPORTED_PROVIDERS,
   __version__: () => __version__,
+  finalizers: () => finalizers,
   flushTraces: () => flushTraces,
   getCurrentSpan: () => getCurrentSpan,
   getCurrentTrace: () => getCurrentTrace
@@ -502,7 +504,7 @@ registerAsyncLocalStorageClass(
 );
 
 // src/version.generated.ts
-var __version__ = "0.19.1";
+var __version__ = "0.21.0";
 
 // src/constants.ts
 var DEFAULT_SERVICE_URL = "https://bitfab.ai";
@@ -780,7 +782,7 @@ var HttpClient = class {
    * Start a replay session by fetching historical traces.
    * Blocking call — creates a test run and returns lightweight item references.
    */
-  async startReplay(traceFunctionKey, limit, traceIds, codeChangeDescription, codeChangeFiles, includeDbBranchLease, experimentGroupId) {
+  async startReplay(traceFunctionKey, limit, traceIds, codeChangeDescription, codeChangeFiles, includeDbBranchLease, experimentGroupId, datasetId) {
     const payload = { traceFunctionKey };
     if (limit !== void 0) {
       payload.limit = limit;
@@ -800,6 +802,9 @@ var HttpClient = class {
     if (experimentGroupId !== void 0) {
       payload.experimentGroupId = experimentGroupId;
     }
+    if (datasetId !== void 0) {
+      payload.datasetId = datasetId;
+    }
     const timeout = includeDbBranchLease ? 18e4 : 3e4;
     return this.request("/api/sdk/replay/start", payload, {
       timeout
@@ -3157,11 +3162,11 @@ var Bitfab = class {
         startedAt,
         spanType: options.type ?? "custom"
       };
-      const sendSpan = async (params) => {
+      const sendSpan = async (params, spanOpts) => {
         const replayCtx = getReplayContext();
         const persistenceCollector = isRootSpan ? replayCtx?.pendingPersistence : void 0;
         let resolvePersistence;
-        if (persistenceCollector) {
+        if (persistenceCollector && !spanOpts?.skipPersistenceRegistration) {
           persistenceCollector.push(
             new Promise((resolve) => {
               resolvePersistence = resolve;
@@ -3261,11 +3266,41 @@ var Bitfab = class {
           }
         }
       }
+      const recordSpan = (result) => {
+        if (options.finalize) {
+          const replayCtx = getReplayContext();
+          const persistenceCollector = isRootSpan ? replayCtx?.pendingPersistence : void 0;
+          let resolvePersistence;
+          if (persistenceCollector) {
+            persistenceCollector.push(
+              new Promise((resolve) => {
+                resolvePersistence = resolve;
+              })
+            );
+          }
+          void Promise.resolve().then(() => options.finalize(result)).then(
+            (output) => sendSpan(
+              { result: output },
+              { skipPersistenceRegistration: true }
+            )
+          ).catch(
+            (error) => sendSpan(
+              {
+                result: void 0,
+                error: error instanceof Error ? `finalize failed: ${error.message}` : `finalize failed: ${String(error)}`
+              },
+              { skipPersistenceRegistration: true }
+            )
+          ).finally(() => resolvePersistence?.());
+        } else {
+          void sendSpan({ result });
+        }
+      };
       const executeWithContext = () => {
         const result = fn(...args);
         if (result instanceof Promise) {
           return result.then((resolvedResult) => {
-            void sendSpan({ result: resolvedResult });
+            recordSpan(resolvedResult);
             return resolvedResult;
           }).catch((error) => {
             void sendSpan({
@@ -3278,7 +3313,7 @@ var Bitfab = class {
         if (isAsyncGenerator(result)) {
           return wrapAsyncGenerator(result, newStack, sendSpan);
         }
-        void sendSpan({ result });
+        recordSpan(result);
         return result;
       };
       return runWithSpanStack(newStack, executeWithContext);
@@ -3562,6 +3597,54 @@ var BitfabFunction = class {
   }
 };
 
+// src/finalizers.ts
+async function settle(value) {
+  try {
+    return await value;
+  } catch {
+    return void 0;
+  }
+}
+async function aiSdk(result) {
+  const r = result ?? {};
+  const [text, usage, totalUsage, finishReason, toolCalls, toolResults] = await Promise.all([
+    settle(r.text),
+    settle(r.usage),
+    settle(r.totalUsage),
+    settle(r.finishReason),
+    settle(r.toolCalls),
+    settle(r.toolResults)
+  ]);
+  return {
+    text,
+    usage: totalUsage ?? usage,
+    finishReason,
+    toolCalls,
+    toolResults
+  };
+}
+async function readableStream(stream, onLive) {
+  const [live, copy] = stream.tee();
+  onLive(live);
+  const chunks = [];
+  const reader = copy.getReader();
+  try {
+    for (; ; ) {
+      const { done, value } = await reader.read();
+      if (done) {
+        break;
+      }
+      chunks.push(value);
+    }
+  } catch {
+  }
+  return { chunks };
+}
+var finalizers = {
+  aiSdk,
+  readableStream
+};
+
 // src/node.ts
 init_asyncStorage();
 assertAsyncStorageRegistered();
@@ -3578,6 +3661,7 @@ assertAsyncStorageRegistered();
   ReplayEnvironment,
   SUPPORTED_PROVIDERS,
   __version__,
+  finalizers,
   flushTraces,
   getCurrentSpan,
   getCurrentTrace