@tanstack/ai 0.27.0 → 0.29.0

package/dist/esm/logger/console-logger.js.map

@@ -1 +1 @@
-{"version":3,"file":"console-logger.js","sources":["../../../src/logger/console-logger.ts"],"sourcesContent":["import type { Logger } from './types'\n\n/**\n * Default `Logger` implementation that routes each level to the matching\n * `console` method:\n *\n * - `debug` → `console.debug`\n * - `info` → `console.info`\n * - `warn` → `console.warn`\n * - `error` → `console.error`\n *\n * When a `meta` object is supplied, the message is logged first and the meta\n * object is then printed via `console.dir(meta, { depth: null, colors: true })`\n * so deeply nested structures (e.g. provider chunk payloads with `usage`,\n * `output`, `reasoning`, `tools`) render in full instead of truncating to\n * `[Object]` / `[Array]`. On Node this produces a depth-unlimited inspect\n * dump; browsers present the object as an interactive tree (extra options\n * are ignored).\n *\n * This is the logger used when `debug` is enabled on any activity and no\n * custom `logger` is supplied via `debug: { logger }`.\n */\nconst DIR_OPTIONS = { depth: null, colors: true } as const\n\nexport class ConsoleLogger implements Logger {\n  /** Log a debug-level message; forwards to `console.debug`. */\n  debug(message: string, meta?: Record<string, unknown>): void {\n    console.debug(message)\n    if (meta !== undefined) console.dir(meta, DIR_OPTIONS)\n  }\n\n  /** Log an info-level message; forwards to `console.info`. */\n  info(message: string, meta?: Record<string, unknown>): void {\n    console.info(message)\n    if (meta !== undefined) console.dir(meta, DIR_OPTIONS)\n  }\n\n  /** Log a warning-level message; forwards to `console.warn`. */\n  warn(message: string, meta?: Record<string, unknown>): void {\n    console.warn(message)\n    if (meta !== undefined) console.dir(meta, DIR_OPTIONS)\n  }\n\n  /** Log an error-level message; forwards to `console.error`. */\n  error(message: string, meta?: Record<string, unknown>): void {\n    console.error(message)\n    if (meta !== undefined) console.dir(meta, DIR_OPTIONS)\n  }\n}\n"],"names":[],"mappings":"AAsBA,MAAM,cAAc,EAAE,OAAO,MAAM,QAAQ,KAAA;AAEpC,MAAM,cAAgC;AAAA;AAAA,EAE3C,MAAM,SAAiB,MAAsC;AAC3D,YAAQ,MAAM,OAAO;AACrB,QAAI,SAAS,OAAW,SAAQ,IAAI,MAAM,WAAW;AAAA,EACvD;AAAA;AAAA,EAGA,KAAK,SAAiB,MAAsC;AAC1D,YAAQ,KAAK,OAAO;AACpB,QAAI,SAAS,OAAW,SAAQ,IAAI,MAAM,WAAW;AAAA,EACvD;AAAA;AAAA,EAGA,KAAK,SAAiB,MAAsC;AAC1D,YAAQ,KAAK,OAAO;AACpB,QAAI,SAAS,OAAW,SAAQ,IAAI,MAAM,WAAW;AAAA,EACvD;AAAA;AAAA,EAGA,MAAM,SAAiB,MAAsC;AAC3D,YAAQ,MAAM,OAAO;AACrB,QAAI,SAAS,OAAW,SAAQ,IAAI,MAAM,WAAW;AAAA,EACvD;AACF;"}
+{"version":3,"file":"console-logger.js","sources":["../../../src/logger/console-logger.ts"],"sourcesContent":["import type { Logger } from './types'\n\n/**\n * `util.inspect` options used with `console.dir` on Node so deeply nested\n * structures (e.g. provider chunk payloads with `usage`, `output`,\n * `reasoning`, `tools`) render in full instead of truncating to\n * `[Object]` / `[Array]`.\n */\nconst DIR_OPTIONS = { depth: null, colors: true } as const\n\n/**\n * How `meta` should be rendered on the current runtime:\n *\n * - `dir` — Node. `console.dir(meta, { depth: null, colors: true })` gives a\n *   depth-unlimited, colored inspect dump.\n * - `json` — Cloudflare Workers / workerd. workerd never forwards\n *   `console.dir` output to the terminal (with or without options), and its\n *   own inspect of extra console arguments truncates nested objects, so the\n *   payload is appended as circular-safe pretty-printed JSON instead.\n * - `arg` — everything else (browsers, Deno, Bun). `meta` is passed as an\n *   extra console argument: devtools keep collapsible object trees and the\n *   runtime's inspect handles circular references natively.\n */\ntype MetaStrategy = 'dir' | 'json' | 'arg'\n\nfunction resolveMetaStrategy(): MetaStrategy {\n  // workerd must be detected before the Node check: under the `nodejs_compat`\n  // flag it emulates `process.versions.node`, but still drops `console.dir`.\n  try {\n    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- navigator is missing on Node < 21 despite the DOM lib typing it as always present\n    if (globalThis.navigator?.userAgent === 'Cloudflare-Workers') return 'json'\n  } catch {\n    // A locked-down runtime with a throwing `userAgent` getter is not workerd;\n    // fall through to the remaining checks rather than crash the log call.\n  }\n  if (\n    typeof process !== 'undefined' &&\n    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- a partial process global (bundler shims) may lack versions\n    typeof process.versions?.node === 'string'\n  ) {\n    return 'dir'\n  }\n  return 'arg'\n}\n\n/**\n * `JSON.stringify` hardened for debug payloads: circular references collapse\n * to `\"[Circular]\"`, `Error` instances expand to `name`/`message`/`stack`\n * (they would otherwise stringify to `{}`), and `bigint` values become\n * strings (they would otherwise throw). Never throws — falls back to\n * `String(value)` and, if even that coercion throws, a placeholder.\n */\nfunction stringifyMetaSafely(value: unknown): string {\n  const seen = new WeakSet<object>()\n  try {\n    return JSON.stringify(\n      value,\n      (_key, entry: unknown) => {\n        if (typeof entry === 'bigint') return entry.toString()\n        if (entry instanceof Error) {\n          return {\n            name: entry.name,\n            message: entry.message,\n            stack: entry.stack,\n          }\n        }\n        if (typeof entry === 'object' && entry !== null) {\n          if (seen.has(entry)) return '[Circular]'\n          seen.add(entry)\n        }\n        return entry\n      },\n      2,\n    )\n  } catch {\n    try {\n      return String(value)\n    } catch {\n      return '[Unserializable meta]'\n    }\n  }\n}\n\n/**\n * Default `Logger` implementation that routes each level to the matching\n * `console` method:\n *\n * - `debug` → `console.debug`\n * - `info` → `console.info`\n * - `warn` → `console.warn`\n * - `error` → `console.error`\n *\n * When a `meta` object is supplied it is rendered with the strategy that\n * actually surfaces it on the current runtime (see {@link MetaStrategy}):\n * depth-unlimited `console.dir` on Node, circular-safe JSON on Cloudflare\n * Workers, and an extra console argument everywhere else.\n *\n * This is the logger used when `debug` is enabled on any activity and no\n * custom `logger` is supplied via `debug: { logger }`.\n */\nexport class ConsoleLogger implements Logger {\n  /** Log a debug-level message; forwards to `console.debug`. */\n  debug(message: string, meta?: Record<string, unknown>): void {\n    this.emit('debug', message, meta)\n  }\n\n  /** Log an info-level message; forwards to `console.info`. */\n  info(message: string, meta?: Record<string, unknown>): void {\n    this.emit('info', message, meta)\n  }\n\n  /** Log a warning-level message; forwards to `console.warn`. */\n  warn(message: string, meta?: Record<string, unknown>): void {\n    this.emit('warn', message, meta)\n  }\n\n  /** Log an error-level message; forwards to `console.error`. */\n  error(message: string, meta?: Record<string, unknown>): void {\n    this.emit('error', message, meta)\n  }\n\n  private emit(\n    level: 'debug' | 'info' | 'warn' | 'error',\n    message: string,\n    meta?: Record<string, unknown>,\n  ): void {\n    if (meta === undefined) {\n      console[level](message)\n      return\n    }\n    switch (resolveMetaStrategy()) {\n      case 'dir':\n        console[level](message)\n        console.dir(meta, DIR_OPTIONS)\n        break\n      case 'json':\n        console[level](`${message}\\n${stringifyMetaSafely(meta)}`)\n        break\n      case 'arg':\n        console[level](message, meta)\n        break\n    }\n  }\n}\n"],"names":[],"mappings":"AAQA,MAAM,cAAc,EAAE,OAAO,MAAM,QAAQ,KAAA;AAiB3C,SAAS,sBAAoC;AAG3C,MAAI;AAEF,QAAI,WAAW,WAAW,cAAc,qBAAsB,QAAO;AAAA,EACvE,QAAQ;AAAA,EAGR;AACA,MACE,OAAO,YAAY;AAAA,EAEnB,OAAO,QAAQ,UAAU,SAAS,UAClC;AACA,WAAO;AAAA,EACT;AACA,SAAO;AACT;AASA,SAAS,oBAAoB,OAAwB;AACnD,QAAM,2BAAW,QAAA;AACjB,MAAI;AACF,WAAO,KAAK;AAAA,MACV;AAAA,MACA,CAAC,MAAM,UAAmB;AACxB,YAAI,OAAO,UAAU,SAAU,QAAO,MAAM,SAAA;AAC5C,YAAI,iBAAiB,OAAO;AAC1B,iBAAO;AAAA,YACL,MAAM,MAAM;AAAA,YACZ,SAAS,MAAM;AAAA,YACf,OAAO,MAAM;AAAA,UAAA;AAAA,QAEjB;AACA,YAAI,OAAO,UAAU,YAAY,UAAU,MAAM;AAC/C,cAAI,KAAK,IAAI,KAAK,EAAG,QAAO;AAC5B,eAAK,IAAI,KAAK;AAAA,QAChB;AACA,eAAO;AAAA,MACT;AAAA,MACA;AAAA,IAAA;AAAA,EAEJ,QAAQ;AACN,QAAI;AACF,aAAO,OAAO,KAAK;AAAA,IACrB,QAAQ;AACN,aAAO;AAAA,IACT;AAAA,EACF;AACF;AAmBO,MAAM,cAAgC;AAAA;AAAA,EAE3C,MAAM,SAAiB,MAAsC;AAC3D,SAAK,KAAK,SAAS,SAAS,IAAI;AAAA,EAClC;AAAA;AAAA,EAGA,KAAK,SAAiB,MAAsC;AAC1D,SAAK,KAAK,QAAQ,SAAS,IAAI;AAAA,EACjC;AAAA;AAAA,EAGA,KAAK,SAAiB,MAAsC;AAC1D,SAAK,KAAK,QAAQ,SAAS,IAAI;AAAA,EACjC;AAAA;AAAA,EAGA,MAAM,SAAiB,MAAsC;AAC3D,SAAK,KAAK,SAAS,SAAS,IAAI;AAAA,EAClC;AAAA,EAEQ,KACN,OACA,SACA,MACM;AACN,QAAI,SAAS,QAAW;AACtB,cAAQ,KAAK,EAAE,OAAO;AACtB;AAAA,IACF;AACA,YAAQ,uBAAoB;AAAA,MAC1B,KAAK;AACH,gBAAQ,KAAK,EAAE,OAAO;AACtB,gBAAQ,IAAI,MAAM,WAAW;AAC7B;AAAA,MACF,KAAK;AACH,gBAAQ,KAAK,EAAE,GAAG,OAAO;AAAA,EAAK,oBAAoB,IAAI,CAAC,EAAE;AACzD;AAAA,MACF,KAAK;AACH,gBAAQ,KAAK,EAAE,SAAS,IAAI;AAC5B;AAAA,IAAA;AAAA,EAEN;AACF;"}

package/dist/esm/logger/types.d.ts

@@ -4,22 +4,22 @@
 export interface Logger {
     /**
      * Called for chunk-level diagnostic output (raw provider chunks, per-chunk output, agent-loop iteration markers).
-     * @param meta Structured data forwarded to the underlying logger. Loggers like pino will preserve this as a structured record; console-based loggers pass it as the second argument to `console.<level>`.
+     * @param meta Structured data forwarded to the underlying logger. Loggers like pino will preserve this as a structured record; the default `ConsoleLogger` renders it with a runtime-appropriate strategy (depth-unlimited `console.dir` on Node, JSON appended to the message on Cloudflare Workers, a second `console.<level>` argument elsewhere).
      */
     debug: (message: string, meta?: Record<string, unknown>) => void;
     /**
      * Called for notable informational events (outgoing requests, tool invocations, middleware transitions).
-     * @param meta Structured data forwarded to the underlying logger. Loggers like pino will preserve this as a structured record; console-based loggers pass it as the second argument to `console.<level>`.
+     * @param meta Structured data forwarded to the underlying logger. Loggers like pino will preserve this as a structured record; the default `ConsoleLogger` renders it with a runtime-appropriate strategy (depth-unlimited `console.dir` on Node, JSON appended to the message on Cloudflare Workers, a second `console.<level>` argument elsewhere).
      */
     info: (message: string, meta?: Record<string, unknown>) => void;
     /**
      * Called for notable warnings that don't halt execution (deprecations, recoverable anomalies).
-     * @param meta Structured data forwarded to the underlying logger. Loggers like pino will preserve this as a structured record; console-based loggers pass it as the second argument to `console.<level>`.
+     * @param meta Structured data forwarded to the underlying logger. Loggers like pino will preserve this as a structured record; the default `ConsoleLogger` renders it with a runtime-appropriate strategy (depth-unlimited `console.dir` on Node, JSON appended to the message on Cloudflare Workers, a second `console.<level>` argument elsewhere).
      */
     warn: (message: string, meta?: Record<string, unknown>) => void;
     /**
      * Called for caught exceptions throughout the pipeline.
-     * @param meta Structured data forwarded to the underlying logger. Loggers like pino will preserve this as a structured record; console-based loggers pass it as the second argument to `console.<level>`.
+     * @param meta Structured data forwarded to the underlying logger. Loggers like pino will preserve this as a structured record; the default `ConsoleLogger` renders it with a runtime-appropriate strategy (depth-unlimited `console.dir` on Node, JSON appended to the message on Cloudflare Workers, a second `console.<level>` argument elsewhere).
      */
     error: (message: string, meta?: Record<string, unknown>) => void;
 }

package/dist/esm/realtime/index.d.ts

@@ -19,9 +19,7 @@ export type * from './types.js';
  *   .handler(async () => {
  *     return realtimeToken({
  *       adapter: openaiRealtimeToken({
- *         model: 'gpt-4o-realtime-preview',
- *         voice: 'alloy',
- *         instructions: 'You are a helpful assistant...',
+ *         model: 'gpt-realtime',
  *       }),
  *     })
  *   })

package/dist/esm/realtime/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../../../src/realtime/index.ts"],"sourcesContent":["import type { RealtimeToken, RealtimeTokenOptions } from './types'\n\n// Re-export all types\nexport type * from './types'\n\n/**\n * Generate a realtime token using the provided adapter.\n *\n * This function is used on the server to generate ephemeral tokens\n * that clients can use to establish realtime connections.\n *\n * @param options - Token generation options including the adapter\n * @returns Promise resolving to a RealtimeToken\n *\n * @example\n * ```typescript\n * import { realtimeToken } from '@tanstack/ai'\n * import { openaiRealtimeToken } from '@tanstack/ai-openai'\n *\n * // Server function (TanStack Start example)\n * export const getRealtimeToken = createServerFn()\n *   .handler(async () => {\n *     return realtimeToken({\n *       adapter: openaiRealtimeToken({\n *         model: 'gpt-4o-realtime-preview',\n *         voice: 'alloy',\n *         instructions: 'You are a helpful assistant...',\n *       }),\n *     })\n *   })\n * ```\n */\nexport async function realtimeToken(\n  options: RealtimeTokenOptions,\n): Promise<RealtimeToken> {\n  const { adapter } = options\n  return adapter.generateToken()\n}\n"],"names":[],"mappings":"AAgCA,eAAsB,cACpB,SACwB;AACxB,QAAM,EAAE,YAAY;AACpB,SAAO,QAAQ,cAAA;AACjB;"}
+{"version":3,"file":"index.js","sources":["../../../src/realtime/index.ts"],"sourcesContent":["import type { RealtimeToken, RealtimeTokenOptions } from './types'\n\n// Re-export all types\nexport type * from './types'\n\n/**\n * Generate a realtime token using the provided adapter.\n *\n * This function is used on the server to generate ephemeral tokens\n * that clients can use to establish realtime connections.\n *\n * @param options - Token generation options including the adapter\n * @returns Promise resolving to a RealtimeToken\n *\n * @example\n * ```typescript\n * import { realtimeToken } from '@tanstack/ai'\n * import { openaiRealtimeToken } from '@tanstack/ai-openai'\n *\n * // Server function (TanStack Start example)\n * export const getRealtimeToken = createServerFn()\n *   .handler(async () => {\n *     return realtimeToken({\n *       adapter: openaiRealtimeToken({\n *         model: 'gpt-realtime',\n *       }),\n *     })\n *   })\n * ```\n */\nexport async function realtimeToken(\n  options: RealtimeTokenOptions,\n): Promise<RealtimeToken> {\n  const { adapter } = options\n  return adapter.generateToken()\n}\n"],"names":[],"mappings":"AA8BA,eAAsB,cACpB,SACwB;AACxB,QAAM,EAAE,YAAY;AACpB,SAAO,QAAQ,cAAA;AACjB;"}

package/dist/esm/types.d.ts

@@ -6,7 +6,7 @@ import { BaseEvent as AGUIBaseEvent, CustomEvent as AGUICustomEvent, MessagesSna
 /**
  * Tool call states - track the lifecycle of a tool call
  */
-export type ToolCallState = 'awaiting-input' | 'input-streaming' | 'input-complete' | 'approval-requested' | 'approval-responded' | 'complete';
+export type ToolCallState = 'awaiting-input' | 'input-streaming' | 'input-complete' | 'approval-requested' | 'approval-responded' | 'complete' | 'error';
 /**
  * Tool result states - track the lifecycle of a tool result
  */
@@ -348,6 +348,12 @@ type RuntimeContextField<TContext> = IsUnknown<TContext> extends true ? {
 export type ToolExecutionContext<TContext = unknown> = RuntimeContextField<TContext> & {
     /** The ID of the tool call being executed */
     toolCallId?: string;
+    /**
+     * Abort signal for the current chat run. Aborts when the run's
+     * `abortController` fires (or middleware aborts). Long-running tools —
+     * e.g. MCP `callTool` — should forward this to cancel in-flight work.
+     */
+    abortSignal?: AbortSignal;
     /**
      * Emit a custom event during tool execution.
      * Events are streamed to the client in real-time as AG-UI CUSTOM events.
@@ -1342,6 +1348,12 @@ export interface VideoUrlResult {
     url: string;
     /** When the URL expires, if applicable */
     expiresAt?: Date;
+    /**
+     * Usage information for the completed generation, when the adapter can report
+     * it. For usage-based providers (e.g. fal) this carries `unitsBilled` — the
+     * real billed quantity — so consumers can compute exact cost.
+     */
+    usage?: TokenUsage;
 }
 /**
  * Options for text-to-speech generation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai",
-  "version": "0.27.0",
+  "version": "0.29.0",
   "description": "Type-safe TypeScript AI SDK for streaming chat, tool calling, agents, structured outputs, and multimodal generation.",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -68,7 +68,7 @@
     "@ag-ui/core": "^0.0.52",
     "@standard-schema/spec": "^1.1.0",
     "partial-json": "^0.1.7",
-    "@tanstack/ai-event-client": "0.5.3"
+    "@tanstack/ai-event-client": "0.6.0"
   },
   "peerDependencies": {
     "@opentelemetry/api": ">=1.9.0"

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

@@ -27,13 +27,13 @@ import { geminiImage } from '@tanstack/ai-gemini'
 | Model                           | Max Input | Max Output | Notes                        |
 | ------------------------------- | --------- | ---------- | ---------------------------- |
 | `gemini-3.1-pro-preview`        | 1M        | 65K        | Latest flagship, thinking    |
-| `gemini-3-pro-preview`          | 1M        | 65K        | Previous flagship            |
 | `gemini-3-flash-preview`        | 1M        | 65K        | Fast, thinking, multimodal   |
+| `gemini-3.1-flash-lite`         | 1M        | 65K        | Budget GA, thinking          |
 | `gemini-3.1-flash-lite-preview` | 1M        | 65K        | Budget, still capable        |
 | `gemini-2.5-pro`                | 1M        | 65K        | Stable release, all features |
 | `gemini-2.5-flash`              | 1M        | 65K        | Fast stable release          |
 
-All Gemini text models accept `text`, `image`, `audio`, `video`, and `document` input.
+Most Gemini text models accept `text`, `image`, `audio`, `video`, and `document` input; `gemini-2.5-flash` accepts all of these except `document`.
 
 ## Provider-Specific modelOptions
 

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

@@ -310,6 +310,77 @@ const { messages, sendMessage } = useChat({
 The only difference is swapping `toServerSentEventsResponse` / `fetchServerSentEvents`
 for `toHttpResponse` / `fetchHttpStream`. Everything else stays identical.
 
+### 5. MCP Tool Discovery via `chat({ mcp })`
+
+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.
+
+```typescript
+// Prop shape:
+// chat({
+//   ...,
+//   mcp: {
+//     clients: Array<MCPClient | MCPClients>,
+//     connection?: 'close' | 'keep-alive',  // default: 'close'
+//     lazyTools?: boolean,
+//     onDiscoveryError?: (error: unknown, source) => void,
+//   }
+// })
+```
+
+- **`clients`** — one or more `MCPClient` / `MCPClients` instances.
+- **`connection`** — `'close'` (default) closes each client when the run ends
+  (after the agent loop completes and the stream is drained); with
+  `'keep-alive'`, `chat()` never closes the clients — the caller owns their
+  lifecycle (keep connections warm across requests).
+- **`lazyTools`** — forwarded to `tools({ lazy: true })` so tool schemas are
+  sent to the LLM on demand.
+- **`onDiscoveryError`** — throw (or re-throw) to fail the entire call fast;
+  return normally to skip that source and continue. Omit to rethrow (fail-fast).
+
+**When to use `mcp` vs. the tools spread:**
+
+| Approach                                                | Use when                                                                                        |
+| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `chat({ mcp: { clients: [...] } })`                     | You want discovery + lifecycle managed for you, and don't need fully-typed input/output schemas |
+| `tools: [...await client.tools([toolDefinition(...)])]` | You want fully-typed MCP tools with Zod input/output validation                                 |
+
+**Server-side example:**
+
+```typescript
+import { createFileRoute } from '@tanstack/react-router'
+import { chat, toServerSentEventsResponse } from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
+import { createMCPClient } from '@tanstack/ai-mcp'
+
+export const Route = createFileRoute('/api/chat')({
+  server: {
+    handlers: {
+      POST: async ({ request }) => {
+        const { messages } = await request.json()
+
+        const mcpClient = await createMCPClient({
+          transport: { type: 'http', url: 'https://mcp.example.com/mcp' },
+        })
+
+        const stream = chat({
+          adapter: openaiText('gpt-5.5'),
+          messages,
+          mcp: {
+            clients: [mcpClient],
+            connection: 'keep-alive', // chat() won't close it — reuse across requests
+          },
+        })
+
+        return toServerSentEventsResponse(stream)
+        // connection: 'keep-alive' — chat() never closes mcpClient; it stays open for reuse across runs.
+      },
+    },
+  },
+})
+```
+
 ## Common Mistakes
 
 ### a. CRITICAL: Using Vercel AI SDK patterns (streamText, generateText)

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

@@ -343,10 +343,38 @@ const { generate, result, jobId, videoStatus, isLoading } = useGenerateVideo({
     console.log(`${status.status} (${status.progress}%)`),
 })
 
-// videoStatus: { jobId, status, progress?, url?, error? }
+// videoStatus: { jobId, status, progress?, url?, error?, usage? }
 // result (on completion): { url }
 ```
 
+### 6. Cost tracking (fal billable units)
+
+fal bills media generation by usage-based units, not tokens. Every fal media
+adapter (`falImage`, `falAudio`, `falSpeech`, `falTranscription`, `falVideo`)
+surfaces the real billed quantity on the result as `usage.unitsBilled`, read
+from fal's `x-fal-billable-units` response header — no `fetch` interceptor
+needed. It rides on the canonical `TokenUsage` shape (token fields are `0` for
+media), mirroring how duration-billed transcription surfaces `durationSeconds`.
+
+```typescript
+import { generateImage } from '@tanstack/ai'
+import { falImage } from '@tanstack/ai-fal'
+
+const result = await generateImage({
+  adapter: falImage('fal-ai/flux/dev'),
+  prompt: 'a serene mountain lake',
+})
+
+// usage.unitsBilled is the priced quantity. Multiply by the endpoint unit
+// price (GET https://api.fal.ai/v1/models/pricing?endpoint_id=…) for exact cost.
+if (result.usage?.unitsBilled != null) {
+  const cost = result.usage.unitsBilled * unitPrice
+}
+```
+
+For video, the units arrive with the completed result: `getVideoJobStatus()`
+returns `usage` and emits a `video:usage` devtools event when fal reports it.
+
 ---
 
 ## Common Hook API

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

@@ -375,6 +375,293 @@ gets the full schema, then calls `compareProducts` directly.
 Once discovered, a tool stays available for the conversation.
 When all lazy tools are discovered, the discovery tool is removed automatically.
 
+## MCP Tools
+
+`@tanstack/ai-mcp` lets a server-side `chat()` call discover and invoke tools
+hosted on any MCP server (Streamable HTTP, SSE, or stdio).
+
+### Basic usage — auto-discovery
+
+```typescript
+// src/routes/api.chat.ts
+import { createFileRoute } from '@tanstack/react-router'
+import { chat, toServerSentEventsResponse } from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
+import { createMCPClient } from '@tanstack/ai-mcp'
+
+export const Route = createFileRoute('/api/chat')({
+  server: {
+    handlers: {
+      POST: async ({ request }) => {
+        const { messages } = await request.json()
+
+        // 1. Connect to the MCP server.
+        const mcp = await createMCPClient({
+          transport: { type: 'http', url: 'https://mcp.example.com/mcp' },
+        })
+
+        // 2. Discover all tools from the server (returns ServerTool[]).
+        const mcpTools = await mcp.tools()
+
+        // 3. Spread them into chat() — they work exactly like hand-written tools.
+        // Caller owns the lifecycle — chat() never closes the client. Tools run
+        // while the response streams, so close in a middleware terminal hook
+        // (a try/finally around the return would close before tools execute).
+        const stream = chat({
+          adapter: openaiText('gpt-5.5'),
+          messages,
+          tools: [...mcpTools],
+          middleware: [
+            {
+              name: 'mcp-close',
+              onFinish: () => mcp.close(),
+              onAbort: () => mcp.close(),
+              onError: () => mcp.close(),
+            },
+          ],
+        })
+        return toServerSentEventsResponse(stream)
+      },
+    },
+  },
+})
+```
+
+### Typed path — pass toolDefinition instances
+
+Pass bare `toolDefinition()` instances (no `.server()`) to `client.tools([...])`.
+The MCP client supplies a `callTool` proxy as the execute function, while
+input/output validation and types come from the definitions' Zod schemas.
+
+```typescript
+import { toolDefinition } from '@tanstack/ai'
+import { createMCPClient } from '@tanstack/ai-mcp'
+import { z } from 'zod'
+
+const getWeather = toolDefinition({
+  name: 'get_weather',
+  description: 'Current weather for a city',
+  inputSchema: z.object({ city: z.string() }),
+  outputSchema: z.object({ temperature: z.number(), conditions: z.string() }),
+})
+
+const mcp = await createMCPClient({
+  transport: { type: 'http', url: 'https://mcp.example.com/mcp' },
+})
+
+// Returns ServerTool[] typed to the definitions' input/output schemas.
+// Throws MCPToolNotFoundError if the server does not expose a tool with that name.
+const tools = await mcp.tools([getWeather])
+
+const stream = chat({ adapter: openaiText('gpt-5.5'), messages, tools })
+```
+
+### Multiple servers with `createMCPClients`
+
+```typescript
+import { createMCPClients } from '@tanstack/ai-mcp'
+
+// Each key becomes the default prefix for that server's tools.
+await using pool = await createMCPClients({
+  github: { transport: { type: 'http', url: 'https://mcp.github.com/mcp' } },
+  linear: { transport: { type: 'http', url: 'https://mcp.linear.app/mcp' } },
+})
+
+// Tools auto-prefixed: 'github_search_repos', 'linear_create_issue', etc.
+const tools = await pool.tools()
+
+const stream = chat({ adapter: openaiText('gpt-5.5'), messages, tools })
+```
+
+Use `pool.clients.<name>` for typed per-server access (resources, prompts, typed
+`tools([defs])` overload).
+
+### `ToolExecutionContext.abortSignal` — cancelling long-running tools
+
+Every server tool's execute function now receives `abortSignal` in its context.
+When the chat run aborts (e.g. the client disconnects or calls the run's
+`abortController`), the signal fires and any in-flight `callTool` call is
+cancelled automatically.
+
+You can also forward it from your own server tools:
+
+```typescript
+const longRunningTool = myToolDef.server(async (args, ctx) => {
+  // Forward to fetch, a DB query, or an MCP callTool call.
+  const response = await fetch('https://slow.api/data', {
+    signal: ctx?.abortSignal,
+  })
+  return response.json()
+})
+```
+
+MCP tools wire this automatically — `makeMcpExecute` passes `ctx?.abortSignal`
+as the `signal` option to `client.callTool(...)`, so MCP server calls cancel
+with the chat run without any extra code.
+
+### stdio transport (Node-only)
+
+```typescript
+import { createMCPClient } from '@tanstack/ai-mcp'
+import { stdioTransport } from '@tanstack/ai-mcp/stdio'
+
+const mcp = await createMCPClient({
+  transport: stdioTransport({ command: 'npx', args: ['-y', 'my-mcp-server'] }),
+})
+```
+
+Import `stdioTransport` from the `/stdio` subpath only — it contains Node.js
+`child_process` imports and must not be bundled for edge runtimes.
+
+### `chat({ mcp })` — discovery + lifecycle in one prop
+
+Instead of manually calling `client.tools()` and managing `close()`, pass an
+`mcp` object and let `chat()` handle discovery and lifecycle.
+
+```typescript
+// Prop shape (ChatMCPOptions):
+// mcp: {
+//   clients: Array<MCPClient | MCPClients>,
+//   connection?: 'close' | 'keep-alive',  // default: 'close'
+//   lazyTools?: boolean,
+//   onDiscoveryError?: (error: unknown, source) => void,
+// }
+```
+
+- At run start, `chat()` calls `.tools()` on every entry in `clients` and merges
+  the results — identical to spreading `await client.tools()` into `tools: [...]`.
+- `lazyTools: true` is forwarded to `tools({ lazy: true })`.
+- `onDiscoveryError`: throw to fail-fast; return to skip that source.
+- `connection: 'close'` (default) closes each client when the run ends (after
+  the agent loop completes and the stream is drained). With `'keep-alive'`,
+  `chat()` never closes the clients — the caller owns their lifecycle (keep
+  connections warm across requests).
+
+**When to use `mcp` vs. the tools spread:**
+
+| Approach                                                | Use when                                                                          |
+| ------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| `chat({ mcp: { clients: [...] } })`                     | Convenience: discovery + lifecycle in one place; untyped tool args are acceptable |
+| `tools: [...await client.tools([toolDefinition(...)])]` | Fully-typed tool args/results via Zod schemas                                     |
+
+**Example:**
+
+```typescript
+import { createFileRoute } from '@tanstack/react-router'
+import { chat, toServerSentEventsResponse } from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
+import { createMCPClient } from '@tanstack/ai-mcp'
+
+export const Route = createFileRoute('/api/chat')({
+  server: {
+    handlers: {
+      POST: async ({ request }) => {
+        const { messages } = await request.json()
+
+        const mcpClient = await createMCPClient({
+          transport: { type: 'http', url: 'https://mcp.example.com/mcp' },
+        })
+
+        const stream = chat({
+          adapter: openaiText('gpt-5.5'),
+          messages,
+          mcp: {
+            clients: [mcpClient],
+            connection: 'keep-alive',
+            onDiscoveryError: (err, source) => {
+              console.warn('MCP discovery failed, skipping source:', err)
+              // returning (not throwing) skips this source and continues
+            },
+          },
+        })
+
+        return toServerSentEventsResponse(stream)
+      },
+    },
+  },
+})
+```
+
+## Provider Skills
+
+> **Not to be confused with `@tanstack/ai-code-mode-skills`**, which are locally-generated TypeScript functions executed client-side. Provider Skills are hosted, provider-managed bundles that the model loads on demand and runs inside the provider's server-side sandbox.
+
+Provider Skills are inert without an execution tool. The execution tool is what activates the sandbox; skills are additional capability bundles that run inside it:
+
+- **Anthropic**: skills require the `code_execution` tool (`@tanstack/ai-anthropic/tools`).
+- **OpenAI**: skills live inside the `shell` tool (`@tanstack/ai-openai/tools`) and are Responses API only.
+
+### Anthropic: `codeExecutionTool` with skills
+
+Import from `@tanstack/ai-anthropic/tools`:
+
+```typescript
+import { codeExecutionTool } from '@tanstack/ai-anthropic/tools'
+import { chat, toServerSentEventsResponse } from '@tanstack/ai'
+import { anthropicText } from '@tanstack/ai-anthropic'
+
+export async function POST(request: Request) {
+  const { messages } = await request.json()
+  const stream = chat({
+    adapter: anthropicText('claude-sonnet-4-5'),
+    messages,
+    tools: [
+      codeExecutionTool(
+        { type: 'code_execution_20250825', name: 'code_execution' },
+        {
+          skills: [{ type: 'anthropic', skill_id: 'pptx', version: 'latest' }],
+        },
+      ),
+    ],
+  })
+  return toServerSentEventsResponse(stream)
+}
+```
+
+`AnthropicContainerSkill` shape: `{ type: 'anthropic' | 'custom'; skill_id: string; version?: string }`. Constraints: max 8 skills per request; `skill_id` must be 1–64 characters.
+
+The adapter automatically:
+
+- Lifts the skills into the request's top-level `container.skills` param (the shape Anthropic's API requires).
+- Attaches the required beta headers (`code-execution-2025-08-25` plus `skills-2025-10-02` when skills are present). You do not set these manually.
+
+**Deprecation:** Setting skills via `modelOptions.container.skills` is deprecated. Use `codeExecutionTool(config, { skills })` instead — the legacy path bypasses the beta-header wiring.
+
+### OpenAI: `shellTool` with skills (Responses API only)
+
+Import from `@tanstack/ai-openai/tools`:
+
+```typescript
+import { shellTool } from '@tanstack/ai-openai/tools'
+import { chat, toServerSentEventsResponse } from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
+
+export async function POST(request: Request) {
+  const { messages } = await request.json()
+  const stream = chat({
+    adapter: openaiText('gpt-5.2'),
+    messages,
+    tools: [
+      shellTool({
+        environment: {
+          type: 'container_auto',
+          skills: [
+            { type: 'skill_reference', skill_id: 'skill_abc', version: '2' },
+          ],
+        },
+      }),
+    ],
+  })
+  return toServerSentEventsResponse(stream)
+}
+```
+
+`SkillReference` shape: `{ type: 'skill_reference'; skill_id: string; version?: string }`. `version` is a string — use a positive integer as a string (e.g. `'2'`) or `'latest'`. This is Responses API only; Chat Completions does not support the shell tool.
+
+### Scope
+
+Only hosted/managed-by-id skills (`type: 'anthropic'` / `type: 'custom'` for Anthropic; `type: 'skill_reference'` for OpenAI) are wired. Inline bundles, local-path, and upload-API skill creation are not handled by these factories.
+
 ## Common Mistakes
 
 ### a. HIGH: Not passing tool definitions to both server and client