bitfab 0.12.1 → 0.13.0

package/dist/index.d.cts

@@ -467,6 +467,38 @@ interface CurrentSpan {
      */
     setPrompt(prompt: string): void;
 }
+/**
+ * A detached handle to a previously-created trace, looked up by its
+ * caller-supplied id (the same id passed when the trace was started).
+ *
+ * Unlike `getCurrentTrace()`, this handle is not tied to AsyncLocalStorage —
+ * each method sends to the server immediately. Useful for adding context
+ * to a trace from a different process, request, or thread (e.g. a forked
+ * agent that wants to annotate the original conversation's trace).
+ */
+interface DetachedTrace {
+    /** The caller-supplied trace id this handle resolves. */
+    readonly traceId: string;
+    /**
+     * Append a context entry to this trace. Each call adds one entry to the
+     * server-side contexts array; existing entries are preserved.
+     *
+     * Returns a promise that the caller may await for confirmation, or ignore
+     * to fire-and-forget. The pending request is tracked so `flushTraces()`
+     * waits for it.
+     */
+    addContext(context: Record<string, unknown>): Promise<unknown>;
+    /**
+     * Merge metadata into this trace. Server-side shallow-merges the new keys
+     * into the existing metadata object; existing keys are preserved unless
+     * overwritten by the new values.
+     */
+    setMetadata(metadata: Record<string, unknown>): Promise<unknown>;
+    /**
+     * Set the sessionId for this trace. Replaces any existing sessionId.
+     */
+    setSessionId(sessionId: string): Promise<unknown>;
+}
 /**
  * A handle to the current active trace, allowing trace-level context to be set.
  */
@@ -707,6 +739,27 @@ declare class Bitfab {
      * @returns A wrapped function with the same signature that creates spans for inputs and outputs
      */
     withSpan<TArgs extends unknown[], TReturn>(traceFunctionKey: string, optionsOrFn: SpanOptions | ((...args: TArgs) => TReturn), maybeFn?: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
+    /**
+     * Get a detached handle to a previously-created trace, looked up by the
+     * caller-supplied id (the same id passed at trace creation).
+     *
+     * The returned handle is not tied to AsyncLocalStorage — each method sends
+     * to the server immediately. Useful for adding context to a trace from a
+     * different process or thread than the one that created it.
+     *
+     * Throws synchronously if `traceId` is malformed (empty, too long, or
+     * contains characters outside `[a-zA-Z0-9_\-.:]`). Server returns 404 if
+     * no trace exists with that id in the org; the failure surfaces as a
+     * logged warning (fire-and-forget) or via the awaited promise.
+     *
+     * Example:
+     * ```typescript
+     * const trace = client.getTrace("order_abc_123");
+     * await trace.addContext({ refund_status: "approved" });
+     * await trace.setMetadata({ region: "us-west" });
+     * ```
+     */
+    getTrace(traceId: string): DetachedTrace;
     /**
      * Get a function wrapper for a specific trace function key.
      *
@@ -822,7 +875,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.12.1";
+declare const __version__ = "0.13.0";
 
 /**
  * Constants for the Bitfab SDK.
@@ -832,4 +885,4 @@ declare const __version__ = "0.12.1";
  */
 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 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 };
+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 DetachedTrace, 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

@@ -467,6 +467,38 @@ interface CurrentSpan {
      */
     setPrompt(prompt: string): void;
 }
+/**
+ * A detached handle to a previously-created trace, looked up by its
+ * caller-supplied id (the same id passed when the trace was started).
+ *
+ * Unlike `getCurrentTrace()`, this handle is not tied to AsyncLocalStorage —
+ * each method sends to the server immediately. Useful for adding context
+ * to a trace from a different process, request, or thread (e.g. a forked
+ * agent that wants to annotate the original conversation's trace).
+ */
+interface DetachedTrace {
+    /** The caller-supplied trace id this handle resolves. */
+    readonly traceId: string;
+    /**
+     * Append a context entry to this trace. Each call adds one entry to the
+     * server-side contexts array; existing entries are preserved.
+     *
+     * Returns a promise that the caller may await for confirmation, or ignore
+     * to fire-and-forget. The pending request is tracked so `flushTraces()`
+     * waits for it.
+     */
+    addContext(context: Record<string, unknown>): Promise<unknown>;
+    /**
+     * Merge metadata into this trace. Server-side shallow-merges the new keys
+     * into the existing metadata object; existing keys are preserved unless
+     * overwritten by the new values.
+     */
+    setMetadata(metadata: Record<string, unknown>): Promise<unknown>;
+    /**
+     * Set the sessionId for this trace. Replaces any existing sessionId.
+     */
+    setSessionId(sessionId: string): Promise<unknown>;
+}
 /**
  * A handle to the current active trace, allowing trace-level context to be set.
  */
@@ -707,6 +739,27 @@ declare class Bitfab {
      * @returns A wrapped function with the same signature that creates spans for inputs and outputs
      */
     withSpan<TArgs extends unknown[], TReturn>(traceFunctionKey: string, optionsOrFn: SpanOptions | ((...args: TArgs) => TReturn), maybeFn?: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
+    /**
+     * Get a detached handle to a previously-created trace, looked up by the
+     * caller-supplied id (the same id passed at trace creation).
+     *
+     * The returned handle is not tied to AsyncLocalStorage — each method sends
+     * to the server immediately. Useful for adding context to a trace from a
+     * different process or thread than the one that created it.
+     *
+     * Throws synchronously if `traceId` is malformed (empty, too long, or
+     * contains characters outside `[a-zA-Z0-9_\-.:]`). Server returns 404 if
+     * no trace exists with that id in the org; the failure surfaces as a
+     * logged warning (fire-and-forget) or via the awaited promise.
+     *
+     * Example:
+     * ```typescript
+     * const trace = client.getTrace("order_abc_123");
+     * await trace.addContext({ refund_status: "approved" });
+     * await trace.setMetadata({ region: "us-west" });
+     * ```
+     */
+    getTrace(traceId: string): DetachedTrace;
     /**
      * Get a function wrapper for a specific trace function key.
      *
@@ -822,7 +875,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.12.1";
+declare const __version__ = "0.13.0";
 
 /**
  * Constants for the Bitfab SDK.
@@ -832,4 +885,4 @@ declare const __version__ = "0.12.1";
  */
 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 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 };
+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 DetachedTrace, 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-NU52P7HA.js";
+} from "./chunk-62NGOY7Q.js";
 import {
   BitfabError,
   DEFAULT_SERVICE_URL,
   __version__,
   flushTraces
-} from "./chunk-OOKZ6S64.js";
+} from "./chunk-QLVXAFGP.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.12.1";
+    __version__ = "0.13.0";
   }
 });
 
@@ -151,7 +151,8 @@ var init_http = __esm({
         this.timeout = config.timeout ?? 12e4;
       }
       /**
-       * Make an HTTP POST request to the Bitfab API.
+       * Make an HTTP request to the Bitfab API. Defaults to POST; pass
+       * `options.method` to use a different verb (e.g. "PATCH").
        *
        * @param endpoint - The API endpoint (without base URL)
        * @param payload - The request body
@@ -162,6 +163,7 @@ var init_http = __esm({
       async request(endpoint, payload, options) {
         const url = `${this.serviceUrl}${endpoint}`;
         const timeout = options?.timeout ?? this.timeout;
+        const method = options?.method ?? "POST";
         const controller = new AbortController();
         const timeoutId = setTimeout(() => controller.abort(), timeout);
         let body;
@@ -182,7 +184,7 @@ var init_http = __esm({
         }
         try {
           const response = await fetch(url, {
-            method: "POST",
+            method,
             headers: {
               "Content-Type": "application/json",
               Authorization: `Bearer ${this.apiKey}`
@@ -281,6 +283,22 @@ var init_http = __esm({
           }
         });
       }
+      /**
+       * Partial update of an existing external trace identified by sourceTraceId.
+       * Used by the detached `client.getTrace(id)` handle. Fire-and-forget;
+       * returns a tracked promise that callers may optionally await.
+       */
+      patchTrace(sourceTraceId, payload) {
+        const endpoint = `/api/sdk/externalTraces/${encodeURIComponent(sourceTraceId)}`;
+        return awaitOnExit(
+          this.request(endpoint, payload, { method: "PATCH" })
+        ).catch((error) => {
+          try {
+            console.error("Bitfab: Failed to patch trace:", error);
+          } catch {
+          }
+        });
+      }
       /**
        * Start a replay session by fetching historical traces.
        * Blocking call — creates a test run and returns lightweight item references.
@@ -473,9 +491,11 @@ function buildMockTree(rootNode) {
   function walk(node) {
     const key = node.traceFunctionKey;
     if (key) {
-      const index = counters.get(key) ?? 0;
-      counters.set(key, index + 1);
-      spans.set(`${key}:${index}`, {
+      const name = node.spanName;
+      const counterKey = `${key}:${name}`;
+      const index = counters.get(counterKey) ?? 0;
+      counters.set(counterKey, index + 1);
+      spans.set(`${counterKey}:${index}`, {
         sourceSpanId: node.sourceSpanId,
         output: node.output,
         outputMeta: node.outputMeta
@@ -485,7 +505,9 @@ function buildMockTree(rootNode) {
       walk(child);
     }
   }
-  walk(rootNode);
+  for (const child of rootNode.children) {
+    walk(child);
+  }
   return { spans };
 }
 async function processItem(httpClient, serverItem, fn, testRunId, mockStrategy) {
@@ -2223,6 +2245,23 @@ function extractContextFromCollector(collector) {
     return null;
   }
 }
+var TRACE_ID_PATTERN = /^[a-zA-Z0-9_\-.:]+$/;
+var TRACE_ID_MAX_LENGTH = 256;
+function validateTraceId(traceId) {
+  if (typeof traceId !== "string" || traceId.length === 0) {
+    throw new BitfabError("traceId is required and must be a non-empty string");
+  }
+  if (traceId.length > TRACE_ID_MAX_LENGTH) {
+    throw new BitfabError(
+      `traceId must be ${TRACE_ID_MAX_LENGTH} characters or fewer`
+    );
+  }
+  if (!TRACE_ID_PATTERN.test(traceId)) {
+    throw new BitfabError(
+      `traceId may only contain letters, digits, "_", "-", ".", ":"`
+    );
+  }
+}
 var noOpSpan = {
   traceId: "",
   addContext() {
@@ -2615,6 +2654,15 @@ var Bitfab = class {
     const options = typeof optionsOrFn === "function" ? {} : optionsOrFn;
     const fn = typeof optionsOrFn === "function" ? optionsOrFn : maybeFn;
     const self = this;
+    const fnIsAsyncFunction = fn.constructor.name === "AsyncFunction";
+    const fnReturnsPromise = fnIsAsyncFunction || (() => {
+      try {
+        const src = fn.toString();
+        return /\b(?:Promise|await)\b/.test(src);
+      } catch {
+        return false;
+      }
+    })();
     const wrappedFn = function(...args) {
       if (!asyncLocalStorage && !isAsyncStorageInitDone()) {
         return asyncLocalStorageReady.then(
@@ -2708,11 +2756,12 @@ var Bitfab = class {
       const replayCtxForMock = getReplayContext();
       if (replayCtxForMock?.mockTree && !isRootSpan) {
         const counters = replayCtxForMock.callCounters;
-        const callIndex = counters.get(traceFunctionKey) ?? 0;
-        counters.set(traceFunctionKey, callIndex + 1);
+        const counterKey = `${traceFunctionKey}:${baseSpanParams.spanName}`;
+        const callIndex = counters.get(counterKey) ?? 0;
+        counters.set(counterKey, callIndex + 1);
         const shouldMock = replayCtxForMock.mockStrategy === "all" || replayCtxForMock.mockStrategy === "marked" && options.mockOnReplay === true;
         if (shouldMock) {
-          const mockKey = `${traceFunctionKey}:${callIndex}`;
+          const mockKey = `${counterKey}:${callIndex}`;
           const mockSpan = replayCtxForMock.mockTree.spans.get(mockKey);
           if (mockSpan) {
             let output = mockSpan.output;
@@ -2723,7 +2772,7 @@ var Bitfab = class {
               });
             }
             void sendSpan({ result: output });
-            if (fn.constructor.name === "AsyncFunction") {
+            if (fnReturnsPromise) {
               return Promise.resolve(output);
             }
             return output;
@@ -2754,6 +2803,61 @@ var Bitfab = class {
     };
     return wrappedFn;
   }
+  /**
+   * Get a detached handle to a previously-created trace, looked up by the
+   * caller-supplied id (the same id passed at trace creation).
+   *
+   * The returned handle is not tied to AsyncLocalStorage — each method sends
+   * to the server immediately. Useful for adding context to a trace from a
+   * different process or thread than the one that created it.
+   *
+   * Throws synchronously if `traceId` is malformed (empty, too long, or
+   * contains characters outside `[a-zA-Z0-9_\-.:]`). Server returns 404 if
+   * no trace exists with that id in the org; the failure surfaces as a
+   * logged warning (fire-and-forget) or via the awaited promise.
+   *
+   * Example:
+   * ```typescript
+   * const trace = client.getTrace("order_abc_123");
+   * await trace.addContext({ refund_status: "approved" });
+   * await trace.setMetadata({ region: "us-west" });
+   * ```
+   */
+  getTrace(traceId) {
+    validateTraceId(traceId);
+    return {
+      traceId,
+      addContext: (context) => {
+        if (!this.enabled) {
+          return Promise.resolve();
+        }
+        if (typeof context !== "object" || context === null) {
+          return Promise.resolve();
+        }
+        return this.httpClient.patchTrace(traceId, {
+          appendContexts: [context]
+        });
+      },
+      setMetadata: (metadata) => {
+        if (!this.enabled) {
+          return Promise.resolve();
+        }
+        if (typeof metadata !== "object" || metadata === null) {
+          return Promise.resolve();
+        }
+        return this.httpClient.patchTrace(traceId, { mergeMetadata: metadata });
+      },
+      setSessionId: (sessionId) => {
+        if (!this.enabled) {
+          return Promise.resolve();
+        }
+        if (typeof sessionId !== "string" || sessionId.length === 0) {
+          return Promise.resolve();
+        }
+        return this.httpClient.patchTrace(traceId, { setSessionId: sessionId });
+      }
+    };
+  }
   /**
    * Get a function wrapper for a specific trace function key.
    *