@raindrop-ai/ai-sdk 0.0.29 → 0.0.30

package/dist/{chunk-QGI4SABN.mjs → chunk-LM3XO4KR.mjs}

@@ -1714,13 +1714,76 @@ function readRaindropCallMetadataFromArgs(args) {
   return meta;
 }
 
+// src/internal/parent-tool-context.ts
+var SyncFallbackStorage2 = class {
+  constructor() {
+    this._stack = [];
+  }
+  getStore() {
+    return this._stack[this._stack.length - 1];
+  }
+  run(store, callback) {
+    this._stack.push(store);
+    try {
+      return callback();
+    } finally {
+      this._stack.pop();
+    }
+  }
+  // `enterWith` is intentionally absent on the sync fallback — the
+  // event-driven enter/clear pattern only makes sense when the runtime
+  // can propagate state across awaits, which the sync stack cannot.
+};
+var _storage2 = null;
+function getStorage2() {
+  if (_storage2) return _storage2;
+  const Ctor = globalThis.RAINDROP_ASYNC_LOCAL_STORAGE;
+  _storage2 = Ctor ? new Ctor() : new SyncFallbackStorage2();
+  return _storage2;
+}
+function _resetParentToolContextStorage() {
+  _storage2 = null;
+}
+function getCurrentParentToolContext() {
+  return getStorage2().getStore();
+}
+function enterParentToolContext(ctx) {
+  var _a;
+  const storage = getStorage2();
+  (_a = storage.enterWith) == null ? void 0 : _a.call(storage, ctx);
+}
+function clearParentToolContext() {
+  var _a;
+  const storage = getStorage2();
+  (_a = storage.enterWith) == null ? void 0 : _a.call(storage, void 0);
+}
+function runWithParentToolContext(ctx, fn) {
+  return getStorage2().run(ctx, fn);
+}
+
 // src/internal/raindrop-telemetry-integration.ts
 var RaindropTelemetryIntegration = class {
   constructor(opts) {
     this.callStates = /* @__PURE__ */ new Map();
+    /**
+     * Per-tool-call snapshot of the parent-tool ALS context taken right
+     * before `enterParentToolContext` overwrites it in `toolExecutionStart`.
+     * Kept at the integration level (rather than on `CallState`) so the
+     * snapshot survives even when the parent generation has no tracked
+     * `CallState` — e.g. the AI SDK dispatches a tool callback for a
+     * `callId` we never registered via `onStart`. Without this, the
+     * unconditional ALS enter in `toolExecutionStart` would leave
+     * `toolExecutionEnd` no way to restore the prior context, so it would
+     * clear and wipe whatever the outer scope had set.
+     *
+     * Keyed by `toolCallId` because that's the only identifier guaranteed
+     * to round-trip between `toolExecutionStart` and `toolExecutionEnd`
+     * (the `event.callId` can be the same for parallel sibling tools).
+     */
+    this.priorParentContexts = /* @__PURE__ */ new Map();
     // ── onStart ─────────────────────────────────────────────────────────────
     this.onStart = (event) => {
-      var _a, _b, _c, _d;
+      var _a, _b, _c, _d, _e;
       if (event.isEnabled === false) return;
       const isEmbed = event.operationId === "ai.embed" || event.operationId === "ai.embedMany";
       const recordInputs = event.recordInputs !== false;
@@ -1739,6 +1802,47 @@ var RaindropTelemetryIntegration = class {
         event.operationId,
         functionId
       );
+      const parentToolContext = !isEmbed && this.subagentWrapping ? getCurrentParentToolContext() : void 0;
+      const metadataSubagentName = !isEmbed && this.subagentWrapping && parentToolContext === void 0 ? typeof (metadata == null ? void 0 : metadata["ash.subagent.name"]) === "string" ? metadata["ash.subagent.name"] : void 0 : void 0;
+      const subagentName = (_e = parentToolContext == null ? void 0 : parentToolContext.toolName) != null ? _e : metadataSubagentName;
+      let subagentToolCallSpan;
+      let rootParentOverride;
+      if (subagentName && this.sendTraces) {
+        const parentAttrs = parentToolContext ? [
+          attrString("raindrop.parent.callId", parentToolContext.parentCallId),
+          attrString("raindrop.parent.toolCallId", parentToolContext.toolCallId),
+          attrString("raindrop.parent.toolName", parentToolContext.toolName)
+        ] : [];
+        subagentToolCallSpan = this.traceShipper.startSpan({
+          name: subagentName,
+          parent: inheritedParent,
+          eventId,
+          operationId: "ai.toolCall",
+          attributes: [
+            attrString("operation.name", "ai.toolCall"),
+            attrString("resource.name", subagentName),
+            attrString("raindrop.span.kind", "tool_call"),
+            attrString("ai.toolCall.name", subagentName),
+            attrString("raindrop.subagent.name", subagentName),
+            attrString("raindrop.agent.role", "subagent"),
+            ...parentAttrs
+          ]
+        });
+        const subagentParentRef = this.spanParentRef(subagentToolCallSpan);
+        const markerSpan = this.traceShipper.startSpan({
+          name: "agent.subagent",
+          parent: subagentParentRef,
+          eventId,
+          operationId: "agent.subagent",
+          attributes: [
+            attrString("operation.name", "agent.subagent"),
+            attrString("raindrop.span.kind", "llm_call"),
+            attrString("raindrop.subagent.name", subagentName)
+          ]
+        });
+        this.traceShipper.endSpan(markerSpan);
+        rootParentOverride = subagentParentRef;
+      }
       let rootSpan;
       if (this.sendTraces) {
         const promptAttrs = !isEmbed && recordInputs ? [
@@ -1759,7 +1863,7 @@ var RaindropTelemetryIntegration = class {
         ] : [attrString("ai.value", safeJsonWithUint8(event.value))] : [];
         rootSpan = this.traceShipper.startSpan({
           name: event.operationId,
-          parent: inheritedParent,
+          parent: rootParentOverride != null ? rootParentOverride : inheritedParent,
           eventId,
           operationId: event.operationId,
           attributes: [
@@ -1787,18 +1891,21 @@ var RaindropTelemetryIntegration = class {
         operationId: event.operationId,
         eventId,
         rootSpan,
-        rootParent: rootSpan ? this.spanParentRef(rootSpan) : inheritedParent,
+        rootParent: rootSpan ? this.spanParentRef(rootSpan) : rootParentOverride != null ? rootParentOverride : inheritedParent,
         stepSpan: void 0,
         stepParent: void 0,
         toolSpans: /* @__PURE__ */ new Map(),
         embedSpans: /* @__PURE__ */ new Map(),
+        parentContextToolCallIds: /* @__PURE__ */ new Set(),
         recordInputs,
         recordOutputs,
         functionId,
         metadata,
         accumulatedText: "",
         inputText: isEmbed ? void 0 : this.extractInputText(event),
-        toolCallCount: 0
+        toolCallCount: 0,
+        subagentName,
+        subagentToolCallSpan
       });
     };
     // ── onStepStart ─────────────────────────────────────────────────────────
@@ -2022,6 +2129,9 @@ var RaindropTelemetryIntegration = class {
       } else {
         this.finishGenerate(event, state);
       }
+      if (state.subagentToolCallSpan) {
+        this.traceShipper.endSpan(state.subagentToolCallSpan);
+      }
       this.cleanup(event.callId);
     };
     // ── onError ─────────────────────────────────────────────────────────────
@@ -2039,6 +2149,10 @@ var RaindropTelemetryIntegration = class {
         this.traceShipper.endSpan(embedSpan, { error: actualError });
       }
       state.embedSpans.clear();
+      for (const toolCallId of state.parentContextToolCallIds) {
+        this.priorParentContexts.delete(toolCallId);
+      }
+      state.parentContextToolCallIds.clear();
       for (const toolSpan of state.toolSpans.values()) {
         this.traceShipper.endSpan(toolSpan, { error: actualError });
       }
@@ -2046,6 +2160,9 @@ var RaindropTelemetryIntegration = class {
       if (state.rootSpan) {
         this.traceShipper.endSpan(state.rootSpan, { error: actualError });
       }
+      if (state.subagentToolCallSpan) {
+        this.traceShipper.endSpan(state.subagentToolCallSpan, { error: actualError });
+      }
       this.cleanup(event.callId);
     };
     // ── executeTool ─────────────────────────────────────────────────────────
@@ -2070,6 +2187,7 @@ var RaindropTelemetryIntegration = class {
     this.eventShipper = opts.eventShipper;
     this.sendTraces = opts.sendTraces !== false;
     this.sendEvents = opts.sendEvents !== false;
+    this.subagentWrapping = opts.subagentWrapping !== false;
     this.debug = opts.debug === true;
     this.defaultContext = opts.context;
   }
@@ -2151,9 +2269,20 @@ var RaindropTelemetryIntegration = class {
   // (see https://github.com/vercel/ai/pull/14589). Event shape is identical.
   // Both names are exposed and forward to a single implementation.
   toolExecutionStart(event) {
+    const { toolCall } = event;
+    const priorParent = getCurrentParentToolContext();
+    this.priorParentContexts.set(
+      toolCall.toolCallId,
+      priorParent != null ? priorParent : null
+    );
+    enterParentToolContext({
+      parentCallId: event.callId,
+      toolCallId: toolCall.toolCallId,
+      toolName: toolCall.toolName
+    });
     const state = this.getState(event.callId);
+    state == null ? void 0 : state.parentContextToolCallIds.add(toolCall.toolCallId);
     if (!(state == null ? void 0 : state.stepParent)) return;
-    const { toolCall } = event;
     const { operationName, resourceName } = opName(
       "ai.toolCall",
       state.functionId
@@ -2177,6 +2306,17 @@ var RaindropTelemetryIntegration = class {
     this.emitLive(state, "tool_start", toolCall.toolName, { args: toolCall.input });
   }
   toolExecutionEnd(event) {
+    var _a;
+    const toolCallId = (_a = event.toolCall) == null ? void 0 : _a.toolCallId;
+    if (toolCallId && this.priorParentContexts.has(toolCallId)) {
+      const prior = this.priorParentContexts.get(toolCallId);
+      this.priorParentContexts.delete(toolCallId);
+      if (prior) {
+        enterParentToolContext(prior);
+      } else {
+        clearParentToolContext();
+      }
+    }
     const state = this.getState(event.callId);
     if (!state) return;
     const toolSpan = state.toolSpans.get(event.toolCall.toolCallId);
@@ -2240,7 +2380,8 @@ var RaindropTelemetryIntegration = class {
       );
       this.traceShipper.endSpan(state.rootSpan, { attributes: outputAttrs });
     }
-    if (this.sendEvents) {
+    const suppressSubagentEvent = state.subagentName !== void 0 && state.subagentToolCallSpan !== void 0;
+    if (this.sendEvents && !suppressSubagentEvent) {
       const callMeta = this.extractRaindropMetadata(state.metadata);
       const userId = (_f = callMeta.userId) != null ? _f : (_e = this.defaultContext) == null ? void 0 : _e.userId;
       if (userId) {
@@ -4333,7 +4474,7 @@ function extractNestedTokens(usage, key) {
 // package.json
 var package_default = {
   name: "@raindrop-ai/ai-sdk",
-  version: "0.0.29"};
+  version: "0.0.30"};
 
 // src/internal/version.ts
 var libraryName = package_default.name;
@@ -4424,12 +4565,16 @@ function createRaindropAISDK(opts) {
   const writeKey = opts.writeKey;
   const eventsRequested = ((_a = opts.events) == null ? void 0 : _a.enabled) !== false;
   const tracesRequested = ((_b = opts.traces) == null ? void 0 : _b.enabled) !== false;
-  const eventsEnabled = eventsRequested && !!writeKey;
-  const tracesEnabled = tracesRequested && !!writeKey;
   const envDebug = envDebugEnabled();
-  if (!writeKey && (eventsRequested || tracesRequested)) {
+  const localWorkshopInput = opts.localWorkshopUrl === false ? null : opts.localWorkshopUrl;
+  const resolvedLocalDebuggerUrl = resolveLocalDebuggerBaseUrl(localWorkshopInput);
+  const localDebuggerUrl = localWorkshopInput === null ? null : resolvedLocalDebuggerUrl != null ? resolvedLocalDebuggerUrl : void 0;
+  const hasDestination = !!writeKey || !!resolvedLocalDebuggerUrl;
+  const eventsEnabled = eventsRequested && hasDestination;
+  const tracesEnabled = tracesRequested && hasDestination;
+  if (!hasDestination && (eventsRequested || tracesRequested)) {
     console.warn(
-      "[raindrop-ai/ai-sdk] writeKey not provided; telemetry shipping is disabled"
+      "[raindrop-ai/ai-sdk] writeKey not provided and no local Workshop reachable; telemetry shipping is disabled"
     );
   }
   const eventShipper = new EventShipper2({
@@ -4437,9 +4582,9 @@ function createRaindropAISDK(opts) {
     endpoint: opts.endpoint,
     enabled: eventsEnabled,
     debug: ((_c = opts.events) == null ? void 0 : _c.debug) === true || envDebug,
-    partialFlushMs: (_d = opts.events) == null ? void 0 : _d.partialFlushMs
+    partialFlushMs: (_d = opts.events) == null ? void 0 : _d.partialFlushMs,
+    localDebuggerUrl
   });
-  const localDebuggerUrl = opts.localWorkshopUrl === false ? null : opts.localWorkshopUrl;
   const traceShipper = new TraceShipper2({
     writeKey,
     endpoint: opts.endpoint,
@@ -4461,12 +4606,30 @@ function createRaindropAISDK(opts) {
         traceShipper
       });
     },
-    createTelemetryIntegration(context) {
+    createTelemetryIntegration(contextOrOptions) {
+      const FLAT_CONTEXT_KEYS = [
+        "userId",
+        "eventId",
+        "eventName",
+        "convoId",
+        "properties"
+      ];
+      let context;
+      let subagentWrapping;
+      if (contextOrOptions === void 0) ; else if ("context" in contextOrOptions) {
+        context = contextOrOptions.context;
+        subagentWrapping = contextOrOptions.subagentWrapping;
+      } else if ("subagentWrapping" in contextOrOptions && !FLAT_CONTEXT_KEYS.some((k) => k in contextOrOptions)) {
+        subagentWrapping = contextOrOptions.subagentWrapping;
+      } else {
+        context = contextOrOptions;
+      }
       return new RaindropTelemetryIntegration({
         traceShipper,
         eventShipper,
         sendTraces: tracesEnabled,
         sendEvents: eventsEnabled,
+        subagentWrapping,
         debug: envDebug,
         context
       });
@@ -4574,4 +4737,4 @@ function createRaindropAISDK(opts) {
   };
 }
 
-export { DEFAULT_REDACT_ATTRIBUTE_KEYS, DEFAULT_SECRET_KEY_NAMES, REDACTED_PLACEHOLDER, RaindropTelemetryIntegration, _resetRaindropCallMetadataStorage, _resetWarnedMissingUserId, createRaindropAISDK, currentSpan, defaultTransformSpan, eventMetadata, eventMetadataFromChatRequest, getContextManager, getCurrentRaindropCallMetadata, readRaindropCallMetadataFromArgs, redactJsonAttributeValue, redactSecretsInObject, runWithRaindropCallMetadata, withCurrent };
+export { DEFAULT_REDACT_ATTRIBUTE_KEYS, DEFAULT_SECRET_KEY_NAMES, REDACTED_PLACEHOLDER, RaindropTelemetryIntegration, _resetParentToolContextStorage, _resetRaindropCallMetadataStorage, _resetWarnedMissingUserId, clearParentToolContext, createRaindropAISDK, currentSpan, defaultTransformSpan, enterParentToolContext, eventMetadata, eventMetadataFromChatRequest, getContextManager, getCurrentParentToolContext, getCurrentRaindropCallMetadata, readRaindropCallMetadataFromArgs, redactJsonAttributeValue, redactSecretsInObject, runWithParentToolContext, runWithRaindropCallMetadata, withCurrent };

package/dist/{index-DKdCelJA.d.mts → index-Ba_ZzUH4.d.mts}

@@ -391,6 +391,19 @@ type RaindropTelemetryIntegrationOptions = {
     eventShipper: EventShipper;
     sendTraces?: boolean;
     sendEvents?: boolean;
+    /**
+     * When `true` (default), generations started inside a tool's `execute`
+     * callback on the same async branch are wrapped in a synthetic `TOOL_CALL`
+     * + `agent.subagent` LLM marker so observability backends can render them
+     * as an agent block (and so the inner LLM's `track_partial` is suppressed).
+     *
+     * This is the right semantic for any framework that lowers sub-agents to
+     * AI SDK tools (Ash, Mastra, Claude Agent SDK, hand-rolled tool loops),
+     * not Ash-specific. Set to `false` if you have a tool whose `execute`
+     * happens to call `streamText`/`generateText` for unrelated reasons (e.g.
+     * RAG enrichment) and don't want it labelled as a sub-agent.
+     */
+    subagentWrapping?: boolean;
     debug?: boolean;
     context?: {
         userId?: string;
@@ -405,9 +418,26 @@ declare class RaindropTelemetryIntegration implements TelemetryIntegration {
     private readonly eventShipper;
     private readonly sendTraces;
     private readonly sendEvents;
+    private readonly subagentWrapping;
     private readonly debug;
     private readonly defaultContext;
     private readonly callStates;
+    /**
+     * Per-tool-call snapshot of the parent-tool ALS context taken right
+     * before `enterParentToolContext` overwrites it in `toolExecutionStart`.
+     * Kept at the integration level (rather than on `CallState`) so the
+     * snapshot survives even when the parent generation has no tracked
+     * `CallState` — e.g. the AI SDK dispatches a tool callback for a
+     * `callId` we never registered via `onStart`. Without this, the
+     * unconditional ALS enter in `toolExecutionStart` would leave
+     * `toolExecutionEnd` no way to restore the prior context, so it would
+     * clear and wipe whatever the outer scope had set.
+     *
+     * Keyed by `toolCallId` because that's the only identifier guaranteed
+     * to round-trip between `toolExecutionStart` and `toolExecutionEnd`
+     * (the `event.callId` can be the same for parallel sibling tools).
+     */
+    private readonly priorParentContexts;
     constructor(opts: RaindropTelemetryIntegrationOptions);
     private getState;
     private cleanup;
@@ -510,6 +540,92 @@ declare function readRaindropCallMetadataFromArgs(args: readonly unknown[]): Rai
 
 declare function _resetWarnedMissingUserId(): void;
 
+/**
+ * Parent tool execution context propagation.
+ *
+ * Problem
+ * ───────
+ * When a tool's `execute` callback recursively calls `streamText` /
+ * `generateText` (which is exactly how Ash lowers sub-agents, but also a
+ * common pattern in hand-rolled agent loops, Mastra, Claude Agent SDK,
+ * etc.), the inner generation's telemetry events are dispatched with no
+ * connection back to the outer tool call. The AI SDK fires `onStart` for
+ * the inner generation with its own fresh `callId`; nothing on the event
+ * tells the integration "this generation was triggered from inside tool
+ * X's execute callback."
+ *
+ * Without that linkage, observability tools have to fall back to
+ * regex-matching the prompt to guess whether a call is a sub-agent
+ * dispatch — fragile, framework-specific, and easily spoofable by user
+ * input.
+ *
+ * Solution
+ * ────────
+ * We maintain an `AsyncLocalStorage` slot that holds the currently-active
+ * parent tool call. The integration's `onToolExecutionStart` enters the
+ * slot before the AI SDK awaits `tool.execute(...)`; the inner
+ * generation's `onStart` reads from the slot to recover parent linkage.
+ * `onToolExecutionEnd` clears the slot so subsequent code in the same
+ * async branch doesn't see stale state.
+ *
+ * Async-context scoping
+ * ─────────────────────
+ * `enterWith` modifies the *current* async context, which propagates
+ * downward into any `await` continuation and into child async resources
+ * (including the awaited `tool.execute` and anything it calls). Sibling
+ * branches are unaffected: when the AI SDK dispatches tool calls via
+ * `Promise.all(map(async (tc) => ...))`, each map callback runs in its
+ * own async branch, so `enterWith` in one branch is invisible to the
+ * others. This is exactly the behaviour we need for parallel sub-agent
+ * dispatch.
+ *
+ * On runtimes that don't expose `AsyncLocalStorage` (browser, Cloudflare
+ * Workers without `nodejs_compat`), we fall back to a synchronous stack
+ * via `runWithParentToolContext` — see the `SyncFallbackStorage` in
+ * `call-metadata.ts` for the established pattern. `enterWith` becomes a
+ * silent no-op on the sync fallback, so async tool execution on those
+ * runtimes won't have parent linkage and the inner generation will
+ * render as a top-level call instead of being grouped under its caller.
+ */
+type ParentToolContext = {
+    /** The `callId` of the generation whose step kicked off this tool call. */
+    parentCallId: string;
+    /** The tool-call id from the parent generation's step. */
+    toolCallId: string;
+    /** The tool name the parent generation invoked. */
+    toolName: string;
+};
+/** Test helper — drop the storage so tests start from a fresh slot. */
+declare function _resetParentToolContextStorage(): void;
+/**
+ * Returns the active parent tool context, or `undefined` if no tool is
+ * currently executing in this async branch.
+ */
+declare function getCurrentParentToolContext(): ParentToolContext | undefined;
+/**
+ * Enter a parent tool context on the current async branch. Subsequent
+ * `await`-ed work (including the parent's `tool.execute` body) inherits
+ * the context until {@link clearParentToolContext} runs. No-op on
+ * runtimes without `enterWith` support (browser/edge sync fallback).
+ */
+declare function enterParentToolContext(ctx: ParentToolContext): void;
+/**
+ * Clear the parent tool context on the current async branch. Pairs with
+ * {@link enterParentToolContext}. No-op on runtimes without `enterWith`
+ * support.
+ *
+ * `enterWith(undefined)` is supported by Node's `AsyncLocalStorage` at
+ * runtime; the `as never` cast bypasses TypeScript's stricter typing on
+ * the shared global declaration (`store: T`).
+ */
+declare function clearParentToolContext(): void;
+/**
+ * Run `fn` with `ctx` bound as the parent tool context. The sync-fallback
+ * equivalent of `enter`/`clear` — useful in tests and any code path
+ * where you want strict block scoping.
+ */
+declare function runWithParentToolContext<R>(ctx: ParentToolContext, fn: () => R): R;
+
 /**
  * Options for creating event metadata for call-time context override.
  */
@@ -860,8 +976,17 @@ type RaindropAISDKClient = {
     /**
      * Create a TelemetryIntegration instance for direct registration with AI SDK v7+.
      * Use with `registerTelemetryIntegration()` from the `ai` package.
+     *
+     * Accepts the same `context` it has always accepted, or a full options
+     * object exposing `{ context, subagentWrapping }`. Sub-agent wrapping
+     * defaults to `true`; pass `subagentWrapping: false` to opt out for
+     * consumers whose `tool.execute` happens to call `generateText` for
+     * non-agentic reasons (e.g. RAG enrichment).
      */
-    createTelemetryIntegration(context?: RaindropTelemetryIntegrationOptions["context"]): RaindropTelemetryIntegration;
+    createTelemetryIntegration(contextOrOptions?: RaindropTelemetryIntegrationOptions["context"] | {
+        context?: RaindropTelemetryIntegrationOptions["context"];
+        subagentWrapping?: boolean;
+    }): RaindropTelemetryIntegration;
     events: {
         patch(eventId: string, patch: EventPatch): Promise<void>;
         addAttachments(eventId: string, attachments: Attachment[]): Promise<void>;
@@ -933,4 +1058,4 @@ type RaindropAISDKClient = {
 };
 declare function createRaindropAISDK(opts: RaindropAISDKOptions): RaindropAISDKClient;
 
-export { type AISDKChatRequestLike as A, type BuildEventPatch as B, ContextManager as C, DEFAULT_REDACT_ATTRIBUTE_KEYS as D, type EndSpanArgs as E, defaultTransformSpan as F, eventMetadata as G, eventMetadataFromChatRequest as H, type IdentifyInput as I, getContextManager as J, getCurrentRaindropCallMetadata as K, readRaindropCallMetadataFromArgs as L, redactJsonAttributeValue as M, redactSecretsInObject as N, type OtlpAnyValue as O, runWithRaindropCallMetadata as P, withCurrent as Q, REDACTED_PLACEHOLDER as R, type SelfDiagnosticsOptions as S, type TraceSpan as T, type WrapAISDKOptions as W, _resetRaindropCallMetadataStorage as _, type AISDKChatRequestMessageLike as a, type AISDKMessage as b, type AgentCallMetadata as c, type AgentWithMetadata as d, type Attachment as e, type ContextSpan as f, type CreateSpanArgs as g, DEFAULT_SECRET_KEY_NAMES as h, type EventBuilder as i, type EventMetadataOptions as j, type OtlpSpan as k, type RaindropAISDKClient as l, type RaindropAISDKContext as m, type RaindropAISDKOptions as n, type RaindropCallMetadata as o, RaindropTelemetryIntegration as p, type RaindropTelemetryIntegrationOptions as q, type SelfDiagnosticsSignalDefinition as r, type SelfDiagnosticsSignalDefinitions as s, type StartSpanArgs as t, type TransformSpanHook as u, type WrappedAI as v, type WrappedAISDK as w, _resetWarnedMissingUserId as x, createRaindropAISDK as y, currentSpan as z };
+export { withCurrent as $, type AISDKChatRequestLike as A, type BuildEventPatch as B, ContextManager as C, DEFAULT_REDACT_ATTRIBUTE_KEYS as D, type EndSpanArgs as E, createRaindropAISDK as F, currentSpan as G, defaultTransformSpan as H, type IdentifyInput as I, enterParentToolContext as J, eventMetadata as K, eventMetadataFromChatRequest as L, getContextManager as M, getCurrentParentToolContext as N, type OtlpAnyValue as O, type ParentToolContext as P, getCurrentRaindropCallMetadata as Q, REDACTED_PLACEHOLDER as R, type SelfDiagnosticsOptions as S, type TraceSpan as T, readRaindropCallMetadataFromArgs as U, redactJsonAttributeValue as V, type WrapAISDKOptions as W, redactSecretsInObject as X, runWithParentToolContext as Y, runWithRaindropCallMetadata as Z, _resetParentToolContextStorage as _, type AISDKChatRequestMessageLike as a, type AISDKMessage as b, type AgentCallMetadata as c, type AgentWithMetadata as d, type Attachment as e, type ContextSpan as f, type CreateSpanArgs as g, DEFAULT_SECRET_KEY_NAMES as h, type EventBuilder as i, type EventMetadataOptions as j, type OtlpSpan as k, type RaindropAISDKClient as l, type RaindropAISDKContext as m, type RaindropAISDKOptions as n, type RaindropCallMetadata as o, RaindropTelemetryIntegration as p, type RaindropTelemetryIntegrationOptions as q, type SelfDiagnosticsSignalDefinition as r, type SelfDiagnosticsSignalDefinitions as s, type StartSpanArgs as t, type TransformSpanHook as u, type WrappedAI as v, type WrappedAISDK as w, _resetRaindropCallMetadataStorage as x, _resetWarnedMissingUserId as y, clearParentToolContext as z };

package/dist/{index-DKdCelJA.d.ts → index-Ba_ZzUH4.d.ts}

@@ -391,6 +391,19 @@ type RaindropTelemetryIntegrationOptions = {
     eventShipper: EventShipper;
     sendTraces?: boolean;
     sendEvents?: boolean;
+    /**
+     * When `true` (default), generations started inside a tool's `execute`
+     * callback on the same async branch are wrapped in a synthetic `TOOL_CALL`
+     * + `agent.subagent` LLM marker so observability backends can render them
+     * as an agent block (and so the inner LLM's `track_partial` is suppressed).
+     *
+     * This is the right semantic for any framework that lowers sub-agents to
+     * AI SDK tools (Ash, Mastra, Claude Agent SDK, hand-rolled tool loops),
+     * not Ash-specific. Set to `false` if you have a tool whose `execute`
+     * happens to call `streamText`/`generateText` for unrelated reasons (e.g.
+     * RAG enrichment) and don't want it labelled as a sub-agent.
+     */
+    subagentWrapping?: boolean;
     debug?: boolean;
     context?: {
         userId?: string;
@@ -405,9 +418,26 @@ declare class RaindropTelemetryIntegration implements TelemetryIntegration {
     private readonly eventShipper;
     private readonly sendTraces;
     private readonly sendEvents;
+    private readonly subagentWrapping;
     private readonly debug;
     private readonly defaultContext;
     private readonly callStates;
+    /**
+     * Per-tool-call snapshot of the parent-tool ALS context taken right
+     * before `enterParentToolContext` overwrites it in `toolExecutionStart`.
+     * Kept at the integration level (rather than on `CallState`) so the
+     * snapshot survives even when the parent generation has no tracked
+     * `CallState` — e.g. the AI SDK dispatches a tool callback for a
+     * `callId` we never registered via `onStart`. Without this, the
+     * unconditional ALS enter in `toolExecutionStart` would leave
+     * `toolExecutionEnd` no way to restore the prior context, so it would
+     * clear and wipe whatever the outer scope had set.
+     *
+     * Keyed by `toolCallId` because that's the only identifier guaranteed
+     * to round-trip between `toolExecutionStart` and `toolExecutionEnd`
+     * (the `event.callId` can be the same for parallel sibling tools).
+     */
+    private readonly priorParentContexts;
     constructor(opts: RaindropTelemetryIntegrationOptions);
     private getState;
     private cleanup;
@@ -510,6 +540,92 @@ declare function readRaindropCallMetadataFromArgs(args: readonly unknown[]): Rai
 
 declare function _resetWarnedMissingUserId(): void;
 
+/**
+ * Parent tool execution context propagation.
+ *
+ * Problem
+ * ───────
+ * When a tool's `execute` callback recursively calls `streamText` /
+ * `generateText` (which is exactly how Ash lowers sub-agents, but also a
+ * common pattern in hand-rolled agent loops, Mastra, Claude Agent SDK,
+ * etc.), the inner generation's telemetry events are dispatched with no
+ * connection back to the outer tool call. The AI SDK fires `onStart` for
+ * the inner generation with its own fresh `callId`; nothing on the event
+ * tells the integration "this generation was triggered from inside tool
+ * X's execute callback."
+ *
+ * Without that linkage, observability tools have to fall back to
+ * regex-matching the prompt to guess whether a call is a sub-agent
+ * dispatch — fragile, framework-specific, and easily spoofable by user
+ * input.
+ *
+ * Solution
+ * ────────
+ * We maintain an `AsyncLocalStorage` slot that holds the currently-active
+ * parent tool call. The integration's `onToolExecutionStart` enters the
+ * slot before the AI SDK awaits `tool.execute(...)`; the inner
+ * generation's `onStart` reads from the slot to recover parent linkage.
+ * `onToolExecutionEnd` clears the slot so subsequent code in the same
+ * async branch doesn't see stale state.
+ *
+ * Async-context scoping
+ * ─────────────────────
+ * `enterWith` modifies the *current* async context, which propagates
+ * downward into any `await` continuation and into child async resources
+ * (including the awaited `tool.execute` and anything it calls). Sibling
+ * branches are unaffected: when the AI SDK dispatches tool calls via
+ * `Promise.all(map(async (tc) => ...))`, each map callback runs in its
+ * own async branch, so `enterWith` in one branch is invisible to the
+ * others. This is exactly the behaviour we need for parallel sub-agent
+ * dispatch.
+ *
+ * On runtimes that don't expose `AsyncLocalStorage` (browser, Cloudflare
+ * Workers without `nodejs_compat`), we fall back to a synchronous stack
+ * via `runWithParentToolContext` — see the `SyncFallbackStorage` in
+ * `call-metadata.ts` for the established pattern. `enterWith` becomes a
+ * silent no-op on the sync fallback, so async tool execution on those
+ * runtimes won't have parent linkage and the inner generation will
+ * render as a top-level call instead of being grouped under its caller.
+ */
+type ParentToolContext = {
+    /** The `callId` of the generation whose step kicked off this tool call. */
+    parentCallId: string;
+    /** The tool-call id from the parent generation's step. */
+    toolCallId: string;
+    /** The tool name the parent generation invoked. */
+    toolName: string;
+};
+/** Test helper — drop the storage so tests start from a fresh slot. */
+declare function _resetParentToolContextStorage(): void;
+/**
+ * Returns the active parent tool context, or `undefined` if no tool is
+ * currently executing in this async branch.
+ */
+declare function getCurrentParentToolContext(): ParentToolContext | undefined;
+/**
+ * Enter a parent tool context on the current async branch. Subsequent
+ * `await`-ed work (including the parent's `tool.execute` body) inherits
+ * the context until {@link clearParentToolContext} runs. No-op on
+ * runtimes without `enterWith` support (browser/edge sync fallback).
+ */
+declare function enterParentToolContext(ctx: ParentToolContext): void;
+/**
+ * Clear the parent tool context on the current async branch. Pairs with
+ * {@link enterParentToolContext}. No-op on runtimes without `enterWith`
+ * support.
+ *
+ * `enterWith(undefined)` is supported by Node's `AsyncLocalStorage` at
+ * runtime; the `as never` cast bypasses TypeScript's stricter typing on
+ * the shared global declaration (`store: T`).
+ */
+declare function clearParentToolContext(): void;
+/**
+ * Run `fn` with `ctx` bound as the parent tool context. The sync-fallback
+ * equivalent of `enter`/`clear` — useful in tests and any code path
+ * where you want strict block scoping.
+ */
+declare function runWithParentToolContext<R>(ctx: ParentToolContext, fn: () => R): R;
+
 /**
  * Options for creating event metadata for call-time context override.
  */
@@ -860,8 +976,17 @@ type RaindropAISDKClient = {
     /**
      * Create a TelemetryIntegration instance for direct registration with AI SDK v7+.
      * Use with `registerTelemetryIntegration()` from the `ai` package.
+     *
+     * Accepts the same `context` it has always accepted, or a full options
+     * object exposing `{ context, subagentWrapping }`. Sub-agent wrapping
+     * defaults to `true`; pass `subagentWrapping: false` to opt out for
+     * consumers whose `tool.execute` happens to call `generateText` for
+     * non-agentic reasons (e.g. RAG enrichment).
      */
-    createTelemetryIntegration(context?: RaindropTelemetryIntegrationOptions["context"]): RaindropTelemetryIntegration;
+    createTelemetryIntegration(contextOrOptions?: RaindropTelemetryIntegrationOptions["context"] | {
+        context?: RaindropTelemetryIntegrationOptions["context"];
+        subagentWrapping?: boolean;
+    }): RaindropTelemetryIntegration;
     events: {
         patch(eventId: string, patch: EventPatch): Promise<void>;
         addAttachments(eventId: string, attachments: Attachment[]): Promise<void>;
@@ -933,4 +1058,4 @@ type RaindropAISDKClient = {
 };
 declare function createRaindropAISDK(opts: RaindropAISDKOptions): RaindropAISDKClient;
 
-export { type AISDKChatRequestLike as A, type BuildEventPatch as B, ContextManager as C, DEFAULT_REDACT_ATTRIBUTE_KEYS as D, type EndSpanArgs as E, defaultTransformSpan as F, eventMetadata as G, eventMetadataFromChatRequest as H, type IdentifyInput as I, getContextManager as J, getCurrentRaindropCallMetadata as K, readRaindropCallMetadataFromArgs as L, redactJsonAttributeValue as M, redactSecretsInObject as N, type OtlpAnyValue as O, runWithRaindropCallMetadata as P, withCurrent as Q, REDACTED_PLACEHOLDER as R, type SelfDiagnosticsOptions as S, type TraceSpan as T, type WrapAISDKOptions as W, _resetRaindropCallMetadataStorage as _, type AISDKChatRequestMessageLike as a, type AISDKMessage as b, type AgentCallMetadata as c, type AgentWithMetadata as d, type Attachment as e, type ContextSpan as f, type CreateSpanArgs as g, DEFAULT_SECRET_KEY_NAMES as h, type EventBuilder as i, type EventMetadataOptions as j, type OtlpSpan as k, type RaindropAISDKClient as l, type RaindropAISDKContext as m, type RaindropAISDKOptions as n, type RaindropCallMetadata as o, RaindropTelemetryIntegration as p, type RaindropTelemetryIntegrationOptions as q, type SelfDiagnosticsSignalDefinition as r, type SelfDiagnosticsSignalDefinitions as s, type StartSpanArgs as t, type TransformSpanHook as u, type WrappedAI as v, type WrappedAISDK as w, _resetWarnedMissingUserId as x, createRaindropAISDK as y, currentSpan as z };
+export { withCurrent as $, type AISDKChatRequestLike as A, type BuildEventPatch as B, ContextManager as C, DEFAULT_REDACT_ATTRIBUTE_KEYS as D, type EndSpanArgs as E, createRaindropAISDK as F, currentSpan as G, defaultTransformSpan as H, type IdentifyInput as I, enterParentToolContext as J, eventMetadata as K, eventMetadataFromChatRequest as L, getContextManager as M, getCurrentParentToolContext as N, type OtlpAnyValue as O, type ParentToolContext as P, getCurrentRaindropCallMetadata as Q, REDACTED_PLACEHOLDER as R, type SelfDiagnosticsOptions as S, type TraceSpan as T, readRaindropCallMetadataFromArgs as U, redactJsonAttributeValue as V, type WrapAISDKOptions as W, redactSecretsInObject as X, runWithParentToolContext as Y, runWithRaindropCallMetadata as Z, _resetParentToolContextStorage as _, type AISDKChatRequestMessageLike as a, type AISDKMessage as b, type AgentCallMetadata as c, type AgentWithMetadata as d, type Attachment as e, type ContextSpan as f, type CreateSpanArgs as g, DEFAULT_SECRET_KEY_NAMES as h, type EventBuilder as i, type EventMetadataOptions as j, type OtlpSpan as k, type RaindropAISDKClient as l, type RaindropAISDKContext as m, type RaindropAISDKOptions as n, type RaindropCallMetadata as o, RaindropTelemetryIntegration as p, type RaindropTelemetryIntegrationOptions as q, type SelfDiagnosticsSignalDefinition as r, type SelfDiagnosticsSignalDefinitions as s, type StartSpanArgs as t, type TransformSpanHook as u, type WrappedAI as v, type WrappedAISDK as w, _resetRaindropCallMetadataStorage as x, _resetWarnedMissingUserId as y, clearParentToolContext as z };