feat: Provider tools on /tools subpath with per-model type gating

.changeset/provider-tools-ai-anthropic.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/ai-anthropic': minor
+---
+
+Expose provider-tool factories (`webSearchTool`, `codeExecutionTool`, `computerUseTool`, `bashTool`, `textEditorTool`, `webFetchTool`, `memoryTool`, `customTool`) on a new `/tools` subpath. Each factory now returns a branded type (e.g. `AnthropicWebSearchTool`) that is gated against the selected model's `supports.tools` list. Existing factory signatures and runtime behavior are unchanged; old config-type aliases (`WebSearchTool`, `BashTool`, etc.) remain as `@deprecated` aliases pointing at the renamed `*ToolConfig` types.

.changeset/provider-tools-ai-core.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/ai': minor
+---
+
+Add `ProviderTool<TProvider, TKind>` phantom-branded tool subtype and a `toolCapabilities` channel on `TextAdapter['~types']`. `TextActivityOptions['tools']` is now typed so that adapter-exported provider tools are gated against the selected model's `supports.tools` list. User tools from `toolDefinition()` remain unaffected.

.changeset/provider-tools-ai-gemini.md

@@ -0,0 +1,7 @@
+---
+'@tanstack/ai-gemini': minor
+---
+
+Expose provider-tool factories (`codeExecutionTool`, `fileSearchTool`, `googleSearchTool`, `googleSearchRetrievalTool`, `googleMapsTool`, `urlContextTool`, `computerUseTool`) on a new `/tools` subpath, each returning a branded type gated against the selected model's `supports.tools` list.
+
+Note: `supports.capabilities` entries that described tools (`code_execution`, `file_search`, `grounding_with_gmaps` → renamed `google_maps`, `search_grounding` → renamed `google_search`, `url_context`) have been relocated to the new `supports.tools` field. The `capabilities` array loses those entries. This is a model-meta shape change but not a runtime break.

.changeset/provider-tools-ai-grok.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/ai-grok': patch
+---
+
+Expose the `/tools` subpath and add an empty `supports.tools: []` channel per model so Grok adapters participate in the core tool-capability type gating. No provider-specific tool factories are exposed yet — define your own tools with `toolDefinition()` from `@tanstack/ai`.

.changeset/provider-tools-ai-groq.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/ai-groq': patch
+---
+
+Expose the `/tools` subpath and add an empty `supports.tools: []` channel per model so Groq adapters participate in the core tool-capability type gating. No provider-specific tool factories are exposed yet — define your own tools with `toolDefinition()` from `@tanstack/ai`.

.changeset/provider-tools-ai-openai.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/ai-openai': minor
+---
+
+Expose provider-tool factories (`webSearchTool`, `webSearchPreviewTool`, `fileSearchTool`, `imageGenerationTool`, `codeInterpreterTool`, `mcpTool`, `computerUseTool`, `localShellTool`, `shellTool`, `applyPatchTool`, `customTool`) on a new `/tools` subpath. Each factory returns a branded type (e.g. `OpenAIWebSearchTool`) gated against the selected model's `supports.tools` list. `supports.tools` was expanded to include `web_search_preview`, `local_shell`, `shell`, `apply_patch`. Existing factory signatures and runtime behavior are unchanged.

.changeset/provider-tools-ai-openrouter.md

@@ -0,0 +1,7 @@
+---
+'@tanstack/ai-openrouter': minor
+---
+
+**Breaking export change.** `createWebSearchTool` has been removed from the package root. Import `webSearchTool` from `@tanstack/ai-openrouter/tools` instead. See Migration Guide §6 for the before/after snippet.
+
+Alongside: the new `/tools` subpath exposes `webSearchTool` (branded `OpenRouterWebSearchTool`) and the existing `convertToolsToProviderFormat`. A new `supports.tools` channel on each chat model gates provider tools at the type level.

docs/adapters/anthropic.md

@@ -237,3 +237,198 @@ Creates an Anthropic summarization adapter with an explicit API key.
 - [Getting Started](../getting-started/quick-start) - Learn the basics
 - [Tools Guide](../tools/tools) - Learn about tools
 - [Other Adapters](./openai) - Explore other providers
+
+## Provider Tools
+
+Anthropic exposes several native tools beyond user-defined function calls.
+Import them from `@tanstack/ai-anthropic/tools` and pass them into
+`chat({ tools: [...] })`.
+
+> For the full concept, a comparison matrix, and type-gating details, see
+> [Provider Tools](../tools/provider-tools.md).
+
+### `webSearchTool`
+
+Enables Claude to run Anthropic's native web search with inline citations.
+Scope the search with `allowed_domains` or `blocked_domains` (mutually
+exclusive); set `max_uses` to cap per-turn cost.
+
+```typescript
+import { chat } from "@tanstack/ai";
+import { anthropicText } from "@tanstack/ai-anthropic";
+import { webSearchTool } from "@tanstack/ai-anthropic/tools";
+
+const stream = chat({
+  adapter: anthropicText("claude-opus-4-6"),
+  messages: [{ role: "user", content: "What's new in AI this week?" }],
+  tools: [
+    webSearchTool({
+      name: "web_search",
+      type: "web_search_20250305",
+      max_uses: 2,
+    }),
+  ],
+});
+```
+
+**Supported models:** every current Claude model. `claude-3-haiku` supports
+only `web_search` (not `web_fetch`). See [Provider Tools](../tools/provider-tools.md#which-models-support-which-tools).
+
+### `webFetchTool`
+
+Lets Claude fetch the contents of a URL directly, useful when you want the
+model to read a specific page rather than run a search. Takes no required
+arguments — pass an optional config object to override defaults.
+
+```typescript
+import { chat } from "@tanstack/ai";
+import { anthropicText } from "@tanstack/ai-anthropic";
+import { webFetchTool } from "@tanstack/ai-anthropic/tools";
+
+const stream = chat({
+  adapter: anthropicText("claude-sonnet-4-5"),
+  messages: [{ role: "user", content: "Summarise https://example.com" }],
+  tools: [webFetchTool()],
+});
+```
+
+**Supported models:** Claude Sonnet 4.x and above. See [Provider Tools](../tools/provider-tools.md#which-models-support-which-tools).
+
+### `codeExecutionTool`
+
+Gives Claude a sandboxed code-execution environment so it can run Python
+snippets, analyse data, and return results inline. Choose the version string
+that matches your desired API revision.
+
+```typescript
+import { chat } from "@tanstack/ai";
+import { anthropicText } from "@tanstack/ai-anthropic";
+import { codeExecutionTool } from "@tanstack/ai-anthropic/tools";
+
+const stream = chat({
+  adapter: anthropicText("claude-sonnet-4-5"),
+  messages: [{ role: "user", content: "Plot a histogram of [1,2,2,3,3,3]" }],
+  tools: [
+    codeExecutionTool({ name: "code_execution", type: "code_execution_20250825" }),
+  ],
+});
+```
+
+**Supported models:** Claude Sonnet 4.x and above. See [Provider Tools](../tools/provider-tools.md#which-models-support-which-tools).
+
+### `computerUseTool`
+
+Allows Claude to observe a virtual desktop (screenshots) and interact with it
+via keyboard and mouse events. Provide the screen resolution so Claude can
+calculate accurate coordinates.
+
+```typescript
+import { chat } from "@tanstack/ai";
+import { anthropicText } from "@tanstack/ai-anthropic";
+import { computerUseTool } from "@tanstack/ai-anthropic/tools";
+
+const stream = chat({
+  adapter: anthropicText("claude-sonnet-4-5"),
+  messages: [{ role: "user", content: "Open the browser and go to example.com" }],
+  tools: [
+    computerUseTool({
+      type: "computer_20250124",
+      name: "computer",
+      display_width_px: 1024,
+      display_height_px: 768,
+    }),
+  ],
+});
+```
+
+**Supported models:** Claude Sonnet 3.5 and above. See [Provider Tools](../tools/provider-tools.md#which-models-support-which-tools).
+
+### `bashTool`
+
+Provides Claude with a persistent bash shell session, letting it run arbitrary
+commands, install packages, or manipulate files on the host. Choose the type
+string that matches your API revision.
+
+```typescript
+import { chat } from "@tanstack/ai";
+import { anthropicText } from "@tanstack/ai-anthropic";
+import { bashTool } from "@tanstack/ai-anthropic/tools";
+
+const stream = chat({
+  adapter: anthropicText("claude-sonnet-4-5"),
+  messages: [{ role: "user", content: "List all TypeScript files in src/" }],
+  tools: [bashTool({ name: "bash", type: "bash_20250124" })],
+});
+```
+
+**Supported models:** Claude Sonnet 3.5 and above. See [Provider Tools](../tools/provider-tools.md#which-models-support-which-tools).
+
+### `textEditorTool`
+
+Gives Claude a structured text-editor interface for viewing and modifying files
+using `str_replace`, `create`, `view`, and `undo_edit` commands. Choose the
+type string for the API revision you target.
+
+```typescript
+import { chat } from "@tanstack/ai";
+import { anthropicText } from "@tanstack/ai-anthropic";
+import { textEditorTool } from "@tanstack/ai-anthropic/tools";
+
+const stream = chat({
+  adapter: anthropicText("claude-sonnet-4-5"),
+  messages: [{ role: "user", content: "Fix the bug in src/index.ts" }],
+  tools: [
+    textEditorTool({ type: "text_editor_20250124", name: "str_replace_editor" }),
+  ],
+});
+```
+
+**Supported models:** Claude Sonnet 3.5 and above. See [Provider Tools](../tools/provider-tools.md#which-models-support-which-tools).
+
+### `memoryTool`
+
+Enables Claude to store and retrieve information across conversation turns
+using Anthropic's managed memory service. Call with no arguments to use
+default configuration.
+
+```typescript
+import { chat } from "@tanstack/ai";
+import { anthropicText } from "@tanstack/ai-anthropic";
+import { memoryTool } from "@tanstack/ai-anthropic/tools";
+
+const stream = chat({
+  adapter: anthropicText("claude-sonnet-4-5"),
+  messages: [{ role: "user", content: "Remember that I prefer metric units" }],
+  tools: [memoryTool()],
+});
+```
+
+**Supported models:** Claude Sonnet 4.x and above. See [Provider Tools](../tools/provider-tools.md#which-models-support-which-tools).
+
+### `customTool`
+
+Creates a tool with an inline JSON Schema input definition instead of going
+through `toolDefinition()`. Useful when you need fine-grained control over the
+schema shape or want to add `cache_control`. Unlike branded provider tools,
+`customTool` returns a plain `Tool` and is accepted by any chat model.
+
+```typescript
+import { chat } from "@tanstack/ai";
+import { anthropicText } from "@tanstack/ai-anthropic";
+import { customTool } from "@tanstack/ai-anthropic/tools";
+import { z } from "zod";
+
+const stream = chat({
+  adapter: anthropicText("claude-sonnet-4-5"),
+  messages: [{ role: "user", content: "Look up user 42" }],
+  tools: [
+    customTool(
+      "lookup_user",
+      "Look up a user by ID and return their profile",
+      z.object({ userId: z.number() }),
+    ),
+  ],
+});
+```
+
+**Supported models:** all current Claude models. See [Provider Tools](../tools/provider-tools.md#which-models-support-which-tools).