TanStack
AI v0v0
Docs
CodeRabbit
Cloudflare
AG Grid
SerpAPI
Netlify
OpenRouter
Neon
WorkOS
Clerk
Electric
PowerSync
Sentry
Railway
Prisma
Strapi
Unkey
CodeRabbit
Cloudflare
AG Grid
SerpAPI
Netlify
OpenRouter
Neon
WorkOS
Clerk
Electric
PowerSync
Sentry
Railway
Prisma
Strapi
Unkey
Menu
Getting Started
Comparison
Tools
Chat & Streaming
Code Mode
Media
Advanced
Migration
API
Adapters
Community Adapters
Class References
Function References
Interface References
Type Alias References
Variable References

ChatMiddleware

Interface: ChatMiddleware

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

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

ts
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 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') },
}
ts
const redactionMiddleware: ChatMiddleware = {
  name: 'redaction',
  onChunk(ctx, chunk) {
    if (chunk.type === 'TEXT_MESSAGE_CONTENT') {
      return { ...chunk, delta: redact(chunk.delta) }
    }
  },
}
const redactionMiddleware: ChatMiddleware = {
  name: 'redaction',
  onChunk(ctx, chunk) {
    if (chunk.type === 'TEXT_MESSAGE_CONTENT') {
      return { ...chunk, delta: redact(chunk.delta) }
    }
  },
}

Properties

name?

ts
optional name: string;
optional name: string;

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

Optional name for debugging and identification

onAbort()?

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

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

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

Parameters

ctx

ChatMiddlewareContext

info

AbortInfo

Returns

void | Promise<void>

onAfterToolCall()?

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

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

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

Parameters

ctx

ChatMiddlewareContext

info

AfterToolCallInfo

Returns

void | Promise<void>

onBeforeToolCall()?

ts
optional onBeforeToolCall: (ctx, hookCtx) => 
  | BeforeToolCallDecision
| Promise<BeforeToolCallDecision>;
optional onBeforeToolCall: (ctx, hookCtx) => 
  | BeforeToolCallDecision
| Promise<BeforeToolCallDecision>;

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

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

Parameters

ctx

ChatMiddlewareContext

hookCtx

ToolCallHookContext

Returns

| BeforeToolCallDecision | Promise<BeforeToolCallDecision>

onChunk()?

ts
optional onChunk: (ctx, chunk) => 
  | void
  | AGUIEvent
  | AGUIEvent[]
  | Promise<void | AGUIEvent | AGUIEvent[] | null>
  | null;
optional onChunk: (ctx, chunk) => 
  | void
  | AGUIEvent
  | AGUIEvent[]
  | Promise<void | AGUIEvent | AGUIEvent[] | null>
  | null;

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

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

Parameters

ctx

ChatMiddlewareContext

chunk

AGUIEvent

Returns

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

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

onConfig()?

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

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

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

config

ChatMiddlewareConfig

Returns

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

onError()?

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

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

Called when the chat run encounters an unhandled error. Exactly one of onFinish/onAbort/onError will be called per run.

Parameters

ctx

ChatMiddlewareContext

info

ErrorInfo

Returns

void | Promise<void>

onFinish()?

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

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

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

Parameters

ctx

ChatMiddlewareContext

info

FinishInfo

Returns

void | Promise<void>

onIteration()?

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

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

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

info

IterationInfo

Returns

void | Promise<void>

onStart()?

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

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

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

Parameters

ctx

ChatMiddlewareContext

Returns

void | Promise<void>

onToolPhaseComplete()?

ts
optional onToolPhaseComplete: (ctx, info) => void | Promise<void>;
optional onToolPhaseComplete: (ctx, info) => void | Promise<void>;

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

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

info

ToolPhaseCompleteInfo

Returns

void | Promise<void>

onUsage()?

ts
optional onUsage: (ctx, usage) => void | Promise<void>;
optional onUsage: (ctx, usage) => void | Promise<void>;

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

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

Parameters

ctx

ChatMiddlewareContext

usage

UsageInfo

Returns

void | Promise<void>

Edit on GitHub
Home
© 2026 TanStack LLC