@tanstack/ai 0.53.0 → 0.54.0

package/skills/ai-core/middleware/SKILL.md

@@ -24,26 +24,31 @@ sources:
 ```typescript
 import { chat, toServerSentEventsResponse } from '@tanstack/ai'
 import { openaiText } from '@tanstack/ai-openai'
+import { trackAnalytics, reportError } from './analytics'
 
-const stream = chat({
-  adapter: openaiText('gpt-5.2'),
-  messages,
-  middleware: [
-    {
-      onStart: (ctx) => {
-        console.log('Chat started:', ctx.model)
-      },
-      onFinish: (ctx, info) => {
-        trackAnalytics({ model: ctx.model, tokens: info.usage?.totalTokens })
-      },
-      onError: (ctx, info) => {
-        reportError(info.error)
+export async function POST(request: Request) {
+  const { messages } = await request.json()
+
+  const stream = chat({
+    adapter: openaiText('gpt-5.5'),
+    messages,
+    middleware: [
+      {
+        onStart: (ctx) => {
+          console.log('Chat started:', ctx.model)
+        },
+        onFinish: (ctx, info) => {
+          trackAnalytics({ model: ctx.model, tokens: info.usage?.totalTokens })
+        },
+        onError: (ctx, info) => {
+          reportError(info.error)
+        },
       },
-    },
-  ],
-})
+    ],
+  })
 
-return toServerSentEventsResponse(stream)
+  return toServerSentEventsResponse(stream)
+}
 ```
 
 ## Hooks Reference
@@ -119,19 +124,30 @@ specific config changes that should not affect the agent-loop adapter calls.
 **Signature:**
 
 ```ts
-onStructuredOutputConfig?: (
-  ctx: ChatMiddlewareContext,
-  config: StructuredOutputMiddlewareConfig,
-) =>
-  | void
-  | null
-  | Partial<StructuredOutputMiddlewareConfig>
-  | Promise<void | null | Partial<StructuredOutputMiddlewareConfig>>
+import type {
+  ChatMiddlewareContext,
+  StructuredOutputMiddlewareConfig,
+} from '@tanstack/ai'
+
+// Excerpt of the `ChatMiddleware` interface exported by '@tanstack/ai'
+interface ChatMiddleware {
+  onStructuredOutputConfig?: (
+    ctx: ChatMiddlewareContext,
+    config: StructuredOutputMiddlewareConfig,
+  ) =>
+    | void
+    | null
+    | Partial<StructuredOutputMiddlewareConfig>
+    | Promise<void | null | Partial<StructuredOutputMiddlewareConfig>>
+}
 ```
 
 **`StructuredOutputMiddlewareConfig` shape:**
 
 ```ts
+import type { ChatMiddlewareConfig, JSONSchema } from '@tanstack/ai'
+
+// As exported by '@tanstack/ai'
 interface StructuredOutputMiddlewareConfig extends Omit<
   ChatMiddlewareConfig,
   'tools'
@@ -203,13 +219,17 @@ const analytics: ChatMiddleware = {
   },
 }
 
-const stream = chat({
-  adapter: openaiText('gpt-5.2'),
-  messages,
-  middleware: [analytics],
-})
+export async function POST(request: Request) {
+  const { messages } = await request.json()
+
+  const stream = chat({
+    adapter: openaiText('gpt-5.5'),
+    messages,
+    middleware: [analytics],
+  })
 
-return toServerSentEventsResponse(stream)
+  return toServerSentEventsResponse(stream)
+}
 ```
 
 ### Pattern 2: Tool Interception Middleware
@@ -278,11 +298,14 @@ native-combined schema.
 
 ```typescript
 import type { ChatMiddleware } from '@tanstack/ai'
+import { trace } from '@opentelemetry/api'
 
 const tracing: ChatMiddleware = {
   name: 'tracing',
   onChunk(ctx, chunk) {
-    span.addEvent('chunk', { phase: ctx.phase, type: chunk.type })
+    trace
+      .getActiveSpan()
+      ?.addEvent('chunk', { phase: ctx.phase, type: chunk.type })
   },
 }
 ```
@@ -296,6 +319,7 @@ the native-combined path, it observes the structured stream with
 
 ```typescript
 import type { ChatMiddleware } from '@tanstack/ai'
+import { sharedDefs } from './defs'
 
 const injectDefs: ChatMiddleware = {
   name: 'inject-defs',
@@ -317,9 +341,27 @@ Middleware executes in array order (left-to-right). Ordering matters for hooks t
 pipe or short-circuit:
 
 ```typescript
-import { chat, type ChatMiddleware } from '@tanstack/ai'
+import {
+  chat,
+  toolDefinition,
+  toServerSentEventsResponse,
+  type ChatMiddleware,
+} from '@tanstack/ai'
 import { toolCacheMiddleware } from '@tanstack/ai/middlewares'
 import { openaiText } from '@tanstack/ai-openai'
+import { z } from 'zod'
+
+const weatherTool = toolDefinition({
+  name: 'getWeather',
+  description: 'Get the current weather for a city',
+  inputSchema: z.object({ city: z.string() }),
+}).server(async ({ city }) => ({ city, tempC: 21 }))
+
+const stockTool = toolDefinition({
+  name: 'getStock',
+  description: 'Get the latest price for a ticker symbol',
+  inputSchema: z.object({ symbol: z.string() }),
+}).server(async ({ symbol }) => ({ symbol, price: 123.45 }))
 
 const logging: ChatMiddleware = {
   name: 'logging',
@@ -347,16 +389,22 @@ const configTransform: ChatMiddleware = {
   },
 }
 
-const stream = chat({
-  adapter: openaiText('gpt-5.2'),
-  messages,
-  tools: [weatherTool, stockTool],
-  middleware: [
-    logging, // Runs first
-    configTransform, // Transforms config second
-    toolCacheMiddleware({ ttl: 60_000 }), // Caches tool results third
-  ],
-})
+export async function POST(request: Request) {
+  const { messages } = await request.json()
+
+  const stream = chat({
+    adapter: openaiText('gpt-5.5'),
+    messages,
+    tools: [weatherTool, stockTool],
+    middleware: [
+      logging, // Runs first
+      configTransform, // Transforms config second
+      toolCacheMiddleware({ ttl: 60_000 }), // Caches tool results third
+    ],
+  })
+
+  return toServerSentEventsResponse(stream)
+}
 ```
 
 **Composition rules by hook:**
@@ -378,7 +426,21 @@ Not a built-in. Cap fan-out with `onBeforeToolCall` skip + `onShouldContinue`.
 See `docs/chat/agentic-cycle.md` ("Tool-call budgets").
 
 ```typescript
-import { chat, maxIterations, type ChatMiddleware } from '@tanstack/ai'
+import {
+  chat,
+  maxIterations,
+  toolDefinition,
+  toServerSentEventsResponse,
+  type ChatMiddleware,
+} from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
+import { z } from 'zod'
+
+const weatherTool = toolDefinition({
+  name: 'getWeather',
+  description: 'Get the current weather for a city',
+  inputSchema: z.object({ city: z.string() }),
+}).server(async ({ city }) => ({ city, tempC: 21 }))
 
 function toolCallBudget(opts: {
   max?: number
@@ -409,13 +471,19 @@ function toolCallBudget(opts: {
   }
 }
 
-chat({
-  adapter,
-  messages,
-  tools: [weatherTool],
-  agentLoopStrategy: maxIterations(20),
-  middleware: [toolCallBudget({ maxPerTurn: 10, max: 20 })],
-})
+export async function POST(request: Request) {
+  const { messages } = await request.json()
+
+  const stream = chat({
+    adapter: openaiText('gpt-5.5'),
+    messages,
+    tools: [weatherTool],
+    agentLoopStrategy: maxIterations(20),
+    middleware: [toolCallBudget({ maxPerTurn: 10, max: 20 })],
+  })
+
+  return toServerSentEventsResponse(stream)
+}
 ```
 
 ## Built-in: toolCacheMiddleware
@@ -423,21 +491,35 @@ chat({
 Caches tool call results by name + arguments. Import from `@tanstack/ai/middlewares`:
 
 ```typescript
-import { chat } from '@tanstack/ai'
+import { chat, toolDefinition, toServerSentEventsResponse } from '@tanstack/ai'
 import { toolCacheMiddleware } from '@tanstack/ai/middlewares'
+import { openaiText } from '@tanstack/ai-openai'
+import { z } from 'zod'
 
-const stream = chat({
-  adapter,
-  messages,
-  tools: [weatherTool],
-  middleware: [
-    toolCacheMiddleware({
-      ttl: 60_000, // Cache entries expire after 60 seconds
-      maxSize: 50, // Max 50 entries (LRU eviction)
-      toolNames: ['getWeather'], // Only cache specific tools
-    }),
-  ],
-})
+const weatherTool = toolDefinition({
+  name: 'getWeather',
+  description: 'Get the current weather for a city',
+  inputSchema: z.object({ city: z.string() }),
+}).server(async ({ city }) => ({ city, tempC: 21 }))
+
+export async function POST(request: Request) {
+  const { messages } = await request.json()
+
+  const stream = chat({
+    adapter: openaiText('gpt-5.5'),
+    messages,
+    tools: [weatherTool],
+    middleware: [
+      toolCacheMiddleware({
+        ttl: 60_000, // Cache entries expire after 60 seconds
+        maxSize: 50, // Max 50 entries (LRU eviction)
+        toolNames: ['getWeather'], // Only cache specific tools
+      }),
+    ],
+  })
+
+  return toServerSentEventsResponse(stream)
+}
 ```
 
 Options: `maxSize` (default 100), `ttl` (default Infinity), `toolNames` (default all),
@@ -550,7 +632,12 @@ implement, and what `@tanstack/ai-sandbox`'s run driver resolves per run — its
 `snapshot()` method alongside `append`, `read`, and `close`:
 
 ```ts
-snapshot: () => Promise<Array<{ offset: TOffset; chunk: StreamChunk }>>
+import type { StreamChunk } from '@tanstack/ai'
+
+// Excerpt of the `StreamDurability` interface exported by '@tanstack/ai'
+interface StreamDurability<TOffset extends string = string> {
+  snapshot: () => Promise<Array<{ offset: TOffset; chunk: StreamChunk }>>
+}
 ```
 
 It returns everything stored for a run right now, in append order, then
@@ -695,11 +782,15 @@ Source: docs/sandbox/observability.md
 ### a. MEDIUM: Trying to modify StreamChunks in middleware
 
 ```typescript
+import type { ChatMiddleware } from '@tanstack/ai'
+
 // WRONG -- mutating the chunk object directly
 const broken: ChatMiddleware = {
   name: 'broken',
   onChunk: (ctx, chunk) => {
-    chunk.delta = 'modified' // Mutation does nothing; chunk is not modified in-place
+    if (chunk.type === 'TEXT_MESSAGE_CONTENT') {
+      chunk.delta = 'modified' // Mutation does nothing; chunk is not modified in-place
+    }
   },
 }
 
@@ -736,6 +827,9 @@ middleware had decided to reject. A throw from either fails the whole stream. Th
 is where an unhandled error actually costs you a response:
 
 ```typescript
+import type { ChatMiddleware } from '@tanstack/ai'
+import { logChunk, requireEnv } from './logging'
+
 // WRONG -- an unhandled error in onChunk kills the entire streaming response
 const fragile: ChatMiddleware = {
   name: 'fragile-chunk-logger',
@@ -745,7 +839,12 @@ const fragile: ChatMiddleware = {
   },
   onConfig: (ctx, config) => {
     // Same for a config transform that reads an env var that is not set
-    return { model: requireEnv('MODEL_OVERRIDE') }
+    return {
+      modelOptions: {
+        ...config.modelOptions,
+        temperature: Number(requireEnv('TEMPERATURE')),
+      },
+    }
   },
 }
 
@@ -761,9 +860,15 @@ const resilient: ChatMiddleware = {
     // Return void to pass through
   },
   onConfig: (ctx, config) => {
-    const override = process.env.MODEL_OVERRIDE
+    const temperature = process.env.TEMPERATURE
     // Decide, do not throw: no override means no transform.
-    return override === undefined ? undefined : { model: override }
+    if (temperature === undefined) return undefined
+    return {
+      modelOptions: {
+        ...config.modelOptions,
+        temperature: Number(temperature),
+      },
+    }
   },
   onFinish: (ctx, info) => {
     // Already guarded by core — but prefer ctx.defer() anyway, so a slow

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

@@ -139,7 +139,7 @@ const company = await chat({
 
 // Full type safety on nested properties
 console.log(company.headquarters.city)
-console.log(company.employees[0].role)
+console.log(company.employees[0]?.role)
 console.log(company.financials?.revenue)
 ```
 
@@ -147,7 +147,7 @@ console.log(company.financials?.revenue)
 
 Pass `stream: true` alongside `outputSchema` to get an async iterable of standard streaming chunks plus a completed typed 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
+```typescript group=person-stream
 import { chat } from '@tanstack/ai'
 import { openaiText } from '@tanstack/ai-openai'
 import { z } from 'zod'
@@ -316,7 +316,7 @@ function RecipeBuilder() {
             .filter((p) => p.type === 'text')
             .map((p) => p.content)
             .join('')
-          return <UserBubble key={m.id} text={text} />
+          return <p key={m.id}>{text}</p>
         }
         if (m.role === 'assistant') {
           // `data` is `Recipe` because the schema generic flows from
@@ -338,8 +338,8 @@ function RecipeBuilder() {
 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>
+  const recipe = part.data ?? part.partial
+  return <h3>{recipe?.title ?? 'Plating up…'}</h3>
 }
 ```
 
@@ -398,12 +398,19 @@ const ReportSchema = z.object({
   oneLiner: z.string(),
 })
 
-const { final } = useChat({
-  connection: fetchServerSentEvents('/api/repo-report'),
-  outputSchema: ReportSchema,
-})
+function RepoReport() {
+  const { final, sendMessage } = useChat({
+    connection: fetchServerSentEvents('/api/repo-report'),
+    outputSchema: ReportSchema,
+  })
 
-final?.name
+  return (
+    <div>
+      <button onClick={() => sendMessage('Describe this repo')}>Report</button>
+      {final && <h2>{final.name}</h2>}
+    </div>
+  )
+}
 ```
 
 - Claude Code: `--json-schema`. Codex: `--output-schema`. OpenCode, Grok Build, and `acpCompatible`: prompt-and-parse.
@@ -419,28 +426,51 @@ final?.name
 
 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
-  // ...
+```tsx group=recipe-renderer
+import { useChat, fetchServerSentEvents } from '@tanstack/ai-react'
+import { z } from 'zod'
+import { ReasoningView, ToolCallView, RecipeCard } from './views'
+
+const RecipeSchema = z.object({
+  title: z.string(),
+  steps: z.array(z.string()),
 })
+
+function useRecipeChat() {
+  return useChat({
+    connection: fetchServerSentEvents('/api/recipes'),
+    outputSchema: RecipeSchema,
+  })
+}
+
+function ObsoleteRenderer() {
+  const { messages } = useRecipeChat()
+  const last = messages.at(-1)
+  // OBSOLETE — this guard was needed only because JSON used to land in a TextPart
+  return last?.parts.map((part, i) => {
+    if (part.type === 'text') return null // ❌ hides the structured JSON
+    return <pre key={i}>{JSON.stringify(part)}</pre>
+  })
+}
 ```
 
 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
-})
+```tsx group=recipe-renderer
+function RecipeRenderer() {
+  const { messages } = useRecipeChat()
+  const last = messages.at(-1)
+  // CORRECT — find the structured-output part directly; let actual TextParts render
+  return 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.
@@ -456,18 +486,24 @@ Source: PR #577 — structured-output became a typed UIMessage part.
 
 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 each structured-output part
-{messages.map((m) =>
-  m.role === 'assistant'
-    ? m.parts.find((p) => p.type === 'structured-output')
-      ? <RecipeCard key={m.id} part={...} />
-      : null
-    : null
-)}
+```tsx group=recipe-renderer
+function RecipeHistory() {
+  const { messages, final } = useRecipeChat()
+
+  return (
+    <>
+      {/* WRONG — `final` only reflects the latest turn; earlier recipes vanish from this view */}
+      {final && <h3>{final.title}</h3>}
+
+      {/* CORRECT for history — walk messages, render each structured-output part */}
+      {messages.map((m) => {
+        if (m.role !== 'assistant') return null
+        const part = m.parts.find((p) => p.type === 'structured-output')
+        return part ? <RecipeCard key={m.id} part={part} /> : null
+      })}
+    </>
+  )
+}
 ```
 
 Source: PR #577 — partial/final derive from the most recent structured-output part after the latest user message.
@@ -476,7 +512,7 @@ Source: PR #577 — partial/final derive from the most recent structured-output
 
 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. Read the completed typed object from the terminal `structured-output.complete` event. Standard Schema validation remains the consumer's responsibility.
 
-```typescript
+```typescript group=person-stream
 // WRONG -- partial JSON, throws SyntaxError mid-stream, no schema validation
 for await (const chunk of stream) {
   if (chunk.type === 'TEXT_MESSAGE_CONTENT') {
@@ -500,8 +536,9 @@ Source: maintainer interview
 
 The adapter already handles provider differences (OpenAI uses `response_format`, Anthropic uses tool-based extraction, Gemini uses `responseSchema`). Never configure this yourself.
 
-```typescript
+```typescript ignore
 // WRONG -- do not set provider-specific response format
+// (this does not compile: modelOptions has no response-format field)
 chat({
   adapter,
   messages,
@@ -509,11 +546,17 @@ chat({
     responseFormat: { type: 'json_schema', json_schema: mySchema },
   },
 })
+```
 
+```typescript
 // CORRECT -- just pass outputSchema, the adapter handles the rest
-chat({
-  adapter,
-  messages,
+import { chat } from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
+import { z } from 'zod'
+
+const person = await chat({
+  adapter: openaiText('gpt-5.2'),
+  messages: [{ role: 'user', content: 'John Doe, 30' }],
   outputSchema: z.object({ name: z.string(), age: z.number() }),
 })
 ```
@@ -529,8 +572,15 @@ of using the schema validation library already in the project (Zod, ArkType,
 Valibot). Always check what the project uses and match it.
 
 ```typescript
-// WRONG -- raw schema object, no schema-library type inference
-chat({
+import { chat } from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
+import { z } from 'zod'
+
+const adapter = openaiText('gpt-5.2')
+const messages = [{ role: 'user' as const, content: 'John Doe, 30' }]
+
+// WRONG -- raw schema object, no schema-library type inference (result is unknown)
+const untyped = await chat({
   adapter,
   messages,
   outputSchema: {
@@ -545,9 +595,7 @@ chat({
 })
 
 // CORRECT -- use the project's schema library (e.g. Zod)
-import { z } from 'zod'
-
-chat({
+const person = await chat({
   adapter,
   messages,
   outputSchema: z.object({
@@ -555,6 +603,7 @@ chat({
     age: z.number(),
   }),
 })
+person.name // string
 ```
 
 Using the project's schema library gives you TypeScript type inference and