Open History to see the last commit
1---
2id: DefinedChatMiddleware
3title: DefinedChatMiddleware
4---
5
6# Interface: DefinedChatMiddleware\<TContext, TRequires, TProvides\>
7
8Defined in: [packages/ai/src/activities/chat/middleware/define.ts:8](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/define.ts#L8)
9
10A middleware whose `requires`/`provides` tuple types are captured precisely
11(via `const` inference) for the array coverage check and the builder.
12
13## Extends
14
15- [`ChatMiddleware`](ChatMiddleware.md)\<`TContext`\>
16
17## Type Parameters
18
19### TContext
20
21`TContext`
22
23### TRequires
24
25`TRequires` *extends* `ReadonlyArray`\<[`CapabilityHandle`](../type-aliases/CapabilityHandle.md)\>
26
27### TProvides
28
29`TProvides` *extends* `ReadonlyArray`\<[`CapabilityHandle`](../type-aliases/CapabilityHandle.md)\>
30
31## Properties
32
33### name?
34
35```ts
36optional name: string;
37```
38
39Defined in: [packages/ai/src/activities/chat/middleware/types.ts:423](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L423)
40
41Optional name for debugging and identification
42
43#### Inherited from
44
45[`ChatMiddleware`](ChatMiddleware.md).[`name`](ChatMiddleware.md#name)
46
47***
48
49### onAbort()?
50
51```ts
52optional onAbort: (ctx, info) => void | Promise<void>;
53```
54
55Defined in: [packages/ai/src/activities/chat/middleware/types.ts:573](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L573)
56
57Called when the chat run is aborted.
58Exactly one of onFinish/onAbort/onError will be called per run.
59
60#### Parameters
61
62##### ctx
63
64[`ChatMiddlewareContext`](ChatMiddlewareContext.md)\<`TContext`\>
65
66##### info
67
68[`AbortInfo`](AbortInfo.md)
69
70#### Returns
71
72`void` \| `Promise`\<`void`\>
73
74#### Inherited from
75
76[`ChatMiddleware`](ChatMiddleware.md).[`onAbort`](ChatMiddleware.md#onabort)
77
78***
79
80### onAfterToolCall()?
81
82```ts
83optional onAfterToolCall: (ctx, info) => void | Promise<void>;
84```
85
86Defined in: [packages/ai/src/activities/chat/middleware/types.ts:537](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L537)
87
88Called after a tool execution completes (success or failure).
89
90#### Parameters
91
92##### ctx
93
94[`ChatMiddlewareContext`](ChatMiddlewareContext.md)\<`TContext`\>
95
96##### info
97
98[`AfterToolCallInfo`](AfterToolCallInfo.md)
99
100#### Returns
101
102`void` \| `Promise`\<`void`\>
103
104#### Inherited from
105
106[`ChatMiddleware`](ChatMiddleware.md).[`onAfterToolCall`](ChatMiddleware.md#onaftertoolcall)
107
108***
109
110### onBeforeToolCall()?
111
112```ts
113optional onBeforeToolCall: (ctx, hookCtx) =>
114 | BeforeToolCallDecision
115| Promise<BeforeToolCallDecision>;
116```
117
118Defined in: [packages/ai/src/activities/chat/middleware/types.ts:529](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L529)
119
120Called before a tool is executed.
121Can observe, transform args, skip execution, or abort the run.
122
123#### Parameters
124
125##### ctx
126
127[`ChatMiddlewareContext`](ChatMiddlewareContext.md)\<`TContext`\>
128
129##### hookCtx
130
131[`ToolCallHookContext`](ToolCallHookContext.md)
132
133#### Returns
134
135 \| [`BeforeToolCallDecision`](../type-aliases/BeforeToolCallDecision.md)
136 \| `Promise`\<[`BeforeToolCallDecision`](../type-aliases/BeforeToolCallDecision.md)\>
137
138#### Inherited from
139
140[`ChatMiddleware`](ChatMiddleware.md).[`onBeforeToolCall`](ChatMiddleware.md#onbeforetoolcall)
141
142***
143
144### onChunk()?
145
146```ts
147optional onChunk: (ctx, chunk) =>
148 | void
149 | AGUIEvent
150 | AGUIEvent[]
151 | Promise<void | AGUIEvent | AGUIEvent[] | null>
152 | null;
153```
154
155Defined in: [packages/ai/src/activities/chat/middleware/types.ts:515](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L515)
156
157Called for every chunk yielded by chat().
158Can observe, transform, expand, or drop chunks.
159
160#### Parameters
161
162##### ctx
163
164[`ChatMiddlewareContext`](ChatMiddlewareContext.md)\<`TContext`\>
165
166##### chunk
167
168[`AGUIEvent`](../type-aliases/AGUIEvent.md)
169
170#### Returns
171
172 \| `void`
173 \| [`AGUIEvent`](../type-aliases/AGUIEvent.md)
174 \| [`AGUIEvent`](../type-aliases/AGUIEvent.md)[]
175 \| `Promise`\<void \| AGUIEvent \| AGUIEvent\[\] \| null\>
176 \| `null`
177
178void (pass through), chunk (replace), chunk[] (expand), null (drop)
179
180#### Inherited from
181
182[`ChatMiddleware`](ChatMiddleware.md).[`onChunk`](ChatMiddleware.md#onchunk)
183
184***
185
186### onConfig()?
187
188```ts
189optional onConfig: (ctx, config) =>
190 | void
191 | Partial<ChatMiddlewareConfig>
192 | Promise<
193 | void
194 | Partial<ChatMiddlewareConfig>
195 | null>
196 | null;
197```
198
199Defined in: [packages/ai/src/activities/chat/middleware/types.ts:462](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L462)
200
201Called to observe or transform the chat configuration.
202Called at init and at the beginning of each agent iteration.
203
204Return a partial config to merge with the current config, or void to pass through.
205Only the fields you return are overwritten — everything else is preserved.
206
207#### Parameters
208
209##### ctx
210
211[`ChatMiddlewareContext`](ChatMiddlewareContext.md)\<`TContext`\>
212
213##### config
214
215[`ChatMiddlewareConfig`](ChatMiddlewareConfig.md)
216
217#### Returns
218
219 \| `void`
220 \| `Partial`\<[`ChatMiddlewareConfig`](ChatMiddlewareConfig.md)\>
221 \| `Promise`\<
222 \| `void`
223 \| `Partial`\<[`ChatMiddlewareConfig`](ChatMiddlewareConfig.md)\>
224 \| `null`\>
225 \| `null`
226
227#### Inherited from
228
229[`ChatMiddleware`](ChatMiddleware.md).[`onConfig`](ChatMiddleware.md#onconfig)
230
231***
232
233### onError()?
234
235```ts
236optional onError: (ctx, info) => void | Promise<void>;
237```
238
239Defined in: [packages/ai/src/activities/chat/middleware/types.ts:582](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L582)
240
241Called when the chat run encounters an unhandled error.
242Exactly one of onFinish/onAbort/onError will be called per run.
243
244#### Parameters
245
246##### ctx
247
248[`ChatMiddlewareContext`](ChatMiddlewareContext.md)\<`TContext`\>
249
250##### info
251
252[`ErrorInfo`](ErrorInfo.md)
253
254#### Returns
255
256`void` \| `Promise`\<`void`\>
257
258#### Inherited from
259
260[`ChatMiddleware`](ChatMiddleware.md).[`onError`](ChatMiddleware.md#onerror)
261
262***
263
264### onFinish()?
265
266```ts
267optional onFinish: (ctx, info) => void | Promise<void>;
268```
269
270Defined in: [packages/ai/src/activities/chat/middleware/types.ts:564](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L564)
271
272Called when the chat run completes normally.
273Exactly one of onFinish/onAbort/onError will be called per run.
274
275#### Parameters
276
277##### ctx
278
279[`ChatMiddlewareContext`](ChatMiddlewareContext.md)\<`TContext`\>
280
281##### info
282
283[`FinishInfo`](FinishInfo.md)
284
285#### Returns
286
287`void` \| `Promise`\<`void`\>
288
289#### Inherited from
290
291[`ChatMiddleware`](ChatMiddleware.md).[`onFinish`](ChatMiddleware.md#onfinish)
292
293***
294
295### onIteration()?
296
297```ts
298optional onIteration: (ctx, info) => void | Promise<void>;
299```
300
301Defined in: [packages/ai/src/activities/chat/middleware/types.ts:504](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L504)
302
303Called at the start of each agent loop iteration, after a new assistant message ID
304is created. Use this to observe iteration boundaries.
305
306#### Parameters
307
308##### ctx
309
310[`ChatMiddlewareContext`](ChatMiddlewareContext.md)\<`TContext`\>
311
312##### info
313
314[`IterationInfo`](IterationInfo.md)
315
316#### Returns
317
318`void` \| `Promise`\<`void`\>
319
320#### Inherited from
321
322[`ChatMiddleware`](ChatMiddleware.md).[`onIteration`](ChatMiddleware.md#oniteration)
323
324***
325
326### onStart()?
327
328```ts
329optional onStart: (ctx) => void | Promise<void>;
330```
331
332Defined in: [packages/ai/src/activities/chat/middleware/types.ts:498](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L498)
333
334Called when the chat run starts (after initial onConfig).
335
336#### Parameters
337
338##### ctx
339
340[`ChatMiddlewareContext`](ChatMiddlewareContext.md)\<`TContext`\>
341
342#### Returns
343
344`void` \| `Promise`\<`void`\>
345
346#### Inherited from
347
348[`ChatMiddleware`](ChatMiddleware.md).[`onStart`](ChatMiddleware.md#onstart)
349
350***
351
352### onStructuredOutputConfig()?
353
354```ts
355optional onStructuredOutputConfig: (ctx, config) =>
356 | void
357 | Partial<StructuredOutputMiddlewareConfig>
358 | Promise<
359 | void
360 | Partial<StructuredOutputMiddlewareConfig>
361 | null>
362 | null;
363```
364
365Defined in: [packages/ai/src/activities/chat/middleware/types.ts:486](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L486)
366
367Called at the start of the final structured-output call (when the chat
368was invoked with outputSchema). Pipes through middleware in order, like
369onConfig, but with access to the JSON Schema being sent to the provider.
370
371Return a partial to shallow-merge into the current config, or void to
372pass through.
373
374Fires BEFORE onConfig at the structured-output boundary. onConfig also
375re-fires at the same boundary with ctx.phase === 'structuredOutput',
376receiving the post-onStructuredOutputConfig view of the config (minus
377outputSchema). Use onConfig for general-purpose transforms that apply
378to every adapter call; use this hook when you need to transform the
379outputSchema or apply structured-output-specific behavior.
380
381#### Parameters
382
383##### ctx
384
385[`ChatMiddlewareContext`](ChatMiddlewareContext.md)\<`TContext`\>
386
387##### config
388
389[`StructuredOutputMiddlewareConfig`](StructuredOutputMiddlewareConfig.md)
390
391#### Returns
392
393 \| `void`
394 \| `Partial`\<[`StructuredOutputMiddlewareConfig`](StructuredOutputMiddlewareConfig.md)\>
395 \| `Promise`\<
396 \| `void`
397 \| `Partial`\<[`StructuredOutputMiddlewareConfig`](StructuredOutputMiddlewareConfig.md)\>
398 \| `null`\>
399 \| `null`
400
401#### Inherited from
402
403[`ChatMiddleware`](ChatMiddleware.md).[`onStructuredOutputConfig`](ChatMiddleware.md#onstructuredoutputconfig)
404
405***
406
407### onToolPhaseComplete()?
408
409```ts
410optional onToolPhaseComplete: (ctx, info) => void | Promise<void>;
411```
412
413Defined in: [packages/ai/src/activities/chat/middleware/types.ts:546](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L546)
414
415Called after all tool calls in an iteration have been processed.
416Provides aggregate data about tool execution results, approvals, and client tools.
417
418#### Parameters
419
420##### ctx
421
422[`ChatMiddlewareContext`](ChatMiddlewareContext.md)\<`TContext`\>
423
424##### info
425
426[`ToolPhaseCompleteInfo`](ToolPhaseCompleteInfo.md)
427
428#### Returns
429
430`void` \| `Promise`\<`void`\>
431
432#### Inherited from
433
434[`ChatMiddleware`](ChatMiddleware.md).[`onToolPhaseComplete`](ChatMiddleware.md#ontoolphasecomplete)
435
436***
437
438### onUsage()?
439
440```ts
441optional onUsage: (ctx, usage) => void | Promise<void>;
442```
443
444Defined in: [packages/ai/src/activities/chat/middleware/types.ts:555](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L555)
445
446Called when usage data is available from a RUN_FINISHED chunk.
447Called once per model iteration that reports usage.
448
449#### Parameters
450
451##### ctx
452
453[`ChatMiddlewareContext`](ChatMiddlewareContext.md)\<`TContext`\>
454
455##### usage
456
457[`UsageInfo`](UsageInfo.md)
458
459#### Returns
460
461`void` \| `Promise`\<`void`\>
462
463#### Inherited from
464
465[`ChatMiddleware`](ChatMiddleware.md).[`onUsage`](ChatMiddleware.md#onusage)
466
467***
468
469### optionalRequires?
470
471```ts
472optional optionalRequires: readonly CapabilityHandle[];
473```
474
475Defined in: [packages/ai/src/activities/chat/middleware/types.ts:445](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L445)
476
477Capabilities this middleware uses if present but does not require.
478Non-gating: never causes a validation error. Read with
479`getX(ctx, { optional: true })`.
480
481#### Inherited from
482
483[`ChatMiddleware`](ChatMiddleware.md).[`optionalRequires`](ChatMiddleware.md#optionalrequires)
484
485***
486
487### provides?
488
489```ts
490optional provides: TProvides;
491```
492
493Defined in: [packages/ai/src/activities/chat/middleware/define.ts:14](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/define.ts#L14)
494
495Capabilities this middleware provides. Each declared capability MUST be
496provided (via its `provide` accessor) inside `setup`, or `chat()` throws
497after the setup phase.
498
499#### Overrides
500
501[`ChatMiddleware`](ChatMiddleware.md).[`provides`](ChatMiddleware.md#provides)
502
503***
504
505### requires?
506
507```ts
508optional requires: TRequires;
509```
510
511Defined in: [packages/ai/src/activities/chat/middleware/define.ts:13](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/define.ts#L13)
512
513Capabilities this middleware requires. `chat()` validates that some
514middleware (or the adapter) provides each one; unsatisfied requirements are
515a compile-time error (array coverage / builder) and a runtime error before
516the adapter runs.
517
518#### Overrides
519
520[`ChatMiddleware`](ChatMiddleware.md).[`requires`](ChatMiddleware.md#requires)
521
522***
523
524### sandbox?
525
526```ts
527optional sandbox: ChatSandboxHooks<TContext>;
528```
529
530Defined in: [packages/ai/src/activities/chat/middleware/types.ts:591](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L591)
531
532Sandbox file-event hooks. Fire when a sandbox provided by `withSandbox` is
533active during the run and a file is created/changed/deleted. Server-side.
534
535#### Inherited from
536
537[`ChatMiddleware`](ChatMiddleware.md).[`sandbox`](ChatMiddleware.md#sandbox)
538
539***
540
541### setup()?
542
543```ts
544optional setup: (ctx) => void | Promise<void>;
545```
546
547Defined in: [packages/ai/src/activities/chat/middleware/types.ts:453](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L453)
548
549Provisioning hook. Runs FIRST — before `onConfig` (init) — across all
550middleware in array order. Use it to call `provide` accessors so later
551middleware (`onConfig` onward) can consume the capabilities. Receives the
552stable context; does NOT receive the mutable config.
553
554#### Parameters
555
556##### ctx
557
558[`ChatMiddlewareContext`](ChatMiddlewareContext.md)\<`TContext`\>
559
560#### Returns
561
562`void` \| `Promise`\<`void`\>
563
564#### Inherited from
565
566[`ChatMiddleware`](ChatMiddleware.md).[`setup`](ChatMiddleware.md#setup)