raindrop-ai 0.2.1 → 0.2.2-otelv2

package/dist/index.js

@@ -5771,7 +5771,13 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
-// ../core/dist/chunk-Y5LUB7OE.js
+// src/lib/inject-als.ts
+var import_node_async_hooks = require("async_hooks");
+if (!globalThis.RAINDROP_ASYNC_LOCAL_STORAGE) {
+  globalThis.RAINDROP_ASYNC_LOCAL_STORAGE = import_node_async_hooks.AsyncLocalStorage;
+}
+
+// ../core/dist/chunk-ITAZONWL.js
 function normalizeFeatureFlags(input) {
   if (Array.isArray(input)) {
     return Object.fromEntries(input.map((name) => [name, "true"]));
@@ -6166,6 +6172,171 @@ var DEFAULT_REDACT_ATTRIBUTE_KEYS = [
   "ai.response.providerMetadata"
 ];
 var REDACT_JSON_ATTRIBUTE_KEYS = new Set(DEFAULT_REDACT_ATTRIBUTE_KEYS);
+function getAsyncLocalStorageCtor() {
+  return globalThis.RAINDROP_ASYNC_LOCAL_STORAGE;
+}
+function getWeakRefCtor() {
+  const ctor = globalThis.WeakRef;
+  return typeof ctor === "function" ? ctor : void 0;
+}
+var MAX_BINDING_STACK = 128;
+var EMPTY_STACK = [];
+var RoutingContextStorage = class {
+  constructor() {
+    this._als = null;
+    this._enterWithUsable = false;
+    this._syncStack = EMPTY_STACK;
+    this._adoptionChecked = false;
+    this._warnedNoAmbientBind = false;
+  }
+  maybeAdoptAsyncLocalStorage() {
+    if (this._adoptionChecked) return;
+    this._adoptionChecked = true;
+    const Ctor = getAsyncLocalStorageCtor();
+    if (!Ctor) return;
+    const als = new Ctor();
+    try {
+      als.run(EMPTY_STACK, () => {
+      });
+    } catch (e) {
+      return;
+    }
+    this._als = als;
+    if (typeof als.enterWith === "function") {
+      try {
+        als.enterWith(EMPTY_STACK);
+        this._enterWithUsable = true;
+      } catch (e) {
+        this._enterWithUsable = false;
+      }
+    }
+  }
+  getStack() {
+    var _a;
+    this.maybeAdoptAsyncLocalStorage();
+    if (this._als) return (_a = this._als.getStore()) != null ? _a : this._syncStack;
+    return this._syncStack;
+  }
+  /**
+   * Persist an ambient stack mutation. Returns false when an ALS is adopted but
+   * `enterWith` is unusable (workerd): callers must NOT fall back to the
+   * process-shared sync stack, since concurrent isolates would cross-stamp.
+   */
+  setAmbientStack(stack) {
+    if (this._als) {
+      if (!this._enterWithUsable) return false;
+      this._als.enterWith(stack);
+      return true;
+    }
+    this._syncStack = stack;
+    return true;
+  }
+  push(binding) {
+    this.maybeAdoptAsyncLocalStorage();
+    if (this._als && !this._enterWithUsable) {
+      this.warnNoAmbientBindOnce();
+      return;
+    }
+    let stack = this.getStack();
+    if (stack.length >= MAX_BINDING_STACK) {
+      stack = stack.filter((b) => b.isLive());
+      if (stack.length >= MAX_BINDING_STACK) {
+        stack = stack.slice(stack.length - (MAX_BINDING_STACK - 1));
+      }
+    }
+    this.setAmbientStack([...stack, binding]);
+  }
+  remove(binding) {
+    binding.markDead();
+    const stack = this.getStack();
+    const pruned = stack.filter((b) => b !== binding && b.isLive());
+    if (pruned.length !== stack.length) {
+      this.setAmbientStack(pruned);
+    }
+  }
+  runWith(binding, callback) {
+    this.maybeAdoptAsyncLocalStorage();
+    if (this._als) {
+      return this._als.run([...this.getStack(), binding], callback);
+    }
+    const previous = this._syncStack;
+    this._syncStack = [...previous, binding];
+    try {
+      return callback();
+    } finally {
+      this._syncStack = previous;
+    }
+  }
+  current() {
+    const stack = this.getStack();
+    if (stack.length === 0) return void 0;
+    const top = stack[stack.length - 1];
+    if (top.isLive()) return top;
+    const pruned = stack.filter((b) => b.isLive());
+    this.setAmbientStack(pruned);
+    return pruned.length > 0 ? pruned[pruned.length - 1] : void 0;
+  }
+  warnNoAmbientBindOnce() {
+    if (this._warnedNoAmbientBind) return;
+    this._warnedNoAmbientBind = true;
+    console.warn(
+      "[raindrop] This runtime's AsyncLocalStorage does not implement enterWith (e.g. Cloudflare Workers), so begin()/finish() cannot scope auto-instrumented spans to a project without cross-contaminating concurrent requests. Manual events and explicit span routing are unaffected; use asCurrent()/withSpan (run-based) to route auto-instrumented spans on this runtime."
+    );
+  }
+};
+var ROUTING_STORAGE_KEY = /* @__PURE__ */ Symbol.for("raindrop.tracing.routingContextStorage");
+function routingStorage() {
+  const holder = globalThis;
+  let storage = holder[ROUTING_STORAGE_KEY];
+  if (!storage) {
+    storage = new RoutingContextStorage();
+    holder[ROUTING_STORAGE_KEY] = storage;
+  }
+  return storage;
+}
+function makeBoundContext(binding, owner) {
+  const WeakRefCtor = owner !== void 0 ? getWeakRefCtor() : void 0;
+  const ref = WeakRefCtor && owner !== void 0 ? new WeakRefCtor(owner) : void 0;
+  let dead = false;
+  return {
+    projectId: binding.projectId,
+    authHint: binding.authHint,
+    isLive() {
+      if (dead) return false;
+      return ref === void 0 || ref.deref() !== void 0;
+    },
+    markDead() {
+      dead = true;
+    }
+  };
+}
+function bindRoutingContext(binding, owner) {
+  const bound = makeBoundContext(binding, owner);
+  try {
+    routingStorage().push(bound);
+  } catch (e) {
+  }
+  return bound;
+}
+function unbindRoutingContext(bound) {
+  if (!bound || !isBoundContext(bound)) return;
+  try {
+    routingStorage().remove(bound);
+  } catch (e) {
+  }
+}
+function withRoutingContext(binding, callback) {
+  const bound = makeBoundContext(binding);
+  return routingStorage().runWith(bound, callback);
+}
+function currentRoutingBinding() {
+  const bound = routingStorage().current();
+  if (!bound) return void 0;
+  return { projectId: bound.projectId, authHint: bound.authHint };
+}
+function isBoundContext(value) {
+  return typeof value.isLive === "function";
+}
 
 // ../core/dist/index.node.js
 var import_async_hooks = require("async_hooks");
@@ -10305,7 +10476,7 @@ var SignalEventSchema = external_exports.object({
 // package.json
 var package_default = {
   name: "raindrop-ai",
-  version: "0.2.1",
+  version: "0.2.2",
   main: "dist/index.js",
   module: "dist/index.mjs",
   types: "dist/index.d.ts",
@@ -10371,6 +10542,7 @@ var package_default = {
   dependencies: {
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/exporter-trace-otlp-http": "^0.57.2",
+    "@opentelemetry/exporter-trace-otlp-proto": "^0.57.2",
     "@traceloop/node-server-sdk": "0.19.0-otel-v1",
     weakref: "^0.2.1",
     zod: "^3.23.8"
@@ -10402,6 +10574,7 @@ var package_default = {
       "@traceloop/instrumentation-together",
       "@opentelemetry/instrumentation",
       "@opentelemetry/exporter-trace-otlp-http",
+      "@opentelemetry/exporter-trace-otlp-proto",
       "@opentelemetry/sdk-trace-base"
     ],
     noExternal: [
@@ -10517,7 +10690,7 @@ var import_instrumentation_pinecone = require("@traceloop/instrumentation-pineco
 var import_instrumentation_qdrant = require("@traceloop/instrumentation-qdrant");
 var import_instrumentation_together = require("@traceloop/instrumentation-together");
 var import_instrumentation_vertexai = require("@traceloop/instrumentation-vertexai");
-var traceloop3 = __toESM(require("@traceloop/node-server-sdk"));
+var traceloop4 = __toESM(require("@traceloop/node-server-sdk"));
 var import_weakref = require("weakref");
 
 // src/tracing/direct/http.ts
@@ -10741,6 +10914,190 @@ function getActiveTraceContext() {
   };
 }
 
+// src/tracing/multi-project.ts
+var import_node_crypto = require("crypto");
+var import_exporter_trace_otlp_proto = require("@opentelemetry/exporter-trace-otlp-proto");
+var PROJECT_ID_SPAN_ATTRIBUTE = "raindrop.project_id";
+var AUTH_HINT_SPAN_ATTRIBUTE = "raindrop.auth_hint";
+var EXPORT_SUCCESS = 0;
+var EXPORT_FAILED = 1;
+function authHintForKey(writeKey) {
+  if (!writeKey) return void 0;
+  return (0, import_node_crypto.createHash)("sha256").update(writeKey, "utf8").digest("hex").slice(0, 8);
+}
+var STATE_KEY = /* @__PURE__ */ Symbol.for("raindrop.tracing.multiProjectState");
+function getState() {
+  const holder = globalThis;
+  let state = holder[STATE_KEY];
+  if (!state) {
+    state = {
+      foreignClientSeen: false,
+      seenClientHints: /* @__PURE__ */ new Set(),
+      ownerAuthHint: void 0,
+      ownerProjectId: void 0,
+      pipelineClaimed: false,
+      traceloopConfiguredWithoutClaim: false,
+      multiKeyWarned: false,
+      pendingMultiKeyWarning: false
+    };
+    holder[STATE_KEY] = state;
+  }
+  return state;
+}
+function emitMultiKeyWarningOnce() {
+  const state = getState();
+  if (state.multiKeyWarned) return;
+  state.multiKeyWarned = true;
+  state.pendingMultiKeyWarning = false;
+  console.warn(
+    "[raindrop] Multiple API keys detected in one process. The OTel export guard now requires positive attribution: spans not bound to any client (no begin()/asCurrent()) are dropped, and spans bound to a non-owner key are dropped. Manual events are unaffected."
+  );
+}
+function registerClientKey(authHint, tracingEnabled = false) {
+  if (!authHint) return;
+  const state = getState();
+  state.seenClientHints.add(authHint);
+  if (state.seenClientHints.size > 1) {
+    state.foreignClientSeen = true;
+    if (tracingEnabled || state.pipelineClaimed) {
+      emitMultiKeyWarningOnce();
+    } else {
+      state.pendingMultiKeyWarning = true;
+    }
+  }
+}
+function markForeignClient() {
+  getState().foreignClientSeen = true;
+}
+function foreignClientSeen() {
+  return getState().foreignClientSeen;
+}
+function stampSpan(span, projectId, authHint) {
+  try {
+    if (projectId) {
+      span.setAttribute(PROJECT_ID_SPAN_ATTRIBUTE, projectId);
+    }
+    if (authHint && foreignClientSeen()) {
+      span.setAttribute(AUTH_HINT_SPAN_ATTRIBUTE, authHint);
+    }
+  } catch (e) {
+  }
+}
+var RaindropContextSpanProcessor = class {
+  onStart(span) {
+    try {
+      const bound = currentRoutingBinding();
+      if (!bound) return;
+      stampSpan(span, bound.projectId, bound.authHint);
+    } catch (e) {
+    }
+  }
+  onEnd() {
+  }
+  async forceFlush() {
+  }
+  async shutdown() {
+  }
+};
+var GuardedSpanExporter = class {
+  constructor(inner, ownerAuthHint) {
+    this.droppedTotal = 0;
+    this.inner = inner;
+    this.ownerAuthHint = ownerAuthHint;
+  }
+  partition(spans) {
+    var _a;
+    const allowed = [];
+    let dropped = 0;
+    const requirePositive = foreignClientSeen();
+    for (const span of spans) {
+      const attrs = (_a = span.attributes) != null ? _a : {};
+      const hint = attrs[AUTH_HINT_SPAN_ATTRIBUTE];
+      const keep = requirePositive ? hint === this.ownerAuthHint : hint === void 0 || hint === this.ownerAuthHint;
+      if (keep) {
+        allowed.push(span);
+      } else {
+        dropped += 1;
+      }
+    }
+    return { allowed, dropped };
+  }
+  warnDropped(dropped) {
+    this.droppedTotal += dropped;
+    const total = this.droppedTotal;
+    rateLimitedLog(
+      "js-sdk.multi-project.dropped",
+      () => console.warn(
+        `[raindrop] Dropped ${dropped} span(s) produced under a different API key than the tracing pipeline's (total dropped: ${total}). One process has ONE OTel pipeline authenticating with the first tracing-enabled client's key; tracing for a different key/org in the same process is unsupported \u2014 run it in its own process. Manual events (track_ai/begin/finish/signals/identify) are unaffected.`
+      )
+    );
+  }
+  export(spans, resultCallback) {
+    let allowed;
+    let dropped;
+    try {
+      ({ allowed, dropped } = this.partition(spans));
+    } catch (e) {
+      if (foreignClientSeen()) {
+        this.warnDropped(spans.length);
+        resultCallback({ code: EXPORT_FAILED });
+        return;
+      }
+      this.inner.export(spans, resultCallback);
+      return;
+    }
+    if (dropped) {
+      this.warnDropped(dropped);
+    }
+    if (allowed.length === 0) {
+      resultCallback({ code: EXPORT_SUCCESS });
+      return;
+    }
+    this.inner.export(allowed, resultCallback);
+  }
+  shutdown() {
+    return this.inner.shutdown();
+  }
+  forceFlush() {
+    return this.inner.forceFlush ? this.inner.forceFlush() : Promise.resolve();
+  }
+};
+function buildGuardedExporter(baseUrl, headers, ownerAuthHint) {
+  const inner = new import_exporter_trace_otlp_proto.OTLPTraceExporter({
+    url: `${baseUrl}/v1/traces`,
+    headers
+  });
+  return new GuardedSpanExporter(inner, ownerAuthHint);
+}
+function pipelineOwnerHint() {
+  return getState().ownerAuthHint;
+}
+function claimPipeline(authHint, projectId) {
+  const state = getState();
+  if (state.pipelineClaimed) {
+    return false;
+  }
+  state.pipelineClaimed = true;
+  state.ownerAuthHint = authHint;
+  state.ownerProjectId = projectId;
+  if (state.foreignClientSeen && state.pendingMultiKeyWarning) {
+    emitMultiKeyWarningOnce();
+  }
+  return true;
+}
+function releasePipelineClaim() {
+  const state = getState();
+  state.pipelineClaimed = false;
+  state.ownerAuthHint = void 0;
+  state.ownerProjectId = void 0;
+}
+function markTraceloopConfiguredWithoutClaim() {
+  getState().traceloopConfiguredWithoutClaim = true;
+}
+function traceloopConfiguredWithoutClaim() {
+  return getState().traceloopConfiguredWithoutClaim;
+}
+
 // src/tracing/direct/shipper.ts
 function serializeAssociationValue(value) {
   return stringifyBounded(value);
@@ -10800,7 +11157,11 @@ var DirectTraceShipper = class {
       attrString2("traceloop.entity.input", params.input),
       attrString2("traceloop.entity.output", params.output),
       // Duration tracking
-      attrInt2("traceloop.entity.duration_ms", params.durationMs)
+      attrInt2("traceloop.entity.duration_ms", params.durationMs),
+      // Per-span project routing: the ingest boundary routes on this attribute
+      // (org-validated) and falls back to the request's project header. Direct
+      // spans ship on this instance's own key, so no cross-key auth hint.
+      attrString2(PROJECT_ID_SPAN_ATTRIBUTE, this.projectId)
     ];
     for (const [key, value] of Object.entries(params.properties)) {
       if (value === void 0) {
@@ -11098,12 +11459,27 @@ var DirectToolSpan = class {
   }
 };
 var LiveInteraction = class {
-  constructor(context5, traceId, analytics, directShipper) {
+  constructor(context5, traceId, analytics, directShipper, routing) {
     this.context = context5;
     this.analytics = analytics;
     this.tracer = import_api2.trace.getTracer("traceloop.tracer");
     this.traceId = traceId;
     this.directShipper = directShipper;
+    this.routing = routing;
+  }
+  /**
+   * Record the routing binding this interaction pushed onto the context stack
+   * (via {@link bindRoutingContext} in `begin()`) so {@link finish} removes
+   * exactly its own entry — non-LIFO safe, and leaving any still-open sibling's
+   * binding intact.
+   */
+  setBoundContext(bound) {
+    this.boundContext = bound;
+  }
+  /** Stamp a manually-created OTel span with this interaction's routing. */
+  stampRouting(span) {
+    if (!this.routing) return;
+    stampSpan(span, this.routing.projectId, this.routing.authHint);
   }
   ensureTraceId(preferred) {
     if (preferred) {
@@ -11172,8 +11548,9 @@ var LiveInteraction = class {
         import_api2.context.active(),
         import_api2.trace.wrapSpanContext(spanContext)
       );
+      const invoke = () => this.routing ? withRoutingContext(this.routing, () => fn.apply(thisArg, args)) : fn.apply(thisArg, args);
       try {
-        const result = await import_api2.context.with(wrappedContext, () => fn.apply(thisArg, args));
+        const result = await import_api2.context.with(wrappedContext, invoke);
         const endTimeMs = Date.now();
         this.directShipper.sendSpan({
           name: taskName,
@@ -11208,11 +11585,17 @@ var LiveInteraction = class {
       }
     }
     const wrappedFn = (...fnArgs) => {
-      var _a2;
-      const activeTraceId = (_a2 = import_api2.trace.getSpan(import_api2.context.active())) == null ? void 0 : _a2.spanContext().traceId;
+      const activeSpan = import_api2.trace.getSpan(import_api2.context.active());
+      const activeTraceId = activeSpan == null ? void 0 : activeSpan.spanContext().traceId;
       if (activeTraceId) {
         this.traceId = activeTraceId;
       }
+      if (activeSpan) {
+        this.stampRouting(activeSpan);
+      }
+      if (this.routing) {
+        return withRoutingContext(this.routing, () => fn.apply(thisArg, fnArgs));
+      }
       return fn.apply(thisArg, fnArgs);
     };
     return traceloop.withTask(
@@ -11224,7 +11607,6 @@ var LiveInteraction = class {
         suppressTracing: params.suppressTracing
       },
       wrappedFn,
-      void 0,
       ...args
     );
   }
@@ -11261,10 +11643,11 @@ var LiveInteraction = class {
         import_api2.context.active(),
         import_api2.trace.wrapSpanContext(spanContext)
       );
+      const invoke = () => this.routing ? withRoutingContext(this.routing, () => fn.apply(thisArg, args)) : fn.apply(thisArg, args);
       let result;
       let error;
       try {
-        result = await import_api2.context.with(wrappedContext, () => fn.apply(thisArg, args));
+        result = await import_api2.context.with(wrappedContext, invoke);
       } catch (err) {
         error = err instanceof Error ? err.message : String(err);
         const endTimeMs2 = Date.now();
@@ -11332,6 +11715,9 @@ var LiveInteraction = class {
       const activeSpan = import_api2.trace.getSpan(import_api2.context.active());
       const ctx = activeSpan == null ? void 0 : activeSpan.spanContext();
       const liveSpanId = ctx && (0, import_api2.isValidSpanId)(ctx.spanId) ? ctx.spanId : void 0;
+      if (activeSpan) {
+        this.stampRouting(activeSpan);
+      }
       emitLive({
         type: "tool_start",
         spanId: liveSpanId,
@@ -11340,7 +11726,7 @@ var LiveInteraction = class {
         metadata: params.inputParameters ? { args: params.inputParameters } : void 0
       });
       try {
-        const r = await fn.apply(thisArg, wrappedArgs);
+        const r = this.routing ? await withRoutingContext(this.routing, () => fn.apply(thisArg, wrappedArgs)) : await fn.apply(thisArg, wrappedArgs);
         emitLive({
           type: "tool_result",
           spanId: liveSpanId,
@@ -11376,7 +11762,6 @@ var LiveInteraction = class {
         suppressTracing: params.suppressTracing
       },
       wrapped,
-      void 0,
       ...args
     );
   }
@@ -11387,6 +11772,7 @@ var LiveInteraction = class {
     setAssociationProperties(span, contextProperties);
     span.setAttribute("traceloop.span.kind", "task");
     setAssociationProperties(span, properties);
+    this.stampRouting(span);
     return span;
   }
   startToolSpan(params) {
@@ -11428,6 +11814,7 @@ var LiveInteraction = class {
     setAssociationProperties(span, contextProperties);
     span.setAttribute("traceloop.span.kind", "tool");
     setAssociationProperties(span, properties);
+    this.stampRouting(span);
     if (inputParameters !== void 0) {
       span.setAttribute("traceloop.entity.input", serializeSpanValue(inputParameters));
     }
@@ -11530,6 +11917,8 @@ var LiveInteraction = class {
   }
   async finish(resultEvent) {
     var _a, _b, _c, _d;
+    unbindRoutingContext(this.boundContext);
+    this.boundContext = void 0;
     if (!this.traceId) {
       this.resolveLiveTraceId();
     }
@@ -11617,6 +12006,7 @@ var LiveInteraction = class {
     setAssociationProperties(span, contextProperties);
     span.setAttribute("traceloop.span.kind", "tool");
     setAssociationProperties(span, properties);
+    this.stampRouting(span);
     if (input !== void 0) {
       span.setAttribute("traceloop.entity.input", stringifyBounded(input));
     }
@@ -11662,10 +12052,16 @@ var LiveInteraction = class {
 var import_api3 = require("@opentelemetry/api");
 var traceloop2 = __toESM(require("@traceloop/node-server-sdk"));
 var LiveTracer = class {
-  constructor(globalProperties, directShipper) {
+  constructor(globalProperties, directShipper, routing) {
     this.tracer = import_api3.trace.getTracer("traceloop.tracer");
     this.globalProperties = globalProperties || {};
     this.directShipper = directShipper;
+    this.routing = routing;
+  }
+  /** Stamp a manually-created OTel span with this tracer's client routing. */
+  stampRouting(span) {
+    if (!this.routing) return;
+    stampSpan(span, this.routing.projectId, this.routing.authHint);
   }
   emitLiveEvent(event) {
     var _a, _b;
@@ -11688,6 +12084,16 @@ var LiveTracer = class {
       ...params.properties || {}
     };
     const inputParameters = typeof params === "string" ? void 0 : params.inputParameters;
+    const wrappedFn = (...fnArgs) => {
+      const activeSpan = import_api3.trace.getSpan(import_api3.context.active());
+      if (activeSpan) {
+        this.stampRouting(activeSpan);
+      }
+      if (this.routing) {
+        return withRoutingContext(this.routing, () => fn.apply(thisArg, fnArgs));
+      }
+      return fn.apply(thisArg, fnArgs);
+    };
     return traceloop2.withTask(
       {
         name: taskName,
@@ -11696,8 +12102,7 @@ var LiveTracer = class {
         traceContent: params.traceContent,
         suppressTracing: params.suppressTracing
       },
-      fn,
-      thisArg,
+      wrappedFn,
       ...args
     );
   }
@@ -11746,6 +12151,7 @@ var LiveTracer = class {
     const span = this.tracer.startSpan(name, {
       startTime: startTimeMs
     });
+    this.stampRouting(span);
     Object.entries(this.globalProperties).forEach(([key, value]) => {
       span.setAttribute("traceloop.association.properties." + key, String(value));
     });
@@ -11790,6 +12196,59 @@ var LiveTracer = class {
   }
 };
 
+// src/tracing/exit-flush.ts
+var traceloop3 = __toESM(require("@traceloop/node-server-sdk"));
+var STATE_KEY2 = /* @__PURE__ */ Symbol.for("raindrop.tracing.exitFlushState");
+function getState2() {
+  const holder = globalThis;
+  let state = holder[STATE_KEY2];
+  if (!state) {
+    state = {
+      clientFlushers: /* @__PURE__ */ new Set(),
+      pipelineFlushNeeded: false,
+      handlerRegistered: false
+    };
+    holder[STATE_KEY2] = state;
+  }
+  return state;
+}
+function ensureExitHandler(state) {
+  if (state.handlerRegistered) return;
+  if (typeof process === "undefined" || typeof process.once !== "function") return;
+  state.handlerRegistered = true;
+  process.once("beforeExit", () => {
+    void flushAll();
+  });
+}
+function registerClientFlusher(flush) {
+  const state = getState2();
+  state.clientFlushers.add(flush);
+  ensureExitHandler(state);
+  return () => {
+    state.clientFlushers.delete(flush);
+  };
+}
+function markPipelineForExitFlush() {
+  const state = getState2();
+  state.pipelineFlushNeeded = true;
+  ensureExitHandler(state);
+}
+async function flushAll() {
+  const state = getState2();
+  const tasks = [];
+  for (const flush of state.clientFlushers) {
+    tasks.push(Promise.resolve().then(flush).catch(() => {
+    }));
+  }
+  if (state.pipelineFlushNeeded) {
+    tasks.push(
+      Promise.resolve().then(() => traceloop3.forceFlush()).catch(() => {
+      })
+    );
+  }
+  await Promise.all(tasks);
+}
+
 // src/tracing/tracer-core.ts
 if (localDebuggerEnabled()) {
   if (!process.env.OTEL_EXPORTER_OTLP_PROTOCOL) {
@@ -11898,6 +12357,29 @@ function resolveLocalDebuggerExporterBaseUrl(baseUrlOpt) {
 function createLocalDebuggerOtlpExporter(config) {
   return new import_exporter_trace_otlp_http.OTLPTraceExporter(config);
 }
+function parseTraceloopHeaders(value) {
+  const headers = {};
+  for (const entry of value.split(",")) {
+    const keyPairPart = entry.split(";")[0];
+    const sep = keyPairPart.indexOf("=");
+    if (sep <= 0) continue;
+    try {
+      const key = decodeURIComponent(keyPairPart.slice(0, sep).trim());
+      const val = decodeURIComponent(keyPairPart.slice(sep + 1).trim());
+      if (key.length > 0 && val.length > 0) headers[key] = val;
+    } catch (e) {
+    }
+  }
+  return headers;
+}
+function traceloopDefaultHeaders(writeKey) {
+  const env = process.env.TRACELOOP_HEADERS;
+  if (env) {
+    const parsed = parseTraceloopHeaders(env);
+    if (Object.keys(parsed).length > 0) return parsed;
+  }
+  return { Authorization: `Bearer ${writeKey}` };
+}
 function createLocalDebuggerSpanProcessor(options) {
   const localDebuggerUrl = resolveLocalDebuggerExporterBaseUrl(options.localDebuggerUrlOpt);
   if (!localDebuggerUrl) {
@@ -11908,7 +12390,7 @@ function createLocalDebuggerSpanProcessor(options) {
     headers: {}
   });
   try {
-    return traceloop3.createSpanProcessor({
+    return traceloop4.createSpanProcessor({
       apiKey: options.writeKey,
       baseUrl: localDebuggerUrl,
       disableBatch: options.disableBatching,
@@ -11924,12 +12406,6 @@ function createLocalDebuggerSpanProcessor(options) {
     return void 0;
   }
 }
-function mergeWithBestEffortLocalDebuggerProcessor(processor, localDebuggerProcessor) {
-  if (!localDebuggerProcessor) {
-    return processor;
-  }
-  return new CompositeSpanProcessor(processor ? [processor] : [], [localDebuggerProcessor]);
-}
 var warnedSpanNormalizeFailure = false;
 var INVALID_OTEL_SPAN_ID = "0000000000000000";
 function normalizeSpanForV1Exporter(span) {
@@ -12229,13 +12705,12 @@ function createManualInstrumentations(instrumentModules) {
   }
   return instrumentations;
 }
-var activeInteractions = new import_weakref.WeakValueMap();
-var activeInteractionsByEventId = new import_weakref.WeakValueMap();
 function getCurrentTraceId() {
   var _a;
   return (_a = import_api4.trace.getSpan(import_api4.context.active())) == null ? void 0 : _a.spanContext().traceId;
 }
 var tracing = (analytics, apiUrl, writeKey, options, isDebug = false) => {
+  var _a;
   process.env.TRACELOOP_TELEMETRY = "false";
   const {
     logLevel,
@@ -12250,12 +12725,15 @@ var tracing = (analytics, apiUrl, writeKey, options, isDebug = false) => {
     ...otherOptions
   } = options;
   const cloudEnabledResolved = cloudEnabled != null ? cloudEnabled : true;
+  const authHint = authHintForKey(writeKey);
+  const clientTracingExports = !useExternalOtel && cloudEnabledResolved && tracingEnabled !== false;
+  registerClientKey(authHint, clientTracingExports);
   const withProjectIdHeaders = (existing) => {
     if (!projectId) {
       return existing;
     }
     return {
-      Authorization: `Bearer ${writeKey}`,
+      ...traceloopDefaultHeaders(writeKey),
       ...existing != null ? existing : {},
       ...projectIdHeaders(projectId)
     };
@@ -12277,9 +12755,12 @@ var tracing = (analytics, apiUrl, writeKey, options, isDebug = false) => {
     projectId
   }) : void 0;
   let traceloopInitialized = false;
+  let claimedPipeline = false;
+  const activeInteractions = new import_weakref.WeakValueMap();
+  const activeInteractionsByEventId = new import_weakref.WeakValueMap();
   try {
     if (useExternalOtel) {
-      traceloop3.initialize({
+      traceloop4.initialize({
         baseUrl: apiUrl,
         apiKey: writeKey,
         logLevel,
@@ -12291,6 +12772,7 @@ var tracing = (analytics, apiUrl, writeKey, options, isDebug = false) => {
         // DO NOT create NodeSDK - customer has their own
       });
       traceloopInitialized = true;
+      markTraceloopConfiguredWithoutClaim();
       if (isDebug) {
         console.log(
           "[raindrop] External OTEL mode active. Add raindrop.createSpanProcessor() to your NodeSDK's spanProcessors. Register instrumentations (AnthropicInstrumentation, etc.) on your NodeSDK."
@@ -12307,12 +12789,12 @@ var tracing = (analytics, apiUrl, writeKey, options, isDebug = false) => {
       const localDebuggerProcessor = createLocalDebuggerSpanProcessor({
         writeKey,
         disableBatching,
-        allowedInstrumentationLibraries: traceloop3.ALL_INSTRUMENTATION_LIBRARIES,
+        allowedInstrumentationLibraries: traceloop4.ALL_INSTRUMENTATION_LIBRARIES,
         localDebuggerUrlOpt: localDebuggerUrl
       });
       if (!cloudEnabledResolved) {
         if (localDebuggerProcessor) {
-          traceloop3.initialize({
+          traceloop4.initialize({
             baseUrl: apiUrl,
             apiKey: writeKey,
             ...otherOptions,
@@ -12323,8 +12805,9 @@ var tracing = (analytics, apiUrl, writeKey, options, isDebug = false) => {
             processor: localDebuggerProcessor
           });
           traceloopInitialized = true;
+          markTraceloopConfiguredWithoutClaim();
         } else {
-          traceloop3.initialize({
+          traceloop4.initialize({
             baseUrl: apiUrl,
             apiKey: writeKey,
             logLevel,
@@ -12332,33 +12815,91 @@ var tracing = (analytics, apiUrl, writeKey, options, isDebug = false) => {
             tracingEnabled: false
           });
           traceloopInitialized = true;
+          markTraceloopConfiguredWithoutClaim();
         }
+      } else if (tracingEnabled === false) {
+        traceloopInitialized = false;
       } else {
-        const processor = mergeWithBestEffortLocalDebuggerProcessor(
-          otherOptions.processor,
-          localDebuggerProcessor
-        );
-        const headers = withProjectIdHeaders(otherOptions.headers);
-        traceloop3.initialize({
-          baseUrl: apiUrl,
-          apiKey: writeKey,
-          ...otherOptions,
-          logLevel,
-          silenceInitializationMessage: true,
-          tracingEnabled: tracingEnabled !== false,
-          disableBatch: disableBatching,
-          ...processor ? { processor } : {},
-          ...headers ? { headers } : {}
-        });
-        traceloopInitialized = true;
+        const claimed = claimPipeline(authHint, projectId);
+        claimedPipeline = claimed;
+        const ownerHint = pipelineOwnerHint();
+        if (!claimed && authHint !== ownerHint) {
+          markForeignClient();
+          console.warn(
+            "[raindrop] The OTel tracing pipeline is already initialized with a DIFFERENT api key. One process supports one tracing key/org: auto-instrumented spans from this client will be dropped at export, and spans not bound to any client (no begin()/asCurrent()) will be dropped as unattributable (manual events are unaffected and route normally). Run this client in its own process for tracing."
+          );
+        }
+        if (claimed && traceloopConfiguredWithoutClaim()) {
+          releasePipelineClaim();
+          claimedPipeline = false;
+          console.warn(
+            "[raindrop] Cannot initialize the cloud tracing pipeline: OpenTelemetry was already configured in this process by an earlier Raindrop client (external-OTEL mode, or a local-only/Workshop client with no write key). Traceloop's tracer provider is fixed once per process, so this client's auto-instrumented spans will NOT be exported. Construct the cloud tracing-enabled client FIRST, or run it in its own process. Manual events (track_ai/begin/finish/signals/identify) are unaffected."
+          );
+        } else if (claimed) {
+          const exporterHeaders = (_a = withProjectIdHeaders(otherOptions.headers)) != null ? _a : traceloopDefaultHeaders(writeKey);
+          let guardedExporter;
+          try {
+            const callerExporter = otherOptions.exporter;
+            guardedExporter = callerExporter ? new GuardedSpanExporter(callerExporter, ownerHint) : buildGuardedExporter(apiUrl, exporterHeaders, ownerHint);
+          } catch (guardError) {
+            releasePipelineClaim();
+            claimedPipeline = false;
+            console.warn(
+              `[raindrop] could not install the guarded span exporter (${guardError instanceof Error ? guardError.message : guardError}); disabling tracing rather than running an unguarded pipeline. Manual events are unaffected.`
+            );
+          }
+          if (guardedExporter) {
+            const contextProcessor = new RaindropContextSpanProcessor();
+            const callerProcessor = otherOptions.processor;
+            const processor = new CompositeSpanProcessor(
+              callerProcessor ? [contextProcessor, callerProcessor] : [contextProcessor],
+              localDebuggerProcessor ? [localDebuggerProcessor] : []
+            );
+            try {
+              traceloop4.initialize({
+                baseUrl: apiUrl,
+                apiKey: writeKey,
+                ...otherOptions,
+                logLevel,
+                silenceInitializationMessage: true,
+                // This branch only runs when tracing is enabled (the disabled
+                // case is handled above), so tracing is always on here.
+                tracingEnabled: true,
+                disableBatch: disableBatching,
+                processor,
+                exporter: guardedExporter
+              });
+              traceloopInitialized = true;
+            } catch (initError) {
+              releasePipelineClaim();
+              claimedPipeline = false;
+              throw initError;
+            }
+          }
+        } else {
+          traceloopInitialized = true;
+        }
       }
     }
   } catch (error) {
+    if (claimedPipeline && !traceloopInitialized) {
+      releasePipelineClaim();
+      claimedPipeline = false;
+    }
     console.warn(
       "[raindrop] Failed to initialize traceloop. Spans will not be sent.",
       error instanceof Error ? error.message : error
     );
   }
+  if (traceloopInitialized) {
+    markPipelineForExitFlush();
+  }
+  const deregisterExitFlusher = directShipper ? registerClientFlusher(async () => {
+    try {
+      await directShipper.flush();
+    } catch (e) {
+    }
+  }) : void 0;
   return {
     /**
      * Returns instrumentation instances for your NodeSDK.
@@ -12446,7 +12987,7 @@ var tracing = (analytics, apiUrl, writeKey, options, isDebug = false) => {
         );
       }
       const headers = withProjectIdHeaders(processorOptions == null ? void 0 : processorOptions.headers);
-      const productionProcessor = traceloop3.createSpanProcessor({
+      const productionProcessor = traceloop4.createSpanProcessor({
         baseUrl: apiUrl,
         apiKey: writeKey,
         disableBatch: disableBatching,
@@ -12459,12 +13000,16 @@ var tracing = (analytics, apiUrl, writeKey, options, isDebug = false) => {
         allowedInstrumentationLibraries: processorOptions == null ? void 0 : processorOptions.allowedInstrumentationLibraries,
         localDebuggerUrlOpt: localDebuggerUrl
       });
+      const contextProcessor = new RaindropContextSpanProcessor();
       return withV2SpanCompat(
-        mergeWithBestEffortLocalDebuggerProcessor(productionProcessor, localDebuggerProcessor)
+        new CompositeSpanProcessor(
+          [contextProcessor, productionProcessor],
+          localDebuggerProcessor ? [localDebuggerProcessor] : []
+        )
       );
     },
     begin(traceContext) {
-      var _a;
+      var _a2;
       if (!traceContext.eventId) {
         traceContext.eventId = crypto.randomUUID();
       }
@@ -12473,19 +13018,27 @@ var tracing = (analytics, apiUrl, writeKey, options, isDebug = false) => {
         traceContext,
         traceId,
         analytics,
-        directShipper
+        directShipper,
+        { projectId, authHint }
       );
-      analytics._trackAiPartial({
-        ...traceContext,
-        properties: {
-          ...(_a = traceContext.properties) != null ? _a : {},
-          ...interaction.getTraceId() ? { trace_id: interaction.getTraceId() } : {}
+      const bound = bindRoutingContext({ projectId, authHint }, interaction);
+      interaction.setBoundContext(bound);
+      try {
+        analytics._trackAiPartial({
+          ...traceContext,
+          properties: {
+            ...(_a2 = traceContext.properties) != null ? _a2 : {},
+            ...interaction.getTraceId() ? { trace_id: interaction.getTraceId() } : {}
+          }
+        });
+        if (interaction.getTraceId()) {
+          activeInteractions.set(interaction.getTraceId(), interaction);
         }
-      });
-      if (interaction.getTraceId()) {
-        activeInteractions.set(interaction.getTraceId(), interaction);
+        activeInteractionsByEventId.set(traceContext.eventId, interaction);
+      } catch (error) {
+        unbindRoutingContext(bound);
+        throw error;
       }
-      activeInteractionsByEventId.set(traceContext.eventId, interaction);
       return interaction;
     },
     getActiveInteraction(eventId) {
@@ -12500,12 +13053,15 @@ var tracing = (analytics, apiUrl, writeKey, options, isDebug = false) => {
           return interactionByTraceId;
         }
       }
-      const interaction = new LiveInteraction({ eventId }, traceId, analytics, directShipper);
+      const interaction = new LiveInteraction({ eventId }, traceId, analytics, directShipper, {
+        projectId,
+        authHint
+      });
       activeInteractionsByEventId.set(eventId, interaction);
       return interaction;
     },
     tracer(globalProperties) {
-      return new LiveTracer(globalProperties, directShipper);
+      return new LiveTracer(globalProperties, directShipper, { projectId, authHint });
     },
     /**
      * Best-effort drain of in-flight OTel spans and direct shipper batches.
@@ -12520,18 +13076,19 @@ var tracing = (analytics, apiUrl, writeKey, options, isDebug = false) => {
       }
       if (traceloopInitialized) {
         try {
-          await traceloop3.forceFlush();
+          await traceloop4.forceFlush();
         } catch (e) {
         }
       }
     },
     async close() {
+      deregisterExitFlusher == null ? void 0 : deregisterExitFlusher();
       activeInteractions.clear();
       activeInteractionsByEventId.clear();
       await (directShipper == null ? void 0 : directShipper.shutdown());
       if (traceloopInitialized) {
         try {
-          await traceloop3.forceFlush();
+          await traceloop4.forceFlush();
         } catch (e) {
         }
       }
@@ -12743,6 +13300,7 @@ var Raindrop = class {
     setDefaultMaxTextFieldChars(config.maxTextFieldChars);
     this.maxTextFieldChars = resolveMaxTextFieldChars(config.maxTextFieldChars);
     this.writeKey = (_a = config.writeKey) != null ? _a : "";
+    this.authHint = authHintForKey(this.writeKey);
     this.localDebuggerUrlOpt = config.localWorkshopUrl === false ? null : config.localWorkshopUrl;
     this.awaitSpanFlushOpt = config.awaitSpanFlush;
     this.apiUrl = (_b = this.formatEndpoint(config.endpoint)) != null ? _b : `https://api.raindrop.ai/v1/`;
@@ -12805,6 +13363,14 @@ var Raindrop = class {
   /**
    * Begins a new interaction.
    *
+   * The interaction's routing binding lives until `finish()` (which unbinds it
+   * by identity, so it is removed even if `finish()` runs inside a nested
+   * `withSpan`/`withTool`/`asCurrent` scope or a detached task). One exception:
+   * calling `begin()` INSIDE an `asCurrent(fn)` scope pushes the binding within
+   * that scope, so it dies when the scope exits (matching the Python SDK's
+   * token-reset semantics) — start such interactions outside `asCurrent`, or
+   * keep their work inside the same scope.
+   *
    * @param traceContext - The trace context for the interaction.
    * @returns The interaction object.
    */
@@ -12822,6 +13388,22 @@ var Raindrop = class {
   tracer(globalProperties) {
     return this._tracing.tracer(globalProperties);
   }
+  /**
+   * Scope all spans created inside `fn` (and its awaited continuations) to this
+   * client's project/key, without an interaction. Use it around auto-
+   * instrumented calls (an LLM SDK call, a framework invocation) that aren't
+   * wrapped by `begin()`/`finish()` so their spans route to this client's
+   * project in a multi-client process. The binding lasts exactly the duration
+   * of `fn` — it is removed when `fn` returns or throws.
+   *
+   * @example
+   * ```ts
+   * const answer = await raindrop.asCurrent(() => llm.chat({ ... }));
+   * ```
+   */
+  asCurrent(fn) {
+    return withRoutingContext({ projectId: this.projectId, authHint: this.authHint }, fn);
+  }
   createSpanProcessor(processorOptions) {
     return this._tracing.createSpanProcessor(processorOptions);
   }