@raindrop-ai/ai-sdk 0.2.1 → 0.3.1

package/dist/index.node.js

@@ -4,7 +4,7 @@ var async_hooks = require('async_hooks');
 
 // src/index.node.ts
 
-// ../core/dist/chunk-QNWZIOOY.js
+// ../core/dist/chunk-3V4MIA75.js
 function normalizeFeatureFlags(input) {
   if (Array.isArray(input)) {
     return Object.fromEntries(input.map((name) => [name, "true"]));
@@ -67,6 +67,311 @@ function base64Encode(bytes) {
   }
   return out;
 }
+function base64ToHex(value) {
+  if (!value) return "";
+  const maybeBuffer = globalThis.Buffer;
+  if (maybeBuffer) {
+    return maybeBuffer.from(value, "base64").toString("hex");
+  }
+  const atobFn = globalThis.atob;
+  if (typeof atobFn !== "function") return "";
+  try {
+    const binary = atobFn(value);
+    let hex = "";
+    for (let i = 0; i < binary.length; i++) {
+      hex += (binary.charCodeAt(i) & 255).toString(16).padStart(2, "0");
+    }
+    return hex;
+  } catch (e) {
+    return "";
+  }
+}
+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 HANDOFF_ATTRIBUTE_PREFIXES = [
+  "ai.telemetry.metadata.",
+  "ai.settings.context.",
+  ""
+];
+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 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;
+}
+function readHandoffField(metadata, suffix) {
+  for (const prefix of HANDOFF_ATTRIBUTE_PREFIXES) {
+    const value = metadata[`${prefix}${suffix}`];
+    if (typeof value === "string" && value.trim().length > 0) return value.trim();
+  }
+  return void 0;
+}
+function readDetachedChildLink(metadata) {
+  if (!metadata) return void 0;
+  const parentEventId = readHandoffField(metadata, HANDOFF_ATTRIBUTE_SUFFIXES.parentEventId);
+  if (!parentEventId) return void 0;
+  return {
+    parentEventId,
+    parentSpanId: readHandoffField(metadata, HANDOFF_ATTRIBUTE_SUFFIXES.parentSpanId),
+    name: readHandoffField(metadata, HANDOFF_ATTRIBUTE_SUFFIXES.name)
+  };
+}
+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 resetUnresolvedCarrierWarning() {
+  warnedHolder()[UNRESOLVED_CARRIER_WARNED_KEY] = false;
+}
+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();
@@ -831,6 +1136,7 @@ var EventShipper = class {
   }
 };
 var MODEL_USAGE_ATTRIBUTES = {
+  usageSource: "raindrop.usage.source",
   providerName: "gen_ai.provider.name",
   requestModel: "gen_ai.request.model",
   responseModel: "gen_ai.response.model",
@@ -839,20 +1145,22 @@ var MODEL_USAGE_ATTRIBUTES = {
   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",
-  reasoningOutputTokens: "raindrop.usage.output_tokens.reasoning",
-  cacheReadTokens: "raindrop.usage.input_tokens.cache_read",
-  cacheWriteTokens: "raindrop.usage.input_tokens.cache_write"
-};
+  providerReportedCost: "gen_ai.usage.provider_reported_cost"};
 var MODEL_PROVIDER_NAMES = [
+  ["google.vertex.anthropic", "google-vertex"],
+  ["google.vertex_ai", "google-vertex"],
   ["google.vertex", "google-vertex"],
+  ["gcp.vertex_ai", "google-vertex"],
+  ["gcp.gemini", "google"],
+  ["google_vertexai", "google-vertex"],
   ["vertex.anthropic", "google-vertex"],
   ["amazon-bedrock", "amazon-bedrock"],
+  ["aws.bedrock", "amazon-bedrock"],
   ["bedrock", "amazon-bedrock"],
   ["anthropic", "anthropic"],
   ["openai", "openai"],
   ["google", "google"],
+  ["az.ai.openai", "azure"],
   ["azure", "azure"],
   ["openrouter", "openrouter"]
 ];
@@ -863,60 +1171,20 @@ function canonicalModelProvider(provider) {
   const match = MODEL_PROVIDER_NAMES.find(
     ([family]) => normalizedProvider === family || normalizedProvider.startsWith(`${family}.`)
   );
-  return (_a = match == null ? void 0 : match[1]) != null ? _a : provider;
+  return (_a = match == null ? void 0 : match[1]) != null ? _a : normalizedProvider;
 }
 function tokenCount(value) {
   return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : void 0;
 }
-function exclusiveTokens({
-  explicit,
-  total,
-  parts,
-  semantics
-}) {
-  if (explicit !== void 0) return explicit;
-  if (total === void 0) return void 0;
-  if (semantics === "exclusive") return total;
-  const observedParts = parts.filter((part) => part !== void 0 && part > 0);
-  if (semantics === void 0 && observedParts.length > 0) return void 0;
-  const exclusive = total - observedParts.reduce((sum, part) => sum + part, 0);
-  return exclusive >= 0 ? exclusive : void 0;
-}
-function buildModelUsageAttributes(usage) {
-  const inputTokens = tokenCount(usage.inputTokens);
-  const outputTokens = tokenCount(usage.outputTokens);
-  const explicitNonCachedInputTokens = tokenCount(usage.nonCachedInputTokens);
-  const explicitNonReasoningOutputTokens = tokenCount(usage.nonReasoningOutputTokens);
-  const reasoningTokens = tokenCount(usage.reasoningTokens);
-  const cacheReadInputTokens = tokenCount(usage.cacheReadInputTokens);
-  const cacheWriteInputTokens = tokenCount(usage.cacheWriteInputTokens);
-  const nonCachedInputTokens = exclusiveTokens({
-    explicit: explicitNonCachedInputTokens,
-    total: inputTokens,
-    parts: [cacheReadInputTokens, cacheWriteInputTokens],
-    semantics: usage.inputTokenSemantics
-  });
-  const nonReasoningOutputTokens = exclusiveTokens({
-    explicit: explicitNonReasoningOutputTokens,
-    total: outputTokens,
-    parts: [reasoningTokens],
-    semantics: usage.outputTokenSemantics
-  });
-  const exclusivePoolAttributes = nonCachedInputTokens !== void 0 && nonReasoningOutputTokens !== void 0 ? [
-    // backend consumes this complete raindrop.* set as one atomic billing-pool contract.
-    attrInt(MODEL_USAGE_ATTRIBUTES.nonCachedInputTokens, nonCachedInputTokens),
-    attrInt(MODEL_USAGE_ATTRIBUTES.nonReasoningOutputTokens, nonReasoningOutputTokens),
-    attrInt(MODEL_USAGE_ATTRIBUTES.reasoningOutputTokens, reasoningTokens),
-    attrInt(MODEL_USAGE_ATTRIBUTES.cacheReadTokens, cacheReadInputTokens),
-    attrInt(MODEL_USAGE_ATTRIBUTES.cacheWriteTokens, cacheWriteInputTokens)
-  ] : [];
+function buildRawModelUsageAttributes(usage) {
+  const providerReportedCost = typeof usage.providerReportedCost === "number" && Number.isFinite(usage.providerReportedCost) && usage.providerReportedCost >= 0 ? usage.providerReportedCost : void 0;
   return [
-    attrInt(MODEL_USAGE_ATTRIBUTES.inputTokens, inputTokens),
-    attrInt(MODEL_USAGE_ATTRIBUTES.outputTokens, outputTokens),
-    attrInt(MODEL_USAGE_ATTRIBUTES.reasoningTokens, reasoningTokens),
-    attrInt(MODEL_USAGE_ATTRIBUTES.cacheReadInputTokens, cacheReadInputTokens),
-    attrInt(MODEL_USAGE_ATTRIBUTES.cacheWriteInputTokens, cacheWriteInputTokens),
-    ...exclusivePoolAttributes
+    attrInt(MODEL_USAGE_ATTRIBUTES.inputTokens, tokenCount(usage.inputTokens)),
+    attrInt(MODEL_USAGE_ATTRIBUTES.outputTokens, tokenCount(usage.outputTokens)),
+    attrInt(MODEL_USAGE_ATTRIBUTES.reasoningTokens, tokenCount(usage.reasoningTokens)),
+    attrInt(MODEL_USAGE_ATTRIBUTES.cacheReadInputTokens, tokenCount(usage.cacheReadInputTokens)),
+    attrInt(MODEL_USAGE_ATTRIBUTES.cacheWriteInputTokens, tokenCount(usage.cacheWriteInputTokens)),
+    attrDouble(MODEL_USAGE_ATTRIBUTES.providerReportedCost, providerReportedCost)
   ].filter((attribute) => attribute !== void 0);
 }
 var STRING_ALIASES = {
@@ -1580,7 +1848,7 @@ installTracingSuppressionHook();
 // package.json
 var package_default = {
   name: "@raindrop-ai/ai-sdk",
-  version: "0.2.1"};
+  version: "0.3.1"};
 
 // src/internal/version.ts
 var libraryName = package_default.name;
@@ -2468,37 +2736,361 @@ function runWithParentToolContext(ctx, fn) {
   return getStorage2().run(ctx, fn);
 }
 
-// src/internal/usage.ts
-function firstTokenCount(...values) {
-  for (const value of values) {
-    if (typeof value === "number" && Number.isSafeInteger(value) && value >= 0) {
-      return value;
+// src/internal/subagents.ts
+var SUBAGENT_CANCELLED_OUTPUT = "Cancelled before producing a result.";
+var SUBAGENT_ABORTED_OUTPUT = "Aborted before producing a result.";
+var SUBAGENT_FAILED_OPERATION_ID = SUBAGENT_ABORT_OPERATION_ID;
+var MAX_SETTLED_EVENT_IDS = 1024;
+function isTraceCarrier(value) {
+  const candidate = value;
+  return typeof candidate.traceId === "string" && typeof candidate.spanId === "string" && typeof candidate.eventId === "string";
+}
+function attrsFrom(metadata) {
+  return Object.entries(withMetadataPrefix(metadata)).map(([key, value]) => attrString(key, value));
+}
+function attrsExact(attributes) {
+  return Object.entries(attributes).map(([key, value]) => attrString(key, value));
+}
+function handoffSpanAttrs(link) {
+  if (!link) return [];
+  return attrsFrom(detachedChildMetadata(link));
+}
+function subagentNameAttrs(name, link) {
+  if (!name || (link == null ? void 0 : link.name)) return [];
+  return attrsFrom({ [HANDOFF_ATTRIBUTE_SUFFIXES.name]: name });
+}
+function cancelledSpanAttrs() {
+  return attrsExact(cancelledTerminalAttributes());
+}
+function describeAbortReason(reason) {
+  if (reason instanceof Error) return `Aborted: ${reason.message}`;
+  if (typeof reason === "string" && reason.trim().length > 0) return reason;
+  if (reason === void 0 || reason === null) return SUBAGENT_ABORTED_OUTPUT;
+  const serialized = boundedStringify(reason);
+  return serialized ? `Aborted: ${serialized}` : SUBAGENT_ABORTED_OUTPUT;
+}
+function stampOpenSpan(span, metadata) {
+  if (span.endTimeUnixNano) return;
+  span.attributes.push(...attrsFrom(metadata));
+}
+function stampOpenSpanExact(span, attributes) {
+  if (span.endTimeUnixNano) return;
+  span.attributes.push(...attrsExact(attributes));
+}
+var SubagentApi = class {
+  constructor(opts) {
+    var _a;
+    this.opts = opts;
+    this.settledEventIds = (_a = opts.settledEventIds) != null ? _a : /* @__PURE__ */ new Set();
+  }
+  /** True when this child's outcome has already been reported. */
+  wasSettledExplicitly(eventId) {
+    return this.settledEventIds.has(eventId);
+  }
+  /**
+   * Record an outcome reported somewhere other than `cancel()` / `fail()`, so
+   * first-outcome-wins holds across every path that can state one.
+   *
+   * An aborted generation is such a path: an AbortSignal cancellation IS the
+   * run's outcome, and the `fail(err)` that a catch block around the aborted
+   * call naturally reports would otherwise error the child's spans — which is
+   * the only thing separating `failed` from `cancelled`.
+   */
+  noteSettled(eventId) {
+    this.remember(eventId);
+  }
+  remember(eventId) {
+    if (this.settledEventIds.has(eventId)) return;
+    if (this.settledEventIds.size >= MAX_SETTLED_EVENT_IDS) {
+      const oldest = this.settledEventIds.values().next();
+      if (!oldest.done) this.settledEventIds.delete(oldest.value);
     }
+    this.settledEventIds.add(eventId);
   }
-  return void 0;
-}
-function flatUsageSemantics(provider) {
-  const normalizedProvider = typeof provider === "string" ? provider.trim().toLowerCase() : void 0;
-  if (normalizedProvider === "anthropic" || (normalizedProvider == null ? void 0 : normalizedProvider.startsWith("anthropic.")) || normalizedProvider === "vertex.anthropic" || (normalizedProvider == null ? void 0 : normalizedProvider.startsWith("vertex.anthropic."))) {
-    return {
-      inputTokenSemantics: "exclusive",
-      outputTokenSemantics: "total"
-    };
+  /**
+   * Record a detached sub-agent on this turn: allocate the child's event id,
+   * stamp the dispatch, and return the headers to send with the job.
+   *
+   * This dispatches nothing — you do, moments later, with the returned headers.
+   * Nothing here waits for the child either, or claims to know how it is doing.
+   * Readers derive that from the child's own event.
+   */
+  subagent(options = {}) {
+    var _a;
+    const childEventId = (_a = options.childEventId) != null ? _a : randomUUID();
+    const name = options.name;
+    try {
+      return this.recordLaunch(childEventId, name, options);
+    } catch (err) {
+      if (this.opts.debug) {
+        console.warn(
+          `[raindrop-ai/ai-sdk] sub-agent dispatch not recorded: ${err instanceof Error ? err.message : err}`
+        );
+      }
+      return { childEventId, name, headers: {}, carrier: null };
+    }
   }
-  if (normalizedProvider === "openai" || (normalizedProvider == null ? void 0 : normalizedProvider.startsWith("openai.")) || normalizedProvider === "azure" || (normalizedProvider == null ? void 0 : normalizedProvider.startsWith("azure."))) {
-    return {
-      inputTokenSemantics: "total",
-      outputTokenSemantics: "total"
+  recordLaunch(childEventId, name, options) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l, _m, _n, _o, _p;
+    const active = (_a = this.opts.spanSource) == null ? void 0 : _a.activeDispatch();
+    const inherited = getContextManager().getParentSpanIds();
+    const eventId = (_e = (_c = (_b = options.eventId) != null ? _b : active == null ? void 0 : active.eventId) != null ? _c : inherited == null ? void 0 : inherited.eventId) != null ? _e : (_d = this.opts.defaultContext) == null ? void 0 : _d.eventId;
+    const userId = (_h = (_f = options.userId) != null ? _f : active == null ? void 0 : active.userId) != null ? _h : (_g = this.opts.defaultContext) == null ? void 0 : _g.userId;
+    const convoId = (_k = (_i = options.convoId) != null ? _i : active == null ? void 0 : active.convoId) != null ? _k : (_j = this.opts.defaultContext) == null ? void 0 : _j.convoId;
+    if (!eventId) {
+      return { childEventId, name, headers: {}, carrier: null };
+    }
+    const dispatch = detachedDispatchMetadata({ childEventId, name });
+    const toolEvents = toolEventsAllowMetadata();
+    for (const span of (_l = active == null ? void 0 : active.turnSpans) != null ? _l : []) {
+      stampOpenSpan(span, toolEvents);
+    }
+    let dispatchIds;
+    if (active == null ? void 0 : active.dispatchSpan) {
+      stampOpenSpan(active.dispatchSpan, dispatch);
+      dispatchIds = active.dispatchSpan.ids;
+    } else if (this.opts.sendTraces) {
+      dispatchIds = this.synthesizeDispatchSpan({
+        childEventId,
+        name,
+        toolName: options.toolName,
+        eventId,
+        userId,
+        convoId,
+        input: options.input,
+        // No active turn means no telemetry setting to honor: `input` is then
+        // recorded on the explicit say-so of whoever passed it.
+        recordInputs: (_m = active == null ? void 0 : active.recordInputs) != null ? _m : true,
+        dispatch,
+        parent: (inherited == null ? void 0 : inherited.eventId) === eventId ? inherited : void 0
+      }).ids;
+    }
+    const traceId = base64ToHex((_o = (_n = dispatchIds == null ? void 0 : dispatchIds.traceIdB64) != null ? _n : inherited == null ? void 0 : inherited.traceIdB64) != null ? _o : "");
+    const spanId = base64ToHex((_p = dispatchIds == null ? void 0 : dispatchIds.spanIdB64) != null ? _p : "");
+    if (!traceId || !spanId) {
+      if (this.opts.debug) {
+        console.warn(
+          "[raindrop-ai/ai-sdk] sub-agent dispatch recorded without a carrier: no dispatch span to reference (traces disabled?)"
+        );
+      }
+      return { childEventId, name, headers: {}, carrier: null };
+    }
+    const carrier = {
+      traceId,
+      spanId,
+      eventId,
+      childEventId,
+      ...name ? { name } : {},
+      ...convoId ? { convoId } : {},
+      ...userId ? { userId } : {}
     };
+    return { childEventId, name, headers: toHeaders(carrier), carrier };
   }
-  if (normalizedProvider === "google" || (normalizedProvider == null ? void 0 : normalizedProvider.startsWith("google."))) {
+  /**
+   * Record a dispatch span for a launch with no open tool-call span to decorate:
+   * a launch from outside a tool's `execute`, or from a caller that is not an
+   * LLM turn at all (an HTTP handler that enqueues jobs). Shaped as a tool call
+   * so it reads identically to a model-issued launch.
+   */
+  synthesizeDispatchSpan(args) {
+    var _a;
+    const spanName = (_a = args.toolName) != null ? _a : DEFAULT_DISPATCH_SPAN_NAME;
+    const span = this.opts.traceShipper.startSpan({
+      name: spanName,
+      parent: args.parent,
+      eventId: args.eventId,
+      userId: args.userId,
+      convoId: args.convoId,
+      operationId: "ai.toolCall",
+      attributes: [
+        attrString("operation.name", "ai.toolCall"),
+        attrString("resource.name", spanName),
+        attrString("ai.toolCall.name", spanName),
+        attrString("ai.toolCall.id", `call_${args.childEventId.replace(/-/g, "").slice(0, 12)}`),
+        // Gated like every other input the turn's spans record: a caller that
+        // disabled input capture must not leak the payload through the one
+        // span this API synthesizes on its behalf.
+        ...args.recordInputs ? [attrString("ai.toolCall.args", boundedStringify(args.input))] : [],
+        ...attrsFrom(args.dispatch)
+      ]
+    });
+    this.opts.traceShipper.endSpan(span, {
+      // A dispatch returns a handle, not an answer — the answer is the child's.
+      attributes: [
+        attrString(
+          "ai.toolCall.result",
+          boundedStringify({ jobId: args.childEventId, status: "accepted" })
+        )
+      ]
+    });
+    return span;
+  }
+  /**
+   * Adopt a carrier as the current run's parent reference.
+   *
+   * A missing carrier is a legitimate state — the child was invoked directly
+   * rather than dispatched — so this always returns a usable run and leaves
+   * `parent` null. Call sites stay unconditional.
+   */
+  resume(carrierOrHeaders, options = {}) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _i;
+    const carrier = carrierOrHeaders ? isTraceCarrier(carrierOrHeaders) ? carrierOrHeaders : this.readCarrier(carrierOrHeaders) : null;
+    warnUnresolvedCarrier(carrierOrHeaders, carrier);
+    const name = (_a = carrier == null ? void 0 : carrier.name) != null ? _a : options.name;
+    const eventId = (_c = (_b = carrier == null ? void 0 : carrier.childEventId) != null ? _b : options.eventId) != null ? _c : randomUUID();
+    const userId = (_f = (_d = carrier == null ? void 0 : carrier.userId) != null ? _d : options.userId) != null ? _f : (_e = this.opts.defaultContext) == null ? void 0 : _e.userId;
+    const convoId = (_i = (_g = carrier == null ? void 0 : carrier.convoId) != null ? _g : options.convoId) != null ? _i : (_h = this.opts.defaultContext) == null ? void 0 : _h.convoId;
+    const parent = carrier ? {
+      parentEventId: carrier.eventId,
+      ...carrier.spanId ? { parentSpanId: carrier.spanId } : {},
+      ...name ? { name } : {}
+    } : null;
     return {
-      inputTokenSemantics: "total",
-      // Google v5 reports candidate output and thoughts separately.
-      outputTokenSemantics: "exclusive"
+      eventId,
+      name,
+      userId,
+      convoId,
+      parent,
+      metadata: {
+        eventId,
+        ...userId ? { userId } : {},
+        ...convoId ? { convoId } : {},
+        ...parent ? { subagent: parent } : {}
+      },
+      cancel: (reason) => this.settle(eventId, { userId, convoId, name, cancelled: true, output: reason }),
+      fail: (reason) => this.settle(eventId, {
+        userId,
+        convoId,
+        name,
+        handoff: parent != null ? parent : void 0,
+        cancelled: false,
+        output: describeAbortReason(reason),
+        error: reason
+      })
     };
   }
-  return {};
+  /**
+   * A carrier arrives from outside this process, so a hostile or merely broken
+   * header bag must cost the job its link, never its run.
+   */
+  readCarrier(headers) {
+    try {
+      return fromHeaders(headers);
+    } catch (err) {
+      if (this.opts.debug) {
+        console.warn(
+          `[raindrop-ai/ai-sdk] sub-agent carrier ignored: ${err instanceof Error ? err.message : err}`
+        );
+      }
+      return null;
+    }
+  }
+  /**
+   * Mark a failed child's own spans as errored.
+   *
+   * Reporting the reason as output is what gets the child an event at all, but
+   * output alone is not enough: status is derived from span shape, and a child
+   * with final output and no error spans derives `finished`. A failed job
+   * reporting success is worse than one reporting nothing, so the failure has
+   * to land on the telemetry too, not just in the text.
+   *
+   * This is the child describing its own run, not a caller writing a status it
+   * cannot observe — the child's own spans are exactly where the contract puts
+   * failure.
+   */
+  recordFailureOnSpans(eventId, args, reason) {
+    var _a, _b, _c;
+    if (!this.opts.sendTraces) return;
+    const failure = (_a = args.error) != null ? _a : reason;
+    let marked = 0;
+    for (const span2 of (_c = (_b = this.opts.spanSource) == null ? void 0 : _b.openSpansForEvent(eventId)) != null ? _c : []) {
+      if (span2.endTimeUnixNano) continue;
+      this.opts.traceShipper.endSpan(span2, { error: failure });
+      marked++;
+    }
+    if (marked > 0) return;
+    const spanName = SUBAGENT_ABORT_SPAN_NAME;
+    const span = this.opts.traceShipper.startSpan({
+      name: spanName,
+      eventId,
+      userId: args.userId,
+      convoId: args.convoId,
+      // Required, not decorative: ingest drops any span carrying no
+      // `ai.operationId` (or traceloop / `gen_ai.*` key) and still answers 200,
+      // so without this the failure disappears silently. The value is
+      // deliberately none of the generate/stream/tool/embed forms, which is
+      // what classifies the span as INTERNAL rather than mislabelling a failed
+      // job as a model call or a tool call.
+      operationId: SUBAGENT_FAILED_OPERATION_ID,
+      // Carries the reverse reference like every other span the child emits:
+      // this is often the child's ONLY span, and a span read on its own is the
+      // whole reason the reference cannot live on the root alone. The name is
+      // stamped even for an unlinked run, which has no caller to reference —
+      // `span_name` no longer says which sub-agent this was, so the attribute
+      // is the only thing that can.
+      attributes: [
+        attrString("resource.name", spanName),
+        ...handoffSpanAttrs(args.handoff),
+        ...subagentNameAttrs(args.name, args.handoff)
+      ]
+    });
+    this.opts.traceShipper.endSpan(span, { error: failure });
+  }
+  async settle(eventId, args) {
+    var _a, _b;
+    if (this.settledEventIds.has(eventId)) {
+      if (this.opts.debug) {
+        console.warn(
+          `[raindrop-ai/ai-sdk] sub-agent ${eventId} already reported an outcome; ignoring the second one`
+        );
+      }
+      return;
+    }
+    this.remember(eventId);
+    const output = args.output && args.output.trim().length > 0 ? args.output : args.cancelled ? SUBAGENT_CANCELLED_OUTPUT : SUBAGENT_ABORTED_OUTPUT;
+    try {
+      if (args.cancelled) {
+        for (const span of (_b = (_a = this.opts.spanSource) == null ? void 0 : _a.openSpansForEvent(eventId)) != null ? _b : []) {
+          stampOpenSpanExact(span, cancelledTerminalAttributes());
+        }
+      } else {
+        this.recordFailureOnSpans(eventId, args, output);
+      }
+    } catch (err) {
+      if (this.opts.debug) {
+        console.warn(
+          `[raindrop-ai/ai-sdk] sub-agent outcome not recorded on spans: ${err instanceof Error ? err.message : err}`
+        );
+      }
+    }
+    if (!this.opts.sendEvents) return;
+    await this.opts.eventShipper.patch(eventId, {
+      userId: args.userId,
+      convoId: args.convoId,
+      // An event is only created from a run that reported something. A child
+      // that dies silently produces no event at all, which pins the caller on
+      // `queued` forever — indistinguishable from a job that never started.
+      output,
+      ...args.cancelled ? { properties: { [HANDOFF_TERMINAL_PROPERTY_KEY]: HANDOFF_TERMINAL_CANCELLED } } : {},
+      isPending: false
+    }).catch((err) => {
+      if (this.opts.debug) {
+        console.warn(
+          `[raindrop-ai/ai-sdk] sub-agent outcome patch failed: ${err instanceof Error ? err.message : err}`
+        );
+      }
+    });
+  }
+};
+
+// src/internal/usage.ts
+function firstTokenCount(...values) {
+  for (const value of values) {
+    if (typeof value === "number" && Number.isSafeInteger(value) && value >= 0) {
+      return value;
+    }
+  }
+  return void 0;
 }
 var CACHE_WRITE_METADATA_KEYS = [
   ["anthropic", "cacheCreationInputTokens"],
@@ -2516,7 +3108,7 @@ function cacheWriteTokensFromProviderMetadata(providerMetadata) {
     })
   );
 }
-function extractUsageMetricsFromUsage(usage, provider, providerMetadata) {
+function extractUsageMetricsFromUsage(usage, _provider, providerMetadata) {
   if (!isRecord(usage)) return {};
   const inputTokenValue = usage["inputTokens"];
   const outputTokenValue = usage["outputTokens"];
@@ -2584,7 +3176,7 @@ function extractUsageMetricsFromUsage(usage, provider, providerMetadata) {
     cacheReadInputTokens,
     cachedInputTokens: cacheReadInputTokens,
     cacheWriteInputTokens,
-    ...hasStructuredUsage ? {} : flatUsageSemantics(provider)
+    ...hasStructuredUsage ? { usageSource: "ai-sdk-structured" } : {}
   };
 }
 
@@ -2660,6 +3252,7 @@ var RaindropTelemetryIntegration = class {
         eventName: (_f = callMeta.eventName) != null ? _f : (_e = this.defaultContext) == null ? void 0 : _e.eventName
       };
       const inherited = getContextManager().getParentSpanIds();
+      const handoff = readDetachedChildLink(metadata);
       const eventIdGenerated = (metadata == null ? void 0 : metadata["raindrop.internal.eventIdGenerated"]) === "true" || (metadata == null ? void 0 : metadata["raindrop.internal.eventIdGenerated"]) === true || (callContextMetadata == null ? void 0 : callContextMetadata.eventIdGenerated) === true;
       const explicitEventId = callMeta.eventId && !eventIdGenerated ? callMeta.eventId : void 0;
       const eventId = (_j = (_i = (_h = explicitEventId != null ? explicitEventId : (_g = this.defaultContext) == null ? void 0 : _g.eventId) != null ? _h : inherited == null ? void 0 : inherited.eventId) != null ? _i : callMeta.eventId) != null ? _j : randomUUID();
@@ -2689,7 +3282,10 @@ var RaindropTelemetryIntegration = class {
             attrString("ai.toolCall.name", subagentName),
             attrString("raindrop.subagent.name", subagentName),
             attrString("raindrop.agent.role", "subagent"),
-            ...parentAttrs
+            ...parentAttrs,
+            // Top of this child's tree, so the reverse reference matters as much
+            // here as on the root: these are the spans a reader lands on first.
+            ...handoffSpanAttrs(handoff)
           ]
         });
         const subagentParentRef = this.spanParentRef(subagentToolCallSpan);
@@ -2702,7 +3298,8 @@ var RaindropTelemetryIntegration = class {
           attributes: [
             attrString("operation.name", "agent.subagent"),
             attrString("raindrop.span.kind", "llm_call"),
-            attrString("raindrop.subagent.name", subagentName)
+            attrString("raindrop.subagent.name", subagentName),
+            ...handoffSpanAttrs(handoff)
           ]
         });
         this.traceShipper.endSpan(markerSpan);
@@ -2770,7 +3367,9 @@ var RaindropTelemetryIntegration = class {
         inputText: isEmbed ? void 0 : this.extractInputText(event),
         toolCallCount: 0,
         subagentName,
-        subagentToolCallSpan
+        subagentToolCallSpan,
+        handoff,
+        nestedInEvent: inheritedParent !== void 0
       });
     };
     // ── onStepStart ─────────────────────────────────────────────────────────
@@ -2815,7 +3414,8 @@ var RaindropTelemetryIntegration = class {
           ...attrsFromModelProvider(event.provider),
           attrString("ai.model.id", event.modelId),
           attrString(MODEL_USAGE_ATTRIBUTES.requestModel, event.modelId),
-          ...inputAttrs
+          ...inputAttrs,
+          ...handoffSpanAttrs(state.handoff)
         ]
       });
       state.stepSpan = stepSpan;
@@ -2928,7 +3528,8 @@ var RaindropTelemetryIntegration = class {
           attrInt("ai.usage.totalTokens", usageMetrics.totalTokens),
           attrInt("ai.usage.reasoningTokens", usageMetrics.reasoningTokens),
           attrInt("ai.usage.cachedInputTokens", usageMetrics.cachedInputTokens),
-          ...buildModelUsageAttributes(usageMetrics)
+          attrString(MODEL_USAGE_ATTRIBUTES.usageSource, usageMetrics.usageSource),
+          ...buildRawModelUsageAttributes(usageMetrics)
         );
       }
       this.emitProviderExecutedToolSpans(event, state);
@@ -2954,7 +3555,8 @@ var RaindropTelemetryIntegration = class {
           attrString("operation.name", operationName),
           attrString("resource.name", resourceName),
           attrString("ai.telemetry.functionId", state.functionId),
-          ...inputAttrs
+          ...inputAttrs,
+          ...handoffSpanAttrs(state.handoff)
         ]
       });
       state.embedSpans.set(event.embedCallId, embedSpan);
@@ -3026,15 +3628,26 @@ var RaindropTelemetryIntegration = class {
         this.traceShipper.endSpan(toolSpan, { error: actualError });
       }
       state.toolSpans.clear();
+      const abortReason = describeAbortReason(actualError);
       if (state.rootSpan) {
-        this.traceShipper.endSpan(state.rootSpan, { error: actualError });
+        this.traceShipper.endSpan(state.rootSpan, {
+          error: actualError,
+          attributes: this.abortOutcomeAttrs(state, abortReason, "error")
+        });
       }
       if (state.subagentToolCallSpan) {
         this.traceShipper.endSpan(state.subagentToolCallSpan, { error: actualError });
       }
       const isEmbed = state.operationId === "ai.embed" || state.operationId === "ai.embedMany";
       if (!isEmbed) {
-        this.finalizeGenerateEvent(state, state.accumulatedText || void 0, void 0);
+        const errorIsTheRunsOutcome = state.handoff !== void 0 && !state.nestedInEvent;
+        this.finalizeGenerateEvent(
+          state,
+          state.accumulatedText || void 0,
+          void 0,
+          false,
+          errorIsTheRunsOutcome ? { fallbackOutput: abortReason } : void 0
+        );
       }
       this.cleanup(event.callId);
     };
@@ -3071,9 +3684,19 @@ var RaindropTelemetryIntegration = class {
         this.traceShipper.endSpan(toolSpan, { attributes: [abortedAttr] });
       }
       state.toolSpans.clear();
+      const abortIsTheRunsOutcome = state.handoff !== void 0 && !state.nestedInEvent;
       if (state.rootSpan) {
         this.traceShipper.endSpan(state.rootSpan, {
-          attributes: [abortedAttr, attrInt("ai.toolCall.count", state.toolCallCount)]
+          attributes: [
+            abortedAttr,
+            attrInt("ai.toolCall.count", state.toolCallCount),
+            // An aborted detached child IS a cancelled sub-agent, and a cancelled
+            // run is span-for-span identical to a finished one — spans close,
+            // nothing errors, there is just no answer. So it is the one outcome
+            // that has to be stated, and the child states it on itself.
+            ...abortIsTheRunsOutcome ? cancelledSpanAttrs() : [],
+            ...abortIsTheRunsOutcome ? this.abortOutcomeAttrs(state, SUBAGENT_CANCELLED_OUTPUT, "stop") : []
+          ]
         });
       }
       if (state.subagentToolCallSpan) {
@@ -3081,7 +3704,17 @@ var RaindropTelemetryIntegration = class {
           attributes: [abortedAttr]
         });
       }
-      this.finalizeGenerateEvent(state, state.accumulatedText || void 0, void 0);
+      this.finalizeGenerateEvent(
+        state,
+        state.accumulatedText || void 0,
+        void 0,
+        false,
+        abortIsTheRunsOutcome ? {
+          fallbackOutput: SUBAGENT_CANCELLED_OUTPUT,
+          properties: { [HANDOFF_TERMINAL_PROPERTY_KEY]: HANDOFF_TERMINAL_CANCELLED }
+        } : void 0
+      );
+      if (abortIsTheRunsOutcome) this.subagents.noteSettled(state.eventId);
       this.cleanup(callId);
     };
     // ── executeTool ─────────────────────────────────────────────────────────
@@ -3109,6 +3742,97 @@ var RaindropTelemetryIntegration = class {
     this.subagentWrapping = opts.subagentWrapping !== false;
     this.debug = opts.debug === true;
     this.defaultContext = opts.context;
+    this.subagents = new SubagentApi({
+      traceShipper: this.traceShipper,
+      eventShipper: this.eventShipper,
+      sendTraces: this.sendTraces,
+      sendEvents: this.sendEvents,
+      debug: this.debug,
+      defaultContext: this.defaultContext,
+      settledEventIds: opts.settledEventIds,
+      spanSource: {
+        activeDispatch: () => this.activeDispatch(),
+        openSpansForEvent: (eventId) => this.openSpansForEvent(eventId)
+      }
+    });
+  }
+  /**
+   * Record a detached sub-agent on the turn that is live right now.
+   *
+   * Returns the dispatch — the child's event id and the headers to send with
+   * the job. Dispatching is still yours to do; this only states that you are
+   * about to, so a reader can follow the link before the child exists.
+   */
+  subagent(options = {}) {
+    return this.subagents.subagent(options);
+  }
+  // ── detached sub-agent hand-offs ─────────────────────────────────────────
+  /**
+   * The turn a `subagent()` dispatch is happening inside.
+   *
+   * Resolved from the parent-tool context first, which is the only way to reach
+   * the EXACT span that dispatched: the tool call the model itself issued, still
+   * open while its `execute` runs. Falling back to the event id lets a launch
+   * from elsewhere in the turn (a queue producer called mid-generation) still
+   * find the turn's spans, which is where the tool-events opt-in has to land.
+   */
+  activeDispatch() {
+    var _a;
+    const parentTool = getCurrentParentToolContext();
+    let state = parentTool ? this.getState(parentTool.parentCallId) : void 0;
+    const inheritedEventId = (_a = getContextManager().getParentSpanIds()) == null ? void 0 : _a.eventId;
+    if (!state && inheritedEventId) {
+      for (const candidate of this.callStates.values()) {
+        if (candidate.eventId === inheritedEventId) {
+          state = candidate;
+          break;
+        }
+      }
+    }
+    if (!state) return void 0;
+    return {
+      eventId: state.eventId,
+      userId: state.identity.userId,
+      convoId: state.identity.convoId,
+      dispatchSpan: parentTool ? state.toolSpans.get(parentTool.toolCallId) : void 0,
+      turnSpans: [state.rootSpan, state.stepSpan].filter(
+        (span) => span !== void 0
+      ),
+      recordInputs: state.recordInputs
+    };
+  }
+  /** Spans still open for an event, so a late outcome can still be stated. */
+  openSpansForEvent(eventId) {
+    const spans = [];
+    for (const state of this.callStates.values()) {
+      if (state.eventId !== eventId) continue;
+      if (state.rootSpan) spans.push(state.rootSpan);
+      if (state.stepSpan) spans.push(state.stepSpan);
+    }
+    return spans;
+  }
+  /**
+   * End-attributes that keep a detached child legible when it ends without an
+   * answer — an error, an abort, a cancellation.
+   *
+   * An event is created from an LLM span only when it has a finish reason and
+   * non-empty output, so a child that dies silently produces NO event, and the
+   * caller's hand-off pill stays on `queued` forever — indistinguishable from a
+   * job that never started. Reporting the abort reason as the run's output is
+   * what makes the outcome visible. Only detached children get this: an inline
+   * generation's failure is already legible from its caller's own event.
+   *
+   * And only the run's OUTERMOST generation gets it (see `nestedInEvent`): an
+   * inner sub-call ending badly is not the run ending, and since an event is
+   * created from an LLM span with output, `ai.response.text` here would state
+   * the run's outcome through the span while the turn is still working.
+   */
+  abortOutcomeAttrs(state, reason, finishReason) {
+    if (!state.handoff || state.nestedInEvent) return [];
+    return [
+      attrString("ai.response.text", capText2(state.accumulatedText || reason)),
+      attrString("ai.response.finishReason", finishReason)
+    ];
   }
   // ── helpers ──────────────────────────────────────────────────────────────
   getState(callId) {
@@ -3227,7 +3951,8 @@ var RaindropTelemetryIntegration = class {
         attrString("ai.telemetry.functionId", state.functionId),
         attrString("ai.toolCall.name", toolCall.toolName),
         attrString("ai.toolCall.id", toolCall.toolCallId),
-        ...inputAttrs
+        ...inputAttrs,
+        ...handoffSpanAttrs(state.handoff)
       ]
     });
     state.toolSpans.set(toolCall.toolCallId, toolSpan);
@@ -3306,7 +4031,8 @@ var RaindropTelemetryIntegration = class {
           attrString("ai.toolCall.name", call.toolName),
           attrString("ai.toolCall.id", call.toolCallId),
           attrString("ai.toolCall.providerExecuted", "true"),
-          ...inputAttrs
+          ...inputAttrs,
+          ...handoffSpanAttrs(state.handoff)
         ]
       });
       state.toolCallCount += 1;
@@ -3387,19 +4113,22 @@ var RaindropTelemetryIntegration = class {
    * is finalized by that resume — otherwise each execution would finalize the
    * same event ID into a separate canonical row.
    */
-  finalizeGenerateEvent(state, output, model, keepPending = false) {
+  finalizeGenerateEvent(state, output, model, keepPending = false, detachedOutcome) {
     var _a, _b, _c, _d, _e, _f, _g, _h, _i;
     const suppressSubagentEvent = state.subagentName !== void 0 && state.subagentToolCallSpan !== void 0;
     if (!this.sendEvents || suppressSubagentEvent) return;
+    if (this.subagents.wasSettledExplicitly(state.eventId)) return;
     const callMeta = this.extractRaindropMetadata(state.metadata);
     const userId = (_b = callMeta.userId) != null ? _b : (_a = this.defaultContext) == null ? void 0 : _a.userId;
     if (!userId) return;
     const eventName = (_e = (_d = callMeta.eventName) != null ? _d : (_c = this.defaultContext) == null ? void 0 : _c.eventName) != null ? _e : state.operationId;
     const cappedOutput = capText2(output);
+    const reportedOutput = state.handoff && detachedOutcome && !(cappedOutput == null ? void 0 : cappedOutput.trim()) ? detachedOutcome.fallbackOutput : cappedOutput;
     const input = capText2(state.inputText);
     const properties = {
       ...(_f = this.defaultContext) == null ? void 0 : _f.properties,
-      ...callMeta.properties
+      ...callMeta.properties,
+      ...state.handoff ? detachedOutcome == null ? void 0 : detachedOutcome.properties : void 0
     };
     const featureFlags = {
       ...((_g = this.defaultContext) == null ? void 0 : _g.featureFlags) ? normalizeFeatureFlags(this.defaultContext.featureFlags) : {},
@@ -3411,7 +4140,7 @@ var RaindropTelemetryIntegration = class {
       userId,
       convoId,
       input,
-      output: cappedOutput,
+      output: reportedOutput,
       model,
       properties: Object.keys(properties).length > 0 ? properties : void 0,
       featureFlags: Object.keys(featureFlags).length > 0 ? featureFlags : void 0,
@@ -3748,9 +4477,7 @@ function extractRaindropMetadata(metadata) {
     } catch (e) {
     }
   } else if (featureFlags && typeof featureFlags === "object") {
-    result.featureFlags = normalizeFeatureFlags(
-      featureFlags
-    );
+    result.featureFlags = normalizeFeatureFlags(featureFlags);
   }
   return result;
 }
@@ -3961,12 +4688,7 @@ function setupOperation(params) {
       ...attrsFromTelemetryMetadata(telemetry == null ? void 0 : telemetry.metadata),
       ...attrsFromHeaders(isRecord(arg) ? arg["headers"] : void 0),
       ...attrsFromSettings(arg),
-      ...(telemetry == null ? void 0 : telemetry.recordInputs) === false ? [] : [
-        attrString(
-          "ai.prompt",
-          safeJsonWithUint8(normalizePromptAttr(arg))
-        )
-      ]
+      ...(telemetry == null ? void 0 : telemetry.recordInputs) === false ? [] : [attrString("ai.prompt", safeJsonWithUint8(normalizePromptAttr(arg)))]
     ]
   }) : void 0;
   const rootParentForChildren = rootSpan ? { traceIdB64: rootSpan.ids.traceIdB64, spanIdB64: rootSpan.ids.spanIdB64 } : inheritedParent;
@@ -4316,13 +5038,17 @@ function wrapAISDK(aiSDK, deps) {
   }
   const useNative = deps.options.nativeTelemetry === true;
   if (useNative) {
-    const wrapTimeCtx = resolveContext(deps.options.context, { operation: "wrap", args: void 0 });
+    const wrapTimeCtx = resolveContext(deps.options.context, {
+      operation: "wrap",
+      args: void 0
+    });
     const integration = new RaindropTelemetryIntegration({
       traceShipper: deps.traceShipper,
       eventShipper: deps.eventShipper,
       sendTraces: ((_a = deps.options.send) == null ? void 0 : _a.traces) !== false,
       sendEvents: ((_b = deps.options.send) == null ? void 0 : _b.events) !== false,
       debug,
+      settledEventIds: deps.settledEventIds,
       context: {
         userId: wrapTimeCtx.userId,
         eventId: wrapTimeCtx.eventId,
@@ -4560,7 +5286,13 @@ function wrapAgentGenerate(generate, instance, agentSettings, className, aiSDK,
         ...(telemetry == null ? void 0 : telemetry.recordInputs) === false ? [] : [
           attrString(
             "ai.prompt",
-            safeJsonWithUint8(normalizePromptAttr({ system: (_d = mergedArgs["system"]) != null ? _d : mergedArgs["instructions"], prompt: mergedArgs["prompt"], messages: mergedArgs["messages"] }))
+            safeJsonWithUint8(
+              normalizePromptAttr({
+                system: (_d = mergedArgs["system"]) != null ? _d : mergedArgs["instructions"],
+                prompt: mergedArgs["prompt"],
+                messages: mergedArgs["messages"]
+              })
+            )
           )
         ]
       ]
@@ -4774,7 +5506,13 @@ function wrapAgentStream(stream, instance, agentSettings, className, aiSDK, deps
         ...(telemetry == null ? void 0 : telemetry.recordInputs) === false ? [] : [
           attrString(
             "ai.prompt",
-            safeJsonWithUint8(normalizePromptAttr({ system: (_d = mergedArgs["system"]) != null ? _d : mergedArgs["instructions"], prompt: mergedArgs["prompt"], messages: mergedArgs["messages"] }))
+            safeJsonWithUint8(
+              normalizePromptAttr({
+                system: (_d = mergedArgs["system"]) != null ? _d : mergedArgs["instructions"],
+                prompt: mergedArgs["prompt"],
+                messages: mergedArgs["messages"]
+              })
+            )
           )
         ]
       ]
@@ -5151,9 +5889,19 @@ function wrapModel(args, aiSDK, outerOperationId, ctx) {
                 for (const part of content) {
                   if (isRecord(part)) {
                     if ((part["type"] === "reasoning" || part["type"] === "thinking") && typeof ((_a = part["text"]) != null ? _a : part["thinking"]) === "string") {
-                      sendLocalDebuggerLiveEvent({ traceId, type: "reasoning_delta", content: (_b = part["text"]) != null ? _b : part["thinking"], metadata: liveMeta });
+                      sendLocalDebuggerLiveEvent({
+                        traceId,
+                        type: "reasoning_delta",
+                        content: (_b = part["text"]) != null ? _b : part["thinking"],
+                        metadata: liveMeta
+                      });
                     } else if (part["type"] === "text" && typeof part["text"] === "string") {
-                      sendLocalDebuggerLiveEvent({ traceId, type: "text_delta", content: part["text"], metadata: liveMeta });
+                      sendLocalDebuggerLiveEvent({
+                        traceId,
+                        type: "text_delta",
+                        content: part["text"],
+                        metadata: liveMeta
+                      });
                     }
                   }
                 }
@@ -5234,7 +5982,10 @@ function wrapModel(args, aiSDK, outerOperationId, ctx) {
               attributes: [
                 ...((_a = ctx.telemetry) == null ? void 0 : _a.recordOutputs) === false ? [] : [
                   attrString("ai.response.finishReason", finishReason),
-                  attrString("ai.response.text", activeText.length ? capText2(activeText) : void 0),
+                  attrString(
+                    "ai.response.text",
+                    activeText.length ? capText2(activeText) : void 0
+                  ),
                   attrString(
                     "ai.response.toolCalls",
                     safeJsonWithUint8(toolCallsLocal.length ? toolCallsLocal : void 0)
@@ -5252,7 +6003,8 @@ function wrapModel(args, aiSDK, outerOperationId, ctx) {
                 ...finishReason ? [attrStringArray("gen_ai.response.finish_reasons", [finishReason])] : [],
                 attrString("gen_ai.response.id", responseId),
                 attrString(MODEL_USAGE_ATTRIBUTES.responseModel, finalResponseModelId),
-                ...buildModelUsageAttributes(usageMetrics),
+                attrString(MODEL_USAGE_ATTRIBUTES.usageSource, usageMetrics.usageSource),
+                ...buildRawModelUsageAttributes(usageMetrics),
                 ...msToFirstChunk !== void 0 ? [attrInt("ai.stream.msToFirstChunk", msToFirstChunk)] : [],
                 ...msToFinish !== void 0 ? [attrInt("ai.stream.msToFinish", msToFinish)] : [],
                 ...avgOutTokensPerSecond !== void 0 ? [attrDouble("ai.stream.avgOutputTokensPerSecond", avgOutTokensPerSecond)] : [],
@@ -5306,19 +6058,44 @@ function wrapModel(args, aiSDK, outerOperationId, ctx) {
                   if ("providerMetadata" in value) providerMetadata = value["providerMetadata"];
                   if (localDebuggerEnabled() && ctx.rootParentForChildren) {
                     const traceId = ctx.rootParentForChildren.traceIdB64;
-                    const liveMeta = getLocalDebuggerMetadata({ ...ctx.context, eventId: ctx.eventId });
+                    const liveMeta = getLocalDebuggerMetadata({
+                      ...ctx.context,
+                      eventId: ctx.eventId
+                    });
                     if (type === "text-delta") {
                       const text = typeof value["delta"] === "string" ? value["delta"] : typeof value["textDelta"] === "string" ? value["textDelta"] : typeof value["text"] === "string" ? value["text"] : void 0;
-                      if (typeof text === "string" && text) sendLocalDebuggerLiveEvent({ traceId, type: "text_delta", content: text, metadata: liveMeta });
+                      if (typeof text === "string" && text)
+                        sendLocalDebuggerLiveEvent({
+                          traceId,
+                          type: "text_delta",
+                          content: text,
+                          metadata: liveMeta
+                        });
                     } else if (type === "reasoning" || type === "reasoning-delta") {
                       const text = typeof value["delta"] === "string" ? value["delta"] : typeof value["text"] === "string" ? value["text"] : typeof value["thinking"] === "string" ? value["thinking"] : void 0;
-                      if (typeof text === "string" && text) sendLocalDebuggerLiveEvent({ traceId, type: "reasoning_delta", content: text, metadata: liveMeta });
+                      if (typeof text === "string" && text)
+                        sendLocalDebuggerLiveEvent({
+                          traceId,
+                          type: "reasoning_delta",
+                          content: text,
+                          metadata: liveMeta
+                        });
                     } else if (type === "tool-call") {
                       const toolName = typeof value["toolName"] === "string" ? value["toolName"] : "tool";
-                      sendLocalDebuggerLiveEvent({ traceId, type: "tool_start", content: toolName, metadata: { ...liveMeta, args: value["args"] } });
+                      sendLocalDebuggerLiveEvent({
+                        traceId,
+                        type: "tool_start",
+                        content: toolName,
+                        metadata: { ...liveMeta, args: value["args"] }
+                      });
                     } else if (type === "tool-result") {
                       const toolName = typeof value["toolName"] === "string" ? value["toolName"] : "tool";
-                      sendLocalDebuggerLiveEvent({ traceId, type: "tool_result", content: toolName, metadata: { ...liveMeta, result: value["result"] } });
+                      sendLocalDebuggerLiveEvent({
+                        traceId,
+                        type: "tool_result",
+                        content: toolName,
+                        metadata: { ...liveMeta, result: value["result"] }
+                      });
                     }
                   }
                 }
@@ -5398,11 +6175,7 @@ function endDoGenerateSpan(span, result, modelInfo, ctx) {
   } else {
     responseTimestampIso = (/* @__PURE__ */ new Date()).toISOString();
   }
-  const usageMetrics = extractUsageMetricsFromUsage(
-    usage,
-    modelInfo.provider,
-    providerMetadata
-  );
+  const usageMetrics = extractUsageMetricsFromUsage(usage, modelInfo.provider, providerMetadata);
   const { inputTokens, outputTokens } = usageMetrics;
   ctx.traceShipper.endSpan(span, {
     attributes: [
@@ -5423,7 +6196,8 @@ function endDoGenerateSpan(span, result, modelInfo, ctx) {
       ...finishReason ? [attrStringArray("gen_ai.response.finish_reasons", [finishReason])] : [],
       attrString("gen_ai.response.id", responseId),
       attrString(MODEL_USAGE_ATTRIBUTES.responseModel, responseModelId),
-      ...buildModelUsageAttributes(usageMetrics)
+      attrString(MODEL_USAGE_ATTRIBUTES.usageSource, usageMetrics.usageSource),
+      ...buildRawModelUsageAttributes(usageMetrics)
     ]
   });
 }
@@ -5532,6 +6306,8 @@ function eventMetadata(options) {
   if (options.properties) result["raindrop.properties"] = JSON.stringify(options.properties);
   if (options.featureFlags)
     result["raindrop.featureFlags"] = JSON.stringify(normalizeFeatureFlags(options.featureFlags));
+  if (options.subagent) Object.assign(result, detachedChildMetadata(options.subagent));
+  if (options.toolEvents) result[TOOL_EVENTS_SUFFIX] = options.toolEvents;
   return result;
 }
 function deriveChatTurnMessageId(request) {
@@ -5614,12 +6390,22 @@ function createRaindropAISDK(opts) {
     transformSpan: (_j = opts.traces) == null ? void 0 : _j.transformSpan,
     disableDefaultRedaction: (_k = opts.traces) == null ? void 0 : _k.disableDefaultRedaction
   });
+  const settledEventIds = /* @__PURE__ */ new Set();
+  const subagentApi = new SubagentApi({
+    traceShipper,
+    eventShipper,
+    sendTraces: tracesEnabled,
+    sendEvents: eventsEnabled,
+    debug: envDebug,
+    settledEventIds
+  });
   return {
     wrap(aiSDK, options) {
       return wrapAISDK(aiSDK, {
         options: options != null ? options : {},
         eventShipper,
-        traceShipper
+        traceShipper,
+        settledEventIds
       });
     },
     createSelfDiagnosticsTool(options = {}) {
@@ -5656,9 +6442,14 @@ function createRaindropAISDK(opts) {
         sendEvents: eventsEnabled,
         subagentWrapping,
         debug: envDebug,
+        settledEventIds,
         context
       });
     },
+    subagents: subagentApi,
+    subagent(options = {}) {
+      return subagentApi.subagent(options);
+    },
     events: {
       async patch(eventId, patch) {
         await eventShipper.patch(eventId, patch);
@@ -5784,8 +6575,17 @@ globalThis.RAINDROP_ASYNC_LOCAL_STORAGE = async_hooks.AsyncLocalStorage;
 exports.DEFAULT_MAX_TEXT_FIELD_CHARS = DEFAULT_MAX_TEXT_FIELD_CHARS2;
 exports.DEFAULT_REDACT_ATTRIBUTE_KEYS = DEFAULT_REDACT_ATTRIBUTE_KEYS;
 exports.DEFAULT_SECRET_KEY_NAMES = DEFAULT_SECRET_KEY_NAMES;
+exports.DETACHED_MODE = DETACHED_MODE;
+exports.HANDOFF_ATTRIBUTE_PREFIXES = HANDOFF_ATTRIBUTE_PREFIXES;
+exports.HANDOFF_ATTRIBUTE_SUFFIXES = HANDOFF_ATTRIBUTE_SUFFIXES;
+exports.HANDOFF_TERMINAL_CANCELLED = HANDOFF_TERMINAL_CANCELLED;
+exports.HANDOFF_TERMINAL_PROPERTY_KEY = HANDOFF_TERMINAL_PROPERTY_KEY;
 exports.REDACTED_PLACEHOLDER = REDACTED_PLACEHOLDER;
 exports.RaindropTelemetryIntegration = RaindropTelemetryIntegration;
+exports.SUBAGENT_ABORTED_OUTPUT = SUBAGENT_ABORTED_OUTPUT;
+exports.SUBAGENT_AGENT_ROLE = SUBAGENT_AGENT_ROLE;
+exports.SUBAGENT_CANCELLED_OUTPUT = SUBAGENT_CANCELLED_OUTPUT;
+exports.TOOL_EVENTS_ALLOW = TOOL_EVENTS_ALLOW;
 exports.TRUNCATION_MARKER = TRUNCATION_MARKER2;
 exports._resetParentToolContextStorage = _resetParentToolContextStorage;
 exports._resetRaindropCallMetadataStorage = _resetRaindropCallMetadataStorage;
@@ -5799,6 +6599,7 @@ exports.defaultTransformSpan = defaultTransformSpan;
 exports.enterParentToolContext = enterParentToolContext;
 exports.eventMetadata = eventMetadata;
 exports.eventMetadataFromChatRequest = eventMetadataFromChatRequest;
+exports.fromHeaders = fromHeaders;
 exports.getContextManager = getContextManager;
 exports.getCurrentParentToolContext = getCurrentParentToolContext;
 exports.getCurrentRaindropCallMetadata = getCurrentRaindropCallMetadata;
@@ -5807,6 +6608,9 @@ exports.raindrop = raindrop;
 exports.readRaindropCallMetadataFromArgs = readRaindropCallMetadataFromArgs;
 exports.redactJsonAttributeValue = redactJsonAttributeValue;
 exports.redactSecretsInObject = redactSecretsInObject;
+exports.resetUnresolvedCarrierWarning = resetUnresolvedCarrierWarning;
 exports.runWithParentToolContext = runWithParentToolContext;
 exports.runWithRaindropCallMetadata = runWithRaindropCallMetadata;
+exports.toHeaders = toHeaders;
+exports.toLangSmithHeaders = toLangSmithHeaders;
 exports.withCurrent = withCurrent;