Open History to see the last commit
1---
2id: StreamProcessor
3title: StreamProcessor
4---
5
6# Class: StreamProcessor
7
8Defined in: [packages/typescript/ai/src/activities/chat/stream/processor.ts:135](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/activities/chat/stream/processor.ts#L135)
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/typescript/ai/src/activities/chat/stream/processor.ts:165](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/activities/chat/stream/processor.ts#L165)
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/typescript/ai/src/activities/chat/stream/processor.ts:323](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/activities/chat/stream/processor.ts#L323)
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/typescript/ai/src/activities/chat/stream/processor.ts:279](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/activities/chat/stream/processor.ts#L279)
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/typescript/ai/src/activities/chat/stream/processor.ts:212](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/activities/chat/stream/processor.ts#L212)
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/typescript/ai/src/activities/chat/stream/processor.ts:354](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/activities/chat/stream/processor.ts#L354)
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/typescript/ai/src/activities/chat/stream/processor.ts:419](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/activities/chat/stream/processor.ts#L419)
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/typescript/ai/src/activities/chat/stream/processor.ts:1683](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/activities/chat/stream/processor.ts#L1683)
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/typescript/ai/src/activities/chat/stream/processor.ts:263](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/activities/chat/stream/processor.ts#L263)
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/typescript/ai/src/activities/chat/stream/processor.ts:346](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/activities/chat/stream/processor.ts#L346)
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/typescript/ai/src/activities/chat/stream/processor.ts:1844](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/activities/chat/stream/processor.ts#L1844)
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/typescript/ai/src/activities/chat/stream/processor.ts:1801](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/activities/chat/stream/processor.ts#L1801)
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/typescript/ai/src/activities/chat/stream/processor.ts:242](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/activities/chat/stream/processor.ts#L242)
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/typescript/ai/src/activities/chat/stream/processor.ts:436](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/activities/chat/stream/processor.ts#L436)
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/typescript/ai/src/activities/chat/stream/processor.ts:470](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/activities/chat/stream/processor.ts#L470)
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/typescript/ai/src/activities/chat/stream/processor.ts:390](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/activities/chat/stream/processor.ts#L390)
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/typescript/ai/src/activities/chat/stream/processor.ts:1868](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/activities/chat/stream/processor.ts#L1868)
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/typescript/ai/src/activities/chat/stream/processor.ts:184](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/activities/chat/stream/processor.ts#L184)
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/typescript/ai/src/activities/chat/stream/processor.ts:251](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/activities/chat/stream/processor.ts#L251)
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/typescript/ai/src/activities/chat/stream/processor.ts:1831](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/activities/chat/stream/processor.ts#L1831)
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/typescript/ai/src/activities/chat/stream/processor.ts:335](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/activities/chat/stream/processor.ts#L335)
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/typescript/ai/src/activities/chat/stream/processor.ts:1887](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/activities/chat/stream/processor.ts#L1887)
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)\>