@tanstack/ai 0.57.0 → 0.59.0

package/dist/esm/types.d.ts

@@ -4,8 +4,9 @@ import { SystemPrompt } from './system-prompts.js';
 import { CapabilityContext } from './activities/chat/middleware/capabilities.js';
 import { InterruptSubmissionError } from './interrupts.js';
 import { BilledUsage, BillingUnit, CompletionTokensDetails, PromptTokensDetails, ProviderUsageDetails, TokenUsage, UsageCostBreakdown } from '@tanstack/ai-event-client';
-import { BaseEvent as AGUIBaseEvent, CustomEvent as AGUICustomEvent, Interrupt as AGUIInterrupt, MessagesSnapshotEvent as AGUIMessagesSnapshotEvent, ReasoningEncryptedValueEvent as AGUIReasoningEncryptedValueEvent, ReasoningEndEvent as AGUIReasoningEndEvent, ReasoningMessageContentEvent as AGUIReasoningMessageContentEvent, ReasoningMessageEndEvent as AGUIReasoningMessageEndEvent, ReasoningMessageStartEvent as AGUIReasoningMessageStartEvent, ReasoningStartEvent as AGUIReasoningStartEvent, ResumeEntry as AGUIResumeEntry, RunErrorEvent as AGUIRunErrorEvent, RunFinishedEvent as AGUIRunFinishedEvent, RunFinishedOutcome as AGUIRunFinishedOutcome, RunStartedEvent as AGUIRunStartedEvent, StateDeltaEvent as AGUIStateDeltaEvent, StateSnapshotEvent as AGUIStateSnapshotEvent, StepFinishedEvent as AGUIStepFinishedEvent, StepStartedEvent as AGUIStepStartedEvent, TextMessageContentEvent as AGUITextMessageContentEvent, TextMessageEndEvent as AGUITextMessageEndEvent, TextMessageStartEvent as AGUITextMessageStartEvent, ToolCallArgsEvent as AGUIToolCallArgsEvent, ToolCallEndEvent as AGUIToolCallEndEvent, ToolCallResultEvent as AGUIToolCallResultEvent, ToolCallStartEvent as AGUIToolCallStartEvent, EventType } from '@ag-ui/core';
+import { ActivityDeltaEvent as AGUIActivityDeltaEvent, ActivitySnapshotEvent as AGUIActivitySnapshotEvent, AudioPart as AGUIAudioPart, BaseEvent as AGUIBaseEvent, ContentPart as AGUIContentPart, CustomEvent as AGUICustomEvent, DataSource as AGUIDataSource, DocumentPart as AGUIDocumentPart, FileSource as AGUIFileSource, ImagePart as AGUIImagePart, Interrupt as AGUIInterrupt, MessagesSnapshotEvent as AGUIMessagesSnapshotEvent, ReasoningEncryptedValueEvent as AGUIReasoningEncryptedValueEvent, ReasoningEndEvent as AGUIReasoningEndEvent, RawEvent as AGUIRawEvent, ReasoningMessageChunkEvent as AGUIReasoningMessageChunkEvent, ReasoningMessageContentEvent as AGUIReasoningMessageContentEvent, ReasoningMessageEndEvent as AGUIReasoningMessageEndEvent, ReasoningMessageStartEvent as AGUIReasoningMessageStartEvent, ReasoningStartEvent as AGUIReasoningStartEvent, ResumeEntry as AGUIResumeEntry, RunErrorEvent as AGUIRunErrorEvent, RunFinishedEvent as AGUIRunFinishedEvent, RunFinishedOutcome as AGUIRunFinishedOutcome, RunStartedEvent as AGUIRunStartedEvent, StateDeltaEvent as AGUIStateDeltaEvent, StateSnapshotEvent as AGUIStateSnapshotEvent, StepFinishedEvent as AGUIStepFinishedEvent, StepStartedEvent as AGUIStepStartedEvent, SubagentErrorEvent as AGUISubagentErrorEvent, SubagentFinishedEvent as AGUISubagentFinishedEvent, SubagentFinishedSuspendedOutcome as AGUISubagentFinishedSuspendedOutcome, SubagentInfo as AGUISubagentInfo, SubagentRunId as AGUISubagentRunId, SubagentStartedEvent as AGUISubagentStartedEvent, TextMessageChunkEvent as AGUITextMessageChunkEvent, TextMessageContentEvent as AGUITextMessageContentEvent, TextMessageEndEvent as AGUITextMessageEndEvent, TextMessageStartEvent as AGUITextMessageStartEvent, ToolCall as AGUIToolCall, ToolCallArgsEvent as AGUIToolCallArgsEvent, ToolCallChunkEvent as AGUIToolCallChunkEvent, ToolCallEndEvent as AGUIToolCallEndEvent, ToolCallResultEvent as AGUIToolCallResultEvent, ToolCallStartEvent as AGUIToolCallStartEvent, UrlSource as AGUIUrlSource, VideoPart as AGUIVideoPart, EventType } from '@ag-ui/core';
 import { SpecTokenUsage, TokenUsageLeftover } from './utilities/ag-ui-usage.js';
+import { SubagentWireInfo } from './utilities/subagent-wire.js';
 export type { ProviderTool } from './tools/provider-tool.js';
 /**
  * Tool call states - track the lifecycle of a tool call
@@ -87,13 +88,8 @@ export type SchemaInput = StandardJSONSchemaV1<any, any> | StandardSchemaV1<any,
  * JSON Schema at compile time.
  */
 export type InferSchemaType<T> = T extends StandardJSONSchemaV1<infer TInput, unknown> ? TInput : T extends StandardSchemaV1<infer TInput, unknown> ? TInput : unknown;
-export interface ToolCall<TMetadata = unknown> {
-    id: string;
-    type: 'function';
-    function: {
-        name: string;
-        arguments: string;
-    };
+/** AG-UI `ToolCall` with typed metadata. `function.arguments` is a JSON string. */
+export interface ToolCall<TMetadata = unknown> extends Omit<AGUIToolCall, 'metadata'> {
     /** Provider-specific metadata to carry through the tool call lifecycle.
      * Typed per-adapter via `TToolCallMetadata`. For example,
      * `@tanstack/ai-gemini` sets this to `{ thoughtSignature?: string }`. */
@@ -119,99 +115,60 @@ export interface ProviderExecutedToolMetadata {
     [key: string]: unknown;
 }
 /**
- * Supported input modality types for multimodal content.
- * - 'text': Plain text content
- * - 'image': Image content (base64 or URL)
- * - 'audio': Audio content (base64 or URL)
- * - 'video': Video content (base64 or URL)
- * - 'document': Document content like PDFs (base64 or URL)
+ * Supported input modality types for multimodal content: the `type` of each
+ * AG-UI `ContentPart` (text, image, audio, video, document).
  */
-export type Modality = 'text' | 'image' | 'audio' | 'video' | 'document';
+export type Modality = AGUIContentPart['type'];
 /**
- * Source specification for inline data content (base64).
- * Requires a mimeType to ensure providers receive proper content type information.
+ * Inline base64 content. AG-UI `DataSource`: `mimeType` is required.
  */
-export interface ContentPartDataSource {
-    /**
-     * Indicates this is inline data content.
-     */
-    type: 'data';
-    /**
-     * The base64-encoded content value.
-     */
-    value: string;
-    /**
-     * The MIME type of the content (e.g., 'image/png', 'audio/wav').
-     * Required for data sources to ensure proper handling by providers.
-     */
-    mimeType: string;
+export interface ContentPartDataSource extends AGUIDataSource {
 }
 /**
- * Source specification for URL-based content.
- * mimeType is optional as it can often be inferred from the URL or response headers.
+ * URL-referenced content. AG-UI `UrlSource`: `mimeType` is optional.
  */
-export interface ContentPartUrlSource {
-    /**
-     * Indicates this is URL-referenced content.
-     */
-    type: 'url';
-    /**
-     * HTTP(S) URL or data URI pointing to the content.
-     */
-    value: string;
-    /**
-     * Optional MIME type hint for cases where providers can't infer it from the URL.
-     */
-    mimeType?: string;
+export interface ContentPartUrlSource extends AGUIUrlSource {
 }
 /**
- * Source specification for multimodal content.
- * Discriminated union supporting both inline data (base64) and URL-based content.
- * - For 'data' sources: mimeType is required
- * - For 'url' sources: mimeType is optional
+ * A provider-issued file handle (Files API). AG-UI `FileSource`: the handle
+ * is opaque, do not fetch or parse it.
  */
-export type ContentPartSource = ContentPartDataSource | ContentPartUrlSource;
+export interface ContentPartFileSource extends AGUIFileSource {
+}
 /**
- * Image content part for multimodal messages.
+ * Where a media part's bytes come from: inline data, a URL, or a provider
+ * file handle. Same members as AG-UI `PartSource`.
+ */
+export type ContentPartSource = ContentPartDataSource | ContentPartUrlSource | ContentPartFileSource;
+/**
+ * Image content part for multimodal messages. AG-UI `ImagePart` with typed metadata.
  * @template TMetadata - Provider-specific metadata type (e.g., OpenAI's detail level)
  */
-export interface ImagePart<TMetadata = unknown> {
-    type: 'image';
-    /** Source of the image content */
-    source: ContentPartSource;
+export interface ImagePart<TMetadata = unknown> extends AGUIImagePart {
     /** Provider-specific metadata (e.g., OpenAI's detail: 'auto' | 'low' | 'high') */
     metadata?: TMetadata;
 }
 /**
- * Audio content part for multimodal messages.
+ * Audio content part for multimodal messages. AG-UI `AudioPart` with typed metadata.
  * @template TMetadata - Provider-specific metadata type
  */
-export interface AudioPart<TMetadata = unknown> {
-    type: 'audio';
-    /** Source of the audio content */
-    source: ContentPartSource;
+export interface AudioPart<TMetadata = unknown> extends AGUIAudioPart {
     /** Provider-specific metadata (e.g., format, sample rate) */
     metadata?: TMetadata;
 }
 /**
- * Video content part for multimodal messages.
+ * Video content part for multimodal messages. AG-UI `VideoPart` with typed metadata.
  * @template TMetadata - Provider-specific metadata type
  */
-export interface VideoPart<TMetadata = unknown> {
-    type: 'video';
-    /** Source of the video content */
-    source: ContentPartSource;
+export interface VideoPart<TMetadata = unknown> extends AGUIVideoPart {
     /** Provider-specific metadata (e.g., duration, resolution) */
     metadata?: TMetadata;
 }
 /**
- * Document content part for multimodal messages (e.g., PDFs).
+ * Document content part for multimodal messages (e.g., PDFs). AG-UI `DocumentPart` with typed metadata.
  * @template TMetadata - Provider-specific metadata type (e.g., Anthropic's media_type)
  */
-export interface DocumentPart<TMetadata = unknown> {
-    type: 'document';
-    /** Source of the document content */
-    source: ContentPartSource;
+export interface DocumentPart<TMetadata = unknown> extends AGUIDocumentPart {
     /** Provider-specific metadata (e.g., media_type for PDFs) */
     metadata?: TMetadata;
 }
@@ -360,6 +317,28 @@ export interface StructuredOutputPart<TData = unknown> {
     /** Populated when `status === 'error'`. */
     errorMessage?: string;
 }
+export type SubagentStatus = 'running' | 'finished' | 'error' | 'suspended';
+/**
+ * One child invocation as the client sees it. AG-UI `SubagentInfo` names the
+ * child; the other AG-UI fields come from its `SUBAGENT_STARTED`,
+ * `SUBAGENT_FINISHED` and `SUBAGENT_ERROR` events. `id` is the AG-UI
+ * `subagentRunId`. `status`, `parentRunId` and `messages` are client state the
+ * spec does not model.
+ */
+export interface SubagentHandleData extends AGUISubagentInfo, Pick<AGUISubagentStartedEvent, 'parentSubagentRunId' | 'parentToolCallId' | 'metadata'> {
+    id: AGUISubagentRunId;
+    status: SubagentStatus;
+    /** The parent chat run that started this child. */
+    parentRunId?: string;
+    /** Interrupts this child raised, while `status` is `'suspended'`. */
+    interruptIds?: AGUISubagentFinishedSuspendedOutcome['interruptIds'];
+    messages: Array<UIMessage>;
+    error?: Pick<AGUISubagentErrorEvent, 'message' | 'code'>;
+}
+export interface SubagentPart {
+    type: 'subagent';
+    subagent: SubagentHandleData;
+}
 export interface UIResourcePart {
     type: 'ui-resource';
     /** The ui:// resource object in MCP-native shape — fed straight to the renderer. */
@@ -381,7 +360,7 @@ export interface UIResourcePart {
      *  Currently always `undefined` — nothing populates this field yet. */
     meta?: Record<string, unknown>;
 }
-export type MessagePart<TData = unknown> = TextPart | ImagePart | AudioPart | VideoPart | DocumentPart | ToolCallPart | ToolResultPart | ThinkingPart | StructuredOutputPart<TData> | UIResourcePart;
+export type MessagePart<TData = unknown> = TextPart | ImagePart | AudioPart | VideoPart | DocumentPart | ToolCallPart | ToolResultPart | ThinkingPart | StructuredOutputPart<TData> | UIResourcePart | SubagentPart;
 /**
  * Shape of `metadata.tanstack` on a message.
  * `createdAt` is an ISO-8601 string.
@@ -389,6 +368,10 @@ export type MessagePart<TData = unknown> = TextPart | ImagePart | AudioPart | Vi
 export interface TanStackMessageMetadata {
     createdAt?: string;
     model?: string;
+    /** Parent chat run that produced this assistant message. */
+    runId?: string;
+    /** Card data on a child wire message. See `uiMessagesToWire`. */
+    subagent?: SubagentWireInfo;
     /** Thinking signature for a `role: 'reasoning'` fan-out message. */
     signature?: string;
     /** Per-tool-call provider metadata keyed by tool call id (e.g. Gemini thoughtSignature). */
@@ -474,6 +457,21 @@ type RuntimeContextField<TContext> = IsUnknown<TContext> extends true ? {
      */
     context: TContext;
 };
+/**
+ * Options for a single `emitCustomEvent` call, on both the tool-execution and
+ * middleware contexts.
+ */
+export interface EmitCustomEventOptions {
+    /**
+     * Keep this event in the durability batch with later chunks.
+     * CUSTOM events flush as soon as they are emitted, so a progress
+     * indicator can render at emit time. Pass `{ batch: true }` for a
+     * high-volume stream that should share appends with later output.
+     * `process.stdout`, `process.stderr`, `sandbox.file`, and
+     * `sandbox.file.diff` already batch.
+     */
+    batch?: boolean;
+}
 /**
  * Context passed to tool execute functions, providing capabilities like
  * emitting custom events during execution.
@@ -493,6 +491,8 @@ export type ToolExecutionContext<TContext = unknown> = RuntimeContextField<TCont
      *
      * @param eventName - Name of the custom event
      * @param value - Event payload value
+     * @param options - Pass `{ batch: true }` to keep this event in the
+     *   durability batch instead of flushing it immediately
      *
      * @example
      * ```ts
@@ -505,7 +505,7 @@ export type ToolExecutionContext<TContext = unknown> = RuntimeContextField<TCont
      * })
      * ```
      */
-    emitCustomEvent: (eventName: string, value: Record<string, any>) => void;
+    emitCustomEvent: (eventName: string, value: Record<string, any>, options?: EmitCustomEventOptions) => void;
 };
 export type ToolExecuteFunction<TInput extends SchemaInput | undefined = SchemaInput, TOutput extends SchemaInput | undefined = SchemaInput, TContext = unknown> = undefined extends TContext ? (args: InferSchemaType<TInput>, context?: ToolExecutionContext<TContext>) => Promise<InferSchemaType<TOutput>> | InferSchemaType<TOutput> : (args: InferSchemaType<TInput>, context: ToolExecutionContext<TContext>) => Promise<InferSchemaType<TOutput>> | InferSchemaType<TOutput>;
 /**
@@ -890,6 +890,12 @@ export interface TextOptions<TProviderOptionsSuperset extends Record<string, any
      * Surfaced for observability/middleware; not consumed by the LLM call.
      */
     parentRunId?: string;
+    /**
+     * AG-UI subagent run id when this chat runs as a child of another run.
+     * A child `chat()` passes `ctx.subagentRunId`. Middleware reads it as
+     * `ctx.subagentRunId`. Absent on a top-level run.
+     */
+    subagentRunId?: string;
     /** Application state mirrored in a STATE_SNAPSHOT before an interrupt terminal. */
     state?: unknown;
     /**
@@ -1029,13 +1035,10 @@ export interface TextMessageEndEvent extends AGUITextMessageEndEvent {
 /**
  * Emitted when a tool call starts.
  *
- * @ag-ui/core provides: `toolCallId`, `toolCallName`, `parentMessageId?`
- *
- * Field shapes are taken from AG-UI via `Pick` (not `extends`) so Zod
- * `.passthrough()` index signatures do not pollute the StreamChunk
- * discriminated union — required for {@link KnownCustomEvent} narrowing.
+ * @ag-ui/core provides: `toolCallId`, `toolCallName`, `parentMessageId?`,
+ * `subagentRunId?`
  */
-export interface ToolCallStartEvent extends Pick<AGUIToolCallStartEvent, 'toolCallId' | 'toolCallName' | 'parentMessageId' | 'timestamp' | 'rawEvent'> {
+export interface ToolCallStartEvent extends Omit<AGUIToolCallStartEvent, 'type'> {
     type: 'TOOL_CALL_START';
     /** Alias of `toolCallName`. Kept so existing stream readers still compile. */
     toolName?: string;
@@ -1052,11 +1055,9 @@ export interface ToolCallArgsEvent extends AGUIToolCallArgsEvent {
 /**
  * Emitted when a tool call completes.
  *
- * @ag-ui/core provides: `toolCallId`
- *
- * Same `Pick` (not `extends`) rationale as {@link ToolCallStartEvent}.
+ * @ag-ui/core provides: `toolCallId`, `subagentRunId?`
  */
-export interface ToolCallEndEvent extends Pick<AGUIToolCallEndEvent, 'toolCallId' | 'timestamp' | 'rawEvent'> {
+export interface ToolCallEndEvent extends Omit<AGUIToolCallEndEvent, 'type'> {
     type: 'TOOL_CALL_END';
     /** Parsed tool arguments when the adapter already parsed them. */
     input?: unknown;
@@ -1113,12 +1114,9 @@ export interface StateDeltaEvent extends AGUIStateDeltaEvent {
 /**
  * Custom event for extensibility.
  *
- * @ag-ui/core provides: `name`, `value`
- *
- * Uses `Pick` (not `extends`) so the Zod passthrough index signature does not
- * erase discriminant property access on {@link KnownCustomEvent} unions.
+ * @ag-ui/core provides: `name`, `value`, `subagentRunId?`
  */
-export interface CustomEvent extends Pick<AGUICustomEvent, 'name' | 'value' | 'timestamp' | 'rawEvent'> {
+export interface CustomEvent extends Omit<AGUICustomEvent, 'type'> {
     type: 'CUSTOM';
     metadata?: Record<string, any>;
 }
@@ -1403,10 +1401,51 @@ export interface ReasoningEndEvent extends AGUIReasoningEndEvent {
  */
 export interface ReasoningEncryptedValueEvent extends AGUIReasoningEncryptedValueEvent {
 }
+/** AG-UI 1.0 ActivitySnapshotEvent shape. */
+export interface ActivitySnapshotEvent extends AGUIActivitySnapshotEvent {
+}
+/** AG-UI 1.0 ActivityDeltaEvent shape. */
+export interface ActivityDeltaEvent extends AGUIActivityDeltaEvent {
+}
+/** AG-UI 1.0 RawEvent shape. */
+export interface RawEvent extends AGUIRawEvent {
+}
+/** AG-UI 1.0 TextMessageChunkEvent shape. */
+export interface TextMessageChunkEvent extends AGUITextMessageChunkEvent {
+}
+/** AG-UI 1.0 ToolCallChunkEvent shape. */
+export interface ToolCallChunkEvent extends AGUIToolCallChunkEvent {
+}
+/** AG-UI 1.0 ReasoningMessageChunkEvent shape. */
+export interface ReasoningMessageChunkEvent extends AGUIReasoningMessageChunkEvent {
+}
 /**
  * Union of all AG-UI events.
  */
-export type AGUIEvent = RunStartedEvent | RunFinishedEvent | RunErrorEvent | TextMessageStartEvent | TextMessageContentEvent | TextMessageEndEvent | ToolCallStartEvent | ToolCallArgsEvent | ToolCallEndEvent | ToolCallResultEvent | StepStartedEvent | StepFinishedEvent | MessagesSnapshotEvent | StateSnapshotEvent | StateDeltaEvent | CustomEvent | ReasoningStartEvent | ReasoningMessageStartEvent | ReasoningMessageContentEvent | ReasoningMessageEndEvent | ReasoningEndEvent | ReasoningEncryptedValueEvent;
+export type AGUIEvent = ActivitySnapshotEvent | ActivityDeltaEvent | RawEvent | TextMessageChunkEvent | ToolCallChunkEvent | ReasoningMessageChunkEvent | RunStartedEvent | RunFinishedEvent | RunErrorEvent | TextMessageStartEvent | TextMessageContentEvent | TextMessageEndEvent | ToolCallStartEvent | ToolCallArgsEvent | ToolCallEndEvent | ToolCallResultEvent | StepStartedEvent | StepFinishedEvent | MessagesSnapshotEvent | StateSnapshotEvent | StateDeltaEvent | CustomEvent | ReasoningStartEvent | ReasoningMessageStartEvent | ReasoningMessageContentEvent | ReasoningMessageEndEvent | ReasoningEndEvent | ReasoningEncryptedValueEvent | SubagentStartedEvent | SubagentFinishedEvent | SubagentErrorEvent;
+/**
+ * A child agent started. The later chunks for that child carry the same
+ * `subagentRunId`.
+ *
+ * @ag-ui/core provides: `subagentRunId`, `name`, `description?`,
+ * `parentSubagentRunId?`, `parentToolCallId?`, `parentMessageId?`, `metadata?`
+ */
+export interface SubagentStartedEvent extends AGUISubagentStartedEvent {
+}
+/**
+ * A child agent's segment of this run ended.
+ *
+ * @ag-ui/core provides: `subagentRunId`, `result?`, `outcome?`
+ */
+export interface SubagentFinishedEvent extends AGUISubagentFinishedEvent {
+}
+/**
+ * A child agent failed. The parent run can continue.
+ *
+ * @ag-ui/core provides: `subagentRunId`, `message`, `code?`
+ */
+export interface SubagentErrorEvent extends AGUISubagentErrorEvent {
+}
 /**
  * Chunk returned by the SDK during streaming chat completions.
  * Uses the AG-UI protocol event format.

package/dist/esm/utilities/adapter-yield-chunk.d.ts

@@ -3,8 +3,9 @@ import { ContentPart, StreamChunk, ToolOutputState } from '../types.js';
 /**
  * Adapter / engine yield before normalize. Public StreamChunk is spec-only.
  * This type still allows the old extra fields.
+ * Extras never override a spec field (see WithAdapterExtras).
  */
-export type AdapterYieldChunk = StreamChunk & {
+type AdapterExtras = {
     model?: string;
     finishReason?: 'stop' | 'length' | 'content_filter' | 'tool_calls' | null;
     usage?: any;
@@ -29,3 +30,6 @@ export type AdapterYieldChunk = StreamChunk & {
     threadId?: string;
     runId?: string;
 };
+type WithAdapterExtras<T> = T extends StreamChunk ? T & Omit<AdapterExtras, keyof T> : never;
+export type AdapterYieldChunk = WithAdapterExtras<StreamChunk>;
+export {};

package/dist/esm/utilities/ag-ui-usage.d.ts

@@ -1,14 +1,7 @@
+import { TokenUsage as SpecTokenUsage } from '@ag-ui/core';
 import { TokenUsage } from '../types.js';
 /** AG-UI spec `usage[]` item (provider/model labels + token counts only). */
-export interface SpecTokenUsage {
-    provider?: string;
-    model?: string;
-    inputTokens?: number;
-    outputTokens?: number;
-    totalTokens?: number;
-    reasoningTokens?: number;
-    cachedInputTokens?: number;
-}
+export type { TokenUsage as SpecTokenUsage } from '@ag-ui/core';
 export interface ToSpecTokenUsageOptions {
     provider?: string;
     model?: string;
@@ -20,5 +13,12 @@ export declare function toSpecTokenUsage(usage: TokenUsage, options?: ToSpecToke
     usage: Array<SpecTokenUsage>;
     leftover?: TokenUsageLeftover;
 };
+/**
+ * Add two usage totals, as for a parent run and its children. Numbers add
+ * up. `billed` adds up only in the same unit. `providerUsageDetails` is
+ * opaque, so the latest one stays. `@tanstack/ai-persistence` sums per-run
+ * usage with the same rules.
+ */
+export declare function addTokenUsage(current: TokenUsage, next: TokenUsage): TokenUsage;
 export declare function rebuildTokenUsage(usage: unknown, leftover?: TokenUsageLeftover): TokenUsage | undefined;
 export declare function fromSpecTokenUsage(usage: ReadonlyArray<SpecTokenUsage> | undefined, leftover?: TokenUsageLeftover): TokenUsage | undefined;

package/dist/esm/utilities/ag-ui-usage.js

@@ -21,6 +21,7 @@ function toSpecTokenUsage(usage, options) {
 	};
 	const cachedInputTokens = promptTokensDetails?.cachedTokens;
 	if (cachedInputTokens !== void 0) spec.cachedInputTokens = cachedInputTokens;
+	if (promptTokensDetails?.cacheWriteTokens !== void 0) spec.cacheWriteInputTokens = promptTokensDetails.cacheWriteTokens;
 	const reasoningTokens = completionTokensDetails?.reasoningTokens;
 	if (reasoningTokens !== void 0) spec.reasoningTokens = reasoningTokens;
 	const leftoverPrompt = promptTokensDetails ? definedDetails(withoutKey(promptTokensDetails, "cachedTokens")) : void 0;
@@ -34,17 +35,79 @@ function toSpecTokenUsage(usage, options) {
 		})
 	};
 }
+function sumNumbers(current, next) {
+	if (!current) return next;
+	if (!next) return current;
+	const result = { ...current };
+	for (const key of Object.keys(next)) {
+		const value = next[key];
+		if (typeof value !== "number") continue;
+		const previous = current[key];
+		result[key] = (typeof previous === "number" ? previous : 0) + value;
+	}
+	return result;
+}
+function sumOptional(current, next) {
+	if (current === void 0) return next;
+	if (next === void 0) return current;
+	return current + next;
+}
+/**
+* Add two usage totals, as for a parent run and its children. Numbers add
+* up. `billed` adds up only in the same unit. `providerUsageDetails` is
+* opaque, so the latest one stays. `@tanstack/ai-persistence` sums per-run
+* usage with the same rules.
+*/
+function addTokenUsage(current, next) {
+	const promptTokensDetails = sumNumbers(current.promptTokensDetails, next.promptTokensDetails);
+	const completionTokensDetails = sumNumbers(current.completionTokensDetails, next.completionTokensDetails);
+	const costDetails = sumNumbers(current.costDetails, next.costDetails);
+	const cost = sumOptional(current.cost, next.cost);
+	const durationSeconds = sumOptional(current.durationSeconds, next.durationSeconds);
+	const unitsBilled = sumOptional(current.unitsBilled, next.unitsBilled);
+	const billed = current.billed && next.billed && current.billed.unit === next.billed.unit ? {
+		quantity: current.billed.quantity + next.billed.quantity,
+		unit: current.billed.unit
+	} : next.billed ?? current.billed;
+	const providerUsageDetails = next.providerUsageDetails ?? current.providerUsageDetails;
+	return {
+		...current,
+		...next,
+		promptTokens: current.promptTokens + next.promptTokens,
+		completionTokens: current.completionTokens + next.completionTokens,
+		totalTokens: current.totalTokens + next.totalTokens,
+		...promptTokensDetails && { promptTokensDetails },
+		...completionTokensDetails && { completionTokensDetails },
+		...cost !== void 0 && { cost },
+		...costDetails && { costDetails },
+		...durationSeconds !== void 0 && { durationSeconds },
+		...unitsBilled !== void 0 && { unitsBilled },
+		...billed && { billed },
+		...providerUsageDetails && { providerUsageDetails }
+	};
+}
 function rebuildTokenUsage(usage, leftover) {
 	if (isTanstackUsage(usage)) return usage;
 	if (Array.isArray(usage)) return fromSpecTokenUsage(usage, leftover);
 	return fromSpecTokenUsage(void 0, leftover);
 }
 function fromSpecTokenUsage(usage, leftover) {
-	const spec = usage?.[0];
-	if (spec == null && leftover == null) return;
+	const spec = usage?.reduce((total, entry) => {
+		for (const key of [
+			"inputTokens",
+			"outputTokens",
+			"totalTokens",
+			"cachedInputTokens",
+			"cacheWriteInputTokens",
+			"reasoningTokens"
+		]) if (entry[key] !== void 0) total[key] = (total[key] ?? 0) + entry[key];
+		return total;
+	}, {});
+	if ((usage === void 0 || usage.length === 0) && leftover == null) return;
 	const { promptTokensDetails: leftoverPromptDetails, completionTokensDetails: leftoverCompletionDetails, ...leftoverRest } = leftover ?? {};
 	const promptTokensDetails = definedDetails({
 		...spec?.cachedInputTokens !== void 0 ? { cachedTokens: spec.cachedInputTokens } : {},
+		...spec?.cacheWriteInputTokens !== void 0 ? { cacheWriteTokens: spec.cacheWriteInputTokens } : {},
 		...leftoverPromptDetails
 	});
 	const completionTokensDetails = definedDetails({
@@ -61,6 +124,6 @@ function fromSpecTokenUsage(usage, leftover) {
 	};
 }
 //#endregion
-export { fromSpecTokenUsage, isTanstackUsage, rebuildTokenUsage, toSpecTokenUsage };
+export { addTokenUsage, fromSpecTokenUsage, isTanstackUsage, rebuildTokenUsage, toSpecTokenUsage };
 
 //# sourceMappingURL=ag-ui-usage.js.map

package/dist/esm/utilities/ag-ui-usage.js.map

@@ -1 +1 @@
-{"version":3,"file":"ag-ui-usage.js","names":[],"sources":["../../../src/utilities/ag-ui-usage.ts"],"sourcesContent":["import type { TokenUsage } from '../types'\n\n/** AG-UI spec `usage[]` item (provider/model labels + token counts only). */\nexport interface SpecTokenUsage {\n  provider?: string\n  model?: string\n  inputTokens?: number\n  outputTokens?: number\n  totalTokens?: number\n  reasoningTokens?: number\n  cachedInputTokens?: number\n}\n\nexport interface ToSpecTokenUsageOptions {\n  provider?: string\n  model?: string\n}\n\n/** TokenUsage fields that have no AG-UI `usage[]` equivalent. */\nexport type TokenUsageLeftover = Omit<\n  TokenUsage,\n  'promptTokens' | 'completionTokens' | 'totalTokens'\n>\n\nfunction definedDetails<T extends object>(value: T): T | undefined {\n  return Object.keys(value).length > 0 ? value : undefined\n}\n\nfunction withoutKey<T extends object, K extends keyof T>(\n  value: T,\n  key: K,\n): Omit<T, K> {\n  const next = { ...value }\n  delete next[key]\n  return next\n}\n\nexport function isTanstackUsage(usage: unknown): usage is TokenUsage {\n  return (\n    typeof usage === 'object' &&\n    usage != null &&\n    !Array.isArray(usage) &&\n    'promptTokens' in usage\n  )\n}\n\nexport function toSpecTokenUsage(\n  usage: TokenUsage,\n  options?: ToSpecTokenUsageOptions,\n): { usage: Array<SpecTokenUsage>; leftover?: TokenUsageLeftover } {\n  const {\n    promptTokens,\n    completionTokens,\n    totalTokens,\n    promptTokensDetails,\n    completionTokensDetails,\n    ...rest\n  } = usage\n\n  const spec: SpecTokenUsage = {\n    ...(options?.provider !== undefined ? { provider: options.provider } : {}),\n    ...(options?.model !== undefined ? { model: options.model } : {}),\n    inputTokens: promptTokens,\n    outputTokens: completionTokens,\n    totalTokens,\n  }\n  const cachedInputTokens = promptTokensDetails?.cachedTokens\n  if (cachedInputTokens !== undefined) {\n    spec.cachedInputTokens = cachedInputTokens\n  }\n  const reasoningTokens = completionTokensDetails?.reasoningTokens\n  if (reasoningTokens !== undefined) {\n    spec.reasoningTokens = reasoningTokens\n  }\n\n  const leftoverPrompt = promptTokensDetails\n    ? definedDetails(withoutKey(promptTokensDetails, 'cachedTokens'))\n    : undefined\n  const leftoverCompletion = completionTokensDetails\n    ? definedDetails(withoutKey(completionTokensDetails, 'reasoningTokens'))\n    : undefined\n\n  return {\n    usage: [spec],\n    leftover: definedDetails({\n      ...rest,\n      ...(leftoverPrompt !== undefined\n        ? { promptTokensDetails: leftoverPrompt }\n        : {}),\n      ...(leftoverCompletion !== undefined\n        ? { completionTokensDetails: leftoverCompletion }\n        : {}),\n    }),\n  }\n}\n\nexport function rebuildTokenUsage(\n  usage: unknown,\n  leftover?: TokenUsageLeftover,\n): TokenUsage | undefined {\n  if (isTanstackUsage(usage)) {\n    return usage\n  }\n  if (Array.isArray(usage)) {\n    return fromSpecTokenUsage(usage, leftover)\n  }\n  return fromSpecTokenUsage(undefined, leftover)\n}\n\nexport function fromSpecTokenUsage(\n  usage: ReadonlyArray<SpecTokenUsage> | undefined,\n  leftover?: TokenUsageLeftover,\n): TokenUsage | undefined {\n  const spec = usage?.[0]\n  if (spec == null && leftover == null) {\n    return undefined\n  }\n\n  const {\n    promptTokensDetails: leftoverPromptDetails,\n    completionTokensDetails: leftoverCompletionDetails,\n    ...leftoverRest\n  } = leftover ?? {}\n\n  const promptTokensDetails = definedDetails({\n    ...(spec?.cachedInputTokens !== undefined\n      ? { cachedTokens: spec.cachedInputTokens }\n      : {}),\n    ...leftoverPromptDetails,\n  })\n  const completionTokensDetails = definedDetails({\n    ...(spec?.reasoningTokens !== undefined\n      ? { reasoningTokens: spec.reasoningTokens }\n      : {}),\n    ...leftoverCompletionDetails,\n  })\n\n  return {\n    promptTokens: spec?.inputTokens ?? 0,\n    completionTokens: spec?.outputTokens ?? 0,\n    totalTokens: spec?.totalTokens ?? 0,\n    ...leftoverRest,\n    ...(promptTokensDetails !== undefined ? { promptTokensDetails } : {}),\n    ...(completionTokensDetails !== undefined\n      ? { completionTokensDetails }\n      : {}),\n  }\n}\n"],"mappings":";AAwBA,SAAS,eAAiC,OAAyB;CACjE,OAAO,OAAO,KAAK,KAAK,CAAC,CAAC,SAAS,IAAI,QAAQ,KAAA;AACjD;AAEA,SAAS,WACP,OACA,KACY;CACZ,MAAM,OAAO,EAAE,GAAG,MAAM;CACxB,OAAO,KAAK;CACZ,OAAO;AACT;AAEA,SAAgB,gBAAgB,OAAqC;CACnE,OACE,OAAO,UAAU,YACjB,SAAS,QACT,CAAC,MAAM,QAAQ,KAAK,KACpB,kBAAkB;AAEtB;AAEA,SAAgB,iBACd,OACA,SACiE;CACjE,MAAM,EACJ,cACA,kBACA,aACA,qBACA,yBACA,GAAG,SACD;CAEJ,MAAM,OAAuB;EAC3B,GAAI,SAAS,aAAa,KAAA,IAAY,EAAE,UAAU,QAAQ,SAAS,IAAI,CAAC;EACxE,GAAI,SAAS,UAAU,KAAA,IAAY,EAAE,OAAO,QAAQ,MAAM,IAAI,CAAC;EAC/D,aAAa;EACb,cAAc;EACd;CACF;CACA,MAAM,oBAAoB,qBAAqB;CAC/C,IAAI,sBAAsB,KAAA,GACxB,KAAK,oBAAoB;CAE3B,MAAM,kBAAkB,yBAAyB;CACjD,IAAI,oBAAoB,KAAA,GACtB,KAAK,kBAAkB;CAGzB,MAAM,iBAAiB,sBACnB,eAAe,WAAW,qBAAqB,cAAc,CAAC,IAC9D,KAAA;CACJ,MAAM,qBAAqB,0BACvB,eAAe,WAAW,yBAAyB,iBAAiB,CAAC,IACrE,KAAA;CAEJ,OAAO;EACL,OAAO,CAAC,IAAI;EACZ,UAAU,eAAe;GACvB,GAAG;GACH,GAAI,mBAAmB,KAAA,IACnB,EAAE,qBAAqB,eAAe,IACtC,CAAC;GACL,GAAI,uBAAuB,KAAA,IACvB,EAAE,yBAAyB,mBAAmB,IAC9C,CAAC;EACP,CAAC;CACH;AACF;AAEA,SAAgB,kBACd,OACA,UACwB;CACxB,IAAI,gBAAgB,KAAK,GACvB,OAAO;CAET,IAAI,MAAM,QAAQ,KAAK,GACrB,OAAO,mBAAmB,OAAO,QAAQ;CAE3C,OAAO,mBAAmB,KAAA,GAAW,QAAQ;AAC/C;AAEA,SAAgB,mBACd,OACA,UACwB;CACxB,MAAM,OAAO,QAAQ;CACrB,IAAI,QAAQ,QAAQ,YAAY,MAC9B;CAGF,MAAM,EACJ,qBAAqB,uBACrB,yBAAyB,2BACzB,GAAG,iBACD,YAAY,CAAC;CAEjB,MAAM,sBAAsB,eAAe;EACzC,GAAI,MAAM,sBAAsB,KAAA,IAC5B,EAAE,cAAc,KAAK,kBAAkB,IACvC,CAAC;EACL,GAAG;CACL,CAAC;CACD,MAAM,0BAA0B,eAAe;EAC7C,GAAI,MAAM,oBAAoB,KAAA,IAC1B,EAAE,iBAAiB,KAAK,gBAAgB,IACxC,CAAC;EACL,GAAG;CACL,CAAC;CAED,OAAO;EACL,cAAc,MAAM,eAAe;EACnC,kBAAkB,MAAM,gBAAgB;EACxC,aAAa,MAAM,eAAe;EAClC,GAAG;EACH,GAAI,wBAAwB,KAAA,IAAY,EAAE,oBAAoB,IAAI,CAAC;EACnE,GAAI,4BAA4B,KAAA,IAC5B,EAAE,wBAAwB,IAC1B,CAAC;CACP;AACF"}
+{"version":3,"file":"ag-ui-usage.js","names":[],"sources":["../../../src/utilities/ag-ui-usage.ts"],"sourcesContent":["import type { TokenUsage as SpecTokenUsage } from '@ag-ui/core'\nimport type { TokenUsage } from '../types'\n\n/** AG-UI spec `usage[]` item (provider/model labels + token counts only). */\nexport type { TokenUsage as SpecTokenUsage } from '@ag-ui/core'\n\nexport interface ToSpecTokenUsageOptions {\n  provider?: string\n  model?: string\n}\n\n/** TokenUsage fields that have no AG-UI `usage[]` equivalent. */\nexport type TokenUsageLeftover = Omit<\n  TokenUsage,\n  'promptTokens' | 'completionTokens' | 'totalTokens'\n>\n\nfunction definedDetails<T extends object>(value: T): T | undefined {\n  return Object.keys(value).length > 0 ? value : undefined\n}\n\nfunction withoutKey<T extends object, K extends keyof T>(\n  value: T,\n  key: K,\n): Omit<T, K> {\n  const next = { ...value }\n  delete next[key]\n  return next\n}\n\nexport function isTanstackUsage(usage: unknown): usage is TokenUsage {\n  return (\n    typeof usage === 'object' &&\n    usage != null &&\n    !Array.isArray(usage) &&\n    'promptTokens' in usage\n  )\n}\n\nexport function toSpecTokenUsage(\n  usage: TokenUsage,\n  options?: ToSpecTokenUsageOptions,\n): { usage: Array<SpecTokenUsage>; leftover?: TokenUsageLeftover } {\n  const {\n    promptTokens,\n    completionTokens,\n    totalTokens,\n    promptTokensDetails,\n    completionTokensDetails,\n    ...rest\n  } = usage\n\n  const spec: SpecTokenUsage = {\n    ...(options?.provider !== undefined ? { provider: options.provider } : {}),\n    ...(options?.model !== undefined ? { model: options.model } : {}),\n    inputTokens: promptTokens,\n    outputTokens: completionTokens,\n    totalTokens,\n  }\n  const cachedInputTokens = promptTokensDetails?.cachedTokens\n  if (cachedInputTokens !== undefined) {\n    spec.cachedInputTokens = cachedInputTokens\n  }\n  if (promptTokensDetails?.cacheWriteTokens !== undefined) {\n    spec.cacheWriteInputTokens = promptTokensDetails.cacheWriteTokens\n  }\n  const reasoningTokens = completionTokensDetails?.reasoningTokens\n  if (reasoningTokens !== undefined) {\n    spec.reasoningTokens = reasoningTokens\n  }\n\n  // cacheWriteTokens stays in the leftover too, so clients built before\n  // cacheWriteInputTokens existed still rebuild it.\n  const leftoverPrompt = promptTokensDetails\n    ? definedDetails(withoutKey(promptTokensDetails, 'cachedTokens'))\n    : undefined\n  const leftoverCompletion = completionTokensDetails\n    ? definedDetails(withoutKey(completionTokensDetails, 'reasoningTokens'))\n    : undefined\n\n  return {\n    usage: [spec],\n    leftover: definedDetails({\n      ...rest,\n      ...(leftoverPrompt !== undefined\n        ? { promptTokensDetails: leftoverPrompt }\n        : {}),\n      ...(leftoverCompletion !== undefined\n        ? { completionTokensDetails: leftoverCompletion }\n        : {}),\n    }),\n  }\n}\n\nfunction sumNumbers<T extends object>(\n  current: T | undefined,\n  next: T | undefined,\n): T | undefined {\n  if (!current) return next\n  if (!next) return current\n  const result = { ...current }\n  for (const key of Object.keys(next) as Array<keyof T>) {\n    const value = next[key]\n    if (typeof value !== 'number') continue\n    const previous = current[key]\n    result[key] = ((typeof previous === 'number' ? previous : 0) +\n      value) as T[keyof T]\n  }\n  return result\n}\n\nfunction sumOptional(current?: number, next?: number): number | undefined {\n  if (current === undefined) return next\n  if (next === undefined) return current\n  return current + next\n}\n\n/**\n * Add two usage totals, as for a parent run and its children. Numbers add\n * up. `billed` adds up only in the same unit. `providerUsageDetails` is\n * opaque, so the latest one stays. `@tanstack/ai-persistence` sums per-run\n * usage with the same rules.\n */\nexport function addTokenUsage(\n  current: TokenUsage,\n  next: TokenUsage,\n): TokenUsage {\n  const promptTokensDetails = sumNumbers(\n    current.promptTokensDetails,\n    next.promptTokensDetails,\n  )\n  const completionTokensDetails = sumNumbers(\n    current.completionTokensDetails,\n    next.completionTokensDetails,\n  )\n  const costDetails = sumNumbers(current.costDetails, next.costDetails)\n  const cost = sumOptional(current.cost, next.cost)\n  const durationSeconds = sumOptional(\n    current.durationSeconds,\n    next.durationSeconds,\n  )\n  const unitsBilled = sumOptional(current.unitsBilled, next.unitsBilled)\n  const billed =\n    current.billed && next.billed && current.billed.unit === next.billed.unit\n      ? {\n          quantity: current.billed.quantity + next.billed.quantity,\n          unit: current.billed.unit,\n        }\n      : (next.billed ?? current.billed)\n  const providerUsageDetails =\n    next.providerUsageDetails ?? current.providerUsageDetails\n  return {\n    ...current,\n    ...next,\n    promptTokens: current.promptTokens + next.promptTokens,\n    completionTokens: current.completionTokens + next.completionTokens,\n    totalTokens: current.totalTokens + next.totalTokens,\n    ...(promptTokensDetails && { promptTokensDetails }),\n    ...(completionTokensDetails && { completionTokensDetails }),\n    ...(cost !== undefined && { cost }),\n    ...(costDetails && { costDetails }),\n    ...(durationSeconds !== undefined && { durationSeconds }),\n    ...(unitsBilled !== undefined && { unitsBilled }),\n    ...(billed && { billed }),\n    ...(providerUsageDetails && { providerUsageDetails }),\n  }\n}\n\nexport function rebuildTokenUsage(\n  usage: unknown,\n  leftover?: TokenUsageLeftover,\n): TokenUsage | undefined {\n  if (isTanstackUsage(usage)) {\n    return usage\n  }\n  if (Array.isArray(usage)) {\n    return fromSpecTokenUsage(usage, leftover)\n  }\n  return fromSpecTokenUsage(undefined, leftover)\n}\n\nexport function fromSpecTokenUsage(\n  usage: ReadonlyArray<SpecTokenUsage> | undefined,\n  leftover?: TokenUsageLeftover,\n): TokenUsage | undefined {\n  const spec = usage?.reduce<SpecTokenUsage>((total, entry) => {\n    for (const key of [\n      'inputTokens',\n      'outputTokens',\n      'totalTokens',\n      'cachedInputTokens',\n      'cacheWriteInputTokens',\n      'reasoningTokens',\n    ] as const) {\n      if (entry[key] !== undefined) total[key] = (total[key] ?? 0) + entry[key]\n    }\n    return total\n  }, {})\n  if ((usage === undefined || usage.length === 0) && leftover == null) {\n    return undefined\n  }\n\n  const {\n    promptTokensDetails: leftoverPromptDetails,\n    completionTokensDetails: leftoverCompletionDetails,\n    ...leftoverRest\n  } = leftover ?? {}\n\n  const promptTokensDetails = definedDetails({\n    ...(spec?.cachedInputTokens !== undefined\n      ? { cachedTokens: spec.cachedInputTokens }\n      : {}),\n    ...(spec?.cacheWriteInputTokens !== undefined\n      ? { cacheWriteTokens: spec.cacheWriteInputTokens }\n      : {}),\n    ...leftoverPromptDetails,\n  })\n  const completionTokensDetails = definedDetails({\n    ...(spec?.reasoningTokens !== undefined\n      ? { reasoningTokens: spec.reasoningTokens }\n      : {}),\n    ...leftoverCompletionDetails,\n  })\n\n  return {\n    promptTokens: spec?.inputTokens ?? 0,\n    completionTokens: spec?.outputTokens ?? 0,\n    totalTokens: spec?.totalTokens ?? 0,\n    ...leftoverRest,\n    ...(promptTokensDetails !== undefined ? { promptTokensDetails } : {}),\n    ...(completionTokensDetails !== undefined\n      ? { completionTokensDetails }\n      : {}),\n  }\n}\n"],"mappings":";AAiBA,SAAS,eAAiC,OAAyB;CACjE,OAAO,OAAO,KAAK,KAAK,CAAC,CAAC,SAAS,IAAI,QAAQ,KAAA;AACjD;AAEA,SAAS,WACP,OACA,KACY;CACZ,MAAM,OAAO,EAAE,GAAG,MAAM;CACxB,OAAO,KAAK;CACZ,OAAO;AACT;AAEA,SAAgB,gBAAgB,OAAqC;CACnE,OACE,OAAO,UAAU,YACjB,SAAS,QACT,CAAC,MAAM,QAAQ,KAAK,KACpB,kBAAkB;AAEtB;AAEA,SAAgB,iBACd,OACA,SACiE;CACjE,MAAM,EACJ,cACA,kBACA,aACA,qBACA,yBACA,GAAG,SACD;CAEJ,MAAM,OAAuB;EAC3B,GAAI,SAAS,aAAa,KAAA,IAAY,EAAE,UAAU,QAAQ,SAAS,IAAI,CAAC;EACxE,GAAI,SAAS,UAAU,KAAA,IAAY,EAAE,OAAO,QAAQ,MAAM,IAAI,CAAC;EAC/D,aAAa;EACb,cAAc;EACd;CACF;CACA,MAAM,oBAAoB,qBAAqB;CAC/C,IAAI,sBAAsB,KAAA,GACxB,KAAK,oBAAoB;CAE3B,IAAI,qBAAqB,qBAAqB,KAAA,GAC5C,KAAK,wBAAwB,oBAAoB;CAEnD,MAAM,kBAAkB,yBAAyB;CACjD,IAAI,oBAAoB,KAAA,GACtB,KAAK,kBAAkB;CAKzB,MAAM,iBAAiB,sBACnB,eAAe,WAAW,qBAAqB,cAAc,CAAC,IAC9D,KAAA;CACJ,MAAM,qBAAqB,0BACvB,eAAe,WAAW,yBAAyB,iBAAiB,CAAC,IACrE,KAAA;CAEJ,OAAO;EACL,OAAO,CAAC,IAAI;EACZ,UAAU,eAAe;GACvB,GAAG;GACH,GAAI,mBAAmB,KAAA,IACnB,EAAE,qBAAqB,eAAe,IACtC,CAAC;GACL,GAAI,uBAAuB,KAAA,IACvB,EAAE,yBAAyB,mBAAmB,IAC9C,CAAC;EACP,CAAC;CACH;AACF;AAEA,SAAS,WACP,SACA,MACe;CACf,IAAI,CAAC,SAAS,OAAO;CACrB,IAAI,CAAC,MAAM,OAAO;CAClB,MAAM,SAAS,EAAE,GAAG,QAAQ;CAC5B,KAAK,MAAM,OAAO,OAAO,KAAK,IAAI,GAAqB;EACrD,MAAM,QAAQ,KAAK;EACnB,IAAI,OAAO,UAAU,UAAU;EAC/B,MAAM,WAAW,QAAQ;EACzB,OAAO,QAAS,OAAO,aAAa,WAAW,WAAW,KACxD;CACJ;CACA,OAAO;AACT;AAEA,SAAS,YAAY,SAAkB,MAAmC;CACxE,IAAI,YAAY,KAAA,GAAW,OAAO;CAClC,IAAI,SAAS,KAAA,GAAW,OAAO;CAC/B,OAAO,UAAU;AACnB;;;;;;;AAQA,SAAgB,cACd,SACA,MACY;CACZ,MAAM,sBAAsB,WAC1B,QAAQ,qBACR,KAAK,mBACP;CACA,MAAM,0BAA0B,WAC9B,QAAQ,yBACR,KAAK,uBACP;CACA,MAAM,cAAc,WAAW,QAAQ,aAAa,KAAK,WAAW;CACpE,MAAM,OAAO,YAAY,QAAQ,MAAM,KAAK,IAAI;CAChD,MAAM,kBAAkB,YACtB,QAAQ,iBACR,KAAK,eACP;CACA,MAAM,cAAc,YAAY,QAAQ,aAAa,KAAK,WAAW;CACrE,MAAM,SACJ,QAAQ,UAAU,KAAK,UAAU,QAAQ,OAAO,SAAS,KAAK,OAAO,OACjE;EACE,UAAU,QAAQ,OAAO,WAAW,KAAK,OAAO;EAChD,MAAM,QAAQ,OAAO;CACvB,IACC,KAAK,UAAU,QAAQ;CAC9B,MAAM,uBACJ,KAAK,wBAAwB,QAAQ;CACvC,OAAO;EACL,GAAG;EACH,GAAG;EACH,cAAc,QAAQ,eAAe,KAAK;EAC1C,kBAAkB,QAAQ,mBAAmB,KAAK;EAClD,aAAa,QAAQ,cAAc,KAAK;EACxC,GAAI,uBAAuB,EAAE,oBAAoB;EACjD,GAAI,2BAA2B,EAAE,wBAAwB;EACzD,GAAI,SAAS,KAAA,KAAa,EAAE,KAAK;EACjC,GAAI,eAAe,EAAE,YAAY;EACjC,GAAI,oBAAoB,KAAA,KAAa,EAAE,gBAAgB;EACvD,GAAI,gBAAgB,KAAA,KAAa,EAAE,YAAY;EAC/C,GAAI,UAAU,EAAE,OAAO;EACvB,GAAI,wBAAwB,EAAE,qBAAqB;CACrD;AACF;AAEA,SAAgB,kBACd,OACA,UACwB;CACxB,IAAI,gBAAgB,KAAK,GACvB,OAAO;CAET,IAAI,MAAM,QAAQ,KAAK,GACrB,OAAO,mBAAmB,OAAO,QAAQ;CAE3C,OAAO,mBAAmB,KAAA,GAAW,QAAQ;AAC/C;AAEA,SAAgB,mBACd,OACA,UACwB;CACxB,MAAM,OAAO,OAAO,QAAwB,OAAO,UAAU;EAC3D,KAAK,MAAM,OAAO;GAChB;GACA;GACA;GACA;GACA;GACA;EACF,GACE,IAAI,MAAM,SAAS,KAAA,GAAW,MAAM,QAAQ,MAAM,QAAQ,KAAK,MAAM;EAEvE,OAAO;CACT,GAAG,CAAC,CAAC;CACL,KAAK,UAAU,KAAA,KAAa,MAAM,WAAW,MAAM,YAAY,MAC7D;CAGF,MAAM,EACJ,qBAAqB,uBACrB,yBAAyB,2BACzB,GAAG,iBACD,YAAY,CAAC;CAEjB,MAAM,sBAAsB,eAAe;EACzC,GAAI,MAAM,sBAAsB,KAAA,IAC5B,EAAE,cAAc,KAAK,kBAAkB,IACvC,CAAC;EACL,GAAI,MAAM,0BAA0B,KAAA,IAChC,EAAE,kBAAkB,KAAK,sBAAsB,IAC/C,CAAC;EACL,GAAG;CACL,CAAC;CACD,MAAM,0BAA0B,eAAe;EAC7C,GAAI,MAAM,oBAAoB,KAAA,IAC1B,EAAE,iBAAiB,KAAK,gBAAgB,IACxC,CAAC;EACL,GAAG;CACL,CAAC;CAED,OAAO;EACL,cAAc,MAAM,eAAe;EACnC,kBAAkB,MAAM,gBAAgB;EACxC,aAAa,MAAM,eAAe;EAClC,GAAG;EACH,GAAI,wBAAwB,KAAA,IAAY,EAAE,oBAAoB,IAAI,CAAC;EACnE,GAAI,4BAA4B,KAAA,IAC5B,EAAE,wBAAwB,IAC1B,CAAC;CACP;AACF"}

package/dist/esm/utilities/ag-ui-wire.js

@@ -1,5 +1,6 @@
 import { tanstackMetadata } from "./merge-metadata.js";
 import { normalizeToolResult } from "./tool-result.js";
+import { wireSubagentInfo, wireSubagentRunId } from "./subagent-wire.js";
 import { coerceCreatedAt, modelMessageToUIMessage } from "../activities/chat/messages.js";
 //#region src/utilities/ag-ui-wire.ts
 function isRecord(value) {
@@ -110,6 +111,7 @@ function uiMessagesToWire(messages, options) {
 				metadata: rebuiltToolMetadata(void 0, void 0, void 0, result)
 			});
 		}
+		for (const part of parts) if (part.type === "subagent") wire.push(...subagentToWire(part, options));
 	}
 	return wire;
 }
@@ -142,6 +144,7 @@ function messageMetadata(msg, parts, includeSnapshotStructuredOutput) {
 	const previousTanstack = tanstackMetadata(msg);
 	const tanstack = {};
 	if (previousTanstack?.model !== void 0) tanstack.model = previousTanstack.model;
+	if (previousTanstack?.runId !== void 0) tanstack.runId = previousTanstack.runId;
 	if (previousTanstack?.signature !== void 0) tanstack.signature = previousTanstack.signature;
 	const createdAt = coerceCreatedAt(msg.createdAt);
 	if (createdAt !== void 0) tanstack.createdAt = createdAt.toISOString();
@@ -175,6 +178,59 @@ function collectText(parts) {
 	else if (p.type === "structured-output" && p.status === "complete" && p.raw !== "") out.push(p.raw);
 	return out.join("");
 }
+/**
+* A child's messages, tagged with its AG-UI `subagentRunId`. The card data
+* rides in `metadata.tanstack.subagent`, so the other side can rebuild the
+* card and continue a suspended child.
+*/
+function subagentToWire(part, options) {
+	const { subagent } = part;
+	const info = {
+		name: subagent.name,
+		status: subagent.status,
+		...subagent.description !== void 0 && { description: subagent.description },
+		...subagent.error !== void 0 && { error: subagent.error },
+		...subagent.interruptIds !== void 0 && { interruptIds: subagent.interruptIds },
+		...subagent.parentSubagentRunId !== void 0 && { parentSubagentRunId: subagent.parentSubagentRunId },
+		...subagent.parentToolCallId !== void 0 && { parentToolCallId: subagent.parentToolCallId },
+		...subagent.metadata !== void 0 && { metadata: subagent.metadata }
+	};
+	const child = uiMessagesToWire(subagent.messages, options);
+	const own = child.some((message) => wireSubagentRunId(message) === void 0);
+	return (own ? child : [{
+		id: `subagent:${subagent.id}`,
+		role: "assistant"
+	}, ...child]).map((message, index) => {
+		const nestedId = wireSubagentRunId(message);
+		if (nestedId !== void 0) {
+			const nested = wireSubagentInfo(message);
+			if (!nested || nested.parentSubagentRunId !== void 0) return message;
+			return withSubagentInfo(message, nestedId, {
+				...nested,
+				parentSubagentRunId: subagent.id
+			});
+		}
+		return withSubagentInfo(message, subagent.id, !own && index === 0 ? {
+			...info,
+			placeholder: true
+		} : info);
+	});
+}
+function withSubagentInfo(message, subagentRunId, info) {
+	const metadata = isRecord(message.metadata) ? message.metadata : {};
+	const tanstack = isRecord(metadata.tanstack) ? metadata.tanstack : {};
+	return {
+		...message,
+		subagentRunId,
+		metadata: {
+			...metadata,
+			tanstack: {
+				...tanstack,
+				subagent: info
+			}
+		}
+	};
+}
 function collectUserContent(parts) {
 	if (!parts.some((p) => p.type === "image" || p.type === "audio" || p.type === "video" || p.type === "document")) return collectText(parts);
 	const out = [];