@tanstack/ai 0.52.3 → 0.54.0

package/skills/ai-core/custom-backend-integration/SKILL.md

@@ -22,8 +22,9 @@ This skill builds on ai-core and ai-core/chat-experience. Read them first.
 
 Connect `useChat` to a custom SSE backend with auth headers:
 
-```typescript
+```tsx
 import { useChat, fetchServerSentEvents } from '@tanstack/ai-react'
+import { token } from './auth'
 
 function Chat() {
   const { messages, sendMessage, isLoading } = useChat({
@@ -69,6 +70,7 @@ framing. This is the recommended default.
 
 ```typescript
 import { useChat, fetchServerSentEvents } from '@tanstack/ai-react'
+import { token, tenantId } from './auth'
 
 const { messages, sendMessage } = useChat({
   connection: fetchServerSentEvents('https://my-api.com/chat', {
@@ -85,6 +87,7 @@ const { messages, sendMessage } = useChat({
 
 ```typescript
 import { useChat, fetchServerSentEvents } from '@tanstack/ai-react'
+import { sessionId, getAccessToken } from './auth'
 
 const { messages, sendMessage } = useChat({
   connection: fetchServerSentEvents(
@@ -95,7 +98,7 @@ const { messages, sendMessage } = useChat({
       },
       body: {
         provider: 'openai',
-        model: 'gpt-4o',
+        model: 'gpt-5.5',
       },
     }),
   ),
@@ -110,6 +113,10 @@ The `body` field in options is merged into the POST request body alongside
 ```typescript
 import { useChat, fetchServerSentEvents } from '@tanstack/ai-react'
 
+// Same signature as globalThis.fetch — wrap it however you need.
+const myCustomFetch: typeof fetch = (input, init) =>
+  fetch(input, { ...init, credentials: 'include' })
+
 const { messages, sendMessage } = useChat({
   connection: fetchServerSentEvents('/api/chat', {
     fetchClient: myCustomFetch,
@@ -124,6 +131,7 @@ instead of SSE. Each line is one JSON-encoded `StreamChunk` followed by `\n`.
 
 ```typescript
 import { useChat, fetchHttpStream } from '@tanstack/ai-react'
+import { token } from './auth'
 
 const { messages, sendMessage } = useChat({
   connection: fetchHttpStream('https://my-api.com/chat', {
@@ -143,6 +151,7 @@ JSON object per line.
 
 ```typescript
 import { useChat, fetchHttpStream } from '@tanstack/ai-react'
+import { region, refreshToken } from './auth'
 
 const { messages, sendMessage } = useChat({
   connection: fetchHttpStream(
@@ -168,15 +177,11 @@ This is the simpler model and covers most HTTP-based protocols.
 
 ```typescript
 import { useChat } from '@tanstack/ai-react'
-import type { ConnectionAdapter } from '@tanstack/ai-react'
-import type { StreamChunk, UIMessage } from '@tanstack/ai'
-
-const websocketAdapter: ConnectionAdapter = {
-  async *connect(
-    messages: Array<UIMessage>,
-    data?: Record<string, any>,
-    abortSignal?: AbortSignal,
-  ): AsyncGenerator<StreamChunk> {
+import type { ConnectConnectionAdapter } from '@tanstack/ai-react'
+import type { StreamChunk } from '@tanstack/ai'
+
+const websocketAdapter: ConnectConnectionAdapter = {
+  async *connect(messages, data, abortSignal) {
     const ws = new WebSocket('wss://my-api.com/chat')
 
     // Wait for connection
@@ -243,25 +248,51 @@ returns an `AsyncIterable<StreamChunk>` that stays open, and `send` dispatches
 messages through it.
 
 ```typescript
-import type { StreamChunk, UIMessage } from '@tanstack/ai'
-
-// SubscribeConnectionAdapter is exported from @tanstack/ai-client
-// (not re-exported by framework packages -- use ConnectionAdapter
-//  union type from @tanstack/ai-react for typing)
-const pushAdapter = {
-  subscribe(abortSignal?: AbortSignal): AsyncIterable<StreamChunk> {
-    // Return a long-lived async iterable that yields chunks
-    // whenever the server pushes them
-    return createPersistentStream(abortSignal)
+import { useChat } from '@tanstack/ai-react'
+import type { SubscribeConnectionAdapter } from '@tanstack/ai-react'
+import type { StreamChunk } from '@tanstack/ai'
+
+// One socket for the lifetime of the client; every run's chunks arrive on it.
+const ws = new WebSocket('wss://my-api.com/chat')
+const ready = new Promise<void>((resolve) => {
+  ws.addEventListener('open', () => resolve(), { once: true })
+})
+
+const pushAdapter: SubscribeConnectionAdapter = {
+  async *subscribe(abortSignal) {
+    // Long-lived async iterable: yields chunks whenever the server pushes
+    // them, until the socket closes or the signal aborts
+    const queue: Array<StreamChunk> = []
+    let wake: (() => void) | null = null
+    let closed = false
+
+    ws.addEventListener('message', (event) => {
+      const chunk: StreamChunk = JSON.parse(event.data)
+      queue.push(chunk)
+      wake?.()
+    })
+    ws.addEventListener('close', () => {
+      closed = true
+      wake?.()
+    })
+    abortSignal?.addEventListener('abort', () => ws.close())
+
+    while (!closed || queue.length > 0) {
+      const next = queue.shift()
+      if (next !== undefined) {
+        yield next
+        continue
+      }
+      await new Promise<void>((r) => {
+        wake = r
+      })
+    }
   },
 
-  async send(
-    messages: Array<UIMessage>,
-    data?: Record<string, any>,
-    abortSignal?: AbortSignal,
-  ): Promise<void> {
+  async send(messages, data) {
     // Dispatch messages; chunks arrive through subscribe()
-    await persistentConnection.send(JSON.stringify({ messages, ...data }))
+    await ready
+    ws.send(JSON.stringify({ messages, ...data }))
   },
 }
 
@@ -279,12 +310,9 @@ a shorthand for creating a `ConnectConnectionAdapter` from an async generator:
 
 ```typescript
 import { useChat, stream } from '@tanstack/ai-react'
-import type { StreamChunk, UIMessage } from '@tanstack/ai'
+import type { StreamChunk } from '@tanstack/ai'
 
-const directAdapter = stream(async function* (
-  messages: Array<UIMessage>,
-  data?: Record<string, any>,
-): AsyncGenerator<StreamChunk> {
+const directAdapter = stream(async function* (messages, data) {
   const response = await fetch('https://my-api.com/chat', {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
@@ -305,7 +333,8 @@ const directAdapter = stream(async function* (
 
     for (const line of lines) {
       if (line.trim()) {
-        yield JSON.parse(line) as StreamChunk
+        const chunk: StreamChunk = JSON.parse(line)
+        yield chunk
       }
     }
   }
@@ -324,35 +353,43 @@ The `ConnectionAdapter` interface has two mutually exclusive modes. Providing
 both throws at runtime.
 
 ```typescript
-// WRONG -- throws "Connection adapter must provide either connect or both
-// subscribe and send, not both modes"
-const adapter = {
+import type {
+  ConnectConnectionAdapter,
+  ConnectionAdapter,
+  SubscribeConnectionAdapter,
+} from '@tanstack/ai-react'
+import { channel } from './channel'
+
+// WRONG -- type-checks (ConnectionAdapter is a union) but throws at runtime:
+// "Connection adapter must provide either connect or both subscribe and
+// send, not both modes"
+const adapter: ConnectionAdapter = {
   async *connect(messages) {
     /* ... */
   },
   subscribe(signal) {
-    /* ... */
+    return channel.chunks(signal)
   },
   async send(messages) {
-    /* ... */
+    await channel.send(messages)
   },
 }
 
 // CORRECT -- pick one mode
 // Option A: ConnectConnectionAdapter (pull-based)
-const pullAdapter = {
+const pullAdapter: ConnectConnectionAdapter = {
   async *connect(messages, data, abortSignal) {
     // ... yield StreamChunks
   },
 }
 
 // Option B: SubscribeConnectionAdapter (push-based)
-const pushAdapter = {
+const pushAdapter: SubscribeConnectionAdapter = {
   subscribe(abortSignal) {
-    return longLivedAsyncIterable
+    return channel.chunks(abortSignal)
   },
   async send(messages, data, abortSignal) {
-    await connection.dispatch({ messages, ...data })
+    await channel.send({ messages, ...data }, abortSignal)
   },
 }
 ```
@@ -388,15 +425,11 @@ streaming, implement retry logic in your connection adapter:
 
 ```typescript
 import { useChat } from '@tanstack/ai-react'
-import type { ConnectionAdapter } from '@tanstack/ai-react'
-import type { StreamChunk, UIMessage } from '@tanstack/ai'
-
-const resilientAdapter: ConnectionAdapter = {
-  async *connect(
-    messages: Array<UIMessage>,
-    data?: Record<string, any>,
-    abortSignal?: AbortSignal,
-  ): AsyncGenerator<StreamChunk> {
+import type { ConnectConnectionAdapter } from '@tanstack/ai-react'
+import type { StreamChunk } from '@tanstack/ai'
+
+const resilientAdapter: ConnectConnectionAdapter = {
+  async *connect(messages, data, abortSignal) {
     const maxRetries = 3
     let attempt = 0
 
@@ -427,7 +460,8 @@ const resilientAdapter: ConnectionAdapter = {
 
           for (const line of lines) {
             if (line.trim()) {
-              yield JSON.parse(line) as StreamChunk
+              const chunk: StreamChunk = JSON.parse(line)
+              yield chunk
             }
           }
         }

package/skills/ai-core/debug-logging/SKILL.md

@@ -30,8 +30,10 @@ printed, or pipe logs into a custom logger (pino, winston, etc.). The same
 import { chat } from '@tanstack/ai'
 import { openaiText } from '@tanstack/ai-openai'
 
+const messages = [{ role: 'user' as const, content: 'Hello' }]
+
 const stream = chat({
-  adapter: openaiText('gpt-5.2'),
+  adapter: openaiText('gpt-5.5'),
   messages,
   debug: true, // all categories on, prints to console
 })
@@ -49,8 +51,13 @@ Each log line is prefixed with an emoji and `[tanstack-ai:<category>]`:
 ## Turn it off
 
 ```typescript
+import { chat } from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
+
+const messages = [{ role: 'user' as const, content: 'Hello' }]
+
 chat({
-  adapter: openaiText('gpt-5.2'),
+  adapter: openaiText('gpt-5.5'),
   messages,
   debug: false, // silence everything, including errors
 })
@@ -63,6 +70,9 @@ Omitting `debug` is **not** the same as `debug: false`. When omitted, the
 ## `DebugOption` — the accepted shapes
 
 ```typescript
+import type { Logger } from '@tanstack/ai'
+
+// As exported by '@tanstack/ai'
 type DebugOption = boolean | DebugConfig
 
 interface DebugConfig {
@@ -95,8 +105,13 @@ Pass a `DebugConfig` object. Unspecified categories default to `true`, so it's
 easiest to toggle by setting specific flags to `false`:
 
 ```typescript
+import { chat } from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
+
+const messages = [{ role: 'user' as const, content: 'Hello' }]
+
 chat({
-  adapter: openaiText('gpt-5.2'),
+  adapter: openaiText('gpt-5.5'),
   messages,
   debug: { middleware: false }, // everything except middleware
 })
@@ -105,8 +120,13 @@ chat({
 To print only a specific set, set the rest to `false` explicitly:
 
 ```typescript
+import { chat } from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
+
+const messages = [{ role: 'user' as const, content: 'Hello' }]
+
 chat({
-  adapter: openaiText('gpt-5.2'),
+  adapter: openaiText('gpt-5.5'),
   messages,
   debug: {
     provider: true,
@@ -124,7 +144,8 @@ chat({
 ## Pipe into your own logger
 
 ```typescript
-import type { Logger } from '@tanstack/ai'
+import { chat, type Logger } from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
 import pino from 'pino'
 
 const pinoLogger = pino()
@@ -135,8 +156,10 @@ const logger: Logger = {
   error: (msg, meta) => pinoLogger.error(meta, msg),
 }
 
+const messages = [{ role: 'user' as const, content: 'Hello' }]
+
 chat({
-  adapter: openaiText('gpt-5.2'),
+  adapter: openaiText('gpt-5.5'),
   messages,
   debug: { logger }, // all categories on, piped to pino
 })
@@ -170,11 +193,48 @@ concepts don't exist in their pipelines.
 Same `debug` option everywhere:
 
 ```typescript
-summarize({ adapter, text, debug: true })
-generateImage({ adapter, prompt: 'a cat', debug: { logger } })
-generateSpeech({ adapter, text, debug: { request: true } })
-generateTranscription({ adapter, audio, debug: false })
-generateVideo({ adapter, prompt: 'a wave', debug: { output: true } })
+import {
+  summarize,
+  generateImage,
+  generateSpeech,
+  generateTranscription,
+  generateVideo,
+} from '@tanstack/ai'
+import {
+  openaiSummarize,
+  openaiImage,
+  openaiSpeech,
+  openaiTranscription,
+  openaiVideo,
+} from '@tanstack/ai-openai'
+import { logger } from './logger'
+import { audio } from './recording'
+
+summarize({
+  adapter: openaiSummarize('gpt-5.5'),
+  text: 'Long article…',
+  debug: true,
+})
+generateImage({
+  adapter: openaiImage('gpt-image-2'),
+  prompt: 'a cat',
+  debug: { logger },
+})
+generateSpeech({
+  adapter: openaiSpeech('tts-1-hd'),
+  text: 'Hello',
+  debug: { request: true },
+})
+generateTranscription({
+  adapter: openaiTranscription('gpt-4o-transcribe'),
+  audio,
+  debug: false,
+})
+generateVideo({
+  adapter: openaiVideo('sora-2'),
+  prompt: 'a wave',
+  debug: { output: true },
+})
 ```
 
 Realtime session adapters in provider packages (e.g. `openaiRealtime`,
@@ -187,6 +247,12 @@ categories don't apply.
 ### a. HIGH: Treating omitted `debug` as silent
 
 ```typescript
+import { chat } from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
+
+const adapter = openaiText('gpt-5.5')
+const messages = [{ role: 'user' as const, content: 'Hello' }]
+
 // WRONG — expecting this to be completely silent
 chat({ adapter, messages })
 // Errors still print via [tanstack-ai:errors] ... on failure.
@@ -203,6 +269,12 @@ Source: docs/advanced/debug-logging.md
 ### b. MEDIUM: Reaching for middleware when `debug` would do
 
 ```typescript
+import { chat, type ChatMiddleware } from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
+
+const adapter = openaiText('gpt-5.5')
+const messages = [{ role: 'user' as const, content: 'Hello' }]
+
 // WRONG — writing logging middleware to see chunks flow
 const chunkLogger: ChatMiddleware = {
   name: 'chunk-logger',
@@ -234,22 +306,32 @@ prefer implementations that don't throw — silenced exceptions are harder to
 debug than loud ones.
 
 ```typescript
+import type { Logger } from '@tanstack/ai'
+
 // WRONG — a logger that can throw on serialization
 const fragile: Logger = {
   debug: (msg, meta) => console.debug(msg, JSON.stringify(meta)), // cyclic meta → throws
-  /* ... */
+  info: (msg, meta) => console.info(msg, JSON.stringify(meta)),
+  warn: (msg, meta) => console.warn(msg, JSON.stringify(meta)),
+  error: (msg, meta) => console.error(msg, JSON.stringify(meta)),
 }
 
 // CORRECT — guard serialization in the logger itself
-const safe: Logger = {
-  debug: (msg, meta) => {
+const guarded =
+  (log: (...args: Array<unknown>) => void): Logger['debug'] =>
+  (msg, meta) => {
     try {
-      console.debug(msg, meta)
+      log(msg, JSON.stringify(meta))
     } catch {
-      console.debug(msg)
+      log(msg) // fall back to the bare message rather than throw
     }
-  },
-  /* ... */
+  }
+
+const safe: Logger = {
+  debug: guarded(console.debug),
+  info: guarded(console.info),
+  warn: guarded(console.warn),
+  error: guarded(console.error),
 }
 ```
 

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

@@ -35,20 +35,40 @@ per-thread (or other) lock yourself when multi-writer races matter.
 ## Wire locks
 
 ```ts
+import { chat } from '@tanstack/ai'
 import { withLocks, InMemoryLockStore } from '@tanstack/ai/locks'
+import { openaiText } from '@tanstack/ai-openai'
 
-middleware: [
-  withLocks(new InMemoryLockStore()), // single process
-]
+const messages = [{ role: 'user' as const, content: 'Hello' }]
+
+chat({
+  adapter: openaiText('gpt-5.6'),
+  messages,
+  middleware: [
+    withLocks(new InMemoryLockStore()), // single process
+  ],
+})
 ```
 
 Alongside persistence — optional, locks do not require it:
 
 ```ts
+import { chat } from '@tanstack/ai'
 import { withLocks, InMemoryLockStore } from '@tanstack/ai/locks'
-import { withPersistence } from '@tanstack/ai-persistence'
-
-middleware: [withPersistence(persistence), withLocks(new InMemoryLockStore())]
+import { openaiText } from '@tanstack/ai-openai'
+import { memoryPersistence, withPersistence } from '@tanstack/ai-persistence'
+
+const persistence = memoryPersistence()
+const messages = [{ role: 'user' as const, content: 'Hello' }]
+
+chat({
+  adapter: openaiText('gpt-5.6'),
+  messages,
+  middleware: [
+    withPersistence(persistence),
+    withLocks(new InMemoryLockStore()),
+  ],
+})
 ```
 
 `withLocks` provides `LocksCapability` for downstream middleware (e.g.
@@ -73,7 +93,9 @@ annotation), then hand it to `withLocks`. Acquire the key, run `fn`, release whe
 `fn` settles:
 
 ```ts
+import { chat } from '@tanstack/ai'
 import { defineLock, withLocks } from '@tanstack/ai/locks'
+import { openaiText } from '@tanstack/ai-openai'
 import { acquire } from './my-lock-backend'
 
 const locks = defineLock({
@@ -87,7 +109,13 @@ const locks = defineLock({
   },
 })
 
-middleware: [withLocks(locks)]
+const messages = [{ role: 'user' as const, content: 'Hello' }]
+
+chat({
+  adapter: openaiText('gpt-5.6'),
+  messages,
+  middleware: [withLocks(locks)],
+})
 ```
 
 ## Lease semantics