@bitfab/sdk 0.54.2 → 0.54.4

package/dist/index.d.cts

@@ -1,3 +1,17 @@
+declare class TraceCompletion {
+    private readonly traces;
+    private readonly closed;
+    private state;
+    start(traceId: string, spanId: string): void;
+    open(traceId: string): void;
+    hold(traceId: string, key: string): void;
+    record(traceId: string, spanId: string): void;
+    end(traceId: string, spanId: string): void;
+    abort(traceId: string, spanId: string): void;
+    close(traceId: string, complete: (count: number) => void, dropped?: boolean): void;
+    private drain;
+}
+
 /**
  * Per-trace database snapshot ref capture.
  *
@@ -327,14 +341,6 @@ interface SimulationPlanResponse {
 }
 type SimulationPlanSubmit = (payload: Record<string, unknown>) => void;
 
-/**
- * HTTP client utilities for Bitfab API requests.
- *
- * This module provides:
- * - HttpClient class for making API requests
- * - awaitOnExit helper so deferred span work still gates process exit
- */
-
 /**
  * Wait for pending fire-and-forget requests AND every live span transport to
  * deliver, within one total deadline. Useful in tests and scripts to ensure all
@@ -407,6 +413,7 @@ declare class HttpClient {
     private traceTransport;
     private readonly traceDeliveries;
     private readonly deferredWork;
+    readonly traceCompletion: TraceCompletion;
     private closed;
     private closing;
     externalSpanTransform: ((payload: Record<string, unknown>, submit: SimulationPlanSubmit) => void) | undefined;
@@ -547,6 +554,7 @@ declare class HttpClient {
      * server-authoritative barrier in `replay.ts`, not by awaiting this call.
      */
     sendExternalTrace(rawPayload: Record<string, unknown>): void;
+    private sendCountedExternalTrace;
     submitExternalTrace(payload: Record<string, unknown>): void;
     /**
      * Partial update of an existing trace identified by its Bitfab trace ID.
@@ -748,7 +756,7 @@ interface CompleteReplayResponse {
     /**
      * Per-replay-trace token usage, keyed by the server trace id (the values of
      * `traceIds`). Aggregated server-side from the freshly-uploaded replay spans,
-     * so it's the REPLAYED run's tokens (the same source Studio reads), not the
+     * so it's the REPLAYED run's tokens (the same source the dashboard reads), not the
      * original trace's. The SDK maps each item onto this to set
      * `ReplayItem.tokens`. Absent on servers that predate this field.
      */
@@ -1786,7 +1794,7 @@ interface ReplayOptions {
      * not use the historical data you asked for.
      */
     dbBranch?: DbBranchOptions | boolean;
-    /** Group ID to associate this replay with an experiment group for live streaming in Studio. */
+    /** Group ID to associate this replay with an experiment group for live streaming on the experiments page. */
     experimentGroupId?: string;
     /**
      * Dataset this replay runs against. Mutually exclusive with `datasetIds`.
@@ -2093,7 +2101,7 @@ interface ReplayItem<T> {
      * Token usage from the REPLAYED run (this item's new execution), aggregated
      * server-side from the spans it produced, or null if the run captured no
      * token data. Compare against {@link ReplayItem.originalTokens} to see how
-     * the code change moved cost. Matches what Studio's experiments view shows.
+     * the code change moved cost. Matches what the experiments page shows.
      *
      * Unprefixed because the replay is this item's subject: anything describing
      * the trace being replayed carries `original`.
@@ -2235,6 +2243,7 @@ interface Trace {
     toJSON(): unknown;
 }
 interface Span<_T = any> {
+    spanId?: string;
     traceId?: string;
     toJSON(): unknown;
     spanData?: {
@@ -2323,11 +2332,14 @@ declare class BitfabOpenAITracingProcessor implements TracingProcessor {
      * since the parent withSpan handles completion.
      */
     onTraceEnd(trace: Trace): Promise<void>;
+    private readonly startedSpans;
+    private readonly endedTraces;
+    private cleanupTrace;
     /**
      * Called when a span is started. Span payloads are authoritative completed
      * snapshots, so start notifications do not cross the transport boundary.
      */
-    onSpanStart(_span: Span<any>): Promise<void>;
+    onSpanStart(span: Span<any>): Promise<void>;
     /**
      * Called when a span is ended.
      *
@@ -3379,7 +3391,7 @@ interface CommitRef {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.54.2";
+declare const __version__ = "0.54.4";
 
 /**
  * Constants for the Bitfab SDK.

package/dist/index.d.ts

@@ -1,3 +1,17 @@
+declare class TraceCompletion {
+    private readonly traces;
+    private readonly closed;
+    private state;
+    start(traceId: string, spanId: string): void;
+    open(traceId: string): void;
+    hold(traceId: string, key: string): void;
+    record(traceId: string, spanId: string): void;
+    end(traceId: string, spanId: string): void;
+    abort(traceId: string, spanId: string): void;
+    close(traceId: string, complete: (count: number) => void, dropped?: boolean): void;
+    private drain;
+}
+
 /**
  * Per-trace database snapshot ref capture.
  *
@@ -327,14 +341,6 @@ interface SimulationPlanResponse {
 }
 type SimulationPlanSubmit = (payload: Record<string, unknown>) => void;
 
-/**
- * HTTP client utilities for Bitfab API requests.
- *
- * This module provides:
- * - HttpClient class for making API requests
- * - awaitOnExit helper so deferred span work still gates process exit
- */
-
 /**
  * Wait for pending fire-and-forget requests AND every live span transport to
  * deliver, within one total deadline. Useful in tests and scripts to ensure all
@@ -407,6 +413,7 @@ declare class HttpClient {
     private traceTransport;
     private readonly traceDeliveries;
     private readonly deferredWork;
+    readonly traceCompletion: TraceCompletion;
     private closed;
     private closing;
     externalSpanTransform: ((payload: Record<string, unknown>, submit: SimulationPlanSubmit) => void) | undefined;
@@ -547,6 +554,7 @@ declare class HttpClient {
      * server-authoritative barrier in `replay.ts`, not by awaiting this call.
      */
     sendExternalTrace(rawPayload: Record<string, unknown>): void;
+    private sendCountedExternalTrace;
     submitExternalTrace(payload: Record<string, unknown>): void;
     /**
      * Partial update of an existing trace identified by its Bitfab trace ID.
@@ -748,7 +756,7 @@ interface CompleteReplayResponse {
     /**
      * Per-replay-trace token usage, keyed by the server trace id (the values of
      * `traceIds`). Aggregated server-side from the freshly-uploaded replay spans,
-     * so it's the REPLAYED run's tokens (the same source Studio reads), not the
+     * so it's the REPLAYED run's tokens (the same source the dashboard reads), not the
      * original trace's. The SDK maps each item onto this to set
      * `ReplayItem.tokens`. Absent on servers that predate this field.
      */
@@ -1786,7 +1794,7 @@ interface ReplayOptions {
      * not use the historical data you asked for.
      */
     dbBranch?: DbBranchOptions | boolean;
-    /** Group ID to associate this replay with an experiment group for live streaming in Studio. */
+    /** Group ID to associate this replay with an experiment group for live streaming on the experiments page. */
     experimentGroupId?: string;
     /**
      * Dataset this replay runs against. Mutually exclusive with `datasetIds`.
@@ -2093,7 +2101,7 @@ interface ReplayItem<T> {
      * Token usage from the REPLAYED run (this item's new execution), aggregated
      * server-side from the spans it produced, or null if the run captured no
      * token data. Compare against {@link ReplayItem.originalTokens} to see how
-     * the code change moved cost. Matches what Studio's experiments view shows.
+     * the code change moved cost. Matches what the experiments page shows.
      *
      * Unprefixed because the replay is this item's subject: anything describing
      * the trace being replayed carries `original`.
@@ -2235,6 +2243,7 @@ interface Trace {
     toJSON(): unknown;
 }
 interface Span<_T = any> {
+    spanId?: string;
     traceId?: string;
     toJSON(): unknown;
     spanData?: {
@@ -2323,11 +2332,14 @@ declare class BitfabOpenAITracingProcessor implements TracingProcessor {
      * since the parent withSpan handles completion.
      */
     onTraceEnd(trace: Trace): Promise<void>;
+    private readonly startedSpans;
+    private readonly endedTraces;
+    private cleanupTrace;
     /**
      * Called when a span is started. Span payloads are authoritative completed
      * snapshots, so start notifications do not cross the transport boundary.
      */
-    onSpanStart(_span: Span<any>): Promise<void>;
+    onSpanStart(span: Span<any>): Promise<void>;
     /**
      * Called when a span is ended.
      *
@@ -3379,7 +3391,7 @@ interface CommitRef {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.54.2";
+declare const __version__ = "0.54.4";
 
 /**
  * Constants for the Bitfab SDK.

package/dist/index.js

@@ -20,7 +20,7 @@ import {
   getCurrentTrace,
   reseedFromRegistry,
   seedFromRegistry
-} from "./chunk-4ZACHEMR.js";
+} from "./chunk-A4NRNU72.js";
 import "./chunk-EGWJYCNT.js";
 import {
   BITFAB_PROGRESS_PREFIX,
@@ -29,7 +29,7 @@ import {
   ReplayError,
   reportReplayProgress,
   serializeReplayResult
-} from "./chunk-SPZEKXAE.js";
+} from "./chunk-NFJ6ZZWY.js";
 import {
   BitfabError,
   DEFAULT_SERVICE_URL,
@@ -37,7 +37,7 @@ import {
   MixedTracingError,
   __version__,
   flushTraces
-} from "./chunk-BIEDMC5U.js";
+} from "./chunk-GMUC6A7M.js";
 import "./chunk-VCRFFCLY.js";
 export {
   AssertionCategoriesClient,

package/dist/node.cjs

@@ -88,7 +88,7 @@ var __version__, __packageName__;
 var init_version_generated = __esm({
   "src/version.generated.ts"() {
     "use strict";
-    __version__ = "0.54.2";
+    __version__ = "0.54.4";
     __packageName__ = "@bitfab/sdk";
   }
 });
@@ -103,6 +103,99 @@ var init_constants = __esm({
   }
 });
 
+// src/traceCompletion.ts
+var TraceCompletion;
+var init_traceCompletion = __esm({
+  "src/traceCompletion.ts"() {
+    "use strict";
+    TraceCompletion = class {
+      constructor() {
+        this.traces = /* @__PURE__ */ new Map();
+        this.closed = /* @__PURE__ */ new Map();
+      }
+      state(traceId) {
+        let state = this.traces.get(traceId);
+        if (state === void 0) {
+          state = { spanIds: /* @__PURE__ */ new Set(), active: /* @__PURE__ */ new Set() };
+          this.traces.set(traceId, state);
+        }
+        return state;
+      }
+      start(traceId, spanId) {
+        if (this.closed.has(traceId)) {
+          return;
+        }
+        const state = this.state(traceId);
+        state.spanIds.add(spanId);
+        state.active.add(spanId);
+      }
+      open(traceId) {
+        if (!this.closed.has(traceId)) {
+          this.state(traceId);
+        }
+      }
+      hold(traceId, key) {
+        this.state(traceId).active.add(key);
+      }
+      record(traceId, spanId) {
+        if (!this.closed.has(traceId)) {
+          this.state(traceId).spanIds.add(spanId);
+        }
+      }
+      end(traceId, spanId) {
+        const state = this.traces.get(traceId);
+        if (state !== void 0) {
+          state.active.delete(spanId);
+          this.drain(traceId, state);
+        }
+      }
+      abort(traceId, spanId) {
+        const state = this.traces.get(traceId);
+        if (state === void 0) {
+          return;
+        }
+        state.active.delete(spanId);
+        state.spanIds.delete(spanId);
+        if (state.active.size === 0 && state.spanIds.size === 0 && state.complete === void 0) {
+          this.traces.delete(traceId);
+          return;
+        }
+        this.drain(traceId, state);
+      }
+      close(traceId, complete, dropped = false) {
+        const count = this.closed.get(traceId);
+        if (count !== void 0) {
+          complete(count);
+          return;
+        }
+        const state = this.traces.get(traceId);
+        if (state === void 0) {
+          return;
+        }
+        state.complete = complete;
+        if (dropped) {
+          state.active.clear();
+        }
+        this.drain(traceId, state);
+      }
+      drain(traceId, state) {
+        if (state.active.size !== 0 || state.complete === void 0) {
+          return;
+        }
+        this.traces.delete(traceId);
+        this.closed.set(traceId, state.spanIds.size);
+        if (this.closed.size > 1024) {
+          const oldest = this.closed.keys().next().value;
+          if (oldest !== void 0) {
+            this.closed.delete(oldest);
+          }
+        }
+        state.complete(state.spanIds.size);
+      }
+    };
+  }
+});
+
 // src/readEnv.ts
 function readEnv(name) {
   if (typeof process !== "undefined" && process.env) {
@@ -2150,6 +2243,7 @@ var REPLAY_DB_BRANCH_REQUEST_TIMEOUT_MS, REPLAY_COMPLETE_REQUEST_TIMEOUT_MS, OTL
 var init_http = __esm({
   "src/http.ts"() {
     "use strict";
+    init_traceCompletion();
     init_compress();
     init_constants();
     init_errors();
@@ -2212,6 +2306,7 @@ var init_http = __esm({
         // must not wait on another client's slow finalize: a false `close()` failure
         // caused by unrelated work is worse than no signal at all.
         this.deferredWork = /* @__PURE__ */ new Set();
+        this.traceCompletion = new TraceCompletion();
         this.closed = false;
         this.apiKey = config.apiKey;
         this.serviceUrl = config.serviceUrl;
@@ -2645,6 +2740,10 @@ var init_http = __esm({
         );
       }
       sendExternalSpan(payload) {
+        const ref2 = carrierRef(payload);
+        if (ref2?.spanId !== void 0) {
+          this.traceCompletion.record(ref2.traceId, ref2.spanId);
+        }
         const gate = this.externalSpanTransform;
         if (gate === void 0) {
           this.submitExternalSpan(payload);
@@ -2676,13 +2775,28 @@ var init_http = __esm({
        */
       sendExternalTrace(rawPayload) {
         const payload = mergeCallerMetadataIntoTracePayload(rawPayload);
-        const gate = this.externalTraceTransform;
-        if (gate === void 0) {
-          this.submitExternalTrace(payload);
+        const traceId = sourceTraceIdOf(payload);
+        if (payload.completed === true && traceId !== void 0) {
+          this.traceCompletion.close(
+            traceId,
+            (expectedSpanCount) => this.sendCountedExternalTrace({ ...payload, expectedSpanCount }),
+            payload.dropped === true
+          );
           return;
         }
+        if (traceId !== void 0) {
+          this.traceCompletion.open(traceId);
+        }
+        this.sendCountedExternalTrace(payload);
+      }
+      sendCountedExternalTrace(payload) {
         try {
-          gate(payload, (ready) => this.submitExternalTrace(ready));
+          const gate = this.externalTraceTransform;
+          if (gate === void 0) {
+            this.submitExternalTrace(payload);
+          } else {
+            gate(payload, (ready) => this.submitExternalTrace(ready));
+          }
         } catch (error) {
           warnDroppedExternalTrace(error);
         }
@@ -4508,6 +4622,7 @@ var BitfabClaudeAgentHandler = class {
       spanInfo.dropped = [...inputDropped];
     }
     this.runToSpan.set(spanId, spanInfo);
+    this.httpClient.traceCompletion.start(spanInfo.traceId, spanInfo.spanId);
     return spanInfo;
   }
   completeSpan(spanId, output, error, extraContexts) {
@@ -4529,6 +4644,7 @@ var BitfabClaudeAgentHandler = class {
       spanInfo.contexts.push(extraContexts);
     }
     this.sendSpan(spanInfo);
+    this.httpClient.traceCompletion.end(spanInfo.traceId, spanInfo.spanId);
   }
   sendSpan(spanInfo) {
     const spanData = {
@@ -6186,6 +6302,9 @@ var BitfabLangGraphCallbackHandler = class {
       spanInfo.hidden = true;
     }
     this.runToSpan.set(runId, spanInfo);
+    if (spanInfo.hidden !== true) {
+      this.httpClient.traceCompletion.start(spanInfo.traceId, spanInfo.spanId);
+    }
     if (isRootInvocation) {
       this.sendTraceStart(spanInfo);
     }
@@ -6217,6 +6336,7 @@ var BitfabLangGraphCallbackHandler = class {
       this.sendTraceCompletion(spanInfo, invocation?.activeContext ?? null);
       this.invocations.delete(runId);
     }
+    this.httpClient.traceCompletion.end(spanInfo.traceId, spanInfo.spanId);
   }
   sendSpan(spanInfo) {
     const spanData = {
@@ -6938,6 +7058,8 @@ var BitfabOpenAITracingProcessor = class {
     this.activeTraces = {};
     this.activeSpanMappings = {};
     this.canonicalTraceIds = {};
+    this.startedSpans = /* @__PURE__ */ new Map();
+    this.endedTraces = /* @__PURE__ */ new Set();
     this.ownsHttpClient = config._httpClient === void 0;
     this.httpClient = config._httpClient ?? new HttpClient({
       apiKey: config.apiKey,
@@ -6976,6 +7098,10 @@ var BitfabOpenAITracingProcessor = class {
     }
     const canonicalTraceId = activeContext?.traceId ?? this.getCanonicalTraceId(trace.traceId);
     this.canonicalTraceIds[trace.traceId] = canonicalTraceId;
+    this.httpClient.traceCompletion.hold(
+      activeContext?.traceId ?? trace.traceId,
+      `openai:${trace.traceId}`
+    );
     this.sendTrace(trace, {
       id: canonicalTraceId,
       sourceTraceId: activeContext?.traceId
@@ -6993,16 +7119,33 @@ var BitfabOpenAITracingProcessor = class {
       id: mapping?.traceId ?? this.getCanonicalTraceId(trace.traceId),
       sourceTraceId: mapping?.traceId
     });
-    delete this.activeSpanMappings[trace.traceId];
-    delete this.canonicalTraceIds[trace.traceId];
-    delete this.activeTraces[trace.traceId];
+    this.endedTraces.add(trace.traceId);
+    this.httpClient.traceCompletion.end(
+      mapping?.traceId ?? trace.traceId,
+      `openai:${trace.traceId}`
+    );
+    this.cleanupTrace(trace.traceId);
+  }
+  cleanupTrace(traceId) {
+    if (!this.endedTraces.has(traceId) || [...this.startedSpans.values()].includes(traceId)) {
+      return;
+    }
+    this.endedTraces.delete(traceId);
+    delete this.activeSpanMappings[traceId];
+    delete this.canonicalTraceIds[traceId];
+    delete this.activeTraces[traceId];
   }
   /**
    * Called when a span is started. Span payloads are authoritative completed
    * snapshots, so start notifications do not cross the transport boundary.
    */
   // biome-ignore lint/suspicious/noExplicitAny: OpenAI Agents SDK uses any for span data
-  async onSpanStart(_span) {
+  async onSpanStart(span) {
+    if (span.spanId !== void 0 && span.traceId !== null && span.traceId !== void 0) {
+      this.startedSpans.set(span.spanId, span.traceId);
+      const traceId = this.activeSpanMappings[span.traceId]?.traceId ?? span.traceId;
+      this.httpClient.traceCompletion.start(traceId, span.spanId);
+    }
   }
   /**
    * Called when a span is ended.
@@ -7011,7 +7154,17 @@ var BitfabOpenAITracingProcessor = class {
    */
   // biome-ignore lint/suspicious/noExplicitAny: OpenAI Agents SDK uses any for span data
   async onSpanEnd(span) {
-    this.sendSpan(span);
+    const originalTraceId = span.traceId ?? "";
+    const traceId = this.activeSpanMappings[originalTraceId]?.traceId ?? originalTraceId;
+    try {
+      this.sendSpan(span);
+    } finally {
+      if (span.spanId !== void 0) {
+        this.httpClient.traceCompletion.end(traceId, span.spanId);
+        this.startedSpans.delete(span.spanId);
+      }
+      this.cleanupTrace(originalTraceId);
+    }
   }
   /**
    * Called when a trace is being flushed.
@@ -8717,6 +8870,7 @@ var Bitfab = class {
       let newStack;
       let executeWithContext;
       let registeredTraceId;
+      let startedSpan;
       try {
         const currentStack = getSpanStack();
         const parentContext = currentStack[currentStack.length - 1];
@@ -8768,6 +8922,8 @@ var Bitfab = class {
           });
           registeredTraceId = traceId;
         }
+        self.httpClient.traceCompletion.start(traceId, spanId);
+        startedSpan = { traceId, spanId };
         const functionName = fn.name !== "" ? fn.name : void 0;
         const rootTraceFunctionKey = activeTraceStates.get(traceId)?.traceFunctionKey ?? traceFunctionKey;
         const baseSpanParams = {
@@ -8842,6 +8998,8 @@ var Bitfab = class {
               retireTraceMetadata(traceId);
             }
           } catch {
+          } finally {
+            self.httpClient.traceCompletion.end(traceId, spanId);
           }
         };
         const recordSpan = (result) => {
@@ -8858,6 +9016,14 @@ var Bitfab = class {
             void sendSpan({ result });
           }
         };
+        const resolveMockOrAbort = async (resolve) => {
+          try {
+            return await resolve();
+          } catch (error) {
+            self.httpClient.traceCompletion.abort(traceId, spanId);
+            throw error;
+          }
+        };
         executeWithContext = () => {
           let result;
           try {
@@ -8914,7 +9080,7 @@ var Bitfab = class {
               );
             }
             return (async () => {
-              const output = await pending;
+              const output = await resolveMockOrAbort(() => pending);
               void sendSpan({
                 result: output,
                 mocked: true,
@@ -8984,7 +9150,7 @@ var Bitfab = class {
                 );
               }
               return runWithSpanStack(newStack, async () => {
-                const resolved2 = await resolution;
+                const resolved2 = await resolveMockOrAbort(() => resolution);
                 if (resolved2.matched) {
                   void sendSpan({
                     result: resolved2.output,
@@ -9000,7 +9166,9 @@ var Bitfab = class {
                   );
                 }
                 if (shouldMockWithBaseStrategy) {
-                  const output = await resolveRecordedOutput();
+                  const output = await resolveMockOrAbort(
+                    () => resolveRecordedOutput()
+                  );
                   void sendSpan({
                     result: output,
                     mocked: true,
@@ -9030,6 +9198,12 @@ var Bitfab = class {
           }
         }
       } catch (setupError) {
+        if (startedSpan) {
+          self.httpClient.traceCompletion.abort(
+            startedSpan.traceId,
+            startedSpan.spanId
+          );
+        }
         if (registeredTraceId) {
           activeTraceStates.delete(registeredTraceId);
           retireTraceMetadata(registeredTraceId);