@raindrop-ai/ai-sdk 0.0.29 → 0.0.31

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

@@ -378,7 +378,9 @@ interface TelemetryIntegration {
     onStepFinish?: Listener<any>;
     onEmbedStart?: Listener<any>;
     onEmbedFinish?: Listener<any>;
+    onEmbedEnd?: Listener<any>;
     onFinish?: Listener<any>;
+    onEnd?: Listener<any>;
     onError?: Listener<any>;
     executeTool?: <T>(params: {
         callId: string;
@@ -391,6 +393,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 +420,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;
@@ -433,7 +465,9 @@ declare class RaindropTelemetryIntegration implements TelemetryIntegration {
     onStepFinish: (event: any) => void;
     onEmbedStart: (event: any) => void;
     onEmbedFinish: (event: any) => void;
+    onEmbedEnd: (event: any) => void;
     onFinish: (event: any) => void;
+    onEnd: (event: any) => void;
     private finishGenerate;
     private finishEmbed;
     onError: (error: unknown) => void;
@@ -510,6 +544,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 +980,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 +1062,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.browser.d.mts

@@ -378,7 +378,9 @@ interface TelemetryIntegration {
     onStepFinish?: Listener<any>;
     onEmbedStart?: Listener<any>;
     onEmbedFinish?: Listener<any>;
+    onEmbedEnd?: Listener<any>;
     onFinish?: Listener<any>;
+    onEnd?: Listener<any>;
     onError?: Listener<any>;
     executeTool?: <T>(params: {
         callId: string;
@@ -391,6 +393,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 +420,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;
@@ -433,7 +465,9 @@ declare class RaindropTelemetryIntegration implements TelemetryIntegration {
     onStepFinish: (event: any) => void;
     onEmbedStart: (event: any) => void;
     onEmbedFinish: (event: any) => void;
+    onEmbedEnd: (event: any) => void;
     onFinish: (event: any) => void;
+    onEnd: (event: any) => void;
     private finishGenerate;
     private finishEmbed;
     onError: (error: unknown) => void;
@@ -510,6 +544,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 +980,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 +1062,4 @@ type RaindropAISDKClient = {
 };
 declare function createRaindropAISDK(opts: RaindropAISDKOptions): RaindropAISDKClient;
 
-export { type AISDKChatRequestLike, type AISDKChatRequestMessageLike, type AISDKMessage, type AgentCallMetadata, type AgentWithMetadata, type Attachment, type BuildEventPatch, ContextManager, type ContextSpan, type CreateSpanArgs, DEFAULT_REDACT_ATTRIBUTE_KEYS, DEFAULT_SECRET_KEY_NAMES, type EndSpanArgs, type EventBuilder, type EventMetadataOptions, type IdentifyInput, type OtlpAnyValue, type OtlpSpan, REDACTED_PLACEHOLDER, type RaindropAISDKClient, type RaindropAISDKContext, type RaindropAISDKOptions, type RaindropCallMetadata, RaindropTelemetryIntegration, type RaindropTelemetryIntegrationOptions, type SelfDiagnosticsOptions, type SelfDiagnosticsSignalDefinition, type SelfDiagnosticsSignalDefinitions, type StartSpanArgs, type TraceSpan, type TransformSpanHook, type WrapAISDKOptions, type WrappedAI, type WrappedAISDK, _resetRaindropCallMetadataStorage, _resetWarnedMissingUserId, createRaindropAISDK, currentSpan, defaultTransformSpan, eventMetadata, eventMetadataFromChatRequest, getContextManager, getCurrentRaindropCallMetadata, readRaindropCallMetadataFromArgs, redactJsonAttributeValue, redactSecretsInObject, runWithRaindropCallMetadata, withCurrent };
+export { type AISDKChatRequestLike, type AISDKChatRequestMessageLike, type AISDKMessage, type AgentCallMetadata, type AgentWithMetadata, type Attachment, type BuildEventPatch, ContextManager, type ContextSpan, type CreateSpanArgs, DEFAULT_REDACT_ATTRIBUTE_KEYS, DEFAULT_SECRET_KEY_NAMES, type EndSpanArgs, type EventBuilder, type EventMetadataOptions, type IdentifyInput, type OtlpAnyValue, type OtlpSpan, type ParentToolContext, REDACTED_PLACEHOLDER, type RaindropAISDKClient, type RaindropAISDKContext, type RaindropAISDKOptions, type RaindropCallMetadata, RaindropTelemetryIntegration, type RaindropTelemetryIntegrationOptions, type SelfDiagnosticsOptions, type SelfDiagnosticsSignalDefinition, type SelfDiagnosticsSignalDefinitions, type StartSpanArgs, type TraceSpan, type TransformSpanHook, type WrapAISDKOptions, type WrappedAI, type WrappedAISDK, _resetParentToolContextStorage, _resetRaindropCallMetadataStorage, _resetWarnedMissingUserId, clearParentToolContext, createRaindropAISDK, currentSpan, defaultTransformSpan, enterParentToolContext, eventMetadata, eventMetadataFromChatRequest, getContextManager, getCurrentParentToolContext, getCurrentRaindropCallMetadata, readRaindropCallMetadataFromArgs, redactJsonAttributeValue, redactSecretsInObject, runWithParentToolContext, runWithRaindropCallMetadata, withCurrent };

package/dist/index.browser.d.ts

@@ -378,7 +378,9 @@ interface TelemetryIntegration {
     onStepFinish?: Listener<any>;
     onEmbedStart?: Listener<any>;
     onEmbedFinish?: Listener<any>;
+    onEmbedEnd?: Listener<any>;
     onFinish?: Listener<any>;
+    onEnd?: Listener<any>;
     onError?: Listener<any>;
     executeTool?: <T>(params: {
         callId: string;
@@ -391,6 +393,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 +420,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;
@@ -433,7 +465,9 @@ declare class RaindropTelemetryIntegration implements TelemetryIntegration {
     onStepFinish: (event: any) => void;
     onEmbedStart: (event: any) => void;
     onEmbedFinish: (event: any) => void;
+    onEmbedEnd: (event: any) => void;
     onFinish: (event: any) => void;
+    onEnd: (event: any) => void;
     private finishGenerate;
     private finishEmbed;
     onError: (error: unknown) => void;
@@ -510,6 +544,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 +980,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 +1062,4 @@ type RaindropAISDKClient = {
 };
 declare function createRaindropAISDK(opts: RaindropAISDKOptions): RaindropAISDKClient;
 
-export { type AISDKChatRequestLike, type AISDKChatRequestMessageLike, type AISDKMessage, type AgentCallMetadata, type AgentWithMetadata, type Attachment, type BuildEventPatch, ContextManager, type ContextSpan, type CreateSpanArgs, DEFAULT_REDACT_ATTRIBUTE_KEYS, DEFAULT_SECRET_KEY_NAMES, type EndSpanArgs, type EventBuilder, type EventMetadataOptions, type IdentifyInput, type OtlpAnyValue, type OtlpSpan, REDACTED_PLACEHOLDER, type RaindropAISDKClient, type RaindropAISDKContext, type RaindropAISDKOptions, type RaindropCallMetadata, RaindropTelemetryIntegration, type RaindropTelemetryIntegrationOptions, type SelfDiagnosticsOptions, type SelfDiagnosticsSignalDefinition, type SelfDiagnosticsSignalDefinitions, type StartSpanArgs, type TraceSpan, type TransformSpanHook, type WrapAISDKOptions, type WrappedAI, type WrappedAISDK, _resetRaindropCallMetadataStorage, _resetWarnedMissingUserId, createRaindropAISDK, currentSpan, defaultTransformSpan, eventMetadata, eventMetadataFromChatRequest, getContextManager, getCurrentRaindropCallMetadata, readRaindropCallMetadataFromArgs, redactJsonAttributeValue, redactSecretsInObject, runWithRaindropCallMetadata, withCurrent };
+export { type AISDKChatRequestLike, type AISDKChatRequestMessageLike, type AISDKMessage, type AgentCallMetadata, type AgentWithMetadata, type Attachment, type BuildEventPatch, ContextManager, type ContextSpan, type CreateSpanArgs, DEFAULT_REDACT_ATTRIBUTE_KEYS, DEFAULT_SECRET_KEY_NAMES, type EndSpanArgs, type EventBuilder, type EventMetadataOptions, type IdentifyInput, type OtlpAnyValue, type OtlpSpan, type ParentToolContext, REDACTED_PLACEHOLDER, type RaindropAISDKClient, type RaindropAISDKContext, type RaindropAISDKOptions, type RaindropCallMetadata, RaindropTelemetryIntegration, type RaindropTelemetryIntegrationOptions, type SelfDiagnosticsOptions, type SelfDiagnosticsSignalDefinition, type SelfDiagnosticsSignalDefinitions, type StartSpanArgs, type TraceSpan, type TransformSpanHook, type WrapAISDKOptions, type WrappedAI, type WrappedAISDK, _resetParentToolContextStorage, _resetRaindropCallMetadataStorage, _resetWarnedMissingUserId, clearParentToolContext, createRaindropAISDK, currentSpan, defaultTransformSpan, enterParentToolContext, eventMetadata, eventMetadataFromChatRequest, getContextManager, getCurrentParentToolContext, getCurrentRaindropCallMetadata, readRaindropCallMetadataFromArgs, redactJsonAttributeValue, redactSecretsInObject, runWithParentToolContext, runWithRaindropCallMetadata, withCurrent };