@tanstack/ai 0.58.0 → 0.61.0

package/dist/esm/activities/chat/adapter.d.ts

@@ -69,6 +69,14 @@ export interface TextAdapter<TModel extends string, TProviderOptions extends Rec
      * this is the declaration/validation surface only.
      */
     readonly requires?: ReadonlyArray<CapabilityHandle>;
+    /**
+     * Declares that this adapter can consume `{ type: 'file' }` content sources
+     * (provider Files API references). `chat()` rejects file sources in preflight
+     * for adapters that don't declare this, so an adapter written before the
+     * file arm existed fails closed instead of silently mis-mapping a reference
+     * onto its URL/data branch.
+     */
+    readonly supportsFileSources?: boolean;
     /**
      * @internal Type-only properties for inference. Not assigned at runtime.
      */
@@ -156,6 +164,7 @@ export declare abstract class BaseTextAdapter<TModel extends string, TProviderOp
     abstract readonly name: string;
     readonly model: TModel;
     readonly requires?: ReadonlyArray<CapabilityHandle>;
+    readonly supportsFileSources: boolean;
     '~types': {
         providerOptions: TProviderOptions;
         inputModalities: TInputModalities;

package/dist/esm/activities/chat/adapter.js

@@ -9,6 +9,7 @@ var BaseTextAdapter = class {
 	kind = "text";
 	model;
 	requires = void 0;
+	supportsFileSources = false;
 	config;
 	constructor(config = {}, model) {
 		this.config = config;

package/dist/esm/activities/chat/adapter.js.map

@@ -1 +1 @@
-{"version":3,"file":"adapter.js","names":[],"sources":["../../../../src/activities/chat/adapter.ts"],"sourcesContent":["import type {\n  DefaultMessageMetadataByModality,\n  JSONSchema,\n  Modality,\n  TextOptions,\n  TokenUsage,\n} from '../../types'\nimport type { AdapterYieldChunk } from '../../utilities/adapter-yield-chunk'\nimport type { CapabilityHandle } from './middleware/capabilities'\n\n/**\n * Configuration for adapter instances\n */\nexport interface TextAdapterConfig {\n  apiKey?: string\n  baseUrl?: string\n  timeout?: number\n  maxRetries?: number\n  headers?: Record<string, string>\n}\n\n/**\n * Options for structured output generation.\n *\n * The internal logger is threaded through `chatOptions.logger` (inherited from\n * `TextOptions`). Adapter implementations must call `logger.request()` before\n * SDK calls, `logger.provider()` for each chunk received, and `logger.errors()`\n * in catch blocks.\n */\nexport interface StructuredOutputOptions<TProviderOptions extends object> {\n  /** Text options for the request */\n  chatOptions: TextOptions<TProviderOptions>\n  /** JSON Schema for structured output - already converted from Zod in the ai layer */\n  outputSchema: JSONSchema\n}\n\n/**\n * Result from structured output generation\n */\nexport interface StructuredOutputResult<T = unknown> {\n  /** The parsed data conforming to the schema */\n  data: T\n  /** The raw text response from the model before parsing */\n  rawText: string\n  /** Token usage information (if provided by the adapter) */\n  usage?: TokenUsage\n}\n\n/**\n * Text adapter interface with pre-resolved generics.\n *\n * An adapter is created by a provider function: `provider('model')` → `adapter`\n * All type resolution happens at the provider call site, not in this interface.\n *\n * Generic parameters:\n * - TModel: The specific model name (e.g., 'gpt-4o')\n * - TProviderOptions: Provider-specific options for this model (already resolved)\n * - TInputModalities: Supported input modalities for this model (already resolved)\n * - TMessageMetadata: Metadata types for content parts (already resolved)\n * - TToolCapabilities: Tuple of tool-kind strings supported by this model, resolved from `supports.tools`\n * - TToolCallMetadata: Metadata type that round-trips with tool calls (e.g. Gemini's `thoughtSignature`)\n * - TSystemPromptMetadata: Provider-typed metadata accepted on each\n *   `systemPrompts[i]` entry (e.g. Anthropic `cache_control`). Defaults to\n *   `never` — adapters without per-prompt metadata reject the `metadata`\n *   field at the call site.\n */\nexport interface TextAdapter<\n  TModel extends string,\n  TProviderOptions extends Record<string, any>,\n  TInputModalities extends ReadonlyArray<Modality>,\n  TMessageMetadataByModality extends DefaultMessageMetadataByModality,\n  TToolCapabilities extends ReadonlyArray<string> = ReadonlyArray<string>,\n  TToolCallMetadata = unknown,\n  TSystemPromptMetadata = never,\n> {\n  /** Discriminator for adapter kind */\n  readonly kind: 'text'\n  /** Provider name identifier (e.g., 'openai', 'anthropic') */\n  readonly name: string\n  /** The model this adapter is configured for */\n  readonly model: TModel\n\n  /**\n   * Capabilities this adapter requires at runtime. `chat()` validates that the\n   * configured middleware provides each one. Model adapters omit this; harness\n   * adapters (e.g. a future `claudeCode()`) declare e.g. `[sandboxCapability]`.\n   * Runtime access to capabilities from inside the adapter is not yet wired —\n   * this is the declaration/validation surface only.\n   */\n  readonly requires?: ReadonlyArray<CapabilityHandle>\n\n  /**\n   * @internal Type-only properties for inference. Not assigned at runtime.\n   */\n  '~types': {\n    providerOptions: TProviderOptions\n    inputModalities: TInputModalities\n    messageMetadataByModality: TMessageMetadataByModality\n    toolCapabilities: TToolCapabilities\n    toolCallMetadata: TToolCallMetadata\n    systemPromptMetadata: TSystemPromptMetadata\n  }\n\n  /**\n   * Stream text completions from the model\n   */\n  chatStream: (\n    options: TextOptions<TProviderOptions>,\n  ) => AsyncIterable<AdapterYieldChunk>\n\n  /**\n   * Generate structured output using the provider's native structured output API.\n   * This method uses stream: false and sends the JSON schema to the provider\n   * to ensure the response conforms to the expected structure.\n   *\n   * @param options - Structured output options containing chat options and JSON schema\n   * @returns Promise with the raw data (validation is done in the chat function)\n   */\n  structuredOutput: (\n    options: StructuredOutputOptions<TProviderOptions>,\n  ) => Promise<StructuredOutputResult<unknown>>\n\n  /**\n   * Stream structured output using the provider's native streaming structured\n   * output API (stream + response_format json_schema in a single request).\n   *\n   * Optional — adapters without native streaming JSON omit this method and the\n   * activity layer synthesizes a stream around the non-streaming\n   * `structuredOutput` call.\n   *\n   * Implementations must emit standard AG-UI lifecycle events (RUN_STARTED,\n   * TEXT_MESSAGE_*, RUN_FINISHED) carrying raw JSON text deltas, plus a final\n   * `CUSTOM` event named `structured-output.complete` whose `value` is\n   * `{ object, raw, reasoning? }`. Events must be timestamped when emitted so\n   * their timestamps follow stream order.\n   */\n  structuredOutputStream?: (\n    options: StructuredOutputOptions<TProviderOptions>,\n  ) => AsyncIterable<AdapterYieldChunk>\n\n  /**\n   * Declares whether the adapter supports combining `tools` and a\n   * schema-constrained final answer in a single streaming request.\n   *\n   * When `true`, the engine wires `outputSchema` into the regular\n   * `chatStream()` call and skips the separate `runStructuredFinalization`\n   * round-trip. The model's natural final turn carries the\n   * schema-constrained JSON text and the engine harvests it from the agent\n   * loop's accumulated content.\n   *\n   * When `false`, `undefined`, or the method is omitted, the engine runs\n   * the agent loop without `outputSchema` and then issues a separate\n   * `structuredOutput` / `structuredOutputStream` call against the JSON\n   * schema for finalization (the legacy path).\n   *\n   * The method receives the per-call `modelOptions` so providers whose\n   * support depends on the resolved upstream model (e.g. OpenRouter) can\n   * answer per-request. Most adapters can return a constant.\n   */\n  supportsCombinedToolsAndSchema?: (\n    modelOptions?: TProviderOptions | undefined,\n  ) => boolean\n\n  /**\n   * Where native-combined structured output is taken from.\n   *\n   * - `'text'` (default when omitted): the agent loop's accumulated\n   *   assistant text is schema JSON. The engine parses it after the loop.\n   *   HTTP adapters use this.\n   * - `'event'`: the adapter emits `structured-output.complete` during\n   *   `chatStream`. The engine must not parse accumulated prose. Harness\n   *   adapters use this.\n   */\n  combinedStructuredOutputSource?: (\n    modelOptions?: TProviderOptions | undefined,\n  ) => 'text' | 'event'\n}\n\n/**\n * A TextAdapter with any/unknown type parameters.\n * Useful as a constraint in generic functions and interfaces.\n */\nexport type AnyTextAdapter = TextAdapter<any, any, any, any, any, any, any>\n\n/**\n * Abstract base class for text adapters.\n * Extend this class to implement a text adapter for a specific provider.\n *\n * Generic parameters match TextAdapter - all pre-resolved by the provider function.\n */\nexport abstract class BaseTextAdapter<\n  TModel extends string,\n  TProviderOptions extends Record<string, any>,\n  TInputModalities extends ReadonlyArray<Modality>,\n  TMessageMetadataByModality extends DefaultMessageMetadataByModality,\n  TToolCapabilities extends ReadonlyArray<string> = ReadonlyArray<string>,\n  TToolCallMetadata = unknown,\n  TSystemPromptMetadata = never,\n> implements TextAdapter<\n  TModel,\n  TProviderOptions,\n  TInputModalities,\n  TMessageMetadataByModality,\n  TToolCapabilities,\n  TToolCallMetadata,\n  TSystemPromptMetadata\n> {\n  readonly kind = 'text' as const\n  abstract readonly name: string\n  readonly model: TModel\n  readonly requires?: ReadonlyArray<CapabilityHandle> = undefined\n\n  // Type-only property - never assigned at runtime\n  declare '~types': {\n    providerOptions: TProviderOptions\n    inputModalities: TInputModalities\n    messageMetadataByModality: TMessageMetadataByModality\n    toolCapabilities: TToolCapabilities\n    toolCallMetadata: TToolCallMetadata\n    systemPromptMetadata: TSystemPromptMetadata\n  }\n\n  protected config: TextAdapterConfig\n\n  constructor(config: TextAdapterConfig = {}, model: TModel) {\n    this.config = config\n    this.model = model\n  }\n\n  abstract chatStream(\n    options: TextOptions<TProviderOptions>,\n  ): AsyncIterable<AdapterYieldChunk>\n\n  /**\n   * Generate structured output using the provider's native structured output API.\n   * Concrete implementations should override this to use provider-specific structured output.\n   */\n  abstract structuredOutput(\n    options: StructuredOutputOptions<TProviderOptions>,\n  ): Promise<StructuredOutputResult<unknown>>\n\n  protected generateId(): string {\n    return `${this.name}-${Date.now()}-${Math.random().toString(36).substring(7)}`\n  }\n}\n"],"mappings":";;;;;;;AA8LA,IAAsB,kBAAtB,MAgBE;CACA,OAAgB;CAEhB;CACA,WAAsD,KAAA;CAYtD;CAEA,YAAY,SAA4B,CAAC,GAAG,OAAe;EACzD,KAAK,SAAS;EACd,KAAK,QAAQ;CACf;CAcA,aAA+B;EAC7B,OAAO,GAAG,KAAK,KAAK,GAAG,KAAK,IAAI,EAAE,GAAG,KAAK,OAAO,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,UAAU,CAAC;CAC7E;AACF"}
+{"version":3,"file":"adapter.js","names":[],"sources":["../../../../src/activities/chat/adapter.ts"],"sourcesContent":["import type {\n  DefaultMessageMetadataByModality,\n  JSONSchema,\n  Modality,\n  TextOptions,\n  TokenUsage,\n} from '../../types'\nimport type { AdapterYieldChunk } from '../../utilities/adapter-yield-chunk'\nimport type { CapabilityHandle } from './middleware/capabilities'\n\n/**\n * Configuration for adapter instances\n */\nexport interface TextAdapterConfig {\n  apiKey?: string\n  baseUrl?: string\n  timeout?: number\n  maxRetries?: number\n  headers?: Record<string, string>\n}\n\n/**\n * Options for structured output generation.\n *\n * The internal logger is threaded through `chatOptions.logger` (inherited from\n * `TextOptions`). Adapter implementations must call `logger.request()` before\n * SDK calls, `logger.provider()` for each chunk received, and `logger.errors()`\n * in catch blocks.\n */\nexport interface StructuredOutputOptions<TProviderOptions extends object> {\n  /** Text options for the request */\n  chatOptions: TextOptions<TProviderOptions>\n  /** JSON Schema for structured output - already converted from Zod in the ai layer */\n  outputSchema: JSONSchema\n}\n\n/**\n * Result from structured output generation\n */\nexport interface StructuredOutputResult<T = unknown> {\n  /** The parsed data conforming to the schema */\n  data: T\n  /** The raw text response from the model before parsing */\n  rawText: string\n  /** Token usage information (if provided by the adapter) */\n  usage?: TokenUsage\n}\n\n/**\n * Text adapter interface with pre-resolved generics.\n *\n * An adapter is created by a provider function: `provider('model')` → `adapter`\n * All type resolution happens at the provider call site, not in this interface.\n *\n * Generic parameters:\n * - TModel: The specific model name (e.g., 'gpt-4o')\n * - TProviderOptions: Provider-specific options for this model (already resolved)\n * - TInputModalities: Supported input modalities for this model (already resolved)\n * - TMessageMetadata: Metadata types for content parts (already resolved)\n * - TToolCapabilities: Tuple of tool-kind strings supported by this model, resolved from `supports.tools`\n * - TToolCallMetadata: Metadata type that round-trips with tool calls (e.g. Gemini's `thoughtSignature`)\n * - TSystemPromptMetadata: Provider-typed metadata accepted on each\n *   `systemPrompts[i]` entry (e.g. Anthropic `cache_control`). Defaults to\n *   `never` — adapters without per-prompt metadata reject the `metadata`\n *   field at the call site.\n */\nexport interface TextAdapter<\n  TModel extends string,\n  TProviderOptions extends Record<string, any>,\n  TInputModalities extends ReadonlyArray<Modality>,\n  TMessageMetadataByModality extends DefaultMessageMetadataByModality,\n  TToolCapabilities extends ReadonlyArray<string> = ReadonlyArray<string>,\n  TToolCallMetadata = unknown,\n  TSystemPromptMetadata = never,\n> {\n  /** Discriminator for adapter kind */\n  readonly kind: 'text'\n  /** Provider name identifier (e.g., 'openai', 'anthropic') */\n  readonly name: string\n  /** The model this adapter is configured for */\n  readonly model: TModel\n\n  /**\n   * Capabilities this adapter requires at runtime. `chat()` validates that the\n   * configured middleware provides each one. Model adapters omit this; harness\n   * adapters (e.g. a future `claudeCode()`) declare e.g. `[sandboxCapability]`.\n   * Runtime access to capabilities from inside the adapter is not yet wired —\n   * this is the declaration/validation surface only.\n   */\n  readonly requires?: ReadonlyArray<CapabilityHandle>\n\n  /**\n   * Declares that this adapter can consume `{ type: 'file' }` content sources\n   * (provider Files API references). `chat()` rejects file sources in preflight\n   * for adapters that don't declare this, so an adapter written before the\n   * file arm existed fails closed instead of silently mis-mapping a reference\n   * onto its URL/data branch.\n   */\n  readonly supportsFileSources?: boolean\n\n  /**\n   * @internal Type-only properties for inference. Not assigned at runtime.\n   */\n  '~types': {\n    providerOptions: TProviderOptions\n    inputModalities: TInputModalities\n    messageMetadataByModality: TMessageMetadataByModality\n    toolCapabilities: TToolCapabilities\n    toolCallMetadata: TToolCallMetadata\n    systemPromptMetadata: TSystemPromptMetadata\n  }\n\n  /**\n   * Stream text completions from the model\n   */\n  chatStream: (\n    options: TextOptions<TProviderOptions>,\n  ) => AsyncIterable<AdapterYieldChunk>\n\n  /**\n   * Generate structured output using the provider's native structured output API.\n   * This method uses stream: false and sends the JSON schema to the provider\n   * to ensure the response conforms to the expected structure.\n   *\n   * @param options - Structured output options containing chat options and JSON schema\n   * @returns Promise with the raw data (validation is done in the chat function)\n   */\n  structuredOutput: (\n    options: StructuredOutputOptions<TProviderOptions>,\n  ) => Promise<StructuredOutputResult<unknown>>\n\n  /**\n   * Stream structured output using the provider's native streaming structured\n   * output API (stream + response_format json_schema in a single request).\n   *\n   * Optional — adapters without native streaming JSON omit this method and the\n   * activity layer synthesizes a stream around the non-streaming\n   * `structuredOutput` call.\n   *\n   * Implementations must emit standard AG-UI lifecycle events (RUN_STARTED,\n   * TEXT_MESSAGE_*, RUN_FINISHED) carrying raw JSON text deltas, plus a final\n   * `CUSTOM` event named `structured-output.complete` whose `value` is\n   * `{ object, raw, reasoning? }`. Events must be timestamped when emitted so\n   * their timestamps follow stream order.\n   */\n  structuredOutputStream?: (\n    options: StructuredOutputOptions<TProviderOptions>,\n  ) => AsyncIterable<AdapterYieldChunk>\n\n  /**\n   * Declares whether the adapter supports combining `tools` and a\n   * schema-constrained final answer in a single streaming request.\n   *\n   * When `true`, the engine wires `outputSchema` into the regular\n   * `chatStream()` call and skips the separate `runStructuredFinalization`\n   * round-trip. The model's natural final turn carries the\n   * schema-constrained JSON text and the engine harvests it from the agent\n   * loop's accumulated content.\n   *\n   * When `false`, `undefined`, or the method is omitted, the engine runs\n   * the agent loop without `outputSchema` and then issues a separate\n   * `structuredOutput` / `structuredOutputStream` call against the JSON\n   * schema for finalization (the legacy path).\n   *\n   * The method receives the per-call `modelOptions` so providers whose\n   * support depends on the resolved upstream model (e.g. OpenRouter) can\n   * answer per-request. Most adapters can return a constant.\n   */\n  supportsCombinedToolsAndSchema?: (\n    modelOptions?: TProviderOptions | undefined,\n  ) => boolean\n\n  /**\n   * Where native-combined structured output is taken from.\n   *\n   * - `'text'` (default when omitted): the agent loop's accumulated\n   *   assistant text is schema JSON. The engine parses it after the loop.\n   *   HTTP adapters use this.\n   * - `'event'`: the adapter emits `structured-output.complete` during\n   *   `chatStream`. The engine must not parse accumulated prose. Harness\n   *   adapters use this.\n   */\n  combinedStructuredOutputSource?: (\n    modelOptions?: TProviderOptions | undefined,\n  ) => 'text' | 'event'\n}\n\n/**\n * A TextAdapter with any/unknown type parameters.\n * Useful as a constraint in generic functions and interfaces.\n */\nexport type AnyTextAdapter = TextAdapter<any, any, any, any, any, any, any>\n\n/**\n * Abstract base class for text adapters.\n * Extend this class to implement a text adapter for a specific provider.\n *\n * Generic parameters match TextAdapter - all pre-resolved by the provider function.\n */\nexport abstract class BaseTextAdapter<\n  TModel extends string,\n  TProviderOptions extends Record<string, any>,\n  TInputModalities extends ReadonlyArray<Modality>,\n  TMessageMetadataByModality extends DefaultMessageMetadataByModality,\n  TToolCapabilities extends ReadonlyArray<string> = ReadonlyArray<string>,\n  TToolCallMetadata = unknown,\n  TSystemPromptMetadata = never,\n> implements TextAdapter<\n  TModel,\n  TProviderOptions,\n  TInputModalities,\n  TMessageMetadataByModality,\n  TToolCapabilities,\n  TToolCallMetadata,\n  TSystemPromptMetadata\n> {\n  readonly kind = 'text' as const\n  abstract readonly name: string\n  readonly model: TModel\n  readonly requires?: ReadonlyArray<CapabilityHandle> = undefined\n  readonly supportsFileSources: boolean = false\n\n  // Type-only property - never assigned at runtime\n  declare '~types': {\n    providerOptions: TProviderOptions\n    inputModalities: TInputModalities\n    messageMetadataByModality: TMessageMetadataByModality\n    toolCapabilities: TToolCapabilities\n    toolCallMetadata: TToolCallMetadata\n    systemPromptMetadata: TSystemPromptMetadata\n  }\n\n  protected config: TextAdapterConfig\n\n  constructor(config: TextAdapterConfig = {}, model: TModel) {\n    this.config = config\n    this.model = model\n  }\n\n  abstract chatStream(\n    options: TextOptions<TProviderOptions>,\n  ): AsyncIterable<AdapterYieldChunk>\n\n  /**\n   * Generate structured output using the provider's native structured output API.\n   * Concrete implementations should override this to use provider-specific structured output.\n   */\n  abstract structuredOutput(\n    options: StructuredOutputOptions<TProviderOptions>,\n  ): Promise<StructuredOutputResult<unknown>>\n\n  protected generateId(): string {\n    return `${this.name}-${Date.now()}-${Math.random().toString(36).substring(7)}`\n  }\n}\n"],"mappings":";;;;;;;AAuMA,IAAsB,kBAAtB,MAgBE;CACA,OAAgB;CAEhB;CACA,WAAsD,KAAA;CACtD,sBAAwC;CAYxC;CAEA,YAAY,SAA4B,CAAC,GAAG,OAAe;EACzD,KAAK,SAAS;EACd,KAAK,QAAQ;CACf;CAcA,aAA+B;EAC7B,OAAO,GAAG,KAAK,KAAK,GAAG,KAAK,IAAI,EAAE,GAAG,KAAK,OAAO,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,UAAU,CAAC;CAC7E;AACF"}

package/dist/esm/activities/chat/agents/define-agent.d.ts

@@ -0,0 +1,81 @@
+import { SubagentInfo as AGUISubagentInfo } from '@ag-ui/core';
+import { InterruptDefinition } from '../../../interrupt-definition.js';
+import { AnyTool, ModelMessage, RunAgentResumeItem, SchemaInput, StreamChunk, UIMessage } from '../../../types.js';
+import { AnyClientTool } from '../tools/tool-definition.js';
+/**
+ * Context the library passes into {@link defineAgent} `run`.
+ */
+export interface SubagentRunContext {
+    messages: Array<UIMessage | ModelMessage>;
+    abortSignal?: AbortSignal;
+    threadId: string;
+    /** Run id for the child `chat()`. */
+    runId: string;
+    /**
+     * The run this child run continues. It is the parent chat run on the first
+     * run, and the interrupted parent run on a resume. Pass it to the child
+     * `chat()`.
+     */
+    parentRunId: string;
+    /** Answers to this child's interrupts. Pass it to the child `chat()`. */
+    resume?: Array<RunAgentResumeItem>;
+    /**
+     * The child's AG-UI run id. Stays the same when an interrupted child
+     * continues. Pass it to the child `chat()` so its middleware sees
+     * `ctx.subagentRunId`.
+     */
+    subagentRunId: string;
+    parentSubagentRunId?: string;
+}
+/**
+ * A tool a child agent can carry into client part types.
+ * Server tools and client tools both qualify.
+ */
+export type SubagentTool = AnyTool | AnyClientTool;
+/**
+ * A named child agent. `run` is a `chat()` call (or any stream of AG-UI chunks).
+ * `TTools` and `TSchema` stay on the object so `useChat({ subagents })` can
+ * type that child's parts.
+ */
+export interface DefinedAgent<TName extends string = string, TTools extends ReadonlyArray<SubagentTool> = ReadonlyArray<SubagentTool>, TSchema extends SchemaInput | undefined = SchemaInput | undefined, TInterrupts extends ReadonlyArray<InterruptDefinition<any, any, any, any>> = ReadonlyArray<InterruptDefinition<any, any, any, any>>> extends AGUISubagentInfo {
+    name: TName;
+    /** Required here: the router and the synthetic tool both read it. */
+    description: string;
+    run: (ctx: SubagentRunContext) => AsyncIterable<StreamChunk> | Promise<AsyncIterable<StreamChunk>>;
+    tools?: TTools;
+    interrupts?: TInterrupts;
+    outputSchema?: TSchema;
+    subagents?: unknown;
+}
+/**
+ * Choice options for a `decide()` router. `main` is required plus every agent name.
+ */
+export type SubagentChoiceOptions<TAgents extends ReadonlyArray<DefinedAgent>> = {
+    main: string;
+} & {
+    [K in TAgents[number]['name']]: string;
+};
+/**
+ * Define a named child agent. Pass the same object to `chat({ subagents })`.
+ * Pass the agents array to `useChat({ subagents })` when you render parts
+ * yourself. The hook uses it for types only. It does not call `run`.
+ *
+ * @example
+ * ```ts
+ * const researcher = defineAgent({
+ *   name: 'researcher',
+ *   description: 'Looks up facts',
+ *   run: (ctx) =>
+ *     chat({
+ *       adapter: openaiText('gpt-5.6'),
+ *       messages: ctx.messages,
+ *       threadId: ctx.threadId,
+ *       runId: ctx.runId,
+ *       parentRunId: ctx.parentRunId,
+ *       subagentRunId: ctx.subagentRunId,
+ *       resume: ctx.resume,
+ *     }),
+ * })
+ * ```
+ */
+export declare function defineAgent<const TName extends string, const TTools extends ReadonlyArray<SubagentTool> = readonly [], TSchema extends SchemaInput | undefined = undefined, const TInterrupts extends ReadonlyArray<InterruptDefinition<any, any, any, any>> = readonly []>(agent: DefinedAgent<TName, TTools, TSchema, TInterrupts>): DefinedAgent<TName, TTools, TSchema, TInterrupts>;

package/dist/esm/activities/chat/agents/define-agent.js

@@ -0,0 +1,34 @@
+//#region src/activities/chat/agents/define-agent.ts
+/**
+* Define a named child agent. Pass the same object to `chat({ subagents })`.
+* Pass the agents array to `useChat({ subagents })` when you render parts
+* yourself. The hook uses it for types only. It does not call `run`.
+*
+* @example
+* ```ts
+* const researcher = defineAgent({
+*   name: 'researcher',
+*   description: 'Looks up facts',
+*   run: (ctx) =>
+*     chat({
+*       adapter: openaiText('gpt-5.6'),
+*       messages: ctx.messages,
+*       threadId: ctx.threadId,
+*       runId: ctx.runId,
+*       parentRunId: ctx.parentRunId,
+*       subagentRunId: ctx.subagentRunId,
+*       resume: ctx.resume,
+*     }),
+* })
+* ```
+*/
+function defineAgent(agent) {
+	if (agent.name.trim() === "") throw new Error("defineAgent requires a non-empty name");
+	if (agent.name.trim() === "main") throw new Error("defineAgent cannot use the name 'main'. A router uses it for the parent.");
+	if (agent.description.trim() === "") throw new Error("defineAgent requires a non-empty description");
+	return agent;
+}
+//#endregion
+export { defineAgent };
+
+//# sourceMappingURL=define-agent.js.map

package/dist/esm/activities/chat/agents/define-agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-agent.js","names":[],"sources":["../../../../../src/activities/chat/agents/define-agent.ts"],"sourcesContent":["import type { SubagentInfo as AGUISubagentInfo } from '@ag-ui/core'\nimport type { InterruptDefinition } from '../../../interrupt-definition'\nimport type {\n  AnyTool,\n  ModelMessage,\n  RunAgentResumeItem,\n  SchemaInput,\n  StreamChunk,\n  UIMessage,\n} from '../../../types'\nimport type { AnyClientTool } from '../tools/tool-definition'\n\n/**\n * Context the library passes into {@link defineAgent} `run`.\n */\nexport interface SubagentRunContext {\n  messages: Array<UIMessage | ModelMessage>\n  abortSignal?: AbortSignal\n  threadId: string\n  /** Run id for the child `chat()`. */\n  runId: string\n  /**\n   * The run this child run continues. It is the parent chat run on the first\n   * run, and the interrupted parent run on a resume. Pass it to the child\n   * `chat()`.\n   */\n  parentRunId: string\n  /** Answers to this child's interrupts. Pass it to the child `chat()`. */\n  resume?: Array<RunAgentResumeItem>\n  /**\n   * The child's AG-UI run id. Stays the same when an interrupted child\n   * continues. Pass it to the child `chat()` so its middleware sees\n   * `ctx.subagentRunId`.\n   */\n  subagentRunId: string\n  parentSubagentRunId?: string\n}\n\n/**\n * A tool a child agent can carry into client part types.\n * Server tools and client tools both qualify.\n */\nexport type SubagentTool = AnyTool | AnyClientTool\n\n/**\n * A named child agent. `run` is a `chat()` call (or any stream of AG-UI chunks).\n * `TTools` and `TSchema` stay on the object so `useChat({ subagents })` can\n * type that child's parts.\n */\nexport interface DefinedAgent<\n  TName extends string = string,\n  TTools extends ReadonlyArray<SubagentTool> = ReadonlyArray<SubagentTool>,\n  TSchema extends SchemaInput | undefined = SchemaInput | undefined,\n  TInterrupts extends ReadonlyArray<InterruptDefinition<any, any, any, any>> =\n    ReadonlyArray<InterruptDefinition<any, any, any, any>>,\n> extends AGUISubagentInfo {\n  name: TName\n  /** Required here: the router and the synthetic tool both read it. */\n  description: string\n  run: (\n    ctx: SubagentRunContext,\n  ) => AsyncIterable<StreamChunk> | Promise<AsyncIterable<StreamChunk>>\n  tools?: TTools\n  interrupts?: TInterrupts\n  outputSchema?: TSchema\n  subagents?: unknown\n}\n\n/**\n * Choice options for a `decide()` router. `main` is required plus every agent name.\n */\nexport type SubagentChoiceOptions<TAgents extends ReadonlyArray<DefinedAgent>> =\n  { main: string } & {\n    [K in TAgents[number]['name']]: string\n  }\n\n/**\n * Define a named child agent. Pass the same object to `chat({ subagents })`.\n * Pass the agents array to `useChat({ subagents })` when you render parts\n * yourself. The hook uses it for types only. It does not call `run`.\n *\n * @example\n * ```ts\n * const researcher = defineAgent({\n *   name: 'researcher',\n *   description: 'Looks up facts',\n *   run: (ctx) =>\n *     chat({\n *       adapter: openaiText('gpt-5.6'),\n *       messages: ctx.messages,\n *       threadId: ctx.threadId,\n *       runId: ctx.runId,\n *       parentRunId: ctx.parentRunId,\n *       subagentRunId: ctx.subagentRunId,\n *       resume: ctx.resume,\n *     }),\n * })\n * ```\n */\nexport function defineAgent<\n  const TName extends string,\n  const TTools extends ReadonlyArray<SubagentTool> = readonly [],\n  TSchema extends SchemaInput | undefined = undefined,\n  const TInterrupts extends ReadonlyArray<\n    InterruptDefinition<any, any, any, any>\n  > = readonly [],\n>(agent: DefinedAgent<TName, TTools, TSchema, TInterrupts>) {\n  if (agent.name.trim() === '') {\n    throw new Error('defineAgent requires a non-empty name')\n  }\n  // A router returns 'main' to keep the turn on the parent.\n  if (agent.name.trim() === 'main') {\n    throw new Error(\n      \"defineAgent cannot use the name 'main'. A router uses it for the parent.\",\n    )\n  }\n  if (agent.description.trim() === '') {\n    throw new Error('defineAgent requires a non-empty description')\n  }\n  return agent\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AAmGA,SAAgB,YAOd,OAA0D;CAC1D,IAAI,MAAM,KAAK,KAAK,MAAM,IACxB,MAAM,IAAI,MAAM,uCAAuC;CAGzD,IAAI,MAAM,KAAK,KAAK,MAAM,QACxB,MAAM,IAAI,MACR,0EACF;CAEF,IAAI,MAAM,YAAY,KAAK,MAAM,IAC/B,MAAM,IAAI,MAAM,8CAA8C;CAEhE,OAAO;AACT"}

package/dist/esm/activities/chat/agents/route.d.ts

@@ -0,0 +1,53 @@
+import { boolean, choice } from '../../evaluate/index.js';
+import { DefinedAgent } from './define-agent.js';
+import { SubagentOrder, SubagentRouterPick } from './spawn.js';
+export interface SubagentRouteOptions<TAgents extends ReadonlyArray<DefinedAgent>> {
+    /**
+     * Question text for every agent. The key is the agent name.
+     * Omit this and each question uses that agent's description.
+     */
+    when?: {
+        [K in TAgents[number]['name']]: string;
+    };
+    /**
+     * Agents that run after the other selected agents. The lead group starts
+     * together. The `then` agents then run one after another in list order, and
+     * each reads the text so far. Used only when the router picks at least one
+     * agent from each group. Otherwise `pick` returns `{ names, order }`.
+     */
+    then?: ReadonlyArray<TAgents[number]['name']>;
+}
+type RouteQuestions<TAgents extends ReadonlyArray<DefinedAgent>> = {
+    [K in TAgents[number]['name']]: ReturnType<typeof boolean>;
+} & {
+    order: ReturnType<typeof choice<{
+        parallel: string;
+        sequence: string;
+    }>>;
+};
+type RouteAnswers<TAgents extends ReadonlyArray<DefinedAgent>> = {
+    [K in TAgents[number]['name']]: {
+        value: boolean;
+    };
+} & {
+    order: {
+        value: SubagentOrder;
+    };
+};
+/**
+ * Build `decide()` questions for a subagent router.
+ *
+ * One yes/no question per agent, plus an `order` choice.
+ * `pick` returns `main`, one name, `{ names, order }`, or `{ steps }`.
+ * Names follow the `agents` array order.
+ * `{ names, order }` overrides `subagents.order` for that turn.
+ * `then`: agents that run after the other selected agents. The lead group
+ * starts together. The `then` agents then run one after another in list
+ * order, and each reads the text so far. Used only when the router picks at
+ * least one agent from each group. Otherwise `pick` returns `{ names, order }`.
+ */
+export declare function subagentRoute<const TAgents extends ReadonlyArray<DefinedAgent>>(agents: TAgents, options?: SubagentRouteOptions<TAgents>): {
+    questions: RouteQuestions<TAgents>;
+    pick: (result: RouteAnswers<TAgents>) => SubagentRouterPick;
+};
+export {};

package/dist/esm/activities/chat/agents/route.js

@@ -0,0 +1,59 @@
+import { boolean, choice } from "../../evaluate/index.js";
+//#region src/activities/chat/agents/route.ts
+var ORDER_KEY = "order";
+/**
+* Build `decide()` questions for a subagent router.
+*
+* One yes/no question per agent, plus an `order` choice.
+* `pick` returns `main`, one name, `{ names, order }`, or `{ steps }`.
+* Names follow the `agents` array order.
+* `{ names, order }` overrides `subagents.order` for that turn.
+* `then`: agents that run after the other selected agents. The lead group
+* starts together. The `then` agents then run one after another in list
+* order, and each reads the text so far. Used only when the router picks at
+* least one agent from each group. Otherwise `pick` returns `{ names, order }`.
+*/
+function subagentRoute(agents, options) {
+	const namesInList = new Set(agents.map((agent) => agent.name));
+	for (const agent of agents) if (agent.name === ORDER_KEY) throw new Error("subagentRoute cannot use an agent named \"order\". Rename that agent.");
+	for (const name of options?.then ?? []) if (!namesInList.has(name)) throw new Error(`subagentRoute then includes unknown agent "${name}".`);
+	const questions = { order: choice({
+		instructions: "When more than one agent runs, how must they run?",
+		options: {
+			parallel: "Start them together. Use this when no agent must read text from another agent. Working on the same topic is not a reason to wait.",
+			sequence: "Run them in agent-list order. Use this only when a later agent must read the earlier agent text, such as research notes and then a draft article."
+		}
+	}) };
+	for (const agent of agents) {
+		const when = options?.when?.[agent.name];
+		questions[agent.name] = boolean({ instructions: when ?? agent.description });
+	}
+	function pick(result) {
+		const names = agents.map((agent) => agent.name).filter((name) => result[name].value);
+		if (names.length === 0) return "main";
+		const only = names.length === 1 ? names[0] : void 0;
+		if (only !== void 0) return only;
+		const later = new Set(options?.then ?? []);
+		const lead = names.filter((name) => !later.has(name));
+		const tail = names.filter((name) => later.has(name));
+		if (lead.length === 0 || tail.length === 0) return {
+			names,
+			order: result.order.value
+		};
+		return { steps: [lead.length > 1 ? {
+			names: lead,
+			order: "parallel"
+		} : { names: lead }, tail.length > 1 ? {
+			names: tail,
+			order: "sequence"
+		} : { names: tail }] };
+	}
+	return {
+		questions,
+		pick
+	};
+}
+//#endregion
+export { subagentRoute };
+
+//# sourceMappingURL=route.js.map

package/dist/esm/activities/chat/agents/route.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"route.js","names":[],"sources":["../../../../../src/activities/chat/agents/route.ts"],"sourcesContent":["import { boolean, choice } from '../../evaluate/index'\nimport type { DefinedAgent } from './define-agent'\nimport type { SubagentOrder, SubagentRouterPick } from './spawn'\n\nconst ORDER_KEY = 'order'\n\nexport interface SubagentRouteOptions<\n  TAgents extends ReadonlyArray<DefinedAgent>,\n> {\n  /**\n   * Question text for every agent. The key is the agent name.\n   * Omit this and each question uses that agent's description.\n   */\n  when?: { [K in TAgents[number]['name']]: string }\n  /**\n   * Agents that run after the other selected agents. The lead group starts\n   * together. The `then` agents then run one after another in list order, and\n   * each reads the text so far. Used only when the router picks at least one\n   * agent from each group. Otherwise `pick` returns `{ names, order }`.\n   */\n  then?: ReadonlyArray<TAgents[number]['name']>\n}\n\ntype RouteQuestions<TAgents extends ReadonlyArray<DefinedAgent>> = {\n  [K in TAgents[number]['name']]: ReturnType<typeof boolean>\n} & {\n  order: ReturnType<\n    typeof choice<{\n      parallel: string\n      sequence: string\n    }>\n  >\n}\n\ntype RouteAnswers<TAgents extends ReadonlyArray<DefinedAgent>> = {\n  [K in TAgents[number]['name']]: { value: boolean }\n} & {\n  order: { value: SubagentOrder }\n}\n\n/**\n * Build `decide()` questions for a subagent router.\n *\n * One yes/no question per agent, plus an `order` choice.\n * `pick` returns `main`, one name, `{ names, order }`, or `{ steps }`.\n * Names follow the `agents` array order.\n * `{ names, order }` overrides `subagents.order` for that turn.\n * `then`: agents that run after the other selected agents. The lead group\n * starts together. The `then` agents then run one after another in list\n * order, and each reads the text so far. Used only when the router picks at\n * least one agent from each group. Otherwise `pick` returns `{ names, order }`.\n */\nexport function subagentRoute<\n  const TAgents extends ReadonlyArray<DefinedAgent>,\n>(agents: TAgents, options?: SubagentRouteOptions<TAgents>) {\n  const namesInList = new Set(agents.map((agent) => agent.name))\n  for (const agent of agents) {\n    if (agent.name === ORDER_KEY) {\n      throw new Error(\n        'subagentRoute cannot use an agent named \"order\". Rename that agent.',\n      )\n    }\n  }\n  for (const name of options?.then ?? []) {\n    if (!namesInList.has(name)) {\n      throw new Error(`subagentRoute then includes unknown agent \"${name}\".`)\n    }\n  }\n\n  const questions: Record<string, unknown> = {\n    order: choice({\n      instructions: 'When more than one agent runs, how must they run?',\n      options: {\n        parallel:\n          'Start them together. Use this when no agent must read text from another agent. Working on the same topic is not a reason to wait.',\n        sequence:\n          'Run them in agent-list order. Use this only when a later agent must read the earlier agent text, such as research notes and then a draft article.',\n      },\n    }),\n  }\n\n  for (const agent of agents) {\n    const when = options?.when?.[agent.name as TAgents[number]['name']]\n    questions[agent.name] = boolean({\n      instructions: when ?? agent.description,\n    })\n  }\n\n  function pick(result: RouteAnswers<TAgents>): SubagentRouterPick {\n    const names = agents\n      .map((agent) => agent.name)\n      .filter((name) => result[name as TAgents[number]['name']].value)\n    if (names.length === 0) return 'main'\n    const only = names.length === 1 ? names[0] : undefined\n    if (only !== undefined) return only\n    const later = new Set(options?.then ?? [])\n    const lead = names.filter((name) => !later.has(name))\n    const tail = names.filter((name) => later.has(name))\n    if (lead.length === 0 || tail.length === 0) {\n      return { names, order: result.order.value }\n    }\n    return {\n      steps: [\n        lead.length > 1\n          ? { names: lead, order: 'parallel' as const }\n          : { names: lead },\n        tail.length > 1\n          ? { names: tail, order: 'sequence' as const }\n          : { names: tail },\n      ],\n    }\n  }\n\n  return { questions: questions as RouteQuestions<TAgents>, pick }\n}\n"],"mappings":";;AAIA,IAAM,YAAY;;;;;;;;;;;;;AAgDlB,SAAgB,cAEd,QAAiB,SAAyC;CAC1D,MAAM,cAAc,IAAI,IAAI,OAAO,KAAK,UAAU,MAAM,IAAI,CAAC;CAC7D,KAAK,MAAM,SAAS,QAClB,IAAI,MAAM,SAAS,WACjB,MAAM,IAAI,MACR,uEACF;CAGJ,KAAK,MAAM,QAAQ,SAAS,QAAQ,CAAC,GACnC,IAAI,CAAC,YAAY,IAAI,IAAI,GACvB,MAAM,IAAI,MAAM,8CAA8C,KAAK,GAAG;CAI1E,MAAM,YAAqC,EACzC,OAAO,OAAO;EACZ,cAAc;EACd,SAAS;GACP,UACE;GACF,UACE;EACJ;CACF,CAAC,EACH;CAEA,KAAK,MAAM,SAAS,QAAQ;EAC1B,MAAM,OAAO,SAAS,OAAO,MAAM;EACnC,UAAU,MAAM,QAAQ,QAAQ,EAC9B,cAAc,QAAQ,MAAM,YAC9B,CAAC;CACH;CAEA,SAAS,KAAK,QAAmD;EAC/D,MAAM,QAAQ,OACX,KAAK,UAAU,MAAM,IAAI,CAAC,CAC1B,QAAQ,SAAS,OAAO,KAAgC,CAAC,KAAK;EACjE,IAAI,MAAM,WAAW,GAAG,OAAO;EAC/B,MAAM,OAAO,MAAM,WAAW,IAAI,MAAM,KAAK,KAAA;EAC7C,IAAI,SAAS,KAAA,GAAW,OAAO;EAC/B,MAAM,QAAQ,IAAI,IAAI,SAAS,QAAQ,CAAC,CAAC;EACzC,MAAM,OAAO,MAAM,QAAQ,SAAS,CAAC,MAAM,IAAI,IAAI,CAAC;EACpD,MAAM,OAAO,MAAM,QAAQ,SAAS,MAAM,IAAI,IAAI,CAAC;EACnD,IAAI,KAAK,WAAW,KAAK,KAAK,WAAW,GACvC,OAAO;GAAE;GAAO,OAAO,OAAO,MAAM;EAAM;EAE5C,OAAO,EACL,OAAO,CACL,KAAK,SAAS,IACV;GAAE,OAAO;GAAM,OAAO;EAAoB,IAC1C,EAAE,OAAO,KAAK,GAClB,KAAK,SAAS,IACV;GAAE,OAAO;GAAM,OAAO;EAAoB,IAC1C,EAAE,OAAO,KAAK,CACpB,EACF;CACF;CAEA,OAAO;EAAa;EAAsC;CAAK;AACjE"}

package/dist/esm/activities/chat/agents/spawn.d.ts

@@ -0,0 +1,124 @@
+import { EventType, Interrupt, ModelMessage, RunAgentResumeItem, StreamChunk, TokenUsage, Tool, UIMessage } from '../../../types.js';
+import { SpecTokenUsage } from '../../../utilities/ag-ui-usage.js';
+import { DefinedAgent, SubagentRunContext } from './define-agent.js';
+import { ChatMiddleware } from '../middleware/types.js';
+import { SubagentTurn } from './turn.js';
+export declare const SUBAGENT_STARTED = EventType.SUBAGENT_STARTED;
+export declare const SUBAGENT_FINISHED = EventType.SUBAGENT_FINISHED;
+export declare const SUBAGENT_ERROR = EventType.SUBAGENT_ERROR;
+export type SubagentOrder = 'parallel' | 'sequence';
+export interface SubagentRouterPlan {
+    names: ReadonlyArray<string>;
+    /** Overrides `subagents.order` for this turn. */
+    order?: SubagentOrder;
+}
+export interface SubagentStep {
+    names: ReadonlyArray<string>;
+    /** Overrides `subagents.order` for this step. */
+    order?: SubagentOrder;
+}
+export interface SubagentStepsPlan {
+    steps: ReadonlyArray<SubagentStep>;
+}
+export type SubagentRouterPick = 'main' | string | ReadonlyArray<string> | SubagentRouterPlan | SubagentStepsPlan;
+export interface SubagentsBag<TAgents extends ReadonlyArray<DefinedAgent> = ReadonlyArray<DefinedAgent>> {
+    agents: TAgents;
+    router?: (ctx: {
+        messages: SubagentRunContext['messages'];
+        agents: NoInfer<TAgents>;
+        abortSignal?: AbortSignal;
+    }) => SubagentRouterPick | Promise<SubagentRouterPick>;
+    strategy?: 'exclusive' | 'handoff';
+    /**
+     * How a router list runs. `parallel` starts every name together.
+     * `sequence` runs each name after the previous one finishes, and passes
+     * that child's text to the next child.
+     */
+    order?: 'parallel' | 'sequence';
+    sandbox?: 'own' | 'inherit';
+}
+/** What the children of one parent run left behind for the parent terminal. */
+export interface SubagentSink {
+    interrupts: Array<Interrupt>;
+    /** One AG-UI entry per child model call. */
+    usage: Array<SpecTokenUsage>;
+    /** Summed full usage of the children, including cost. */
+    total?: TokenUsage;
+}
+export declare function createSubagentSink(): SubagentSink;
+/** One child to start, or a suspended child to continue. */
+export interface SpawnEntry {
+    name: string;
+    resume?: {
+        subagentRunId: string;
+        /** The child's own messages from the interrupted run. */
+        messages: Array<UIMessage | ModelMessage>;
+        entries: Array<RunAgentResumeItem>;
+        /** Text the child wrote before it stopped. */
+        text: string;
+    };
+}
+interface SpawnContext {
+    messages: SubagentRunContext['messages'];
+    abortSignal?: AbortSignal;
+    threadId: string;
+    /** The parent chat run. */
+    parentRunId: string;
+    /** The interrupted parent run, on a resume. */
+    interruptedRunId?: string;
+}
+export declare function createSubagentId(): string;
+/**
+ * Bind child interrupts to the parent run. The client resumes the parent run,
+ * so each binding must name that run. The resumed child then validates with
+ * the parent's interrupted run id.
+ */
+export declare function rebindInterrupts(interrupts: ReadonlyArray<Interrupt>, runId: string): Array<Interrupt>;
+export declare function normalizeRouterPick(pick: SubagentRouterPick, agents: ReadonlyArray<DefinedAgent>): {
+    steps: ReadonlyArray<SubagentStep>;
+};
+/** Add a finished child run's usage to the sink. */
+export declare function collectUsage(sink: SubagentSink, finished?: StreamChunk): void;
+/** A parent run's last chunk: it completed, or it failed. */
+type ParentTerminal = Extract<StreamChunk, {
+    type: 'RUN_FINISHED' | 'RUN_ERROR';
+}>;
+/**
+ * Put the children's usage on a parent terminal. `usage[]` keeps one entry per
+ * model call. `metadata.tanstack.usage` holds the summed cost and the other
+ * TanStack fields, so `fromSpecTokenUsage` reads the full total. Empties the
+ * sink, so the next parent terminal does not count it again.
+ *
+ * `RUN_ERROR` is accepted too: a turn that failed still spent whatever its
+ * children spent. Such a chunk carries no usage of its own, so `runUsage` and
+ * `fullUsage` return empty for it and the children's total stands alone.
+ */
+export declare function withChildUsage(chunk: ParentTerminal, sink: SubagentSink): ParentTerminal;
+export declare function spawnAgentStream(agent: DefinedAgent, ctx: SubagentRunContext, sink?: SubagentSink, parentToolCallId?: string): AsyncIterable<StreamChunk>;
+export declare function spawnNamedAgents(entries: ReadonlyArray<SpawnEntry>, bag: SubagentsBag, ctx: SpawnContext, sink?: SubagentSink): AsyncGenerator<import('../../..').AGUIEvent, void, any>;
+/**
+ * Text of the named direct children, in `names` order. Text from nested
+ * children stays out: their chunks carry their own id.
+ */
+export declare function collectNamedText(chunks: Array<StreamChunk>, names: ReadonlyArray<string>): string;
+/**
+ * Record the parent messages when the model calls a subagent tool, so the
+ * child reads the conversation as it is at that call.
+ */
+export declare function subagentCallMessages(names: ReadonlySet<string>): {
+    middleware: ChatMiddleware<unknown, never>;
+    messagesFor: (toolCallId: string | undefined) => ModelMessage<string | import('../../..').ContentPart<unknown, unknown, unknown, unknown, unknown>[] | null>[] | undefined;
+};
+export declare function createSyntheticSubagentTools(bag: SubagentsBag, parent: {
+    /** Messages the parent run started with. Used when no call was recorded. */
+    messages: SubagentRunContext['messages'];
+    /** The parent messages at a tool call. See subagentCallMessages. */
+    messagesFor?: (toolCallId: string | undefined) => SubagentRunContext['messages'] | undefined;
+    threadId: string;
+    runId: string;
+    interruptedRunId?: string;
+    abortSignal?: AbortSignal;
+    turn?: SubagentTurn;
+    sink: SubagentSink;
+}): Array<Tool>;
+export {};