Skip to content
Source
Sign inSign up
TanStack/ai
Open History to see the last commit

domain_map.yaml

845 lines44.1 KB

1# domain_map.yaml
2# Generated by skill-domain-discovery
3# Library: @tanstack/ai
4# Version: 0.10.0
5# Date: 2026-04-08
6# Status: reviewed
7​
8library:
9 name: '@tanstack/ai'
10 version: '0.10.0'
11 repository: 'https://github.com/TanStack/ai'
12 description: 'Type-safe, provider-agnostic AI SDK for building chat, tool calling, media generation, and code execution features across React, Solid, Vue, Svelte, and Preact.'
13 primary_framework: 'framework-agnostic'
14​
15domains:
16 - name: 'Building chat experiences'
17 slug: 'chat-experiences'
18 description: 'End-to-end chat implementation — server endpoints, streaming, client hooks, message rendering, thinking content, and multimodal messages.'
19​
20 - name: 'Implementing tool calling'
21 slug: 'tool-system'
22 description: 'Isomorphic tool definitions, server/client execution, approval flows, lazy discovery, and rendering tool results in UI.'
23​
24 - name: 'Generating media content'
25 slug: 'media-generation'
26 description: 'Image, video, text-to-speech, transcription, and summarization using activity-specific adapters and generation hooks.'
27​
28 - name: 'Executing LLM-generated code'
29 slug: 'code-execution'
30 description: 'Code Mode sandbox setup, isolate drivers, skills system, and client-side execution progress display.'
31​
32 - name: 'Configuring adapters and models'
33 slug: 'adapter-management'
34 description: 'Provider adapter selection, per-model type safety, model options, runtime switching, extending adapters with custom models.'
35​
36 - name: 'Transport and protocol'
37 slug: 'transport-protocol'
38 description: 'AG-UI streaming protocol implementation, SSE/HTTP stream formats, and custom backend connections.'
39​
40 - name: 'Extending behavior'
41 slug: 'extensibility'
42 description: 'Middleware hooks for analytics, caching, observability, and cross-cutting concerns on the chat lifecycle.'
43​
44skills:
45 - name: 'Chat Experience'
46 slug: 'chat-experience'
47 domain: 'chat-experiences'
48 description: 'Implement an end-to-end chatbot: server endpoint with streaming response, client-side UI with useChat, message rendering, multimodal content, and thinking/reasoning display.'
49 type: 'core'
50 packages:
51 - '@tanstack/ai'
52 - '@tanstack/ai-client'
53 - '@tanstack/ai-react'
54 - '@tanstack/ai-solid'
55 - '@tanstack/ai-vue'
56 - '@tanstack/ai-svelte'
57 - '@tanstack/ai-preact'
58 covers:
59 - 'chat()'
60 - 'toServerSentEventsResponse()'
61 - 'toServerSentEventsStream()'
62 - 'toHttpResponse()'
63 - 'toHttpStream()'
64 - 'useChat()'
65 - 'ChatClient'
66 - 'fetchServerSentEvents()'
67 - 'fetchHttpStream()'
68 - 'UIMessage'
69 - 'ModelMessage'
70 - 'ContentPart (text, image, audio, video, document)'
71 - 'ThinkingPart'
72 - 'StreamChunk / AG-UI events'
73 - 'convertMessagesToModelMessages()'
74 - 'uiMessageToModelMessages()'
75 - 'modelMessagesToUIMessages()'
76 tasks:
77 - 'Set up a server-side chat endpoint that streams responses'
78 - 'Build a React/Solid/Vue/Svelte chat UI with useChat'
79 - 'Render assistant messages with thinking/reasoning content'
80 - 'Send multimodal content (images, audio, video, documents) in messages'
81 - 'Handle streaming states (loading, error, ready) in the UI'
82 - 'Convert between UIMessage and ModelMessage formats'
83 failure_modes:
84 - mistake: 'Using monolithic openai() instead of openaiText()'
85 mechanism: 'The legacy monolithic adapter (openai(), anthropic()) is deprecated. The new tree-shakeable adapters (openaiText, anthropicText) take the model name as an argument and are the correct API.'
86 wrong_pattern: |
87 import { openai } from '@tanstack/ai-openai'
88 const stream = chat({ adapter: openai(), model: 'gpt-5.2', messages })
89 correct_pattern: |
90 import { openaiText } from '@tanstack/ai-openai'
91 const stream = chat({ adapter: openaiText('gpt-5.2'), messages })
92 source: 'docs/migration/migration.md'
93 priority: 'CRITICAL'
94 status: 'active'
95 version_context: 'Changed in v0.5.0; agents trained on older code will produce the monolithic pattern'
96​
97 - mistake: 'Using toResponseStream instead of toServerSentEventsResponse'
98 mechanism: 'toResponseStream was renamed to toServerSentEventsResponse (returns a Response) or toServerSentEventsStream (returns a ReadableStream). The old name no longer exists.'
99 wrong_pattern: |
100 import { toResponseStream } from '@tanstack/ai'
101 return toResponseStream(stream, { abortController })
102 correct_pattern: |
103 import { toServerSentEventsResponse } from '@tanstack/ai'
104 return toServerSentEventsResponse(stream)
105 source: 'docs/migration/migration.md'
106 priority: 'HIGH'
107 status: 'active'
108 version_context: 'Renamed in v0.5.0'
109​
110 - mistake: 'Passing model as separate parameter to chat()'
111 mechanism: 'Model name is now passed to the adapter factory function, not as a separate parameter to chat(). Passing model to chat() is silently ignored.'
112 wrong_pattern: |
113 const stream = chat({
114 adapter: openaiText(),
115 model: 'gpt-5.2',
116 messages,
117 })
118 correct_pattern: |
119 const stream = chat({
120 adapter: openaiText('gpt-5.2'),
121 messages,
122 })
123 source: 'docs/migration/migration.md'
124 priority: 'HIGH'
125 status: 'active'
126 version_context: 'Changed in v0.5.0'
127​
128 - mistake: 'Nesting temperature/maxTokens in options object'
129 mechanism: 'Common options (temperature, topP, maxTokens) are now flattened at the top level of the chat config, not nested under an options key.'
130 wrong_pattern: |
131 chat({
132 adapter: openaiText('gpt-5.2'),
133 messages,
134 options: { temperature: 0.7, maxTokens: 1000 },
135 })
136 correct_pattern: |
137 chat({
138 adapter: openaiText('gpt-5.2'),
139 messages,
140 temperature: 0.7,
141 maxTokens: 1000,
142 })
143 source: 'docs/migration/migration.md'
144 priority: 'HIGH'
145 status: 'active'
146 version_context: 'Changed in v0.5.0'
147​
148 - mistake: 'Using providerOptions instead of modelOptions'
149 mechanism: 'The providerOptions parameter was renamed to modelOptions. Using the old name is silently ignored — provider-specific options will not be applied.'
150 wrong_pattern: |
151 chat({
152 adapter: openaiText('gpt-5.2'),
153 messages,
154 providerOptions: { responseFormat: { type: 'json_object' } },
155 })
156 correct_pattern: |
157 chat({
158 adapter: openaiText('gpt-5.2'),
159 messages,
160 modelOptions: { responseFormat: { type: 'json_object' } },
161 })
162 source: 'docs/migration/migration.md'
163 priority: 'HIGH'
164 status: 'active'
165 version_context: 'Renamed in v0.5.0'
166​
167 - mistake: 'Not handling RUN_ERROR events in streaming context'
168 mechanism: 'Streaming errors do not throw — they arrive as RUN_ERROR events. If the client does not explicitly subscribe to and handle these events, errors are silently lost and the UI appears to hang.'
169 source: 'docs/chat/streaming.md'
170 priority: 'MEDIUM'
171 status: 'active'
172​
173 - mistake: 'Using Vercel AI SDK patterns (streamText, generateText)'
174 mechanism: 'Agents frequently generate Vercel AI SDK code instead of TanStack AI code. streamText() and generateText() do not exist — the correct function is chat(). This is the most common AI-agent confusion pattern.'
175 wrong_pattern: |
176 import { streamText } from 'ai'
177 import { openai } from '@ai-sdk/openai'
178 const result = streamText({ model: openai('gpt-4o'), messages })
179 correct_pattern: |
180 import { chat } from '@tanstack/ai'
181 import { openaiText } from '@tanstack/ai-openai'
182 const stream = chat({ adapter: openaiText('gpt-5.2'), messages })
183 source: 'maintainer interview'
184 priority: 'CRITICAL'
185 status: 'active'
186 version_context: 'Vercel AI SDK patterns dominate agent training data; agents default to these'
187​
188 - mistake: 'Using Vercel createOpenAI() provider pattern'
189 mechanism: 'Agents generate createOpenAI() or similar Vercel provider factory patterns. TanStack AI uses openaiText(model) adapter factories instead.'
190 wrong_pattern: |
191 import { createOpenAI } from '@ai-sdk/openai'
192 const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY })
193 streamText({ model: openai('gpt-4o'), messages })
194 correct_pattern: |
195 import { openaiText } from '@tanstack/ai-openai'
196 import { chat } from '@tanstack/ai'
197 chat({ adapter: openaiText('gpt-5.2'), messages })
198 source: 'maintainer interview'
199 priority: 'CRITICAL'
200 status: 'active'
201 version_context: 'createOpenAI/createAnthropic patterns from Vercel AI SDK are widespread in training data'
202​
203 - mistake: 'Implementing custom SSE stream instead of using toServerSentEventsResponse'
204 mechanism: 'Agents often write manual SSE formatting (writing "data: " prefixes, handling encoding, setting headers) instead of using the built-in toServerSentEventsResponse() or toServerSentEventsStream() utilities. The manual implementation is error-prone and misses edge cases.'
205 wrong_pattern: |
206 const encoder = new TextEncoder()
207 const stream = new ReadableStream({
208 async start(controller) {
209 for await (const chunk of chatStream) {
210 controller.enqueue(encoder.encode(`data: ${JSON.stringify(chunk)}\n\n`))
211 }
212 controller.close()
213 }
214 })
215 return new Response(stream, { headers: { 'Content-Type': 'text/event-stream' } })
216 correct_pattern: |
217 import { chat, toServerSentEventsResponse } from '@tanstack/ai'
218 const stream = chat({ adapter: openaiText('gpt-5.2'), messages })
219 return toServerSentEventsResponse(stream)
220 source: 'maintainer interview'
221 priority: 'HIGH'
222 status: 'active'
223​
224 - mistake: 'Implementing custom onEnd/onFinish callbacks instead of middleware'
225 mechanism: 'Agents try to add onEnd, onFinish, or onComplete callback options to chat() or useChat(). These do not exist. The correct pattern is to use middleware hooks (onFinish, onUsage, onError) for post-stream lifecycle events.'
226 wrong_pattern: |
227 chat({
228 adapter: openaiText('gpt-5.2'),
229 messages,
230 onEnd: (result) => { trackAnalytics(result) },
231 onFinish: (result) => { saveToDatabase(result) },
232 })
233 correct_pattern: |
234 chat({
235 adapter: openaiText('gpt-5.2'),
236 messages,
237 middleware: [{
238 onFinish: (ctx) => { trackAnalytics(ctx) },
239 onUsage: (ctx) => { saveToDatabase(ctx) },
240 }],
241 })
242 source: 'maintainer interview'
243 priority: 'HIGH'
244 status: 'active'
245 skills: ['chat-experience', 'middleware']
246​
247 - mistake: 'Importing from @tanstack/ai-client instead of framework package'
248 mechanism: 'The core @tanstack/ai-client package is headless and re-exported by framework packages (@tanstack/ai-react, ai-solid, etc.). Agents should import from the framework package so developers dont need to install both. Only import from @tanstack/ai-client for vanilla JS.'
249 wrong_pattern: |
250 import { fetchServerSentEvents } from '@tanstack/ai-client'
251 import { useChat } from '@tanstack/ai-react'
252 correct_pattern: |
253 import { useChat, fetchServerSentEvents } from '@tanstack/ai-react'
254 source: 'maintainer interview'
255 priority: 'HIGH'
256 status: 'active'
257​
258 - name: 'Tool Calling'
259 slug: 'tool-calling'
260 domain: 'tool-system'
261 description: 'Define isomorphic tools with toolDefinition(), implement server and client execution, set up approval flows, use lazy tool discovery, and render tool results in the UI.'
262 type: 'core'
263 packages:
264 - '@tanstack/ai'
265 - '@tanstack/ai-client'
266 - '@tanstack/ai-react'
267 covers:
268 - 'toolDefinition()'
269 - '.server()'
270 - '.client()'
271 - 'clientTools()'
272 - 'needsApproval'
273 - 'addToolApprovalResponse()'
274 - 'lazy: true'
275 - 'ToolCallManager'
276 - 'ToolCallPart / ToolResultPart'
277 - 'createChatClientOptions()'
278 - 'InferChatMessages'
279 tasks:
280 - 'Define a tool with toolDefinition() and Zod schemas'
281 - 'Add server-side tool execution with .server()'
282 - 'Add client-side tool execution with .client()'
283 - 'Build tools that execute on both server and client'
284 - 'Implement tool approval UI for sensitive operations'
285 - 'Use lazy tool discovery to reduce token usage'
286 - 'Render tool call progress and results in chat UI'
287 - 'Pass tool definitions to both server chat() and client useChat()'
288 failure_modes:
289 - mistake: 'Missing @standard-schema/spec causes tool types to be unknown'
290 mechanism: 'Without the @standard-schema/spec package installed, Zod schema inference in toolDefinition() breaks silently — input types become unknown in .server() and .client() callbacks. This is an undocumented peer dependency.'
291 wrong_pattern: |
292 // package.json missing @standard-schema/spec
293 const tool = toolDefinition({
294 name: 'getTodos',
295 inputSchema: z.object({ userId: z.string() }),
296 })
297 // .server() callback input is typed as unknown
298 const serverTool = tool.server(async (input) => { /* input: unknown */ })
299 correct_pattern: |
300 // pnpm add @standard-schema/spec
301 const tool = toolDefinition({
302 name: 'getTodos',
303 inputSchema: z.object({ userId: z.string() }),
304 })
305 // .server() callback input is correctly typed
306 const serverTool = tool.server(async ({ userId }) => { /* userId: string */ })
307 source: 'https://github.com/TanStack/ai/issues/235'
308 priority: 'CRITICAL'
309 status: 'active'
310 version_context: 'Undocumented peer dependency; multiple users hit this independently'
311​
312 - mistake: 'Not passing tool definitions to both server and client'
313 mechanism: 'Server tools need the definition on the server (in chat()), and client tools need the definition on the client (in useChat/clientTools). Forgetting either side causes the tool to not execute or not render.'
314 wrong_pattern: |
315 // Server only — client can't render tool results
316 chat({ adapter, messages, tools: [getProducts] })
317 // Client has no tool definitions
318 useChat({ connection: fetchServerSentEvents('/api/chat') })
319 correct_pattern: |
320 // Server
321 chat({ adapter, messages, tools: [getProducts] })
322 // Client also receives tool definitions for rendering
323 useChat({
324 connection: fetchServerSentEvents('/api/chat'),
325 clientTools: clientTools([getProductsDef.client()]),
326 })
327 source: 'docs/tools/tools.md, maintainer interview'
328 priority: 'HIGH'
329 status: 'active'
330​
331 - mistake: 'Multiple client tools stall in same round'
332 mechanism: 'Race condition in drainPostStreamActions() where nested drain calls steal queued actions, permanently stalling conversations when the LLM calls multiple client tools in a single round.'
333 source: 'https://github.com/TanStack/ai/issues/302'
334 priority: 'HIGH'
335 status: 'active'
336 version_context: 'Known bug; community patch exists but no official fix'
337​
338 - mistake: 'Server tool output missing from UIMessage parts'
339 mechanism: 'Server-executed tools show state "input-complete" with no output field in the UIMessage ToolCallPart, while client tools show state "complete" with output. Code that checks part.output for server tools will get undefined.'
340 source: 'https://github.com/TanStack/ai/issues/176'
341 priority: 'HIGH'
342 status: 'active'
343​
344 - mistake: 'Anthropic adapter passes null tool input, stalling agent loops'
345 mechanism: 'When Anthropic produces an empty tool_use block, JSON.parse("null") returns null instead of {}, failing Zod validation and silently killing the conversation.'
346 source: 'https://github.com/TanStack/ai/issues/265'
347 priority: 'HIGH'
348 status: 'active'
349 skills: ['tool-calling', 'adapter-configuration']
350​
351 - mistake: 'Tool results always stringified, blocking multimodal responses'
352 mechanism: 'JSON.stringify() is applied at three locations in the tool result pipeline, forcing all tool results to strings. This blocks image-returning tools with providers that support multimodal tool responses (e.g., OpenAI Responses API).'
353 source: 'https://github.com/TanStack/ai/issues/363'
354 priority: 'MEDIUM'
355 status: 'active'
356​
357 - name: 'Media Generation'
358 slug: 'media-generation'
359 domain: 'media-generation'
360 description: 'Generate images, video, speech (TTS), and transcriptions using activity-specific adapters and React/framework generation hooks.'
361 type: 'core'
362 packages:
363 - '@tanstack/ai'
364 - '@tanstack/ai-openai'
365 - '@tanstack/ai-gemini'
366 - '@tanstack/ai-fal'
367 - '@tanstack/ai-elevenlabs'
368 - '@tanstack/ai-react'
369 covers:
370 - 'generateImage()'
371 - 'generateVideo()'
372 - 'getVideoJobStatus()'
373 - 'generateSpeech()'
374 - 'generateTranscription()'
375 - 'summarize()'
376 - 'useGenerateImage()'
377 - 'useGenerateSpeech()'
378 - 'useTranscription()'
379 - 'useSummarize()'
380 - 'useGenerateVideo()'
381 - 'useGeneration()'
382 - 'openaiImage / geminiImage / openaiSpeech / openaiTranscription / openaiVideo'
383 tasks:
384 - 'Generate images with OpenAI DALL-E/GPT-Image or Gemini Imagen'
385 - 'Generate video with OpenAI Sora (async polling pattern)'
386 - 'Implement text-to-speech with OpenAI TTS or ElevenLabs'
387 - 'Transcribe audio with OpenAI Whisper'
388 - 'Summarize text'
389 - 'Use React generation hooks for streaming progress'
390 - 'Connect generation hooks to TanStack Start server functions'
391 subsystems:
392 - name: 'Image generation'
393 package: '@tanstack/ai-openai, @tanstack/ai-gemini'
394 config_surface: 'Size formats differ (OpenAI WIDTHxHEIGHT vs Gemini aspectRatio), numberOfImages, quality levels'
395 - name: 'Video generation'
396 package: '@tanstack/ai-openai'
397 config_surface: 'Async job/polling pattern, pollingInterval, maxDuration, size, duration (4/8/12s)'
398 - name: 'Text-to-speech'
399 package: '@tanstack/ai-openai, @tanstack/ai-gemini, @tanstack/ai-elevenlabs'
400 config_surface: 'Voice selection, output format (mp3/opus/aac/flac/wav/pcm), streaming audio'
401 - name: 'Transcription'
402 package: '@tanstack/ai-openai'
403 config_surface: 'Input File/base64/data URL, language code, response format (json/text/srt/vtt), word-level timestamps'
404 failure_modes:
405 - mistake: 'Using removed embedding() function'
406 mechanism: 'Embeddings support was removed from TanStack AI. Use your vector database built-in embedding support or call the provider SDK directly.'
407 wrong_pattern: |
408 import { embedding } from '@tanstack/ai'
409 import { openaiEmbed } from '@tanstack/ai-openai'
410 const result = await embedding({ adapter: openaiEmbed(), model: 'text-embedding-3-small', input: 'Hello' })
411 correct_pattern: |
412 import OpenAI from 'openai'
413 const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY })
414 const result = await openai.embeddings.create({ model: 'text-embedding-3-small', input: 'Hello' })
415 source: 'docs/migration/migration.md'
416 priority: 'HIGH'
417 status: 'removed'
418 version_context: 'Removed in v0.5.0; agents trained on pre-removal code will still generate this'
419​
420 - mistake: 'Not downloading OpenAI image URLs before they expire'
421 mechanism: 'OpenAI image generation URLs expire after 1 hour. If the URL is stored or displayed without downloading the image data, it will break silently after expiration.'
422 source: 'docs/media/image-generation.md'
423 priority: 'MEDIUM'
424 status: 'active'
425​
426 - mistake: 'Using stream:true for activities that do not support streaming'
427 mechanism: 'Not all generation activities support streaming (e.g., some models require polling for video). Using stream:true on unsupported activities may hang or return no progress events.'
428 source: 'docs/media/generations.md'
429 priority: 'MEDIUM'
430 status: 'active'
431​
432 - mistake: 'Forgetting toServerSentEventsResponse when using TanStack Start server functions'
433 mechanism: 'When using generation hooks with TanStack Start server functions, the stream must be wrapped with toServerSentEventsResponse(). Without it, the server function returns raw data instead of a streamable SSE response. This is the key integration step that cannot be skipped.'
434 source: 'maintainer interview'
435 priority: 'HIGH'
436 status: 'active'
437​
438 - name: 'Code Mode'
439 slug: 'code-mode'
440 domain: 'code-execution'
441 description: 'Set up LLM-generated TypeScript execution in sandboxed environments with isolate drivers, skills system, and client-side progress display.'
442 type: 'core'
443 packages:
444 - '@tanstack/ai-code-mode'
445 - '@tanstack/ai-code-mode-skills'
446 - '@tanstack/ai-isolate-node'
447 - '@tanstack/ai-isolate-quickjs'
448 - '@tanstack/ai-isolate-cloudflare'
449 covers:
450 - 'createCodeModeTool()'
451 - 'createCodeModeSystemPrompt()'
452 - 'codeModeWithSkills()'
453 - 'createNodeIsolateDriver()'
454 - 'createQuickJSIsolateDriver()'
455 - 'createCloudflareIsolateDriver()'
456 - 'Trust strategies (ask, auto, none)'
457 - 'SkillStorage (FileSystem, LocalStorage, InMemory, Mongo)'
458 - 'Custom events: code_mode:execution_started, code_mode:console, code_mode:external_call'
459 tasks:
460 - 'Set up Code Mode with an isolate driver'
461 - 'Add tools that are callable from within generated code'
462 - 'Implement persistent skill storage for reusable code patterns'
463 - 'Display code execution progress in the client UI'
464 - 'Choose between Node, QuickJS, and Cloudflare isolate drivers'
465 subsystems:
466 - name: 'Node.js isolated-vm driver'
467 package: '@tanstack/ai-isolate-node'
468 config_surface: 'memoryLimit (128MB default), timeout (30s), skipProbe, requires native module compilation'
469 - name: 'QuickJS WASM driver'
470 package: '@tanstack/ai-isolate-quickjs'
471 config_surface: 'memoryLimit (128MB), timeout (30s), maxStackSize (512KB), universal but limited stdlib'
472 - name: 'Cloudflare Workers driver'
473 package: '@tanstack/ai-isolate-cloudflare'
474 config_surface: 'workerUrl (required), authorization, timeout (30s), maxToolRounds (10), client-server execution model'
475 failure_modes:
476 - mistake: 'Passing API keys or secrets to the sandbox environment'
477 mechanism: 'Code Mode executes LLM-generated code. Any secrets passed into the sandbox context are accessible to generated code, which could exfiltrate them via tool calls or network access.'
478 source: 'docs/code-mode/code-mode.md'
479 priority: 'CRITICAL'
480 status: 'active'
481​
482 - mistake: 'Not setting timeout for code execution'
483 mechanism: 'LLM-generated code may contain infinite loops. Without a timeout, execution hangs indefinitely. The default timeout is 30s, but developers may override it to 0 or remove it.'
484 source: 'packages/typescript/ai-code-mode/src/'
485 priority: 'HIGH'
486 status: 'active'
487​
488 - mistake: 'Using Node isolated-vm driver without checking platform compatibility'
489 mechanism: 'isolated-vm requires native module compilation. On incompatible platforms (wrong Node version, missing build tools), it causes segfaults. The driver has a probe mechanism (probeIsolatedVm()) but skipProbe:true bypasses it.'
490 source: 'packages/typescript/ai-isolate-node/src/'
491 priority: 'HIGH'
492 status: 'active'
493​
494 - mistake: 'Expecting identical behavior across isolate drivers'
495 mechanism: 'Node driver has full V8 support, QuickJS has limited stdlib (no File I/O, limited async), Cloudflare has network latency per tool call and a maxToolRounds limit (default 10). Same code may work in Node but fail in QuickJS or hit round limits on Cloudflare.'
496 source: 'docs/code-mode/code-mode-isolates.md'
497 priority: 'MEDIUM'
498 status: 'active'
499​
500 - name: 'Structured Outputs'
501 slug: 'structured-outputs'
502 domain: 'chat-experiences'
503 description: 'Get type-safe JSON responses from the LLM using schema constraints with Zod, ArkType, or Valibot. Just pass outputSchema to chat() — the adapter handles provider differences transparently.'
504 type: 'core'
505 packages:
506 - '@tanstack/ai'
507 covers:
508 - 'outputSchema parameter in chat()'
509 - 'convertSchemaToJsonSchema()'
510 - 'Zod, ArkType, Valibot schema support'
511 tasks:
512 - 'Extract typed data from LLM responses using outputSchema on chat()'
513 - 'Use Zod schemas for structured output validation'
514 failure_modes:
515 - mistake: 'Trying to implement provider-specific structured output strategies'
516 mechanism: 'Agents try to manually configure provider-specific structured output (e.g., setting response_format for OpenAI, forcing tool calls for Anthropic, setting responseMimeType for Gemini). The correct approach is to just pass outputSchema to chat() — the adapter handles everything transparently. There is no scenario where the developer needs to know the provider strategy.'
517 wrong_pattern: |
518 chat({
519 adapter: openaiText('gpt-5.2'),
520 messages,
521 modelOptions: { responseFormat: { type: 'json_schema', json_schema: mySchema } },
522 })
523 correct_pattern: |
524 chat({
525 adapter: openaiText('gpt-5.2'),
526 messages,
527 outputSchema: z.object({ name: z.string(), age: z.number() }),
528 })
529 source: 'maintainer interview'
530 priority: 'HIGH'
531 status: 'active'
532​
533 - mistake: 'Using convertSchemaToJsonSchema with ArkType'
534 mechanism: 'convertSchemaToJsonSchema() is broken for ArkType schemas, producing incorrect JSON Schema output. Zod works correctly; other schema libraries may have similar issues.'
535 source: 'https://github.com/TanStack/ai/issues/276'
536 priority: 'MEDIUM'
537 status: 'active'
538​
539 - mistake: 'Missing required array in OpenAI structured output schema'
540 mechanism: 'OpenAI structured outputs require all properties in the required array and additionalProperties: false. Schemas that dont meet this constraint fail silently or produce validation errors.'
541 source: 'Source code: openai adapter structured output transformation'
542 priority: 'MEDIUM'
543 status: 'active'
544​
545 - name: 'Adapter Configuration'
546 slug: 'adapter-configuration'
547 domain: 'adapter-management'
548 description: 'Select and configure provider adapters, set per-model type safety, configure model options (reasoning, thinking), switch adapters at runtime, and extend adapters with custom models.'
549 type: 'core'
550 packages:
551 - '@tanstack/ai'
552 - '@tanstack/ai-openai'
553 - '@tanstack/ai-anthropic'
554 - '@tanstack/ai-gemini'
555 - '@tanstack/ai-ollama'
556 - '@tanstack/ai-grok'
557 - '@tanstack/ai-groq'
558 - '@tanstack/ai-openrouter'
559 covers:
560 - 'openaiText() / anthropicText() / geminiText() / ollamaText() / grokText() / groqText() / openRouterText()'
561 - 'modelOptions'
562 - 'Per-model TypeScript type narrowing'
563 - 'extendAdapter()'
564 - 'createModel()'
565 - 'Runtime adapter switching pattern'
566 - 'Reasoning/thinking configuration'
567 tasks:
568 - 'Choose and configure a provider adapter'
569 - 'Set up per-model type-safe options'
570 - 'Configure reasoning/thinking for Claude or OpenAI o-series'
571 - 'Switch between providers at runtime based on user selection'
572 - 'Extend an adapter with custom or fine-tuned models'
573 - 'Set up API keys via environment variables'
574 subsystems:
575 - name: 'OpenAI adapter'
576 package: '@tanstack/ai-openai'
577 config_surface: 'Responses API, reasoning effort/summary, service tier, store, prompt caching, structured output via json_schema'
578 - name: 'Anthropic adapter'
579 package: '@tanstack/ai-anthropic'
580 config_surface: 'Extended thinking budget, prompt caching, MCP servers, tool-based structured output'
581 - name: 'Gemini adapter'
582 package: '@tanstack/ai-gemini'
583 config_surface: 'responseMimeType for JSON, thinking, widest modality support (audio/video/document)'
584 - name: 'Ollama adapter'
585 package: '@tanstack/ai-ollama'
586 config_surface: 'Local-only, arbitrary model names, extensive sampling params (mirostat, numa, gpu layers)'
587 - name: 'OpenRouter adapter'
588 package: '@tanstack/ai-openrouter'
589 config_surface: 'Multi-provider routing, web search tool, provider preferences, 300+ models'
590 - name: 'Grok adapter'
591 package: '@tanstack/ai-grok'
592 config_surface: 'OpenAI-compatible API, 2M context, caching support'
593 - name: 'Groq adapter'
594 package: '@tanstack/ai-groq'
595 config_surface: 'Fastest inference, vision, browser search, code execution features'
596 reference_candidates:
597 - topic: 'Model metadata and supported features per model'
598 reason: '>50 models across adapters with distinct capabilities, context windows, and pricing'
599 - topic: 'Provider-specific modelOptions'
600 reason: 'Each adapter has 10+ unique provider options that differ in naming and behavior'
601 failure_modes:
602 - mistake: 'Missing @standard-schema/spec makes all types any'
603 mechanism: 'Without @standard-schema/spec installed, the entire type system degrades — chat() returns any, tool definitions lose type inference, modelOptions has no type checking. The library core value proposition (type safety) disappears with no warning.'
604 wrong_pattern: |
605 // package.json has no @standard-schema/spec
606 // Everything compiles but all types are 'any'
607 const result = chat({ adapter: openaiText('gpt-5.2'), messages })
608 // result: any — no type checking at all
609 correct_pattern: |
610 // pnpm add @standard-schema/spec
611 // Full type safety restored
612 const result = chat({ adapter: openaiText('gpt-5.2'), messages })
613 // result: AsyncIterable<StreamChunk> with full type checking
614 source: 'https://github.com/TanStack/ai/issues/235, https://github.com/TanStack/ai/discussions/191'
615 priority: 'CRITICAL'
616 status: 'active'
617 version_context: 'Undocumented peer dependency; #1 first-5-minutes failure for new users'
618 skills: ['adapter-configuration', 'tool-calling', 'structured-outputs']
619​
620 - mistake: 'Confusing legacy monolithic adapter with tree-shakeable adapter'
621 mechanism: 'Both openai() (legacy) and openaiText() (current) exist. Legacy adapters are deprecated but not removed. Using the legacy adapter misses model-specific type safety and tree-shaking benefits.'
622 source: 'https://github.com/TanStack/ai/issues/407'
623 priority: 'HIGH'
624 status: 'active'
625​
626 - mistake: 'Ollama adapter silently drops systemPrompts'
627 mechanism: 'mapCommonOptionsToOllama() never accesses options.systemPrompts. System prompts passed to chat() with Ollama are silently ignored — no error, no warning.'
628 source: 'https://github.com/TanStack/ai/issues/388'
629 priority: 'HIGH'
630 status: 'active'
631​
632 - mistake: 'Anthropic prompt caching fails on system prompts'
633 mechanism: 'The Anthropic adapter joins system prompts into a plain string instead of TextBlockParam[], preventing Anthropics cache_control from working. This can cost $1.50-2.00 extra per agentic run.'
634 source: 'https://github.com/TanStack/ai/issues/379'
635 priority: 'HIGH'
636 status: 'active'
637​
638 - mistake: 'Wrong API key environment variable name'
639 mechanism: 'Each adapter looks for a specific env var: OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_API_KEY or GEMINI_API_KEY (not GOOGLE_GENAI_API_KEY), XAI_API_KEY (not GROK_API_KEY), GROQ_API_KEY, OPENROUTER_API_KEY, OLLAMA_HOST. Using the wrong name causes silent auth failures.'
640 source: 'Source code: adapter env key lookup functions'
641 priority: 'MEDIUM'
642 status: 'active'
643​
644 - name: 'Custom Backend Integration'
645 slug: 'custom-backend-integration'
646 domain: 'transport-protocol'
647 description: 'Connect the client-side useChat hook to a non-TanStack-AI backend through custom connection adapters.'
648 type: 'composition'
649 packages:
650 - '@tanstack/ai-client'
651 - '@tanstack/ai-react'
652 covers:
653 - 'Custom ConnectionAdapter interface'
654 - 'ConnectConnectionAdapter vs SubscribeConnectionAdapter'
655 - 'fetchServerSentEvents() customization'
656 - 'fetchHttpStream() customization'
657 tasks:
658 - 'Connect useChat to a custom backend that speaks SSE'
659 - 'Connect useChat to a custom backend with NDJSON streaming'
660 - 'Implement a fully custom connection adapter'
661 - 'Add authentication headers to connection requests'
662 failure_modes:
663 - mistake: 'Providing both connect and subscribe+send in connection adapter'
664 mechanism: 'The ConnectionAdapter interface has two mutually exclusive modes. Providing both throws: "Connection adapter must provide either connect or both subscribe and send, not both modes".'
665 source: 'Source code assertion: ai-client/src/connection-adapters.ts line 116'
666 priority: 'HIGH'
667 status: 'active'
668​
669 - mistake: 'Not handling SSE browser connection limits'
670 mechanism: 'Browsers limit SSE connections to 6-8 per domain. Opening multiple chat sessions on the same page can exhaust this limit, causing new connections to queue indefinitely.'
671 source: 'docs/chat/connection-adapters.md'
672 priority: 'MEDIUM'
673 status: 'active'
674​
675 - mistake: 'Using HTTP stream without implementing reconnection'
676 mechanism: 'SSE has built-in browser auto-reconnection, but HTTP stream (NDJSON) does not. Connection drops with HTTP stream silently lose the response without retrying.'
677 source: 'docs/protocol/http-stream-protocol.md'
678 priority: 'MEDIUM'
679 status: 'active'
680​
681 - name: 'AG-UI Protocol'
682 slug: 'ag-ui-protocol'
683 domain: 'transport-protocol'
684 description: 'Implement the AG-UI streaming protocol server-side without using client packages — for backends that serve AG-UI events to any compatible frontend.'
685 type: 'core'
686 packages:
687 - '@tanstack/ai'
688 covers:
689 - 'StreamChunk / AG-UI event types'
690 - 'RUN_STARTED, TEXT_MESSAGE_START/CONTENT/END, TOOL_CALL_START/ARGS/END, RUN_FINISHED, RUN_ERROR'
691 - 'STEP_STARTED/STEP_FINISHED (thinking)'
692 - 'STATE_SNAPSHOT/STATE_DELTA'
693 - 'CUSTOM events'
694 - 'toServerSentEventsStream()'
695 - 'toHttpStream()'
696 tasks:
697 - 'Build a server that emits AG-UI protocol events'
698 - 'Choose between SSE and HTTP stream transport format'
699 - 'Handle tool calls within the AG-UI event lifecycle'
700 - 'Emit custom events for application-specific data'
701 failure_modes:
702 - mistake: 'TanStack AI message format doesnt match AG-UI spec'
703 mechanism: 'TanStack AIs internal request format (messages with parts containing content) diverges from the AG-UI spec (messages with content as string/InputContent, plus threadId, runId, tools, context, forwardedProps). Clients expecting strict AG-UI compliance will fail.'
704 source: 'https://github.com/TanStack/ai/issues/311'
705 priority: 'HIGH'
706 status: 'active'
707​
708 - mistake: 'Proxy buffering breaks SSE streaming'
709 mechanism: 'Reverse proxies (nginx, Cloudflare, etc.) may buffer SSE responses, delaying or batching events. Must set X-Accel-Buffering: no or equivalent proxy headers.'
710 source: 'docs/protocol/sse-protocol.md'
711 priority: 'MEDIUM'
712 status: 'active'
713​
714 - mistake: 'Assuming all AG-UI events arrive in every response'
715 mechanism: 'Not all events are guaranteed. STEP_STARTED/STEP_FINISHED only appear with thinking-enabled models. TOOL_CALL events only appear when tools are called. Code that expects a fixed event sequence will break.'
716 source: 'docs/protocol/chunk-definitions.md'
717 priority: 'MEDIUM'
718 status: 'active'
719​
720 - name: 'Middleware'
721 slug: 'middleware'
722 domain: 'extensibility'
723 description: 'Intercept the chat lifecycle with middleware hooks for analytics, event firing, tool caching, and custom cross-cutting concerns.'
724 type: 'core'
725 packages:
726 - '@tanstack/ai'
727 covers:
728 - 'middleware array in chat() config'
729 - 'Hooks: onConfig, onStart, onChunk, onBeforeToolCall, onAfterToolCall, onUsage, onFinish, onAbort, onError'
730 - 'toolCacheMiddleware'
731 - 'Middleware execution order (left-to-right)'
732 tasks:
733 - 'Add analytics tracking to chat completions'
734 - 'Fire events at the end of a stream'
735 - 'Cache tool call results with TTL'
736 - 'Implement custom logging or tracing'
737 - 'Add rate limiting or request validation'
738 failure_modes:
739 - mistake: 'Structured output request runs outside middleware pipeline'
740 mechanism: 'When using chat({ outputSchema }), the final structured output request to the provider executes outside the middleware chain. Observability/tracing middleware will miss this call.'
741 source: 'https://github.com/TanStack/ai/issues/390'
742 priority: 'HIGH'
743 status: 'active'
744​
745 - mistake: 'Trying to modify StreamChunks in middleware'
746 mechanism: 'Middleware hooks provide read-only access to stream chunks via onChunk. They cannot modify, filter, or transform chunks after emission. Attempting to mutate chunk objects has no effect.'
747 source: 'docs/advanced/middleware.md'
748 priority: 'MEDIUM'
749 status: 'active'
750​
751 - mistake: 'Middleware exceptions breaking the stream'
752 mechanism: 'Unhandled exceptions in middleware hooks propagate up and break the streaming response. All middleware hooks should be wrapped in try-catch to prevent analytics/logging failures from killing the chat stream.'
753 source: 'docs/advanced/middleware.md'
754 priority: 'MEDIUM'
755 status: 'active'
756​
757tensions:
758 - name: 'Type safety vs. quick prototyping'
759 skills: ['adapter-configuration', 'chat-experience']
760 description: 'Per-model type safety requires explicit adapter creation, @standard-schema/spec installation, and specific model string literals. Quick prototyping wants dynamic model selection and minimal setup.'
761 implication: 'Agents optimizing for quick setup will skip @standard-schema/spec and use string variables for model names, silently losing all type safety — the librarys core value proposition.'
762​
763 - name: 'Tree-shaking vs. API discoverability'
764 skills: ['adapter-configuration', 'chat-experience', 'media-generation']
765 description: 'Split adapters (openaiText, openaiImage, openaiSpeech) minimize bundle size but require developers to know the exact import path for each activity.'
766 implication: 'Agents default to importing from the package root or using wildcard imports, pulling in the entire adapter bundle and defeating tree-shaking.'
767​
768 - name: 'Server/client tool symmetry vs. state consistency'
769 skills: ['tool-calling', 'chat-experience']
770 description: 'Tools can execute on server or client, but server tool results have different UIMessage state (input-complete with no output) than client tools (complete with output).'
771 implication: 'Agents building tool rendering UI will write code that checks part.output, which works for client tools but fails silently for server tools.'
772​
773 - name: 'AG-UI protocol compliance vs. internal message format'
774 skills: ['ag-ui-protocol', 'custom-backend-integration']
775 description: 'TanStack AIs internal UIMessage format (parts-based) diverges from the AG-UI spec (content-based). Full AG-UI compliance would require a different message structure.'
776 implication: 'Agents building AG-UI compatible servers will use TanStack AIs message format, which breaks interop with other AG-UI clients expecting the standard format.'
777​
778cross_references:
779 - from: 'chat-experience'
780 to: 'tool-calling'
781 reason: 'Most chat implementations include tool calling. Tools require definitions on both server (chat()) and client (useChat/clientTools).'
782​
783 - from: 'chat-experience'
784 to: 'adapter-configuration'
785 reason: 'Chat setup requires adapter selection and model configuration. Adapter choice affects available features (thinking, structured output strategy).'
786​
787 - from: 'chat-experience'
788 to: 'middleware'
789 reason: 'Middleware hooks into the chat lifecycle. Analytics, logging, and caching are typically set up alongside chat configuration.'
790​
791 - from: 'tool-calling'
792 to: 'code-mode'
793 reason: 'Code Mode is an advanced alternative to tool calling for complex multi-step operations. Users building chat with tools should consider code mode for token efficiency.'
794​
795 - from: 'structured-outputs'
796 to: 'adapter-configuration'
797 reason: 'Structured output strategy differs by provider (native JSON schema vs tool-based vs responseMimeType). Adapter choice determines how structured outputs work.'
798​
799 - from: 'media-generation'
800 to: 'adapter-configuration'
801 reason: 'Each media activity (image, video, speech, transcription) requires a specific activity adapter. Provider capabilities vary significantly for media.'
802​
803 - from: 'custom-backend-integration'
804 to: 'ag-ui-protocol'
805 reason: 'Custom backends must implement either SSE or HTTP stream format. Understanding the AG-UI protocol helps build compatible custom servers.'
806​
807 - from: 'code-mode'
808 to: 'chat-experience'
809 reason: 'Code Mode is always used on top of a chat experience. Client integration requires handling code_mode:* custom events in useChat.'
810​
811gaps:
812 - skill: 'chat-experience'
813 question: 'What is the recommended pattern for message persistence across page reloads? Multiple GitHub discussions request this but no official guidance exists.'
814 context: 'Users building production chat apps need persistence. Without guidance, agents will implement ad-hoc solutions.'
815 status: 'open'
816​
817 - skill: 'tool-calling'
818 question: 'What is the expected behavior when a server tool throws an error — should it terminate the agent loop or return an error result to the LLM for self-correction?'
819 context: 'Docs say "return error in output, dont throw" but the actual error handling behavior in the agent loop is unclear.'
820 status: 'open'
821​
822 - skill: 'adapter-configuration'
823 question: 'Is @standard-schema/spec intended to be a hard dependency or peer dependency? The current silent degradation to any types seems unintentional.'
824 context: 'This is the #1 developer pain point. Clarifying intent would determine whether the skill should instruct installing it or whether it should be automatic.'
825 status: 'open'
826​
827 - skill: 'ag-ui-protocol'
828 question: 'How much AG-UI spec compliance is intended? The message format divergence seems like it could be a design choice or a known gap.'
829 context: 'Determines whether skills should teach TanStack AI message format or AG-UI spec format for server implementations.'
830 status: 'open'
831​
832 - skill: 'middleware'
833 question: 'Is the structured output request running outside middleware (#390) a known limitation or a bug that will be fixed?'
834 context: 'Affects whether the skill should include a workaround or document it as expected behavior.'
835 status: 'open'
836​
837 - skill: 'structured-outputs'
838 question: 'Should the skill teach provider-specific structured output strategies or just outputSchema?'
839 context: 'Resolved: maintainer confirmed always just use outputSchema on chat() — the adapter handles everything transparently. No scenario requires knowing provider strategy.'
840 status: 'resolved'
841​
842 - skill: 'chat-experience'
843 question: 'Should agents import from @tanstack/ai-client or from framework packages?'
844 context: 'Resolved: always import from framework package (e.g., @tanstack/ai-react). Core is headless and re-exported. Only use @tanstack/ai-client for vanilla JS.'
845 status: 'resolved'