@tanstack/ai 0.61.0 → 0.64.0

package/skills/ai-core/tool-calling/SKILL.md

@@ -513,6 +513,9 @@ The post-discovery payload always returns the full description and schema regard
 `@tanstack/ai-mcp` lets a server-side `chat()` call discover and invoke tools
 hosted on any MCP server (Streamable HTTP, SSE, or stdio).
 
+`createMCPClient` tries spec `2026-07-28` first.
+If the server does not support that spec, the client uses the 2025 initialize handshake.
+
 **MCP tools and UI resources:** When an MCP tool result carries a `ui://`
 resource URI (via `_meta.ui.resourceUri`), TanStack AI surfaces it as a
 `UIResourcePart` on the assistant `UIMessage` in the client message list.
@@ -723,6 +726,106 @@ export async function POST(request: Request) {
 }
 ```
 
+### Host your own MCP server
+
+Import `createMCPServer` from `@tanstack/ai-mcp/server`.
+Pass tools from `toolDefinition().server()`.
+Call `server.fetch(request)` in your HTTP route.
+
+```typescript
+import { toolDefinition } from '@tanstack/ai'
+import { createMCPServer } from '@tanstack/ai-mcp/server'
+import { z } from 'zod'
+
+const getWeather = toolDefinition({
+  name: 'get_weather',
+  description: 'Current weather for a city',
+  inputSchema: z.object({ city: z.string() }),
+}).server(async ({ city }) => {
+  return { city, temperature: 18, conditions: 'clear' }
+})
+
+const server = createMCPServer({
+  name: 'weather',
+  version: '1.0.0',
+  tools: [getWeather],
+})
+
+export function POST(request: Request) {
+  return server.fetch(request)
+}
+```
+
+`stdioTransport` from `@tanstack/ai-mcp/stdio` connects your client to a command.
+`serveMCPStdio` from `@tanstack/ai-mcp/server/stdio` serves your server on stdin and stdout.
+Write logs with `console.error`.
+stdout carries only protocol messages.
+
+```typescript
+import { toolDefinition } from '@tanstack/ai'
+import { createMCPServer } from '@tanstack/ai-mcp/server'
+import { serveMCPStdio } from '@tanstack/ai-mcp/server/stdio'
+import { z } from 'zod'
+
+const getWeather = toolDefinition({
+  name: 'get_weather',
+  description: 'Current weather for a city',
+  inputSchema: z.object({ city: z.string() }),
+}).server(async ({ city }) => {
+  return { city, temperature: 18, conditions: 'clear' }
+})
+
+const server = createMCPServer({
+  name: 'weather',
+  version: '1.0.0',
+  tools: [getWeather],
+})
+
+serveMCPStdio(server)
+```
+
+The `@tanstack/ai-mcp` skill shows `ctx.context.requestInput` and `ctx.context.sample`.
+
+### Read an MCP input interrupt
+
+When `chat()` receives an MCP input request, the run outcome is an interrupt.
+The stream ends with `RUN_FINISHED`.
+The outcome type is `interrupt`.
+Read each interrupt whose `reason` is `mcp_input`.
+The payload key is `tanstack:interruptPayload`.
+
+`form` means the server asks the user for input.
+`sampling` means the server asks for a model result.
+
+```typescript
+import { chat, INTERRUPT_PAYLOAD_METADATA_KEY } from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
+import { createMCPClient } from '@tanstack/ai-mcp'
+
+const client = await createMCPClient({
+  transport: { type: 'http', url: 'https://mcp.example.com/mcp' },
+})
+
+const stream = chat({
+  adapter: openaiText('gpt-5.5'),
+  messages: [{ role: 'user', content: 'Weather in Paris?' }],
+  tools: await client.tools(),
+})
+
+for await (const chunk of stream) {
+  if (chunk.type !== 'RUN_FINISHED') continue
+  if (chunk.outcome?.type !== 'interrupt') continue
+
+  for (const item of chunk.outcome.interrupts) {
+    if (item.reason !== 'mcp_input') continue
+    const payload = item.metadata?.[INTERRUPT_PAYLOAD_METADATA_KEY]
+    if (typeof payload !== 'object' || payload === null) continue
+    if (!('kind' in payload)) continue
+    // payload.kind is 'form' or 'sampling'
+  }
+}
+```
+
 ## Provider Skills
 
 > **Not to be confused with `@tanstack/ai-code-mode-snippets`**, whose snippets are TypeScript functions your application generates and runs in its own Code Mode sandbox (a local JS isolate). Provider Skills are hosted, provider-managed bundles that the model loads on demand and runs inside the provider's server-side sandbox.

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

@@ -2,6 +2,7 @@ import type { SubagentInfo as AGUISubagentInfo } from '@ag-ui/core'
 import type { InterruptDefinition } from '../../../interrupt-definition'
 import type {
   AnyTool,
+  InferSchemaType,
   ModelMessage,
   RunAgentResumeItem,
   SchemaInput,
@@ -12,8 +13,16 @@ import type { AnyClientTool } from '../tools/tool-definition'
 
 /**
  * Context the library passes into {@link defineAgent} `run`.
+ * `TInput` is the agent's `inputSchema`.
  */
-export interface SubagentRunContext {
+export interface SubagentRunContext<
+  TInput extends SchemaInput | undefined = any,
+> {
+  /**
+   * The input the parent model wrote for this child, checked against
+   * `inputSchema`. `undefined` when the agent has no `inputSchema`.
+   */
+  input: TInput extends SchemaInput ? InferSchemaType<TInput> : undefined
   messages: Array<UIMessage | ModelMessage>
   abortSignal?: AbortSignal
   threadId: string
@@ -53,13 +62,20 @@ export interface DefinedAgent<
   TSchema extends SchemaInput | undefined = SchemaInput | undefined,
   TInterrupts extends ReadonlyArray<InterruptDefinition<any, any, any, any>> =
     ReadonlyArray<InterruptDefinition<any, any, any, any>>,
+  TInput extends SchemaInput | undefined = any,
 > extends AGUISubagentInfo {
   name: TName
   /** Required here: the router and the synthetic tool both read it. */
   description: string
   run: (
-    ctx: SubagentRunContext,
+    ctx: SubagentRunContext<TInput>,
   ) => AsyncIterable<StreamChunk> | Promise<AsyncIterable<StreamChunk>>
+  /**
+   * The input the parent model writes when it calls this agent's tool, such
+   * as a short brief. `run` reads it as `ctx.input`. Tool mode only: a
+   * `subagents.router` cannot start an agent that has `inputSchema`.
+   */
+  inputSchema?: TInput
   tools?: TTools
   interrupts?: TInterrupts
   outputSchema?: TSchema
@@ -104,7 +120,8 @@ export function defineAgent<
   const TInterrupts extends ReadonlyArray<
     InterruptDefinition<any, any, any, any>
   > = readonly [],
->(agent: DefinedAgent<TName, TTools, TSchema, TInterrupts>) {
+  TInput extends SchemaInput | undefined = undefined,
+>(agent: DefinedAgent<TName, TTools, TSchema, TInterrupts, TInput>) {
   if (agent.name.trim() === '') {
     throw new Error('defineAgent requires a non-empty name')
   }

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

@@ -9,6 +9,7 @@ import {
   tanstackMetadata,
   withTanstackMetadata,
 } from '../../../utilities/merge-metadata'
+import { mergeStreams } from '../../../utilities/merge-streams'
 import { INTERRUPT_BINDING_METADATA_KEY } from '../../../interrupt-resume'
 import { EMIT_STREAM_CHUNK, SUBAGENT_TOOL } from '../tools/tool-calls'
 import type { SubagentToolOutcome } from '../tools/tool-calls'
@@ -93,6 +94,8 @@ export function createSubagentSink(): SubagentSink {
 /** One child to start, or a suspended child to continue. */
 export interface SpawnEntry {
   name: string
+  /** The checked tool input for an agent with `inputSchema`. */
+  input?: unknown
   resume?: {
     subagentRunId: string
     /** The child's own messages from the interrupted run. */
@@ -248,6 +251,7 @@ function openAgentStream(
   return spawnAgentStream(
     agent,
     {
+      input: entry.input,
       messages: resumed?.messages ?? ctx.messages,
       ...(ctx.abortSignal ? { abortSignal: ctx.abortSignal } : {}),
       threadId: childThreadId(bag.sandbox, ctx.threadId, entry.name),
@@ -522,36 +526,6 @@ export async function* spawnAgentStream(
   }
 }
 
-async function* mergeAgentStreams(streams: Array<AsyncIterable<StreamChunk>>) {
-  const readers = streams.map((stream) => {
-    const iterator = stream[Symbol.asyncIterator]()
-    return {
-      iterator,
-      next: iterator.next(),
-    }
-  })
-
-  try {
-    while (readers.length > 0) {
-      const indexed = readers.map((reader, index) =>
-        reader.next.then((result) => ({ index, result, reader })),
-      )
-      const winner = await Promise.race(indexed)
-      if (winner.result.done) {
-        readers.splice(winner.index, 1)
-        continue
-      }
-      yield winner.result.value
-      winner.reader.next = winner.reader.iterator.next()
-    }
-  } finally {
-    // The reader stopped early. Close every child so its finally runs.
-    for (const reader of readers) {
-      void reader.iterator.return?.().catch(() => {})
-    }
-  }
-}
-
 /** True when a child in these chunks failed or stopped for outside input. */
 function stopsSequence(chunks: ReadonlyArray<StreamChunk>, id: string) {
   return chunks.some(
@@ -617,7 +591,7 @@ export async function* spawnNamedAgents(
       yield* onlyStream
       return
     }
-    yield* mergeAgentStreams(streams)
+    yield* mergeStreams(streams)
   } finally {
     group.controller.abort()
     group.dispose()
@@ -721,8 +695,10 @@ export function createSyntheticSubagentTools(
   return bag.agents.map((agent) => ({
     name: agent.name,
     description: agent.description,
+    ...(agent.inputSchema !== undefined && { inputSchema: agent.inputSchema }),
     [SUBAGENT_TOOL]: true,
-    execute: async (_input: unknown, context?: unknown) => {
+    // The tool loop checks `input` against `inputSchema` before this runs.
+    execute: async (input: unknown, context?: unknown) => {
       const toolContext = context as
         | {
             toolCallId?: string
@@ -736,17 +712,20 @@ export function createSyntheticSubagentTools(
           child.parentToolCallId !== undefined &&
           child.parentToolCallId === toolCallId,
       )
-      const entry: SpawnEntry = suspended
-        ? {
-            name: agent.name,
-            resume: {
-              subagentRunId: suspended.subagentRunId,
-              messages: suspended.messages,
-              entries: suspended.resume,
-              text: suspended.text,
-            },
-          }
-        : { name: agent.name }
+      // An agent without `inputSchema` still gets `{}` from the model. Its
+      // `ctx.input` stays undefined.
+      const entry: SpawnEntry = {
+        name: agent.name,
+        ...(agent.inputSchema !== undefined && { input }),
+        ...(suspended && {
+          resume: {
+            subagentRunId: suspended.subagentRunId,
+            messages: suspended.messages,
+            entries: suspended.resume,
+            text: suspended.text,
+          },
+        }),
+      }
       const sink = createSubagentSink()
       const link = linkAbort(parent.abortSignal)
       let subagentRunId = suspended?.subagentRunId ?? ''