@tanstack/ai 0.57.0 → 0.59.0

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

@@ -0,0 +1,78 @@
+import { splitSubagentWire, subagentWireText, wireSubagentRunId } from "../../../utilities/subagent-wire.js";
+//#region src/activities/chat/agents/turn.ts
+/** Key of the router plan in `SUBAGENT_STARTED` metadata (`metadata.tanstack`). */
+var SUBAGENT_PLAN_KEY = "subagentPlan";
+function planOf(metadata) {
+	const tanstack = metadata?.tanstack;
+	if (typeof tanstack !== "object" || tanstack === null) return void 0;
+	return tanstack[SUBAGENT_PLAN_KEY];
+}
+function uiText(messages) {
+	return messages.flatMap((message) => message.role === "assistant" ? message.parts.flatMap((part) => part.type === "text" && part.content.trim() !== "" ? [part.content.trim()] : []) : []).join("\n\n");
+}
+function partInterruptIds(part) {
+	return [...part.subagent.interruptIds ?? [], ...part.subagent.messages.flatMap((message) => message.parts.flatMap((nested) => nested.type === "subagent" ? partInterruptIds(nested) : []))];
+}
+function groupInterruptIds(group) {
+	return [...group.info.interruptIds ?? [], ...splitSubagentWire(group.messages).groups.flatMap(groupInterruptIds)];
+}
+/**
+* Find the children of the trailing assistant turn that `resume` answers.
+* Returns undefined when no child owns a resume entry.
+*/
+function readSubagentTurn(messages, resume) {
+	if (!resume || resume.length === 0) return void 0;
+	const lastUser = messages.findLastIndex((message) => message.role === "user" && wireSubagentRunId(message) === void 0);
+	const before = messages.slice(0, lastUser + 1);
+	const turn = messages.slice(lastUser + 1);
+	const found = [];
+	let plan;
+	for (const message of turn) {
+		if (!("parts" in message)) continue;
+		for (const part of message.parts) {
+			if (part.type !== "subagent") continue;
+			plan ??= planOf(part.subagent.metadata);
+			found.push({
+				subagentRunId: part.subagent.id,
+				name: part.subagent.name,
+				status: part.subagent.status,
+				...part.subagent.parentToolCallId !== void 0 && { parentToolCallId: part.subagent.parentToolCallId },
+				messages: part.subagent.messages,
+				text: uiText(part.subagent.messages),
+				ids: new Set(partInterruptIds(part))
+			});
+		}
+	}
+	for (const group of splitSubagentWire(turn).groups) {
+		plan ??= planOf(group.info.metadata);
+		found.push({
+			subagentRunId: group.id,
+			name: group.info.name,
+			status: group.info.status,
+			...group.info.parentToolCallId !== void 0 && { parentToolCallId: group.info.parentToolCallId },
+			messages: group.messages,
+			text: subagentWireText(group.messages),
+			ids: new Set(groupInterruptIds(group))
+		});
+	}
+	const owned = /* @__PURE__ */ new Set();
+	const children = found.map(({ ids, ...child }) => {
+		const entries = resume.filter((entry) => ids.has(entry.interruptId));
+		for (const entry of entries) owned.add(entry.interruptId);
+		return {
+			...child,
+			resume: entries
+		};
+	});
+	if (owned.size === 0) return void 0;
+	return {
+		before,
+		children,
+		rest: resume.filter((entry) => !owned.has(entry.interruptId)),
+		...plan !== void 0 && { plan }
+	};
+}
+//#endregion
+export { SUBAGENT_PLAN_KEY, readSubagentTurn };
+
+//# sourceMappingURL=turn.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"turn.js","names":[],"sources":["../../../../../src/activities/chat/agents/turn.ts"],"sourcesContent":["import {\n  splitSubagentWire,\n  subagentWireText,\n  wireSubagentRunId,\n} from '../../../utilities/subagent-wire'\nimport type { SubagentWireGroup } from '../../../utilities/subagent-wire'\nimport type {\n  ModelMessage,\n  RunAgentResumeItem,\n  SubagentPart,\n  SubagentStatus,\n  UIMessage,\n} from '../../../types'\n\ntype AnyMessage = UIMessage | ModelMessage\n\nexport interface SubagentTurnChild {\n  subagentRunId: string\n  name: string\n  status: SubagentStatus\n  parentToolCallId?: string\n  /** The child's own messages from the earlier run. */\n  messages: Array<AnyMessage>\n  /** Text the child wrote. */\n  text: string\n  /** Resume entries for this child and its nested children. */\n  resume: Array<RunAgentResumeItem>\n}\n\n/** The interrupted turn that a resume continues. */\nexport interface SubagentTurn {\n  /**\n   * Messages up to and including the last top-level user message. Child wire\n   * messages do not count.\n   */\n  before: Array<AnyMessage>\n  /** Direct children of the parent in that turn. */\n  children: Array<SubagentTurnChild>\n  /** Resume entries that no child owns. They belong to the parent run. */\n  rest: Array<RunAgentResumeItem>\n  /** The router plan of the earlier run, from the children's metadata. */\n  plan?: unknown\n}\n\n/** Key of the router plan in `SUBAGENT_STARTED` metadata (`metadata.tanstack`). */\nexport const SUBAGENT_PLAN_KEY = 'subagentPlan'\n\nfunction planOf(metadata: Record<string, unknown> | undefined): unknown {\n  const tanstack = metadata?.tanstack\n  if (typeof tanstack !== 'object' || tanstack === null) return undefined\n  return (tanstack as Record<string, unknown>)[SUBAGENT_PLAN_KEY]\n}\n\nfunction uiText(messages: ReadonlyArray<UIMessage>) {\n  return messages\n    .flatMap((message) =>\n      message.role === 'assistant'\n        ? message.parts.flatMap((part) =>\n            part.type === 'text' && part.content.trim() !== ''\n              ? [part.content.trim()]\n              : [],\n          )\n        : [],\n    )\n    .join('\\n\\n')\n}\n\nfunction partInterruptIds(part: SubagentPart): Array<string> {\n  return [\n    ...(part.subagent.interruptIds ?? []),\n    ...part.subagent.messages.flatMap((message) =>\n      message.parts.flatMap((nested) =>\n        nested.type === 'subagent' ? partInterruptIds(nested) : [],\n      ),\n    ),\n  ]\n}\n\nfunction groupInterruptIds(group: SubagentWireGroup<unknown>): Array<string> {\n  return [\n    ...(group.info.interruptIds ?? []),\n    ...splitSubagentWire(group.messages).groups.flatMap(groupInterruptIds),\n  ]\n}\n\n/**\n * Find the children of the trailing assistant turn that `resume` answers.\n * Returns undefined when no child owns a resume entry.\n */\nexport function readSubagentTurn(\n  messages: ReadonlyArray<AnyMessage>,\n  resume: ReadonlyArray<RunAgentResumeItem> | undefined,\n): SubagentTurn | undefined {\n  if (!resume || resume.length === 0) return undefined\n  const lastUser = messages.findLastIndex(\n    (message) =>\n      message.role === 'user' && wireSubagentRunId(message) === undefined,\n  )\n  const before = messages.slice(0, lastUser + 1)\n  const turn = messages.slice(lastUser + 1)\n\n  const found: Array<Omit<SubagentTurnChild, 'resume'> & { ids: Set<string> }> =\n    []\n  let plan: unknown\n  for (const message of turn) {\n    if (!('parts' in message)) continue\n    for (const part of message.parts) {\n      if (part.type !== 'subagent') continue\n      plan ??= planOf(part.subagent.metadata)\n      found.push({\n        subagentRunId: part.subagent.id,\n        name: part.subagent.name,\n        status: part.subagent.status,\n        ...(part.subagent.parentToolCallId !== undefined && {\n          parentToolCallId: part.subagent.parentToolCallId,\n        }),\n        messages: part.subagent.messages,\n        text: uiText(part.subagent.messages),\n        ids: new Set(partInterruptIds(part)),\n      })\n    }\n  }\n  for (const group of splitSubagentWire(turn).groups) {\n    plan ??= planOf(group.info.metadata)\n    found.push({\n      subagentRunId: group.id,\n      name: group.info.name,\n      status: group.info.status,\n      ...(group.info.parentToolCallId !== undefined && {\n        parentToolCallId: group.info.parentToolCallId,\n      }),\n      messages: group.messages,\n      text: subagentWireText(group.messages),\n      ids: new Set(groupInterruptIds(group)),\n    })\n  }\n\n  const owned = new Set<string>()\n  const children = found.map(({ ids, ...child }) => {\n    const entries = resume.filter((entry) => ids.has(entry.interruptId))\n    for (const entry of entries) owned.add(entry.interruptId)\n    return { ...child, resume: entries }\n  })\n  if (owned.size === 0) return undefined\n  return {\n    before,\n    children,\n    rest: resume.filter((entry) => !owned.has(entry.interruptId)),\n    ...(plan !== undefined && { plan }),\n  }\n}\n"],"mappings":";;;AA6CA,IAAa,oBAAoB;AAEjC,SAAS,OAAO,UAAwD;CACtE,MAAM,WAAW,UAAU;CAC3B,IAAI,OAAO,aAAa,YAAY,aAAa,MAAM,OAAO,KAAA;CAC9D,OAAQ,SAAqC;AAC/C;AAEA,SAAS,OAAO,UAAoC;CAClD,OAAO,SACJ,SAAS,YACR,QAAQ,SAAS,cACb,QAAQ,MAAM,SAAS,SACrB,KAAK,SAAS,UAAU,KAAK,QAAQ,KAAK,MAAM,KAC5C,CAAC,KAAK,QAAQ,KAAK,CAAC,IACpB,CAAC,CACP,IACA,CAAC,CACP,CAAC,CACA,KAAK,MAAM;AAChB;AAEA,SAAS,iBAAiB,MAAmC;CAC3D,OAAO,CACL,GAAI,KAAK,SAAS,gBAAgB,CAAC,GACnC,GAAG,KAAK,SAAS,SAAS,SAAS,YACjC,QAAQ,MAAM,SAAS,WACrB,OAAO,SAAS,aAAa,iBAAiB,MAAM,IAAI,CAAC,CAC3D,CACF,CACF;AACF;AAEA,SAAS,kBAAkB,OAAkD;CAC3E,OAAO,CACL,GAAI,MAAM,KAAK,gBAAgB,CAAC,GAChC,GAAG,kBAAkB,MAAM,QAAQ,CAAC,CAAC,OAAO,QAAQ,iBAAiB,CACvE;AACF;;;;;AAMA,SAAgB,iBACd,UACA,QAC0B;CAC1B,IAAI,CAAC,UAAU,OAAO,WAAW,GAAG,OAAO,KAAA;CAC3C,MAAM,WAAW,SAAS,eACvB,YACC,QAAQ,SAAS,UAAU,kBAAkB,OAAO,MAAM,KAAA,CAC9D;CACA,MAAM,SAAS,SAAS,MAAM,GAAG,WAAW,CAAC;CAC7C,MAAM,OAAO,SAAS,MAAM,WAAW,CAAC;CAExC,MAAM,QACJ,CAAC;CACH,IAAI;CACJ,KAAK,MAAM,WAAW,MAAM;EAC1B,IAAI,EAAE,WAAW,UAAU;EAC3B,KAAK,MAAM,QAAQ,QAAQ,OAAO;GAChC,IAAI,KAAK,SAAS,YAAY;GAC9B,SAAS,OAAO,KAAK,SAAS,QAAQ;GACtC,MAAM,KAAK;IACT,eAAe,KAAK,SAAS;IAC7B,MAAM,KAAK,SAAS;IACpB,QAAQ,KAAK,SAAS;IACtB,GAAI,KAAK,SAAS,qBAAqB,KAAA,KAAa,EAClD,kBAAkB,KAAK,SAAS,iBAClC;IACA,UAAU,KAAK,SAAS;IACxB,MAAM,OAAO,KAAK,SAAS,QAAQ;IACnC,KAAK,IAAI,IAAI,iBAAiB,IAAI,CAAC;GACrC,CAAC;EACH;CACF;CACA,KAAK,MAAM,SAAS,kBAAkB,IAAI,CAAC,CAAC,QAAQ;EAClD,SAAS,OAAO,MAAM,KAAK,QAAQ;EACnC,MAAM,KAAK;GACT,eAAe,MAAM;GACrB,MAAM,MAAM,KAAK;GACjB,QAAQ,MAAM,KAAK;GACnB,GAAI,MAAM,KAAK,qBAAqB,KAAA,KAAa,EAC/C,kBAAkB,MAAM,KAAK,iBAC/B;GACA,UAAU,MAAM;GAChB,MAAM,iBAAiB,MAAM,QAAQ;GACrC,KAAK,IAAI,IAAI,kBAAkB,KAAK,CAAC;EACvC,CAAC;CACH;CAEA,MAAM,wBAAQ,IAAI,IAAY;CAC9B,MAAM,WAAW,MAAM,KAAK,EAAE,KAAK,GAAG,YAAY;EAChD,MAAM,UAAU,OAAO,QAAQ,UAAU,IAAI,IAAI,MAAM,WAAW,CAAC;EACnE,KAAK,MAAM,SAAS,SAAS,MAAM,IAAI,MAAM,WAAW;EACxD,OAAO;GAAE,GAAG;GAAO,QAAQ;EAAQ;CACrC,CAAC;CACD,IAAI,MAAM,SAAS,GAAG,OAAO,KAAA;CAC7B,OAAO;EACL;EACA;EACA,MAAM,OAAO,QAAQ,UAAU,CAAC,MAAM,IAAI,MAAM,WAAW,CAAC;EAC5D,GAAI,SAAS,KAAA,KAAa,EAAE,KAAK;CACnC;AACF"}

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

@@ -1,4 +1,6 @@
 import { InterruptDefinition } from '../../interrupt-definition.js';
+import { DefinedAgent } from './agents/define-agent.js';
+import { SubagentsBag } from './agents/spawn.js';
 import { AnyTextAdapter } from './adapter.js';
 import { AnyTool, ChatStream, ConstrainedModelMessage, InferSchemaType, LazyToolsConfig, ModelMessage, ProviderTool, SchemaInput, StructuredOutputStream, TextOptions, UIMessage } from '../../types.js';
 import { AnyChatMiddleware, ChatMiddleware } from './middleware/types.js';
@@ -45,7 +47,7 @@ type RuntimeContextOption<TTools, TMiddleware, TContext> = [
 };
 type ExactMiddlewareOption<TTools, TContext, TInterrupts extends ReadonlyArray<InterruptDefinition<any, any, any, any>>, TMiddleware extends Array<unknown> | undefined> = [TMiddleware] extends [undefined] ? Array<RegistryChatMiddleware<InlineChatContext<TTools, TContext>, NoInfer<TInterrupts>>> : TMiddleware & (TMiddleware extends Array<RegistryChatMiddleware<InlineChatContext<TTools, NoInfer<TContext>>, NoInfer<TInterrupts>>> ? Array<RegistryChatMiddleware<InlineChatContext<TTools, TContext>, NoInfer<TInterrupts>>> : CheckInterruptRegistry<TInterrupts, TMiddleware>) & CheckCoverage<Extract<TMiddleware, ReadonlyArray<AnyChatMiddleware>>>;
 type TextActivityOptionsWithContext<TAdapter extends AnyTextAdapter, TSchema extends SchemaInput | undefined, TStream extends boolean, TTools extends TextActivityOptions<TAdapter, TSchema, TStream, any>['tools'], TInterrupts extends ReadonlyArray<InterruptDefinition<any, any, any, any>> = [
-], TContext = unknown, TMiddleware extends Array<unknown> | undefined = undefined> = Omit<TextActivityOptions<TAdapter, TSchema, TStream, any>, 'tools' | 'middleware' | 'context' | 'interrupts'> & {
+], TContext = unknown, TMiddleware extends Array<unknown> | undefined = undefined, TAgents extends ReadonlyArray<DefinedAgent> = ReadonlyArray<DefinedAgent>> = Omit<TextActivityOptions<TAdapter, TSchema, TStream, any, TAgents>, 'tools' | 'middleware' | 'context' | 'interrupts'> & {
     tools?: TTools;
     interrupts?: TInterrupts & CheckUniqueInterruptDefinitions<TInterrupts>;
     middleware?: ExactMiddlewareOption<TTools, TContext, TInterrupts, TMiddleware>;
@@ -59,7 +61,7 @@ type TextActivityOptionsWithContext<TAdapter extends AnyTextAdapter, TSchema ext
  * @template TStream - Whether to stream the output (default: true)
  * @template TContext - Runtime context value threaded to middleware hooks and server tools
  */
-export interface TextActivityOptions<TAdapter extends AnyTextAdapter, TSchema extends SchemaInput | undefined, TStream extends boolean, TContext = unknown> {
+export interface TextActivityOptions<TAdapter extends AnyTextAdapter, TSchema extends SchemaInput | undefined, TStream extends boolean, TContext = unknown, TAgents extends ReadonlyArray<DefinedAgent> = ReadonlyArray<DefinedAgent>> {
     /** The text adapter to use (created by a provider function like openaiText('gpt-5.5')) */
     adapter: TAdapter;
     /**
@@ -125,6 +127,8 @@ export interface TextActivityOptions<TAdapter extends AnyTextAdapter, TSchema ex
     runId?: TextOptions['runId'];
     /** Parent run ID for AG-UI protocol nested run correlation. */
     parentRunId?: TextOptions['parentRunId'];
+    /** Subagent run id when this chat runs as a child. See `defineAgent`. */
+    subagentRunId?: TextOptions['subagentRunId'];
     /** Application state mirrored in a STATE_SNAPSHOT before an interrupt terminal. */
     state?: TextOptions['state'];
     /**
@@ -132,6 +136,12 @@ export interface TextActivityOptions<TAdapter extends AnyTextAdapter, TSchema ex
      * before accepting new input on a thread with pending interrupts.
      */
     resume?: TextOptions['resume'];
+    /**
+     * Named child agents. When `router` is set, the library spawns that agent
+     * directly. When `router` is omitted, the main model gets one synthetic
+     * server tool per agent and picks the child.
+     */
+    subagents?: SubagentsBag<TAgents>;
     /**
      * Optional Standard Schema for structured output.
      * When provided, the activity will:
@@ -299,6 +309,6 @@ export type TextActivityResult<TSchema extends SchemaInput | undefined, TStream
  * // result is { summary: string, keyPoints: string[] }
  * ```
  */
-export declare function chat<TAdapter extends AnyTextAdapter, TSchema extends SchemaInput | undefined = undefined, TStream extends boolean = boolean, const TTools extends TextActivityOptions<TAdapter, TSchema, TStream, any>['tools'] = TextActivityOptions<TAdapter, TSchema, TStream, any>['tools'], const TInterrupts extends ReadonlyArray<InterruptDefinition<any, any, any, any>> = [], TContext = unknown, const TMiddleware extends Array<unknown> | undefined = undefined>(options: TextActivityOptionsWithContext<TAdapter, TSchema, TStream, TTools, TInterrupts, TContext, TMiddleware>): TextActivityResult<TSchema, TStream, TTools>;
+export declare function chat<TAdapter extends AnyTextAdapter, TSchema extends SchemaInput | undefined = undefined, TStream extends boolean = boolean, const TTools extends TextActivityOptions<TAdapter, TSchema, TStream, any>['tools'] = TextActivityOptions<TAdapter, TSchema, TStream, any>['tools'], const TInterrupts extends ReadonlyArray<InterruptDefinition<any, any, any, any>> = [], TContext = unknown, const TMiddleware extends Array<unknown> | undefined = undefined, const TAgents extends ReadonlyArray<DefinedAgent> = ReadonlyArray<DefinedAgent>>(options: TextActivityOptionsWithContext<TAdapter, TSchema, TStream, TTools, TInterrupts, TContext, TMiddleware, TAgents>): TextActivityResult<TSchema, TStream, TTools>;
 export type { TextAdapter, TextAdapterConfig, StructuredOutputOptions, StructuredOutputResult, } from './adapter.js';
 export { BaseTextAdapter } from './adapter.js';