@tanstack/ai 0.39.0 → 0.39.1

package/dist/esm/utilities/provider-executed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-executed.js","sources":["../../../src/utilities/provider-executed.ts"],"sourcesContent":["import type { ProviderExecutedToolMetadata } from '../types'\n\n/**\n * Narrow a tool call's opaque `metadata` to the provider-executed convention.\n * Returns the typed metadata when the call is provider-executed, else `null`.\n *\n * @see ProviderExecutedToolMetadata\n */\nexport function getProviderExecutedMetadata(\n  toolCall: { metadata?: unknown } | null | undefined,\n): ProviderExecutedToolMetadata | null {\n  const metadata = toolCall?.metadata\n  if (\n    typeof metadata === 'object' &&\n    metadata !== null &&\n    (metadata as ProviderExecutedToolMetadata).providerExecuted === true\n  ) {\n    return metadata as ProviderExecutedToolMetadata\n  }\n  return null\n}\n\n/**\n * True when a tool call was executed by the provider (e.g. Anthropic\n * `web_search` / `web_fetch` server tools) rather than the agent loop. Such\n * calls must not be routed to client-side execution and are already \"complete\".\n */\nexport function isProviderExecutedToolCall(\n  toolCall: { metadata?: unknown } | null | undefined,\n): boolean {\n  return getProviderExecutedMetadata(toolCall) !== null\n}\n"],"names":[],"mappings":"AAQO,SAAS,4BACd,UACqC;AACrC,QAAM,WAAW,UAAU;AAC3B,MACE,OAAO,aAAa,YACpB,aAAa,QACZ,SAA0C,qBAAqB,MAChE;AACA,WAAO;AAAA,EACT;AACA,SAAO;AACT;AAOO,SAAS,2BACd,UACS;AACT,SAAO,4BAA4B,QAAQ,MAAM;AACnD;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai",
-  "version": "0.39.0",
+  "version": "0.39.1",
   "description": "Type-safe TypeScript AI SDK for streaming chat, tool calling, agents, structured outputs, and multimodal generation.",
   "author": "Tanner Linsley",
   "license": "MIT",

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

@@ -21,17 +21,23 @@ import { anthropicText } from '@tanstack/ai-anthropic'
 
 ## Key Chat Models
 
-| Model               | Context Window | Max Output | Notes                           |
-| ------------------- | -------------- | ---------- | ------------------------------- |
-| `claude-opus-4-6`   | 200K           | 128K       | Most capable, adaptive thinking |
-| `claude-sonnet-4-6` | 1M             | 64K        | Best balance, adaptive thinking |
-| `claude-sonnet-4-5` | 200K           | 64K        | Previous gen balanced           |
-| `claude-opus-4-5`   | 200K           | 32K        | Previous gen most capable       |
-| `claude-haiku-4-5`  | 200K           | 64K        | Fast and affordable             |
-| `claude-sonnet-4`   | 200K           | 64K        | Older balanced model            |
-| `claude-opus-4`     | 200K           | 32K        | Older most capable              |
-
-Note: Model IDs use the format `claude-opus-4-6`, `claude-sonnet-4-6`, etc.
+| Model               | Context Window | Max Output | Notes                                       |
+| ------------------- | -------------- | ---------- | ------------------------------------------- |
+| `claude-fable-5`    | 1M             | 128K       | Most capable; thinking always on (adaptive) |
+| `claude-sonnet-5`   | 1M             | 128K       | Best balance; adaptive thinking by default  |
+| `claude-opus-4-8`   | 1M             | 128K       | Opus tier; adaptive thinking, no sampling   |
+| `claude-opus-4-7`   | 1M             | 128K       | Older Opus; adaptive thinking, no sampling  |
+| `claude-opus-4-6`   | 200K           | 128K       | Older Opus, adaptive + budget thinking      |
+| `claude-sonnet-4-6` | 1M             | 64K        | Previous gen balanced, adaptive + budget    |
+| `claude-sonnet-4-5` | 200K           | 64K        | Previous gen balanced                       |
+| `claude-opus-4-5`   | 200K           | 32K        | Previous gen most capable                   |
+| `claude-opus-4-1`   | 200K           | 64K        | Deprecated (retires 2026-08-05)             |
+| `claude-haiku-4-5`  | 200K           | 64K        | Fast and affordable                         |
+
+Note: Model IDs use the format `claude-sonnet-5`, `claude-opus-4-8`, etc.
+Retired models (Claude 3.x, Sonnet 3.7, Opus 4 / Sonnet 4) and the `-fast`
+variant ids were removed — every registered id resolves against the
+first-party Anthropic API.
 
 ## Provider-Specific modelOptions
 
@@ -90,11 +96,36 @@ chat({
 ANTHROPIC_API_KEY
 ```
 
+## Adaptive-era modelOptions (Sonnet 5, Fable 5, Opus 4.7/4.8)
+
+The per-model types restrict `modelOptions` on the newest models:
+
+```typescript
+chat({
+  adapter: anthropicText('claude-sonnet-5'), // or 'claude-fable-5', 'claude-opus-4-8'
+  messages,
+  modelOptions: {
+    // Adaptive thinking only — budget_tokens is rejected (400).
+    // On claude-fable-5, { type: 'disabled' } is also rejected;
+    // elsewhere it opts out of thinking.
+    thinking: { type: 'adaptive', display: 'summarized' },
+    // Effort lives under output_config; 'xhigh' is available on
+    // Opus 4.7+, Sonnet 5, and Fable 5.
+    output_config: { effort: 'xhigh' },
+    max_tokens: 64_000,
+    // NO temperature / top_p / top_k — the API rejects them on these models
+  },
+})
+```
+
 ## Gotchas
 
 - `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.
+- `claude-sonnet-5`, `claude-fable-5`, `claude-opus-4-8`, and
+  `claude-opus-4-7` do NOT accept `temperature`, `top_p`, `top_k`, or
+  `thinking: { type: 'enabled', budget_tokens }` — adaptive thinking +
+  `output_config.effort` replace them (typed per model).
 - System prompts support prompt caching via `cache_control` on `TextBlockParam[]`.
 - All Claude models accept `text`, `image`, and `document` (PDF) input.

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

@@ -151,7 +151,7 @@ function ImageGenerator() {
 
 Supported adapters: `openaiImage` (dall-e-2, dall-e-3, gpt-image-1,
 gpt-image-1-mini, gpt-image-2) and `geminiImage` (gemini-3.1-flash-image-preview,
-imagen-4.0-generate-001, etc.).
+gemini-3.1-flash-lite-image, imagen-4.0-generate-001, etc.).
 
 ```typescript
 import { generateImage } from '@tanstack/ai'

package/src/activities/chat/index.ts

@@ -12,6 +12,7 @@ import { streamToText } from '../../stream-to-response.js'
 import { resolveDebugOption } from '../../logger/resolve'
 import { EventType } from '../../types'
 import { normalizeToolResult } from '../../utilities/tool-result'
+import { isProviderExecutedToolCall } from '../../utilities/provider-executed'
 import { LazyToolManager } from './tools/lazy-tool-manager'
 import {
   MiddlewareAbortError,
@@ -1884,6 +1885,13 @@ class TextEngine<
     for (const message of this.messages) {
       if (message.role === 'assistant' && message.toolCalls) {
         for (const toolCall of message.toolCalls) {
+          // Provider-executed tool calls (e.g. Anthropic `web_search`) were
+          // already run by the provider; they carry no client result, so they
+          // would otherwise look "pending" forever and the loop would try (and
+          // fail) to execute them client-side. Skip them.
+          if (isProviderExecutedToolCall(toolCall)) {
+            continue
+          }
           if (!completedToolIds.has(toolCall.id)) {
             pending.push(toolCall)
           }

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

@@ -23,6 +23,7 @@ import {
   uiMessageToModelMessages,
 } from '../messages.js'
 import { normalizeToolResult } from '../../../utilities/tool-result'
+import { isProviderExecutedToolCall } from '../../../utilities/provider-executed'
 import { defaultJSONParser } from './json-parser'
 import {
   appendStructuredOutputDelta,
@@ -403,12 +404,15 @@ export class StreamProcessor {
     // 1. It was approved/denied (approval-responded state)
     // 2. It has an output field set (client tool completed via addToolResult)
     // 3. It has a corresponding tool-result part (server tool completed)
+    // 4. It is provider-executed (e.g. Anthropic web_search) — already run by
+    //    the provider, so there is no client result to wait for.
     return toolParts.every(
       (part) =>
         part.state === 'complete' ||
         part.state === 'approval-responded' ||
         (part.output !== undefined && !part.approval) ||
-        toolResultIds.has(part.id),
+        toolResultIds.has(part.id) ||
+        isProviderExecutedToolCall(part),
     )
   }
 
@@ -881,10 +885,140 @@ export class StreamProcessor {
     // them directly to UIMessage[] is unsafe and causes "Cannot read properties
     // of undefined (reading 'find')" when code later reads message.parts (e.g.
     // the onToolCallStateChange devtools handler).
-    this.messages = chunk.messages.map(aguiSnapshotMessageToUIMessage)
+    //
+    // The AG-UI `MESSAGES_SNAPSHOT` wire shape cannot reconstruct client-side
+    // tool-call metadata a server may omit: a `role: 'tool'` message only carries
+    // `toolCallId` + `content`, and an assistant message in the snapshot may
+    // drop `toolCalls` the client already observed via `TOOL_CALL_*` events.
+    // Without the matching `tool-call` part, later `addToolResult(toolCallId)`
+    // calls cannot locate the call and warn + no-op (see #859). To keep the
+    // UI representation consistent with the streaming fan-out and preserve the
+    // unreconstructable metadata, reconcile the normalized snapshot against
+    // the pre-snapshot state; see `reconcileSnapshotToolCalls`.
+    const prevMessages = this.messages
+    const normalized = chunk.messages.map(aguiSnapshotMessageToUIMessage)
+    this.messages = this.reconcileSnapshotToolCalls(normalized, prevMessages)
     this.emitMessagesChange()
   }
 
+  /**
+   * Reconcile a freshly normalized snapshot with the pre-snapshot message
+   * state so unreconstructable tool-call metadata is preserved.
+   *
+   * Post-pass (a): anchor `tool-result`-only assistant messages (the shape
+   * `aguiSnapshotMessageToUIMessage` emits for AG-UI `role: 'tool'` wire
+   * messages) into the message containing the matching `tool-call` part, or —
+   * when the snapshot supplies no such part — the nearest earlier anchorable
+   * assistant message, matching the in-stream fan-out shape
+   * `assistant: [text, tool-call, tool-result, ...]`. Detached messages with
+   * no earlier anchorable assistant are kept verbatim.
+   *
+   * Post-pass (b): when a `tool-result` part references a `toolCallId` whose
+   * `tool-call` part is absent from the snapshot, carry the `tool-call` part
+   * forward from the pre-snapshot state (state and output untouched) so a
+   * subsequent `addToolResult(toolCallId)` can still locate the call.
+   */
+  private reconcileSnapshotToolCalls(
+    snapshot: Array<UIMessage>,
+    prevMessages: Array<UIMessage>,
+  ): Array<UIMessage> {
+    // Index tool-call parts observed before the snapshot by id so we can
+    // restore metadata the snapshot cannot re-emit. Duplicate ids resolve
+    // last-write-wins: the same tool call can appear in multiple messages
+    // across reconnects, and the most recent part carries the freshest state.
+    const prevToolCalls = new Map<string, ToolCallPart>()
+    for (const msg of prevMessages) {
+      for (const part of msg.parts) {
+        if (part.type === 'tool-call') {
+          prevToolCalls.set(part.id, part)
+        }
+      }
+    }
+    // Index tool-call parts already present in the snapshot so (b) only fills
+    // genuine gaps rather than duplicating a tool-call the snapshot supplies.
+    const snapshotToolCallIds = new Set<string>()
+    for (const msg of snapshot) {
+      for (const part of msg.parts) {
+        if (part.type === 'tool-call') {
+          snapshotToolCallIds.add(part.id)
+        }
+      }
+    }
+
+    const reconciled: Array<UIMessage> = []
+    for (const msg of snapshot) {
+      const toolResultPart =
+        msg.role === 'assistant' && msg.parts.length === 1
+          ? msg.parts.find((p): p is ToolResultPart => p.type === 'tool-result')
+          : undefined
+
+      if (!toolResultPart) {
+        reconciled.push(msg)
+        continue
+      }
+
+      // Prefer the message that actually contains the matching tool-call
+      // part. AG-UI `reasoning`/`activity` messages also normalize to
+      // `role: 'assistant'`, so anchoring into the nearest assistant alone
+      // could separate a result from its call (and a later
+      // `addToolResult(toolCallId)` would then append a duplicate result
+      // next to the call).
+      const target =
+        reconciled.findLast((m) =>
+          m.parts.some(
+            (p) => p.type === 'tool-call' && p.id === toolResultPart.toolCallId,
+          ),
+        ) ??
+        reconciled.findLast(
+          (m) =>
+            m.role === 'assistant' &&
+            !(m.parts.length === 1 && m.parts[0]?.type === 'tool-result'),
+        )
+
+      if (!target) {
+        // No assistant to anchor into — keep the detached message intact.
+        if (!snapshotToolCallIds.has(toolResultPart.toolCallId)) {
+          console.warn(
+            `[StreamProcessor] MESSAGES_SNAPSHOT contains a tool-result for "${toolResultPart.toolCallId}" but no matching tool-call exists in the snapshot, and there is no assistant message to anchor into; addToolResult("${toolResultPart.toolCallId}") will not be able to locate this call`,
+          )
+        }
+        reconciled.push(msg)
+        continue
+      }
+
+      const parts = [...target.parts]
+      // (b) Fill in a missing tool-call part from the pre-snapshot state when
+      // the snapshot references its id via a tool-result but supplies no
+      // tool-call metadata of its own.
+      if (
+        !snapshotToolCallIds.has(toolResultPart.toolCallId) &&
+        !parts.some(
+          (p) => p.type === 'tool-call' && p.id === toolResultPart.toolCallId,
+        )
+      ) {
+        const prev = prevToolCalls.get(toolResultPart.toolCallId)
+        if (prev) {
+          // Insert the carried-over tool-call before its tool-result (pushed
+          // below) so call→result ordering matches the streaming fan-out.
+          parts.push({ ...prev })
+          snapshotToolCallIds.add(prev.id)
+        } else {
+          console.warn(
+            `[StreamProcessor] MESSAGES_SNAPSHOT contains a tool-result for "${toolResultPart.toolCallId}" but no matching tool-call exists in the snapshot or the pre-snapshot state; addToolResult("${toolResultPart.toolCallId}") will not be able to locate this call`,
+          )
+        }
+      }
+      parts.push(toolResultPart)
+      // Replace rather than push into `target.parts`: a snapshot message that
+      // arrived already carrying `parts` (TanStack server echoing UIMessages)
+      // shares its array with the incoming chunk, and mutating it in place
+      // would corrupt the caller's event object.
+      target.parts = parts
+    }
+
+    return reconciled
+  }
+
   /**
    * Handle TEXT_MESSAGE_CONTENT event.
    *
@@ -1781,8 +1915,12 @@ export class StreamProcessor {
    * downgrading a failed call back to 'input-complete'.
    */
   private isToolCallPartErrored(toolCallId: string): boolean {
+    // `initialMessages` may be ModelMessage-shaped (no `parts`) — e.g. the
+    // common pattern of seeding a processor with the same messages passed to
+    // `chat()`. Guard the access so iterating them never throws.
     return this.messages.some((msg) =>
-      msg.parts.some(
+      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- `parts` is typed as required, but seeded ModelMessage-shaped messages can lack it at runtime.
+      msg.parts?.some(
         (part) =>
           part.type === 'tool-call' &&
           part.id === toolCallId &&

package/src/index.ts

@@ -256,6 +256,11 @@ export {
   normalizeToolResult,
 } from './utilities/tool-result'
 
+export {
+  getProviderExecutedMetadata,
+  isProviderExecutedToolCall,
+} from './utilities/provider-executed'
+
 // Adapter extension utilities
 export { createModel, extendAdapter } from './extend-adapter'
 export type { ExtendedModelDef, ModelCapabilities } from './extend-adapter'

package/src/types.ts

@@ -160,6 +160,26 @@ export interface ToolCall<TMetadata = unknown> {
   metadata?: TMetadata
 }
 
+/**
+ * Convention for tool-call `metadata` that marks a call as **provider-executed**
+ * — run by the provider's own infrastructure (e.g. Anthropic `web_search` /
+ * `web_fetch` server tools) rather than by the agent loop. Adapters set
+ * `providerExecuted: true` so that:
+ *
+ * 1. The agent loop never tries to execute the call client-side (see
+ *    {@link isProviderExecutedToolCall} usage in the chat engine), and
+ * 2. The adapter can stash the raw provider result alongside it so the call —
+ *    and its evidence — round-trips into the next turn's request.
+ *
+ * Provider-specific payloads live under a namespaced key (e.g. `anthropic`),
+ * keeping this convention opaque to the framework core. The index signature
+ * preserves those per-adapter fields.
+ */
+export interface ProviderExecutedToolMetadata {
+  providerExecuted?: boolean
+  [key: string]: unknown
+}
+
 // ============================================================================
 // Multimodal Content Types
 // ============================================================================
@@ -362,7 +382,9 @@ export interface ToolCallPart<TMetadata = unknown> {
   /** Tool execution output (for client tools or after approval) */
   output?: any
   /** Provider-specific metadata that round-trips with the tool call.
-   * Typed per-adapter via `TToolCallMetadata`. */
+   * Typed per-adapter via `TToolCallMetadata`. May follow the
+   * {@link ProviderExecutedToolMetadata} convention to mark provider-executed
+   * server tools (e.g. Anthropic `web_search`). */
   metadata?: TMetadata
 }
 

package/src/utilities/provider-executed.ts

@@ -0,0 +1,32 @@
+import type { ProviderExecutedToolMetadata } from '../types'
+
+/**
+ * Narrow a tool call's opaque `metadata` to the provider-executed convention.
+ * Returns the typed metadata when the call is provider-executed, else `null`.
+ *
+ * @see ProviderExecutedToolMetadata
+ */
+export function getProviderExecutedMetadata(
+  toolCall: { metadata?: unknown } | null | undefined,
+): ProviderExecutedToolMetadata | null {
+  const metadata = toolCall?.metadata
+  if (
+    typeof metadata === 'object' &&
+    metadata !== null &&
+    (metadata as ProviderExecutedToolMetadata).providerExecuted === true
+  ) {
+    return metadata as ProviderExecutedToolMetadata
+  }
+  return null
+}
+
+/**
+ * True when a tool call was executed by the provider (e.g. Anthropic
+ * `web_search` / `web_fetch` server tools) rather than the agent loop. Such
+ * calls must not be routed to client-side execution and are already "complete".
+ */
+export function isProviderExecutedToolCall(
+  toolCall: { metadata?: unknown } | null | undefined,
+): boolean {
+  return getProviderExecutedMetadata(toolCall) !== null
+}