Interface: DefinedChatMiddleware<TContext, TRequires, TProvides>#
Defined in: packages/ai/src/activities/chat/middleware/define.ts:8
A middleware whose requires/provides tuple types are captured precisely
(via const inference) for the array coverage check and the builder.
Extends#
ChatMiddleware<TContext>
Type Parameters#
TContext#
TContext
TRequires#
TRequires extends ReadonlyArray<CapabilityHandle>
TProvides#
TProvides extends ReadonlyArray<CapabilityHandle>
Properties#
name?#
optional name: string;
Defined in: packages/ai/src/activities/chat/middleware/types.ts:423
Optional name for debugging and identification
Inherited from#
onAbort()?#
optional onAbort: (ctx, info) => void | Promise<void>;
Defined in: packages/ai/src/activities/chat/middleware/types.ts:573
Called when the chat run is aborted. Exactly one of onFinish/onAbort/onError will be called per run.
Parameters#
ctx#
ChatMiddlewareContext<TContext>
info#
Returns#
void | Promise<void>
Inherited from#
onAfterToolCall()?#
optional onAfterToolCall: (ctx, info) => void | Promise<void>;
Defined in: packages/ai/src/activities/chat/middleware/types.ts:537
Called after a tool execution completes (success or failure).
Parameters#
ctx#
ChatMiddlewareContext<TContext>
info#
Returns#
void | Promise<void>
Inherited from#
ChatMiddleware.onAfterToolCall
onBeforeToolCall()?#
optional onBeforeToolCall: (ctx, hookCtx) =>
| BeforeToolCallDecision
| Promise<BeforeToolCallDecision>;
Defined in: packages/ai/src/activities/chat/middleware/types.ts:529
Called before a tool is executed. Can observe, transform args, skip execution, or abort the run.
Parameters#
ctx#
ChatMiddlewareContext<TContext>
hookCtx#
Returns#
| BeforeToolCallDecision
| Promise<BeforeToolCallDecision>
Inherited from#
ChatMiddleware.onBeforeToolCall
onChunk()?#
optional onChunk: (ctx, chunk) =>
| void
| AGUIEvent
| AGUIEvent[]
| Promise<void | AGUIEvent | AGUIEvent[] | null>
| null;
Defined in: packages/ai/src/activities/chat/middleware/types.ts:515
Called for every chunk yielded by chat(). Can observe, transform, expand, or drop chunks.
Parameters#
ctx#
ChatMiddlewareContext<TContext>
chunk#
Returns#
| void
| AGUIEvent
| AGUIEvent[]
| Promise<void | AGUIEvent | AGUIEvent[] | null>
| null
void (pass through), chunk (replace), chunk[] (expand), null (drop)
Inherited from#
onConfig()?#
optional onConfig: (ctx, config) =>
| void
| Partial<ChatMiddlewareConfig>
| Promise<
| void
| Partial<ChatMiddlewareConfig>
| null>
| null;
Defined in: packages/ai/src/activities/chat/middleware/types.ts:462
Called to observe or transform the chat configuration. Called at init and at the beginning of each agent iteration.
Return a partial config to merge with the current config, or void to pass through. Only the fields you return are overwritten — everything else is preserved.
Parameters#
ctx#
ChatMiddlewareContext<TContext>
config#
Returns#
| void
| Partial<ChatMiddlewareConfig>
| Promise<
| void
| Partial<ChatMiddlewareConfig>
| null>
| null
Inherited from#
onError()?#
optional onError: (ctx, info) => void | Promise<void>;
Defined in: packages/ai/src/activities/chat/middleware/types.ts:582
Called when the chat run encounters an unhandled error. Exactly one of onFinish/onAbort/onError will be called per run.
Parameters#
ctx#
ChatMiddlewareContext<TContext>
info#
Returns#
void | Promise<void>
Inherited from#
onFinish()?#
optional onFinish: (ctx, info) => void | Promise<void>;
Defined in: packages/ai/src/activities/chat/middleware/types.ts:564
Called when the chat run completes normally. Exactly one of onFinish/onAbort/onError will be called per run.
Parameters#
ctx#
ChatMiddlewareContext<TContext>
info#
Returns#
void | Promise<void>
Inherited from#
onIteration()?#
optional onIteration: (ctx, info) => void | Promise<void>;
Defined in: packages/ai/src/activities/chat/middleware/types.ts:504
Called at the start of each agent loop iteration, after a new assistant message ID is created. Use this to observe iteration boundaries.
Parameters#
ctx#
ChatMiddlewareContext<TContext>
info#
Returns#
void | Promise<void>
Inherited from#
onStart()?#
optional onStart: (ctx) => void | Promise<void>;
Defined in: packages/ai/src/activities/chat/middleware/types.ts:498
Called when the chat run starts (after initial onConfig).
Parameters#
ctx#
ChatMiddlewareContext<TContext>
Returns#
void | Promise<void>
Inherited from#
onStructuredOutputConfig()?#
optional onStructuredOutputConfig: (ctx, config) =>
| void
| Partial<StructuredOutputMiddlewareConfig>
| Promise<
| void
| Partial<StructuredOutputMiddlewareConfig>
| null>
| null;
Defined in: packages/ai/src/activities/chat/middleware/types.ts:486
Called at the start of the final structured-output call (when the chat was invoked with outputSchema). Pipes through middleware in order, like onConfig, but with access to the JSON Schema being sent to the provider.
Return a partial to shallow-merge into the current config, or void to pass through.
Fires BEFORE onConfig at the structured-output boundary. onConfig also re-fires at the same boundary with ctx.phase === 'structuredOutput', receiving the post-onStructuredOutputConfig view of the config (minus outputSchema). Use onConfig for general-purpose transforms that apply to every adapter call; use this hook when you need to transform the outputSchema or apply structured-output-specific behavior.
Parameters#
ctx#
ChatMiddlewareContext<TContext>
config#
StructuredOutputMiddlewareConfig
Returns#
| void
| Partial<StructuredOutputMiddlewareConfig>
| Promise<
| void
| Partial<StructuredOutputMiddlewareConfig>
| null>
| null
Inherited from#
ChatMiddleware.onStructuredOutputConfig
onToolPhaseComplete()?#
optional onToolPhaseComplete: (ctx, info) => void | Promise<void>;
Defined in: packages/ai/src/activities/chat/middleware/types.ts:546
Called after all tool calls in an iteration have been processed. Provides aggregate data about tool execution results, approvals, and client tools.
Parameters#
ctx#
ChatMiddlewareContext<TContext>
info#
Returns#
void | Promise<void>
Inherited from#
ChatMiddleware.onToolPhaseComplete
onUsage()?#
optional onUsage: (ctx, usage) => void | Promise<void>;
Defined in: packages/ai/src/activities/chat/middleware/types.ts:555
Called when usage data is available from a RUN_FINISHED chunk. Called once per model iteration that reports usage.
Parameters#
ctx#
ChatMiddlewareContext<TContext>
usage#
Returns#
void | Promise<void>
Inherited from#
optionalRequires?#
optional optionalRequires: readonly CapabilityHandle[];
Defined in: packages/ai/src/activities/chat/middleware/types.ts:445
Capabilities this middleware uses if present but does not require.
Non-gating: never causes a validation error. Read with
getX(ctx, { optional: true }).
Inherited from#
ChatMiddleware.optionalRequires
provides?#
optional provides: TProvides;
Defined in: packages/ai/src/activities/chat/middleware/define.ts:14
Capabilities this middleware provides. Each declared capability MUST be
provided (via its provide accessor) inside setup, or chat() throws
after the setup phase.
Overrides#
requires?#
optional requires: TRequires;
Defined in: packages/ai/src/activities/chat/middleware/define.ts:13
Capabilities this middleware requires. chat() validates that some
middleware (or the adapter) provides each one; unsatisfied requirements are
a compile-time error (array coverage / builder) and a runtime error before
the adapter runs.
Overrides#
sandbox?#
optional sandbox: ChatSandboxHooks<TContext>;
Defined in: packages/ai/src/activities/chat/middleware/types.ts:591
Sandbox file-event hooks. Fire when a sandbox provided by withSandbox is
active during the run and a file is created/changed/deleted. Server-side.
Inherited from#
setup()?#
optional setup: (ctx) => void | Promise<void>;
Defined in: packages/ai/src/activities/chat/middleware/types.ts:453
Provisioning hook. Runs FIRST — before onConfig (init) — across all
middleware in array order. Use it to call provide accessors so later
middleware (onConfig onward) can consume the capabilities. Receives the
stable context; does NOT receive the mutable config.
Parameters#
ctx#
ChatMiddlewareContext<TContext>
Returns#
void | Promise<void>