feat: type-safe tool-call parts in useChat (typed chunks, parsed input, gated approval) (#918)

* feat(react,vue,solid,svelte): infer typed chunks from a bare tools array

Add the `const` modifier to the `TTools` type param of useChat/createChat so a
plain inline `tools: [a, b]` array captures the tuple + literal tool names and
yields a typed, discriminated tool-call part union — no `clientTools(...)`
wrapper or `as const` needed. clientTools() still works.

* feat(ai): populate parsed input on tool-call parts

ToolCallPart already declared a typed `input?` field but it was never written
at runtime — only the raw `arguments` string and `output` were set. Populate
`input` from the parsed arguments once complete (in the stream processor's
completeToolCall, the TOOL_CALL_END parsed-input path, and history hydration in
modelMessagesToUIMessages), carrying it forward through the part updaters.
`arguments` is unchanged and not deprecated.

* feat(ai,ai-client): gate tool-call `approval` on needsApproval

Capture `needsApproval` as a literal type param (TNeedsApproval) on the client
tool types, and include the `approval` field on a tool-call part only when the
tool was defined with `needsApproval: true`. Non-approval tools have no
`approval` field (reading it is a compile error). Generic handlers still work
via an `'approval' in part` guard or the base ToolCallPart type; untyped
useChat() is unaffected.

* docs,examples,e2e: cover typed tool-call parts + AG-UI tool-forwarding safety

- Document parsed `input`, approval gating (+ generic-handler escape hatches),
  and the AG-UI client-tool forwarding security tradeoff (manual registration
  is the safe default; mergeAgentTools trusts the client) in tool-approval,
  client-tools, ag-ui-compliance docs and the tool-calling skill.
- Drop the redundant Object.values() around mergeAgentTools (it already returns
  an array) in the react/vue examples.
- Add the /typesafe-tools demo route and e2e assertions for input population.

* docs: prefer plain `tools` arrays, document clientTools as an optional escape hatch

A plain `tools: [a, b]` array (inline or a separate const) now narrows tool
names, inputs and outputs on its own, so drop `clientTools(...)` from the
framework/API/tool docs and demote it to an optional identity helper documented
once in client-tools + the ai-client reference. Adds a regression test proving a
separately-declared const array narrows without clientTools or `as const`.

* fix(examples,e2e): resolve type errors surfaced by precise tool inference

- ts-solid-chat: pass a real `fetchServerSentEvents` connection to useChat
  instead of re-passing `chatOptions.connection` (typed `| undefined`, which
  no longer satisfies the connection/fetcher transport XOR now that the tools
  tuple is precise); guard `part.approval` with `'approval' in part`.
- e2e tools-test: cast the untyped history-fixture `initialMessages` to the
  typed message shape so they don't conflict with the concrete tools tuple.

* fix: address PR review — sync TOOL_CALL_END.input override + doc nits

- processor: when TOOL_CALL_END provides a parsed `input` that diverges from
  the accumulated args parse, refresh the rendered tool-call part so
  `part.input` reflects the canonical override (not the stale parse). Adds a
  divergent-input test.
- docs/skill: render `part.input` directly in approval examples (parts have
  parsed input by approval time); note the approval gate in the ai-client
  ToolCallPart reference; use gpt-5.5 across all ag-ui-compliance tiers.

* ci: apply automated fixes

* fix(e2e): type-check Gemini video mock config

`Omit<GeminiVideoConfig, 'apiKey'>` drops the inherited `GoogleGenAIOptions`
keys (a tsc quirk from the config's own `allowUrlFetch` member — the empty
image/audio configs are unaffected), so the `httpOptions` mock-routing literal
was rejected only here. Cast to the param type; the mock base URL is required
at runtime. Pre-existing on main, surfaced now that `test:pr` type-checks
examples/testing and this PR makes the e2e app affected.

* ci: apply automated fixes

* fix: address PR review follow-ups — rebase, parity, tests, safety

- Rebase onto main (resolve solid-chat + e2e merge conflicts)
- Extend `const TTools` to Preact `useChat` and Angular `injectChat`
- Add message-updaters tests for `input` carry-forward through approval
- Guard `JSON.stringify(chunk.input)` in stream processor
- Strengthen approval-gating changeset migration notes; include angular/preact
  in the const-tools inference changeset

* ci: apply automated fixes

* fix(examples): link Type-Safe Tools demo from home page and nav

The /typesafe-tools route was added in PR #918 but had no discoverability
entry points — add it to the empty-state grid on the home page and to the
Examples section in the header drawer.

* fix(examples): remove duplicate connection in ts-solid-chat useChat

Spreading chatOptions already supplies the SSE connection. Re-specifying
connection conflicted with the ChatTransport XOR and broke test:types.

---------

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
Co-authored-by: Tom Beckenham <34339192+tombeckenham@users.noreply.github.com>

Author: 3 people

.changeset/tool-call-approval-gating.md

@@ -0,0 +1,55 @@
+---
+'@tanstack/ai': minor
+'@tanstack/ai-client': minor
+---
+
+Gate the tool-call part's `approval` field on the tool's `needsApproval` flag.
+Previously `approval?` was declared on every typed tool-call part regardless of
+whether the tool could ever request approval. Now the flag is captured as a
+literal type (`toolDefinition({ needsApproval: true })` → `true`) and threaded
+through `ClientTool` / `ToolDefinitionInstance` / `ToolDefinition`, and
+`ToolCallPartForTool` only includes `approval` for tools defined with
+`needsApproval: true`:
+
+```ts
+const { messages } = useChat({ tools: [getGuitars, addToCart] }) // addToCart: needsApproval: true
+for (const part of message.parts) {
+  if (part.type !== 'tool-call') continue
+  if (part.name === 'addToCart') part.approval?.id // ✅ typed
+  if (part.name === 'getGuitars') part.approval // ✅ compile error — no such field
+}
+```
+
+## ⚠️ Breaking change (types only)
+
+**This is the primary migration surface for this release.** When you pass a typed
+`tools` array to `useChat` / `createChat` / `injectChat`, reading `part.approval`
+on a mixed tool-call union **without first narrowing by `part.name`** no longer
+compiles. Code that previously did `part.approval?.id` in a generic handler over
+all tool-call parts must be updated:
+
+```ts
+// ❌ No longer compiles on a typed mixed union
+part.approval?.id
+
+// ✅ Narrow to an approval-required tool first
+if (part.name === 'deleteAccount') part.approval?.id
+
+// ✅ Or guard with `in`
+if ('approval' in part) part.approval?.id
+
+// ✅ Or type the handler against the base (untyped) ToolCallPart
+function handleApproval(part: ToolCallPart) {
+  return part.approval?.id
+}
+```
+
+Untyped `useChat()` (no inferred `tools` generic) and the base `ToolCallPart`
+type are unaffected: `approval` stays available on every tool-call part there.
+**Runtime behavior is unchanged** — only TypeScript narrowing is stricter.
+
+Adds a `TNeedsApproval extends boolean` type parameter (defaulting to `false`)
+to the client tool types; existing explicit type arguments keep working via the
+default. Literal capture requires `toolDefinition({ needsApproval: true })` at
+the call site — a dynamic `needsApproval: boolean` variable will not gate the
+type.

.changeset/tool-call-part-parsed-input.md

@@ -0,0 +1,19 @@
+---
+'@tanstack/ai': minor
+---
+
+Populate the parsed `input` on tool-call message parts. `ToolCallPart` already
+declared a typed `input?` field, but it was never written at runtime — only the
+raw `arguments` string (and `output`) were set, so `part.input` was always
+`undefined` and consumers had to fall back to `part.input ?? JSON.parse(part.arguments)`.
+
+`input` is now set from the parsed arguments once they are complete
+(`state: 'input-complete'` and later, including `approval-requested`), in the
+streaming processor, the `TOOL_CALL_END`-with-parsed-input path, and when
+hydrating history via `modelMessagesToUIMessages`. While arguments are still
+streaming, `input` stays `undefined` and the raw `arguments` string remains the
+live source. A tool call that terminates in an error state may also keep `input`
+unset. `arguments` is unchanged, always present, and not deprecated.
+
+With typed tools (`useChat({ tools })`), `part.input` is fully typed per tool
+via the `part.name` discriminant — matching `part.output`.

.changeset/usechat-const-tools-inference.md

@@ -0,0 +1,18 @@
+---
+'@tanstack/ai-angular': patch
+'@tanstack/ai-preact': patch
+'@tanstack/ai-react': patch
+'@tanstack/ai-solid': patch
+'@tanstack/ai-svelte': patch
+'@tanstack/ai-vue': patch
+---
+
+Add the `const` modifier to the `TTools` type parameter of `useChat`
+(`createChat` in Svelte, `injectChat` in Angular) so a plain inline `tools` array
+now yields full type-safe message chunks. Previously the array widened to
+`Array<Union>` and lost the literal tool `name`s that drive the
+discriminated `tool-call` part union, so callers had to wrap their tools in
+`clientTools(...)` (or add `as const`) to get narrowing. That wrapper is now
+optional — `tools: [toolA, toolB]` narrows `part.name`, `part.input`, and
+`part.output` on its own. `clientTools(...)` still works and remains useful
+for defining a shared tuple outside the hook call.

docs/advanced/runtime-context.md

@@ -79,7 +79,6 @@ This inference also works when reusable tools or middleware are declared outside
 The same rule applies on the client:
 
 ```typescript
-import { clientTools } from "@tanstack/ai-client";
 import { useChat, fetchServerSentEvents } from "@tanstack/ai-react";
 import { toolDefinition } from "@tanstack/ai";
 
@@ -99,7 +98,7 @@ const inspectClientContext = toolDefinition({
 
 useChat({
   connection: fetchServerSentEvents("/api/chat"),
-  tools: clientTools(inspectClientContext),
+  tools: [inspectClientContext],
   context: {
     currentTabId: "settings",
     mode: "debug",
@@ -184,7 +183,7 @@ When any tool or middleware in a `chat()` call declares a concrete context type,
 Client runtime context is local to `ChatClient` and framework hooks. It is passed to client tool implementations and is not serialized to the server.
 
 ```typescript
-import { createChatClientOptions, clientTools } from "@tanstack/ai-client";
+import { createChatClientOptions } from "@tanstack/ai-client";
 import { useChat, fetchServerSentEvents } from "@tanstack/ai-react";
 import { toolDefinition } from "@tanstack/ai";
 
@@ -203,7 +202,7 @@ const notifyUser = toolDefinition({
 
 const chatOptions = createChatClientOptions({
   connection: fetchServerSentEvents("/api/chat"),
-  tools: clientTools(notifyUser),
+  tools: [notifyUser],
   context: {
     currentTabId: "settings",
     toast: (message) => window.alert(message),
@@ -221,7 +220,6 @@ To send serializable client data to the server, use `forwardedProps`, validate i
 
 ```typescript
 import { useChat, fetchServerSentEvents } from "@tanstack/ai-react";
-import { clientTools } from "@tanstack/ai-client";
 import { toolDefinition } from "@tanstack/ai";
 
 type ClientContext = {
@@ -240,7 +238,7 @@ const notifyUser = toolDefinition({
 // Client
 useChat({
   connection: fetchServerSentEvents("/api/chat"),
-  tools: clientTools(notifyUser),
+  tools: [notifyUser],
   forwardedProps: {
     tenantId: "tenant_456",
   },

docs/api/ai-angular.md

@@ -234,7 +234,6 @@ import { Component } from "@angular/core";
 import { CommonModule } from "@angular/common";
 import { injectChat, fetchServerSentEvents } from "@tanstack/ai-angular";
 import {
-  clientTools,
   createChatClientOptions,
   type InferChatMessages,
 } from "@tanstack/ai-client";
@@ -280,7 +279,7 @@ export class TypedChatComponent {
   });
 
   // Create typed tools array (no 'as const' needed!)
-  private tools = clientTools(this.updateUI, this.saveToStorage);
+  private tools = [this.updateUI, this.saveToStorage];
 
   chat = injectChat({
     connection: fetchServerSentEvents("/api/chat"),
@@ -526,15 +525,14 @@ Helper to create typed chat options (re-exported from `@tanstack/ai-client`).
 
 ```typescript
 import {
-  clientTools,
   createChatClientOptions,
   type InferChatMessages,
 } from "@tanstack/ai-client";
 import { fetchServerSentEvents } from "@tanstack/ai-angular";
 import { tool1, tool2 } from "./tools";
 
 // Create typed tools array (no 'as const' needed!)
-const tools = clientTools(tool1, tool2);
+const tools = [tool1, tool2];
 
 const chatOptions = createChatClientOptions({
   connection: fetchServerSentEvents("/api/chat"),

docs/api/ai-client.md

@@ -28,7 +28,6 @@ The main client class for managing chat state.
 ```typescript
 import {
   ChatClient,
-  clientTools,
   fetchServerSentEvents,
   type UIMessage,
 } from "@tanstack/ai-client";
@@ -37,7 +36,7 @@ import { myClientTool } from "./tools";
 const client = new ChatClient({
   connection: fetchServerSentEvents("/api/chat"),
   initialMessages: [],
-  tools: clientTools(myClientTool),
+  tools: [myClientTool],
   onMessagesChange: (messages: UIMessage[]) => {
     console.log("Messages updated:", messages);
   },
@@ -281,7 +280,7 @@ const adapter = stream(async (messages, data, signal) => {
 
 ### `clientTools(...tools)`
 
-Creates a typed array of client tools with proper type inference. This eliminates the need for `as const` when defining tool arrays and enables proper discriminated union type narrowing.
+**Optional.** A plain array — `tools: [tool1, tool2]` — already narrows tool names, inputs and outputs without any wrapper or `as const`. `clientTools()` is an identity helper that performs the same capture explicitly; reach for it only when you want to build a shared, reusable tools tuple outside the hook/options call.
 
 ```typescript
 import {
@@ -320,7 +319,7 @@ const tool2Client = myTool2.client((input) => {
   return { result: input.query };
 });
 
-// Create typed tools array (no 'as const' needed!)
+// The explicit-capture form (equivalent to `[tool1Client, tool2Client]`).
 const tools = clientTools(tool1Client, tool2Client);
 
 // Now when you use these tools in chat options:
@@ -348,13 +347,12 @@ Helper function to create typed chat client options with proper type inference.
 ```typescript
 import {
   createChatClientOptions,
-  clientTools,
   fetchServerSentEvents,
   type InferChatMessages,
 } from "@tanstack/ai-client";
 import { tool1, tool2 } from "./tools";
 
-const tools = clientTools(tool1, tool2);
+const tools = [tool1, tool2];
 
 const chatOptions = createChatClientOptions({
   connection: fetchServerSentEvents("/api/chat"),
@@ -370,7 +368,6 @@ type ChatMessages = InferChatMessages<typeof chatOptions>;
 ```typescript
 import {
   createChatClientOptions,
-  clientTools,
   fetchServerSentEvents,
 } from "@tanstack/ai-client";
 import { toolDefinition } from "@tanstack/ai";
@@ -394,7 +391,7 @@ const tool = projectTool.client<ClientContext>((input, ctx: { context: ClientCon
 
 const chatOptions = createChatClientOptions({
   connection: fetchServerSentEvents("/api/chat"),
-  tools: clientTools(tool),
+  tools: [tool],
   context: {
     activeProjectId: "project_123",
   },
@@ -454,12 +451,12 @@ interface ToolCallPart {
   arguments: string; // JSON string (may be incomplete during streaming)
   input?: any; // Parsed tool input (typed from tool's inputSchema)
   state: ToolCallState;
-  approval?: ApprovalRequest;
+  approval?: ApprovalRequest; // only on tools declared `needsApproval: true`
   output?: any; // Tool execution output (typed from tool's outputSchema)
 }
 ```
 
-When using typed tools with `clientTools()` and `createChatClientOptions()`, the `input` and `output` fields are automatically typed based on your tool's Zod schemas, and `name` becomes a discriminated union enabling type narrowing.
+When you pass a typed `tools` array (a plain array works — `clientTools()` is optional), the `input` and `output` fields are automatically typed based on your tool's Zod schemas, and `name` becomes a discriminated union enabling type narrowing. The `approval` field is present **only** on parts for tools declared with `needsApproval: true` — narrow by `part.name` (or guard with `'approval' in part`) before accessing it.
 
 ### `ToolResultPart`
 

docs/api/ai-preact.md

@@ -27,7 +27,6 @@ Main hook for managing chat state in Preact with full type safety.
 ```tsx
 import { useChat, fetchServerSentEvents } from "@tanstack/ai-preact";
 import { 
-  clientTools, 
   createChatClientOptions, 
   type InferChatMessages 
 } from "@tanstack/ai-client";
@@ -50,7 +49,7 @@ function ChatComponent() {
   });
 
   // Create typed tools array (no 'as const' needed!)
-  const tools = clientTools(updateUI);
+  const tools = [updateUI];
 
   const chatOptions = createChatClientOptions({
     connection: fetchServerSentEvents("/api/chat"),
@@ -246,7 +245,6 @@ export function ChatWithApproval() {
 ```tsx
 import { useChat, fetchServerSentEvents } from "@tanstack/ai-preact";
 import { 
-  clientTools, 
   createChatClientOptions, 
   type InferChatMessages 
 } from "@tanstack/ai-client";
@@ -282,7 +280,7 @@ export function ChatWithClientTools() {
   });
 
   // Create typed tools array (no 'as const' needed!)
-  const tools = clientTools(updateUI, saveToStorage);
+  const tools = [updateUI, saveToStorage];
 
   const { messages, sendMessage } = useChat({
     connection: fetchServerSentEvents("/api/chat"),
@@ -311,15 +309,14 @@ Helper to create typed chat options (re-exported from `@tanstack/ai-client`).
 
 ```typescript
 import { 
-  clientTools, 
   createChatClientOptions, 
   type InferChatMessages 
 } from "@tanstack/ai-client";
 import { fetchServerSentEvents } from "@tanstack/ai-preact";
 import { tool1, tool2 } from "./tools";
 
 // Create typed tools array (no 'as const' needed!)
-const tools = clientTools(tool1, tool2);
+const tools = [tool1, tool2];
 
 const chatOptions = createChatClientOptions({
   connection: fetchServerSentEvents("/api/chat"),

docs/api/ai-react.md

@@ -33,7 +33,6 @@ Main hook for managing chat state in React with full type safety.
 ```tsx
 import { useChat, fetchServerSentEvents } from "@tanstack/ai-react";
 import { 
-  clientTools, 
   createChatClientOptions, 
   type InferChatMessages 
 } from "@tanstack/ai-client";
@@ -60,7 +59,7 @@ function ChatComponent() {
   });
 
   // Create typed tools array (no 'as const' needed!)
-  const tools = clientTools(updateUI);
+  const tools = [updateUI];
 
   const chatOptions = createChatClientOptions({
     connection: fetchServerSentEvents("/api/chat"),
@@ -275,7 +274,6 @@ export function ChatWithApproval() {
 ```tsx
 import { useChat, fetchServerSentEvents } from "@tanstack/ai-react";
 import { 
-  clientTools, 
   createChatClientOptions, 
   type InferChatMessages 
 } from "@tanstack/ai-client";
@@ -319,7 +317,7 @@ export function ChatWithClientTools() {
   });
 
   // Create typed tools array (no 'as const' needed!)
-  const tools = clientTools(updateUI, saveToStorage);
+  const tools = [updateUI, saveToStorage];
 
   const { messages, sendMessage } = useChat({
     connection: fetchServerSentEvents("/api/chat"),
@@ -348,15 +346,14 @@ Helper to create typed chat options (re-exported from `@tanstack/ai-client`).
 
 ```typescript
 import { 
-  clientTools, 
   createChatClientOptions, 
   fetchServerSentEvents,
   type InferChatMessages 
 } from "@tanstack/ai-client";
 import { tool1, tool2 } from "./tools";
 
 // Create typed tools array (no 'as const' needed!)
-const tools = clientTools(tool1, tool2);
+const tools = [tool1, tool2];
 
 const chatOptions = createChatClientOptions({
   connection: fetchServerSentEvents("/api/chat"),