Interface: DefinedChatMiddleware<TContext, TRequires, TProvides, TInterruptDefinitions>#

Defined in: packages/ai/src/activities/chat/middleware/define.ts:11

A middleware whose requires/provides tuple types are captured precisely (via const inference) for the array coverage check and the builder.

Extends#

• ChatMiddleware<TContext, TInterruptDefinitions>

Type Parameters#

TContext#

TContext

TRequires#

TRequires extends ReadonlyArray<CapabilityHandle>

TProvides#

TProvides extends ReadonlyArray<CapabilityHandle>

TInterruptDefinitions#

TInterruptDefinitions extends AnyInterruptDefinition = never

Properties#

name?#

optional name?: string;

Defined in: packages/ai/src/activities/chat/middleware/types.ts:579

Optional name for debugging and identification

Inherited from#

ChatMiddleware.name

onAbort?#

optional onAbort?: (ctx, info) => void | Promise<void>;

Defined in: packages/ai/src/activities/chat/middleware/types.ts:767

Called when the chat run is aborted. Exactly one of onFinish/onAbort/onError will be called per run.

Parameters#

ctx#

ChatMiddlewareContext<TContext>

info#

AbortInfo

Returns#

void | Promise<void>

Inherited from#

ChatMiddleware.onAbort

onAfterToolCall?#

optional onAfterToolCall?: (ctx, info) => void | Promise<void>;

Defined in: packages/ai/src/activities/chat/middleware/types.ts:731

Called after a tool execution completes (success or failure).

Parameters#

ctx#

ChatMiddlewareContext<TContext>

info#

AfterToolCallInfo

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:723

Called before a tool is executed. Can observe, transform args, skip execution, or abort the run.

Parameters#

ctx#

ChatMiddlewareContext<TContext>

hookCtx#

ToolCallHookContext

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:709

Called for every chunk yielded by chat(). Can observe, transform, expand, or drop chunks.

Parameters#

ctx#

ChatMiddlewareContext<TContext>

chunk#

AGUIEvent

Returns#

| void | AGUIEvent | AGUIEvent[] | Promise<void | AGUIEvent | AGUIEvent[] | null> | null

void (pass through), chunk (replace), chunk[] (expand), null (drop)

Inherited from#

ChatMiddleware.onChunk

onConfig?#

optional onConfig?: (ctx, config) => 
  | void
  | Partial<ChatMiddlewareConfig>
  | Promise<
  | void
  | Partial<ChatMiddlewareConfig>
  | null>
  | null;

Defined in: packages/ai/src/activities/chat/middleware/types.ts:637

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#

ChatMiddlewareConfig

Returns#

| void | Partial<ChatMiddlewareConfig> | Promise< | void | Partial<ChatMiddlewareConfig> | null> | null

Inherited from#

ChatMiddleware.onConfig

onError?#

optional onError?: (ctx, info) => void | Promise<void>;

Defined in: packages/ai/src/activities/chat/middleware/types.ts:776

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#

ErrorInfo

Returns#

void | Promise<void>

Inherited from#

ChatMiddleware.onError

onFinish?#

optional onFinish?: (ctx, info) => void | Promise<void>;

Defined in: packages/ai/src/activities/chat/middleware/types.ts:758

Called when the chat run completes normally. Exactly one of onFinish/onAbort/onError will be called per run.

Parameters#

ctx#

ChatMiddlewareContext<TContext>

info#

FinishInfo

Returns#

void | Promise<void>

Inherited from#

ChatMiddleware.onFinish

onInterruptBoundary?#

optional onInterruptBoundary?: (ctx) => 
  | InterruptBoundaryResult<TInterruptDefinitions>
| Promise<InterruptBoundaryResult<TInterruptDefinitions>>;

Defined in: packages/ai/src/activities/chat/middleware/types.ts:585

Called at a lifecycle boundary. Return interrupt requests to pause the run. Requests from every middleware in the same boundary form one batch.

Parameters#

ctx#

ChatMiddlewareContext<TContext> & object

Returns#

| InterruptBoundaryResult<TInterruptDefinitions> | Promise<InterruptBoundaryResult<TInterruptDefinitions>>

Inherited from#

ChatMiddleware.onInterruptBoundary

onInterruptResolution?#

optional onInterruptResolution?: (ctx, resolutions) => 
  | InterruptResolutionResult
| Promise<InterruptResolutionResult>;

Defined in: packages/ai/src/activities/chat/middleware/types.ts:595

Called on a continuation run after the client answers registered interrupts. Return toolResume to decide whether pending tools continue, cancel, or stop.

Parameters#

ctx#

ChatMiddlewareContext<TContext>

resolutions#

InterruptResolutionCollection<TInterruptDefinitions>

Returns#

| InterruptResolutionResult | Promise<InterruptResolutionResult>

Inherited from#

ChatMiddleware.onInterruptResolution

onIteration?#

optional onIteration?: (ctx, info) => void | Promise<void>;

Defined in: packages/ai/src/activities/chat/middleware/types.ts:679

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#

IterationInfo

Returns#

void | Promise<void>

Inherited from#

ChatMiddleware.onIteration

onShouldContinue?#

optional onShouldContinue?: (ctx, state) => boolean | void | Promise<boolean | void>;

Defined in: packages/ai/src/activities/chat/middleware/types.ts:698

Called when the engine is deciding whether to start another agent-loop iteration (after a tool phase or between model turns).

Return false to stop further iterations. Return true, void, or undefined to allow continuation. Combined with AND semantics across middleware and with agentLoopStrategy — any false stops the loop.

Does not abort the run: the stream finishes normally with the current messages. Use ctx.abort() only when you need a hard abort.

Receives the same AgentLoopState passed to strategies (iterationCount, toolCallCount, lastTurnToolCallCount, etc.).

Parameters#

ctx#

ChatMiddlewareContext<TContext>

state#

AgentLoopState

Returns#

boolean | void | Promise<boolean | void>

Inherited from#

ChatMiddleware.onShouldContinue

onStart?#

optional onStart?: (ctx) => void | Promise<void>;

Defined in: packages/ai/src/activities/chat/middleware/types.ts:673

Called when the chat run starts (after initial onConfig).

Parameters#

ctx#

ChatMiddlewareContext<TContext>

Returns#

void | Promise<void>

Inherited from#

ChatMiddleware.onStart

onStructuredOutputConfig?#

optional onStructuredOutputConfig?: (ctx, config) => 
  | void
  | Partial<StructuredOutputMiddlewareConfig>
  | Promise<
  | void
  | Partial<StructuredOutputMiddlewareConfig>
  | null>
  | null;

Defined in: packages/ai/src/activities/chat/middleware/types.ts:661

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:740

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#

ToolPhaseCompleteInfo

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:749

Called when usage data is available from a RUN_FINISHED chunk. Called once per model iteration that reports usage.

Parameters#

ctx#

ChatMiddlewareContext<TContext>

usage#

UsageInfo

Returns#

void | Promise<void>

Inherited from#

ChatMiddleware.onUsage

optionalRequires?#

optional optionalRequires?: readonly CapabilityHandle[];

Defined in: packages/ai/src/activities/chat/middleware/types.ts:620

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:18

Capabilities this middleware provides. Each declared capability MUST be provided (via its provide accessor) inside setup, or chat() throws after the setup phase.

Overrides#

ChatMiddleware.provides

requires?#

optional requires?: TRequires;

Defined in: packages/ai/src/activities/chat/middleware/define.ts:17

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#

ChatMiddleware.requires

sandbox?#

optional sandbox?: ChatSandboxHooks<TContext>;

Defined in: packages/ai/src/activities/chat/middleware/types.ts:785

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#

ChatMiddleware.sandbox

setup?#

optional setup?: (ctx) => void | Promise<void>;

Defined in: packages/ai/src/activities/chat/middleware/types.ts:628

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>

Inherited from#

ChatMiddleware.setup