bitfab 0.12.2 → 0.13.1

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.2";
+declare const __version__ = "0.13.1";
 
 /**
  * Constants for the Bitfab SDK.
@@ -832,4 +885,4 @@ declare const __version__ = "0.12.2";
  */
 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.2";
+declare const __version__ = "0.13.1";
 
 /**
  * Constants for the Bitfab SDK.
@@ -832,4 +885,4 @@ declare const __version__ = "0.12.2";
  */
 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-3HBV4GQO.js";
+} from "./chunk-HIDM5UYA.js";
 import {
   BitfabError,
   DEFAULT_SERVICE_URL,
   __version__,
   flushTraces
-} from "./chunk-HUSTKOQI.js";
+} from "./chunk-3JCQD7E5.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.2";
+    __version__ = "0.13.1";
   }
 });
 
@@ -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.
@@ -410,15 +428,43 @@ var init_replayContext = __esm({
 });
 
 // src/serialize.ts
+function describeValue(value) {
+  try {
+    const ctorName = value?.constructor?.name;
+    if (ctorName && ctorName !== "Object") {
+      return ctorName;
+    }
+  } catch {
+  }
+  return typeof value;
+}
+function unserializableStub(value, reason) {
+  let summary;
+  try {
+    summary = `<unserializable: ${describeValue(value)} (${reason})>`;
+  } catch {
+    summary = `<unserializable (${reason})>`;
+  }
+  return { json: summary };
+}
 function serializeValue(value) {
   try {
     const { json, meta } = import_superjson.default.serialize(value);
+    let size;
+    try {
+      size = JSON.stringify(json).length;
+    } catch {
+      return unserializableStub(value, "stringify_failed_after_superjson");
+    }
+    if (size > MAX_SERIALIZED_BYTES) {
+      return unserializableStub(value, `too_large_${size}_bytes`);
+    }
     return meta ? { json, meta } : { json };
   } catch {
     try {
       return { json: JSON.parse(JSON.stringify(value)) };
     } catch {
-      return { json: String(value) };
+      return unserializableStub(value, "json_stringify_failed");
     }
   }
 }
@@ -431,11 +477,12 @@ function deserializeValue(serialized) {
     meta: serialized.meta
   });
 }
-var import_superjson;
+var import_superjson, MAX_SERIALIZED_BYTES;
 var init_serialize = __esm({
   "src/serialize.ts"() {
     "use strict";
     import_superjson = __toESM(require("superjson"), 1);
+    MAX_SERIALIZED_BYTES = 512e3;
   }
 });
 
@@ -2227,6 +2274,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() {
@@ -2768,6 +2832,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.
    *