experimental-a2 0.3.0 → 0.5.0

package/src/ai-server.ts

@@ -0,0 +1,1719 @@
+/**
+ * experimental-a2/ai/server — the server-only implementation of an experimental-a2/ai definition.
+ *
+ * `createHandlers()` exposes the ordinary A2 handler table;
+ * `createAgentServer()` is its batteries-included assembly with createServer.
+ */
+
+// oxlint-disable no-await-in-loop -- stream chunks and durable appends are
+// ordered; parallel consumption would corrupt progress sequence and state.
+
+import { AsyncLocalStorage } from 'node:async_hooks'
+import { convertToModelMessages } from 'ai'
+import type {
+  FinishReason,
+  Instructions,
+  LanguageModel,
+  LanguageModelUsage,
+  ModelMessage,
+  TextStreamPart,
+  ToolSet,
+  UIMessage,
+  UIMessageChunk,
+} from 'ai'
+import { generateAISDKStep, type AISDKStepSettings } from './ai-sdk-step.ts'
+import type {
+  AIEventDefs,
+  AIState,
+  AgentDefinition,
+  AgentToolContext,
+  AgentToolEventDefs,
+  ApprovalRequestedPayload,
+  CompactionCompletedPayload,
+  GenerationCompletedPayload,
+  GenerationFailedPayload,
+  GenerationProgressPayload,
+  GenerationRequestedPayload,
+  GenerationStartedPayload,
+  MessageCompletedPayload,
+  MessageCreatedPayload,
+  MessageInterruptedPayload,
+  ToolCalledPayload,
+  ToolResultPayload,
+} from './ai.ts'
+import {
+  aiCoordinatorReducer,
+  continuationReady,
+  type AICoordinatorState,
+} from './ai-coordinator.ts'
+import type { AppendInput, ContractEvent, EventDefs } from './contract.ts'
+import { A2Error } from './errors.ts'
+import {
+  consumeSchedulerSendFailure,
+  installAmbientToolScopeStorage,
+  type AmbientToolScope,
+} from './internal.ts'
+import {
+  createServer,
+  type A2Server,
+  type HandlerContext,
+  type PushValidationContext,
+  type ServerOptions,
+} from './server.ts'
+
+export function validateAgentPush(context: PushValidationContext): void {
+  const rejected = context.events.find((event) => {
+    if (event.type !== 'ai.message.created') {
+      return !(
+        event.type === 'ai.approval.responded' ||
+        event.type === 'ai.input.responded' ||
+        event.type === 'ai.message.interrupted' ||
+        event.type === 'ai.retry.requested'
+      )
+    }
+    const payload = event.payload
+    return (
+      typeof payload !== 'object' ||
+      payload === null ||
+      !('message' in payload) ||
+      typeof payload.message !== 'object' ||
+      payload.message === null ||
+      !('role' in payload.message) ||
+      payload.message.role !== 'user'
+    )
+  })
+  if (rejected !== undefined) {
+    throw new A2Error(
+      'INVALID_PAYLOAD',
+      `event '${rejected.type}' is server-only for an AI agent`,
+    )
+  }
+}
+
+type AgentGenerationProgress = {
+  type: 'progress'
+  chunks: UIMessageChunk[]
+}
+
+type AgentGenerationFinish = {
+  type: 'finish'
+  finishReason?: FinishReason
+  usage?: LanguageModelUsage
+}
+
+type AgentGenerationUpdate = AgentGenerationProgress | AgentGenerationFinish
+
+export type AgentGenerateContext<
+  M extends UIMessage,
+  D extends AIEventDefs<M> & EventDefs,
+  T extends ToolSet,
+> = {
+  request: ContractEvent<D, 'ai.generation.requested'>
+  requestId: string
+  generationId: string
+  responseMessageId: string
+  messages: M[]
+  state: AIState<M>
+  history: ContractEvent<D>[]
+  signal: AbortSignal
+  model: LanguageModel
+  tools: T
+  instructions?: Instructions
+  generation: AgentGenerationSettings<T>
+}
+
+export type AgentGenerate<
+  M extends UIMessage,
+  D extends AIEventDefs<M> & EventDefs,
+  T extends ToolSet,
+> = (
+  context: AgentGenerateContext<M, D, T>,
+) => ReadableStream<UIMessageChunk> | Promise<ReadableStream<UIMessageChunk>>
+
+type UIMessageMetadata<M extends UIMessage> =
+  M extends UIMessage<infer Metadata> ? Metadata : unknown
+
+export type AgentMessageMetadata<
+  M extends UIMessage,
+  D extends AIEventDefs<M> & EventDefs,
+  T extends ToolSet,
+> = (
+  context: AgentGenerateContext<M, D, T> & { part: TextStreamPart<T> },
+) => UIMessageMetadata<M> | undefined
+
+export type AgentResolverContext<
+  M extends UIMessage,
+  D extends AIEventDefs<M> & EventDefs,
+> = {
+  event: ContractEvent<D, 'ai.generation.requested'>
+  state: AIState<M>
+  history: ContractEvent<D>[]
+  signal: AbortSignal
+}
+
+export type Resolvable<T, C> = T | ((context: C) => T | Promise<T>)
+
+export type CompactionPolicy<
+  M extends UIMessage,
+  D extends AIEventDefs<M> & EventDefs,
+> = {
+  shouldCompact(
+    context: AgentResolverContext<M, D> & { messages: M[] },
+  ): boolean | Promise<boolean>
+  compact(
+    context: AgentResolverContext<M, D> & { messages: M[] },
+  ): M[] | Promise<M[]>
+}
+
+export type AgentGenerationSettings<T extends ToolSet> = AISDKStepSettings<T>
+
+export type CreateHandlersOptions<
+  M extends UIMessage,
+  D extends AIEventDefs<M> & EventDefs,
+  T extends ToolSet = ToolSet,
+> = {
+  agent: AgentDefinition<M, D>
+  /** AI SDK model string or provider model, optionally resolved per generation. */
+  model: Resolvable<LanguageModel, AgentResolverContext<M, D>>
+  tools?: T
+  instructions?: Resolvable<
+    Instructions | undefined,
+    AgentResolverContext<M, D>
+  >
+  /** Settings for each one-step AI SDK streamText call. */
+  generation?: AgentGenerationSettings<T>
+  /**
+   * Maximum model steps in one assistant response. Defaults to Infinity.
+   */
+  maxSteps?: number
+  /** Map default AI SDK stream parts to typed assistant message metadata. */
+  messageMetadata?: AgentMessageMetadata<M, D, T>
+  /**
+   * Replace model generation with an AI SDK UI message chunk stream.
+   * The custom stream owns its metadata chunks.
+   */
+  generate?: AgentGenerate<M, D, T>
+  compaction?: CompactionPolicy<M, D>
+  /** Progress is durably flushed at either limit, whichever is reached first. */
+  progress?: { maxChunks?: number; maxDelayMs?: number }
+}
+
+export type CreateAgentServerOptions<
+  M extends UIMessage,
+  D extends AIEventDefs<M> & EventDefs,
+  T extends ToolSet = ToolSet,
+> = CreateHandlersOptions<M, D, T> &
+  Omit<ServerOptions<D>, 'contract' | 'handlers' | 'validatePush'> & {
+    handlers?: ServerOptions<D>['handlers']
+  }
+
+const resolve = async <T, C>(
+  value: Resolvable<T, C>,
+  context: C,
+): Promise<T> =>
+  typeof value === 'function'
+    ? await (value as (context: C) => T | Promise<T>)(context)
+    : value
+
+const modelName = (model: LanguageModel): string => {
+  if (typeof model === 'string') return model
+  if ('modelId' in model && typeof model.modelId === 'string') {
+    return model.modelId
+  }
+  return 'custom'
+}
+
+const errorMessage = (error: unknown): string =>
+  error instanceof Error ? error.message : String(error)
+
+const toolScopeStorage = installAmbientToolScopeStorage(
+  () => new AsyncLocalStorage<AmbientToolScope>(),
+)
+
+/** Run `fn` with `ctx` as the ambient tool handler context, for direct tool tests. */
+export function runWithHandlerContext<D extends AgentToolEventDefs, R>(
+  ctx: AgentToolContext<D>,
+  fn: () => R,
+): R {
+  return toolScopeStorage.run({ context: ctx }, fn)
+}
+
+const promptCacheKey = (sessionId: string, generationId: string): string =>
+  `${sessionId}\u001f${generationId}`
+
+const asyncIterator = (value: unknown): AsyncIterator<unknown> | undefined => {
+  if (typeof value !== 'object' || value === null) return undefined
+  const factory = Reflect.get(value, Symbol.asyncIterator)
+  if (typeof factory !== 'function') return undefined
+  return (factory as (this: object) => AsyncIterator<unknown>).call(value)
+}
+
+const isBoundaryChunk = (chunk: UIMessageChunk | undefined): boolean =>
+  chunk !== undefined &&
+  (chunk.type === 'text-end' ||
+    chunk.type === 'reasoning-end' ||
+    chunk.type === 'tool-input-available' ||
+    chunk.type === 'tool-input-error' ||
+    chunk.type === 'tool-output-available' ||
+    chunk.type === 'tool-output-error' ||
+    chunk.type === 'tool-output-denied' ||
+    chunk.type === 'tool-approval-request' ||
+    chunk.type === 'finish' ||
+    chunk.type === 'abort' ||
+    chunk.type === 'error')
+
+const nextOrTimer = async <T>(
+  next: Promise<IteratorResult<T>>,
+  delayMs: number,
+): Promise<{ type: 'next'; result: IteratorResult<T> } | { type: 'timer' }> => {
+  let timer: ReturnType<typeof setTimeout> | undefined
+  try {
+    return await Promise.race([
+      next.then((result) => ({ type: 'next' as const, result })),
+      new Promise<{ type: 'timer' }>((finishTimer) => {
+        timer = setTimeout(() => finishTimer({ type: 'timer' }), delayMs)
+        ;(timer as { unref?: () => void }).unref?.()
+      }),
+    ])
+  } finally {
+    if (timer !== undefined) clearTimeout(timer)
+  }
+}
+
+type GenerationCompletion = {
+  finishReason?: FinishReason
+  usage?: LanguageModelUsage
+}
+
+type GenerationSource = {
+  stream: ReadableStream<UIMessageChunk>
+  completion?: () => GenerationCompletion
+}
+
+async function generateWithAISDK<
+  M extends UIMessage,
+  D extends AIEventDefs<M> & EventDefs,
+  T extends ToolSet,
+>(
+  context: AgentGenerateContext<M, D, T>,
+  messageMetadata: AgentMessageMetadata<M, D, T> | undefined,
+): Promise<GenerationSource> {
+  const step = await generateAISDKStep<M, T>({
+    model: context.model,
+    tools: context.tools,
+    messages: context.messages,
+    responseMessageId: context.responseMessageId,
+    abortSignal: context.signal,
+    ...(context.instructions === undefined
+      ? {}
+      : { instructions: context.instructions }),
+    settings: context.generation,
+    ...(messageMetadata === undefined
+      ? {}
+      : {
+          messageMetadata: ({ part }) => messageMetadata({ ...context, part }),
+        }),
+  })
+  return {
+    stream: step.stream as ReadableStream<UIMessageChunk>,
+    completion: step.completion,
+  }
+}
+
+async function* consumeGeneration(options: {
+  source: GenerationSource
+  progress?: { maxChunks?: number; maxDelayMs?: number }
+}): AsyncGenerator<AgentGenerationUpdate> {
+  const pending: UIMessageChunk[] = []
+  let streamedFinishReason: FinishReason | undefined
+  let streamedError: string | undefined
+  const maxChunks = options.progress?.maxChunks ?? 16
+  const maxDelayMs = options.progress?.maxDelayMs ?? 30
+  let lastFlush = Date.now()
+  const chunks = options.source.stream[Symbol.asyncIterator]()
+  let pendingChunk = chunks.next()
+  try {
+    for (;;) {
+      let result: IteratorResult<UIMessageChunk>
+      if (pending.length > 0) {
+        const remaining = Math.max(0, maxDelayMs - (Date.now() - lastFlush))
+        const outcome = await nextOrTimer(pendingChunk, remaining)
+        if (outcome.type === 'timer') {
+          yield { type: 'progress', chunks: pending.splice(0) }
+          lastFlush = Date.now()
+          continue
+        }
+        result = outcome.result
+      } else {
+        result = await pendingChunk
+      }
+      if (result.done) break
+      const chunk = result.value
+      pending.push(chunk)
+      if (chunk.type === 'finish') streamedFinishReason = chunk.finishReason
+      if (chunk.type === 'error') streamedError = chunk.errorText
+      pendingChunk = chunks.next()
+
+      if (pending.length >= maxChunks || isBoundaryChunk(pending.at(-1))) {
+        yield { type: 'progress', chunks: pending.splice(0) }
+        lastFlush = Date.now()
+      }
+    }
+  } catch (error) {
+    if (pending.length > 0)
+      yield { type: 'progress', chunks: pending.splice(0) }
+    throw error
+  }
+
+  let completion: GenerationCompletion | undefined
+  try {
+    completion = options.source.completion?.()
+  } catch (error) {
+    if (pending.length > 0) {
+      yield { type: 'progress', chunks: pending.splice(0) }
+    }
+    throw error
+  }
+  if (pending.length > 0) {
+    yield { type: 'progress', chunks: pending.splice(0) }
+  }
+  if (streamedError !== undefined) throw new Error(streamedError)
+  const finishReason = completion?.finishReason ?? streamedFinishReason
+  yield {
+    type: 'finish',
+    ...(finishReason === undefined ? {} : { finishReason }),
+    ...(completion?.usage === undefined ? {} : { usage: completion.usage }),
+  }
+}
+
+const replay = <M extends UIMessage, D extends AIEventDefs<M> & EventDefs>(
+  definition: AgentDefinition<M, D>,
+  history: ContractEvent<D>[],
+): AIState<M> => {
+  let state = definition.reducer.initialState
+  for (const event of history) state = definition.reducer.fold(state, event)
+  return state
+}
+
+const contextMessages = <M extends UIMessage>(state: AIState<M>): M[] => {
+  const compaction = state.compaction
+  if (compaction?.status !== 'completed' || !compaction.messages) {
+    return state.messages
+  }
+  const boundary = state.messages.findIndex(
+    (message) => message.id === compaction.throughMessageId,
+  )
+  const retained = new Set(compaction.retainedMessageIds ?? [])
+  return boundary === -1
+    ? state.messages
+    : [
+        ...compaction.messages,
+        ...state.messages
+          .slice(0, boundary + 1)
+          .filter((message) => retained.has(message.id)),
+        ...state.messages.slice(boundary + 1),
+      ]
+}
+
+const activeContextMessages = <M extends UIMessage>(
+  state: AIState<M>,
+  coordinator: AICoordinatorState,
+): M[] => {
+  const queued = new Set(coordinator.queued.map((item) => item.messageId))
+  return contextMessages(state).filter((message) => !queued.has(message.id))
+}
+
+const generationRequestId = (generationId: string): string | undefined => {
+  const markerIndex = generationId.lastIndexOf(':generation:')
+  return markerIndex === -1 ? undefined : generationId.slice(0, markerIndex)
+}
+
+type ToolCallClassification = 'automatic' | 'approval' | 'unknown'
+
+type PendingToolCall = {
+  call: ToolCalledPayload
+  classification: ToolCallClassification
+}
+
+const toolCalledEvent = <D extends EventDefs>(
+  payload: ToolCalledPayload,
+): AppendInput<D> =>
+  ({
+    type: 'ai.tool.called',
+    id: `${payload.generationId}:tool:${payload.toolCallId}:called`,
+    payload,
+  }) as AppendInput<D>
+
+const approvalClassification = <T extends ToolSet>(
+  tools: T,
+  generation: AgentGenerationSettings<T>,
+  toolName: string,
+): ToolCallClassification => {
+  const configured = generation.toolApproval
+  if (typeof configured === 'function') return 'unknown'
+  const policy = configured?.[toolName]
+  if (typeof policy === 'function') return 'unknown'
+  if (
+    policy === 'user-approval' ||
+    (typeof policy === 'object' && policy?.type === 'user-approval')
+  ) {
+    return 'approval'
+  }
+  if (
+    policy === 'denied' ||
+    (typeof policy === 'object' && policy?.type === 'denied')
+  ) {
+    return 'approval'
+  }
+  const tool = tools[toolName] as { needsApproval?: unknown } | undefined
+  if (typeof tool?.needsApproval === 'function') return 'unknown'
+  return tool?.needsApproval === true ? 'approval' : 'automatic'
+}
+
+const lifecycleEvents = <D extends EventDefs, T extends ToolSet>(options: {
+  requestId: string
+  messageId: string
+  generationId: string
+  sequence: number
+  chunks: UIMessageChunk[]
+  pending: PendingToolCall[]
+  tools: T
+  generation: AgentGenerationSettings<T>
+  custom: boolean
+}): { events: AppendInput<D>[]; pending: PendingToolCall[] } => {
+  const result: AppendInput<D>[] = []
+  const pending = [...options.pending]
+  const take = (toolCallId: string): PendingToolCall | undefined => {
+    const index = pending.findIndex(
+      (candidate) => candidate.call.toolCallId === toolCallId,
+    )
+    if (index === -1) return undefined
+    return pending.splice(index, 1)[0]
+  }
+  const flush = (toolCallId: string): void => {
+    const pendingCall = take(toolCallId)
+    if (pendingCall) result.push(toolCalledEvent<D>(pendingCall.call))
+  }
+  for (const [chunkIndex, chunk] of options.chunks.entries()) {
+    const resultId = `${options.generationId}:tool-result:${options.sequence}:${chunkIndex}`
+    if (chunk.type === 'tool-input-available') {
+      const payload: ToolCalledPayload = {
+        requestId: options.requestId,
+        messageId: options.messageId,
+        generationId: options.generationId,
+        toolCallId: chunk.toolCallId,
+        toolName: chunk.toolName,
+        input: chunk.input,
+        ...(chunk.dynamic === undefined ? {} : { dynamic: chunk.dynamic }),
+        ...(chunk.providerExecuted === undefined
+          ? {}
+          : { providerExecuted: chunk.providerExecuted }),
+        ...((
+          options.tools[chunk.toolName] as
+            { supportsDeferredResults?: boolean } | undefined
+        )?.supportsDeferredResults === true
+          ? { supportsDeferredResults: true }
+          : {}),
+        ...(chunk.providerMetadata === undefined
+          ? {}
+          : { providerMetadata: chunk.providerMetadata }),
+        ...(chunk.toolMetadata === undefined
+          ? {}
+          : { toolMetadata: chunk.toolMetadata }),
+        ...(chunk.title === undefined ? {} : { title: chunk.title }),
+      }
+      take(payload.toolCallId)
+      const classification = approvalClassification(
+        options.tools,
+        options.generation,
+        chunk.toolName,
+      )
+      if (classification === 'automatic') {
+        result.push(toolCalledEvent<D>(payload))
+      } else {
+        pending.push({ call: payload, classification })
+      }
+    } else if (chunk.type === 'tool-input-error') {
+      const payload: ToolResultPayload = {
+        requestId: options.requestId,
+        messageId: options.messageId,
+        generationId: options.generationId,
+        toolCallId: chunk.toolCallId,
+        toolName: chunk.toolName,
+        ...(chunk.dynamic ? { input: chunk.input } : { rawInput: chunk.input }),
+        error: chunk.errorText,
+        phase: 'input',
+        ...(chunk.dynamic === undefined ? {} : { dynamic: chunk.dynamic }),
+        ...(chunk.providerExecuted === undefined
+          ? {}
+          : { providerExecuted: chunk.providerExecuted }),
+        ...(chunk.providerMetadata === undefined
+          ? {}
+          : { providerMetadata: chunk.providerMetadata }),
+        ...(chunk.toolMetadata === undefined
+          ? {}
+          : { toolMetadata: chunk.toolMetadata }),
+      }
+      const called: ToolCalledPayload = {
+        requestId: options.requestId,
+        messageId: options.messageId,
+        generationId: options.generationId,
+        toolCallId: chunk.toolCallId,
+        toolName: chunk.toolName,
+        input: chunk.input,
+      }
+      take(chunk.toolCallId)
+      result.push(toolCalledEvent<D>(called), {
+        type: 'ai.tool.result',
+        id: resultId,
+        payload,
+      } as AppendInput<D>)
+    } else if (chunk.type === 'tool-output-available') {
+      flush(chunk.toolCallId)
+      const payload: ToolResultPayload = {
+        requestId: options.requestId,
+        messageId: options.messageId,
+        generationId: options.generationId,
+        toolCallId: chunk.toolCallId,
+        output: chunk.output,
+        phase: 'execution',
+        ...(chunk.preliminary === undefined
+          ? {}
+          : { preliminary: chunk.preliminary }),
+        ...(chunk.dynamic === undefined ? {} : { dynamic: chunk.dynamic }),
+        ...(chunk.providerExecuted === undefined
+          ? {}
+          : { providerExecuted: chunk.providerExecuted }),
+        ...(chunk.providerMetadata === undefined
+          ? {}
+          : { providerMetadata: chunk.providerMetadata }),
+        ...(chunk.toolMetadata === undefined
+          ? {}
+          : { toolMetadata: chunk.toolMetadata }),
+      }
+      result.push({
+        type: 'ai.tool.result',
+        id: resultId,
+        payload,
+      } as AppendInput<D>)
+    } else if (chunk.type === 'tool-output-error') {
+      flush(chunk.toolCallId)
+      const payload: ToolResultPayload = {
+        requestId: options.requestId,
+        messageId: options.messageId,
+        generationId: options.generationId,
+        toolCallId: chunk.toolCallId,
+        error: chunk.errorText,
+        phase: 'execution',
+        ...(chunk.dynamic === undefined ? {} : { dynamic: chunk.dynamic }),
+        ...(chunk.providerExecuted === undefined
+          ? {}
+          : { providerExecuted: chunk.providerExecuted }),
+        ...(chunk.providerMetadata === undefined
+          ? {}
+          : { providerMetadata: chunk.providerMetadata }),
+        ...(chunk.toolMetadata === undefined
+          ? {}
+          : { toolMetadata: chunk.toolMetadata }),
+      }
+      result.push({
+        type: 'ai.tool.result',
+        id: resultId,
+        payload,
+      } as AppendInput<D>)
+    } else if (chunk.type === 'tool-output-denied') {
+      flush(chunk.toolCallId)
+      const payload: ToolResultPayload = {
+        requestId: options.requestId,
+        messageId: options.messageId,
+        generationId: options.generationId,
+        toolCallId: chunk.toolCallId,
+        denied: true,
+        phase: 'execution',
+      }
+      result.push({
+        type: 'ai.tool.result',
+        id: resultId,
+        payload,
+      } as AppendInput<D>)
+    } else if (chunk.type === 'tool-approval-request') {
+      flush(chunk.toolCallId)
+      const payload: ApprovalRequestedPayload = {
+        messageId: options.messageId,
+        generationId: options.generationId,
+        approvalId: chunk.approvalId,
+        toolCallId: chunk.toolCallId,
+        ...(chunk.isAutomatic === undefined
+          ? {}
+          : { isAutomatic: chunk.isAutomatic }),
+        ...(chunk.signature === undefined
+          ? {}
+          : { signature: chunk.signature }),
+      }
+      result.push({
+        type: 'ai.approval.requested',
+        id: `${options.generationId}:approval:${chunk.approvalId}`,
+        payload,
+      } as AppendInput<D>)
+    } else if (chunk.type === 'tool-approval-response') {
+      result.push({
+        type: 'ai.approval.responded',
+        id: `${options.generationId}:approval:${chunk.approvalId}:automatic-response`,
+        payload: {
+          messageId: options.messageId,
+          generationId: options.generationId,
+          approvalId: chunk.approvalId,
+          approved: chunk.approved,
+          ...(chunk.reason === undefined ? {} : { reason: chunk.reason }),
+        },
+      } as AppendInput<D>)
+    }
+  }
+  return { events: result, pending }
+}
+
+function queuedMessagesAt<D extends EventDefs>(
+  history: ContractEvent<D>[],
+): AICoordinatorState['queued'] {
+  const queued: AICoordinatorState['queued'] = []
+  for (const event of history) {
+    if (event.type === 'ai.message.created') {
+      const payload = event.payload as MessageCreatedPayload<UIMessage>
+      if (payload.message.role !== 'user') continue
+      const duplicate = queued.findIndex(
+        (item) => item.messageId === payload.message.id,
+      )
+      if (duplicate !== -1) queued.splice(duplicate, 1)
+      queued.push({
+        index: event.index,
+        messageId: payload.message.id,
+        generate: payload.generate !== false,
+      })
+      continue
+    }
+    if (event.type !== 'ai.generation.requested') continue
+    const request = event.payload as GenerationRequestedPayload
+    if (request.reason !== 'message') continue
+    const requested = queued.findIndex(
+      (item) => item.messageId === request.messageId,
+    )
+    if (requested !== -1) queued.splice(0, requested + 1)
+  }
+  return queued
+}
+
+function withoutGenerationLifecycle<D extends EventDefs>(
+  history: ContractEvent<D>[],
+  generationIds: ReadonlySet<string>,
+): ContractEvent<D>[] {
+  if (generationIds.size === 0) return history
+  const approvalKeys = new Set<string>()
+  const inputKeys = new Set<string>()
+  for (const event of history) {
+    const payload = event.payload as {
+      generationId?: unknown
+      messageId?: unknown
+      approvalId?: unknown
+      inputId?: unknown
+    }
+    if (
+      typeof payload.generationId !== 'string' ||
+      !generationIds.has(payload.generationId) ||
+      typeof payload.messageId !== 'string'
+    ) {
+      continue
+    }
+    if (
+      event.type === 'ai.approval.requested' &&
+      typeof payload.approvalId === 'string'
+    ) {
+      approvalKeys.add(`${payload.messageId}\u001f${payload.approvalId}`)
+    }
+    if (
+      event.type === 'ai.input.requested' &&
+      typeof payload.inputId === 'string'
+    ) {
+      inputKeys.add(`${payload.messageId}\u001f${payload.inputId}`)
+    }
+  }
+  return history.filter((event) => {
+    const payload = event.payload as {
+      generationId?: unknown
+      messageId?: unknown
+      approvalId?: unknown
+      inputId?: unknown
+    }
+    if (
+      typeof payload.generationId === 'string' &&
+      generationIds.has(payload.generationId)
+    ) {
+      return false
+    }
+    if (
+      event.type === 'ai.approval.responded' &&
+      typeof payload.messageId === 'string' &&
+      typeof payload.approvalId === 'string'
+    ) {
+      return !approvalKeys.has(
+        `${payload.messageId}\u001f${payload.approvalId}`,
+      )
+    }
+    if (
+      event.type === 'ai.input.responded' &&
+      typeof payload.messageId === 'string' &&
+      typeof payload.inputId === 'string'
+    ) {
+      return !inputKeys.has(`${payload.messageId}\u001f${payload.inputId}`)
+    }
+    return true
+  })
+}
+
+/**
+ * Build the ordinary A2 handler table for the built-in agent protocol.
+ * Application handlers can be spread beside this table.
+ */
+export function createHandlers<
+  M extends UIMessage,
+  D extends AIEventDefs<M> & EventDefs,
+  T extends ToolSet = ToolSet,
+>(
+  options: CreateHandlersOptions<M, D, T>,
+): NonNullable<ServerOptions<D>['handlers']> {
+  if (options.model === undefined) {
+    throw new TypeError('createHandlers requires model')
+  }
+  if (
+    options.progress?.maxChunks !== undefined &&
+    (!Number.isInteger(options.progress.maxChunks) ||
+      options.progress.maxChunks < 1)
+  ) {
+    throw new TypeError('progress.maxChunks must be a positive integer')
+  }
+  if (
+    options.progress?.maxDelayMs !== undefined &&
+    (!Number.isFinite(options.progress.maxDelayMs) ||
+      options.progress.maxDelayMs < 0)
+  ) {
+    throw new TypeError('progress.maxDelayMs must be a non-negative number')
+  }
+  if (
+    options.maxSteps !== undefined &&
+    options.maxSteps !== Number.POSITIVE_INFINITY &&
+    (!Number.isInteger(options.maxSteps) || options.maxSteps < 1)
+  ) {
+    throw new TypeError('maxSteps must be a positive integer or Infinity')
+  }
+
+  const tools = options.tools ?? ({} as T)
+  const generation = options.generation ?? {}
+  const maxSteps = options.maxSteps ?? Number.POSITIVE_INFINITY
+  const coordinator = aiCoordinatorReducer(options.agent.contract)
+  const promptCache = new Map<string, Promise<ModelMessage[]>>()
+
+  const coordinatorStateAt = (
+    history: ContractEvent<D>[],
+    frontier = Number.POSITIVE_INFINITY,
+  ): AICoordinatorState => {
+    let state = coordinator.initialState
+    for (const event of history) {
+      if (event.index >= frontier) break
+      state = coordinator.fold(state, event)
+    }
+    return state
+  }
+
+  const requestForNextMessage = (
+    state: AICoordinatorState,
+  ): AppendInput<D> | undefined => {
+    if (state.closed || state.response !== undefined) return undefined
+    const next = state.queued.find((item) => item.generate !== false)
+    if (next === undefined) return undefined
+    return {
+      type: 'ai.generation.requested',
+      id: `ai.generate:message:${next.messageId}`,
+      payload: { messageId: next.messageId, reason: 'message' },
+    } as AppendInput<D>
+  }
+
+  const scheduleNext = async (
+    ctx: Pick<HandlerContext<D>, 'session'>,
+  ): Promise<AppendInput<D> | void> =>
+    requestForNextMessage((await ctx.session.state(coordinator)).state)
+
+  const continueIfReady = async (
+    ctx: Pick<HandlerContext<D>, 'session'>,
+    generationId: string,
+  ): Promise<void> => {
+    const state = (await ctx.session.state(coordinator)).state
+    const response = state.response
+    if (response?.generation?.generationId !== generationId) {
+      return
+    }
+    const input = response.inputResponse
+    const inputReady =
+      response.completion?.generationId === generationId &&
+      response.failure === undefined &&
+      input !== undefined &&
+      response.inputs.length === 0 &&
+      response.calls.every(
+        (call) =>
+          call.terminal ||
+          (call.call.providerExecuted === true &&
+            call.call.supportsDeferredResults !== true &&
+            call.approval !== undefined &&
+            call.response !== undefined),
+      )
+    if (inputReady) {
+      await ctx.session.append('continue-after-input', {
+        type: 'ai.generation.requested',
+        id: `ai.generate:input:${encodeURIComponent(response.responseMessageId)}:${encodeURIComponent(input.generationId)}:${encodeURIComponent(input.inputId)}`,
+        payload: {
+          messageId: response.responseMessageId,
+          responseMessageId: response.responseMessageId,
+          reason: 'input',
+        },
+      } as AppendInput<D>)
+      return
+    }
+    if (!continuationReady(state)) return
+    await ctx.session.append('continue-after-tools', {
+      type: 'ai.generation.requested',
+      id: `ai.generate:tools:${generationId}`,
+      payload: {
+        messageId: response.responseMessageId,
+        responseMessageId: response.responseMessageId,
+        reason: 'tool',
+      },
+    } as AppendInput<D>)
+  }
+
+  type RuntimeTool = {
+    execute?: (
+      input: unknown,
+      options: {
+        toolCallId: string
+        messages: ModelMessage[]
+        abortSignal?: AbortSignal
+      },
+    ) => unknown
+  }
+
+  type ToolHandlerContext =
+    | HandlerContext<D, 'ai.tool.called'>
+    | HandlerContext<D, 'ai.approval.responded'>
+
+  const resultEvent = (
+    call: ToolCalledPayload,
+    suffix: string,
+    result: {
+      output?: unknown
+      error?: string
+      denied?: boolean
+      preliminary?: boolean
+    },
+  ): AppendInput<D> =>
+    ({
+      type: 'ai.tool.result',
+      id: `${call.generationId}:tool:${call.toolCallId}:${suffix}`,
+      payload: {
+        requestId: call.requestId,
+        messageId: call.messageId,
+        generationId: call.generationId,
+        toolCallId: call.toolCallId,
+        toolName: call.toolName,
+        input: call.input,
+        phase: 'execution',
+        ...(result.output === undefined ? {} : { output: result.output }),
+        ...(result.error === undefined ? {} : { error: result.error }),
+        ...(result.denied === undefined ? {} : { denied: result.denied }),
+        ...(result.preliminary === undefined
+          ? {}
+          : { preliminary: result.preliminary }),
+        ...(call.dynamic === undefined ? {} : { dynamic: call.dynamic }),
+        ...(call.providerExecuted === undefined
+          ? {}
+          : { providerExecuted: call.providerExecuted }),
+        ...(call.toolMetadata === undefined
+          ? {}
+          : { toolMetadata: call.toolMetadata }),
+      },
+    }) as AppendInput<D>
+
+  const promptMessages = (
+    sessionId: string,
+    call: ToolCalledPayload,
+    readHistory: () => Promise<ContractEvent<D>[]>,
+  ): Promise<ModelMessage[]> => {
+    const key = promptCacheKey(sessionId, call.generationId)
+    const cached = promptCache.get(key)
+    if (cached) return cached
+    const computation = (async () => {
+      const history = await readHistory()
+      const coordinatorState = coordinatorStateAt(history)
+      const compaction = history.find(
+        (event) =>
+          event.type === 'ai.compaction.completed' &&
+          (event.payload as CompactionCompletedPayload<M>).generationId ===
+            call.generationId,
+      )
+      if (compaction !== undefined) {
+        const messages = (
+          compaction.payload as CompactionCompletedPayload<M>
+        ).messages.filter(
+          (message) =>
+            !coordinatorState.queued.some(
+              (queued) => queued.messageId === message.id,
+            ),
+        )
+        return convertToModelMessages(messages, { tools })
+      }
+      const started = history.find(
+        (event) =>
+          event.type === 'ai.generation.started' &&
+          (event.payload as GenerationStartedPayload).generationId ===
+            call.generationId,
+      )
+      const frontier = started?.index ?? Number.POSITIVE_INFINITY
+      const state = replay(
+        options.agent,
+        history.filter((event) => event.index < frontier),
+      )
+      return convertToModelMessages(
+        activeContextMessages(state, coordinatorState),
+        { tools },
+      )
+    })()
+    promptCache.set(key, computation)
+    void computation.catch(() => {
+      if (promptCache.get(key) === computation) promptCache.delete(key)
+    })
+    return computation
+  }
+
+  const toolExecutionFailure = (
+    ctx: ToolHandlerContext,
+    call: ToolCalledPayload,
+    error: unknown,
+  ): AppendInput<D> | void => {
+    const schedulerFailure = consumeSchedulerSendFailure(error)
+    if (ctx.signal.aborted) return
+    if (schedulerFailure === 'retryable') throw error
+    return resultEvent(call, 'execution:error', {
+      error: errorMessage(error),
+    })
+  }
+
+  const runToolExecution = async (
+    ctx: ToolHandlerContext,
+    call: ToolCalledPayload,
+    execute: NonNullable<RuntimeTool['execute']>,
+    messages: ModelMessage[],
+  ): Promise<AppendInput<D> | void> => {
+    let output: unknown
+    try {
+      output = await execute(call.input, {
+        toolCallId: call.toolCallId,
+        messages,
+        abortSignal: ctx.signal,
+      })
+    } catch (error) {
+      return toolExecutionFailure(ctx, call, error)
+    }
+    let iterator: AsyncIterator<unknown> | undefined
+    try {
+      iterator = asyncIterator(output)
+    } catch (error) {
+      return toolExecutionFailure(ctx, call, error)
+    }
+    if (iterator === undefined) {
+      return resultEvent(call, 'execution:0', { output })
+    }
+    let last: unknown
+    let sequence = 0
+    for (;;) {
+      let result: IteratorResult<unknown>
+      try {
+        result = await iterator.next()
+      } catch (error) {
+        return toolExecutionFailure(ctx, call, error)
+      }
+      if (result.done) break
+      if (ctx.signal.aborted) {
+        try {
+          await iterator.return?.()
+        } catch {
+          // The aborted handler cannot record an iterator cleanup failure.
+        }
+        return
+      }
+      last = result.value
+      try {
+        await ctx.session.append(
+          `tool:${call.toolCallId}:preliminary:${sequence}`,
+          resultEvent(call, `execution:${sequence}:preliminary`, {
+            output: result.value,
+            preliminary: true,
+          }),
+        )
+      } catch (error) {
+        try {
+          await iterator.return?.()
+        } catch {
+          // Preserve the append failure that makes the durable handler retry.
+        }
+        throw error
+      }
+      sequence += 1
+    }
+    return resultEvent(
+      call,
+      `execution:${sequence}:final`,
+      sequence === 0 ? {} : { output: last },
+    )
+  }
+
+  const executeTool = async (
+    ctx: ToolHandlerContext,
+    call: ToolCalledPayload,
+  ): Promise<AppendInput<D> | void> => {
+    const tool = tools[call.toolName] as RuntimeTool | undefined
+    const execute = tool?.execute
+    if (execute === undefined) {
+      return resultEvent(call, 'execution:error', {
+        error: `Tool '${call.toolName}' has no server executor`,
+      })
+    }
+    const messages = await promptMessages(
+      ctx.event.sessionId,
+      call,
+      ctx.session.history,
+    )
+    const scope: AmbientToolScope = {
+      contract: options.agent.contract,
+      context: ctx,
+    }
+    // Async iteration resumes in the caller's context, so the whole
+    // execution, not just the execute call, runs inside the scope.
+    return toolScopeStorage.run(scope, () =>
+      runToolExecution(ctx, call, execute, messages),
+    )
+  }
+
+  const handleToolCall = async (
+    ctx: HandlerContext<D, 'ai.tool.called'>,
+  ): Promise<AppendInput<D> | void> => {
+    const state = (await ctx.session.state(coordinator)).state
+    const response = state.response
+    const current = response?.calls.find(
+      (candidate) => candidate.index === ctx.event.index,
+    )
+    if (
+      current === undefined ||
+      response?.generation?.generationId !== ctx.event.payload.generationId ||
+      response.failure !== undefined ||
+      current.terminal ||
+      current.approval !== undefined
+    ) {
+      return
+    }
+    if (current.call.providerExecuted === true) {
+      await continueIfReady(ctx, current.call.generationId)
+      return
+    }
+    return executeTool(ctx, current.call)
+  }
+
+  const handleApproval = async (
+    ctx: HandlerContext<D, 'ai.approval.responded'>,
+  ): Promise<AppendInput<D> | void> => {
+    const state = (await ctx.session.state(coordinator)).state
+    const response = state.response
+    const current = response?.calls.find(
+      (candidate) =>
+        candidate.approval?.approvalId === ctx.event.payload.approvalId &&
+        candidate.approval.messageId === ctx.event.payload.messageId &&
+        candidate.approval.generationId === ctx.event.payload.generationId &&
+        candidate.responseIndex === ctx.event.index,
+    )
+    if (
+      current === undefined ||
+      response?.generation?.generationId !== current.call.generationId ||
+      response.failure !== undefined ||
+      current.terminal
+    ) {
+      return
+    }
+    if (current.call.providerExecuted === true) {
+      await continueIfReady(ctx, current.call.generationId)
+      return
+    }
+    if (!ctx.event.payload.approved) {
+      return resultEvent(current.call, 'execution:denied', { denied: true })
+    }
+    return executeTool(ctx, current.call)
+  }
+
+  const generationHandler = async (
+    ctx: HandlerContext<D, 'ai.generation.requested'>,
+  ): Promise<void | AppendInput<D> | readonly AppendInput<D>[]> => {
+    const history = await ctx.session.history()
+    const requestId = ctx.event.id
+    const request = ctx.event.payload
+    const coordinatorState = (await ctx.session.state(coordinator)).state
+    if (
+      coordinatorState.closed ||
+      coordinatorState.response?.activeRequestId !== requestId
+    ) {
+      return
+    }
+    const terminal = history.some((event) => {
+      if (event.type === 'ai.generation.completed') {
+        return (
+          (event.payload as GenerationCompletedPayload).requestId === requestId
+        )
+      }
+      if (event.type !== 'ai.generation.failed') return false
+      const payload = event.payload as GenerationFailedPayload
+      return payload.requestId === requestId && payload.superseded !== true
+    })
+    if (terminal) return
+
+    const previousStarts = history.filter(
+      (event) =>
+        event.type === 'ai.generation.started' &&
+        (event.payload as GenerationStartedPayload).requestId === requestId,
+    )
+    const priorAttempts = previousStarts.map(
+      (event) => (event.payload as GenerationStartedPayload).attempt,
+    )
+    if (priorAttempts.some((priorAttempt) => priorAttempt >= ctx.attempt)) {
+      return
+    }
+    const attempt = ctx.attempt
+    const generationId = `${requestId}:generation:${attempt}`
+    const responseMessageId =
+      request.responseMessageId ??
+      (request.reason === 'message'
+        ? `${request.messageId}:assistant`
+        : request.messageId)
+
+    const responseStepCount = history.filter(
+      (event) =>
+        event.type === 'ai.generation.completed' &&
+        (event.payload as GenerationCompletedPayload).responseMessageId ===
+          responseMessageId,
+    ).length
+
+    const sourceCoordinatorState = coordinatorStateAt(history, ctx.event.index)
+    if (request.reason === 'tool') {
+      const prefix = 'ai.generate:tools:'
+      if (!requestId.startsWith(prefix)) return
+      const sourceGenerationId = requestId.slice(prefix.length)
+      if (
+        !continuationReady(sourceCoordinatorState) ||
+        sourceCoordinatorState.response?.generation?.generationId !==
+          sourceGenerationId ||
+        sourceCoordinatorState.response.responseMessageId !==
+          request.messageId ||
+        sourceCoordinatorState.response.responseMessageId !==
+          request.responseMessageId
+      ) {
+        return
+      }
+    }
+
+    const previous = previousStarts
+      .filter(
+        (event) =>
+          (event.payload as GenerationStartedPayload).attempt < attempt,
+      )
+      .toSorted(
+        (left, right) =>
+          (right.payload as GenerationStartedPayload).attempt -
+          (left.payload as GenerationStartedPayload).attempt,
+      )[0]
+
+    const incompleteId = previous
+      ? (previous.payload as GenerationStartedPayload).generationId
+      : undefined
+    const replacedGenerationIds = new Set<string>()
+    if (incompleteId !== undefined) replacedGenerationIds.add(incompleteId)
+    if (
+      request.reason === 'retry' &&
+      sourceCoordinatorState.response?.failure?.generationId !== undefined
+    ) {
+      replacedGenerationIds.add(
+        sourceCoordinatorState.response.failure.generationId,
+      )
+    }
+    const promptHistory = withoutGenerationLifecycle(
+      history,
+      replacedGenerationIds,
+    )
+    let state = replay(options.agent, promptHistory)
+    const resolverContext: AgentResolverContext<M, D> = {
+      event: ctx.event,
+      state,
+      history,
+      signal: ctx.signal,
+    }
+
+    const resolvedModel = await resolve(options.model, resolverContext)
+    if (resolvedModel === undefined) {
+      throw new TypeError('the model resolver returned undefined')
+    }
+    if (ctx.signal.aborted) return
+
+    if (request.reason === 'tool' && responseStepCount >= maxSteps) {
+      const source = sourceCoordinatorState.response?.generation
+      if (source === undefined) return
+      return {
+        type: 'ai.generation.failed',
+        id: `${requestId}:step-limit`,
+        payload: {
+          requestId: source.requestId,
+          messageId: source.messageId,
+          generationId: source.generationId,
+          responseMessageId,
+          error: `agent exceeded the ${maxSteps}-step limit`,
+          stepLimit: true,
+        },
+      } as AppendInput<D>
+    }
+
+    const started: GenerationStartedPayload = {
+      requestId,
+      messageId: request.messageId,
+      generationId,
+      responseMessageId,
+      attempt,
+      model: modelName(resolvedModel),
+    }
+    const startEvents: AppendInput<D>[] = []
+    if (previous) {
+      const payload = previous.payload as GenerationStartedPayload
+      const superseded: GenerationFailedPayload = {
+        requestId,
+        messageId: payload.messageId,
+        generationId: payload.generationId,
+        responseMessageId: payload.responseMessageId,
+        error: 'generation attempt was superseded after an incomplete run',
+        superseded: true,
+      }
+      startEvents.push({
+        type: 'ai.generation.failed',
+        id: `${payload.generationId}:superseded`,
+        payload: superseded,
+      } as AppendInput<D>)
+    }
+    startEvents.push({
+      type: 'ai.generation.started',
+      id: generationId,
+      payload: started,
+    } as AppendInput<D>)
+    await ctx.session.append('generation-start', ...startEvents)
+
+    const startedCoordinatorState = (await ctx.session.state(coordinator)).state
+    if (
+      startedCoordinatorState.response?.activeRequestId !== requestId ||
+      startedCoordinatorState.response.generation?.generationId !== generationId
+    ) {
+      return
+    }
+
+    const promptCoordinatorState = {
+      ...coordinatorStateAt(history),
+      queued: queuedMessagesAt(history),
+    }
+    let messages = activeContextMessages(state, promptCoordinatorState)
+    if (options.compaction) {
+      const compactionContext = { ...resolverContext, messages }
+      if (await options.compaction.shouldCompact(compactionContext)) {
+        const throughMessageId = messages.at(-1)?.id ?? request.messageId
+        await ctx.session.append('compaction-requested', {
+          type: 'ai.compaction.requested',
+          id: `${generationId}:compaction:requested`,
+          payload: { generationId, throughMessageId },
+        })
+        messages = await options.compaction.compact(compactionContext)
+        const completed: CompactionCompletedPayload<M> = {
+          generationId,
+          throughMessageId,
+          messages,
+          ...(promptCoordinatorState.queued.length === 0
+            ? {}
+            : {
+                retainedMessageIds: promptCoordinatorState.queued.map(
+                  (item) => item.messageId,
+                ),
+              }),
+        }
+        await ctx.session.append('compaction-completed', {
+          type: 'ai.compaction.completed',
+          id: `${generationId}:compaction:completed`,
+          payload: completed,
+        })
+        state = {
+          ...state,
+          compaction: { status: 'completed', ...completed },
+        }
+      }
+    }
+
+    const currentState = (await ctx.session.state(options.agent.reducer)).state
+    const currentCoordinatorState = (await ctx.session.state(coordinator)).state
+    const generationMessages = activeContextMessages(
+      currentState,
+      currentCoordinatorState,
+    )
+    promptCache.set(
+      promptCacheKey(ctx.event.sessionId, generationId),
+      convertToModelMessages(generationMessages, { tools }),
+    )
+
+    let pendingToolCalls: PendingToolCall[] = []
+    try {
+      const resolvedInstructions =
+        options.instructions === undefined
+          ? undefined
+          : await resolve(options.instructions, resolverContext)
+      const generateContext: AgentGenerateContext<M, D, T> = {
+        request: ctx.event,
+        requestId,
+        generationId,
+        responseMessageId,
+        messages: generationMessages,
+        state: currentState,
+        history,
+        signal: ctx.signal,
+        model: resolvedModel,
+        tools,
+        ...(resolvedInstructions === undefined
+          ? {}
+          : { instructions: resolvedInstructions }),
+        generation: options.generation ?? {},
+      }
+      const custom = options.generate !== undefined
+      const source =
+        options.generate === undefined
+          ? await generateWithAISDK(generateContext, options.messageMetadata)
+          : { stream: await options.generate(generateContext) }
+      const updates = consumeGeneration({
+        source,
+        ...(options.progress === undefined
+          ? {}
+          : { progress: options.progress }),
+      })
+
+      let sequence = 0
+      let finish: AgentGenerationFinish | undefined
+      for await (const update of updates) {
+        ctx.signal.throwIfAborted()
+        if (update.type === 'finish') {
+          finish = update
+          continue
+        }
+        const progress: GenerationProgressPayload = {
+          requestId,
+          messageId: request.messageId,
+          generationId,
+          responseMessageId,
+          sequence,
+          chunks: update.chunks,
+        }
+        const lifecycle = lifecycleEvents<D, T>({
+          requestId,
+          messageId: responseMessageId,
+          generationId,
+          sequence,
+          chunks: update.chunks,
+          pending: pendingToolCalls,
+          tools,
+          generation,
+          custom,
+        })
+        pendingToolCalls = lifecycle.pending
+        await ctx.session.append(
+          `generation-progress:${sequence}`,
+          {
+            type: 'ai.generation.progress',
+            id: `${generationId}:progress:${sequence}`,
+            payload: progress,
+          },
+          ...lifecycle.events,
+        )
+        sequence += 1
+      }
+
+      if (!finish) throw new Error('agent generation finished without output')
+      const completed: GenerationCompletedPayload = {
+        requestId,
+        messageId: request.messageId,
+        generationId,
+        responseMessageId,
+        ...(finish.finishReason === undefined
+          ? {}
+          : { finishReason: finish.finishReason }),
+        ...(finish.usage === undefined ? {} : { usage: finish.usage }),
+      }
+      const completionEvent = {
+        type: 'ai.generation.completed',
+        id: `${generationId}:completed`,
+        payload: completed,
+      } as AppendInput<D>
+      const unresolved = options.generate
+        ? pendingToolCalls.filter(
+            (pending) => pending.classification !== 'automatic',
+          )
+        : []
+      if (unresolved.length > 0) {
+        throw new Error(
+          `generation ended with unresolved tool authorization for '${unresolved[0]!.call.toolName}'`,
+        )
+      }
+      const pendingEvents = pendingToolCalls
+        .filter(
+          (pending) =>
+            pending.classification === 'automatic' ||
+            (options.generate === undefined &&
+              pending.classification === 'unknown'),
+        )
+        .map((pending) => toolCalledEvent<D>(pending.call))
+      if (finish.finishReason === 'tool-calls') {
+        return [...pendingEvents, completionEvent]
+      }
+      return [
+        ...pendingEvents,
+        completionEvent,
+        {
+          type: 'ai.message.completed',
+          id: `${generationId}:message:completed`,
+          payload: {
+            messageId: responseMessageId,
+          } satisfies MessageCompletedPayload,
+        } as AppendInput<D>,
+      ]
+    } catch (error) {
+      if (error instanceof A2Error) throw error
+      if (ctx.signal.aborted) {
+        const interrupted: MessageInterruptedPayload = {
+          messageId: responseMessageId,
+          generationId,
+          reason: 'aborted',
+        }
+        return {
+          type: 'ai.message.interrupted',
+          id: `${generationId}:interrupted`,
+          payload: interrupted,
+        } as AppendInput<D>
+      }
+      const failed: GenerationFailedPayload = {
+        requestId,
+        messageId: request.messageId,
+        generationId,
+        responseMessageId,
+        error: errorMessage(error),
+      }
+      return {
+        type: 'ai.generation.failed',
+        id: `${generationId}:failed`,
+        payload: failed,
+      } as AppendInput<D>
+    }
+  }
+
+  const handleMessageCreated = async (
+    ctx: HandlerContext<D, 'ai.message.created'>,
+  ): Promise<AppendInput<D> | void> => {
+    if (
+      ctx.event.payload.message.role !== 'user' ||
+      ctx.event.payload.generate === false
+    ) {
+      return
+    }
+    return scheduleNext(ctx)
+  }
+
+  const handleRetry = async (
+    ctx: HandlerContext<D, 'ai.retry.requested'>,
+  ): Promise<AppendInput<D> | void> => {
+    const state = (await ctx.session.state(coordinator)).state
+    const response = state.response
+    if (
+      response?.status !== 'failed' ||
+      response.rootMessageId !== ctx.event.payload.messageId ||
+      response.responseMessageId !== ctx.event.payload.responseMessageId
+    ) {
+      return
+    }
+    return {
+      type: 'ai.generation.requested',
+      id: `ai.generate:retry:${ctx.event.payload.retryId}`,
+      payload: {
+        messageId: response.rootMessageId,
+        responseMessageId: response.responseMessageId,
+        reason: 'retry',
+      },
+    } as AppendInput<D>
+  }
+
+  const handleInputResponse = async (
+    ctx: HandlerContext<D, 'ai.input.responded'>,
+  ): Promise<void> => {
+    const state = (await ctx.session.state(coordinator)).state
+    const response = state.response
+    if (
+      response?.responseMessageId !== ctx.event.payload.messageId ||
+      response.inputResponse?.index !== ctx.event.index ||
+      response.inputResponse.generationId !== ctx.event.payload.generationId ||
+      response.inputResponse.inputId !== ctx.event.payload.inputId
+    ) {
+      return
+    }
+    await continueIfReady(ctx, ctx.event.payload.generationId)
+  }
+
+  const clearPromptCache = (sessionId: string): void => {
+    const prefix = `${sessionId}\u001f`
+    for (const key of promptCache.keys()) {
+      if (key.startsWith(prefix)) promptCache.delete(key)
+    }
+  }
+
+  const handleResponseEnded = async (
+    ctx: HandlerContext<D, 'ai.message.completed' | 'ai.message.interrupted'>,
+  ): Promise<AppendInput<D> | void> => {
+    clearPromptCache(ctx.event.sessionId)
+    return scheduleNext(ctx)
+  }
+
+  return {
+    'ai.message.created': { lane: 'a2.ai.turn', handler: handleMessageCreated },
+    'ai.retry.requested': { lane: 'a2.ai.turn', handler: handleRetry },
+    'ai.input.responded': {
+      lane: 'a2.ai.turn',
+      handler: handleInputResponse,
+    },
+    'ai.message.completed': {
+      lane: 'a2.ai.turn',
+      handler: handleResponseEnded,
+    },
+    'ai.message.interrupted': {
+      lane: 'a2.ai.turn',
+      handler: handleResponseEnded,
+    },
+    'ai.session.closed': {
+      handler: (ctx) => {
+        clearPromptCache(ctx.event.sessionId)
+        return Promise.resolve()
+      },
+    },
+    'ai.generation.failed': {
+      handler: (ctx) => {
+        promptCache.delete(
+          promptCacheKey(ctx.event.sessionId, ctx.event.payload.generationId),
+        )
+        return Promise.resolve()
+      },
+    },
+    'ai.generation.requested': {
+      lane: 'a2.ai.turn',
+      abortOn: {
+        'ai.message.interrupted': (event, trigger, context) => {
+          const responseMessageId =
+            trigger.payload.responseMessageId ??
+            (trigger.payload.reason === 'message'
+              ? `${trigger.payload.messageId}:assistant`
+              : trigger.payload.messageId)
+          return (
+            event.payload.messageId === responseMessageId &&
+            (event.payload.requestId === trigger.id ||
+              event.payload.generationId ===
+                `${trigger.id}:generation:${context.attempt}`)
+          )
+        },
+        'ai.session.closed': true,
+      },
+      handler: generationHandler,
+    },
+    'ai.generation.completed': {
+      handler: async (ctx) =>
+        continueIfReady(ctx, ctx.event.payload.generationId),
+    },
+    'ai.tool.called': {
+      abortOn: {
+        'ai.generation.failed': (event, trigger) =>
+          event.payload.generationId === trigger.payload.generationId,
+        'ai.message.interrupted': (event, trigger) =>
+          event.payload.messageId === trigger.payload.messageId &&
+          (event.payload.requestId === trigger.payload.requestId ||
+            event.payload.generationId === trigger.payload.generationId),
+        'ai.session.closed': true,
+      },
+      handler: handleToolCall,
+    },
+    'ai.approval.responded': {
+      abortOn: {
+        'ai.generation.failed': (event, trigger) =>
+          event.payload.responseMessageId === trigger.payload.messageId &&
+          event.payload.generationId === trigger.payload.generationId,
+        'ai.message.interrupted': (event, trigger) =>
+          event.payload.messageId === trigger.payload.messageId &&
+          (event.payload.requestId ===
+            generationRequestId(trigger.payload.generationId) ||
+            event.payload.generationId === trigger.payload.generationId),
+        'ai.session.closed': true,
+      },
+      handler: handleApproval,
+    },
+    'ai.tool.result': {
+      handler: async (ctx) => {
+        if (ctx.event.payload.preliminary === true) return
+        await continueIfReady(ctx, ctx.event.payload.generationId)
+      },
+    },
+  } as NonNullable<ServerOptions<D>['handlers']>
+}
+
+/** Assemble an A2 server with the built-in agent handlers and app extensions. */
+export function createAgentServer<
+  M extends UIMessage,
+  D extends AIEventDefs<M> & EventDefs,
+  T extends ToolSet = ToolSet,
+>(options: CreateAgentServerOptions<M, D, T>): A2Server<D> {
+  const {
+    agent: definition,
+    model,
+    tools,
+    instructions,
+    generation,
+    maxSteps,
+    messageMetadata,
+    generate,
+    compaction,
+    progress,
+    handlers,
+    ...serverOptions
+  } = options
+  const builtIns = createHandlers({
+    agent: definition,
+    model,
+    ...(tools === undefined ? {} : { tools }),
+    ...(instructions === undefined ? {} : { instructions }),
+    ...(generation === undefined ? {} : { generation }),
+    ...(maxSteps === undefined ? {} : { maxSteps }),
+    ...(messageMetadata === undefined ? {} : { messageMetadata }),
+    ...(generate === undefined ? {} : { generate }),
+    ...(compaction === undefined ? {} : { compaction }),
+    ...(progress === undefined ? {} : { progress }),
+  })
+  return createServer({
+    ...serverOptions,
+    contract: definition.contract,
+    handlers: { ...builtIns, ...handlers },
+    validatePush: validateAgentPush,
+  })
+}
+
+export type { Instructions, LanguageModel, ToolSet }