@bitfab/sdk 0.26.1 → 0.27.0

package/dist/index.cjs

@@ -64,35 +64,6 @@ var init_warnOnce = __esm({
   }
 });
 
-// src/randomUuid.ts
-function randomUuid() {
-  const globalCrypto = globalThis.crypto;
-  if (typeof globalCrypto?.randomUUID === "function") {
-    try {
-      return globalCrypto.randomUUID();
-    } catch {
-    }
-  }
-  warnOnce(
-    "crypto-unavailable",
-    "global crypto.randomUUID is unavailable; using a non-cryptographic fallback for trace/span ids. Tracing works normally (ids are correlation-only, not security-sensitive)."
-  );
-  return fallbackUuidV4();
-}
-function fallbackUuidV4() {
-  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (char) => {
-    const rand = Math.random() * 16 | 0;
-    const value = char === "x" ? rand : rand & 3 | 8;
-    return value.toString(16);
-  });
-}
-var init_randomUuid = __esm({
-  "src/randomUuid.ts"() {
-    "use strict";
-    init_warnOnce();
-  }
-});
-
 // src/serialize.ts
 function describeValue(value) {
   try {
@@ -148,7 +119,11 @@ function deserializeValue(serialized) {
   });
 }
 function toJsonSafe(value) {
-  const safe = toJsonSafeInner(value, 0, /* @__PURE__ */ new WeakSet());
+  return toJsonSafeReport(value).safe;
+}
+function toJsonSafeReport(value) {
+  const dropped = [];
+  const safe = toJsonSafeInner(value, 0, /* @__PURE__ */ new WeakSet(), dropped);
   try {
     const size = JSON.stringify(safe)?.length ?? 0;
     if (size > MAX_FRAMEWORK_SERIALIZED_BYTES) {
@@ -156,13 +131,16 @@ function toJsonSafe(value) {
         "toJsonSafe:too_large",
         `a framework payload exceeded ${MAX_FRAMEWORK_SERIALIZED_BYTES} bytes and was replaced with a placeholder so the span still ships. The captured state for this span is incomplete.`
       );
-      return `<unserializable: too_large_${size}_bytes>`;
+      return {
+        safe: `<unserializable: too_large_${size}_bytes>`,
+        dropped: [...dropped, `too_large_${size}_bytes`]
+      };
     }
   } catch {
   }
-  return safe;
+  return { safe, dropped };
 }
-function toJsonSafeInner(value, depth, seen) {
+function toJsonSafeInner(value, depth, seen, dropped) {
   if (value === null || value === void 0) {
     return value;
   }
@@ -171,30 +149,40 @@ function toJsonSafeInner(value, depth, seen) {
   }
   const className = value?.constructor?.name ?? typeof value;
   if (depth > MAX_SAFE_DEPTH) {
+    dropped.push(className);
     return `<${className}>`;
   }
   if (typeof value !== "object") {
+    if (typeof value === "function" || typeof value === "symbol") {
+      dropped.push(className);
+    }
     try {
       return String(value);
     } catch {
+      dropped.push(className);
       return `<${className}>`;
     }
   }
   if (seen.has(value)) {
+    dropped.push(className);
     return `<cycle ${className}>`;
   }
   seen.add(value);
   let result;
   if (Array.isArray(value)) {
-    result = value.map((item) => toJsonSafeInner(item, depth + 1, seen));
+    result = value.map(
+      (item) => toJsonSafeInner(item, depth + 1, seen, dropped)
+    );
   } else if (typeof value.toJSON === "function") {
     try {
       result = toJsonSafeInner(
         value.toJSON(),
         depth + 1,
-        seen
+        seen,
+        dropped
       );
     } catch {
+      dropped.push(className);
       result = `<${className}>`;
     }
   } else {
@@ -202,11 +190,12 @@ function toJsonSafeInner(value, depth, seen) {
       const obj = {};
       for (const [k, v] of Object.entries(value)) {
         if (!k.startsWith("_")) {
-          obj[k] = toJsonSafeInner(v, depth + 1, seen);
+          obj[k] = toJsonSafeInner(v, depth + 1, seen, dropped);
         }
       }
       result = obj;
     } catch {
+      dropped.push(className);
       result = `<${className}>`;
     }
   }
@@ -225,6 +214,35 @@ var init_serialize = __esm({
   }
 });
 
+// src/randomUuid.ts
+function randomUuid() {
+  const globalCrypto = globalThis.crypto;
+  if (typeof globalCrypto?.randomUUID === "function") {
+    try {
+      return globalCrypto.randomUUID();
+    } catch {
+    }
+  }
+  warnOnce(
+    "crypto-unavailable",
+    "global crypto.randomUUID is unavailable; using a non-cryptographic fallback for trace/span ids. Tracing works normally (ids are correlation-only, not security-sensitive)."
+  );
+  return fallbackUuidV4();
+}
+function fallbackUuidV4() {
+  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (char) => {
+    const rand = Math.random() * 16 | 0;
+    const value = char === "x" ? rand : rand & 3 | 8;
+    return value.toString(16);
+  });
+}
+var init_randomUuid = __esm({
+  "src/randomUuid.ts"() {
+    "use strict";
+    init_warnOnce();
+  }
+});
+
 // src/asyncStorage.ts
 function registerAsyncLocalStorageClass(cls) {
   if (!AsyncLocalStorageClass) {
@@ -289,8 +307,21 @@ var init_replayContext = __esm({
 // src/replay.ts
 var replay_exports = {};
 __export(replay_exports, {
-  replay: () => replay
+  BITFAB_PROGRESS_PREFIX: () => BITFAB_PROGRESS_PREFIX,
+  replay: () => replay,
+  reportReplayProgress: () => reportReplayProgress
 });
+function reportReplayProgress(progress) {
+  const stderr = typeof process !== "undefined" ? process.stderr : void 0;
+  if (!stderr) {
+    return;
+  }
+  try {
+    stderr.write(`${BITFAB_PROGRESS_PREFIX}${JSON.stringify(progress)}
+`);
+  } catch {
+  }
+}
 function deserializeInputs(spanData) {
   const inputMeta = spanData.input_meta;
   const rawInput = spanData.input;
@@ -488,7 +519,7 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options) {
   const resultItems = await mapWithConcurrency(
     tasks,
     maxConcurrency,
-    options?.onProgress ? (item) => {
+    options?.onProgress ? (item, index) => {
       completed += 1;
       if (item.error === null) {
         succeeded += 1;
@@ -496,7 +527,20 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options) {
         errored += 1;
       }
       try {
-        options?.onProgress?.({ completed, total, succeeded, errored });
+        options?.onProgress?.({
+          completed,
+          total,
+          succeeded,
+          errored,
+          item: {
+            // Source (historical) trace id, so a UI can identify the trace
+            // that just settled. The item's own traceId is the new replay
+            // trace and is assigned later (below), so use the server item.
+            traceId: serverItems[index]?.traceId ?? null,
+            error: item.error,
+            durationMs: item.durationMs
+          }
+        });
       } catch {
       }
     } : void 0
@@ -553,6 +597,7 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options) {
     testRunUrl: `${serviceUrl}${testRunUrl}`
   };
 }
+var BITFAB_PROGRESS_PREFIX;
 var init_replay = __esm({
   "src/replay.ts"() {
     "use strict";
@@ -560,12 +605,14 @@ var init_replay = __esm({
     init_randomUuid();
     init_replayContext();
     init_serialize();
+    BITFAB_PROGRESS_PREFIX = "@@bitfab:progress ";
   }
 });
 
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  BITFAB_PROGRESS_PREFIX: () => BITFAB_PROGRESS_PREFIX,
   Bitfab: () => Bitfab,
   BitfabClaudeAgentHandler: () => BitfabClaudeAgentHandler,
   BitfabError: () => BitfabError,
@@ -582,12 +629,13 @@ __export(index_exports, {
   finalizers: () => finalizers,
   flushTraces: () => flushTraces,
   getCurrentSpan: () => getCurrentSpan,
-  getCurrentTrace: () => getCurrentTrace
+  getCurrentTrace: () => getCurrentTrace,
+  reportReplayProgress: () => reportReplayProgress
 });
 module.exports = __toCommonJS(index_exports);
 
 // src/version.generated.ts
-var __version__ = "0.26.1";
+var __version__ = "0.27.0";
 
 // src/constants.ts
 var DEFAULT_SERVICE_URL = "https://bitfab.ai";
@@ -1029,6 +1077,62 @@ var HttpClient = class {
   }
 };
 
+// src/processorPayload.ts
+init_serialize();
+init_warnOnce();
+var SERIALIZATION_DEGRADED_STEP = "serialization_degraded";
+function degradedError(dropped) {
+  const names = [...new Set(dropped)].sort().join(", ");
+  return {
+    source: "sdk",
+    step: SERIALIZATION_DEGRADED_STEP,
+    error: `non-replayable: could not faithfully capture ${names}`
+  };
+}
+var ENVELOPE_FIELDS = [
+  "type",
+  "source",
+  "traceFunctionKey",
+  "sourceTraceId",
+  "completed"
+];
+function rebuildEnvelope(payload, bodyKey, placeholder) {
+  const rebuilt = {};
+  for (const k of ENVELOPE_FIELDS) {
+    if (k in payload) {
+      rebuilt[k] = payload[k];
+    }
+  }
+  rebuilt[bodyKey] = { serialized: placeholder };
+  return rebuilt;
+}
+function finalizeSpanPayload(payload, extraDropped) {
+  const { safe, dropped } = toJsonSafeReport(payload);
+  const allDropped = [...extraDropped ?? [], ...dropped];
+  const collapsed = safe === null || typeof safe !== "object" || Array.isArray(safe);
+  const result = collapsed ? rebuildEnvelope(payload, "rawSpan", safe) : safe;
+  if (allDropped.length > 0) {
+    const existing = result.errors;
+    const errors = Array.isArray(existing) ? existing : [];
+    errors.push(degradedError(allDropped));
+    result.errors = errors;
+  }
+  return result;
+}
+function finalizeTracePayload(payload) {
+  const { safe, dropped } = toJsonSafeReport(payload);
+  const collapsed = safe === null || typeof safe !== "object" || Array.isArray(safe);
+  const result = collapsed ? rebuildEnvelope(payload, "externalTrace", safe) : safe;
+  if (dropped.length > 0 || collapsed) {
+    const names = dropped.length > 0 ? [...new Set(dropped)].sort().join(", ") : "trace";
+    warnOnce(
+      `finalizeTrace:${names.replace(/\d+/g, "N")}`,
+      `a trace held non-serializable value(s) (${names}); they were captured as placeholders, so the trace may not be replayable.`
+    );
+  }
+  return result;
+}
+
 // src/claudeAgentSdk.ts
 init_randomUuid();
 init_serialize();
@@ -1158,6 +1262,7 @@ var BitfabClaudeAgentHandler = class {
   // ── span helpers ─────────────────────────────────────────────
   startSpan(spanId, name, spanType, inputData, parentId) {
     const traceId = this.ensureTrace();
+    const { safe: safeInput, dropped: inputDropped } = toJsonSafeReport(inputData);
     const spanInfo = {
       spanId,
       traceId,
@@ -1165,9 +1270,12 @@ var BitfabClaudeAgentHandler = class {
       startedAt: nowIso(),
       name,
       type: spanType,
-      input: safeSerialize(inputData),
+      input: safeInput,
       contexts: []
     };
+    if (inputDropped.length > 0) {
+      spanInfo.dropped = [...inputDropped];
+    }
     this.runToSpan.set(spanId, spanInfo);
     return spanInfo;
   }
@@ -1178,7 +1286,11 @@ var BitfabClaudeAgentHandler = class {
     }
     this.runToSpan.delete(spanId);
     spanInfo.endedAt = nowIso();
-    spanInfo.output = safeSerialize(output);
+    const { safe: safeOutput, dropped: outputDropped } = toJsonSafeReport(output);
+    spanInfo.output = safeOutput;
+    if (outputDropped.length > 0) {
+      spanInfo.dropped = [...spanInfo.dropped ?? [], ...outputDropped];
+    }
     if (error !== void 0) {
       spanInfo.error = error;
     }
@@ -1221,8 +1333,9 @@ var BitfabClaudeAgentHandler = class {
       sourceTraceId: spanInfo.traceId,
       rawSpan
     };
+    const finalized = finalizeSpanPayload(payload, spanInfo.dropped);
     try {
-      this.httpClient.sendExternalSpan(payload);
+      this.httpClient.sendExternalSpan(finalized);
     } catch {
     }
   }
@@ -1249,8 +1362,9 @@ var BitfabClaudeAgentHandler = class {
       externalTrace,
       completed
     };
+    const finalized = finalizeTracePayload(traceData);
     try {
-      this.httpClient.sendExternalTrace(traceData);
+      this.httpClient.sendExternalTrace(finalized);
     } catch {
     }
   }
@@ -1888,7 +2002,6 @@ var LANGGRAPH_METADATA_KEYS = [
 function nowIso2() {
   return (/* @__PURE__ */ new Date()).toISOString();
 }
-var safeSerialize2 = toJsonSafe;
 function convertMessage(message) {
   if (typeof message !== "object" || message === null) {
     return { role: "unknown", content: String(message) };
@@ -2133,6 +2246,7 @@ var BitfabLangGraphCallbackHandler = class {
     }
     const lgMetadata = extractLangGraphMetadata(metadata);
     const contexts = Object.keys(lgMetadata).length > 0 ? [lgMetadata] : [];
+    const { safe: safeInput, dropped: inputDropped } = toJsonSafeReport(inputData);
     const spanInfo = {
       spanId: runId,
       traceId: invocation.traceId,
@@ -2141,9 +2255,12 @@ var BitfabLangGraphCallbackHandler = class {
       startedAt: nowIso2(),
       name,
       type: spanType,
-      input: safeSerialize2(inputData),
+      input: safeInput,
       contexts
     };
+    if (inputDropped.length > 0) {
+      spanInfo.dropped = [...inputDropped];
+    }
     if (willHide) {
       spanInfo.hidden = true;
     }
@@ -2157,7 +2274,11 @@ var BitfabLangGraphCallbackHandler = class {
     }
     this.runToSpan.delete(runId);
     spanInfo.endedAt = nowIso2();
-    spanInfo.output = safeSerialize2(output);
+    const { safe: safeOutput, dropped: outputDropped } = toJsonSafeReport(output);
+    spanInfo.output = safeOutput;
+    if (outputDropped.length > 0) {
+      spanInfo.dropped = [...spanInfo.dropped ?? [], ...outputDropped];
+    }
     if (error !== void 0) {
       spanInfo.error = error;
     }
@@ -2208,8 +2329,9 @@ var BitfabLangGraphCallbackHandler = class {
       sourceTraceId: spanInfo.traceId,
       rawSpan
     };
+    const finalized = finalizeSpanPayload(payload, spanInfo.dropped);
     try {
-      this.httpClient.sendExternalSpan(payload);
+      this.httpClient.sendExternalSpan(finalized);
     } catch {
     }
   }
@@ -2227,8 +2349,9 @@ var BitfabLangGraphCallbackHandler = class {
       },
       completed
     };
+    const finalized = finalizeTracePayload(traceData);
     try {
-      this.httpClient.sendExternalTrace(traceData);
+      this.httpClient.sendExternalTrace(finalized);
     } catch {
     }
   }
@@ -2743,7 +2866,7 @@ var BitfabOpenAITracingProcessor = class {
     if (errors.length > 0) {
       payload.errors = errors;
     }
-    return payload;
+    return finalizeSpanPayload(payload);
   }
   /**
    * Send span to Bitfab API (fire-and-forget).
@@ -4253,8 +4376,12 @@ var finalizers = {
   aiSdk,
   readableStream
 };
+
+// src/index.ts
+init_replay();
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  BITFAB_PROGRESS_PREFIX,
   Bitfab,
   BitfabClaudeAgentHandler,
   BitfabError,
@@ -4271,6 +4398,7 @@ var finalizers = {
   finalizers,
   flushTraces,
   getCurrentSpan,
-  getCurrentTrace
+  getCurrentTrace,
+  reportReplayProgress
 });
 //# sourceMappingURL=index.cjs.map