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

DefinedChatMiddleware.md

566 lines13.6 KB

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)