@tanstack/ai 0.17.0 → 0.19.0

package/dist/esm/utilities/chat-params.js

@@ -0,0 +1,96 @@
+import { RunAgentInputSchema, AGUIError } from "@ag-ui/core";
+const KNOWN_PART_TYPES = /* @__PURE__ */ new Set([
+  "text",
+  "image",
+  "audio",
+  "video",
+  "document",
+  "tool-call",
+  "tool-result",
+  "thinking"
+]);
+function isValidParts(value) {
+  if (!Array.isArray(value)) return false;
+  for (const p of value) {
+    if (!p || typeof p !== "object") return false;
+    const type = p.type;
+    if (typeof type !== "string" || !KNOWN_PART_TYPES.has(type)) return false;
+  }
+  return true;
+}
+function chatParamsFromRequestBody(body) {
+  const parseResult = RunAgentInputSchema.safeParse(body);
+  if (!parseResult.success) {
+    return Promise.reject(
+      new AGUIError(
+        `Request body is not a valid AG-UI RunAgentInput. If you're upgrading from a previous @tanstack/ai-client release, see docs/migration/ag-ui-compliance.md. Validation errors: ${parseResult.error.message}`
+      )
+    );
+  }
+  const parsed = parseResult.data;
+  const rawMessages = body.messages ?? [];
+  const messages = parsed.messages.map((m, i) => {
+    const raw = rawMessages[i];
+    if (raw && typeof raw === "object" && "parts" in raw && isValidParts(raw.parts)) {
+      return { ...m, parts: raw.parts };
+    }
+    return m;
+  });
+  return Promise.resolve({
+    messages,
+    threadId: parsed.threadId,
+    runId: parsed.runId,
+    parentRunId: parsed.parentRunId,
+    tools: parsed.tools,
+    forwardedProps: parsed.forwardedProps ?? {},
+    state: parsed.state,
+    context: parsed.context
+  });
+}
+async function chatParamsFromRequest(req) {
+  let body;
+  try {
+    body = await req.json();
+  } catch (cause) {
+    const res = new Response(
+      "Invalid AG-UI request body. See docs/migration/ag-ui-compliance.md.",
+      { status: 400 }
+    );
+    res.cause = cause;
+    throw res;
+  }
+  try {
+    return await chatParamsFromRequestBody(body);
+  } catch (cause) {
+    const res = new Response(
+      "Invalid AG-UI request body. See docs/migration/ag-ui-compliance.md.",
+      { status: 400 }
+    );
+    res.cause = cause;
+    throw res;
+  }
+}
+function mergeAgentTools(serverTools, clientTools) {
+  const seen = new Set(serverTools.map((t) => t.name));
+  const merged = [...serverTools];
+  for (const ct of clientTools) {
+    if (seen.has(ct.name)) {
+      continue;
+    }
+    seen.add(ct.name);
+    merged.push({
+      name: ct.name,
+      description: ct.description,
+      inputSchema: ct.parameters
+      // No `execute` — runtime treats this as a client-side tool and
+      // emits ClientToolRequest events.
+    });
+  }
+  return merged;
+}
+export {
+  chatParamsFromRequest,
+  chatParamsFromRequestBody,
+  mergeAgentTools
+};
+//# sourceMappingURL=chat-params.js.map

package/dist/esm/utilities/chat-params.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-params.js","sources":["../../../src/utilities/chat-params.ts"],"sourcesContent":["import { AGUIError, RunAgentInputSchema } from '@ag-ui/core'\nimport type { Context as AGUIContext } from '@ag-ui/core'\nimport type { JSONSchema, ModelMessage, Tool, UIMessage } from '../types'\n\nconst KNOWN_PART_TYPES = new Set([\n  'text',\n  'image',\n  'audio',\n  'video',\n  'document',\n  'tool-call',\n  'tool-result',\n  'thinking',\n])\n\nfunction isValidParts(value: unknown): value is Array<{ type: string }> {\n  if (!Array.isArray(value)) return false\n  for (const p of value) {\n    if (!p || typeof p !== 'object') return false\n    const type = (p as { type?: unknown }).type\n    if (typeof type !== 'string' || !KNOWN_PART_TYPES.has(type)) return false\n  }\n  return true\n}\n\n/**\n * Parse and validate an HTTP request body as an AG-UI `RunAgentInput`.\n *\n * Returns a spread-friendly object whose `messages` field is suitable for\n * passing directly to `chat({ messages })`. The existing\n * `convertMessagesToModelMessages` handles AG-UI fan-out dedup and\n * reasoning/activity/developer-role normalization internally.\n *\n * @throws An error with a migration-pointing message when the body does\n *   not conform to AG-UI 0.0.52 `RunAgentInputSchema`. Surface this as a\n *   400 Bad Request to the client.\n */\nexport function chatParamsFromRequestBody(body: unknown): Promise<{\n  messages: Array<UIMessage | ModelMessage>\n  threadId: string\n  runId: string\n  parentRunId?: string\n  tools: Array<{ name: string; description: string; parameters: JSONSchema }>\n  forwardedProps: Record<string, unknown>\n  state: unknown\n  context: Array<AGUIContext>\n}> {\n  const parseResult = RunAgentInputSchema.safeParse(body)\n  if (!parseResult.success) {\n    return Promise.reject(\n      new AGUIError(\n        `Request body is not a valid AG-UI RunAgentInput. ` +\n          `If you're upgrading from a previous @tanstack/ai-client release, ` +\n          `see docs/migration/ag-ui-compliance.md. ` +\n          `Validation errors: ${parseResult.error.message}`,\n      ),\n    )\n  }\n\n  const parsed = parseResult.data\n\n  // AG-UI Zod uses `.strip()` so extra fields like `parts` on messages are\n  // dropped during parse. We re-attach them from the original body so the\n  // existing UIMessage path inside `chat()` can use them directly.\n  const rawMessages =\n    (body as { messages?: Array<Record<string, unknown>> }).messages ?? []\n  const messages = parsed.messages.map((m, i) => {\n    const raw = rawMessages[i]\n    if (\n      raw &&\n      typeof raw === 'object' &&\n      'parts' in raw &&\n      isValidParts(raw.parts)\n    ) {\n      return { ...m, parts: raw.parts } as UIMessage | ModelMessage\n    }\n    return m as ModelMessage\n  })\n\n  return Promise.resolve({\n    messages,\n    threadId: parsed.threadId,\n    runId: parsed.runId,\n    parentRunId: parsed.parentRunId,\n    tools: parsed.tools as Array<{\n      name: string\n      description: string\n      parameters: JSONSchema\n    }>,\n    forwardedProps: (parsed.forwardedProps ?? {}) as Record<string, unknown>,\n    state: parsed.state,\n    context: parsed.context,\n  })\n}\n\n/**\n * Read an HTTP `Request`, parse its JSON body, and validate it as an\n * AG-UI `RunAgentInput` — collapsing the standard `req.json()` +\n * `chatParamsFromRequestBody(...)` pair into a single call.\n *\n * On a malformed body or invalid AG-UI shape, this **throws a\n * `Response`** with status 400 and a migration-pointing message in the\n * body. Frameworks that natively handle thrown `Response` objects\n * (TanStack Start, SolidStart, Remix, React Router 7) will return the\n * 400 to the client automatically, so the handler reduces to:\n *\n * ```ts\n * export async function POST(req: Request) {\n *   const params = await chatParamsFromRequest(req)\n *   // ...use params\n * }\n * ```\n *\n * In frameworks that do not auto-handle thrown `Response` objects\n * (Next.js Route Handlers, SvelteKit, Hono, raw Node), wrap the call\n * with try/catch and return the caught Response yourself, or use\n * `chatParamsFromRequestBody` directly with your own JSON-parsing.\n *\n * @throws {Response} 400 on malformed JSON or invalid AG-UI shape.\n */\nexport async function chatParamsFromRequest(\n  req: Request,\n): Promise<Awaited<ReturnType<typeof chatParamsFromRequestBody>>> {\n  let body: unknown\n  try {\n    body = await req.json()\n  } catch (cause) {\n    // Preserve the underlying error on the thrown Response for\n    // server-side observability without leaking it to the client.\n    const res = new Response(\n      'Invalid AG-UI request body. See docs/migration/ag-ui-compliance.md.',\n      { status: 400 },\n    )\n    ;(res as unknown as { cause?: unknown }).cause = cause\n    throw res\n  }\n  try {\n    return await chatParamsFromRequestBody(body)\n  } catch (cause) {\n    // Generic public message — avoid echoing Zod paths (which can contain\n    // user payload fragments) or internal validator strings to the client.\n    // The original AGUIError is attached as `cause` so server logs can\n    // surface it without exposing it to remote callers.\n    const res = new Response(\n      'Invalid AG-UI request body. See docs/migration/ag-ui-compliance.md.',\n      { status: 400 },\n    )\n    ;(res as unknown as { cause?: unknown }).cause = cause\n    throw res\n  }\n}\n\n/**\n * Merge a server-side tool array with the AG-UI client-declared tools\n * received in the request body.\n *\n * Rules:\n * - Server tools win on name collision. The client's declaration is\n *   ignored if the server already has a tool with that name. The client's\n *   UI-side handler still fires when the streamed tool-result event comes\n *   through (see `chat-client.ts` `onToolCall`), giving the\n *   \"after server execution the client also handles\" semantic for free.\n * - Client-only tools (name not in `serverTools`) become no-execute\n *   entries: the runtime's existing `ClientToolRequest` path handles\n *   them — server emits a tool-call request, client executes via its\n *   registered handler, client posts back the result.\n *\n * @param serverTools - The server's tool array (e.g. from\n *   `[myToolDef.server(...)]`). Pass directly to `chat({ tools })`.\n * @param clientTools - The `tools` array received from\n *   `chatParamsFromRequest(...)` / `chatParamsFromRequestBody(...)`.\n * @returns A merged array suitable for `chat({ tools })`.\n */\nexport function mergeAgentTools(\n  serverTools: ReadonlyArray<Tool>,\n  clientTools: ReadonlyArray<{\n    name: string\n    description: string\n    parameters: JSONSchema\n  }>,\n): Array<Tool> {\n  const seen = new Set(serverTools.map((t) => t.name))\n  const merged: Array<Tool> = [...serverTools]\n  for (const ct of clientTools) {\n    if (seen.has(ct.name)) {\n      // Server wins on name collision.\n      continue\n    }\n    seen.add(ct.name)\n    merged.push({\n      name: ct.name,\n      description: ct.description,\n      inputSchema: ct.parameters,\n      // No `execute` — runtime treats this as a client-side tool and\n      // emits ClientToolRequest events.\n    } as Tool)\n  }\n  return merged\n}\n"],"names":[],"mappings":";AAIA,MAAM,uCAAuB,IAAI;AAAA,EAC/B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,CAAC;AAED,SAAS,aAAa,OAAkD;AACtE,MAAI,CAAC,MAAM,QAAQ,KAAK,EAAG,QAAO;AAClC,aAAW,KAAK,OAAO;AACrB,QAAI,CAAC,KAAK,OAAO,MAAM,SAAU,QAAO;AACxC,UAAM,OAAQ,EAAyB;AACvC,QAAI,OAAO,SAAS,YAAY,CAAC,iBAAiB,IAAI,IAAI,EAAG,QAAO;AAAA,EACtE;AACA,SAAO;AACT;AAcO,SAAS,0BAA0B,MASvC;AACD,QAAM,cAAc,oBAAoB,UAAU,IAAI;AACtD,MAAI,CAAC,YAAY,SAAS;AACxB,WAAO,QAAQ;AAAA,MACb,IAAI;AAAA,QACF,gLAGwB,YAAY,MAAM,OAAO;AAAA,MAAA;AAAA,IACnD;AAAA,EAEJ;AAEA,QAAM,SAAS,YAAY;AAK3B,QAAM,cACH,KAAuD,YAAY,CAAA;AACtE,QAAM,WAAW,OAAO,SAAS,IAAI,CAAC,GAAG,MAAM;AAC7C,UAAM,MAAM,YAAY,CAAC;AACzB,QACE,OACA,OAAO,QAAQ,YACf,WAAW,OACX,aAAa,IAAI,KAAK,GACtB;AACA,aAAO,EAAE,GAAG,GAAG,OAAO,IAAI,MAAA;AAAA,IAC5B;AACA,WAAO;AAAA,EACT,CAAC;AAED,SAAO,QAAQ,QAAQ;AAAA,IACrB;AAAA,IACA,UAAU,OAAO;AAAA,IACjB,OAAO,OAAO;AAAA,IACd,aAAa,OAAO;AAAA,IACpB,OAAO,OAAO;AAAA,IAKd,gBAAiB,OAAO,kBAAkB,CAAA;AAAA,IAC1C,OAAO,OAAO;AAAA,IACd,SAAS,OAAO;AAAA,EAAA,CACjB;AACH;AA2BA,eAAsB,sBACpB,KACgE;AAChE,MAAI;AACJ,MAAI;AACF,WAAO,MAAM,IAAI,KAAA;AAAA,EACnB,SAAS,OAAO;AAGd,UAAM,MAAM,IAAI;AAAA,MACd;AAAA,MACA,EAAE,QAAQ,IAAA;AAAA,IAAI;AAEd,QAAuC,QAAQ;AACjD,UAAM;AAAA,EACR;AACA,MAAI;AACF,WAAO,MAAM,0BAA0B,IAAI;AAAA,EAC7C,SAAS,OAAO;AAKd,UAAM,MAAM,IAAI;AAAA,MACd;AAAA,MACA,EAAE,QAAQ,IAAA;AAAA,IAAI;AAEd,QAAuC,QAAQ;AACjD,UAAM;AAAA,EACR;AACF;AAuBO,SAAS,gBACd,aACA,aAKa;AACb,QAAM,OAAO,IAAI,IAAI,YAAY,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC;AACnD,QAAM,SAAsB,CAAC,GAAG,WAAW;AAC3C,aAAW,MAAM,aAAa;AAC5B,QAAI,KAAK,IAAI,GAAG,IAAI,GAAG;AAErB;AAAA,IACF;AACA,SAAK,IAAI,GAAG,IAAI;AAChB,WAAO,KAAK;AAAA,MACV,MAAM,GAAG;AAAA,MACT,aAAa,GAAG;AAAA,MAChB,aAAa,GAAG;AAAA;AAAA;AAAA,IAAA,CAGT;AAAA,EACX;AACA,SAAO;AACT;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "description": "Core TanStack AI library - Open source AI SDK",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -53,9 +53,9 @@
     "tanstack-intent"
   ],
   "dependencies": {
-    "@ag-ui/core": "0.0.49",
+    "@ag-ui/core": "^0.0.52",
     "partial-json": "^0.1.7",
-    "@tanstack/ai-event-client": "0.3.1"
+    "@tanstack/ai-event-client": "0.3.3"
   },
   "peerDependencies": {
     "@opentelemetry/api": ">=1.9.0"

package/skills/ai-core/ag-ui-protocol/SKILL.md

@@ -39,6 +39,47 @@ export async function POST(request: Request) {
 typed AG-UI event (discriminated union on `type`). The `toServerSentEventsResponse()`
 helper encodes that iterable into an SSE-formatted `Response` with correct headers.
 
+## Setup — Receiving AG-UI RunAgentInput on the Server
+
+```typescript
+import {
+  chat,
+  chatParamsFromRequestBody,
+  mergeAgentTools,
+  toServerSentEventsResponse,
+} from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai/adapters'
+import { serverTools } from './tools'
+
+export async function POST(req: Request) {
+  let params
+  try {
+    params = await chatParamsFromRequestBody(await req.json())
+  } catch (error) {
+    return new Response(
+      error instanceof Error ? error.message : 'Bad request',
+      { status: 400 },
+    )
+  }
+
+  const stream = chat({
+    adapter: openaiText('gpt-4o'),
+    messages: params.messages,
+    tools: mergeAgentTools(serverTools, params.tools),
+  })
+
+  return toServerSentEventsResponse(stream)
+}
+```
+
+`chatParamsFromRequestBody` validates the body against `RunAgentInputSchema` from `@ag-ui/core`. `mergeAgentTools` merges the server's tool registry with client-declared tools (server wins on collision; client-only tools become no-execute stubs that flow through the runtime's `ClientToolRequest` path).
+
+`params.messages` is a mixed array of TanStack `UIMessage` anchors (with `parts`) and AG-UI fan-out duplicates (`{role:'tool',...}`, `{role:'reasoning',...}`). The existing `convertMessagesToModelMessages` (called inside `chat()`) handles dedup automatically.
+
+**Wire shape (POST body):** AG-UI `RunAgentInput` — `{threadId, runId, parentRunId?, state, messages, tools, context, forwardedProps}`. The `messages` array carries TanStack `UIMessage` anchors with their canonical `parts` plus AG-UI mirror fields (`content`, `toolCalls`) inline; tool results and thinking parts are additionally emitted as fan-out `{role:'tool',...}` and `{role:'reasoning',...}` entries.
+
+**`forwardedProps` security:** Don't spread it directly into `chat()` — clients could override `adapter`, `model`, `tools`, etc. Always allowlist specific fields.
+
 ## Core Patterns
 
 ### 1. SSE Format — toServerSentEventsStream / toServerSentEventsResponse
@@ -223,9 +264,11 @@ Source: docs/protocol/chunk-definitions.md
 
 ## Tension
 
-HIGH Tension: AG-UI protocol compliance vs. internal message format -- TanStack
-AI's `UIMessage` format (parts-based) diverges from AG-UI spec (content-based).
-Full compliance would require a different message structure.
+RESOLVED: TanStack AI is fully AG-UI compliant on both axes (server→client events
+AND client→server `RunAgentInput`). The wire format carries TanStack `UIMessage`
+anchors with their parts intact alongside AG-UI fan-out messages, so strict AG-UI
+servers see role-based messages while TanStack-aware servers read parts directly
+without transformation. See `docs/migration/ag-ui-compliance.md` for details.
 
 ## Cross-References
 

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

@@ -1,23 +1,30 @@
 ---
 name: ai-core/structured-outputs
 description: >
-  Type-safe JSON schema responses from LLMs using outputSchema on chat().
-  Supports Zod, ArkType, and Valibot schemas. The adapter handles
-  provider-specific strategies transparently — never configure structured
-  output at the provider level. Pass stream:true alongside outputSchema for
-  incremental JSON deltas + a terminal validated object via the
-  `structured-output.complete` event. convertSchemaToJsonSchema() for manual
-  schema conversion.
+  Type-safe JSON schema responses from LLMs using outputSchema on chat()
+  and useChat(). Supports Zod, ArkType, and Valibot schemas. The adapter
+  handles provider-specific strategies transparently — never configure
+  structured output at the provider level. Pass stream:true alongside
+  outputSchema for incremental JSON deltas + a terminal validated object
+  via the `structured-output.complete` event. Every assistant turn in
+  useChat carries its own typed `StructuredOutputPart` on
+  `messages[i].parts`, so multi-turn structured chats preserve history
+  automatically — partial/final derive from the latest assistant turn's
+  part. convertSchemaToJsonSchema() for manual schema conversion.
 type: sub-skill
 library: tanstack-ai
 library_version: '0.10.0'
 sources:
-  - 'TanStack/ai:docs/chat/structured-outputs.md'
+  - 'TanStack/ai:docs/structured-outputs/overview.md'
+  - 'TanStack/ai:docs/structured-outputs/one-shot.md'
+  - 'TanStack/ai:docs/structured-outputs/streaming.md'
+  - 'TanStack/ai:docs/structured-outputs/multi-turn.md'
+  - 'TanStack/ai:docs/structured-outputs/with-tools.md'
 ---
 
 # Structured Outputs
 
-> **Dependency note:** This skill builds on ai-core. Read it first for critical rules.
+> **Dependency note:** This skill builds on ai-core. Read it first for critical rules. The `useChat` patterns below build on ai-core/chat-experience — read that for the base hook surface, then come back here for the structured-output specifics.
 
 ## Setup
 
@@ -26,29 +33,32 @@ import { chat } from '@tanstack/ai'
 import { openaiText } from '@tanstack/ai-openai'
 import { z } from 'zod'
 
-const stream = chat({
+const person = await chat({
   adapter: openaiText('gpt-5.2'),
-  messages: [
-    {
-      role: 'user',
-      content: [
-        {
-          type: 'text',
-          content: 'Extract the person info from: John is 30 years old',
-        },
-      ],
-    },
-  ],
+  messages: [{ role: 'user', content: 'John Doe, 30' }],
   outputSchema: z.object({
     name: z.string(),
     age: z.number(),
   }),
 })
+
+person.name // string — fully typed, no cast
+person.age // number
 ```
 
-When `outputSchema` is provided, `chat()` returns `Promise<InferSchemaType<TSchema>>` instead of `AsyncIterable<StreamChunk>`. The result is fully typed based on the schema.
+When `outputSchema` is provided, `chat()` returns `Promise<InferSchemaType<TSchema>>` instead of `AsyncIterable<StreamChunk>`. The result is fully typed.
+
+Adding `stream: true` switches the return to `StructuredOutputStream<InferSchemaType<TSchema>>` — incremental JSON deltas plus a terminal validated object. See **Pattern 3** below for direct iteration, **Pattern 4** for the `useChat` shape on the client, and **Pattern 5** for multi-turn structured chats.
 
-Adding `stream: true` switches the return to `StructuredOutputStream<InferSchemaType<TSchema>>` — incremental JSON deltas plus a terminal validated object. See **Pattern 3** below.
+## Decision: which pattern fits
+
+| Building this                                                                                  | Use                                                              |
+| ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
+| One prompt in → one typed object out (script, server endpoint, CLI)                            | Pattern 1 (basic) or 2 (nested)                                  |
+| A UI that fills in field by field as the model streams (progressive form, live card)           | Pattern 4 — `useChat({ outputSchema })`                          |
+| Direct iteration of the stream in Node or tests                                                | Pattern 3 — async iterable                                       |
+| Users iterate on a structured object across multiple turns (recipe builder, ticket refinement) | Pattern 5 — multi-turn structured chat                           |
+| Tools that gather info, then return a typed object                                             | Combine any of the above with `tools` — see ai-core/tool-calling |
 
 ## Core Patterns
 
@@ -132,9 +142,9 @@ console.log(company.employees[0].role)
 console.log(company.financials?.revenue)
 ```
 
-### Pattern 3: Streaming structured output
+### Pattern 3: Direct stream iteration
 
-Pass `stream: true` alongside `outputSchema` to receive incremental JSON deltas while the model generates, plus a final validated typed object. Useful for streaming partial UI (progress views, typewriter previews, partially-filled forms).
+Pass `stream: true` alongside `outputSchema` to get an async iterable of standard streaming chunks plus a terminal validated object. Use this when you're a single process end-to-end — Node script, CLI, test, or a server endpoint that responds with one JSON blob. For the in-browser progressive-UI case, jump to Pattern 4 instead.
 
 ```typescript
 import { chat } from '@tanstack/ai'
@@ -156,15 +166,8 @@ const stream = chat({
   stream: true,
 })
 
-let raw = ''
 for await (const chunk of stream) {
-  if (chunk.type === 'TEXT_MESSAGE_CONTENT') {
-    // Partial JSON text — drive progress UI only. Do NOT JSON.parse.
-    raw += chunk.delta
-  } else if (
-    chunk.type === 'CUSTOM' &&
-    chunk.name === 'structured-output.complete'
-  ) {
+  if (chunk.type === 'CUSTOM' && chunk.name === 'structured-output.complete') {
     // Terminal event. `chunk.value.object` is fully validated and typed
     // against the schema you passed in — no helper or cast required.
     chunk.value.object.name // string
@@ -174,7 +177,7 @@ for await (const chunk of stream) {
 }
 ```
 
-The terminal event is a `CUSTOM` chunk: `{ type: 'CUSTOM', name: 'structured-output.complete', value: { object: T, raw: string, reasoning?: string } }`. The return type of `chat({ outputSchema, stream: true })` carries `T` through to the terminal event, so a plain discriminated narrow (`chunk.type === 'CUSTOM' && chunk.name === 'structured-output.complete'`) is enough — no type guard helper needed.
+The terminal event is a `CUSTOM` chunk: `{ type: 'CUSTOM', name: 'structured-output.complete', value: { object: T, raw: string, reasoning?: string } }`. The return type of `chat({ outputSchema, stream: true })` carries `T` through, so a plain discriminated narrow (`chunk.type === 'CUSTOM' && chunk.name === 'structured-output.complete'`) is enough — no type guard helper.
 
 **Adapter coverage for streaming:**
 
@@ -186,13 +189,208 @@ The terminal event is a `CUSTOM` chunk: `{ type: 'CUSTOM', name: 'structured-out
 | `@tanstack/ai-groq`                               | Native single-request stream (Chat Completions)                                               |
 | All other adapters (anthropic, gemini, ollama, …) | Fallback: runs non-streaming `structuredOutput`, emits one `structured-output.complete` event |
 
-The consumer code is identical across providers — always read the final object off `structured-output.complete`. You only see incremental deltas when the adapter implements `structuredOutputStream` natively.
+Consumer code is identical across providers — always read the final object off `structured-output.complete`. You only see incremental `TEXT_MESSAGE_CONTENT` deltas when the adapter implements `structuredOutputStream` natively.
+
+### Pattern 4: useChat with outputSchema (progressive UI)
+
+Pass `outputSchema` to `useChat` and you get a `partial` field that fills in as JSON streams in, plus a `final` field that snaps to the validated object on the terminal event. No `onChunk` ceremony, no manual JSON accumulation, no `parsePartialJSON` calls.
+
+**Server** (same as Pattern 3, just behind an SSE endpoint):
+
+```typescript
+// app/api/extract-person/route.ts (or your framework's equivalent)
+import { chat, toServerSentEventsResponse } from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
+import { z } from 'zod'
+
+const PersonSchema = z.object({
+  name: z.string(),
+  age: z.number(),
+  email: z.string().email(),
+})
+
+export async function POST(request: Request) {
+  const { messages } = await request.json()
+  const stream = chat({
+    adapter: openaiText('gpt-5.2'),
+    messages,
+    outputSchema: PersonSchema,
+    stream: true,
+  })
+  return toServerSentEventsResponse(stream)
+}
+```
+
+**Client:**
+
+```tsx
+import { useChat, fetchServerSentEvents } from '@tanstack/ai-react'
+import { z } from 'zod'
+
+const PersonSchema = z.object({
+  name: z.string(),
+  age: z.number(),
+  email: z.string().email(),
+})
+
+function PersonExtractor() {
+  const { sendMessage, isLoading, partial, final } = useChat({
+    connection: fetchServerSentEvents('/api/extract-person'),
+    outputSchema: PersonSchema,
+  })
+
+  return (
+    <div>
+      <button
+        disabled={isLoading}
+        onClick={() => sendMessage('Extract: John Doe, 30, john@example.com')}
+      >
+        Extract
+      </button>
+      {/* `partial` fills in field by field while streaming. */}
+      <p>Name: {partial.name ?? '…'}</p>
+      <p>Age: {partial.age ?? '…'}</p>
+      <p>Email: {partial.email ?? '…'}</p>
+      {final && <pre>Validated: {JSON.stringify(final, null, 2)}</pre>}
+    </div>
+  )
+}
+```
+
+- `partial` is `DeepPartial<z.infer<typeof PersonSchema>>` — every property optional, every nested array element optional. Updated from `TEXT_MESSAGE_CONTENT` deltas.
+- `final` is `z.infer<typeof PersonSchema> | null` — populated when `structured-output.complete` arrives.
+- `outputSchema` is for client-side type inference only. **Validation runs on the server** against the schema you pass to `chat({ outputSchema })` there.
+- Same shape works for non-streaming adapters: the fallback path emits one whole-JSON `TEXT_MESSAGE_CONTENT` then the terminal event, so `partial` populates and `final` snaps in the same render tick — same consumer code as the native-streaming providers, just without an intermediate field-by-field reveal.
+
+### Pattern 5: Multi-turn structured chat
+
+Every assistant turn produced by `useChat({ outputSchema })` carries its own typed `StructuredOutputPart` on `messages[i].parts`. Old turns stay renderable; new turns produce new parts; history is preserved without manual state plumbing. This is what makes the recipe-builder shape ("now make it vegan") work.
+
+```tsx
+import { useChat, fetchServerSentEvents } from '@tanstack/ai-react'
+import type { StructuredOutputPart } from '@tanstack/ai-client'
+import { z } from 'zod'
+
+const RecipeSchema = z.object({
+  title: z.string(),
+  cuisine: z.string(),
+  servings: z.number(),
+  ingredients: z.array(z.object({ item: z.string(), amount: z.string() })),
+  steps: z.array(z.string()),
+})
+type Recipe = z.infer<typeof RecipeSchema>
+type RecipePart = StructuredOutputPart<Recipe>
+
+function RecipeBuilder() {
+  const { messages, sendMessage } = useChat({
+    outputSchema: RecipeSchema,
+    connection: fetchServerSentEvents('/api/recipes'),
+  })
+
+  return (
+    <div>
+      {messages.map((m) => {
+        if (m.role === 'user') {
+          const text = m.parts
+            .filter((p) => p.type === 'text')
+            .map((p) => p.content)
+            .join('')
+          return <UserBubble key={m.id} text={text} />
+        }
+        if (m.role === 'assistant') {
+          // `data` is `Recipe` because the schema generic flows from
+          // `useChat({ outputSchema })` through `messages` to the part.
+          const part = m.parts.find(
+            (p): p is RecipePart => p.type === 'structured-output',
+          )
+          if (!part) return null
+          return <RecipeCard key={m.id} part={part} />
+        }
+        return null
+      })}
+      <button onClick={() => sendMessage('pasta for two')}>Cook</button>
+      <button onClick={() => sendMessage('now make it vegan')}>Modify</button>
+    </div>
+  )
+}
+
+function RecipeCard({ part }: { part: RecipePart }) {
+  // `data` lands on complete, `partial` fills in while streaming.
+  // Both are typed against the schema. No casts.
+  const recipe = part.data ?? part.partial ?? ({} as Partial<Recipe>)
+  return <h3>{recipe.title ?? 'Plating up…'}</h3>
+}
+```
+
+Key behaviors:
+
+- **Per-turn parts.** Each `sendMessage()` produces a new assistant message with its own `StructuredOutputPart`. The previous turn's part is untouched — `messages.map(...)` renders the whole history.
+- **Typed by schema.** `messages[i].parts.find(p => p.type === 'structured-output').data` is typed as `Recipe` (no cast, no `unknown`). Works because `useChat<TSchema>` threads `InferSchemaType<TSchema>` down through `UIMessage<TTools, TData>` → `MessagePart<TTools, TData>` → `StructuredOutputPart<TData>`. **In `@tanstack/ai` core** the message types are single-generic (`UIMessage<TData>`); the tools generic lives in `@tanstack/ai-client` and the framework hook packages — import from your framework package or `ai-client`, not from `@tanstack/ai`.
+- **`partial` / `final` are derived.** The hook-level `partial` and `final` are NOT singleton state — they're derived from the latest assistant message's part (the one after the most recent user message). Between `sendMessage()` and the first chunk, `partial` reads `{}` and `final` reads `null` because no new assistant turn exists yet.
+- **Round-trip preserves history.** When the client sends turn N+1, each prior assistant turn's `structured-output` part is serialized back as `{ role: 'assistant', content: <part.raw> }` so the model sees its own prior structured response. Streaming / errored parts are dropped from the round-trip.
 
 ## Common Mistakes
 
+### HIGH: Filtering `TextPart`s out of `useChat` renderers when using `outputSchema`
+
+Earlier versions of the library routed structured-output JSON deltas through `TextPart`, so renderers had to filter them out:
+
+```tsx
+// OBSOLETE — this guard was needed only because JSON used to land in a TextPart
+const last = messages.at(-1)
+last?.parts.map((part) => {
+  if (part.type === 'text') return null // ❌ hides the structured JSON
+  // ...
+})
+```
+
+That hack is **gone**. With `outputSchema` set, `TEXT_MESSAGE_CONTENT` deltas now route into a dedicated `StructuredOutputPart` (with `raw`, `partial`, `data`, `status`, optional `errorMessage`). Render the structured part directly; let real `TextPart`s through.
+
+```tsx
+// CORRECT — find the structured-output part directly; let actual TextParts render
+last?.parts.map((part, i) => {
+  if (part.type === 'thinking')
+    return <ReasoningView key={i} text={part.content} />
+  if (part.type === 'tool-call') return <ToolCallView key={i} part={part} />
+  if (part.type === 'structured-output')
+    return <RecipeCard key={i} part={part} />
+  if (part.type === 'text') return <p key={i}>{part.content}</p> // ← real text, not JSON
+  return null
+})
+```
+
+If you still have an `if (part.type === 'text') return null` line in a structured-output renderer specifically for "hiding the JSON," delete it.
+
+Source: PR #577 — structured-output became a typed UIMessage part.
+
+### HIGH: Treating `partial` / `final` as sticky state across turns
+
+`partial` and `final` are **derived from the latest assistant message's `structured-output` part**, not a sticky hook-level slot. In a multi-turn chat:
+
+- Between `sendMessage()` and the first chunk, `partial` reads `{}` and `final` reads `null` (no assistant message after the latest user yet).
+- Once the latest turn completes, `partial === final`. Earlier turns' data is NOT in `partial` / `final` — it lives on the prior assistant messages' parts.
+
+To render history, walk `messages` directly (see Pattern 5). Use `partial` / `final` for a sticky summary of the **most recent** turn only.
+
+```tsx
+// WRONG — `final` only reflects the latest turn; earlier recipes vanish from this view
+{final && <RecipeCard recipe={final} />}
+
+// CORRECT for history — walk messages, render every assistant's structured-output part
+{messages.map((m) =>
+  m.role === 'assistant'
+    ? m.parts.find((p) => p.type === 'structured-output')
+      ? <RecipeCard key={m.id} part={...} />
+      : null
+    : null
+)}
+```
+
+Source: PR #577 — partial/final derive from the latest assistant turn's part.
+
 ### HIGH: Parsing streaming JSON deltas yourself
 
-When using `chat({ outputSchema, stream: true })`, the `TEXT_MESSAGE_CONTENT` chunks contain _partial_ JSON fragments — they are not valid JSON until the stream completes. Always read the validated object from the terminal `structured-output.complete` event. Validation runs once, on the complete payload.
+When iterating `chat({ outputSchema, stream: true })` directly (Pattern 3), the `TEXT_MESSAGE_CONTENT` chunks contain _partial_ JSON fragments — they are not valid JSON until the stream completes. Always read the validated object from the terminal `structured-output.complete` event. Validation runs once, on the complete payload.
 
 ```typescript
 // WRONG -- partial JSON, throws SyntaxError mid-stream, no schema validation
@@ -202,21 +400,15 @@ for await (const chunk of stream) {
   }
 }
 
-// CORRECT -- accumulate deltas only for UX progress; trust the terminal event
-let raw = ''
+// CORRECT -- trust the terminal event
 for await (const chunk of stream) {
-  if (chunk.type === 'TEXT_MESSAGE_CONTENT') {
-    raw += chunk.delta // optional: render a "streaming JSON" preview
-  } else if (
-    chunk.type === 'CUSTOM' &&
-    chunk.name === 'structured-output.complete'
-  ) {
+  if (chunk.type === 'CUSTOM' && chunk.name === 'structured-output.complete') {
     const result = chunk.value.object // ✅ typed and validated
   }
 }
 ```
 
-If you need progressive _parsed_ state (e.g. show fields as they arrive), use a partial-JSON parser on the accumulated `raw` string at render time — but do NOT treat the result as schema-validated; only the terminal event is.
+If you need progressive parsed state in a non-React environment, use a partial-JSON parser on the accumulated raw string at render time — but do NOT treat the result as schema-validated; only the terminal event is. In `useChat`, this is already done for you (`partial` field on Pattern 4).
 
 Source: maintainer interview
 
@@ -290,5 +482,6 @@ Source: maintainer interview
 
 ## Cross-References
 
-- See also: ai-core/adapter-configuration/SKILL.md -- Adapter handles structured output strategy transparently
-- See also: ai-core/chat-experience/SKILL.md -- Consuming `StreamChunk` events on the client (the streaming variant uses the same chunk model plus the terminal `structured-output.complete` custom event)
+- See also: **ai-core/chat-experience/SKILL.md** — Base `useChat` surface; the structured-output additions documented here layer on top.
+- See also: **ai-core/adapter-configuration/SKILL.md** — Adapter handles structured-output strategy transparently.
+- See also: **ai-core/tool-calling/SKILL.md** — Combine `tools` with `outputSchema` for an agent loop that runs tools first and returns a typed object. Tool-approval and client-tool flows compose with structured runs without extra wiring; see [docs/structured-outputs/with-tools.md](https://github.com/TanStack/ai/blob/main/docs/structured-outputs/with-tools.md).