Interface: ChatMiddleware<TContext>#

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

Chat middleware interface.

All hooks are optional. Middleware is composed in array order:

• onConfig: config piped through middlewares in order (first transform influences later)
• onChunk: each output chunk is fed into the next middleware in order

Examples#

const loggingMiddleware: ChatMiddleware = {
  name: 'logging',
  onStart(ctx) { console.log('Chat started', ctx.requestId) },
  onChunk(ctx, chunk) { console.log('Chunk:', chunk.type) },
  onFinish(ctx, info) { console.log('Done:', info.duration, 'ms') },
}

const redactionMiddleware: ChatMiddleware = {
  name: 'redaction',
  onChunk(ctx, chunk) {
    if (chunk.type === 'TEXT_MESSAGE_CONTENT') {
      return { ...chunk, delta: redact(chunk.delta) }
    }
  },
}

Extended by#

• DefinedChatMiddleware

Type Parameters#

TContext#

TContext = unknown

Properties#

name?#

optional name: string;

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

Optional name for debugging and identification

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>

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>

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>

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)

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

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>

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>

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>

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>

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

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>

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>

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 }).

provides?#

optional provides: readonly CapabilityHandle[];

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

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

requires?#

optional requires: readonly CapabilityHandle[];

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

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.

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.

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>