@bitfab/sdk 0.52.6 → 0.53.1

package/dist/index.cjs

@@ -42,7 +42,7 @@ var __version__, __packageName__;
 var init_version_generated = __esm({
   "src/version.generated.ts"() {
     "use strict";
-    __version__ = "0.52.6";
+    __version__ = "0.53.1";
     __packageName__ = "@bitfab/sdk";
   }
 });
@@ -507,8 +507,8 @@ function encodePayloadBody(payload) {
       const marker = { error: `payload_serialize_failed: ${message}` };
       return { body: JSON.stringify(marker), dropped, value: marker };
     }
-    const isRecord2 = typeof sanitized === "object" && sanitized !== null && !Array.isArray(sanitized);
-    if (dropped.length > 0 && isRecord2) {
+    const isRecord4 = typeof sanitized === "object" && sanitized !== null && !Array.isArray(sanitized);
+    if (dropped.length > 0 && isRecord4) {
       const obj = sanitized;
       const existing = Array.isArray(obj.errors) ? obj.errors : [];
       obj.errors = [
@@ -525,7 +525,7 @@ function encodePayloadBody(payload) {
     return {
       body: JSON.stringify(sanitized),
       dropped,
-      value: isRecord2 ? sanitized : void 0
+      value: isRecord4 ? sanitized : void 0
     };
   }
 }
@@ -537,6 +537,456 @@ var init_serializePayload = __esm({
   }
 });
 
+// src/policyRefresh.ts
+var PolicyRefresh;
+var init_policyRefresh = __esm({
+  "src/policyRefresh.ts"() {
+    "use strict";
+    PolicyRefresh = class {
+      constructor() {
+        this.refreshAfter = 0;
+      }
+      due() {
+        return this.inFlight === void 0 && Date.now() >= this.refreshAfter;
+      }
+      hold(durationMs) {
+        this.refreshAfter = Date.now() + durationMs;
+      }
+      releaseHold() {
+        this.refreshAfter = 0;
+      }
+      run(read2, onLoaded, onFailed) {
+        if (!this.due()) {
+          return;
+        }
+        let request;
+        try {
+          request = read2().then(onLoaded).catch(onFailed).finally(() => {
+            this.inFlight = void 0;
+          });
+        } catch (error) {
+          onFailed(error);
+          return;
+        }
+        this.inFlight = request;
+      }
+    };
+  }
+});
+
+// src/spanOrigin.ts
+function isFrameworkInstrumentation(value) {
+  return typeof value === "string" && FRAMEWORK_INSTRUMENTATION_SET.has(value);
+}
+function makeSpanOrigin(instrumentation) {
+  return {
+    name: SPAN_ORIGIN_NAME,
+    version: __version__,
+    instrumentation: { name: instrumentation }
+  };
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function spanOriginOf(payload) {
+  const rawSpan = payload.rawSpan;
+  if (!isRecord(rawSpan)) {
+    return void 0;
+  }
+  const origin = rawSpan.span_origin;
+  if (!isRecord(origin) || !isRecord(origin.instrumentation)) {
+    return void 0;
+  }
+  const { name, version } = origin;
+  const instrumentation = origin.instrumentation.name;
+  if (typeof name !== "string" || typeof version !== "string" || typeof instrumentation !== "string" || !SPAN_INSTRUMENTATIONS.includes(instrumentation)) {
+    return void 0;
+  }
+  return {
+    name,
+    version,
+    instrumentation: { name: instrumentation }
+  };
+}
+function spanInstrumentationOf(payload) {
+  return spanOriginOf(payload)?.instrumentation.name;
+}
+function recordedByFramework(payload) {
+  return isFrameworkInstrumentation(spanInstrumentationOf(payload));
+}
+var SPAN_ORIGIN_NAME, SPAN_INSTRUMENTATIONS, FRAMEWORK_INSTRUMENTATIONS, FRAMEWORK_INSTRUMENTATION_SET;
+var init_spanOrigin = __esm({
+  "src/spanOrigin.ts"() {
+    "use strict";
+    init_constants();
+    SPAN_ORIGIN_NAME = "bitfab.sdk.typescript";
+    SPAN_INSTRUMENTATIONS = [
+      "span",
+      "trace",
+      "openai-agents",
+      "langgraph",
+      "claude-agent-sdk",
+      "vercel-ai"
+    ];
+    FRAMEWORK_INSTRUMENTATIONS = [
+      "openai-agents",
+      "langgraph",
+      "claude-agent-sdk",
+      "vercel-ai"
+    ];
+    FRAMEWORK_INSTRUMENTATION_SET = new Set(
+      FRAMEWORK_INSTRUMENTATIONS
+    );
+  }
+});
+
+// src/unrefTimer.ts
+function unrefTimer(timer) {
+  const handle = timer;
+  if (typeof handle.unref === "function") {
+    handle.unref();
+  }
+}
+var init_unrefTimer = __esm({
+  "src/unrefTimer.ts"() {
+    "use strict";
+  }
+});
+
+// src/simulationPlan.ts
+function planWaitSliceMs(timeoutMs) {
+  return Math.min(SIMULATION_PLAN_READ_TIMEOUT_MS, Math.max(timeoutMs, 0) / 2);
+}
+function parseSimulationPlan(body) {
+  if (typeof body !== "object" || body === null) {
+    return null;
+  }
+  const nodes = body.nodes;
+  if (!Array.isArray(nodes)) {
+    return null;
+  }
+  const contentOff = /* @__PURE__ */ new Map();
+  for (const node of nodes) {
+    if (typeof node !== "object" || node === null) {
+      continue;
+    }
+    const { traceFunctionKey, name, captureContent } = node;
+    if (typeof traceFunctionKey !== "string" || typeof name !== "string" || typeof captureContent !== "boolean") {
+      continue;
+    }
+    if (captureContent) {
+      continue;
+    }
+    const names = contentOff.get(traceFunctionKey) ?? /* @__PURE__ */ new Set();
+    names.add(name);
+    contentOff.set(traceFunctionKey, names);
+  }
+  return contentOff;
+}
+function traceIdOf(payload) {
+  const traceId = payload.traceId;
+  if (typeof traceId === "string") {
+    return traceId;
+  }
+  const id = payload.id;
+  return typeof id === "string" ? id : void 0;
+}
+function isRecord2(value) {
+  return typeof value === "object" && value !== null;
+}
+function rawSpanOf(payload) {
+  return isRecord2(payload.rawSpan) ? payload.rawSpan : void 0;
+}
+function spanDataOf(payload) {
+  const spanData = rawSpanOf(payload)?.span_data;
+  return isRecord2(spanData) ? spanData : void 0;
+}
+function spanNameOf(payload) {
+  const name = spanDataOf(payload)?.name;
+  return typeof name === "string" ? name : void 0;
+}
+function stripContent(payload) {
+  const rawSpan = rawSpanOf(payload);
+  const spanData = spanDataOf(payload);
+  if (rawSpan === void 0 || spanData === void 0) {
+    return payload;
+  }
+  const kept = { ...spanData };
+  for (const key of CONTENT_KEYS) {
+    delete kept[key];
+  }
+  kept[CONTENT_OFF_KEY] = true;
+  return { ...payload, rawSpan: { ...rawSpan, span_data: kept } };
+}
+function simulationPlanEnvDisabled() {
+  const value = readEnv(DISABLE_SIMULATION_PLAN_ENV);
+  return typeof value === "string" && value.trim() !== "";
+}
+function missingSimulationPlanEndpoint(error) {
+  return error instanceof BitfabError && error.status === 404;
+}
+var SIMULATION_PLAN_REFRESH_MS, SIMULATION_PLAN_RETRY_MS, SIMULATION_PLAN_READ_TIMEOUT_MS, SIMULATION_PLAN_MAX_HELD, DISABLE_SIMULATION_PLAN_ENV, ROOT_TRACE_FUNCTION_KEY_FIELD, CONTENT_OFF_KEY, CONTENT_KEYS, SimulationPlan;
+var init_simulationPlan = __esm({
+  "src/simulationPlan.ts"() {
+    "use strict";
+    init_errors();
+    init_policyRefresh();
+    init_readEnv();
+    init_spanOrigin();
+    init_unrefTimer();
+    init_warnOnce();
+    SIMULATION_PLAN_REFRESH_MS = 6e4;
+    SIMULATION_PLAN_RETRY_MS = 1e4;
+    SIMULATION_PLAN_READ_TIMEOUT_MS = 5e3;
+    SIMULATION_PLAN_MAX_HELD = 1e3;
+    DISABLE_SIMULATION_PLAN_ENV = "BITFAB_DISABLE_SIM_PLAN";
+    ROOT_TRACE_FUNCTION_KEY_FIELD = "rootTraceFunctionKey";
+    CONTENT_OFF_KEY = "content_off_by_simulation_plan";
+    CONTENT_KEYS = ["input", "input_meta", "output", "output_meta"];
+    SimulationPlan = class {
+      constructor(source, enabled = true) {
+        this.source = source;
+        this.enabled = enabled;
+        this.policyRefresh = new PolicyRefresh();
+        this.retryPending = false;
+        this.waitingForFirstLoad = 0;
+        this.held = [];
+        this.droppedWhileHolding = 0;
+        this.stopped = false;
+        this.loaded = new Promise((resolve) => {
+          this.resolveLoaded = resolve;
+        });
+      }
+      disabled() {
+        return !this.enabled || simulationPlanEnvDisabled();
+      }
+      refresh() {
+        if (this.stopped || this.disabled()) {
+          return;
+        }
+        this.policyRefresh.run(
+          () => this.source.getSimulationPlan(),
+          (body) => {
+            const parsed = parseSimulationPlan(body);
+            if (parsed === null) {
+              this.scheduleRetry(
+                "sim-plan-unreadable",
+                "the sim plan response was not understood"
+              );
+              return;
+            }
+            this.markLoaded(parsed);
+          },
+          (error) => {
+            if (missingSimulationPlanEndpoint(error)) {
+              this.markLoaded(/* @__PURE__ */ new Map());
+              return;
+            }
+            this.scheduleRetry(
+              "sim-plan-unavailable",
+              `could not read the sim plan: ${error instanceof Error ? error.message : String(error)}`
+            );
+          }
+        );
+      }
+      markLoaded(parsed) {
+        if (this.stopped) {
+          return;
+        }
+        this.contentOffByKey = parsed;
+        this.policyRefresh.hold(SIMULATION_PLAN_REFRESH_MS);
+        this.retryPending = false;
+        this.clearRetryTimer();
+        this.resolveLoaded?.();
+        this.resolveLoaded = void 0;
+        this.releaseHeld();
+      }
+      scheduleRetry(warnKey, reason) {
+        if (this.stopped) {
+          return;
+        }
+        this.policyRefresh.hold(SIMULATION_PLAN_RETRY_MS);
+        if (this.contentOffByKey !== void 0) {
+          return;
+        }
+        this.retryPending = true;
+        warnOnce(
+          warnKey,
+          `${reason}. Spans are held until the first read succeeds; while a record is held it is retried every ${SIMULATION_PLAN_RETRY_MS / 1e3}s, otherwise on the next span.`
+        );
+        this.armRetry();
+      }
+      holdsWork() {
+        return this.held.length > 0 || this.waitingForFirstLoad > 0;
+      }
+      armRetry() {
+        if (this.stopped || !this.retryPending || this.retryTimer !== void 0 || !this.holdsWork()) {
+          return;
+        }
+        const timer = setTimeout(() => {
+          this.retryTimer = void 0;
+          this.policyRefresh.releaseHold();
+          this.refresh();
+        }, SIMULATION_PLAN_RETRY_MS);
+        unrefTimer(timer);
+        this.retryTimer = timer;
+      }
+      clearRetryTimer() {
+        if (this.retryTimer !== void 0) {
+          clearTimeout(this.retryTimer);
+          this.retryTimer = void 0;
+        }
+      }
+      syncRetryTimer() {
+        if (this.holdsWork()) {
+          return;
+        }
+        this.clearRetryTimer();
+      }
+      firstLoad() {
+        if (this.contentOffByKey !== void 0 || this.stopped || this.disabled()) {
+          return void 0;
+        }
+        return this.loaded;
+      }
+      send(payload, traceFunctionKey, submit) {
+        this.refresh();
+        if (this.stopped || this.disabled() || traceFunctionKey === void 0 || spanNameOf(payload) === void 0 || recordedByFramework(payload)) {
+          submit(payload);
+          return;
+        }
+        if (this.contentOffByKey === void 0) {
+          this.hold({ payload, traceFunctionKey, submit });
+          return;
+        }
+        this.submitEntry({ payload, traceFunctionKey, submit });
+      }
+      sendTrace(payload, submit) {
+        this.refresh();
+        if (this.stopped || this.disabled() || this.contentOffByKey !== void 0 || !this.holdsSpanOfTrace(traceIdOf(payload))) {
+          submit(payload);
+          return;
+        }
+        this.hold({ payload, traceFunctionKey: void 0, submit });
+      }
+      holdsSpanOfTrace(traceId) {
+        if (traceId === void 0) {
+          return false;
+        }
+        return this.held.some(
+          (entry) => entry.traceFunctionKey !== void 0 && traceIdOf(entry.payload) === traceId
+        );
+      }
+      hold(entry) {
+        this.held.push(entry);
+        while (this.held.length > SIMULATION_PLAN_MAX_HELD) {
+          this.held.shift();
+          this.droppedWhileHolding += 1;
+        }
+        this.armRetry();
+      }
+      submitEntry(entry) {
+        try {
+          entry.submit(
+            entry.traceFunctionKey === void 0 ? entry.payload : this.apply(entry.payload, entry.traceFunctionKey)
+          );
+        } catch (error) {
+          warnOnce(
+            "sim-plan-held-span-dropped",
+            `a span held for the sim plan was dropped when released: ${error instanceof Error ? error.message : String(error)}`
+          );
+        }
+      }
+      releaseHeld() {
+        const held = this.held;
+        this.held = [];
+        this.syncRetryTimer();
+        this.warnDropped();
+        for (const entry of held) {
+          this.submitEntry(entry);
+        }
+      }
+      warnDropped() {
+        if (this.droppedWhileHolding === 0) {
+          return;
+        }
+        const dropped = this.droppedWhileHolding;
+        this.droppedWhileHolding = 0;
+        warnOnce(
+          "sim-plan-held-overflow",
+          `${dropped} record(s) were dropped while the sim plan was still loading; at most ${SIMULATION_PLAN_MAX_HELD} are held per client.`
+        );
+      }
+      warnNeverLoaded() {
+        if (this.held.length === 0) {
+          return;
+        }
+        warnOnce(
+          "sim-plan-never-loaded",
+          `${this.held.length} record(s) were not sent because the sim plan never loaded`
+        );
+      }
+      async release(timeoutMs) {
+        this.refresh();
+        if (this.holdsWork()) {
+          await this.waitForFirstLoad(timeoutMs);
+        }
+        this.warnNeverLoaded();
+        this.warnDropped();
+      }
+      waitForFirstLoad(timeoutMs) {
+        const firstLoad = this.firstLoad();
+        if (firstLoad === void 0) {
+          return Promise.resolve();
+        }
+        this.waitingForFirstLoad += 1;
+        this.armRetry();
+        return new Promise((resolve) => {
+          let settled2 = false;
+          const finish = () => {
+            if (settled2) {
+              return;
+            }
+            settled2 = true;
+            this.waitingForFirstLoad -= 1;
+            this.syncRetryTimer();
+            resolve();
+          };
+          const timer = setTimeout(finish, Math.max(timeoutMs, 0));
+          void firstLoad.then(() => {
+            clearTimeout(timer);
+            finish();
+          });
+        });
+      }
+      stop() {
+        if (this.stopped) {
+          return;
+        }
+        this.stopped = true;
+        this.retryPending = false;
+        this.clearRetryTimer();
+        this.warnNeverLoaded();
+        this.held = [];
+        this.warnDropped();
+      }
+      contentOff(traceFunctionKey, spanName) {
+        return this.contentOffByKey?.get(traceFunctionKey)?.has(spanName) === true;
+      }
+      apply(payload, traceFunctionKey) {
+        if (recordedByFramework(payload)) {
+          return payload;
+        }
+        const name = spanNameOf(payload);
+        if (name === void 0 || !this.contentOff(traceFunctionKey, name)) {
+          return payload;
+        }
+        return stripContent(payload);
+      }
+    };
+  }
+});
+
 // src/traceMetadata.ts
 function findRecord(traceId) {
   return activeRecords.get(traceId) ?? completedRecords.get(traceId);
@@ -653,19 +1103,6 @@ var init_transportTypes = __esm({
   }
 });
 
-// src/unrefTimer.ts
-function unrefTimer(timer) {
-  const handle = timer;
-  if (typeof handle.unref === "function") {
-    handle.unref();
-  }
-}
-var init_unrefTimer = __esm({
-  "src/unrefTimer.ts"() {
-    "use strict";
-  }
-});
-
 // src/otel.ts
 function readBoundedIntEnv(name, max, fallback, warnKey) {
   const raw = readEnv(name);
@@ -1316,6 +1753,17 @@ __export(http_exports, {
   parseRetryAfterMs: () => parseRetryAfterMs,
   serializePayloadBody: () => serializePayloadBody
 });
+async function releaseHeldExternalSpans(timeoutMs) {
+  const deadline = Date.now() + Math.max(timeoutMs, 0);
+  for (const client of [...liveHttpClients]) {
+    await client.releaseHeldExternalSpans?.(Math.max(0, deadline - Date.now()));
+  }
+}
+function stopSimulationPlans() {
+  for (const client of [...liveHttpClients]) {
+    client.stopSimulationPlan?.();
+  }
+}
 function awaitOnExit(promise) {
   pendingTracePromises.add(promise);
   void promise.finally(() => {
@@ -1326,7 +1774,10 @@ function awaitOnExit(promise) {
 }
 async function flushTraces(timeoutMs = 5e3) {
   const deadline = Date.now() + Math.max(timeoutMs, 0);
-  const requestsFlushed = await awaitPendingRequests(timeoutMs);
+  await releaseHeldExternalSpans(planWaitSliceMs(timeoutMs));
+  const requestsFlushed = await awaitPendingRequests(
+    Math.max(0, deadline - Date.now())
+  );
   const transportsFlushed = await flushTraceTransports(
     Math.max(0, deadline - Date.now())
   );
@@ -1445,7 +1896,22 @@ function sourceTraceIdOf(payload) {
   const id = rawTrace?.id;
   return typeof id === "string" ? id : void 0;
 }
-var REPLAY_DB_BRANCH_REQUEST_TIMEOUT_MS, REPLAY_COMPLETE_REQUEST_TIMEOUT_MS, OTLP_TRACES_ENDPOINT, RETRYABLE_STATUSES, EXIT_FLUSH_TIMEOUT_MS, DEFAULT_LIFECYCLE_TIMEOUT_MS2, pendingTracePromises, carrierSeq, HttpClient;
+function describeError(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function warnDroppedExternalSpan(error) {
+  warnOnce(
+    "external-span-dropped",
+    `a span was dropped because the send step failed: ${describeError(error)}`
+  );
+}
+function warnDroppedExternalTrace(error) {
+  warnOnce(
+    "external-trace-dropped",
+    `a trace was dropped because the send step failed: ${describeError(error)}`
+  );
+}
+var REPLAY_DB_BRANCH_REQUEST_TIMEOUT_MS, REPLAY_COMPLETE_REQUEST_TIMEOUT_MS, OTLP_TRACES_ENDPOINT, RETRYABLE_STATUSES, EXIT_FLUSH_TIMEOUT_MS, DEFAULT_LIFECYCLE_TIMEOUT_MS2, pendingTracePromises, liveHttpClients, carrierSeq, HttpClient;
 var init_http = __esm({
   "src/http.ts"() {
     "use strict";
@@ -1454,6 +1920,7 @@ var init_http = __esm({
     init_errors();
     init_replayContext();
     init_serializePayload();
+    init_simulationPlan();
     init_traceMetadata();
     init_transport();
     init_transportTypes();
@@ -1466,6 +1933,7 @@ var init_http = __esm({
     EXIT_FLUSH_TIMEOUT_MS = 5e3;
     DEFAULT_LIFECYCLE_TIMEOUT_MS2 = 3e4;
     pendingTracePromises = /* @__PURE__ */ new Set();
+    liveHttpClients = /* @__PURE__ */ new Set();
     if (typeof process !== "undefined" && process.versions != null && process.versions.node != null) {
       let isFlushing = false;
       process.on("beforeExit", () => {
@@ -1473,12 +1941,27 @@ var init_http = __esm({
           return;
         }
         isFlushing = true;
-        void Promise.allSettled([
-          ...Array.from(pendingTracePromises).map((p) => p.catch(() => {
-          })),
-          shutdownTraceTransports(EXIT_FLUSH_TIMEOUT_MS).catch(() => false)
-        ]).then(() => {
+        const planWaitMs = SIMULATION_PLAN_READ_TIMEOUT_MS;
+        const stopFlushing = () => {
           isFlushing = false;
+        };
+        const deadline = setTimeout(
+          stopFlushing,
+          EXIT_FLUSH_TIMEOUT_MS + planWaitMs
+        );
+        unrefTimer(deadline);
+        void releaseHeldExternalSpans(planWaitMs).catch(() => {
+        }).then(() => {
+          stopSimulationPlans();
+        }).then(
+          () => Promise.allSettled([
+            ...Array.from(pendingTracePromises).map((p) => p.catch(() => {
+            })),
+            shutdownTraceTransports(EXIT_FLUSH_TIMEOUT_MS).catch(() => false)
+          ])
+        ).then(() => {
+          clearTimeout(deadline);
+          stopFlushing();
         });
       });
     }
@@ -1497,6 +1980,7 @@ var init_http = __esm({
         this.apiKey = config.apiKey;
         this.serviceUrl = config.serviceUrl;
         this.timeout = config.timeout ?? 12e4;
+        liveHttpClients.add(this);
       }
       /**
        * Resolve the API key at the moment it is needed (request time), invoking
@@ -1694,9 +2178,14 @@ var init_http = __esm({
        * attributing its timeout here would fail a client whose own work succeeded.
        */
       async settleDeferredWork(timeoutMs = DEFAULT_LIFECYCLE_TIMEOUT_MS2) {
+        const deadline = Date.now() + Math.max(timeoutMs, 0);
+        await this.releaseHeldExternalSpans?.(planWaitSliceMs(timeoutMs));
         await replayContextReady.catch(() => {
         });
-        return waitForPromises(Array.from(this.deferredWork), timeoutMs);
+        return waitForPromises(
+          Array.from(this.deferredWork),
+          Math.max(0, deadline - Date.now())
+        );
       }
       /**
        * Wait for spans queued by this client to be delivered, within one deadline.
@@ -1704,7 +2193,9 @@ var init_http = __esm({
        */
       async waitForPendingRequests(timeoutMs = DEFAULT_LIFECYCLE_TIMEOUT_MS2) {
         const deadline = Date.now() + Math.max(timeoutMs, 0);
-        const settled2 = await this.settleDeferredWork(timeoutMs);
+        const settled2 = await this.settleDeferredWork(
+          Math.max(0, deadline - Date.now())
+        );
         const flushed = await this.traceTransport?.flush(Math.max(0, deadline - Date.now())) ?? true;
         return settled2 && flushed;
       }
@@ -1719,6 +2210,13 @@ var init_http = __esm({
         }
         const deadline = Date.now() + Math.max(timeoutMs, 0);
         this.closing = (async () => {
+          await this.releaseHeldExternalSpans?.(planWaitSliceMs(timeoutMs));
+          this.stopSimulationPlan?.();
+          this.externalSpanTransform = void 0;
+          this.externalTraceTransform = void 0;
+          this.releaseHeldExternalSpans = void 0;
+          this.stopSimulationPlan = void 0;
+          liveHttpClients.delete(this);
           const settled2 = await this.settleDeferredWork(
             Math.max(0, deadline - Date.now())
           );
@@ -1830,6 +2328,13 @@ var init_http = __esm({
           protocol
         });
       }
+      async getSimulationPlan() {
+        return this.get(
+          "/api/sdk/sim-plan",
+          SIMULATION_PLAN_READ_TIMEOUT_MS,
+          { Connection: "close" }
+        );
+      }
       async getTraceSpan(traceId, lookup) {
         const searchParams = new URLSearchParams();
         if (lookup.id !== void 0) {
@@ -1846,14 +2351,18 @@ var init_http = __esm({
        * GET a JSON endpoint on the service with the client's API key. Throws a
        * `BitfabError` carrying the status text for any non-2xx response.
        */
-      async get(endpoint) {
+      async get(endpoint, timeoutMs, extraHeaders) {
         const url = `${this.serviceUrl}${endpoint}`;
+        const timeout = timeoutMs ?? this.timeout;
         const controller = new AbortController();
-        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        const timeoutId = setTimeout(() => controller.abort(), timeout);
         try {
           const response = await fetch(url, {
             method: "GET",
-            headers: { Authorization: `Bearer ${this.resolveApiKey() ?? ""}` },
+            headers: {
+              Authorization: `Bearer ${this.resolveApiKey() ?? ""}`,
+              ...extraHeaders
+            },
             signal: controller.signal
           });
           if (!response.ok) {
@@ -1872,7 +2381,7 @@ var init_http = __esm({
           }
           if (error instanceof Error) {
             if (error.name === "AbortError") {
-              throw new BitfabError(`Request timed out after ${this.timeout}ms`);
+              throw new BitfabError(`Request timed out after ${timeout}ms`);
             }
             throw new BitfabError(error.message);
           }
@@ -1899,16 +2408,27 @@ var init_http = __esm({
           carrierMeta("internal_trace", body, void 0)
         );
       }
-      /**
-       * Queue an external span (from withSpan wrapper or OpenAI tracing) onto this
-       * client's batching transport. Fire-and-forget: the transport owns delivery,
-       * so callers await `flushTraces()` or `close()` rather than a per-span
-       * promise.
-       */
       sendExternalSpan(payload) {
+        const gate = this.externalSpanTransform;
+        if (gate === void 0) {
+          this.submitExternalSpan(payload);
+          return;
+        }
+        try {
+          gate(payload, (ready) => this.submitExternalSpan(ready));
+        } catch (error) {
+          warnDroppedExternalSpan(error);
+        }
+      }
+      submitExternalSpan(payload) {
+        const body = {
+          ...payload,
+          sdkVersion: __version__
+        };
+        delete body[ROOT_TRACE_FUNCTION_KEY_FIELD];
         this.getTraceTransport()?.submit(
           "external_span",
-          { ...payload, sdkVersion: __version__ },
+          body,
           this.recordedMeta("external_span", payload, carrierRef(payload))
         );
       }
@@ -1920,6 +2440,18 @@ var init_http = __esm({
        */
       sendExternalTrace(rawPayload) {
         const payload = mergeCallerMetadataIntoTracePayload(rawPayload);
+        const gate = this.externalTraceTransform;
+        if (gate === void 0) {
+          this.submitExternalTrace(payload);
+          return;
+        }
+        try {
+          gate(payload, (ready) => this.submitExternalTrace(ready));
+        } catch (error) {
+          warnDroppedExternalTrace(error);
+        }
+      }
+      submitExternalTrace(payload) {
         this.getTraceTransport()?.submit(
           "external_trace",
           {
@@ -3633,6 +4165,7 @@ function finalizeTracePayload(payload) {
 // src/claudeAgentSdk.ts
 init_randomUuid();
 init_serialize();
+init_spanOrigin();
 
 // src/timestamp.ts
 var lastTimestampMicros = 0;
@@ -3840,6 +4373,7 @@ var BitfabClaudeAgentHandler = class {
       trace_id: spanInfo.traceId,
       started_at: spanInfo.startedAt,
       ended_at: spanInfo.endedAt ?? nowIso(),
+      span_origin: makeSpanOrigin("claude-agent-sdk"),
       span_data: spanData
     };
     if (spanInfo.parentId !== null) {
@@ -5151,6 +5685,7 @@ init_constants();
 init_http();
 init_randomUuid();
 init_serialize();
+init_spanOrigin();
 var LANGSMITH_HIDDEN_TAG = "langsmith:hidden";
 var CHAIN_RUN_TYPES = /* @__PURE__ */ new Set(["chain", "parser", "prompt"]);
 var LANGGRAPH_METADATA_KEYS = [
@@ -5505,6 +6040,7 @@ var BitfabLangGraphCallbackHandler = class {
       trace_id: spanInfo.traceId,
       started_at: spanInfo.startedAt,
       ended_at: spanInfo.endedAt ?? nowIso2(),
+      span_origin: makeSpanOrigin("langgraph"),
       span_data: spanData
     };
     if (spanInfo.parentId !== null) {
@@ -5766,14 +6302,14 @@ var BitfabLangGraphCallbackHandler = class {
 init_http();
 init_replayContext();
 var TOOL_RESULT_TAG = "__bitfabLangGraphToolResult";
-function isRecord(value) {
+function isRecord3(value) {
   return typeof value === "object" && value !== null;
 }
 function isToolMessage(value) {
-  return isRecord(value) && value.lc_direct_tool_output === true && value.type === "tool" && (typeof value.content === "string" || Array.isArray(value.content));
+  return isRecord3(value) && value.lc_direct_tool_output === true && value.type === "tool" && (typeof value.content === "string" || Array.isArray(value.content));
 }
 function isCommand(value) {
-  return isRecord(value) && value.lg_name === "Command";
+  return isRecord3(value) && value.lg_name === "Command";
 }
 function encodeNested(value) {
   if (isToolMessage(value) || isCommand(value)) {
@@ -5782,7 +6318,7 @@ function encodeNested(value) {
   if (Array.isArray(value)) {
     return value.map(encodeNested);
   }
-  if (isRecord(value)) {
+  if (isRecord3(value)) {
     return Object.fromEntries(
       Object.entries(value).map(([key, entry]) => [key, encodeNested(entry)])
     );
@@ -5805,17 +6341,17 @@ function encodeNativeToolResult(value) {
   }
   return {
     [TOOL_RESULT_TAG]: "command",
-    graph: isRecord(value) && typeof value.graph === "string" ? value.graph : void 0,
-    update: isRecord(value) ? encodeNested(value.update) : void 0,
-    resume: isRecord(value) ? encodeNested(value.resume) : void 0,
-    goto: isRecord(value) ? encodeNested(value.goto) : void 0
+    graph: isRecord3(value) && typeof value.graph === "string" ? value.graph : void 0,
+    update: isRecord3(value) ? encodeNested(value.update) : void 0,
+    resume: isRecord3(value) ? encodeNested(value.resume) : void 0,
+    goto: isRecord3(value) ? encodeNested(value.goto) : void 0
   };
 }
 function finalizeToolResult(value) {
   return isToolMessage(value) || isCommand(value) ? encodeNativeToolResult(value) : value;
 }
 function isEncodedToolResult(value) {
-  return isRecord(value) && typeof value[TOOL_RESULT_TAG] === "string";
+  return isRecord3(value) && typeof value[TOOL_RESULT_TAG] === "string";
 }
 async function loadLangChainCore() {
   try {
@@ -5851,7 +6387,7 @@ async function reviveNested(value, toolCallId) {
   if (Array.isArray(value)) {
     return Promise.all(value.map((entry) => reviveNested(entry, toolCallId)));
   }
-  if (isRecord(value)) {
+  if (isRecord3(value)) {
     const entries = await Promise.all(
       Object.entries(value).map(async ([key, entry]) => [
         key,
@@ -5876,16 +6412,16 @@ async function reviveToolResult(value, toolCallId) {
       ...value.artifact !== void 0 && {
         artifact: await reviveNested(value.artifact, toolCallId)
       },
-      ...isRecord(value.metadata) && {
+      ...isRecord3(value.metadata) && {
         metadata: await reviveNested(value.metadata, toolCallId)
       },
-      ...isRecord(value.additionalKwargs) && {
+      ...isRecord3(value.additionalKwargs) && {
         additional_kwargs: await reviveNested(
           value.additionalKwargs,
           toolCallId
         )
       },
-      ...isRecord(value.responseMetadata) && {
+      ...isRecord3(value.responseMetadata) && {
         response_metadata: await reviveNested(
           value.responseMetadata,
           toolCallId
@@ -5955,8 +6491,8 @@ var BitfabLangGraphIntegration = class {
       get: (target, property) => {
         if (property === "invoke") {
           return async (input, ...rest) => {
-            const toolCallId = isRecord(input) && typeof input.id === "string" ? input.id : "";
-            const args = isRecord(input) && "args" in input ? input.args : input;
+            const toolCallId = isRecord3(input) && typeof input.id === "string" ? input.id : "";
+            const args = isRecord3(input) && "args" in input ? input.args : input;
             this.assertReplayToolResultExists(toolName, shouldMock);
             const execute = this.client.withSpan(
               this.traceFunctionKey,
@@ -5966,7 +6502,8 @@ var BitfabLangGraphIntegration = class {
                 captureWhen: "nested",
                 mockOnReplay: shouldMock,
                 finalize: finalizeToolResult,
-                surface: "inherit"
+                surface: "inherit",
+                instrumentation: "langgraph"
               },
               async (_args) => await originalInvoke(input, ...rest)
             );
@@ -6009,7 +6546,12 @@ var BitfabLangGraphIntegration = class {
   wrapInvoke(fn) {
     return this.client.withSpan(
       this.traceFunctionKey,
-      { name: this.traceFunctionKey, type: "agent", surface: "inherit" },
+      {
+        name: this.traceFunctionKey,
+        type: "agent",
+        surface: "inherit",
+        instrumentation: "langgraph"
+      },
       fn
     );
   }
@@ -6065,7 +6607,8 @@ var BitfabOpenAIAgentHandler = class {
     const options_ = {
       type: "agent",
       finalize,
-      surface: "inherit"
+      surface: "inherit",
+      instrumentation: "openai-agents"
     };
     const traced = this.withSpanFn(
       this.traceFunctionKey,
@@ -6081,6 +6624,7 @@ var BitfabOpenAIAgentHandler = class {
 };
 
 // src/client.ts
+init_policyRefresh();
 init_randomUuid();
 init_replay();
 
@@ -6164,12 +6708,15 @@ function runWithSeedContext(ctx, fn) {
 
 // src/client.ts
 init_serialize();
+init_simulationPlan();
+init_spanOrigin();
 init_traceMetadata();
 
 // src/tracing.ts
 init_constants();
 init_http();
 init_randomUuid();
+init_spanOrigin();
 var BitfabOpenAITracingProcessor = class {
   /**
    * Initialize the tracing processor.
@@ -6371,6 +6918,7 @@ var BitfabOpenAITracingProcessor = class {
    * Build span payload for the external spans API.
    */
   buildSpanPayload(serializedSpan, errors) {
+    serializedSpan.span_origin = makeSpanOrigin("openai-agents");
     const payload = {
       id: randomUuid(),
       type: "openai",
@@ -6500,7 +7048,8 @@ var BitfabVercelAiHandler = class {
           {
             type: "llm",
             finalize: (result) => summarizeGenerate(result ?? {}, label),
-            surface: "inherit"
+            surface: "inherit",
+            instrumentation: "vercel-ai"
           },
           () => doGenerate()
         );
@@ -6518,7 +7067,12 @@ var BitfabVercelAiHandler = class {
           // The wrapped fn returns immediately with the live stream, so the span
           // output cannot be read from the return value. `finalize` instead
           // awaits the summary the accumulator resolves once the stream drains.
-          { type: "llm", finalize: () => summary, surface: "inherit" },
+          {
+            type: "llm",
+            finalize: () => summary,
+            surface: "inherit",
+            instrumentation: "vercel-ai"
+          },
           async () => {
             const result = await doStream();
             const stream = result.stream.pipeThrough(
@@ -6536,6 +7090,19 @@ var BitfabVercelAiHandler = class {
 // src/client.ts
 init_warnOnce();
 var activeTraceStates = /* @__PURE__ */ new Map();
+function rootTraceFunctionKeyOf(payload) {
+  const captured = payload[ROOT_TRACE_FUNCTION_KEY_FIELD];
+  if (typeof captured === "string") {
+    return captured;
+  }
+  const traceId = payload.traceId;
+  const live = typeof traceId === "string" ? activeTraceStates.get(traceId)?.traceFunctionKey : void 0;
+  if (typeof live === "string") {
+    return live;
+  }
+  const own = payload.traceFunctionKey;
+  return typeof own === "string" ? own : void 0;
+}
 var asyncLocalStorage = null;
 var SPAN_CONTEXT_STORAGE_SYMBOL = /* @__PURE__ */ Symbol.for("bitfab.spanContextStorage");
 var initializeAsyncContext = () => {
@@ -6878,6 +7445,26 @@ var DEFAULT_AUTO_TRACE_MAX_SPANS = 500;
 var AUTO_TRACE_PROTOCOL = "ts-auto-v1";
 var AUTO_TRACE_POLICY_REFRESH_MS = 6e4;
 var AUTO_TRACE_POLICY_RETRY_MS = 1e4;
+function spanOwnerName(receiver) {
+  if (typeof receiver === "function") {
+    return receiver.name !== "" ? receiver.name : void 0;
+  }
+  if (typeof receiver !== "object" || receiver === null) {
+    return void 0;
+  }
+  const owner = receiver.constructor;
+  if (typeof owner !== "function" || owner === Object || owner.name === "") {
+    return void 0;
+  }
+  return owner.name;
+}
+function qualifiedSpanName(receiver, functionName) {
+  if (functionName === void 0) {
+    return void 0;
+  }
+  const owner = spanOwnerName(receiver);
+  return owner === void 0 ? functionName : `${owner}.${functionName}`;
+}
 function autoTraceLimit(value, fallback) {
   return value !== void 0 && Number.isFinite(value) && value >= 0 ? Math.floor(value) : fallback;
 }
@@ -6920,6 +7507,14 @@ var Bitfab = class {
       serviceUrl: this.serviceUrl,
       timeout: this.timeout
     });
+    this.simulationPlan = new SimulationPlan(
+      this.httpClient,
+      config.simulationPlan ?? true
+    );
+    this.httpClient.externalSpanTransform = (payload, submit) => this.applySimulationPlan(payload, submit);
+    this.httpClient.externalTraceTransform = (payload, submit) => this.simulationPlan.sendTrace(payload, submit);
+    this.httpClient.releaseHeldExternalSpans = (timeoutMs) => this.simulationPlan.release(timeoutMs);
+    this.httpClient.stopSimulationPlan = () => this.simulationPlan.stop();
     this.datasets = new DatasetsClient(this.httpClient);
     this.traces = new TracesClient(this.httpClient);
     this.labels = new LabelsClient(this.httpClient);
@@ -7070,6 +7665,7 @@ var Bitfab = class {
   }
   createAutoTraceRoot(traceFunctionKey, name, options, fn) {
     const self = this;
+    self.simulationPlan.refresh();
     const maxDepth = autoTraceLimit(
       options.maxDepth,
       DEFAULT_AUTO_TRACE_MAX_DEPTH
@@ -7080,12 +7676,14 @@ var Bitfab = class {
     );
     const excluded = new Set(options.exclude ?? []);
     const includeWrappers = options.includeWrappers ?? false;
+    const rootNameFor = (receiver) => options.name ?? (fn.name !== "" ? qualifiedSpanName(receiver, name) ?? name : name);
     const rootOptions = {
-      name: options.name ?? name,
+      name: options.name,
+      nameFor: rootNameFor,
       type: options.type ?? "custom",
-      surface: "opt-out"
+      surface: "opt-out",
+      instrumentation: "trace"
     };
-    const rootName = options.name ?? name;
     const buildTracedRoot = (spanOptions) => this.withSpan(
       traceFunctionKey,
       spanOptions,
@@ -7095,6 +7693,7 @@ var Bitfab = class {
           traceFunctionKey
         );
         self.refreshAutoTraceCapturePolicy(traceFunctionKey);
+        self.simulationPlan.refresh();
         let spansUsed = 0;
         let truncated = false;
         const warnTruncated = () => {
@@ -7171,6 +7770,7 @@ var Bitfab = class {
               type: nodeConfiguration?.type ?? "function",
               captureWhen: "nested",
               surface: "opt-out",
+              instrumentation: "trace",
               functionId: definition.id,
               captureContent: nodeConfiguration !== void 0 || capturePolicy === void 0 || capturePolicy.has(definition.id),
               autoTraceDefinition: definition,
@@ -7202,6 +7802,7 @@ var Bitfab = class {
               type: "function",
               captureWhen: "nested",
               surface: "opt-out",
+              instrumentation: "trace",
               captureContent: true,
               ...link !== void 0 && { nestedTrace: link }
             };
@@ -7225,6 +7826,7 @@ var Bitfab = class {
         return tracedRoot.apply(this, args);
       }
       const link = getReplayContext() || inSeedScope() ? void 0 : { traceFunctionKey };
+      const rootName = rootNameFor(this);
       return invokeThroughAutoTraceEntries(
         enclosing,
         (entry, next) => entry.context.invokeNestedRoot(
@@ -7266,38 +7868,36 @@ var Bitfab = class {
     Object.defineProperty(autoTraceRoot, "_bitfabWrappedFn", { value: fn });
     return autoTraceRoot;
   }
+  applySimulationPlan(payload, submit) {
+    this.simulationPlan.send(payload, rootTraceFunctionKeyOf(payload), submit);
+  }
   refreshAutoTraceCapturePolicy(traceFunctionKey) {
-    const now = Date.now();
-    const state = this.autoTracePolicyRefreshes.get(traceFunctionKey) ?? {
-      refreshAfter: 0
-    };
-    if (state.inFlight || now < state.refreshAfter) {
-      return;
-    }
-    const request = this.httpClient.getAutoTracePolicy(
-      traceFunctionKey,
-      AUTO_TRACE_PROTOCOL
-    ).then((policy) => {
-      if (policy.protocol !== AUTO_TRACE_PROTOCOL) {
-        state.refreshAfter = Date.now() + AUTO_TRACE_POLICY_RETRY_MS;
-        return;
-      }
-      const functionIds = Array.isArray(policy.functionIds) ? policy.functionIds.filter(
-        (id) => typeof id === "string" && id.startsWith(`${AUTO_TRACE_PROTOCOL}:`)
-      ).slice(0, DEFAULT_AUTO_TRACE_MAX_SPANS) : [];
-      __setBitfabAutoTraceCapturePolicy(
-        this,
-        traceFunctionKey,
-        policy.revision === null ? void 0 : functionIds
-      );
-      state.refreshAfter = Date.now() + AUTO_TRACE_POLICY_REFRESH_MS;
-    }).catch(() => {
-      state.refreshAfter = Date.now() + AUTO_TRACE_POLICY_RETRY_MS;
-    }).finally(() => {
-      state.inFlight = void 0;
-    });
-    state.inFlight = request;
+    const state = this.autoTracePolicyRefreshes.get(traceFunctionKey) ?? new PolicyRefresh();
     this.autoTracePolicyRefreshes.set(traceFunctionKey, state);
+    state.run(
+      () => this.httpClient.getAutoTracePolicy(
+        traceFunctionKey,
+        AUTO_TRACE_PROTOCOL
+      ),
+      (policy) => {
+        if (policy.protocol !== AUTO_TRACE_PROTOCOL) {
+          state.hold(AUTO_TRACE_POLICY_RETRY_MS);
+          return;
+        }
+        const functionIds = Array.isArray(policy.functionIds) ? policy.functionIds.filter(
+          (id) => typeof id === "string" && id.startsWith(`${AUTO_TRACE_PROTOCOL}:`)
+        ).slice(0, DEFAULT_AUTO_TRACE_MAX_SPANS) : [];
+        __setBitfabAutoTraceCapturePolicy(
+          this,
+          traceFunctionKey,
+          policy.revision === null ? void 0 : functionIds
+        );
+        state.hold(AUTO_TRACE_POLICY_REFRESH_MS);
+      },
+      () => {
+        state.hold(AUTO_TRACE_POLICY_RETRY_MS);
+      }
+    );
   }
   /**
    * Flush and permanently close this client's tracing resources: its pending
@@ -7781,6 +8381,7 @@ var Bitfab = class {
    * @returns A wrapped function with the same signature that creates spans for inputs and outputs
    */
   withSpan(traceFunctionKey, optionsOrFn, maybeFn) {
+    this.simulationPlan.refresh();
     const options = typeof optionsOrFn === "function" ? {} : optionsOrFn;
     const fn = typeof optionsOrFn === "function" ? optionsOrFn : maybeFn;
     const self = this;
@@ -7872,8 +8473,10 @@ var Bitfab = class {
         const testRunId = replayCtxAtStart?.testRunId ?? options.testRunId;
         if (isRootSpan && !activeTraceStates.has(traceId)) {
           const dbSnapshotRef = buildSnapshotRef(self.dbSnapshot, startedAt);
+          self.simulationPlan.refresh();
           activeTraceStates.set(traceId, {
             traceId,
+            traceFunctionKey,
             startedAt,
             contexts: [],
             ...testRunId !== void 0 && { testRunId },
@@ -7888,16 +8491,19 @@ var Bitfab = class {
           registeredTraceId = traceId;
         }
         const functionName = fn.name !== "" ? fn.name : void 0;
+        const rootTraceFunctionKey = activeTraceStates.get(traceId)?.traceFunctionKey ?? traceFunctionKey;
         const baseSpanParams = {
           traceFunctionKey,
+          rootTraceFunctionKey,
           functionName,
-          spanName: options.name ?? functionName ?? traceFunctionKey,
+          spanName: options.name ?? options.nameFor?.(this) ?? qualifiedSpanName(this, functionName) ?? traceFunctionKey,
           traceId,
           spanId,
           parentSpanId,
           inputs,
           startedAt,
           spanType: options.type ?? "custom",
+          instrumentation: options.instrumentation ?? "span",
           functionId: options.functionId,
           captureContent: options.captureContent ?? true,
           autoTraceDefinition: options.autoTraceDefinition,
@@ -8313,6 +8919,7 @@ var Bitfab = class {
    * @returns A BitfabFunction instance for wrapping functions
    */
   getFunction(traceFunctionKey) {
+    this.simulationPlan.refresh();
     return new BitfabFunction(this, traceFunctionKey);
   }
   /**
@@ -8400,6 +9007,7 @@ var Bitfab = class {
       trace_id: params.traceId,
       started_at: params.startedAt,
       ended_at: params.endedAt,
+      span_origin: makeSpanOrigin(params.instrumentation),
       span_data: {
         name: params.spanName,
         type: params.spanType,
@@ -8460,6 +9068,9 @@ var Bitfab = class {
       source: "typescript-sdk-function",
       sourceTraceId: params.traceId,
       traceFunctionKey: params.traceFunctionKey,
+      ...params.rootTraceFunctionKey !== void 0 && {
+        [ROOT_TRACE_FUNCTION_KEY_FIELD]: params.rootTraceFunctionKey
+      },
       rawSpan: externalSpan,
       ...params.testRunId && { testRunId: params.testRunId },
       ...params.mocked && { mocked: true },
@@ -8528,6 +9139,7 @@ var Bitfab = class {
     }
     activeTraceStates.set(traceId, {
       traceId,
+      traceFunctionKey,
       startedAt,
       contexts: [],
       ingestionType: "seeded",
@@ -8537,6 +9149,7 @@ var Bitfab = class {
     try {
       this.sendWrapperSpan({
         traceFunctionKey,
+        rootTraceFunctionKey: traceFunctionKey,
         spanName: options.spanName ?? traceFunctionKey,
         traceId,
         spanId: randomUuid(),
@@ -8546,6 +9159,7 @@ var Bitfab = class {
         startedAt,
         endedAt: startedAt,
         spanType: options.spanType ?? "agent",
+        instrumentation: "span",
         captureContent: true
       });
       this.sendTraceCompletion({
@@ -8591,6 +9205,7 @@ var Bitfab = class {
     }
     activeTraceStates.set(traceId, {
       traceId,
+      traceFunctionKey,
       startedAt: nowIsoTimestamp(),
       contexts: [],
       ingestionType: "seeded",