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#

ChatMiddleware.name

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#

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

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

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

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

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

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

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

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#

IterationInfo

Returns#

void | Promise<void>

Inherited from#

ChatMiddleware.onIteration

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#

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

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

UsageInfo

Returns#

void | Promise<void>

Inherited from#

ChatMiddleware.onUsage

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#

ChatMiddleware.provides

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#

ChatMiddleware.requires

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#

ChatMiddleware.sandbox

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>

Inherited from#

ChatMiddleware.setup