@bitfab/sdk 0.21.2 → 0.22.0

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { Trace, Span } from '@openai/agents';
+import { Agent, AgentInputItem, RunState, NonStreamRunOptions, RunResult, StreamRunOptions, StreamedRunResult, Trace, Span } from '@openai/agents';
 
 /**
  * BAML execution utilities for the Bitfab TypeScript SDK.
@@ -313,6 +313,76 @@ declare class BitfabLangGraphCallbackHandler {
     handleRetrieverError(error: unknown, runId: string): Promise<void>;
 }
 
+/**
+ * OpenAI Agents SDK handler for Bitfab tracing.
+ *
+ * The OpenAI Agents SDK is instrumented in two layers:
+ *
+ *   1. A process-wide `TracingProcessor` (see `getOpenAiTracingProcessor` /
+ *      `BitfabOpenAITracingProcessor`) registered once with `addTraceProcessor`.
+ *      It captures everything *inside* a run — LLM calls, tool calls, handoffs —
+ *      as Bitfab spans.
+ *   2. This handler's `wrapRun`, which owns the *root*. The processor never sees
+ *      the caller's input (the SDK's trace events don't carry it), so a
+ *      processor-only run records a root span with an empty input and is not
+ *      replayable. `wrapRun` is a thin drop-in for `run()` that opens a
+ *      `withSpan` root carrying the input and final output, so the run is
+ *      replayable with no hand-written `withSpan`. The processor's spans nest
+ *      underneath it automatically (it remaps onto the active span context).
+ *
+ * Use both together: register the processor once at startup, then call
+ * `handler.wrapRun(agent, input)` instead of `run(agent, input)`.
+ */
+
+type RootSpanOptions = {
+    type: "agent";
+    finalize: (result: unknown) => unknown | Promise<unknown>;
+};
+type WithSpanFn = <TArgs extends unknown[], TReturn>(traceFunctionKey: string, options: RootSpanOptions, fn: (...args: TArgs) => TReturn) => (...args: TArgs) => TReturn;
+type RunInput<TContext, TAgent extends Agent<any, any>> = string | AgentInputItem[] | RunState<TContext, TAgent>;
+/**
+ * OpenAI Agents SDK handler that records a replayable root span around a run.
+ *
+ * ```typescript
+ * import { Bitfab } from "@bitfab/sdk";
+ * import { addTraceProcessor, Agent, run } from "@openai/agents";
+ *
+ * const bitfab = new Bitfab({ apiKey: "..." });
+ * addTraceProcessor(bitfab.getOpenAiTracingProcessor()); // captures internals
+ *
+ * const agent = new Agent({ name: "Researcher", instructions: "..." });
+ * const handler = bitfab.getOpenAiAgentHandler("research-topic");
+ *
+ * // Swap run(agent, input) -> handler.wrapRun(agent, input)
+ * const result = await handler.wrapRun(agent, "Find X");
+ * return result.finalOutput;
+ * ```
+ */
+declare class BitfabOpenAIAgentHandler {
+    private readonly traceFunctionKey;
+    private readonly withSpanFn;
+    constructor(config: {
+        traceFunctionKey: string;
+        withSpan: WithSpanFn;
+    });
+    /**
+     * Drop-in replacement for the OpenAI Agents SDK's `run()` that records a
+     * replayable root `agent` span.
+     *
+     * The `input` is captured as the root span's input (as a single positional
+     * argument, so `replay(key, fn)` re-feeds it), and the run's `finalOutput`
+     * is recorded as the root output. For streaming runs (`{ stream: true }`),
+     * the result is handed back immediately and the final output is recorded
+     * once the stream completes — first-byte latency is untouched.
+     *
+     * The process-wide tracing processor (`getOpenAiTracingProcessor`) must still
+     * be registered: it captures the LLM/tool/handoff spans that nest beneath
+     * this root.
+     */
+    wrapRun<TAgent extends Agent<any, any>, TContext = undefined>(agent: TAgent, input: RunInput<TContext, TAgent>, options?: NonStreamRunOptions<TContext>): Promise<RunResult<TContext, TAgent>>;
+    wrapRun<TAgent extends Agent<any, any>, TContext = undefined>(agent: TAgent, input: RunInput<TContext, TAgent>, options: StreamRunOptions<TContext>): Promise<StreamedRunResult<TContext, TAgent>>;
+}
+
 /**
  * Per-trace environment exposed to customer code during replay.
  *
@@ -863,6 +933,29 @@ declare class Bitfab {
      * @returns A BitfabOpenAITracingProcessor instance configured for this client
      */
     getOpenAiTracingProcessor(): BitfabOpenAITracingProcessor;
+    /**
+     * Get an OpenAI Agents SDK handler that records a replayable root span.
+     *
+     * The processor from {@link getOpenAiTracingProcessor} captures everything
+     * inside a run (LLM calls, tools, handoffs) but never sees the caller's
+     * input, so a processor-only run records an empty-input root and is not
+     * replayable. This handler's `wrapRun` is a drop-in for `run()` that opens a
+     * `withSpan` root carrying the input and final output; the processor's spans
+     * nest beneath it. Register the processor once at startup, then call
+     * `handler.wrapRun(agent, input)` in place of `run(agent, input)`.
+     *
+     * ```typescript
+     * import { addTraceProcessor, Agent, run } from "@openai/agents";
+     *
+     * addTraceProcessor(client.getOpenAiTracingProcessor());
+     * const handler = client.getOpenAiAgentHandler("research-topic");
+     * const result = await handler.wrapRun(agent, "Find X");
+     * ```
+     *
+     * @param traceFunctionKey - Groups traces under this key in Bitfab
+     * @returns A BitfabOpenAIAgentHandler configured for this client
+     */
+    getOpenAiAgentHandler(traceFunctionKey: string): BitfabOpenAIAgentHandler;
     /**
      * Get a LangGraph/LangChain callback handler for tracing.
      *
@@ -1117,7 +1210,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.21.2";
+declare const __version__ = "0.22.0";
 
 /**
  * Constants for the Bitfab SDK.
@@ -1185,4 +1278,4 @@ declare const finalizers: {
     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 };
+export { type ActiveSpanContext, type AdaptContext, type AdaptInputsFn, type AllowedEnvVars, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler as BitfabLangChainCallbackHandler, BitfabLangGraphCallbackHandler, BitfabOpenAIAgentHandler, 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

@@ -1,4 +1,4 @@
-import { Trace, Span } from '@openai/agents';
+import { Agent, AgentInputItem, RunState, NonStreamRunOptions, RunResult, StreamRunOptions, StreamedRunResult, Trace, Span } from '@openai/agents';
 
 /**
  * BAML execution utilities for the Bitfab TypeScript SDK.
@@ -313,6 +313,76 @@ declare class BitfabLangGraphCallbackHandler {
     handleRetrieverError(error: unknown, runId: string): Promise<void>;
 }
 
+/**
+ * OpenAI Agents SDK handler for Bitfab tracing.
+ *
+ * The OpenAI Agents SDK is instrumented in two layers:
+ *
+ *   1. A process-wide `TracingProcessor` (see `getOpenAiTracingProcessor` /
+ *      `BitfabOpenAITracingProcessor`) registered once with `addTraceProcessor`.
+ *      It captures everything *inside* a run — LLM calls, tool calls, handoffs —
+ *      as Bitfab spans.
+ *   2. This handler's `wrapRun`, which owns the *root*. The processor never sees
+ *      the caller's input (the SDK's trace events don't carry it), so a
+ *      processor-only run records a root span with an empty input and is not
+ *      replayable. `wrapRun` is a thin drop-in for `run()` that opens a
+ *      `withSpan` root carrying the input and final output, so the run is
+ *      replayable with no hand-written `withSpan`. The processor's spans nest
+ *      underneath it automatically (it remaps onto the active span context).
+ *
+ * Use both together: register the processor once at startup, then call
+ * `handler.wrapRun(agent, input)` instead of `run(agent, input)`.
+ */
+
+type RootSpanOptions = {
+    type: "agent";
+    finalize: (result: unknown) => unknown | Promise<unknown>;
+};
+type WithSpanFn = <TArgs extends unknown[], TReturn>(traceFunctionKey: string, options: RootSpanOptions, fn: (...args: TArgs) => TReturn) => (...args: TArgs) => TReturn;
+type RunInput<TContext, TAgent extends Agent<any, any>> = string | AgentInputItem[] | RunState<TContext, TAgent>;
+/**
+ * OpenAI Agents SDK handler that records a replayable root span around a run.
+ *
+ * ```typescript
+ * import { Bitfab } from "@bitfab/sdk";
+ * import { addTraceProcessor, Agent, run } from "@openai/agents";
+ *
+ * const bitfab = new Bitfab({ apiKey: "..." });
+ * addTraceProcessor(bitfab.getOpenAiTracingProcessor()); // captures internals
+ *
+ * const agent = new Agent({ name: "Researcher", instructions: "..." });
+ * const handler = bitfab.getOpenAiAgentHandler("research-topic");
+ *
+ * // Swap run(agent, input) -> handler.wrapRun(agent, input)
+ * const result = await handler.wrapRun(agent, "Find X");
+ * return result.finalOutput;
+ * ```
+ */
+declare class BitfabOpenAIAgentHandler {
+    private readonly traceFunctionKey;
+    private readonly withSpanFn;
+    constructor(config: {
+        traceFunctionKey: string;
+        withSpan: WithSpanFn;
+    });
+    /**
+     * Drop-in replacement for the OpenAI Agents SDK's `run()` that records a
+     * replayable root `agent` span.
+     *
+     * The `input` is captured as the root span's input (as a single positional
+     * argument, so `replay(key, fn)` re-feeds it), and the run's `finalOutput`
+     * is recorded as the root output. For streaming runs (`{ stream: true }`),
+     * the result is handed back immediately and the final output is recorded
+     * once the stream completes — first-byte latency is untouched.
+     *
+     * The process-wide tracing processor (`getOpenAiTracingProcessor`) must still
+     * be registered: it captures the LLM/tool/handoff spans that nest beneath
+     * this root.
+     */
+    wrapRun<TAgent extends Agent<any, any>, TContext = undefined>(agent: TAgent, input: RunInput<TContext, TAgent>, options?: NonStreamRunOptions<TContext>): Promise<RunResult<TContext, TAgent>>;
+    wrapRun<TAgent extends Agent<any, any>, TContext = undefined>(agent: TAgent, input: RunInput<TContext, TAgent>, options: StreamRunOptions<TContext>): Promise<StreamedRunResult<TContext, TAgent>>;
+}
+
 /**
  * Per-trace environment exposed to customer code during replay.
  *
@@ -863,6 +933,29 @@ declare class Bitfab {
      * @returns A BitfabOpenAITracingProcessor instance configured for this client
      */
     getOpenAiTracingProcessor(): BitfabOpenAITracingProcessor;
+    /**
+     * Get an OpenAI Agents SDK handler that records a replayable root span.
+     *
+     * The processor from {@link getOpenAiTracingProcessor} captures everything
+     * inside a run (LLM calls, tools, handoffs) but never sees the caller's
+     * input, so a processor-only run records an empty-input root and is not
+     * replayable. This handler's `wrapRun` is a drop-in for `run()` that opens a
+     * `withSpan` root carrying the input and final output; the processor's spans
+     * nest beneath it. Register the processor once at startup, then call
+     * `handler.wrapRun(agent, input)` in place of `run(agent, input)`.
+     *
+     * ```typescript
+     * import { addTraceProcessor, Agent, run } from "@openai/agents";
+     *
+     * addTraceProcessor(client.getOpenAiTracingProcessor());
+     * const handler = client.getOpenAiAgentHandler("research-topic");
+     * const result = await handler.wrapRun(agent, "Find X");
+     * ```
+     *
+     * @param traceFunctionKey - Groups traces under this key in Bitfab
+     * @returns A BitfabOpenAIAgentHandler configured for this client
+     */
+    getOpenAiAgentHandler(traceFunctionKey: string): BitfabOpenAIAgentHandler;
     /**
      * Get a LangGraph/LangChain callback handler for tracing.
      *
@@ -1117,7 +1210,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.21.2";
+declare const __version__ = "0.22.0";
 
 /**
  * Constants for the Bitfab SDK.
@@ -1185,4 +1278,4 @@ declare const finalizers: {
     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 };
+export { type ActiveSpanContext, type AdaptContext, type AdaptInputsFn, type AllowedEnvVars, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler as BitfabLangChainCallbackHandler, BitfabLangGraphCallbackHandler, BitfabOpenAIAgentHandler, 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

@@ -3,6 +3,7 @@ import {
   BitfabClaudeAgentHandler,
   BitfabFunction,
   BitfabLangGraphCallbackHandler,
+  BitfabOpenAIAgentHandler,
   BitfabOpenAITracingProcessor,
   DEFAULT_SERVICE_URL,
   ReplayEnvironment,
@@ -12,7 +13,7 @@ import {
   flushTraces,
   getCurrentSpan,
   getCurrentTrace
-} from "./chunk-3YKMCCDV.js";
+} from "./chunk-4SLFC266.js";
 import {
   BitfabError
 } from "./chunk-EQI6ZJC3.js";
@@ -23,6 +24,7 @@ export {
   BitfabFunction,
   BitfabLangGraphCallbackHandler as BitfabLangChainCallbackHandler,
   BitfabLangGraphCallbackHandler,
+  BitfabOpenAIAgentHandler,
   BitfabOpenAITracingProcessor,
   DEFAULT_SERVICE_URL,
   ReplayEnvironment,

package/dist/node.cjs

@@ -484,6 +484,7 @@ __export(node_exports, {
   BitfabFunction: () => BitfabFunction,
   BitfabLangChainCallbackHandler: () => BitfabLangGraphCallbackHandler,
   BitfabLangGraphCallbackHandler: () => BitfabLangGraphCallbackHandler,
+  BitfabOpenAIAgentHandler: () => BitfabOpenAIAgentHandler,
   BitfabOpenAITracingProcessor: () => BitfabOpenAITracingProcessor,
   DEFAULT_SERVICE_URL: () => DEFAULT_SERVICE_URL,
   ReplayEnvironment: () => ReplayEnvironment,
@@ -504,7 +505,7 @@ registerAsyncLocalStorageClass(
 );
 
 // src/version.generated.ts
-var __version__ = "0.21.2";
+var __version__ = "0.22.0";
 
 // src/constants.ts
 var DEFAULT_SERVICE_URL = "https://bitfab.ai";
@@ -2286,6 +2287,39 @@ var BitfabLangGraphCallbackHandler = class {
   }
 };
 
+// src/openaiAgentSdk.ts
+var BitfabOpenAIAgentHandler = class {
+  constructor(config) {
+    this.traceFunctionKey = config.traceFunctionKey;
+    this.withSpanFn = config.withSpan;
+  }
+  async wrapRun(agent, input, options) {
+    const { run } = await import("@openai/agents");
+    const isStreaming = options?.stream === true;
+    const finalize = async (result) => {
+      const res = result;
+      if (isStreaming && res?.completed) {
+        try {
+          await res.completed;
+        } catch {
+        }
+      }
+      return res?.finalOutput;
+    };
+    const options_ = { type: "agent", finalize };
+    const traced = this.withSpanFn(
+      this.traceFunctionKey,
+      options_,
+      (agentInput) => run(
+        agent,
+        agentInput,
+        options
+      )
+    );
+    return traced(input);
+  }
+};
+
 // src/client.ts
 init_replayContext();
 
@@ -2979,6 +3013,34 @@ var Bitfab = class {
       }
     });
   }
+  /**
+   * Get an OpenAI Agents SDK handler that records a replayable root span.
+   *
+   * The processor from {@link getOpenAiTracingProcessor} captures everything
+   * inside a run (LLM calls, tools, handoffs) but never sees the caller's
+   * input, so a processor-only run records an empty-input root and is not
+   * replayable. This handler's `wrapRun` is a drop-in for `run()` that opens a
+   * `withSpan` root carrying the input and final output; the processor's spans
+   * nest beneath it. Register the processor once at startup, then call
+   * `handler.wrapRun(agent, input)` in place of `run(agent, input)`.
+   *
+   * ```typescript
+   * import { addTraceProcessor, Agent, run } from "@openai/agents";
+   *
+   * addTraceProcessor(client.getOpenAiTracingProcessor());
+   * const handler = client.getOpenAiAgentHandler("research-topic");
+   * const result = await handler.wrapRun(agent, "Find X");
+   * ```
+   *
+   * @param traceFunctionKey - Groups traces under this key in Bitfab
+   * @returns A BitfabOpenAIAgentHandler configured for this client
+   */
+  getOpenAiAgentHandler(traceFunctionKey) {
+    return new BitfabOpenAIAgentHandler({
+      traceFunctionKey,
+      withSpan: this.withSpan.bind(this)
+    });
+  }
   /**
    * Get a LangGraph/LangChain callback handler for tracing.
    *
@@ -3733,6 +3795,7 @@ assertAsyncStorageRegistered();
   BitfabFunction,
   BitfabLangChainCallbackHandler,
   BitfabLangGraphCallbackHandler,
+  BitfabOpenAIAgentHandler,
   BitfabOpenAITracingProcessor,
   DEFAULT_SERVICE_URL,
   ReplayEnvironment,