@tanstack/ai 0.26.1 → 0.28.0

package/src/activities/chat/mcp/types.ts

@@ -0,0 +1,66 @@
+import type { ServerTool } from '../tools/tool-definition'
+
+/**
+ * Minimal structural shape that `chat({ mcp })` needs from an MCP client.
+ *
+ * `@tanstack/ai-mcp`'s `MCPClient` and `MCPClients` satisfy this interface by
+ * shape — the core `@tanstack/ai` package does NOT import `@tanstack/ai-mcp`
+ * (ai-mcp depends on ai, not the reverse).
+ */
+export interface MCPToolSource {
+  // Keep the options shape in sync with ai-mcp's `ToolsOptions` — extra
+  // optional fields added there still match structurally, but chat() only
+  // forwards what is declared here.
+  tools: (options?: { lazy?: boolean }) => Promise<Array<ServerTool>>
+  close: () => Promise<void>
+}
+
+/**
+ * Controls what happens to MCP connections when the chat run ends.
+ *
+ * - `'close'` (default) — `chat()` closes each connection when the run ends
+ *   (after the agent loop completes and the stream is drained), so tools can
+ *   still execute throughout the run.
+ * - `'keep-alive'` — `chat()` never closes the connections; the caller owns
+ *   their lifecycle (e.g. keep them warm across requests).
+ */
+export type MCPConnectionPolicy = 'close' | 'keep-alive'
+
+/**
+ * Options controlling MCP tool discovery and lifecycle for a `chat()` call.
+ */
+export interface ChatMCPOptions {
+  /**
+   * The MCP clients or client pools to discover tools from and manage.
+   */
+  clients: Array<MCPToolSource>
+
+  /**
+   * Connection lifecycle policy applied to all clients when the run ends.
+   *
+   * Defaults to `'close'`.
+   */
+  connection?: MCPConnectionPolicy
+
+  /**
+   * When `true`, tool schemas are fetched lazily (forwarded to
+   * `tools({ lazy: true })`).
+   *
+   * Defaults to `false`.
+   */
+  lazyTools?: boolean
+
+  /**
+   * Called when tool discovery fails for a single source.
+   *
+   * - Throw (or re-throw) from this handler to fail the entire chat call fast.
+   * - Return normally to skip that source and continue with remaining clients.
+   * - Omit this handler entirely to rethrow the error (fail-fast by default).
+   *
+   * Async handlers are awaited, so a rejected promise also fails fast.
+   */
+  onDiscoveryError?: (
+    error: unknown,
+    source: MCPToolSource,
+  ) => void | Promise<void>
+}

package/src/activities/chat/middleware/types.ts

@@ -90,7 +90,7 @@ export interface ChatMiddlewareContext<TContext = unknown> {
   systemPrompts: Array<SystemPrompt>
   /** Names of configured tools, if any */
   toolNames?: Array<string>
-  /** Flattened generation options (temperature, topP, maxTokens, metadata) */
+  /** Flattened generation options (metadata) */
   options?: Record<string, unknown> | undefined
   /** Provider-specific model options */
   modelOptions?: Record<string, unknown> | undefined
@@ -130,9 +130,6 @@ export interface ChatMiddlewareConfig {
   messages: Array<ModelMessage>
   systemPrompts: Array<SystemPrompt>
   tools: Array<Tool>
-  temperature?: number
-  topP?: number
-  maxTokens?: number
   metadata?: Record<string, unknown> | undefined
   modelOptions?: Record<string, unknown> | undefined
 }

package/src/activities/chat/stream/message-updaters.ts

@@ -161,10 +161,14 @@ export function updateToolCallApproval(
     )
 
     if (toolCallPart) {
-      toolCallPart.state = 'approval-requested'
-      toolCallPart.approval = {
-        id: approvalId,
-        needsApproval: true,
+      const index = parts.indexOf(toolCallPart)
+      parts[index] = {
+        ...toolCallPart,
+        state: 'approval-requested',
+        approval: {
+          id: approvalId,
+          needsApproval: true,
+        },
       }
     }
 
@@ -192,7 +196,8 @@ export function updateToolCallState(
     )
 
     if (toolCallPart) {
-      toolCallPart.state = state
+      const index = parts.indexOf(toolCallPart)
+      parts[index] = { ...toolCallPart, state }
     }
 
     return { ...msg, parts }
@@ -217,8 +222,12 @@ export function updateToolCallWithOutput(
     )
 
     if (toolCallPart) {
-      toolCallPart.output = errorText ? { error: errorText } : output
-      toolCallPart.state = state ?? (errorText ? 'input-complete' : 'complete')
+      const index = parts.indexOf(toolCallPart)
+      parts[index] = {
+        ...toolCallPart,
+        output: errorText ? { error: errorText } : output,
+        state: state ?? (errorText ? 'input-complete' : 'complete'),
+      }
     }
 
     return { ...msg, parts }
@@ -242,8 +251,12 @@ export function updateToolCallApprovalResponse(
     )
 
     if (toolCallPart && toolCallPart.approval) {
-      toolCallPart.approval.approved = approved
-      toolCallPart.state = 'approval-responded'
+      const index = parts.indexOf(toolCallPart)
+      parts[index] = {
+        ...toolCallPart,
+        approval: { ...toolCallPart.approval, approved },
+        state: 'approval-responded',
+      }
     }
 
     return { ...msg, parts }

package/src/activities/chat/tools/tool-calls.ts

@@ -599,6 +599,7 @@ export async function* executeToolCalls<TContext = unknown>(
   ) => CustomEvent,
   middlewareHooks?: ToolExecutionMiddlewareHooks,
   userContext?: TContext,
+  abortSignal?: AbortSignal,
 ): AsyncGenerator<CustomEvent, ExecuteToolCallsResult, void> {
   const results: Array<ToolResult> = []
   const needsApproval: Array<ApprovalRequest> = []
@@ -679,6 +680,7 @@ export async function* executeToolCalls<TContext = unknown>(
     const context = {
       toolCallId: toolCall.id,
       context: userContext,
+      abortSignal,
       emitCustomEvent: (eventName: string, value: Record<string, any>) => {
         if (createCustomEventChunk) {
           pendingEvents.push(

package/src/activities/summarize/chat-stream-summarize.ts

@@ -1,5 +1,6 @@
 import { EventType } from '@ag-ui/core'
 import { toRunErrorPayload } from '../error-payload'
+import { MAX_TOKENS_KEYS } from '../../utilities/sampling-keys'
 import { BaseSummarizeAdapter } from './adapter'
 import type {
   StreamChunk,
@@ -23,6 +24,139 @@ export interface ChatStreamCapable {
   chatStream: (options: TextOptions<any>) => AsyncIterable<StreamChunk>
 }
 
+/**
+ * Provider-native max-output-tokens key per summarize-adapter `name`. summarize
+ * is provider-agnostic and forwards `modelOptions` opaquely to the wrapped text
+ * adapter, so `maxLength` must be written under the exact key the underlying
+ * provider reads — no adapter reads a generic `maxTokens`. Ollama is the one
+ * exception: it nests sampling under `options`, so it has no entry here and is
+ * handled as a special nested case in `applyMaxLength`/`applyDefaultTemperature`.
+ *
+ * Keep in sync with each adapter's wire mapping:
+ * - OpenAI (Responses): `max_output_tokens`
+ * - Anthropic / Grok: `max_tokens`
+ * - Groq: `max_completion_tokens`
+ * - Gemini: `maxOutputTokens`
+ * - OpenRouter: `maxCompletionTokens`
+ * - Ollama: nested `options.num_predict` (no entry — see `applyMaxLength`)
+ */
+const MAX_TOKENS_KEY_BY_ADAPTER: Record<string, string> = {
+  openai: 'max_output_tokens',
+  anthropic: 'max_tokens',
+  grok: 'max_tokens',
+  groq: 'max_completion_tokens',
+  gemini: 'maxOutputTokens',
+  openrouter: 'maxCompletionTokens',
+}
+
+/**
+ * Every flat key any supported provider uses to cap output tokens (plus the
+ * generic `maxTokens` spelling no adapter reads). Used to detect a
+ * caller-supplied token limit so the summarize default never overrides an
+ * explicit caller value. Shared with the OTel middleware via
+ * `MAX_TOKENS_KEYS` so the two spelling sets cannot drift.
+ */
+const KNOWN_MAX_TOKENS_KEYS = MAX_TOKENS_KEYS
+
+/**
+ * Whether `applyMaxLength` knows how to place a token limit for this adapter
+ * `name` (either the nested Ollama shape or a flat provider-native key).
+ * Used to surface a warning when `maxLength` would otherwise be silently
+ * dropped for an unrecognised adapter name.
+ */
+function isKnownMaxTokensAdapter(adapterName: string): boolean {
+  return (
+    adapterName === 'ollama' ||
+    MAX_TOKENS_KEY_BY_ADAPTER[adapterName] !== undefined
+  )
+}
+
+/**
+ * Apply the low-temperature summarize default to a working copy of the
+ * caller's `modelOptions`, placed where the wrapped provider actually reads
+ * it (nested under `options` for Ollama, flat otherwise). The caller always
+ * wins: if they already set `temperature` in that location, it is untouched.
+ */
+function applyDefaultTemperature(
+  adapterName: string,
+  temperature: number,
+  modelOptions: Record<string, unknown>,
+): Record<string, unknown> {
+  const merged: Record<string, unknown> = { ...modelOptions }
+
+  if (adapterName === 'ollama') {
+    const existing =
+      merged.options && typeof merged.options === 'object'
+        ? (merged.options as Record<string, unknown>)
+        : undefined
+    if (existing && 'temperature' in existing) return merged
+    merged.options = { temperature, ...existing }
+    return merged
+  }
+
+  if ('temperature' in merged) return merged
+  merged.temperature = temperature
+  return merged
+}
+
+/**
+ * Resolve `maxLength` to the provider-native max-output-tokens key for the
+ * given summarize-adapter `name` (this wrapper's OWN `name`, not the wrapped
+ * text adapter's) and merge it into a working copy of the caller's
+ * `modelOptions`. The caller always wins: if they already set any recognised
+ * token-limit key (flat or, for Ollama, nested `options.num_predict`), the
+ * default is left untouched. Unknown/unrecognised adapter names fall back to
+ * NOT setting a token key (the prompt hint still asks the model to stay under
+ * `maxLength`) rather than writing a dead key no provider reads.
+ *
+ * Caveat (intentional): "caller wins" keys off ANY recognised spelling in
+ * `KNOWN_MAX_TOKENS_KEYS`, but only the adapter's native key is read on the
+ * wire. So a caller who sets a NON-native spelling for this provider — e.g.
+ * `maxTokens`, or Anthropic's `max_tokens` against an OpenAI adapter — suppresses
+ * the summarize default WITHOUT getting their own value applied either: neither
+ * cap reaches the wire. This favours never clobbering a migration leftover over
+ * guaranteeing a cap; the prompt-level hint still asks the model to stay under
+ * `maxLength`. Rename the key to the provider-native spelling to forward it.
+ */
+function applyMaxLength(
+  adapterName: string,
+  maxLength: number,
+  modelOptions: Record<string, unknown>,
+): Record<string, unknown> {
+  const merged: Record<string, unknown> = { ...modelOptions }
+
+  if (adapterName === 'ollama') {
+    // Honor a caller-set limit in either shape: a recognised flat key (e.g.
+    // left over from a migration) or the nested `options.num_predict`.
+    const callerSetFlatLimit = KNOWN_MAX_TOKENS_KEYS.some(
+      (k) => typeof merged[k] === 'number',
+    )
+    const existing =
+      merged.options && typeof merged.options === 'object'
+        ? (merged.options as Record<string, unknown>)
+        : undefined
+    if (
+      callerSetFlatLimit ||
+      (existing && typeof existing.num_predict === 'number')
+    ) {
+      return merged
+    }
+    merged.options = { num_predict: maxLength, ...existing }
+    return merged
+  }
+
+  const key = MAX_TOKENS_KEY_BY_ADAPTER[adapterName]
+  if (key === undefined) return merged
+
+  const callerSetLimit = KNOWN_MAX_TOKENS_KEYS.some(
+    (k) => typeof merged[k] === 'number',
+  )
+  if (callerSetLimit) return merged
+
+  merged[key] = maxLength
+  return merged
+}
+
 /**
  * Extract the per-model `modelOptions` type a text adapter accepts. Used by
  * provider summarize factories so their `modelOptions` IntelliSense matches
@@ -195,13 +329,38 @@ export class ChatStreamSummarizeAdapter<
     options: SummarizationOptions<TProviderOptions>,
     systemPrompt: string,
   ): TextOptions<TProviderOptions> {
+    // Sampling knobs now live in provider-native `modelOptions`. Apply the
+    // low-temperature default where the wrapped provider actually reads it
+    // (nested under `options` for Ollama, flat otherwise) so callers can still
+    // override it. Resolving the placement from this summarize adapter's OWN
+    // `name` keeps the default off the wire correctly per provider — a flat
+    // `temperature` would be silently dropped by Ollama while still showing up
+    // in OTel.
+    let working: Record<string, unknown> = {
+      ...(options.modelOptions as Record<string, unknown> | undefined),
+    }
+    working = applyDefaultTemperature(this.name, 0.3, working)
+    // `maxLength` must reach the wire under the provider-native token key (it
+    // differs per provider, and no adapter reads a generic `maxTokens`).
+    // Resolve it from this summarize adapter's `name` (the constructor arg,
+    // not the wrapped text adapter's name), never overriding a caller-supplied
+    // token limit.
+    if (options.maxLength !== undefined) {
+      if (!isKnownMaxTokensAdapter(this.name)) {
+        options.logger.warn(
+          `summarize: maxLength=${options.maxLength} could not be mapped to a provider token key for adapter name "${this.name}" — it was dropped from modelOptions (the prompt still asks the model to stay under it). Construct ChatStreamSummarizeAdapter with a recognised provider name to forward the cap.`,
+          { provider: this.name },
+        )
+      }
+      working = applyMaxLength(this.name, options.maxLength, working)
+    }
+    const modelOptions = working as TProviderOptions
+
     return {
       model: options.model,
       messages: [{ role: 'user', content: options.text }],
       systemPrompts: [systemPrompt],
-      maxTokens: options.maxLength,
-      temperature: 0.3,
-      modelOptions: options.modelOptions,
+      modelOptions,
       logger: options.logger,
     }
   }

package/src/extend-adapter.ts

@@ -144,6 +144,14 @@ type ExtractCustomModelNames<TDefs extends ReadonlyArray<ExtendedModelDef>> =
 // Factory Type Inference
 // ===========================
 
+/**
+ * The widest factory shape `extendAdapter` accepts: any function taking a
+ * model as its first parameter. Parameters are contravariant, so `never`
+ * params and an `unknown` return accept every factory without resorting
+ * to `any`.
+ */
+type AnyAdapterFactory = (model: never, ...args: Array<never>) => unknown
+
 /**
  * Infer the model parameter type from an adapter factory function.
  * For generic functions like `<T extends Union>(model: T)`, this gets `T` which
@@ -151,32 +159,44 @@ type ExtractCustomModelNames<TDefs extends ReadonlyArray<ExtendedModelDef>> =
  */
 type InferFactoryModels<TFactory> = TFactory extends (
   model: infer TModel,
-  ...args: Array<any>
-) => any
+  ...args: Array<never>
+) => unknown
   ? TModel extends string
     ? TModel
     : string
   : string
 
-/**
- * Infer the config parameter type from an adapter factory function.
- */
-type InferConfig<TFactory> = TFactory extends (
-  model: any,
-  config?: infer TConfig,
-) => any
-  ? TConfig
-  : undefined
-
 /**
  * Infer the adapter return type from a factory function.
  */
 type InferAdapterReturn<TFactory> = TFactory extends (
-  ...args: Array<any>
+  ...args: Array<never>
 ) => infer TReturn
   ? TReturn
   : never
 
+/**
+ * Extracts all parameter types after the model parameter from a factory,
+ * preserving labels and optionality (e.g. `[apiKey: string, config?: C]`).
+ * Note: overloaded factories resolve against their last overload (a
+ * `Parameters` limitation).
+ */
+type InferRestArgs<TFactory extends AnyAdapterFactory> =
+  Parameters<TFactory> extends [unknown?, ...infer TRest] ? TRest : []
+
+/**
+ * The factory signature produced by `extendAdapter`: accepts both original
+ * and custom model names while preserving all remaining parameters and the
+ * return type of the original factory.
+ */
+type ExtendedFactory<
+  TFactory extends AnyAdapterFactory,
+  TDefs extends ReadonlyArray<ExtendedModelDef>,
+> = (
+  model: InferFactoryModels<TFactory> | ExtractCustomModelNames<TDefs>,
+  ...args: InferRestArgs<TFactory>
+) => InferAdapterReturn<TFactory>
+
 // ===========================
 // extendAdapter Function
 // ===========================
@@ -225,19 +245,17 @@ type InferAdapterReturn<TFactory> = TFactory extends (
  * ```
  */
 export function extendAdapter<
-  TFactory extends (...args: Array<any>) => any,
+  TFactory extends AnyAdapterFactory,
   const TDefs extends ReadonlyArray<ExtendedModelDef>,
->(
-  factory: TFactory,
-  _customModels: TDefs,
-): (
-  model: InferFactoryModels<TFactory> | ExtractCustomModelNames<TDefs>,
-  ...args: InferConfig<TFactory> extends undefined
-    ? []
-    : [config?: InferConfig<TFactory>]
-) => InferAdapterReturn<TFactory> {
+>(factory: TFactory, _customModels: TDefs): ExtendedFactory<TFactory, TDefs>
+// The implementation signature stays at the honest `AnyAdapterFactory` width;
+// the overload above performs the deliberate model-union widening.
+export function extendAdapter(
+  factory: AnyAdapterFactory,
+  _customModels: ReadonlyArray<ExtendedModelDef>,
+): AnyAdapterFactory {
   // At runtime, we simply pass through to the original factory.
   // The _customModels parameter is only used for type inference.
   // No runtime validation - users are trusted to pass valid model names.
-  return factory as any
+  return factory
 }

package/src/index.ts

@@ -52,6 +52,16 @@ export {
   type InferToolOutput,
 } from './activities/chat/tools/tool-definition'
 
+// MCP chat option types
+export type {
+  MCPToolSource,
+  ChatMCPOptions,
+  MCPConnectionPolicy,
+} from './activities/chat/mcp/types'
+
+// MCP error classes (value exports — usable with instanceof)
+export { MCPDuplicateToolNameError } from './activities/chat/mcp/manager'
+
 // Schema conversion (Standard JSON Schema compliant)
 export {
   convertSchemaToJsonSchema,

package/src/logger/internal-logger.ts

@@ -104,4 +104,22 @@ export class InternalLogger {
   request(message: string, meta?: Record<string, unknown>): void {
     this.emit('debug', 'request', message, meta)
   }
+
+  /**
+   * Log a non-fatal misconfiguration or recoverable anomaly. Gated by the
+   * `errors` category — on by default (and when `debug` is unspecified), so
+   * silent-drop conditions surface, but still silenced by `debug: false`,
+   * which honors the "disable everything including errors" contract. Routes to
+   * the underlying logger's `warn` level.
+   */
+  warn(message: string, meta?: Record<string, unknown>): void {
+    if (!this.categories.errors) return
+    const prefixed = `⚠️ [tanstack-ai:warn] ⚠️ ${message}`
+    try {
+      this.logger.warn(prefixed, meta)
+    } catch {
+      // User-supplied logger threw; swallow so a broken logger never masks the
+      // condition we were trying to surface.
+    }
+  }
 }

package/src/middlewares/otel.ts

@@ -4,6 +4,10 @@ import {
   context as otelContext,
   trace as otelTrace,
 } from '@opentelemetry/api'
+import {
+  MAX_TOKENS_KEYS,
+  NESTED_MAX_TOKENS_KEY,
+} from '../utilities/sampling-keys'
 import type {
   AttributeValue,
   Exception,
@@ -162,6 +166,19 @@ function messageEventName(role: string): string {
   }
 }
 
+/**
+ * Return the first candidate that is a finite `number`, or `undefined`. Used to
+ * pick a sampling attribute from among the several provider-native spellings.
+ */
+function firstNumber(...candidates: Array<unknown>): number | undefined {
+  for (const candidate of candidates) {
+    if (typeof candidate === 'number' && Number.isFinite(candidate)) {
+      return candidate
+    }
+  }
+  return undefined
+}
+
 function errorMessage(err: unknown): string | undefined {
   if (err instanceof Error) return err.message
   if (typeof err === 'string') return err
@@ -333,12 +350,37 @@ export function otelMiddleware(options: OtelMiddlewareOptions): ChatMiddleware {
           'gen_ai.request.model': ctx.model,
           'tanstack.ai.iteration': ctx.iteration,
         }
-        if (config.temperature !== undefined)
-          baseAttrs['gen_ai.request.temperature'] = config.temperature
-        if (config.topP !== undefined)
-          baseAttrs['gen_ai.request.top_p'] = config.topP
-        if (config.maxTokens !== undefined)
-          baseAttrs['gen_ai.request.max_tokens'] = config.maxTokens
+        // Sampling options now live in provider-native `modelOptions`, and
+        // providers spell them differently (e.g. `max_output_tokens`,
+        // `max_completion_tokens`, `maxOutputTokens`, `num_predict`). Read the
+        // first numeric value among the known spellings — including Ollama's
+        // nested `options` — so gen_ai attributes populate across providers.
+        const sampling = config.modelOptions ?? {}
+        const nestedOptions =
+          sampling['options'] && typeof sampling['options'] === 'object'
+            ? (sampling['options'] as Record<string, unknown>)
+            : undefined
+        const samplingTemperature = firstNumber(
+          sampling['temperature'],
+          nestedOptions?.['temperature'],
+        )
+        const samplingTopP = firstNumber(
+          sampling['top_p'],
+          sampling['topP'],
+          nestedOptions?.['top_p'],
+        )
+        // Spellings come from the shared `MAX_TOKENS_KEYS` table so this stays
+        // in lockstep with the summarize wrapper's caller-limit detection.
+        const samplingMaxTokens = firstNumber(
+          ...MAX_TOKENS_KEYS.map((k) => sampling[k]),
+          nestedOptions?.[NESTED_MAX_TOKENS_KEY],
+        )
+        if (samplingTemperature !== undefined)
+          baseAttrs['gen_ai.request.temperature'] = samplingTemperature
+        if (samplingTopP !== undefined)
+          baseAttrs['gen_ai.request.top_p'] = samplingTopP
+        if (samplingMaxTokens !== undefined)
+          baseAttrs['gen_ai.request.max_tokens'] = samplingMaxTokens
 
         const baseOptions: SpanOptions = {
           kind: SpanKind.CLIENT,

package/src/types.ts

@@ -490,6 +490,12 @@ 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.
@@ -812,41 +818,6 @@ export interface TextOptions<
    */
   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/src/utilities/sampling-keys.ts

@@ -0,0 +1,28 @@
+/**
+ * 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 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)
+] as const
+
+/**
+ * Ollama nests sampling under `options`; its token cap is `options.num_predict`
+ * rather than a flat key.
+ */
+export const NESTED_MAX_TOKENS_KEY = 'num_predict' as const