@tanstack/ai 0.59.0 → 0.61.0

package/src/activities/chat/stream/processor.ts

@@ -25,14 +25,20 @@ import {
   uiMessageToModelMessages,
 } from '../messages.js'
 import { runErrorEventToError } from '../../../utilities/errors'
-import { isProviderExecutedToolCall } from '../../../utilities/provider-executed'
+import {
+  isAssistantSegmentOf,
+  isProviderExecutedToolCall,
+} from '../../../utilities/provider-executed'
 import {
   mergeMetadata,
   tanstackMetadata,
 } from '../../../utilities/merge-metadata'
 import { getChunkRunId } from '../../../utilities/chunk-ids'
 import type { AdapterYieldChunk } from '../../../utilities/adapter-yield-chunk'
-import { normalizeToolResult } from '../../../utilities/tool-result'
+import {
+  normalizeToolResult,
+  toolResultErrorText,
+} from '../../../utilities/tool-result'
 import { defaultJSONParser } from './json-parser'
 import {
   appendStructuredOutputDelta,
@@ -1518,20 +1524,30 @@ export class StreamProcessor {
         pending.push(msg)
         continue
       }
+      let next = msg
       if (
         msg.role === 'assistant' &&
         pending.length > 0 &&
         !isToolResultOnly(msg)
       ) {
-        out.push({
+        next = {
           ...msg,
           parts: [...pending.flatMap(thinkingParts), ...msg.parts],
-        })
+        }
         pending = []
+      } else {
+        flushPending()
+      }
+      const prev = out.at(-1)
+      if (
+        prev?.role === 'assistant' &&
+        next.role === 'assistant' &&
+        isAssistantSegmentOf(next.id, prev.id)
+      ) {
+        out[out.length - 1] = { ...prev, parts: [...prev.parts, ...next.parts] }
         continue
       }
-      flushPending()
-      out.push(msg)
+      out.push(next)
     }
     flushPending()
     return out
@@ -1705,9 +1721,7 @@ export class StreamProcessor {
             }
           }
           const errorText =
-            result.state === 'error'
-              ? this.extractToolResultError(output)
-              : undefined
+            result.state === 'error' ? toolResultErrorText(output) : undefined
           next = {
             ...next,
             output: errorText ? { error: errorText } : output,
@@ -2001,18 +2015,6 @@ export class StreamProcessor {
     }
   }
 
-  private extractToolResultError(output: unknown): string {
-    if (
-      output &&
-      typeof output === 'object' &&
-      'error' in output &&
-      typeof output.error === 'string'
-    ) {
-      return output.error
-    }
-    return typeof output === 'string' ? output : 'Tool execution failed'
-  }
-
   /**
    * Handle TOOL_CALL_RESULT event (AG-UI spec).
    *
@@ -2069,7 +2071,7 @@ export class StreamProcessor {
       chunk.toolCallId,
       aguiContentToContentParts(chunk.content),
       resultState,
-      resultState === 'error' ? this.extractToolResultError(output) : undefined,
+      resultState === 'error' ? toolResultErrorText(output) : undefined,
     )
     this.emitMessagesChange()
   }

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

@@ -1,5 +1,6 @@
 import { normalizeToolResult } from '../../../utilities/tool-result'
 import { tanstackMetadata } from '../../../utilities/merge-metadata'
+import { isProviderExecutedToolCall } from '../../../utilities/provider-executed'
 import type { AdapterYieldChunk } from '../../../utilities/adapter-yield-chunk'
 import { isStandardSchema, parseWithStandardSchema } from './schema-converter'
 import type { ToolApprovalResolution } from '../../../interrupts'
@@ -854,6 +855,11 @@ export async function* executeToolCalls<TContext = unknown>(
   })
 
   for (const toolCall of toolCalls) {
+    // Provider-executed tools (Anthropic web_search / web_fetch) already ran
+    // inside the provider response and carry their result on the call's
+    // metadata. They have no execute() and must not become client requests.
+    if (isProviderExecutedToolCall(toolCall)) continue
+
     const tool = toolMap.get(toolCall.function.name)
     const toolName = toolCall.function.name
 

package/src/activities/embed/adapter.ts

@@ -39,6 +39,12 @@ export interface EmbeddingAdapter<
   readonly kind: 'embedding'
   /** Adapter name identifier */
   readonly name: string
+  /**
+   * Declares that this adapter can consume `{ type: 'file' }` content
+   * sources (provider Files API references). `embed()` rejects file sources
+   * in preflight for adapters that don't declare this.
+   */
+  readonly supportsFileSources?: boolean
   /** The model this adapter is configured for */
   readonly model: TModel
 
@@ -85,6 +91,7 @@ export abstract class BaseEmbeddingAdapter<
 > {
   readonly kind = 'embedding' as const
   abstract readonly name: string
+  readonly supportsFileSources: boolean = false
   readonly model: TModel
 
   // Type-only property - never assigned at runtime

package/src/activities/embed/index.ts

@@ -15,6 +15,7 @@ import {
   runGenerationUsage,
 } from '../middleware/run'
 import { countEmbeddingInputModalities } from '../../utilities/embedding-input'
+import { assertPromptFileSourceSupport } from '../../utilities/content-source'
 import type { InternalLogger } from '../../logger/internal-logger'
 import type { DebugOption } from '../../logger/types'
 import type { GenerationMiddleware } from '../middleware/types'
@@ -190,6 +191,10 @@ export async function embed<
   TAdapter extends EmbeddingAdapter<string, any, any, any>,
 >(options: EmbedOptions<TAdapter>): Promise<EmbeddingResult> {
   const { adapter, middleware } = options
+  // Fail closed on `{ type: 'file' }` sources before middleware start. No
+  // embedding adapter consumes file handles today; this matches chat /
+  // generateImage / generateVideo.
+  assertPromptFileSourceSupport(adapter, options.input)
   const model = adapter.model
   const requestId = createId('embedding')
   const startTime = Date.now()

package/src/activities/files/adapter.ts

@@ -0,0 +1,120 @@
+/**
+ * Files Adapter
+ *
+ * Base class and interface for the `files` activity — a provider's native Files
+ * API (upload a media asset once, reference it later by the returned handle
+ * instead of re-sending base64 or a public URL each request).
+ *
+ * Providers with a native surface expose a factory (`openaiFiles()`,
+ * `anthropicFiles()`, `geminiFiles()`, `falFiles()`). `upload` is required;
+ * `get`/`delete` are optional because not every provider has a lifecycle API
+ * (fal's storage is upload-only).
+ */
+
+import { base64ToArrayBuffer } from '@tanstack/ai-utils'
+
+/**
+ * Input to {@link FilesAdapter.upload}. Either a `Blob` (memory-efficient,
+ * preferred for large assets) or base64 `data` plus its `mimeType`.
+ */
+export type FileUploadInput =
+  | Blob
+  | {
+      /** Base64-encoded file bytes. */
+      data: string
+      /** MIME type of the bytes (e.g. `'image/png'`, `'application/pdf'`). */
+      mimeType: string
+      /** Optional filename hint sent to providers that accept one. */
+      filename?: string
+    }
+
+/**
+ * A provider-issued file handle returned by {@link FilesAdapter.upload} /
+ * {@link FilesAdapter.get}. Reference it in a message via a `{ type: 'file' }`
+ * content source — use `fileSourceFromHandle` to build one.
+ *
+ * `TProvider` carries the issuing provider's name as a literal (`'openai'`,
+ * `'gemini'`, ...) when the handle came from a concrete files adapter, so
+ * cross-provider lifecycle calls (`deleteFile` with a foreign handle) fail at
+ * compile time. It defaults to `string` so wire-deserialized handles still fit.
+ */
+export interface FileHandle<TProvider extends string = string> {
+  /**
+   * Provider handle used for lifecycle operations (`get`/`delete`): the
+   * OpenAI/Anthropic `file_id`, the Gemini file resource name (`files/...`), or
+   * the fal storage URL (fal itself has no lifecycle API — the URL doubles as
+   * the wire reference).
+   */
+  id: string
+  /** The provider that issued the handle (`'openai'`, `'gemini'`, ...). */
+  provider: TProvider
+  /**
+   * The handle's URL form when the provider exposes one (Gemini file URI, fal
+   * storage URL). For providers whose handle is an opaque id (OpenAI,
+   * Anthropic) this is `undefined`.
+   */
+  uri?: string
+  /** MIME type reported by the provider (or echoed from the upload input). */
+  mimeType?: string
+  /** File size in bytes when the provider reports it. */
+  sizeBytes?: number
+  /** Expiry as epoch milliseconds when the handle is scheduled to expire. */
+  expiresAt?: number
+  /** Original filename when the provider reports it. */
+  filename?: string
+}
+
+/**
+ * The `files` adapter contract. `upload` is required; `get`/`delete` are
+ * optional and present only when the provider has a lifecycle API.
+ *
+ * `TName` is the provider name literal (`'openai'`, `'gemini'`, ...); concrete
+ * adapters bind it so the handles they issue carry their provenance in the
+ * type system.
+ */
+export interface FilesAdapter<TName extends string = string> {
+  readonly kind: 'files'
+  readonly name: TName
+  upload: (input: FileUploadInput) => Promise<FileHandle<TName>>
+  get?: (id: string) => Promise<FileHandle<TName>>
+  delete?: (id: string) => Promise<void>
+}
+
+export type AnyFilesAdapter = FilesAdapter<string>
+
+/**
+ * Normalize a {@link FileUploadInput} to a `Blob` (plus best-effort MIME /
+ * filename) so provider adapters can hand it straight to their SDK. A `Blob`
+ * input passes through; base64 `{ data }` is decoded to bytes. Shared so
+ * provider files adapters don't each re-implement the decode.
+ */
+export function normalizeFileUploadInput(input: FileUploadInput): {
+  blob: Blob
+  mimeType?: string
+  filename?: string
+} {
+  if (input instanceof Blob) {
+    return { blob: input, mimeType: input.type || undefined }
+  }
+  const bytes = base64ToArrayBuffer(input.data)
+  return {
+    blob: new Blob([bytes], { type: input.mimeType }),
+    mimeType: input.mimeType,
+    filename: input.filename,
+  }
+}
+
+/**
+ * Abstract base for provider files adapters. Subclasses bind `TName` to their
+ * provider literal, set `name`, implement `upload`, and may add `get`/`delete`
+ * (declared on {@link FilesAdapter}, not here, since not every provider has a
+ * lifecycle API).
+ */
+export abstract class BaseFilesAdapter<
+  TName extends string = string,
+> implements FilesAdapter<TName> {
+  readonly kind = 'files' as const
+  abstract readonly name: TName
+
+  abstract upload(input: FileUploadInput): Promise<FileHandle<TName>>
+}

package/src/activities/files/index.ts

@@ -0,0 +1,113 @@
+/**
+ * Files Activity
+ *
+ * Dispatch functions for provider Files APIs. Each takes `{ adapter, ... }` and
+ * calls the adapter method directly (mirrors the other activity dispatchers).
+ * `get`/`delete` are optional on the adapter; the dispatchers throw a clear
+ * error when the selected provider has no lifecycle API.
+ */
+
+import type { ContentPartFileSource } from '../../types'
+import type { FileHandle, FileUploadInput, FilesAdapter } from './adapter'
+
+/** The adapter kind this activity handles */
+export const kind = 'files' as const
+
+/**
+ * Upload a file to a provider's Files API and return its handle. The handle
+ * carries the provider name as a literal type, so passing it to another
+ * provider's lifecycle call is a compile error.
+ *
+ * @example
+ * ```ts
+ * const files = openaiFiles()
+ * const handle = await uploadFile({ adapter: files, input: { data, mimeType: 'image/png' } })
+ * ```
+ */
+export async function uploadFile<TName extends string>(options: {
+  adapter: FilesAdapter<TName> & { kind: typeof kind }
+  input: FileUploadInput
+}): Promise<FileHandle<TName>> {
+  return options.adapter.upload(options.input)
+}
+
+/**
+ * Resolve a lifecycle id from either a raw id string or a {@link FileHandle}
+ * (whose `id` — not its `uri`/wire value — is the lifecycle currency).
+ */
+function toLifecycleId(id: string | FileHandle): string {
+  return typeof id === 'string' ? id : id.id
+}
+
+/**
+ * Fetch metadata for a previously uploaded file. Accepts the handle itself
+ * (preferred — the provider-literal type rejects a foreign provider's handle
+ * at compile time) or its raw lifecycle id.
+ *
+ * @throws if the provider's files adapter has no `get` (e.g. fal storage).
+ */
+export async function getFile<TName extends string>(options: {
+  adapter: FilesAdapter<TName> & { kind: typeof kind }
+  // `NoInfer` so `TName` comes from the adapter only. Otherwise a foreign
+  // handle widens it to a union and the call compiles.
+  id: string | FileHandle<NoInfer<TName>>
+}): Promise<FileHandle<TName>> {
+  const { adapter } = options
+  if (!adapter.get) {
+    throw new Error(
+      `${adapter.name}: files adapter does not support get() — this provider ` +
+        `has no file-retrieval API.`,
+    )
+  }
+  return adapter.get(toLifecycleId(options.id))
+}
+
+/**
+ * Delete a previously uploaded file. Accepts the handle itself (preferred —
+ * the provider-literal type rejects a foreign provider's handle at compile
+ * time) or its raw lifecycle id.
+ *
+ * @throws if the provider's files adapter has no `delete` (e.g. fal storage).
+ */
+export async function deleteFile<TName extends string>(options: {
+  adapter: FilesAdapter<TName> & { kind: typeof kind }
+  id: string | FileHandle<NoInfer<TName>>
+}): Promise<void> {
+  const { adapter } = options
+  if (!adapter.delete) {
+    throw new Error(
+      `${adapter.name}: files adapter does not support delete() — this ` +
+        `provider has no file-deletion API.`,
+    )
+  }
+  return adapter.delete(toLifecycleId(options.id))
+}
+
+/**
+ * Build a `{ type: 'file' }` content source from an uploaded
+ * {@link FileHandle}, for use in a chat message (image/audio/document part
+ * `source`).
+ *
+ * The source's `value` is the handle's wire form: the handle URL when the
+ * provider exposes one (Gemini, fal, Grok), otherwise the opaque id (OpenAI,
+ * Anthropic). `provider` records the issuer, so an adapter for a different
+ * provider rejects the source rather than sending a handle it cannot resolve.
+ *
+ * @example
+ * ```ts
+ * const handle = await uploadFile({ adapter: openaiFiles(), input })
+ * messages.push({ role: 'user', content: [
+ *   { type: 'image', source: fileSourceFromHandle(handle) },
+ * ] })
+ * ```
+ */
+export function fileSourceFromHandle<TProvider extends string>(
+  handle: FileHandle<TProvider>,
+): ContentPartFileSource<TProvider> {
+  return {
+    type: 'file',
+    value: handle.uri ?? handle.id,
+    provider: handle.provider,
+    ...(handle.mimeType ? { mimeType: handle.mimeType } : {}),
+  }
+}

package/src/activities/generateImage/adapter.ts

@@ -51,6 +51,13 @@ export interface ImageAdapter<
   readonly kind: 'image'
   /** Adapter name identifier */
   readonly name: string
+  /**
+   * Declares that this adapter can consume `{ type: 'file' }` content
+   * sources (provider Files API references). The activity dispatcher rejects
+   * file sources in preflight for adapters that don't declare this, so
+   * adapters written before the file arm existed fail closed.
+   */
+  readonly supportsFileSources?: boolean
   /** The model this adapter is configured for */
   readonly model: TModel
 
@@ -103,6 +110,7 @@ export abstract class BaseImageAdapter<
 > {
   readonly kind = 'image' as const
   abstract readonly name: string
+  readonly supportsFileSources: boolean = false
   readonly model: TModel
 
   // Type-only property - never assigned at runtime

package/src/activities/generateImage/index.ts

@@ -24,6 +24,7 @@ import {
   raceWithAbort,
 } from '../../utilities/activity-abort'
 import { resolveMediaPrompt } from '../../utilities/media-prompt'
+import { assertPromptFileSourceSupport } from '../../utilities/content-source'
 import type { InternalLogger } from '../../logger/internal-logger'
 import type { DebugOption } from '../../logger/types'
 import type { GenerationMiddleware } from '../middleware/types'
@@ -248,6 +249,9 @@ export function generateImage<
 >(
   options: ImageActivityOptions<TAdapter, TStream>,
 ): ImageActivityResult<TStream> {
+  // Fail closed before middleware start and before `stream: true` emits
+  // RUN_STARTED, so an unsupported file source never opens a run.
+  assertPromptFileSourceSupport(options.adapter, options.prompt)
   if (options.stream) {
     return streamGenerationResult(
       // Only `runId` is taken from the resolved wire identity. `threadId` stays

package/src/activities/generateVideo/adapter.ts

@@ -74,6 +74,13 @@ export interface VideoAdapter<
   readonly kind: 'video'
   /** Adapter name identifier */
   readonly name: string
+  /**
+   * Declares that this adapter can consume `{ type: 'file' }` content
+   * sources (provider Files API references). The activity dispatcher rejects
+   * file sources in preflight for adapters that don't declare this, so
+   * adapters written before the file arm existed fail closed.
+   */
+  readonly supportsFileSources?: boolean
   /** The model this adapter is configured for */
   readonly model: TModel
 
@@ -161,6 +168,7 @@ export abstract class BaseVideoAdapter<
 > {
   readonly kind = 'video' as const
   abstract readonly name: string
+  readonly supportsFileSources: boolean = false
   readonly model: TModel
 
   // Type-only property - never assigned at runtime

package/src/activities/generateVideo/index.ts

@@ -12,6 +12,7 @@
 import { aiEventClient } from '@tanstack/ai-event-client'
 import { toRunErrorPayload } from '../error-payload'
 import { resolveDebugOption } from '../../logger/resolve'
+import { assertPromptFileSourceSupport } from '../../utilities/content-source'
 import {
   applyGenerationResultTransforms,
   createGenerationContext,
@@ -452,6 +453,9 @@ async function runCreateVideoJob<
     timeout,
     abortSignal: callerAbortSignal,
   } = options
+  // Fail closed on `{ type: 'file' }` sources for adapters that haven't
+  // declared support (see assertPromptFileSourceSupport).
+  assertPromptFileSourceSupport(adapter, prompt)
   const model = adapter.model
   const requestId = createId('video')
   const startTime = Date.now()
@@ -580,6 +584,9 @@ async function* runStreamingVideoGeneration<
     timeout,
     abortSignal: callerAbortSignal,
   } = options
+  // Fail closed on `{ type: 'file' }` sources for adapters that haven't
+  // declared support (see assertPromptFileSourceSupport).
+  assertPromptFileSourceSupport(adapter, prompt)
   const model = adapter.model
   const runId = options.runId ?? createId('run')
   const requestId = createId('video')

package/src/activities/generateWorld/adapter.ts

@@ -44,10 +44,12 @@ export interface WorldAdapter<
   }
 
   /**
-   * Open a world session from a prompt.
+   * Create a world from a prompt.
    *
-   * Server adapters typically mint a short-lived token and return it with the
+   * Live session adapters mint a short-lived token and return it with the
    * prompt so a browser can connect, set the prompt, and start streaming.
+   * Job adapters start generation and return a world URL (or an operation
+   * id while the job is still running).
    */
   createWorld: (
     options: WorldGenerationOptions<TProviderOptions>,

package/src/activities/generateWorld/index.ts

@@ -1,9 +1,9 @@
 /**
  * World Activity (Experimental)
  *
- * Mints a session token for a live, prompt-steerable world. Unlike
- * generateVideo (a job that finishes with a URL), the browser then connects
- * with the token, sets the prompt, and streams until pause/reset/close.
+ * Live adapters mint a session token for a prompt-steerable world. Job
+ * adapters start generation and return a viewer URL, or an operation id
+ * while the job is still running.
  *
  * @experimental World generation is an experimental feature and may change.
  */
@@ -76,7 +76,7 @@ export interface WorldActivityOptions<
   /** Provider-specific options for world generation */
   modelOptions?: WorldProviderOptions<TAdapter>
   /**
-   * Whether to wrap the token result as StreamChunks for SSE transport.
+   * Whether to wrap the result as StreamChunks for SSE transport.
    * This is not the live video. When false or omitted, returns
    * Promise<WorldGenerationResult>.
    *
@@ -100,7 +100,7 @@ export interface WorldActivityOptions<
   /** Stable run id for correlating this run when persisted. */
   runId?: string
   /**
-   * Maximum duration of the token mint in milliseconds.
+   * Maximum wait for the mint or job poll, in milliseconds.
    * No SDK-wide default. Composed with {@link abortSignal}; the first abort wins.
    */
   timeout?: number
@@ -135,7 +135,8 @@ function createId(prefix: string): string {
 // ===========================
 
 /**
- * World generation activity - opens a live, prompt-steerable world session.
+ * World generation activity. Live adapters mint a session token. Job
+ * adapters return a viewer URL or an in-progress operation id.
  *
  * @example Mint a session token on the server
  * ```ts

package/src/activities/index.ts

@@ -27,6 +27,7 @@ import type { AnyRerankAdapter } from './rerank/adapter'
 import type { AnyEvaluateAdapter } from './evaluate/adapter'
 import type { AnyWorldAdapter } from './generateWorld/adapter'
 import type { AnyLiveVideoAdapter } from './generateLiveVideo/adapter'
+import type { AnyFilesAdapter } from './files/adapter'
 
 // ===========================
 // Chat Activity
@@ -330,11 +331,32 @@ export {
   type AnyLiveVideoAdapter,
 } from './generateLiveVideo/adapter'
 
+// ===========================
+// Files Activity
+// ===========================
+
+export {
+  kind as filesKind,
+  uploadFile,
+  getFile,
+  deleteFile,
+  fileSourceFromHandle,
+} from './files/index'
+
+export {
+  BaseFilesAdapter,
+  normalizeFileUploadInput,
+  type FilesAdapter,
+  type AnyFilesAdapter,
+  type FileHandle,
+  type FileUploadInput,
+} from './files/adapter'
+
 // ===========================
 // Adapter Union Types
 // ===========================
 
-/** Union of all adapter types that can be passed to chat() */
+/** Union of all adapter types across every activity kind */
 export type AIAdapter =
   | AnyTextAdapter
   | AnySummarizeAdapter
@@ -349,6 +371,7 @@ export type AIAdapter =
   | AnyEvaluateAdapter
   | AnyWorldAdapter
   | AnyLiveVideoAdapter
+  | AnyFilesAdapter
 
 /** Union type of all adapter kinds */
 export type AdapterKind =
@@ -365,3 +388,4 @@ export type AdapterKind =
   | 'evaluate'
   | 'world'
   | 'liveVideo'
+  | 'files'

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

@@ -65,6 +65,8 @@ function throwRunError(
  * `SummarizationOptions<TProviderOptions>` on the wrapper itself.
  */
 export interface ChatStreamCapable {
+  /** Native token-limit option for adapters whose provider name is user-defined. */
+  readonly maxTokensKey?: string
   chatStream: (options: TextOptions<any>) => AsyncIterable<AdapterYieldChunk>
 }
 
@@ -151,8 +153,8 @@ function applyDefaultTemperature(
 
 /**
  * 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
+ * wrapped text adapter's explicit key, falling back to this wrapper's `name`,
+ * 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
@@ -172,10 +174,11 @@ function applyMaxLength(
   adapterName: string,
   maxLength: number,
   modelOptions: Record<string, unknown>,
+  maxTokensKey?: string,
 ): Record<string, unknown> {
   const merged: Record<string, unknown> = { ...modelOptions }
 
-  if (adapterName === 'ollama') {
+  if (adapterName === 'ollama' && maxTokensKey === undefined) {
     // 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(
@@ -195,12 +198,12 @@ function applyMaxLength(
     return merged
   }
 
-  const key = MAX_TOKENS_KEY_BY_ADAPTER[adapterName]
+  const key = maxTokensKey ?? MAX_TOKENS_KEY_BY_ADAPTER[adapterName]
   if (key === undefined) return merged
 
-  const callerSetLimit = KNOWN_MAX_TOKENS_KEYS.some(
-    (k) => typeof merged[k] === 'number',
-  )
+  const callerSetLimit =
+    typeof merged[key] === 'number' ||
+    KNOWN_MAX_TOKENS_KEYS.some((k) => typeof merged[k] === 'number')
   if (callerSetLimit) return merged
 
   merged[key] = maxLength
@@ -372,17 +375,24 @@ export class ChatStreamSummarizeAdapter<
     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.
+    // Prefer the wrapped adapter's explicit key, then this wrapper's name,
+    // never overriding a caller-supplied token limit.
     if (options.maxLength !== undefined) {
-      if (!isKnownMaxTokensAdapter(this.name)) {
+      if (
+        this.textAdapter.maxTokensKey === undefined &&
+        !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)
+      working = applyMaxLength(
+        this.name,
+        options.maxLength,
+        working,
+        this.textAdapter.maxTokensKey,
+      )
     }
     const modelOptions = working as TProviderOptions