@tanstack/ai 0.58.0 → 0.59.0

package/dist/esm/utilities/subagent-wire.js

@@ -0,0 +1,131 @@
+//#region src/utilities/subagent-wire.ts
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function wireSubagentRunId(message) {
+	if (!isRecord(message) || "parts" in message) return void 0;
+	const id = message.subagentRunId;
+	return typeof id === "string" && id !== "" ? id : void 0;
+}
+function wireSubagentInfo(message) {
+	if (!isRecord(message) || !isRecord(message.metadata)) return void 0;
+	const tanstack = message.metadata.tanstack;
+	if (!isRecord(tanstack) || !isRecord(tanstack.subagent)) return void 0;
+	const { name, status, error, interruptIds } = tanstack.subagent;
+	if (typeof name !== "string" || !isStatus(status)) return void 0;
+	const { description, parentSubagentRunId, parentToolCallId, metadata, placeholder } = tanstack.subagent;
+	return {
+		name,
+		status,
+		...typeof description === "string" && { description },
+		...isRecord(error) && typeof error.message === "string" && { error: {
+			message: error.message,
+			...typeof error.code === "string" && { code: error.code }
+		} },
+		...Array.isArray(interruptIds) && { interruptIds: interruptIds.filter((id) => typeof id === "string") },
+		...typeof parentSubagentRunId === "string" && { parentSubagentRunId },
+		...typeof parentToolCallId === "string" && { parentToolCallId },
+		...isRecord(metadata) && { metadata },
+		...placeholder === true && { placeholder: true }
+	};
+}
+function isStatus(value) {
+	return value === "running" || value === "finished" || value === "error" || value === "suspended";
+}
+function untag(message) {
+	if (!isRecord(message)) return message;
+	const { subagentRunId: _id, ...rest } = message;
+	const metadata = isRecord(rest.metadata) ? rest.metadata : void 0;
+	const tanstack = isRecord(metadata?.tanstack) ? metadata.tanstack : void 0;
+	if (!metadata || !tanstack || !("subagent" in tanstack)) return rest;
+	const { subagent: _info, ...tanstackRest } = tanstack;
+	return {
+		...rest,
+		metadata: {
+			...metadata,
+			tanstack: tanstackRest
+		}
+	};
+}
+/**
+* Split wire messages into the parent's own messages and one group per direct
+* child. A nested child's messages stay inside its parent's group.
+*/
+function splitSubagentWire(messages) {
+	const parentOf = /* @__PURE__ */ new Map();
+	for (const message of messages) {
+		const id = wireSubagentRunId(message);
+		if (id !== void 0 && !parentOf.has(id)) parentOf.set(id, wireSubagentInfo(message)?.parentSubagentRunId);
+	}
+	const rootOf = (id) => {
+		let current = id;
+		for (let depth = 0; depth < 64; depth++) {
+			const parent = parentOf.get(current);
+			if (parent === void 0 || !parentOf.has(parent)) return current;
+			current = parent;
+		}
+		return current;
+	};
+	const top = [];
+	const groups = /* @__PURE__ */ new Map();
+	for (const message of messages) {
+		const id = wireSubagentRunId(message);
+		if (id === void 0) {
+			top.push(message);
+			continue;
+		}
+		const root = rootOf(id);
+		let group = groups.get(root);
+		if (!group) {
+			group = {
+				id: root,
+				info: {
+					name: "subagent",
+					status: "finished"
+				},
+				messages: [],
+				hostIndex: top.length - 1
+			};
+			groups.set(root, group);
+		}
+		if (id !== root) {
+			group.messages.push(message);
+			continue;
+		}
+		const info = wireSubagentInfo(message);
+		if (info) group.info = info;
+		if (!info?.placeholder) group.messages.push(untag(message));
+	}
+	return {
+		top,
+		groups: [...groups.values()]
+	};
+}
+/** Text a child wrote, for the parent model and for a later child. */
+function subagentWireText(messages) {
+	const blocks = [];
+	for (const message of messages) {
+		if (!isRecord(message) || message.role !== "assistant") continue;
+		if (wireSubagentRunId(message) !== void 0) continue;
+		const content = message.content;
+		if (typeof content === "string" && content.trim() !== "") blocks.push(content.trim());
+	}
+	const nested = splitSubagentWire(messages).groups;
+	for (const group of nested) {
+		const text = subagentWireText(group.messages);
+		if (text !== "") blocks.push(`${group.info.name}:\n${text}`);
+	}
+	return blocks.join("\n\n");
+}
+/**
+* The id of the parent assistant message that hosts a routed turn's cards.
+* The persistence recorder writes that message, and a handoff run passes the
+* same id so the stored thread keeps one copy.
+*/
+function subagentHostMessageId(runId) {
+	return `assistant:${runId}`;
+}
+//#endregion
+export { splitSubagentWire, subagentHostMessageId, subagentWireText, wireSubagentInfo, wireSubagentRunId };
+
+//# sourceMappingURL=subagent-wire.js.map

package/dist/esm/utilities/subagent-wire.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent-wire.js","names":[],"sources":["../../../src/utilities/subagent-wire.ts"],"sourcesContent":["import type { SubagentInfo as AGUISubagentInfo } from '@ag-ui/core'\nimport type { SubagentHandleData } from '../types'\n\n/**\n * Card data that travels on each child wire message, in\n * `metadata.tanstack.subagent`. The messages carry the AG-UI `subagentRunId`.\n */\nexport interface SubagentWireInfo\n  extends\n    AGUISubagentInfo,\n    Pick<\n      SubagentHandleData,\n      | 'status'\n      | 'error'\n      | 'interruptIds'\n      | 'parentSubagentRunId'\n      | 'parentToolCallId'\n      | 'metadata'\n    > {\n  /** The child has no messages yet. This wire message only holds the card. */\n  placeholder?: true\n}\n\nexport interface SubagentWireGroup<T> {\n  id: string\n  info: SubagentWireInfo\n  /** The child's messages without its own tag. Nested children keep theirs. */\n  messages: Array<T>\n  /** Index in `top` of the last message before this child, or -1. */\n  hostIndex: number\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === 'object' && value !== null && !Array.isArray(value)\n}\n\nexport function wireSubagentRunId(message: unknown): string | undefined {\n  if (!isRecord(message) || 'parts' in message) return undefined\n  const id = message.subagentRunId\n  return typeof id === 'string' && id !== '' ? id : undefined\n}\n\nexport function wireSubagentInfo(\n  message: unknown,\n): SubagentWireInfo | undefined {\n  if (!isRecord(message) || !isRecord(message.metadata)) return undefined\n  const tanstack = message.metadata.tanstack\n  if (!isRecord(tanstack) || !isRecord(tanstack.subagent)) return undefined\n  // Wire data comes from the client. Keep only well-formed fields.\n  const { name, status, error, interruptIds } = tanstack.subagent\n  if (typeof name !== 'string' || !isStatus(status)) return undefined\n  const {\n    description,\n    parentSubagentRunId,\n    parentToolCallId,\n    metadata,\n    placeholder,\n  } = tanstack.subagent\n  return {\n    name,\n    status,\n    ...(typeof description === 'string' && { description }),\n    ...(isRecord(error) &&\n      typeof error.message === 'string' && {\n        error: {\n          message: error.message,\n          ...(typeof error.code === 'string' && { code: error.code }),\n        },\n      }),\n    ...(Array.isArray(interruptIds) && {\n      interruptIds: interruptIds.filter(\n        (id): id is string => typeof id === 'string',\n      ),\n    }),\n    ...(typeof parentSubagentRunId === 'string' && { parentSubagentRunId }),\n    ...(typeof parentToolCallId === 'string' && { parentToolCallId }),\n    ...(isRecord(metadata) && { metadata }),\n    ...(placeholder === true && { placeholder: true as const }),\n  }\n}\n\nfunction isStatus(value: unknown): value is SubagentWireInfo['status'] {\n  return (\n    value === 'running' ||\n    value === 'finished' ||\n    value === 'error' ||\n    value === 'suspended'\n  )\n}\n\nfunction untag<T>(message: T): T {\n  if (!isRecord(message)) return message\n  const { subagentRunId: _id, ...rest } = message\n  void _id\n  const metadata = isRecord(rest.metadata) ? rest.metadata : undefined\n  const tanstack = isRecord(metadata?.tanstack) ? metadata.tanstack : undefined\n  if (!metadata || !tanstack || !('subagent' in tanstack)) return rest as T\n  const { subagent: _info, ...tanstackRest } = tanstack\n  void _info\n  return { ...rest, metadata: { ...metadata, tanstack: tanstackRest } } as T\n}\n\n/**\n * Split wire messages into the parent's own messages and one group per direct\n * child. A nested child's messages stay inside its parent's group.\n */\nexport function splitSubagentWire<T>(messages: ReadonlyArray<T>): {\n  top: Array<T>\n  groups: Array<SubagentWireGroup<T>>\n} {\n  const parentOf = new Map<string, string | undefined>()\n  for (const message of messages) {\n    const id = wireSubagentRunId(message)\n    if (id !== undefined && !parentOf.has(id)) {\n      parentOf.set(id, wireSubagentInfo(message)?.parentSubagentRunId)\n    }\n  }\n  const rootOf = (id: string) => {\n    let current = id\n    for (let depth = 0; depth < 64; depth++) {\n      const parent = parentOf.get(current)\n      if (parent === undefined || !parentOf.has(parent)) return current\n      current = parent\n    }\n    return current\n  }\n\n  const top: Array<T> = []\n  const groups = new Map<string, SubagentWireGroup<T>>()\n  for (const message of messages) {\n    const id = wireSubagentRunId(message)\n    if (id === undefined) {\n      top.push(message)\n      continue\n    }\n    const root = rootOf(id)\n    let group = groups.get(root)\n    if (!group) {\n      group = {\n        id: root,\n        info: { name: 'subagent', status: 'finished' },\n        messages: [],\n        hostIndex: top.length - 1,\n      }\n      groups.set(root, group)\n    }\n    if (id !== root) {\n      group.messages.push(message)\n      continue\n    }\n    const info = wireSubagentInfo(message)\n    if (info) group.info = info\n    if (!info?.placeholder) group.messages.push(untag(message))\n  }\n  return { top, groups: [...groups.values()] }\n}\n\n/** Text a child wrote, for the parent model and for a later child. */\nexport function subagentWireText(messages: ReadonlyArray<unknown>): string {\n  const blocks: Array<string> = []\n  for (const message of messages) {\n    if (!isRecord(message) || message.role !== 'assistant') continue\n    if (wireSubagentRunId(message) !== undefined) continue\n    const content = message.content\n    if (typeof content === 'string' && content.trim() !== '') {\n      blocks.push(content.trim())\n    }\n  }\n  const nested = splitSubagentWire(messages).groups\n  for (const group of nested) {\n    const text = subagentWireText(group.messages)\n    if (text !== '') blocks.push(`${group.info.name}:\\n${text}`)\n  }\n  return blocks.join('\\n\\n')\n}\n\n/**\n * The id of the parent assistant message that hosts a routed turn's cards.\n * The persistence recorder writes that message, and a handoff run passes the\n * same id so the stored thread keeps one copy.\n */\nexport function subagentHostMessageId(runId: string) {\n  return `assistant:${runId}`\n}\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai",
-  "version": "0.58.0",
+  "version": "0.59.0",
   "description": "Type-safe TypeScript AI SDK for streaming chat, tool calling, agents, structured outputs, and multimodal generation.",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -85,7 +85,7 @@
     "tanstack-intent"
   ],
   "dependencies": {
-    "@ag-ui/core": "0.1.1-canary.beta.0",
+    "@ag-ui/core": "1.0.0",
     "@standard-schema/spec": "^1.1.0",
     "partial-json": "^0.1.7",
     "@tanstack/ai-event-client": "^0.12.1",

package/skills/ai-core/adapter-configuration/references/grok-adapter.md

@@ -31,7 +31,7 @@ import { grokImage } from '@tanstack/ai-grok'
 | `grok-build-0.1` | 256K           | Code-specialized; `reasoning` option is not accepted     |
 
 `GROK_CHAT_MODELS` is exactly these four ids. Image models
-(`GROK_IMAGE_MODELS`): `grok-2-image-1212`, `grok-imagine-image`,
+(`GROK_IMAGE_MODELS`): `grok-imagine-image`,
 `grok-imagine-image-2.0`, `grok-imagine-image-quality`.
 
 ## Provider-Specific modelOptions

package/skills/ai-core/media-generation/SKILL.md

@@ -312,7 +312,7 @@ with `allowUrlFetch: true` on the adapter config
 | OpenAI     | gpt-image-2 / gpt-image-1 / -mini → `images.edit()` (up to 16). dall-e-2 → edit (1). dall-e-3 throws.                                                                                                    | Sora-2 / -pro → `input_reference` (single). Throws if >1.                                                                                                                                                                                                                                                                                     |
 | Gemini     | Native (gemini-\*-flash-image, "nano-banana") → multimodal `contents`. Imagen throws.                                                                                                                    | Veo → first un-roled / `'start_frame'` image is the input image; `'end_frame'` → `lastFrame`; `'reference'` / `'character'` → `referenceImages`. Omni Flash sends image/video parts as interaction content blocks (no role routing).                                                                                                          |
 | fal        | Per-endpoint field names from a generated map (`pnpm generate:fal-image-fields`). Defaults: 1 input → `image_url`; >1 → `image_urls`; roles → `mask_url` / `control_image_url` / `reference_image_urls`. | Per-endpoint map (e.g. Kling i2v start frame → `image_url`). Defaults: 1 input → `image_url`; `start_frame`/`end_frame` → `start_image_url`/`end_image_url`; `reference` → `reference_image_urls`.                                                                                                                                            |
-| Grok       | grok-imagine models → `/v1/images/edits` JSON endpoint (≤3 sources, addressed by xAI in request order; prompt sent verbatim; mask/control throw). grok-2-image-1212 throws.                              | Un-roled / `'start_frame'` image → starting frame; `'reference'` / `'character'` → `reference_images` (1.5). On 1.5 a starting frame can be combined with reference inputs (it pins the first frame). A `video` part + `modelOptions.mode: 'edit' \| 'extend'` routes to `/videos/edits` / `/videos/extensions` on `grok-imagine-video` only. |
+| Grok       | grok-imagine models → `/v1/images/edits` JSON endpoint (≤3 sources, addressed by xAI in request order; prompt sent verbatim; mask/control throw).                                                        | Un-roled / `'start_frame'` image → starting frame; `'reference'` / `'character'` → `reference_images` (1.5). On 1.5 a starting frame can be combined with reference inputs (it pins the first frame). A `video` part + `modelOptions.mode: 'edit' \| 'extend'` routes to `/videos/edits` / `/videos/extensions` on `grok-imagine-video` only. |
 | OpenRouter | Prompt parts map 1:1 onto multimodal `text` / `image_url` content parts, preserving interleaved order.                                                                                                   | Dedicated async API (`openRouterVideo`): `start_frame`/`end_frame` → `frame_images[]` (`first_frame`/`last_frame`); `reference`/`character` → `input_references[]`; an unroled image defaults to the start frame. Frame roles validated against the model's `supported_frame_images` metadata.                                                |
 | Anthropic  | n/a (no image generation API).                                                                                                                                                                           | n/a                                                                                                                                                                                                                                                                                                                                           |
 
@@ -1174,7 +1174,7 @@ generateSpeech({
 
 Not every model accepts image-conditioned prompts. The `prompt` type is
 narrowed per model, so passing an image part to a text-only model
-(dall-e-3, Imagen, grok-2-image) is a **compile-time error**; adapters
+(dall-e-3, Imagen) is a **compile-time error**; adapters
 also throw a clear runtime error as a backstop, so users learn at call
 time rather than getting silently wrong output.
 

package/skills/ai-core/middleware/SKILL.md

@@ -55,7 +55,7 @@ export async function POST(request: Request) {
 
 Every hook receives a `ChatMiddlewareContext` as its first argument, which provides
 `requestId`, `streamId`, `phase`, `iteration`, `chunkIndex`, `model`, `provider`,
-`signal`, `abort()`, `defer()`, and more.
+`signal`, `abort()`, `defer()`, and more. `parentRunId` names the run this one continues. `subagentRunId` is set only inside a subagent and names its card.
 
 | Hook                       | When                                                                                                     | Second Argument                                     |
 | -------------------------- | -------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
@@ -609,9 +609,12 @@ driver, or nothing fences a dead host's writes.
 a bare string: `message` is the provider's prose, `code` is the stable,
 machine-branchable classification a consumer switches on. Only
 `createOrResume`, `update`, `get`, and `findActiveRun` are required on a
-`RunStore`; `listByThread` and `listReclaimable` are optional, so a backend can
-leave either out and callers feature-detect
-(`store.listReclaimable?.(opts)`). Shape your own store with
+`RunStore`. `listByThread`, `listByParentRun`, and `listReclaimable` are
+optional, so a backend can leave any of them out and callers feature-detect
+(`store.listReclaimable?.(opts)`). A subagent child run also stores
+`parentRunId`, `subagentRunId`, and `name`. `createOrResume` writes them on
+the first insert and leaves them unchanged on resume. `reconstructChat` calls
+`listByParentRun` to put the child cards back. Shape your own store with
 `defineRunStore` for autocomplete without a separate `: RunStore` annotation,
 matching `defineLock`; `defineRunStore<const T extends RunStore>(store: T): T`
 returns the argument's own type, so an optional method your store implements

package/src/activities/chat/agents/define-agent.ts

@@ -0,0 +1,121 @@
+import type { SubagentInfo as AGUISubagentInfo } from '@ag-ui/core'
+import type { InterruptDefinition } from '../../../interrupt-definition'
+import type {
+  AnyTool,
+  ModelMessage,
+  RunAgentResumeItem,
+  SchemaInput,
+  StreamChunk,
+  UIMessage,
+} from '../../../types'
+import type { AnyClientTool } from '../tools/tool-definition'
+
+/**
+ * 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 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>) {
+  if (agent.name.trim() === '') {
+    throw new Error('defineAgent requires a non-empty name')
+  }
+  // A router returns 'main' to keep the turn on the parent.
+  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
+}

package/src/activities/chat/agents/route.ts

@@ -0,0 +1,115 @@
+import { boolean, choice } from '../../evaluate/index'
+import type { DefinedAgent } from './define-agent'
+import type { SubagentOrder, SubagentRouterPick } from './spawn'
+
+const ORDER_KEY = 'order'
+
+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 function subagentRoute<
+  const TAgents extends ReadonlyArray<DefinedAgent>,
+>(agents: TAgents, options?: SubagentRouteOptions<TAgents>) {
+  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: Record<string, unknown> = {
+    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 as TAgents[number]['name']]
+    questions[agent.name] = boolean({
+      instructions: when ?? agent.description,
+    })
+  }
+
+  function pick(result: RouteAnswers<TAgents>): SubagentRouterPick {
+    const names = agents
+      .map((agent) => agent.name)
+      .filter((name) => result[name as TAgents[number]['name']].value)
+    if (names.length === 0) return 'main'
+    const only = names.length === 1 ? names[0] : undefined
+    if (only !== undefined) 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' as const }
+          : { names: lead },
+        tail.length > 1
+          ? { names: tail, order: 'sequence' as const }
+          : { names: tail },
+      ],
+    }
+  }
+
+  return { questions: questions as RouteQuestions<TAgents>, pick }
+}