@tanstack/ai 0.26.1 → 0.28.0

package/dist/esm/types.d.ts

@@ -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.
@@ -629,41 +635,6 @@ export interface TextOptions<TProviderOptionsSuperset extends Record<string, any
      */
     systemPrompts?: Array<SystemPrompt>;
     agentLoopStrategy?: AgentLoopStrategy;
-    /**
-     * Controls the randomness of the output.
-     * Higher values (e.g., 0.8) make output more random, lower values (e.g., 0.2) make it more focused and deterministic.
-     * Range: [0.0, 2.0]
-     *
-     * Note: Generally recommended to use either temperature or topP, but not both.
-     *
-     * Provider usage:
-     * - OpenAI: `temperature` (number) - in text.top_p field
-     * - Anthropic: `temperature` (number) - ranges from 0.0 to 1.0, default 1.0
-     * - Gemini: `generationConfig.temperature` (number) - ranges from 0.0 to 2.0
-     */
-    temperature?: number;
-    /**
-     * Nucleus sampling parameter. An alternative to temperature sampling.
-     * The model considers the results of tokens with topP probability mass.
-     * For example, 0.1 means only tokens comprising the top 10% probability mass are considered.
-     *
-     * Note: Generally recommended to use either temperature or topP, but not both.
-     *
-     * Provider usage:
-     * - OpenAI: `text.top_p` (number)
-     * - Anthropic: `top_p` (number | null)
-     * - Gemini: `generationConfig.topP` (number)
-     */
-    topP?: number;
-    /**
-     * The maximum number of tokens to generate in the response.
-     *
-     * Provider usage:
-     * - OpenAI: `max_output_tokens` (number) - includes visible output and reasoning tokens
-     * - Anthropic: `max_tokens` (number, required) - range x >= 1
-     * - Gemini: `generationConfig.maxOutputTokens` (number)
-     */
-    maxTokens?: number;
     /**
      * Additional metadata to attach to the request.
      * Can be used for tracking, debugging, or passing custom information.

package/dist/esm/utilities/sampling-keys.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Single source of truth for the provider-native key spellings that cap output
+ * tokens. Sampling options live in opaque, provider-native `modelOptions`, and
+ * every provider spells the token cap differently. Two call sites must agree on
+ * this set or they silently drift:
+ *
+ * - `activities/summarize/chat-stream-summarize.ts` — detects a caller-supplied
+ *   token limit so the summarize default never overrides it.
+ * - `middlewares/otel.ts` — picks the first numeric spelling to populate the
+ *   `gen_ai.request.max_tokens` attribute across providers.
+ *
+ * Keep this list in lockstep with `MAX_TOKENS_KEY_BY_ADAPTER` (the adapter →
+ * native-key map) in the summarize wrapper.
+ */
+export declare const MAX_TOKENS_KEYS: readonly ["max_output_tokens", "max_tokens", "max_completion_tokens", "maxOutputTokens", "maxCompletionTokens", "maxTokens"];
+/**
+ * Ollama nests sampling under `options`; its token cap is `options.num_predict`
+ * rather than a flat key.
+ */
+export declare const NESTED_MAX_TOKENS_KEY: "num_predict";

package/dist/esm/utilities/sampling-keys.js

@@ -0,0 +1,20 @@
+const MAX_TOKENS_KEYS = [
+  "max_output_tokens",
+  // OpenAI (Responses)
+  "max_tokens",
+  // Anthropic / Grok
+  "max_completion_tokens",
+  // Groq
+  "maxOutputTokens",
+  // Gemini
+  "maxCompletionTokens",
+  // OpenRouter
+  "maxTokens"
+  // generic / migration leftover (no adapter reads it)
+];
+const NESTED_MAX_TOKENS_KEY = "num_predict";
+export {
+  MAX_TOKENS_KEYS,
+  NESTED_MAX_TOKENS_KEY
+};
+//# sourceMappingURL=sampling-keys.js.map

package/dist/esm/utilities/sampling-keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sampling-keys.js","sources":["../../../src/utilities/sampling-keys.ts"],"sourcesContent":["/**\n * Single source of truth for the provider-native key spellings that cap output\n * tokens. Sampling options live in opaque, provider-native `modelOptions`, and\n * every provider spells the token cap differently. Two call sites must agree on\n * this set or they silently drift:\n *\n * - `activities/summarize/chat-stream-summarize.ts` — detects a caller-supplied\n *   token limit so the summarize default never overrides it.\n * - `middlewares/otel.ts` — picks the first numeric spelling to populate the\n *   `gen_ai.request.max_tokens` attribute across providers.\n *\n * Keep this list in lockstep with `MAX_TOKENS_KEY_BY_ADAPTER` (the adapter →\n * native-key map) in the summarize wrapper.\n */\nexport const MAX_TOKENS_KEYS = [\n  'max_output_tokens', // OpenAI (Responses)\n  'max_tokens', // Anthropic / Grok\n  'max_completion_tokens', // Groq\n  'maxOutputTokens', // Gemini\n  'maxCompletionTokens', // OpenRouter\n  'maxTokens', // generic / migration leftover (no adapter reads it)\n] as const\n\n/**\n * Ollama nests sampling under `options`; its token cap is `options.num_predict`\n * rather than a flat key.\n */\nexport const NESTED_MAX_TOKENS_KEY = 'num_predict' as const\n"],"names":[],"mappings":"AAcO,MAAM,kBAAkB;AAAA,EAC7B;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AACF;AAMO,MAAM,wBAAwB;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai",
-  "version": "0.26.1",
+  "version": "0.28.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.2"
+    "@tanstack/ai-event-client": "0.5.4"
   },
   "peerDependencies": {
     "@opentelemetry/api": ">=1.9.0"

package/skills/ai-core/adapter-configuration/SKILL.md

@@ -44,8 +44,10 @@ import { openaiText } from '@tanstack/ai-openai'
 const stream = chat({
   adapter: openaiText('gpt-5.2'),
   messages,
-  temperature: 0.7,
-  maxTokens: 1000,
+  modelOptions: {
+    temperature: 0.7,
+    max_output_tokens: 1000,
+  },
 })
 
 return toServerSentEventsResponse(stream)
@@ -55,6 +57,11 @@ The adapter factory function takes the model name as a string literal and an
 optional config object (API key, base URL, etc.). The model name is passed
 into the factory, not into `chat()`.
 
+Sampling options (`temperature`, token limits, `top_p`/`topP`, etc.) live
+inside `modelOptions` using each provider's native key — they are **not**
+top-level options on `chat()`. See the per-provider table in
+[Configuring Sampling](#5-configuring-sampling) below.
+
 ## Core Patterns
 
 ### 1. Adapter Selection
@@ -158,11 +165,11 @@ const openaiStream = chat({
 const anthropicStream = chat({
   adapter: anthropicText('claude-sonnet-4-6'),
   messages,
-  maxTokens: 16000,
   modelOptions: {
+    max_tokens: 16000,
     thinking: {
       type: 'enabled',
-      budget_tokens: 8000, // must be >= 1024 and < maxTokens
+      budget_tokens: 8000, // must be >= 1024 and < max_tokens
     },
   },
 })
@@ -171,8 +178,8 @@ const anthropicStream = chat({
 const adaptiveStream = chat({
   adapter: anthropicText('claude-sonnet-4-6'),
   messages,
-  maxTokens: 16000,
   modelOptions: {
+    max_tokens: 16000,
     thinking: {
       type: 'adaptive',
     },
@@ -224,7 +231,61 @@ const custom = myOpenai('ft:gpt-5.2:my-org:custom-model:abc123')
 At runtime, `extendAdapter` simply passes through to the original factory.
 The `_customModels` parameter is only used for type inference.
 
-### 5. Capability Flag: `supportsCombinedToolsAndSchema`
+### 5. Configuring Sampling
+
+Sampling controls (`temperature`, token limits, nucleus sampling) are passed
+inside `modelOptions` using each provider's **native** key. They are not
+top-level fields on `chat()`/`ai()`/`generate()`.
+
+```typescript
+// OpenAI — native keys
+chat({
+  adapter: openaiText('gpt-5.2'),
+  messages,
+  modelOptions: { temperature: 0.7, top_p: 0.9, max_output_tokens: 1000 },
+})
+
+// Anthropic
+chat({
+  adapter: anthropicText('claude-sonnet-4-6'),
+  messages,
+  modelOptions: { temperature: 0.7, top_p: 0.9, max_tokens: 1000 },
+})
+
+// Gemini — camelCase
+chat({
+  adapter: geminiText('gemini-2.5-pro'),
+  messages,
+  modelOptions: { temperature: 0.7, topP: 0.9, maxOutputTokens: 1000 },
+})
+
+// Ollama — NESTED under modelOptions.options
+chat({
+  adapter: ollamaText('llama3.3'),
+  messages,
+  modelOptions: {
+    options: { temperature: 0.7, top_p: 0.9, num_predict: 1000 },
+  },
+})
+```
+
+Per-provider sampling keys (all live inside `modelOptions`):
+
+| Provider          | Temperature   | Nucleus | Max output tokens                   |
+| ----------------- | ------------- | ------- | ----------------------------------- |
+| OpenAI            | `temperature` | `top_p` | `max_output_tokens`                 |
+| Anthropic         | `temperature` | `top_p` | `max_tokens`                        |
+| Gemini            | `temperature` | `topP`  | `maxOutputTokens`                   |
+| Grok (xAI)        | `temperature` | `top_p` | `max_tokens`                        |
+| Groq              | `temperature` | `top_p` | `max_completion_tokens`             |
+| OpenRouter (chat) | `temperature` | `topP`  | `maxCompletionTokens`               |
+| Ollama            | `temperature` | `top_p` | `num_predict` (nested in `options`) |
+
+`temperature` is the one key every provider names identically; token limits and
+some sampling options use provider-native names. Ollama nests all sampling under
+`modelOptions.options`.
+
+### 6. Capability Flag: `supportsCombinedToolsAndSchema`
 
 Adapters can declare an optional capability method:
 

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

@@ -39,12 +39,15 @@ Note: Model IDs use the format `claude-opus-4-6`, `claude-sonnet-4-6`, etc.
 chat({
   adapter: anthropicText('claude-sonnet-4-6'),
   messages,
-  maxTokens: 16000,
   modelOptions: {
+    // Sampling
+    temperature: 0.7,
+    top_p: 0.9, // cannot be combined with temperature
+    max_tokens: 16000,
     // Extended thinking (budget-based)
     thinking: {
       type: 'enabled',
-      budget_tokens: 8000, // must be >= 1024 and < maxTokens
+      budget_tokens: 8000, // must be >= 1024 and < max_tokens
     },
     // Adaptive thinking (claude-sonnet-4-6, claude-opus-4-6+)
     thinking: {
@@ -89,7 +92,7 @@ ANTHROPIC_API_KEY
 
 ## Gotchas
 
-- `thinking.budget_tokens` must be >= 1024 AND less than `maxTokens`.
+- `thinking.budget_tokens` must be >= 1024 AND less than `modelOptions.max_tokens`.
   Failing either check throws a validation error.
 - Cannot set both `top_p` and `temperature` at the same time (throws error).
 - `claude-3-5-haiku` and `claude-3-haiku` do NOT support extended thinking.

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

@@ -72,6 +72,9 @@ chat({
     // Response modalities
     responseModalities: ['TEXT'],
     // Sampling
+    temperature: 0.7,
+    topP: 0.9,
+    maxOutputTokens: 1000,
     topK: 40,
     seed: 42,
     presencePenalty: 0.5,

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

@@ -40,6 +40,9 @@ Models must be pulled first: `ollama pull llama3.3`
 
 Ollama models use a generic options type. Provider options vary by the
 underlying model. The adapter passes options through to the Ollama API.
+Sampling options are **nested** under `modelOptions.options` (this matches
+Ollama's own request shape) — `temperature`, `top_p`, and `num_predict`
+(max output tokens) all live there.
 
 ```typescript
 import { chat } from '@tanstack/ai'
@@ -48,7 +51,13 @@ import { ollamaText } from '@tanstack/ai-ollama'
 const stream = chat({
   adapter: ollamaText('llama3.3'),
   messages,
-  temperature: 0.7,
+  modelOptions: {
+    options: {
+      temperature: 0.7,
+      top_p: 0.9,
+      num_predict: 1000, // max output tokens
+    },
+  },
   // Ollama-specific options are limited compared to cloud providers
 })
 ```

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

@@ -44,6 +44,10 @@ chat({
   adapter: openaiText('gpt-5.4'),
   messages,
   modelOptions: {
+    // Sampling
+    temperature: 0.7,
+    top_p: 0.9,
+    max_output_tokens: 1000,
     // Reasoning (effort levels: none, minimal, low, medium, high)
     reasoning: {
       effort: 'high',

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

@@ -137,8 +137,10 @@ import { anthropicText } from '@tanstack/ai-anthropic'
 const stream = chat({
   adapter: anthropicText('claude-sonnet-4-5'),
   messages,
-  temperature: 0.7,
-  maxTokens: 2000,
+  modelOptions: {
+    temperature: 0.7,
+    max_tokens: 2000, // Anthropic-native key
+  },
   systemPrompts: ['You are a helpful assistant.'],
   abortController,
 })
@@ -308,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)
@@ -377,17 +450,32 @@ chat({ adapter: openaiText('gpt-5.2'), messages })
 
 The model is passed to the adapter factory, not to `chat()`.
 
-### f. HIGH: Nesting temperature/maxTokens in options object
+### f. HIGH: Passing sampling options at the root of chat()
+
+Sampling options (`temperature`, token limits, `top_p`/`topP`) are **not**
+top-level fields on `chat()`. They live inside `modelOptions` using the
+provider's native key.
 
 ```typescript
-// WRONG
+// WRONG — temperature/maxTokens are not root options
+chat({ adapter, messages, temperature: 0.7, maxTokens: 1000 })
+
+// WRONG — there is no `options` field either
 chat({ adapter, messages, options: { temperature: 0.7, maxTokens: 1000 } })
 
-// CORRECT
-chat({ adapter, messages, temperature: 0.7, maxTokens: 1000 })
+// CORRECT — inside modelOptions, provider-native keys (OpenAI shown)
+chat({
+  adapter,
+  messages,
+  modelOptions: { temperature: 0.7, max_output_tokens: 1000 },
+})
 ```
 
-All parameters are top-level on the `chat()` options object.
+`temperature` is universal across providers; token limits use provider-native
+keys (`max_output_tokens` for OpenAI, `max_tokens` for Anthropic/Grok,
+`maxOutputTokens` for Gemini, `max_completion_tokens` for Groq,
+`maxCompletionTokens` for OpenRouter, and `num_predict` nested under
+`modelOptions.options` for Ollama). See ai-core/adapter-configuration/SKILL.md.
 
 ### g. HIGH: Using providerOptions instead of modelOptions
 

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

@@ -68,6 +68,13 @@ Every hook receives a `ChatMiddlewareContext` as its first argument, which provi
 Terminal hooks (`onFinish`, `onAbort`, `onError`) are **mutually exclusive** -- exactly
 one fires per `chat()` invocation.
 
+> **Sampling in `onConfig`:** `temperature`, `topP`, and `maxTokens` are **not**
+> first-class fields on `ChatMiddlewareConfig`. To adjust sampling from
+> middleware, return a partial that mutates `config.modelOptions` using the
+> provider's native key (e.g. OpenAI `temperature` / `max_output_tokens`,
+> Anthropic `max_tokens`, Ollama nested `options.num_predict`). Returning a
+> top-level `temperature`/`maxTokens` has no effect.
+
 ### Phase values
 
 `ctx.phase` is one of:
@@ -304,6 +311,10 @@ const configTransform: ChatMiddleware = {
     if (ctx.phase === 'init') {
       return {
         systemPrompts: [...config.systemPrompts, 'Always respond in JSON.'],
+        // Sampling options are NOT first-class config fields — mutate them
+        // through `config.modelOptions` using the provider's native key.
+        // (e.g. OpenAI `temperature` / `max_output_tokens`.)
+        modelOptions: { ...config.modelOptions, temperature: 0.2 },
       }
     }
   },