@tanstack/ai 0.52.2 → 0.53.0

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

@@ -73,18 +73,19 @@ top-level options on `chat()`. See the per-provider table in
 Each provider has a dedicated package with tree-shakeable adapter factories.
 The text adapter is the primary one for chat/completions:
 
-| Provider          | Package                          | Factory                                     | Env Var                                           |
-| ----------------- | -------------------------------- | ------------------------------------------- | ------------------------------------------------- |
-| OpenAI            | `@tanstack/ai-openai`            | `openaiText`                                | `OPENAI_API_KEY`                                  |
-| Anthropic         | `@tanstack/ai-anthropic`         | `anthropicText`                             | `ANTHROPIC_API_KEY`                               |
-| Gemini            | `@tanstack/ai-gemini`            | `geminiText`                                | `GOOGLE_API_KEY` or `GEMINI_API_KEY`              |
-| Grok (xAI)        | `@tanstack/ai-grok`              | `grokText`                                  | `XAI_API_KEY`                                     |
-| Groq              | `@tanstack/ai-groq`              | `groqText`                                  | `GROQ_API_KEY`                                    |
-| OpenRouter        | `@tanstack/ai-openrouter`        | `openRouterText`                            | `OPENROUTER_API_KEY`                              |
-| Ollama            | `@tanstack/ai-ollama`            | `ollamaText`                                | `OLLAMA_HOST` (default: `http://localhost:11434`) |
-| Bedrock           | `@tanstack/ai-bedrock`           | `bedrockText`                               | `BEDROCK_API_KEY` or `AWS_BEARER_TOKEN_BEDROCK`   |
-| BytePlus          | `@tanstack/ai-byteplus`          | `byteplusText`                              | `ARK_API_KEY` (falls back to `BYTEPLUS_API_KEY`)  |
-| OpenAI-compatible | `@tanstack/ai-openai/compatible` | `openaiCompatible` / `openaiCompatibleText` | provider-specific (passed via `apiKey`)           |
+| Provider          | Package                          | Factory                                     | Env Var                                                                                |
+| ----------------- | -------------------------------- | ------------------------------------------- | -------------------------------------------------------------------------------------- |
+| OpenAI            | `@tanstack/ai-openai`            | `openaiText`                                | `OPENAI_API_KEY`                                                                       |
+| Anthropic         | `@tanstack/ai-anthropic`         | `anthropicText`                             | `ANTHROPIC_API_KEY`                                                                    |
+| Gemini            | `@tanstack/ai-gemini`            | `geminiText`                                | `GOOGLE_API_KEY` or `GEMINI_API_KEY`                                                   |
+| Grok (xAI)        | `@tanstack/ai-grok`              | `grokText`                                  | `XAI_API_KEY`                                                                          |
+| Groq              | `@tanstack/ai-groq`              | `groqText`                                  | `GROQ_API_KEY`                                                                         |
+| OpenRouter        | `@tanstack/ai-openrouter`        | `openRouterText`                            | `OPENROUTER_API_KEY`                                                                   |
+| Ollama            | `@tanstack/ai-ollama`            | `ollamaText`                                | `OLLAMA_HOST` (default: `http://localhost:11434`)                                      |
+| Bedrock           | `@tanstack/ai-bedrock`           | `bedrockText`                               | `BEDROCK_API_KEY` or `AWS_BEARER_TOKEN_BEDROCK`                                        |
+| BytePlus          | `@tanstack/ai-byteplus`          | `byteplusText`                              | `ARK_API_KEY` (falls back to `BYTEPLUS_API_KEY`)                                       |
+| OpenAI-compatible | `@tanstack/ai-openai/compatible` | `openaiCompatible` / `openaiCompatibleText` | provider-specific (passed via `apiKey`)                                                |
+| Cloudflare        | `@tanstack/ai-cloudflare`        | `cloudflareText`                            | `CLOUDFLARE_ACCOUNT_ID` + `CLOUDFLARE_API_TOKEN`, or `{ binding: env.AI }` in a Worker |
 
 > **BytePlus uses two keys.** `byteplusText` / `byteplusVideo` /
 > `byteplusImage` read `ARK_API_KEY` (ModelArk, `Authorization: Bearer`), but
@@ -417,6 +418,25 @@ compatible providers speak.
 > Verify the provider's current `baseURL` and model ids against its live docs —
 > they drift. See `docs/adapters/openai-compatible.md` for the full provider table.
 
+## Behind a proxy or gateway
+
+Every adapter's client config accepts `baseURL` and `defaultHeaders`. Use these
+two names to route any adapter through Cloudflare AI Gateway, Vercel AI Gateway,
+or a corporate proxy. The adapter maps them onto the vendor SDK's own option
+names (Gemini `httpOptions`, Mistral `serverURL`, Ollama `host`, Cohere and
+ElevenLabs `baseUrl`/`headers`). The vendor names still work; when both are
+set, `baseURL` and `defaultHeaders` win.
+
+```typescript
+const gateway = {
+  baseURL: 'https://gateway.example.com/google-ai-studio',
+  defaultHeaders: {
+    'cf-aig-authorization': `Bearer ${process.env.GATEWAY_TOKEN}`,
+  },
+}
+createGeminiChat('gemini-3.8-flash', apiKey, { ...gateway })
+```
+
 ## Common Mistakes
 
 ### a. HIGH: Confusing legacy monolithic with tree-shakeable adapter

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

@@ -95,3 +95,8 @@ OPENAI_API_KEY
   `effort: 'low'` or higher to enable reasoning.
 - `o3-pro` only supports `high` reasoning effort.
 - `conversation` and `previous_response_id` cannot be used together.
+- Reasoning models (`o*`, `gpt-5*` except `*-chat-latest`, `codex-mini-latest`)
+  pair each `function_call` with a `reasoning` item. The adapter requests
+  `include: ['reasoning.encrypted_content']` for those models and replays that
+  item on the next turn. Pre-5 chat models are left unchanged. If you persist
+  history by hand, keep `thinking[].signature`.

package/skills/ai-core/structured-outputs/SKILL.md

@@ -192,6 +192,7 @@ The terminal event is a `CUSTOM` chunk: `{ type: 'CUSTOM', name: 'structured-out
 | `@tanstack/ai-groq`                                   | Legacy `structuredOutputStream` only (no tools — Groq's API rejects schema + tools + stream)                                                          |
 | `@tanstack/ai-bedrock`                                | Separate native `structuredOutputStream` finalization through Converse or an OpenAI-compatible API                                                    |
 | `@tanstack/ai-byteplus`                               | Native combined mode on supported models; unsupported models emit `RUN_ERROR`                                                                         |
+| `@tanstack/ai-cloudflare`                             | Native `structuredOutputStream` without tools; with tools, a separate finalization call (Workers AI models answer the tool turn in prose)             |
 | `@tanstack/ai-claude-code`                            | Combined + event source — `--json-schema` on the same harness turn. Read `useChat().final`. See Pattern 6.                                            |
 | `@tanstack/ai-codex`                                  | Combined + event source — `--output-schema` on the same harness turn. Read `useChat().final`. See Pattern 6.                                          |
 | `@tanstack/ai-opencode`                               | Combined + event source — prompt-and-parse. Read `useChat().final`. See Pattern 6.                                                                    |

package/src/activities/chat/index.ts

@@ -1870,7 +1870,7 @@ class TextEngine<
   }
 
   private finalizeCurrentThinkingStep(): void {
-    if (this.currentThinkingContent) {
+    if (this.currentThinkingContent || this.currentThinkingSignature) {
       this.accumulatedThinking.push({
         content: this.currentThinkingContent,
         ...(this.currentThinkingSignature && {

package/src/activities/chat/messages.ts

@@ -173,10 +173,10 @@ export function convertMessagesToModelMessages(
 
     if (role === 'reasoning') {
       const content = (msg as { content?: string }).content
-      if (content) {
-        const signature = encryptedValueFrom(msg)
+      const signature = encryptedValueFrom(msg)
+      if (content || signature !== undefined) {
         pendingThinking.push({
-          content,
+          content: typeof content === 'string' ? content : '',
           ...(signature !== undefined ? { signature } : {}),
         })
       }
@@ -593,7 +593,7 @@ function buildAssistantMessages(uiMessage: UIMessage): Array<ModelMessage> {
         break
 
       case 'thinking':
-        if (part.content) {
+        if (part.content || part.signature) {
           // Provider-executed tools have no tool-result part, so thinking
           // after them has to start the next segment or it replays first.
           if (current.toolCalls.some(isProviderExecutedToolCall)) {
@@ -712,7 +712,7 @@ export function modelMessageToUIMessage(
 
   if (modelMessage.role === 'assistant' && modelMessage.thinking?.length) {
     for (const thinking of modelMessage.thinking) {
-      if (!thinking.content) continue
+      if (!thinking.content && !thinking.signature) continue
       parts.push({
         type: 'thinking',
         content: thinking.content,
@@ -917,18 +917,20 @@ export function aguiSnapshotMessageToUIMessage(
       })
     case 'reasoning': {
       const signature = encryptedValueFrom(message)
+      const content = typeof message.content === 'string' ? message.content : ''
       return applySnapshotMetadata(message, {
         id,
         role: 'assistant',
-        parts: message.content
-          ? [
-              {
-                type: 'thinking' as const,
-                content: message.content,
-                ...(signature !== undefined ? { signature } : {}),
-              },
-            ]
-          : [],
+        parts:
+          content || signature !== undefined
+            ? [
+                {
+                  type: 'thinking' as const,
+                  content,
+                  ...(signature !== undefined ? { signature } : {}),
+                },
+              ]
+            : [],
       })
     }
     case 'activity':

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

@@ -95,6 +95,8 @@ const MAX_TOKENS_KEY_BY_ADAPTER: Record<string, string> = {
   // LLM Gateway exposes an OpenAI-compatible Chat Completions surface whose
   // only output cap is `max_tokens` — it does not read `max_completion_tokens`.
   llmgateway: 'max_tokens',
+  // Workers AI's OpenAI-compatible Chat Completions surface reads `max_tokens`.
+  cloudflare: 'max_tokens',
 }
 
 /**

package/src/byok/define-provider.ts

@@ -12,6 +12,11 @@ export interface ByokProvider<TId extends string = string> {
    * values here. This object is imported on the client.
    */
   readonly env?: ReadonlyArray<string>
+  /**
+   * Other descriptors this credential needs. A send for this provider also
+   * carries their headers and prompts for each one that is missing.
+   */
+  readonly with?: ReadonlyArray<ByokProvider>
 }
 
 /**
@@ -22,6 +27,7 @@ export type ByokProviderInit<TId extends string> = {
   readonly id: undefined extends TId ? never : TId
   readonly label: string
   readonly env?: string | ReadonlyArray<string>
+  readonly with?: ReadonlyArray<ByokProvider>
 }
 
 function normalizeEnv(
@@ -42,5 +48,6 @@ export function defineByokProvider<const TId extends string>(
     id: provider.id,
     label: provider.label,
     ...(env ? { env } : {}),
+    ...(provider.with ? { with: provider.with } : {}),
   }
 }

package/src/byok/get-key.ts

@@ -25,3 +25,21 @@ export function getByokKey(
   }
   return null
 }
+
+/**
+ * Read several keys at once, one per name. Same rules as {@link getByokKey}
+ * for each entry. Use it for a credential made of more than one value.
+ */
+export function getByokKeys<
+  const TProviders extends Record<string, ProviderId | ByokProvider>,
+>(
+  request: Request,
+  providers: TProviders,
+): { [K in keyof TProviders]: string | null } {
+  return Object.fromEntries(
+    Object.entries(providers).map(([name, provider]) => [
+      name,
+      getByokKey(request, provider),
+    ]),
+  ) as { [K in keyof TProviders]: string | null }
+}

package/src/byok/server.ts

@@ -1,3 +1,3 @@
-export { getByokKey } from './get-key'
+export { getByokKey, getByokKeys } from './get-key'
 export { byokMissing, isByokMissingBody } from './missing'
 export type { ByokMissingBody } from './missing'