raindrop-ai 0.2.4 → 0.3.0

package/dist/tracing/index.js

@@ -42,7 +42,7 @@ if (!globalThis.RAINDROP_ASYNC_LOCAL_STORAGE) {
 }
 
 // src/tracing/tracer-core.ts
-var import_api4 = require("@opentelemetry/api");
+var import_api5 = require("@opentelemetry/api");
 var import_exporter_trace_otlp_http = require("@opentelemetry/exporter-trace-otlp-http");
 var import_instrumentation_anthropic = require("@traceloop/instrumentation-anthropic");
 var import_instrumentation_bedrock = require("@traceloop/instrumentation-bedrock");
@@ -56,7 +56,7 @@ var import_instrumentation_vertexai = require("@traceloop/instrumentation-vertex
 var traceloop4 = __toESM(require("@traceloop/node-server-sdk"));
 var import_weakref = require("weakref");
 
-// ../core/dist/chunk-QTUH3BHZ.js
+// ../core/dist/chunk-YUIXRQWN.js
 function normalizeFeatureFlags(input) {
   if (Array.isArray(input)) {
     return Object.fromEntries(input.map((name) => [name, "true"]));
@@ -65,6 +65,293 @@ function normalizeFeatureFlags(input) {
     Object.entries(input).map(([k, v]) => [k, String(v)])
   );
 }
+function getCrypto() {
+  const c = globalThis.crypto;
+  return c;
+}
+function randomBytes(length) {
+  const cryptoObj = getCrypto();
+  const out = new Uint8Array(length);
+  if (cryptoObj && typeof cryptoObj.getRandomValues === "function") {
+    cryptoObj.getRandomValues(out);
+    return out;
+  }
+  for (let i = 0; i < out.length; i++) out[i] = Math.floor(Math.random() * 256);
+  return out;
+}
+function randomUUID() {
+  const cryptoObj = getCrypto();
+  if (cryptoObj && typeof cryptoObj.randomUUID === "function") {
+    return cryptoObj.randomUUID();
+  }
+  const b = randomBytes(16);
+  b[6] = b[6] & 15 | 64;
+  b[8] = b[8] & 63 | 128;
+  const hex = [...b].map((x) => x.toString(16).padStart(2, "0")).join("");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+var HANDOFF_ATTRIBUTE_SUFFIXES = {
+  mode: "raindrop.handoff.mode",
+  childEventId: "raindrop.handoff.childEventId",
+  parentEventId: "raindrop.handoff.parentEventId",
+  parentSpanId: "raindrop.handoff.parentSpanId",
+  name: "raindrop.handoff.name",
+  terminal: "raindrop.handoff.terminal",
+  agentRole: "raindrop.agent.role"
+};
+var AI_SDK_METADATA_PREFIX = "ai.telemetry.metadata.";
+var DETACHED_MODE = "detached";
+var SUBAGENT_AGENT_ROLE = "subagent";
+var HANDOFF_TERMINAL_CANCELLED = "cancelled";
+var TOOL_EVENTS_SUFFIX = "raindrop.toolEvents";
+var TOOL_EVENTS_ALLOW = "allow";
+var OPERATION_ID_ATTRIBUTE = "ai.operationId";
+var SUBAGENT_ABORT_OPERATION_ID = "ai.subagent.failed";
+var SUBAGENT_ABORT_SPAN_NAME = SUBAGENT_ABORT_OPERATION_ID;
+var DEFAULT_DISPATCH_SPAN_NAME = "launch_subagent";
+var HANDOFF_TERMINAL_PROPERTY_KEY = HANDOFF_ATTRIBUTE_SUFFIXES.terminal;
+function defined(entries) {
+  const out = {};
+  for (const [key, value] of Object.entries(entries)) {
+    if (typeof value === "string" && value.trim().length > 0) out[key] = value;
+  }
+  return out;
+}
+function detachedDispatchMetadata(dispatch) {
+  return defined({
+    [HANDOFF_ATTRIBUTE_SUFFIXES.mode]: DETACHED_MODE,
+    [HANDOFF_ATTRIBUTE_SUFFIXES.childEventId]: dispatch.childEventId,
+    [HANDOFF_ATTRIBUTE_SUFFIXES.name]: dispatch.name
+  });
+}
+function detachedChildMetadata(link) {
+  return defined({
+    [HANDOFF_ATTRIBUTE_SUFFIXES.parentEventId]: link.parentEventId,
+    [HANDOFF_ATTRIBUTE_SUFFIXES.parentSpanId]: link.parentSpanId,
+    [HANDOFF_ATTRIBUTE_SUFFIXES.name]: link.name,
+    [HANDOFF_ATTRIBUTE_SUFFIXES.agentRole]: SUBAGENT_AGENT_ROLE
+  });
+}
+function cancelledTerminalMetadata() {
+  return { [HANDOFF_ATTRIBUTE_SUFFIXES.terminal]: HANDOFF_TERMINAL_CANCELLED };
+}
+function cancelledTerminalAttributes() {
+  const bare = cancelledTerminalMetadata();
+  return { ...bare, ...withMetadataPrefix(bare) };
+}
+function toolEventsAllowMetadata() {
+  return { [TOOL_EVENTS_SUFFIX]: TOOL_EVENTS_ALLOW };
+}
+function withMetadataPrefix(metadata) {
+  const out = {};
+  for (const [key, value] of Object.entries(metadata)) {
+    out[key.startsWith(AI_SDK_METADATA_PREFIX) ? key : `${AI_SDK_METADATA_PREFIX}${key}`] = value;
+  }
+  return out;
+}
+var BAGGAGE_KEYS = {
+  eventId: "raindrop-event-id",
+  childEventId: "raindrop-child-event-id",
+  name: "raindrop-handoff-name",
+  convoId: "raindrop-convo-id",
+  userId: "raindrop-user-id",
+  // The dispatch span and its trace, carried as fields as well as in
+  // `traceparent`. Not redundant: OTel's HTTP instrumentations rewrite
+  // `traceparent` from whatever span is current as the request goes out, so by
+  // the time the child reads it the ids name the HTTP client span and its trace
+  // instead of the dispatch. The child would then point its reverse reference at
+  // a span the launcher's UI does not know as a dispatch. A field states which
+  // span it means rather than meaning "whoever wrote this header last".
+  dispatchSpanId: "raindrop-dispatch-span-id",
+  traceId: "raindrop-trace-id"
+};
+var TRACEPARENT_HEADER = "traceparent";
+var BAGGAGE_HEADER = "baggage";
+var W3C_TRACE_ID = /^[0-9a-f]{32}$/;
+var W3C_SPAN_ID = /^[0-9a-f]{16}$/;
+function isW3CTraceId(value) {
+  return value !== void 0 && W3C_TRACE_ID.test(value);
+}
+function isW3CSpanId(value) {
+  return value !== void 0 && W3C_SPAN_ID.test(value);
+}
+var warnedNonConformantIds = false;
+function warnNonConformantIdsOnce(traceId, spanId) {
+  if (warnedNonConformantIds) return;
+  warnedNonConformantIds = true;
+  console.warn(
+    `[raindrop] hand-off carrier ids are not W3C-shaped (traceId="${traceId}", spanId="${spanId}"). The child still reports as its own event, but its reverse reference names a span id the backend does not store, so the link back to the launcher will not resolve. A LangSmith carrier reads this way \u2014 its run ids are UUIDs; propagate Raindrop's own carrier (toHeaders) to link.`
+  );
+}
+var HANDOFF_HEADER = "x-raindrop-handoff";
+var LANGSMITH_TRACE_HEADER = "langsmith-trace";
+var LANGSMITH_METADATA_BAGGAGE_KEY = "langsmith-metadata";
+function encodeBaggage(entries) {
+  return Object.entries(entries).filter((entry) => Boolean(entry[1])).map(([key, value]) => `${key}=${encodeURIComponent(value)}`).join(",");
+}
+function decodeBaggage(header) {
+  if (!header) return {};
+  const parsed = {};
+  for (const part of header.split(",")) {
+    const [rawKey, ...rest] = part.split("=");
+    if (!rawKey || rest.length === 0) continue;
+    const key = rawKey.trim();
+    let value;
+    try {
+      value = decodeURIComponent(rest.join("=").trim());
+    } catch (e) {
+      value = rest.join("=").trim();
+    }
+    if (key in parsed && parsed[key] !== value) throw new ConflictingCarrierError(key);
+    parsed[key] = value;
+  }
+  return parsed;
+}
+function carrierBaggage(carrier) {
+  return {
+    [BAGGAGE_KEYS.eventId]: carrier.eventId,
+    [BAGGAGE_KEYS.childEventId]: carrier.childEventId,
+    [BAGGAGE_KEYS.name]: carrier.name,
+    [BAGGAGE_KEYS.convoId]: carrier.convoId,
+    [BAGGAGE_KEYS.userId]: carrier.userId,
+    [BAGGAGE_KEYS.dispatchSpanId]: carrier.spanId,
+    [BAGGAGE_KEYS.traceId]: carrier.traceId
+  };
+}
+function toHeaders(carrier) {
+  const fields = encodeBaggage(carrierBaggage(carrier));
+  const headers = {
+    [BAGGAGE_HEADER]: fields,
+    [HANDOFF_HEADER]: fields
+  };
+  if (isW3CTraceId(carrier.traceId) && isW3CSpanId(carrier.spanId)) {
+    headers[TRACEPARENT_HEADER] = `00-${carrier.traceId}-${carrier.spanId}-01`;
+  }
+  return headers;
+}
+function langsmithStamp() {
+  return (/* @__PURE__ */ new Date()).toISOString().replace(/[-:]/g, "").replace(/\.\d+Z$/, "000000");
+}
+function toLangSmithHeaders(carrier) {
+  const stamp = langsmithStamp();
+  const dottedOrder = `${stamp}Z${carrier.traceId}.${stamp}Z${carrier.spanId}`;
+  return {
+    [LANGSMITH_TRACE_HEADER]: dottedOrder,
+    [BAGGAGE_HEADER]: encodeBaggage({
+      [LANGSMITH_METADATA_BAGGAGE_KEY]: JSON.stringify(carrierBaggage(carrier))
+    }),
+    // Carried here too: a LangSmith-shaped carrier is rewritten in transit
+    // exactly like the native one, and an injected `traceparent` is preferred
+    // over the dotted order on read.
+    [HANDOFF_HEADER]: encodeBaggage(carrierBaggage(carrier))
+  };
+}
+function isHeaderLookup(headers) {
+  return "get" in headers && typeof headers.get === "function";
+}
+var ConflictingCarrierError = class extends Error {
+};
+function readHeader(headers, name) {
+  var _a, _b, _c;
+  if (isHeaderLookup(headers)) return (_a = headers.get(name)) != null ? _a : void 0;
+  const value = (_c = headers[name]) != null ? _c : (_b = Object.entries(headers).find(([key]) => key.toLowerCase() === name)) == null ? void 0 : _b[1];
+  if (!Array.isArray(value)) return value;
+  const distinct = new Set(value);
+  if (distinct.size > 1) throw new ConflictingCarrierError(name);
+  return value[0];
+}
+function readTraceHeader(headers, name) {
+  const value = readHeader(headers, name);
+  if (!(value == null ? void 0 : value.includes(","))) return value;
+  const copies = value.split(",").map((copy) => copy.trim());
+  if (new Set(copies).size > 1) throw new ConflictingCarrierError(name);
+  return copies[0];
+}
+function fromHeaders(headers) {
+  var _a, _b;
+  let baggage;
+  let handoff;
+  let traceparent;
+  let langsmithTrace;
+  try {
+    baggage = decodeBaggage(readHeader(headers, BAGGAGE_HEADER));
+    handoff = decodeBaggage(readHeader(headers, HANDOFF_HEADER));
+    traceparent = readTraceHeader(headers, TRACEPARENT_HEADER);
+    langsmithTrace = readTraceHeader(headers, LANGSMITH_TRACE_HEADER);
+  } catch (error) {
+    if (error instanceof ConflictingCarrierError) return null;
+    throw error;
+  }
+  const langsmithMetadata = baggage[LANGSMITH_METADATA_BAGGAGE_KEY];
+  const nested = langsmithMetadata ? safeParseStringRecord(langsmithMetadata) : {};
+  for (const [key, value] of Object.entries(nested)) {
+    if (key in baggage && baggage[key] !== value) return null;
+  }
+  const fields = {
+    ...baggage,
+    ...nested,
+    // Last, so it wins: the standard headers may have been rewritten in transit
+    // by a propagator, this one is only ever written by us.
+    ...handoff
+  };
+  let traceId;
+  let spanId;
+  if (traceparent) {
+    const [, parsedTraceId, parsedSpanId] = traceparent.split("-");
+    if (isW3CTraceId(parsedTraceId) && isW3CSpanId(parsedSpanId)) {
+      traceId = parsedTraceId;
+      spanId = parsedSpanId;
+    }
+  }
+  if (!traceId && !spanId && langsmithTrace) {
+    const segments = langsmithTrace.split(".");
+    traceId = (_a = segments[0]) == null ? void 0 : _a.split("Z").pop();
+    spanId = (_b = segments[segments.length - 1]) == null ? void 0 : _b.split("Z").pop();
+  }
+  traceId = fields[BAGGAGE_KEYS.traceId] || traceId;
+  spanId = fields[BAGGAGE_KEYS.dispatchSpanId] || spanId;
+  const eventId = fields[BAGGAGE_KEYS.eventId];
+  if (!traceId || !spanId || !eventId) return null;
+  if (!isW3CTraceId(traceId) || !isW3CSpanId(spanId)) {
+    warnNonConformantIdsOnce(traceId, spanId);
+  }
+  const carrier = { traceId, spanId, eventId };
+  const childEventId = fields[BAGGAGE_KEYS.childEventId];
+  if (childEventId) carrier.childEventId = childEventId;
+  const name = fields[BAGGAGE_KEYS.name];
+  if (name) carrier.name = name;
+  const convoId = fields[BAGGAGE_KEYS.convoId];
+  if (convoId) carrier.convoId = convoId;
+  const userId = fields[BAGGAGE_KEYS.userId];
+  if (userId) carrier.userId = userId;
+  return carrier;
+}
+var UNRESOLVED_CARRIER_WARNING = `[raindrop] resume: headers were supplied but no hand-off carrier was found on them (searched ${HANDOFF_HEADER}, ${TRACEPARENT_HEADER}, ${BAGGAGE_HEADER}). This run reports as an UNLINKED event, and the launcher that dispatched it will stay on "queued" forever because nothing ever references its child. Passing headers means a parent handed off, so no carrier on them is almost certainly a defect: a gateway or proxy stripping ${HANDOFF_HEADER}, a middleware overwriting ${BAGGAGE_HEADER}, a request forwarded without its headers, or a hand-built carrier whose field names do not match. Send every header the launcher's dispatch returned. Logged once per process; pass no headers for a directly-invoked sub-agent to silence it.`;
+var UNRESOLVED_CARRIER_WARNED_KEY = /* @__PURE__ */ Symbol.for("raindrop.handoff.warnedUnresolvedCarrier");
+function warnedHolder() {
+  return globalThis;
+}
+function warnUnresolvedCarrier(headers, carrier) {
+  if (carrier) return;
+  if (!headers) return;
+  const holder = warnedHolder();
+  if (holder[UNRESOLVED_CARRIER_WARNED_KEY]) return;
+  holder[UNRESOLVED_CARRIER_WARNED_KEY] = true;
+  console.warn(UNRESOLVED_CARRIER_WARNING);
+}
+function safeParseStringRecord(raw) {
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return {};
+    const result = {};
+    for (const [key, value] of Object.entries(parsed)) {
+      if (typeof value === "string") result[key] = value;
+    }
+    return result;
+  } catch (e) {
+    return {};
+  }
+}
 function runWithTracingSuppressed(fn) {
   const hook = globalThis.RAINDROP_SUPPRESS_TRACING;
   if (typeof hook !== "function") return fn();
@@ -408,6 +695,62 @@ function projectIdHeaders(projectId) {
 }
 var SHUTDOWN_DEADLINE_MS = 1e4;
 var POST_SHUTDOWN_TIMEOUT_MS = 5e3;
+var MODEL_USAGE_ATTRIBUTES = {
+  providerName: "gen_ai.provider.name",
+  requestModel: "gen_ai.request.model",
+  responseModel: "gen_ai.response.model",
+  inputTokens: "gen_ai.usage.input_tokens",
+  outputTokens: "gen_ai.usage.output_tokens",
+  reasoningTokens: "gen_ai.usage.reasoning_tokens",
+  cacheReadInputTokens: "gen_ai.usage.cache_read_input_tokens",
+  cacheWriteInputTokens: "gen_ai.usage.cache_write_input_tokens",
+  nonCachedInputTokens: "raindrop.usage.input_tokens.non_cached",
+  nonReasoningOutputTokens: "raindrop.usage.output_tokens.non_reasoning",
+  totalOutputTokens: "raindrop.usage.output_tokens.total",
+  reasoningOutputTokens: "raindrop.usage.output_tokens.reasoning",
+  cacheReadTokens: "raindrop.usage.input_tokens.cache_read",
+  cacheWriteTokens: "raindrop.usage.input_tokens.cache_write"
+};
+var STRING_ALIASES = {
+  [MODEL_USAGE_ATTRIBUTES.requestModel]: ["ai.model.id", "ai.model"]
+};
+var NUMBER_ALIASES = {
+  [MODEL_USAGE_ATTRIBUTES.inputTokens]: [
+    "gen_ai.usage.prompt_tokens",
+    "ai.usage.prompt_tokens",
+    "ai.usage.promptTokens",
+    "ai.usage.input_tokens",
+    "ai.usage.inputTokens"
+  ],
+  [MODEL_USAGE_ATTRIBUTES.outputTokens]: [
+    "gen_ai.usage.completion_tokens",
+    "ai.usage.completion_tokens",
+    "ai.usage.completionTokens",
+    "ai.usage.output_tokens",
+    "ai.usage.outputTokens"
+  ],
+  [MODEL_USAGE_ATTRIBUTES.reasoningTokens]: [
+    "gen_ai.usage.reasoning.output_tokens",
+    "ai.usage.reasoningTokens",
+    "ai.usage.thoughts_tokens"
+  ],
+  [MODEL_USAGE_ATTRIBUTES.cacheReadInputTokens]: [
+    "gen_ai.usage.cache_read_tokens",
+    "gen_ai.usage.cache_read.input_tokens",
+    "ai.usage.cachedInputTokens",
+    "ai.usage.cached_tokens",
+    "ai.usage.cache_read_tokens",
+    "ai.usage.cache_read_input_tokens",
+    "ai.usage.cacheReadInputTokens"
+  ],
+  [MODEL_USAGE_ATTRIBUTES.cacheWriteInputTokens]: [
+    "gen_ai.usage.cache_creation_input_tokens",
+    "gen_ai.usage.cache_creation.input_tokens",
+    "ai.usage.cacheWriteInputTokens",
+    "ai.usage.cache_creation_input_tokens",
+    "ai.usage.cacheCreationInputTokens"
+  ]
+};
 var DEFAULT_REDACT_ATTRIBUTE_KEYS = [
   "ai.request.providerOptions",
   "ai.response.providerMetadata"
@@ -422,8 +765,10 @@ function getWeakRefCtor() {
 }
 var MAX_BINDING_STACK = 128;
 var EMPTY_STACK = [];
-var RoutingContextStorage = class {
-  constructor() {
+var ContextStackStorage = class {
+  /** Emitted once when this runtime cannot support an ambient push. */
+  constructor(noAmbientBindWarning) {
+    this.noAmbientBindWarning = noAmbientBindWarning;
     this._als = null;
     this._enterWithUsable = false;
     this._syncStack = EMPTY_STACK;
@@ -520,17 +865,17 @@ var RoutingContextStorage = class {
   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."
-    );
+    console.warn(this.noAmbientBindWarning);
   }
 };
+var NO_AMBIENT_ROUTING_BIND_WARNING = "[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 NO_AMBIENT_ATTRIBUTE_BIND_WARNING = "[raindrop] This runtime's AsyncLocalStorage does not implement enterWith (e.g. Cloudflare Workers), so contextual span attributes (the detached sub-agent hand-off reference) cannot be bound ambiently without cross-contaminating concurrent requests. The child's own event still reports; only the per-span reverse reference is skipped.";
 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();
+    storage = new ContextStackStorage(NO_AMBIENT_ROUTING_BIND_WARNING);
     holder[ROUTING_STORAGE_KEY] = storage;
   }
   return storage;
@@ -578,6 +923,104 @@ function currentRoutingBinding() {
 function isBoundContext(value) {
   return typeof value.isLive === "function";
 }
+var ATTRIBUTE_STORAGE_KEY = /* @__PURE__ */ Symbol.for("raindrop.tracing.spanAttributeStorage");
+function attributeStorage() {
+  const holder = globalThis;
+  let storage = holder[ATTRIBUTE_STORAGE_KEY];
+  if (!storage) {
+    storage = new ContextStackStorage(NO_AMBIENT_ATTRIBUTE_BIND_WARNING);
+    holder[ATTRIBUTE_STORAGE_KEY] = storage;
+  }
+  return storage;
+}
+function makeAttributeFrame(attributes, owner) {
+  const snapshot = { ...attributes };
+  const WeakRefCtor = owner !== void 0 ? getWeakRefCtor() : void 0;
+  const ref = WeakRefCtor && owner !== void 0 ? new WeakRefCtor(owner) : void 0;
+  const owned = /* @__PURE__ */ new WeakSet();
+  let dead = false;
+  let sawError = false;
+  return {
+    attributes: snapshot,
+    sawErrorSpan: () => sawError,
+    ownsSpan: (span) => owned.has(span),
+    claimSpan(span) {
+      owned.add(span);
+    },
+    markErrorSpanSeen() {
+      sawError = true;
+    },
+    // A frame whose owner has been collected is dead even though nothing
+    // unbound it: a run that never settles must not keep handing its reverse
+    // reference to whatever runs next on a reused context.
+    isLive() {
+      if (dead) return false;
+      return ref === void 0 || ref.deref() !== void 0;
+    },
+    markDead() {
+      dead = true;
+    }
+  };
+}
+function bindSpanAttributes(attributes, owner) {
+  if (Object.keys(attributes).length === 0) return void 0;
+  const frame = makeAttributeFrame(attributes, owner);
+  try {
+    attributeStorage().push(frame);
+  } catch (e) {
+    return void 0;
+  }
+  return frame;
+}
+function unbindSpanAttributes(frame) {
+  if (!frame || !isAttributeFrame(frame)) return;
+  try {
+    attributeStorage().remove(frame);
+  } catch (e) {
+  }
+}
+function applySpanAttributeFrames(span, setAttribute) {
+  try {
+    for (const frame of attributeStorage().getStack()) {
+      if (!frame.isLive()) continue;
+      frame.claimSpan(span);
+      for (const [key, value] of Object.entries(frame.attributes)) {
+        setAttribute(key, value);
+      }
+    }
+  } catch (e) {
+  }
+}
+function claimSpanForFrames(span) {
+  try {
+    for (const frame of attributeStorage().getStack()) {
+      if (frame.isLive()) frame.claimSpan(span);
+    }
+  } catch (e) {
+  }
+}
+function currentSpanAttributes() {
+  const merged = {};
+  try {
+    for (const frame of attributeStorage().getStack()) {
+      if (!frame.isLive()) continue;
+      Object.assign(merged, frame.attributes);
+    }
+  } catch (e) {
+  }
+  return merged;
+}
+function markErrorSpanSeen(span) {
+  try {
+    for (const frame of attributeStorage().getStack()) {
+      if (frame.ownsSpan(span)) frame.markErrorSpanSeen();
+    }
+  } catch (e) {
+  }
+}
+function isAttributeFrame(value) {
+  return typeof value.isLive === "function";
+}
 
 // ../core/dist/index.node.js
 var import_async_hooks = require("async_hooks");
@@ -701,12 +1144,12 @@ async function postJson2(url, body, headers, opts) {
 }
 
 // src/tracing/direct/ids.ts
-function getCrypto() {
+function getCrypto2() {
   const c = globalThis.crypto;
   return c;
 }
 function randomBytes2(length) {
-  const cryptoObj = getCrypto();
+  const cryptoObj = getCrypto2();
   const out = new Uint8Array(length);
   if (cryptoObj && typeof cryptoObj.getRandomValues === "function") {
     cryptoObj.getRandomValues(out);
@@ -744,7 +1187,7 @@ function base64Encode2(bytes) {
   }
   return out;
 }
-function base64ToHex(base64) {
+function base64ToHex2(base64) {
   const maybeBuffer = globalThis.Buffer;
   if (maybeBuffer) {
     return maybeBuffer.from(base64, "base64").toString("hex");
@@ -764,7 +1207,7 @@ function base64ToHex(base64) {
 // package.json
 var package_default = {
   name: "raindrop-ai",
-  version: "0.2.4",
+  version: "0.3.0",
   main: "dist/index.js",
   module: "dist/index.mjs",
   types: "dist/index.d.ts",
@@ -961,6 +1404,7 @@ var PROJECT_ID_SPAN_ATTRIBUTE = "raindrop.project_id";
 var AUTH_HINT_SPAN_ATTRIBUTE = "raindrop.auth_hint";
 var EXPORT_SUCCESS = 0;
 var EXPORT_FAILED = 1;
+var SPAN_STATUS_ERROR = 2;
 function authHintForKey(writeKey) {
   if (!writeKey) return void 0;
   return (0, import_node_crypto.createHash)("sha256").update(writeKey, "utf8").digest("hex").slice(0, 8);
@@ -1023,16 +1467,29 @@ function stampSpan(span, projectId, authHint) {
   } catch (e) {
   }
 }
+function stampContextAttributes(span) {
+  try {
+    applySpanAttributeFrames(span, (key, value) => span.setAttribute(key, value));
+  } catch (e) {
+  }
+}
 var RaindropContextSpanProcessor = class {
   onStart(span) {
     try {
+      stampContextAttributes(span);
       const bound = currentRoutingBinding();
       if (!bound) return;
       stampSpan(span, bound.projectId, bound.authHint);
     } catch (e) {
     }
   }
-  onEnd() {
+  onEnd(span) {
+    var _a;
+    try {
+      if (((_a = span == null ? void 0 : span.status) == null ? void 0 : _a.code) !== SPAN_STATUS_ERROR) return;
+      markErrorSpanSeen(span);
+    } catch (e) {
+    }
   }
   async forceFlush() {
   }
@@ -1211,9 +1668,18 @@ var DirectTraceShipper = class {
         attrString2(`traceloop.association.properties.${key}`, serializeAssociationValue(value))
       );
     }
+    const spanIdentity = { spanIdB64 };
+    claimSpanForFrames(spanIdentity);
+    for (const [key, value] of Object.entries({
+      ...currentSpanAttributes(),
+      ...params.attributes
+    })) {
+      attributes.push(attrString2(key, value));
+    }
     let status;
     if (params.error) {
       status = { code: 2, message: params.error };
+      markErrorSpanSeen(spanIdentity);
     } else {
       status = {
         code: 1
@@ -1362,18 +1828,305 @@ var DirectTraceShipper = class {
 };
 
 // src/tracing/liveInteraction.ts
-var import_api2 = require("@opentelemetry/api");
+var import_api3 = require("@opentelemetry/api");
 var traceloop = __toESM(require("@traceloop/node-server-sdk"));
-function getPropertiesFromContext(context5) {
+
+// src/tracing/subagents.ts
+var import_api2 = require("@opentelemetry/api");
+var DEFAULT_SUBAGENT_NAME = "subagent";
+var DISPATCH_ACCEPTED = "accepted";
+function reasonText(reason) {
+  var _a;
+  if (reason instanceof Error) return `${reason.name}: ${reason.message}`;
+  if (typeof reason === "string") return reason;
+  if (reason === void 0 || reason === null) return "";
+  try {
+    return (_a = JSON.stringify(reason)) != null ? _a : String(reason);
+  } catch (e) {
+    return String(reason);
+  }
+}
+function stampCurrentSpan(attributes) {
+  try {
+    const span = import_api2.trace.getSpan(import_api2.context.active());
+    if (!(span == null ? void 0 : span.isRecording())) return;
+    for (const [key, value] of Object.entries(attributes)) {
+      span.setAttribute(key, value);
+    }
+  } catch (e) {
+  }
+}
+function stampOwnSpan(attributes, frame) {
+  if (!frame) return;
+  try {
+    const span = import_api2.trace.getSpan(import_api2.context.active());
+    if (!(span == null ? void 0 : span.isRecording()) || !frame.ownsSpan(span)) return;
+    for (const [key, value] of Object.entries(attributes)) {
+      span.setAttribute(key, value);
+    }
+  } catch (e) {
+  }
+}
+function failOwnSpan(reason, frame) {
+  try {
+    const span = import_api2.trace.getSpan(import_api2.context.active());
+    if (!(span == null ? void 0 : span.isRecording())) return false;
+    if (!(frame == null ? void 0 : frame.ownsSpan(span))) return false;
+    const message = reasonText(reason);
+    span.setStatus({ code: import_api2.SpanStatusCode.ERROR, message });
+    span.recordException(reason instanceof Error ? reason : new Error(message));
+    return true;
+  } catch (e) {
+    return false;
+  }
+}
+function allowToolEvents(interaction) {
+  const attributes = withMetadataPrefix(toolEventsAllowMetadata());
+  interaction.bindToolEventsOptIn(attributes);
+  stampCurrentSpan(attributes);
+}
+function recordSubagentDispatch(interaction, options) {
+  var _a;
+  const childEventId = options.childEventId || randomUUID();
+  const name = options.name || DEFAULT_SUBAGENT_NAME;
+  const parentEventId = (_a = interaction.getEventId()) != null ? _a : "";
+  let traceIdHex;
+  let dispatchSpanId;
+  try {
+    allowToolEvents(interaction);
+    const recorded = interaction.recordDispatchSpan({
+      name: options.toolName || DEFAULT_DISPATCH_SPAN_NAME,
+      input: options.input,
+      // A launch's "result" is the job handle; the answer belongs to the
+      // child's event and never appears here.
+      output: { jobId: childEventId, status: DISPATCH_ACCEPTED },
+      properties: options.properties,
+      attributes: detachedDispatchMetadata({ childEventId, name })
+    });
+    traceIdHex = recorded.traceIdHex;
+    dispatchSpanId = recorded.spanIdHex;
+    if (!dispatchSpanId) {
+      console.warn(
+        `[raindrop] subagent(${name}): no dispatch span was recorded, so event ${parentEventId} will not show the launch and NO carrier is returned \u2014 there is no span for the child to reference. Pass childEventId (${childEventId}) to the worker yourself if it must still report under that id. Tracing must be enabled for dispatches to be recorded.`
+      );
+    }
+  } catch (error) {
+    console.warn(
+      `[raindrop] subagent(${name}) failed to record the dispatch; returning a carrier so the child still links back.`,
+      error instanceof Error ? error.message : error
+    );
+  }
+  if (!traceIdHex || !dispatchSpanId) {
+    return {
+      childEventId,
+      name,
+      parentEventId,
+      dispatchSpanId: void 0,
+      carrier: null,
+      headers: {},
+      langsmithHeaders: {}
+    };
+  }
+  const carrier = {
+    traceId: traceIdHex,
+    spanId: dispatchSpanId,
+    eventId: parentEventId,
+    childEventId,
+    name,
+    ...interaction.getConvoId() ? { convoId: interaction.getConvoId() } : {},
+    ...interaction.getUserId() ? { userId: interaction.getUserId() } : {}
+  };
+  return {
+    childEventId,
+    name,
+    parentEventId,
+    dispatchSpanId,
+    carrier,
+    headers: toHeaders(carrier),
+    langsmithHeaders: toLangSmithHeaders(carrier)
+  };
+}
+function carrierFirst(local, carried, field) {
+  if (carried && local && local !== carried) {
+    console.warn(
+      `[raindrop] resumeSubagent: ignoring ${field}="${local}" in favor of the launcher's "${carried}" from the carrier; the launcher allocated it, and a child that substitutes its own breaks the link back to it.`
+    );
+  }
+  return carried || local;
+}
+function isTraceCarrier(value) {
+  const candidate = value;
+  return typeof candidate.traceId === "string" && typeof candidate.spanId === "string" && typeof candidate.eventId === "string";
+}
+function readCarrier(carrierOrHeaders) {
+  if (!carrierOrHeaders) return null;
+  try {
+    if (isTraceCarrier(carrierOrHeaders)) return carrierOrHeaders;
+    return fromHeaders(carrierOrHeaders);
+  } catch (error) {
+    console.warn(
+      `[raindrop] resumeSubagent: ignoring an unreadable hand-off carrier; the run reports as an unlinked event.`,
+      error instanceof Error ? error.message : error
+    );
+    return null;
+  }
+}
+function resolveSubagentResume(carrierOrHeaders, options = {}) {
+  const parentStated = options.parent !== void 0;
+  const parent = parentStated ? options.parent : readCarrier(carrierOrHeaders);
+  if (!parentStated) warnUnresolvedCarrier(carrierOrHeaders, parent);
+  const name = carrierFirst(options.name, parent == null ? void 0 : parent.name, "name") || DEFAULT_SUBAGENT_NAME;
+  const eventId = carrierFirst(options.eventId, parent == null ? void 0 : parent.childEventId, "eventId") || randomUUID();
+  const userId = carrierFirst(options.userId, parent == null ? void 0 : parent.userId, "userId") || "";
+  const convoId = carrierFirst(options.convoId, parent == null ? void 0 : parent.convoId, "convoId");
+  const link = parent ? {
+    parentEventId: parent.eventId,
+    ...parent.spanId ? { parentSpanId: parent.spanId } : {},
+    name
+  } : null;
+  return {
+    parent,
+    link,
+    name,
+    eventId,
+    event: options.event || `subagent.${name}`,
+    userId,
+    ...convoId ? { convoId } : {}
+  };
+}
+function bindSubagentLink(link, owner) {
+  if (!link) return void 0;
+  return bindSpanAttributes(detachedChildMetadata(link), owner);
+}
+var LiveSubagentRun = class {
+  constructor(params) {
+    this.settled = false;
+    this.interaction = params.interaction;
+    this.eventId = params.eventId;
+    this.name = params.name;
+    this.convoId = params.convoId;
+    this.parent = params.parent;
+    this.frame = params.frame;
+    this.frameOwner = params.frameOwner;
+  }
+  get linked() {
+    return this.parent !== null;
+  }
+  async finish(result) {
+    await this.close(result);
+  }
+  async fail(reason) {
+    await this.abort(reason);
+  }
+  async cancel(reason) {
+    const text = reason === void 0 ? "cancelled by caller" : reasonText(reason);
+    const cancelled = cancelledTerminalAttributes();
+    stampOwnSpan(cancelled, this.frame);
+    await this.close({
+      output: `Cancelled: ${text}`,
+      // The caller's view of the child is its EVENT, not its spans, so the
+      // marker has to be a property of the event as well.
+      properties: { [HANDOFF_TERMINAL_PROPERTY_KEY]: HANDOFF_TERMINAL_CANCELLED }
+    });
+  }
+  /**
+   * Close the run with an abort reason, having first made sure the failure is
+   * visible on a span.
+   *
+   * A failure has to leave an errored span behind or it is derived as finished.
+   * Mark whatever is open; if nothing is and the child has not errored a span
+   * already, record one — the killed-before-it-reached-the-model case, which is
+   * much of what aborting is.
+   */
+  async abort(reason) {
+    var _a, _b, _c;
+    const text = reasonText(reason);
+    if (!this.settled && !failOwnSpan(reason, this.frame)) {
+      if (!((_a = this.frame) == null ? void 0 : _a.sawErrorSpan())) {
+        this.interaction.recordSubagentAbortSpan({
+          reason,
+          message: text,
+          attributes: {
+            [HANDOFF_ATTRIBUTE_SUFFIXES.name]: this.name,
+            // The name explicitly, not only via the frame: an UNLINKED run has
+            // no frame, and since the span is named for the operation
+            // (`ai.subagent.failed`) rather than the sub-agent, this attribute
+            // is the only thing left that says which sub-agent failed.
+            ...(_c = (_b = this.frame) == null ? void 0 : _b.attributes) != null ? _c : {}
+          }
+        });
+      }
+    }
+    await this.close({ output: text ? `Aborted: ${text}` : "Aborted before producing a result." });
+  }
+  async close(result) {
+    if (this.settled) return;
+    this.settled = true;
+    try {
+      await this.interaction.finish({ ...result, eventId: this.eventId });
+    } finally {
+      unbindSpanAttributes(this.frame);
+      this.frame = void 0;
+      this.frameOwner = void 0;
+    }
+  }
+  /**
+   * Run `fn` and guarantee the run reports an outcome, mirroring the Python
+   * SDK's `with rd.resume_subagent(...) as run:`.
+   *
+   * A run that leaves without reporting output is closed with its abort reason.
+   * That is not cosmetic: an event is created only from a run with non-empty
+   * output, so a child that dies silently produces no event at all and the
+   * caller's launch stays `queued` forever — indistinguishable from a job that
+   * never started.
+   */
+  async use(fn) {
+    try {
+      const result = await fn(this);
+      if (!this.settled) {
+        console.warn(
+          `[raindrop] sub-agent run ${this.eventId} (${this.name}) ended without reporting output; closing it with an abort reason. An event needs non-empty output to exist, so a silent child leaves its launcher showing "queued" forever \u2014 call finish({ output }), fail(reason) or cancel() before returning.`
+        );
+        await this.abortQuietly("sub-agent ended without reporting output");
+      }
+      return result;
+    } catch (error) {
+      await this.abortQuietly(error);
+      throw error;
+    }
+  }
+  /**
+   * {@link abort} for the outcomes this class reports on the caller's behalf.
+   *
+   * `abort()` ends in `interaction.finish()`, which awaits the terminal event
+   * POST and rejects when it fails. An explicit `fail()` may surface that — the
+   * caller awaited it — but an implicit one must not: rejecting on the error
+   * path replaces the caller's exception with a telemetry one, and rejecting on
+   * the success path loses a result `fn` already produced.
+   */
+  async abortQuietly(reason) {
+    try {
+      await this.abort(reason);
+    } catch (error) {
+      console.warn(
+        `[raindrop] sub-agent run ${this.eventId} (${this.name}) could not report its outcome; the run itself is unaffected.`,
+        error instanceof Error ? error.message : error
+      );
+    }
+  }
+};
+
+// src/tracing/liveInteraction.ts
+function getPropertiesFromContext(context6) {
   const properties = {
-    ...context5.userId && { user_id: context5.userId },
-    ...context5.convoId && { convo_id: context5.convoId },
-    ...context5.eventId && { event_id: context5.eventId },
-    ...context5.event && { event_name: context5.event },
-    ...context5.properties || {}
+    ...context6.userId && { user_id: context6.userId },
+    ...context6.convoId && { convo_id: context6.convoId },
+    ...context6.eventId && { event_id: context6.eventId },
+    ...context6.event && { event_name: context6.event },
+    ...context6.properties || {}
   };
-  if (context5.attachments && context5.attachments.length > 0) {
-    properties.attachments = stringifyBounded(context5.attachments);
+  if (context6.attachments && context6.attachments.length > 0) {
+    properties.attachments = stringifyBounded(context6.attachments);
   }
   return properties;
 }
@@ -1393,12 +2146,12 @@ function serializeAssociationProperties(properties) {
 function serializeSpanValue(value) {
   return stringifyBounded(value);
 }
-function getLocalDebuggerMetadata(context5) {
+function getLocalDebuggerMetadata(context6) {
   return {
-    ...context5.eventId ? { eventId: context5.eventId } : {},
-    ...context5.event ? { eventName: context5.event } : {},
-    ...context5.userId ? { userId: context5.userId } : {},
-    ...context5.convoId ? { convoId: context5.convoId } : {}
+    ...context6.eventId ? { eventId: context6.eventId } : {},
+    ...context6.event ? { eventName: context6.event } : {},
+    ...context6.userId ? { userId: context6.userId } : {},
+    ...context6.convoId ? { convoId: context6.convoId } : {}
   };
 }
 var LiveToolSpan = class {
@@ -1410,7 +2163,7 @@ var LiveToolSpan = class {
   }
   spanIdHex() {
     const ctx = this.span.spanContext();
-    return (0, import_api2.isValidSpanId)(ctx.spanId) ? ctx.spanId : void 0;
+    return (0, import_api3.isValidSpanId)(ctx.spanId) ? ctx.spanId : void 0;
   }
   setInput(input) {
     this.span.setAttribute("traceloop.entity.input", serializeSpanValue(input));
@@ -1422,13 +2175,13 @@ var LiveToolSpan = class {
   setError(error) {
     this.hasError = true;
     this.errorMessage = error instanceof Error ? error.message : String(error);
-    this.span.setStatus({ code: import_api2.SpanStatusCode.ERROR, message: this.errorMessage });
+    this.span.setStatus({ code: import_api3.SpanStatusCode.ERROR, message: this.errorMessage });
     this.span.recordException(error instanceof Error ? error : new Error(this.errorMessage));
   }
   end() {
     var _a;
     if (!this.hasError) {
-      this.span.setStatus({ code: import_api2.SpanStatusCode.OK });
+      this.span.setStatus({ code: import_api3.SpanStatusCode.OK });
     }
     this.span.end();
     (_a = this.emitLiveEvent) == null ? void 0 : _a.call(this, {
@@ -1499,10 +2252,10 @@ var DirectToolSpan = class {
   }
 };
 var LiveInteraction = class {
-  constructor(context5, traceId, analytics, directShipper, routing) {
-    this.context = context5;
+  constructor(context6, traceId, analytics, directShipper, routing) {
+    this.context = context6;
     this.analytics = analytics;
-    this.tracer = import_api2.trace.getTracer("traceloop.tracer");
+    this.tracer = import_api3.trace.getTracer("traceloop.tracer");
     this.traceId = traceId;
     this.directShipper = directShipper;
     this.routing = routing;
@@ -1537,7 +2290,7 @@ var LiveInteraction = class {
       this.traceId = explicitTraceId;
       return explicitTraceId;
     }
-    const activeSpan = import_api2.trace.getSpan(import_api2.context.active());
+    const activeSpan = import_api3.trace.getSpan(import_api3.context.active());
     const activeTraceId = activeSpan == null ? void 0 : activeSpan.spanContext().traceId;
     if (activeTraceId) {
       this.traceId = activeTraceId;
@@ -1580,17 +2333,17 @@ var LiveInteraction = class {
       const spanIdB64 = base64Encode2(randomBytes2(8));
       const startTimeMs = Date.now();
       const spanContext = {
-        traceId: base64ToHex(traceIdB64),
-        spanId: base64ToHex(spanIdB64),
-        traceFlags: import_api2.TraceFlags.SAMPLED
+        traceId: base64ToHex2(traceIdB64),
+        spanId: base64ToHex2(spanIdB64),
+        traceFlags: import_api3.TraceFlags.SAMPLED
       };
-      const wrappedContext = import_api2.trace.setSpan(
-        import_api2.context.active(),
-        import_api2.trace.wrapSpanContext(spanContext)
+      const wrappedContext = import_api3.trace.setSpan(
+        import_api3.context.active(),
+        import_api3.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, invoke);
+        const result = await import_api3.context.with(wrappedContext, invoke);
         const endTimeMs = Date.now();
         this.directShipper.sendSpan({
           name: taskName,
@@ -1625,7 +2378,7 @@ var LiveInteraction = class {
       }
     }
     const wrappedFn = (...fnArgs) => {
-      const activeSpan = import_api2.trace.getSpan(import_api2.context.active());
+      const activeSpan = import_api3.trace.getSpan(import_api3.context.active());
       const activeTraceId = activeSpan == null ? void 0 : activeSpan.spanContext().traceId;
       if (activeTraceId) {
         this.traceId = activeTraceId;
@@ -1675,19 +2428,19 @@ var LiveInteraction = class {
         metadata: params.inputParameters ? { args: params.inputParameters } : void 0
       });
       const spanContext = {
-        traceId: base64ToHex(traceIdB64),
-        spanId: base64ToHex(spanIdB64),
-        traceFlags: import_api2.TraceFlags.SAMPLED
+        traceId: base64ToHex2(traceIdB64),
+        spanId: base64ToHex2(spanIdB64),
+        traceFlags: import_api3.TraceFlags.SAMPLED
       };
-      const wrappedContext = import_api2.trace.setSpan(
-        import_api2.context.active(),
-        import_api2.trace.wrapSpanContext(spanContext)
+      const wrappedContext = import_api3.trace.setSpan(
+        import_api3.context.active(),
+        import_api3.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, invoke);
+        result = await import_api3.context.with(wrappedContext, invoke);
       } catch (err) {
         error = err instanceof Error ? err.message : String(err);
         const endTimeMs2 = Date.now();
@@ -1752,9 +2505,9 @@ var LiveInteraction = class {
     const inputParams = params.inputParameters ? [params.inputParameters] : void 0;
     const emitLive = (event) => this.emitLiveEvent(event);
     const wrapped = async (...wrappedArgs) => {
-      const activeSpan = import_api2.trace.getSpan(import_api2.context.active());
+      const activeSpan = import_api3.trace.getSpan(import_api3.context.active());
       const ctx = activeSpan == null ? void 0 : activeSpan.spanContext();
-      const liveSpanId = ctx && (0, import_api2.isValidSpanId)(ctx.spanId) ? ctx.spanId : void 0;
+      const liveSpanId = ctx && (0, import_api3.isValidSpanId)(ctx.spanId) ? ctx.spanId : void 0;
       if (activeSpan) {
         this.stampRouting(activeSpan);
       }
@@ -1862,7 +2615,7 @@ var LiveInteraction = class {
       console.log(`[raindrop] startToolSpan: started tool span "${name}"`);
     }
     const startSpanCtx = span.spanContext();
-    const startSpanIdHex = (0, import_api2.isValidSpanId)(startSpanCtx.spanId) ? startSpanCtx.spanId : void 0;
+    const startSpanIdHex = (0, import_api3.isValidSpanId)(startSpanCtx.spanId) ? startSpanCtx.spanId : void 0;
     this.emitLiveEvent({
       type: "tool_start",
       spanId: startSpanIdHex,
@@ -1955,10 +2708,151 @@ var LiveInteraction = class {
   getEventId() {
     return this.context.eventId;
   }
+  getUserId() {
+    return this.context.userId;
+  }
+  getConvoId() {
+    return this.context.convoId;
+  }
+  /**
+   * Bind this turn's tool-call event opt-in, once.
+   *
+   * Owned by the interaction rather than by the execution context: the frame
+   * lives exactly as long as the turn does (removed by `finish()`, and dead once
+   * this interaction is collected), instead of outliving it on a context the
+   * host may reuse for unrelated work.
+   */
+  bindToolEventsOptIn(attributes) {
+    if (this.toolEventsFrame) return;
+    this.toolEventsFrame = bindSpanAttributes(attributes, this);
+  }
+  subagent(options) {
+    return recordSubagentDispatch(this, options);
+  }
+  /**
+   * Record the tool span a detached dispatch is written on.
+   *
+   * Distinct from {@link startToolSpan} in the two ways the hand-off needs:
+   * the contract's keys are set as RAW span attributes (under the
+   * `traceloop.association.properties.` prefix the backend's reader cannot see
+   * them), and the caller needs the span's ids to build the carrier.
+   *
+   * @internal
+   */
+  recordDispatchSpan(params) {
+    var _a;
+    const properties = {
+      ...getPropertiesFromContext(this.context),
+      ...(_a = params.properties) != null ? _a : {}
+    };
+    const input = params.input !== void 0 ? serializeSpanValue(params.input) : void 0;
+    const output = serializeSpanValue(params.output);
+    if (this.directShipper) {
+      const activeContext = getActiveTraceContext();
+      const traceIdB64 = this.ensureTraceId(activeContext.traceIdB64);
+      const spanIdB64 = base64Encode2(randomBytes2(8));
+      const timeMs = Date.now();
+      this.directShipper.sendToolSpan({
+        name: params.name,
+        spanId: spanIdB64,
+        input,
+        output,
+        durationMs: 0,
+        startTimeMs: timeMs,
+        endTimeMs: timeMs,
+        properties,
+        traceId: traceIdB64,
+        parentSpanId: activeContext.parentSpanIdB64,
+        attributes: params.attributes
+      });
+      this.emitLiveEvent({
+        traceId: traceIdB64,
+        spanId: spanIdB64,
+        type: "tool_result",
+        content: params.name,
+        timestamp: timeMs,
+        metadata: { result: params.output }
+      });
+      return { traceIdHex: base64ToHex2(traceIdB64), spanIdHex: base64ToHex2(spanIdB64) };
+    }
+    const span = this.tracer.startSpan(params.name);
+    setAssociationProperties(span, properties);
+    span.setAttribute("traceloop.span.kind", "tool");
+    this.stampRouting(span);
+    for (const [key, value] of Object.entries(params.attributes)) {
+      span.setAttribute(key, value);
+    }
+    if (input !== void 0) {
+      span.setAttribute("traceloop.entity.input", input);
+    }
+    span.setAttribute("traceloop.entity.output", output);
+    span.setStatus({ code: import_api3.SpanStatusCode.OK });
+    const spanContext = span.spanContext();
+    span.end();
+    this.emitLiveEvent({
+      spanId: (0, import_api3.isValidSpanId)(spanContext.spanId) ? spanContext.spanId : void 0,
+      type: "tool_result",
+      content: params.name,
+      timestamp: Date.now(),
+      metadata: { result: params.output }
+    });
+    return {
+      traceIdHex: (0, import_api3.isValidTraceId)(spanContext.traceId) ? spanContext.traceId : void 0,
+      spanIdHex: (0, import_api3.isValidSpanId)(spanContext.spanId) ? spanContext.spanId : void 0
+    };
+  }
+  /**
+   * Record the errored span a detached sub-agent's failure needs when nothing
+   * else is open.
+   *
+   * Frequently the child's ONLY span, so it carries the full reverse reference:
+   * anything reading it alone still knows which launch it belongs to. Those
+   * attributes come from the run's own frame rather than the ambient stack,
+   * because `fail()` is often called from a different task than the one that
+   * opened the run and this is the span that can least afford to lose the link.
+   *
+   * @internal
+   */
+  recordSubagentAbortSpan(params) {
+    const { reason, message, attributes } = params;
+    const properties = getPropertiesFromContext(this.context);
+    if (this.directShipper) {
+      const activeContext = getActiveTraceContext();
+      const timeMs = Date.now();
+      this.directShipper.sendSpan({
+        name: SUBAGENT_ABORT_SPAN_NAME,
+        // Not "tool": the run died, it did not call anything. `ai.operationId`
+        // below is what keeps the span (see the attribute's docs in core).
+        spanKind: "task",
+        spanId: base64Encode2(randomBytes2(8)),
+        durationMs: 0,
+        startTimeMs: timeMs,
+        endTimeMs: timeMs,
+        error: message,
+        properties,
+        traceId: this.ensureTraceId(activeContext.traceIdB64),
+        parentSpanId: activeContext.parentSpanIdB64,
+        attributes: { ...attributes, [OPERATION_ID_ATTRIBUTE]: SUBAGENT_ABORT_OPERATION_ID }
+      });
+      return;
+    }
+    const span = this.tracer.startSpan(SUBAGENT_ABORT_SPAN_NAME);
+    span.setAttribute(OPERATION_ID_ATTRIBUTE, SUBAGENT_ABORT_OPERATION_ID);
+    setAssociationProperties(span, properties);
+    this.stampRouting(span);
+    for (const [key, value] of Object.entries(attributes)) {
+      span.setAttribute(key, value);
+    }
+    span.setStatus({ code: import_api3.SpanStatusCode.ERROR, message });
+    span.recordException(reason instanceof Error ? reason : new Error(message));
+    span.end();
+  }
   async finish(resultEvent) {
     var _a, _b, _c, _d;
     unbindRoutingContext(this.boundContext);
     this.boundContext = void 0;
+    unbindSpanAttributes(this.toolEventsFrame);
+    this.toolEventsFrame = void 0;
     if (!this.traceId) {
       this.resolveLiveTraceId();
     }
@@ -2068,10 +2962,10 @@ var LiveInteraction = class {
     }
     if (error) {
       const errorMessage = error instanceof Error ? error.message : String(error);
-      span.setStatus({ code: import_api2.SpanStatusCode.ERROR, message: errorMessage });
+      span.setStatus({ code: import_api3.SpanStatusCode.ERROR, message: errorMessage });
       span.recordException(error instanceof Error ? error : new Error(errorMessage));
     } else {
-      span.setStatus({ code: import_api2.SpanStatusCode.OK });
+      span.setStatus({ code: import_api3.SpanStatusCode.OK });
     }
     span.end(endTimeMs);
     if ((_c = this.analytics) == null ? void 0 : _c.debugLogs) {
@@ -2083,7 +2977,7 @@ var LiveInteraction = class {
       });
     }
     const trackToolCtx = span.spanContext();
-    const trackToolSpanIdHex = (0, import_api2.isValidSpanId)(trackToolCtx.spanId) ? trackToolCtx.spanId : void 0;
+    const trackToolSpanIdHex = (0, import_api3.isValidSpanId)(trackToolCtx.spanId) ? trackToolCtx.spanId : void 0;
     this.emitLiveEvent({
       type: "tool_result",
       spanId: trackToolSpanIdHex,
@@ -2099,11 +2993,11 @@ var LiveInteraction = class {
 };
 
 // src/tracing/liveTracer.ts
-var import_api3 = require("@opentelemetry/api");
+var import_api4 = require("@opentelemetry/api");
 var traceloop2 = __toESM(require("@traceloop/node-server-sdk"));
 var LiveTracer = class {
   constructor(globalProperties, directShipper, routing) {
-    this.tracer = import_api3.trace.getTracer("traceloop.tracer");
+    this.tracer = import_api4.trace.getTracer("traceloop.tracer");
     this.globalProperties = globalProperties || {};
     this.directShipper = directShipper;
     this.routing = routing;
@@ -2115,7 +3009,7 @@ var LiveTracer = class {
   }
   emitLiveEvent(event) {
     var _a, _b;
-    const activeSpan = import_api3.trace.getSpan(import_api3.context.active());
+    const activeSpan = import_api4.trace.getSpan(import_api4.context.active());
     const activeTraceId = activeSpan == null ? void 0 : activeSpan.spanContext().traceId;
     const active = getActiveTraceContext();
     const traceId = (_b = (_a = event.traceId) != null ? _a : activeTraceId) != null ? _b : active.traceIdB64;
@@ -2135,7 +3029,7 @@ var LiveTracer = class {
     };
     const inputParameters = typeof params === "string" ? void 0 : params.inputParameters;
     const wrappedFn = (...fnArgs) => {
-      const activeSpan = import_api3.trace.getSpan(import_api3.context.active());
+      const activeSpan = import_api4.trace.getSpan(import_api4.context.active());
       if (activeSpan) {
         this.stampRouting(activeSpan);
       }
@@ -2230,15 +3124,15 @@ var LiveTracer = class {
     }
     if (error) {
       const errorMessage = error instanceof Error ? error.message : String(error);
-      span.setStatus({ code: import_api3.SpanStatusCode.ERROR, message: errorMessage });
+      span.setStatus({ code: import_api4.SpanStatusCode.ERROR, message: errorMessage });
       span.recordException(error instanceof Error ? error : new Error(errorMessage));
     } else {
-      span.setStatus({ code: import_api3.SpanStatusCode.OK });
+      span.setStatus({ code: import_api4.SpanStatusCode.OK });
     }
     span.end(endTimeMs);
     const ctx = span.spanContext();
-    const traceId = ctx.traceId || ((_b = import_api3.trace.getSpan(import_api3.context.active())) == null ? void 0 : _b.spanContext().traceId);
-    const spanIdHex = (0, import_api3.isValidSpanId)(ctx.spanId) ? ctx.spanId : void 0;
+    const traceId = ctx.traceId || ((_b = import_api4.trace.getSpan(import_api4.context.active())) == null ? void 0 : _b.spanContext().traceId);
+    const spanIdHex = (0, import_api4.isValidSpanId)(ctx.spanId) ? ctx.spanId : void 0;
     if (traceId) {
       this.emitLiveEvent({
         traceId,
@@ -2530,7 +3424,7 @@ try {
             e instanceof Error ? e.message : e
           );
           span.setStatus({
-            code: import_api4.SpanStatusCode.ERROR,
+            code: import_api5.SpanStatusCode.ERROR,
             message: e instanceof Error ? e.message : String(e)
           });
           span.end();
@@ -2562,7 +3456,7 @@ try {
                     );
                     if (!spanEnded) {
                       span.setStatus({
-                        code: import_api4.SpanStatusCode.ERROR,
+                        code: import_api5.SpanStatusCode.ERROR,
                         message: e instanceof Error ? e.message : String(e)
                       });
                       span.end();
@@ -2576,7 +3470,7 @@ try {
               } catch (error) {
                 if (!spanEnded) {
                   const msg = error instanceof Error ? error.message : String(error);
-                  span.setStatus({ code: import_api4.SpanStatusCode.ERROR, message: msg });
+                  span.setStatus({ code: import_api5.SpanStatusCode.ERROR, message: msg });
                   span.recordException(error);
                   span.end();
                   spanEnded = true;
@@ -2599,7 +3493,7 @@ try {
       return result;
     }).catch((error) => {
       span.setStatus({
-        code: import_api4.SpanStatusCode.ERROR,
+        code: import_api5.SpanStatusCode.ERROR,
         message: error.message
       });
       span.recordException(error);
@@ -2662,7 +3556,7 @@ function patchBedrockStreamingBug(inst) {
               } catch (error) {
                 if (!spanEnded) {
                   const msg = error instanceof Error ? error.message : String(error);
-                  span.setStatus({ code: import_api4.SpanStatusCode.ERROR, message: msg });
+                  span.setStatus({ code: import_api5.SpanStatusCode.ERROR, message: msg });
                   span.recordException(error);
                   span.end();
                   spanEnded = true;
@@ -2685,7 +3579,7 @@ function patchBedrockStreamingBug(inst) {
       return result;
     }).catch((error) => {
       span.setStatus({
-        code: import_api4.SpanStatusCode.ERROR,
+        code: import_api5.SpanStatusCode.ERROR,
         message: error.message
       });
       span.recordException(error);
@@ -2767,7 +3661,7 @@ function createManualInstrumentations(instrumentModules) {
 }
 function getCurrentTraceId() {
   var _a;
-  return (_a = import_api4.trace.getSpan(import_api4.context.active())) == null ? void 0 : _a.spanContext().traceId;
+  return (_a = import_api5.trace.getSpan(import_api5.context.active())) == null ? void 0 : _a.spanContext().traceId;
 }
 var tracing = (analytics, apiUrl, writeKey, options, isDebug = false) => {
   var _a;
@@ -2960,6 +3854,72 @@ var tracing = (analytics, apiUrl, writeKey, options, isDebug = false) => {
     } catch (e) {
     }
   }) : void 0;
+  const beginInteraction = (traceContext) => {
+    var _a2;
+    if (!traceContext.eventId) {
+      traceContext.eventId = crypto.randomUUID();
+    }
+    const traceId = getCurrentTraceId();
+    const interaction = new LiveInteraction(
+      traceContext,
+      traceId,
+      analytics,
+      directShipper,
+      { projectId, authHint }
+    );
+    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);
+      }
+      activeInteractionsByEventId.set(traceContext.eventId, interaction);
+    } catch (error) {
+      unbindRoutingContext(bound);
+      throw error;
+    }
+    return interaction;
+  };
+  const openSubagentRun = (carrierOrHeaders, options2) => {
+    const resolved = resolveSubagentResume(carrierOrHeaders, options2);
+    if (!resolved.parent && isDebug) {
+      console.log(
+        `[raindrop] resumeSubagent(${resolved.name}): no hand-off carrier on the request; reporting as an unlinked event ${resolved.eventId}.`
+      );
+    }
+    const frameOwner = { subagentEventId: resolved.eventId };
+    const frame = bindSubagentLink(resolved.link, frameOwner);
+    let interaction;
+    try {
+      interaction = beginInteraction({
+        eventId: resolved.eventId,
+        event: resolved.event,
+        userId: resolved.userId,
+        ...resolved.convoId ? { convoId: resolved.convoId } : {},
+        ...options2.input !== void 0 ? { input: options2.input } : {},
+        ...options2.model !== void 0 ? { model: options2.model } : {},
+        ...options2.properties ? { properties: options2.properties } : {}
+      });
+    } catch (error) {
+      unbindSpanAttributes(frame);
+      throw error;
+    }
+    return new LiveSubagentRun({
+      interaction,
+      eventId: resolved.eventId,
+      name: resolved.name,
+      ...resolved.convoId ? { convoId: resolved.convoId } : {},
+      parent: resolved.link,
+      ...frame ? { frame, frameOwner } : {}
+    });
+  };
   return {
     /**
      * Returns instrumentation instances for your NodeSDK.
@@ -3069,37 +4029,13 @@ var tracing = (analytics, apiUrl, writeKey, options, isDebug = false) => {
       );
     },
     begin(traceContext) {
-      var _a2;
-      if (!traceContext.eventId) {
-        traceContext.eventId = crypto.randomUUID();
-      }
-      const traceId = getCurrentTraceId();
-      const interaction = new LiveInteraction(
-        traceContext,
-        traceId,
-        analytics,
-        directShipper,
-        { projectId, authHint }
-      );
-      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);
-        }
-        activeInteractionsByEventId.set(traceContext.eventId, interaction);
-      } catch (error) {
-        unbindRoutingContext(bound);
-        throw error;
-      }
-      return interaction;
+      return beginInteraction(traceContext);
+    },
+    resumeSubagent(carrierOrHeaders, options2 = {}) {
+      return openSubagentRun(carrierOrHeaders, options2);
+    },
+    withSubagentRun(carrierOrHeaders, fn, options2 = {}) {
+      return openSubagentRun(carrierOrHeaders, options2).use(fn);
     },
     getActiveInteraction(eventId) {
       const interactionByEventId = activeInteractionsByEventId.get(eventId);