@tanstack/ai 0.59.0 → 0.63.0

package/skills/ai-core/chat-experience/SKILL.md

@@ -299,6 +299,8 @@ import type { UIMessage } from '@tanstack/ai-react'
 
 function ImagePart({ part }: { part: UIMessage['parts'][number] }) {
   if (part.type !== 'image') return null
+  // A provider file handle is an opaque id, so the browser cannot load it.
+  if (part.source.type === 'file') return null
   const src =
     part.source.type === 'url'
       ? part.source.value
@@ -307,6 +309,18 @@ function ImagePart({ part }: { part: UIMessage['parts'][number] }) {
 }
 ```
 
+For media reused across turns, upload once via a provider Files adapter
+(`openaiFiles()`, `anthropicFiles()`, `geminiFiles()`, `grokFiles()`,
+`falFiles()`) and send a `{ type: 'file' }` source built with
+`fileSourceFromHandle(handle)` instead of re-sending base64 each request. The
+source is `{ type: 'file', value, provider }`: an opaque handle and the adapter
+that issued it. A different provider (or one without Files API support at all)
+rejects it with a clear error before any request is sent.
+The source crosses the chat wire, so the browser can put it straight into the
+`sendMessage` content. Import `fileSourceFromHandle` from the browser-safe
+`@tanstack/ai/client` entry. See `ai-core/adapter-configuration/SKILL.md` §7
+and `docs/advanced/files-api.md`.
+
 ### 4. Sending Audio Messages (Browser Recording)
 
 Use `useAudioRecorder` from `@tanstack/ai-react` (or `createAudioRecorder` in Svelte) to capture audio in the browser. The resolved `AudioRecording` includes a ready-to-use `part` that slots directly into `sendMessage`.
@@ -385,6 +399,9 @@ Pass `mcp` to let `chat()` own discovery **and** lifecycle for one or more MCP
 clients. Useful when you want minimal boilerplate and don't need to reuse the
 clients across calls.
 
+`createMCPClient` tries spec `2026-07-28` first.
+If the server does not support that spec, the client uses the 2025 initialize handshake.
+
 ```typescript
 // Prop shape:
 // chat({
@@ -443,6 +460,123 @@ export async function POST(request: Request) {
 }
 ```
 
+**Host an MCP server.** Import `createMCPServer` from `@tanstack/ai-mcp/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 handleMcp(request: Request) {
+  return server.fetch(request)
+}
+
+// Mount handleMcp on GET, POST, and DELETE.
+// GET is the spec 2025 stream.
+// DELETE closes a spec 2025 session.
+```
+
+`serveMCPStdio` from `@tanstack/ai-mcp/server/stdio` serves that 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)
+```
+
+**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' },
+})
+
+try {
+  const stream = chat({
+    adapter: openaiText('gpt-5.6'),
+    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'
+    }
+  }
+} finally {
+  await client.close()
+}
+```
+
+To continue, answer the interrupt:
+
+1. In `useChat`, the item `kind` is `generic`.
+2. For a `form`, call `resolveInterrupt` with an object that matches `request.requestedSchema`. A `createMCPServer` server asks for `{ value: string }`.
+3. For `sampling`, call `resolveInterrupt` with the reply text.
+4. Call `cancel()` to decline.
+5. The route passes `parentRunId` and `resume` to `chat()`. The tool runs again with the answer.
+
+```tsx ignore
+// `interrupt` is one item from `useChat().interrupts`.
+if (interrupt.reason === 'mcp_input' && interrupt.kind === 'generic') {
+  interrupt.resolveInterrupt({ value: 'Paris' })
+}
+```
+
+This works on spec `2026-07-28`. On spec 2025, the server asks the client in the middle of the tool call. `chat()` cannot pause that call, so the tool call fails.
+
 ### 7. Queueing Messages Sent While Streaming
 
 By default, a `sendMessage` call that arrives while a stream is in flight is

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

@@ -283,6 +283,14 @@ await generateVideo({
 })
 ```
 
+Reference images / start frames that are reused (or arrive as inline base64 on
+memory-constrained runtimes) can instead be uploaded once via the provider's
+Files adapter and referenced with `source: fileSourceFromHandle(handle)` —
+supported for Gemini image generation (`geminiFiles()`) and fal image/video
+inputs (`falFiles()`). Endpoints that require raw bytes (OpenAI `images/edits`,
+Sora `input_reference`, Gemini Veo) reject file sources with a clear error.
+See `ai-core/adapter-configuration/SKILL.md` §7.
+
 **URL inputs that require an upload throw by default.** Most adapters pass a
 `type: 'url'` source straight through to the provider. Three paths can't —
 OpenAI `images.edit()`, OpenAI Sora `input_reference`, and Gemini **Veo** —

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/adapter.ts

@@ -89,6 +89,15 @@ export interface TextAdapter<
    */
   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.
    */
@@ -209,6 +218,7 @@ export abstract class BaseTextAdapter<
   abstract readonly name: string
   readonly model: TModel
   readonly requires?: ReadonlyArray<CapabilityHandle> = undefined
+  readonly supportsFileSources: boolean = false
 
   // Type-only property - never assigned at runtime
   declare '~types': {

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

@@ -93,6 +93,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 +250,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),
@@ -721,8 +724,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 +741,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 ?? ''