@bitfab/sdk 0.20.0 → 0.21.0

package/dist/index.d.cts

@@ -756,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>;
 }
 
 /**
@@ -1070,7 +1089,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.20.0";
+declare const __version__ = "0.21.0";
 
 /**
  * Constants for the Bitfab SDK.
@@ -1080,4 +1099,62 @@ declare const __version__ = "0.20.0";
  */
 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

@@ -756,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>;
 }
 
 /**
@@ -1070,7 +1089,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.20.0";
+declare const __version__ = "0.21.0";
 
 /**
  * Constants for the Bitfab SDK.
@@ -1080,4 +1099,62 @@ declare const __version__ = "0.20.0";
  */
 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-IUZIGC6T.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

@@ -489,6 +489,7 @@ __export(node_exports, {
   ReplayEnvironment: () => ReplayEnvironment,
   SUPPORTED_PROVIDERS: () => SUPPORTED_PROVIDERS,
   __version__: () => __version__,
+  finalizers: () => finalizers,
   flushTraces: () => flushTraces,
   getCurrentSpan: () => getCurrentSpan,
   getCurrentTrace: () => getCurrentTrace
@@ -503,7 +504,7 @@ registerAsyncLocalStorageClass(
 );
 
 // src/version.generated.ts
-var __version__ = "0.20.0";
+var __version__ = "0.21.0";
 
 // src/constants.ts
 var DEFAULT_SERVICE_URL = "https://bitfab.ai";
@@ -3161,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;
@@ -3265,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({
@@ -3282,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);
@@ -3566,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();
@@ -3582,6 +3661,7 @@ assertAsyncStorageRegistered();
   ReplayEnvironment,
   SUPPORTED_PROVIDERS,
   __version__,
+  finalizers,
   flushTraces,
   getCurrentSpan,
   getCurrentTrace