@tanstack/ai 0.58.0 → 0.59.0

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 {};