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

StreamProcessor.md

497 lines10.2 KB

1---
2id: StreamProcessor
3title: StreamProcessor
4---
5​
6# Class: StreamProcessor
7​
8Defined in: [packages/ai/src/activities/chat/stream/processor.ts:156](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L156)
9​
10StreamProcessor - State machine for processing AI response streams
11​
12Manages the full UIMessage[] conversation and emits events on changes.
13Trusts the adapter contract: adapters emit clean AG-UI events in the
14correct order.
15​
16State tracking:
17- Full message array
18- Per-message stream state (text, tool calls, thinking)
19- Multiple concurrent message streams
20- Tool call completion via TOOL_CALL_END events
21​
22## See
23​
24 - docs/chat-architecture.md#streamprocessor-internal-state — State field reference
25 - docs/chat-architecture.md#adapter-contract — What this class expects from adapters
26​
27## Constructors
28​
29### Constructor
30​
31```ts
32new StreamProcessor(options): StreamProcessor;
33```
34​
35Defined in: [packages/ai/src/activities/chat/stream/processor.ts:193](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L193)
36​
37#### Parameters
38​
39##### options
40​
41[`StreamProcessorOptions`](../interfaces/StreamProcessorOptions.md) = `{}`
42​
43#### Returns
44​
45`StreamProcessor`
46​
47## Methods
48​
49### addToolApprovalResponse()
50​
51```ts
52addToolApprovalResponse(approvalId, approved): void;
53```
54​
55Defined in: [packages/ai/src/activities/chat/stream/processor.ts:351](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L351)
56​
57Add an approval response (called by client after handling onApprovalRequest)
58​
59#### Parameters
60​
61##### approvalId
62​
63`string`
64​
65##### approved
66​
67`boolean`
68​
69#### Returns
70​
71`void`
72​
73***
74​
75### addToolResult()
76​
77```ts
78addToolResult(
79 toolCallId,
80 output,
81 error?): void;
82```
83​
84Defined in: [packages/ai/src/activities/chat/stream/processor.ts:307](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L307)
85​
86Add a tool result (called by client after handling onToolCall)
87​
88#### Parameters
89​
90##### toolCallId
91​
92`string`
93​
94##### output
95​
96`any`
97​
98##### error?
99​
100`string`
101​
102#### Returns
103​
104`void`
105​
106***
107​
108### addUserMessage()
109​
110```ts
111addUserMessage(content, id?): UIMessage;
112```
113​
114Defined in: [packages/ai/src/activities/chat/stream/processor.ts:240](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L240)
115​
116Add a user message to the conversation.
117Supports both simple string content and multimodal content arrays.
118​
119#### Parameters
120​
121##### content
122​
123The message content (string or array of content parts)
124​
125`string` | [`ContentPart`](../type-aliases/ContentPart.md)[]
126​
127##### id?
128​
129`string`
130​
131Optional custom message ID (generated if not provided)
132​
133#### Returns
134​
135[`UIMessage`](../interfaces/UIMessage.md)
136​
137The created UIMessage
138​
139#### Example
140​
141```ts
142// Simple text message
143processor.addUserMessage('Hello!')
144​
145// Multimodal message with image
146processor.addUserMessage([
147 { type: 'text', content: 'What is in this image?' },
148 { type: 'image', source: { type: 'url', value: 'https://example.com/photo.jpg' } }
149])
150​
151// With custom ID
152processor.addUserMessage('Hello!', 'custom-id-123')
153```
154​
155***
156​
157### areAllToolsComplete()
158​
159```ts
160areAllToolsComplete(): boolean;
161```
162​
163Defined in: [packages/ai/src/activities/chat/stream/processor.ts:382](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L382)
164​
165Check if all tool calls in the last assistant message are complete
166Useful for auto-continue logic
167​
168#### Returns
169​
170`boolean`
171​
172***
173​
174### clearMessages()
175​
176```ts
177clearMessages(): void;
178```
179​
180Defined in: [packages/ai/src/activities/chat/stream/processor.ts:454](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L454)
181​
182Clear all messages
183​
184#### Returns
185​
186`void`
187​
188***
189​
190### finalizeStream()
191​
192```ts
193finalizeStream(): void;
194```
195​
196Defined in: [packages/ai/src/activities/chat/stream/processor.ts:2055](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L2055)
197​
198Finalize the stream — complete all pending operations.
199​
200Called when the async iterable ends (stream closed). Acts as the final
201safety net: completes any remaining tool calls, flushes un-emitted text,
202and fires onStreamEnd.
203​
204#### Returns
205​
206`void`
207​
208#### See
209​
210docs/chat-architecture.md#single-shot-text-response — Finalization step
211​
212***
213​
214### getCurrentAssistantMessageId()
215​
216```ts
217getCurrentAssistantMessageId(): string | null;
218```
219​
220Defined in: [packages/ai/src/activities/chat/stream/processor.ts:291](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L291)
221​
222Get the current assistant message ID (if one has been created).
223Returns null if prepareAssistantMessage() was called but no content
224has arrived yet.
225​
226#### Returns
227​
228`string` \| `null`
229​
230***
231​
232### getMessages()
233​
234```ts
235getMessages(): UIMessage<unknown>[];
236```
237​
238Defined in: [packages/ai/src/activities/chat/stream/processor.ts:374](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L374)
239​
240Get current messages
241​
242#### Returns
243​
244[`UIMessage`](../interfaces/UIMessage.md)\<`unknown`\>[]
245​
246***
247​
248### getRecording()
249​
250```ts
251getRecording(): ChunkRecording | null;
252```
253​
254Defined in: [packages/ai/src/activities/chat/stream/processor.ts:2219](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L2219)
255​
256Get the current recording
257​
258#### Returns
259​
260[`ChunkRecording`](../interfaces/ChunkRecording.md) \| `null`
261​
262***
263​
264### getState()
265​
266```ts
267getState(): ProcessorState;
268```
269​
270Defined in: [packages/ai/src/activities/chat/stream/processor.ts:2176](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L2176)
271​
272Get current processor state (aggregated across all messages)
273​
274#### Returns
275​
276[`ProcessorState`](../interfaces/ProcessorState.md)
277​
278***
279​
280### prepareAssistantMessage()
281​
282```ts
283prepareAssistantMessage(): void;
284```
285​
286Defined in: [packages/ai/src/activities/chat/stream/processor.ts:270](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L270)
287​
288Prepare for a new assistant message stream.
289Does NOT create the message immediately -- the message is created lazily
290when the first content-bearing chunk arrives via ensureAssistantMessage().
291This prevents empty assistant messages from flickering in the UI when
292auto-continuation produces no content.
293​
294#### Returns
295​
296`void`
297​
298***
299​
300### process()
301​
302```ts
303process(stream): Promise<ProcessorResult>;
304```
305​
306Defined in: [packages/ai/src/activities/chat/stream/processor.ts:472](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L472)
307​
308Process a stream and emit events through handlers
309​
310#### Parameters
311​
312##### stream
313​
314`AsyncIterable`\<`any`\>
315​
316#### Returns
317​
318`Promise`\<[`ProcessorResult`](../interfaces/ProcessorResult.md)\>
319​
320***
321​
322### processChunk()
323​
324```ts
325processChunk(chunk): void;
326```
327​
328Defined in: [packages/ai/src/activities/chat/stream/processor.ts:506](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L506)
329​
330Process a single chunk from the stream.
331​
332Central dispatch for all AG-UI events. Each event type maps to a specific
333handler. Events not listed in the switch are intentionally ignored
334(STEP_STARTED, STATE_SNAPSHOT, STATE_DELTA).
335​
336#### Parameters
337​
338##### chunk
339​
340[`AGUIEvent`](../type-aliases/AGUIEvent.md)
341​
342#### Returns
343​
344`void`
345​
346#### See
347​
348docs/chat-architecture.md#adapter-contract — Expected event types and ordering
349​
350***
351​
352### removeMessagesAfter()
353​
354```ts
355removeMessagesAfter(index): void;
356```
357​
358Defined in: [packages/ai/src/activities/chat/stream/processor.ts:422](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L422)
359​
360Remove messages after a certain index (for reload/retry)
361​
362#### Parameters
363​
364##### index
365​
366`number`
367​
368#### Returns
369​
370`void`
371​
372***
373​
374### reset()
375​
376```ts
377reset(): void;
378```
379​
380Defined in: [packages/ai/src/activities/chat/stream/processor.ts:2244](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L2244)
381​
382Full reset (including messages)
383​
384#### Returns
385​
386`void`
387​
388***
389​
390### setMessages()
391​
392```ts
393setMessages(messages): void;
394```
395​
396Defined in: [packages/ai/src/activities/chat/stream/processor.ts:212](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L212)
397​
398Set the messages array (e.g., from persisted state)
399​
400#### Parameters
401​
402##### messages
403​
404[`UIMessage`](../interfaces/UIMessage.md)\<`unknown`\>[]
405​
406#### Returns
407​
408`void`
409​
410***
411​
412### ~~startAssistantMessage()~~
413​
414```ts
415startAssistantMessage(messageId?): string;
416```
417​
418Defined in: [packages/ai/src/activities/chat/stream/processor.ts:279](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L279)
419​
420#### Parameters
421​
422##### messageId?
423​
424`string`
425​
426#### Returns
427​
428`string`
429​
430#### Deprecated
431​
432Use prepareAssistantMessage() instead. This eagerly creates
433an assistant message which can cause empty message flicker.
434​
435***
436​
437### startRecording()
438​
439```ts
440startRecording(): void;
441```
442​
443Defined in: [packages/ai/src/activities/chat/stream/processor.ts:2206](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L2206)
444​
445Start recording chunks
446​
447#### Returns
448​
449`void`
450​
451***
452​
453### toModelMessages()
454​
455```ts
456toModelMessages(): ModelMessage<
457 | string
458 | ContentPart<unknown, unknown, unknown, unknown, unknown>[]
459 | null>[];
460```
461​
462Defined in: [packages/ai/src/activities/chat/stream/processor.ts:363](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L363)
463​
464Get the conversation as ModelMessages (for sending to LLM)
465​
466#### Returns
467​
468[`ModelMessage`](../interfaces/ModelMessage.md)\<
469 \| `string`
470 \| [`ContentPart`](../type-aliases/ContentPart.md)\<`unknown`, `unknown`, `unknown`, `unknown`, `unknown`\>[]
471 \| `null`\>[]
472​
473***
474​
475### replay()
476​
477```ts
478static replay(recording, options?): Promise<ProcessorResult>;
479```
480​
481Defined in: [packages/ai/src/activities/chat/stream/processor.ts:2263](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L2263)
482​
483Replay a recording through the processor
484​
485#### Parameters
486​
487##### recording
488​
489[`ChunkRecording`](../interfaces/ChunkRecording.md)
490​
491##### options?
492​
493[`StreamProcessorOptions`](../interfaces/StreamProcessorOptions.md)
494​
495#### Returns
496​
497`Promise`\<[`ProcessorResult`](../interfaces/ProcessorResult.md)\>