experimental-a2 0.16.1 → 0.17.0

package/src/ai-server.ts

@@ -1,1970 +1,26 @@
 /**
- * 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.
+ * experimental-a2/ai/server — `agent()`: the experimental-a2/ai protocol,
+ * its model and tool handlers, and A2's store, scheduler, and telemetry,
+ * assembled as one ordinary A2 server.
  */
 
-// oxlint-disable no-await-in-loop -- stream chunks and durable appends are
-// ordered; parallel consumption would corrupt progress sequence and state.
-
-import { createControlRuntime, ControlCancelled } from './ai-control-server.ts'
-import {
-  createContextReducer,
-  contextForAttempt,
-  generationBase,
-  type AIContextState,
-  type AIModelContext,
-} from './ai-context.ts'
-import type { Reducer } from './reducer.ts'
-import { aiStateReducer } from './ai-stored-state.ts'
-import { aiEventId, AI_EVENT_ID_PREFIX } from './ai-id.ts'
-import type { ControlCommit, ControlCommand } from './ai-control.ts'
-import { AsyncLocalStorage } from 'node:async_hooks'
-import { createHash } from 'node:crypto'
-import { convertToModelMessages, isToolUIPart } from 'ai'
-import type {
-  FinishReason,
+export { agent, runWithHandlerContext } from './ai-agent.ts'
+export type {
+  Agent,
+  AgentFromContractOptions,
+  AgentGenerate,
+  AgentGenerateContext,
+  AgentGenerationSettings,
+  AgentMessageMetadata,
+  AgentModelOptions,
+  AgentOptions,
+  AgentResolverContext,
+  AutomaticCompaction,
+  CompactionOptions,
+  CompactionPolicy,
   Instructions,
   LanguageModel,
-  LanguageModelUsage,
-  ModelMessage,
-  TextStreamPart,
+  ModelSettings,
+  Resolvable,
   ToolSet,
-  UIMessage,
-  UIMessageChunk,
-} from 'ai'
-import { generateAISDKStep, type AISDKStepSettings } from './ai-sdk-step.ts'
-import { gatewayModelId, readModelLimits } from './ai-model-metadata.ts'
-import { estimateInputTokens, measuredInputTokens } from './ai-input-tokens.ts'
-import type {
-  AIEventDefs,
-  AgentDefinition,
-  AgentToolContext,
-  AgentToolEventDefs,
-  ApprovalRequestedPayload,
-  CompactionCompletedPayload,
-  CompactionRequestedPayload,
-  GenerationCompletedPayload,
-  GenerationFailedPayload,
-  GenerationProgressPayload,
-  GenerationStartedPayload,
-  MessageCompletedPayload,
-  ToolCalledPayload,
-  ToolResultPayload,
-} from './ai.ts'
-import 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 ServerOptions,
-} from './server.ts'
-import {
-  setServerFetchHooks,
-  type ServerIngressContext,
-} from './server-fetch.ts'
-
-function validateAgentIngress(context: ServerIngressContext): void {
-  const rejected = context.events.find((event) => {
-    if (event.type !== 'ai.control.requested') return true
-    const command = event.payload as Record<string, unknown>
-    if (
-      command['action'] === 'request-input' ||
-      command['action'] === 'tool-result'
-    )
-      return true
-    if (
-      command['action'] === 'send' ||
-      command['action'] === 'edit' ||
-      command['action'] === 'steer'
-    ) {
-      return (
-        (command['message'] as { role?: unknown } | undefined)?.role !== 'user'
-      )
-    }
-    return false
-  })
-  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[]
-  modelMessages: ModelMessage[]
-  session: Pick<HandlerContext<D>['session'], 'state'>
-  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'>
-  messages: M[]
-  session: Pick<HandlerContext<D>['session'], 'state'>
-  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[]
-      modelMessages: ModelMessage[]
-    },
-  ): boolean | Promise<boolean>
-  compact(
-    context: AgentResolverContext<M, D> & {
-      messages: M[]
-      modelMessages: ModelMessage[]
-    },
-  ): M[] | Promise<M[]>
-}
-
-export type AutomaticCompaction = {
-  thresholdTokens?: number
-  instructions?: string
-}
-
-export type CompactionOptions<
-  M extends UIMessage,
-  D extends AIEventDefs<M> & EventDefs,
-> = false | AutomaticCompaction | CompactionPolicy<M, D>
-
-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?: Resolvable<CompactionOptions<M, D>, AgentResolverContext<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'> & {
-    handlers?: ServerOptions<D>['handlers']
-  }
-
-const checkAbort = (signal: AbortSignal): boolean => {
-  if (!signal.aborted) return false
-  const reason: unknown = signal.reason
-  if (
-    reason instanceof A2Error &&
-    (reason.code === 'CLAIM_EXPIRED' || reason.code === 'SUPERSEDED_ATTEMPT')
-  ) {
-    throw reason
-  }
-  return true
-}
-
-const resolve = async <T, C extends { signal: AbortSignal }>(
-  value: Resolvable<T, C>,
-  context: C,
-): Promise<T> => {
-  let result: T
-  try {
-    result =
-      typeof value === 'function'
-        ? await (value as (context: C) => T | Promise<T>)(context)
-        : value
-  } catch (error) {
-    checkAbort(context.signal)
-    throw error
-  }
-  checkAbort(context.signal)
-  return result
-}
-
-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')
-
-type StreamRead<T> = Awaited<ReturnType<ReadableStreamDefaultReader<T>['read']>>
-
-const nextOrTimer = async <T>(
-  next: Promise<StreamRead<T>>,
-  delayMs: number,
-): Promise<{ type: 'next'; result: StreamRead<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,
->(options: {
-  agentName: string
-  context: AgentGenerateContext<M, D, T>
-  messageMetadata: AgentMessageMetadata<M, D, T> | undefined
-}): Promise<GenerationSource> {
-  const { agentName, context, messageMetadata } = options
-  const headers = context.generation.headers ?? {}
-  const generation =
-    gatewayModelId(context.model) === undefined
-      ? context.generation
-      : {
-          ...context.generation,
-          headers: Object.keys(headers).some(
-            (key) => key.toLowerCase() === 'x-session-affinity',
-          )
-            ? headers
-            : {
-                ...headers,
-                'x-session-affinity': createHash('sha256')
-                  .update(
-                    JSON.stringify([agentName, context.request.sessionId]),
-                  )
-                  .digest('hex'),
-              },
-          providerOptions: {
-            ...context.generation.providerOptions,
-            gateway: {
-              caching: 'auto',
-              ...context.generation.providerOptions?.['gateway'],
-            },
-          },
-        }
-  const step = await generateAISDKStep<M, T>({
-    model: context.model,
-    tools: context.tools,
-    messages: context.messages,
-    modelMessages: context.modelMessages,
-    responseMessageId: context.responseMessageId,
-    abortSignal: context.signal,
-    ...(context.instructions === undefined
-      ? {}
-      : { instructions: context.instructions }),
-    settings: generation,
-    ...(messageMetadata === undefined
-      ? {}
-      : {
-          messageMetadata: ({ part }) =>
-            messageMetadata({ ...context, generation, 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 reader = options.source.stream.getReader()
-  let pendingChunk = reader.read()
-  try {
-    for (;;) {
-      let result: StreamRead<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 = reader.read()
-
-      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
-  } finally {
-    void pendingChunk.catch(() => {})
-    try {
-      await reader.cancel()
-    } catch {
-      // Cleanup must not replace the error that ended generation.
-    } finally {
-      reader.releaseLock()
-    }
-  }
-
-  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 foldAIEvents = <
-  M extends UIMessage,
-  D extends AIEventDefs<M> & EventDefs,
->(options: {
-  reducer: Reducer<D, AIContextState<M>>
-  state: AIContextState<M>
-  events: ContractEvent<D>[]
-}): AIContextState<M> => {
-  let state = options.state
-  for (const event of options.events) state = options.reducer.fold(state, event)
-  return state
-}
-
-const summarize = async <
-  M extends UIMessage,
-  D extends AIEventDefs<M> & EventDefs,
-  T extends ToolSet,
->(options: {
-  agentName: string
-  context: AgentGenerateContext<M, D, T>
-  instructions: string | undefined
-}): Promise<{ summary: string; usage?: LanguageModelUsage }> => {
-  const instruction = [
-    'Summarize this conversation so you can continue the task after the earlier context is replaced by your summary.',
-    'Preserve the objective, constraints, decisions, exact identifiers, completed actions and their results, unresolved questions, and next steps. Distinguish observations from assumptions.',
-    'Respond only with the summary as text. Do not call any tools or continue working on the task.',
-    options.instructions,
-  ]
-    .filter(Boolean)
-    .join('\n')
-  const generation = { ...options.context.generation }
-  for (const key of Object.keys(generation)) {
-    if (
-      key.startsWith('on') ||
-      key.startsWith('experimental_on') ||
-      [
-        'repairToolCall',
-        'experimental_repairToolCall',
-        'experimental_refineToolInput',
-        'experimental_transform',
-        'toolApproval',
-      ].includes(key)
-    ) {
-      Reflect.deleteProperty(generation, key)
-    }
-  }
-  const tools = Object.fromEntries(
-    Object.entries(options.context.tools).map(([name, tool]) => {
-      const definition = { ...tool, needsApproval: false }
-      for (const key of [
-        'execute',
-        'onInputStart',
-        'onInputDelta',
-        'onInputAvailable',
-      ]) {
-        Reflect.deleteProperty(definition, key)
-      }
-      return [name, definition]
-    }),
-  ) as T
-  const source = await generateWithAISDK({
-    agentName: options.agentName,
-    context: {
-      ...options.context,
-      generation,
-      tools,
-      modelMessages: [
-        ...options.context.modelMessages,
-        { role: 'user', content: instruction },
-      ],
-      responseMessageId: await aiEventId(
-        'a2.ai.summary',
-        options.context.generationId,
-      ),
-    },
-    messageMetadata: undefined,
-  })
-  let summary = ''
-  let calledTool = false
-  let finish: AgentGenerationFinish | undefined
-  for await (const update of consumeGeneration({ source })) {
-    options.context.signal.throwIfAborted()
-    if (update.type === 'finish') {
-      finish = update
-      continue
-    }
-    for (const chunk of update.chunks) {
-      if (chunk.type === 'text-delta') summary += chunk.delta
-      if (chunk.type.startsWith('tool-')) calledTool = true
-    }
-  }
-  if (
-    calledTool ||
-    summary.trim().length === 0 ||
-    finish?.finishReason !== 'stop'
-  ) {
-    throw new Error(
-      'compaction must produce a complete text summary without calling tools',
-    )
-  }
-  return {
-    summary,
-    ...(finish.usage === undefined ? {} : { usage: finish.usage }),
-  }
-}
-
-const activeCompaction = <M extends UIMessage>(
-  state: AIModelContext<M>,
-): AIModelContext<M>['compaction'] => {
-  const compaction = state.compaction
-  return compaction?.status === 'completed' ? compaction : null
-}
-
-const contextMessages = <M extends UIMessage>({
-  state,
-  coordinator,
-}: {
-  state: AIModelContext<M>
-  coordinator: AICoordinatorState
-}): M[] => {
-  const queued = new Set(coordinator.queued.map((item) => item.messageId))
-  return state.messages.filter((message) => !queued.has(message.id))
-}
-
-const modelContext = async <M extends UIMessage>(options: {
-  messages: M[]
-  state: AIModelContext<M>
-  tools: ToolSet
-}): Promise<ModelMessage[]> => {
-  const messages = await convertToModelMessages(options.messages, {
-    tools: options.tools,
-  })
-  const summary = activeCompaction(options.state)?.summary
-  return summary === undefined
-    ? messages
-    : [{ role: 'user', content: summary }, ...messages]
-}
-
-type ToolCallClassification = 'automatic' | 'approval' | 'unknown'
-
-type PendingToolCall = {
-  call: ToolCalledPayload
-  classification: ToolCallClassification
-}
-
-const toolCalledEvent = async <D extends EventDefs>(
-  payload: ToolCalledPayload,
-): Promise<AppendInput<D>> =>
-  ({
-    type: 'ai.tool.called',
-    id: await aiEventId(
-      'a2.ai.tool.called',
-      payload.generationId,
-      payload.toolCallId,
-    ),
-    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 = async <
-  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
-}): Promise<{ 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 = async (toolCallId: string): Promise<void> => {
-    const pendingCall = take(toolCallId)
-    if (pendingCall) result.push(await toolCalledEvent<D>(pendingCall.call))
-  }
-  for (const [chunkIndex, chunk] of options.chunks.entries()) {
-    const resultId = (): Promise<string> =>
-      aiEventId(
-        'a2.ai.tool.stream-result',
-        options.generationId,
-        String(options.sequence),
-        String(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(await 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(await toolCalledEvent<D>(called), {
-        type: 'ai.tool.result',
-        id: await resultId(),
-        payload,
-      } as AppendInput<D>)
-    } else if (chunk.type === 'tool-output-available') {
-      await 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: await resultId(),
-        payload,
-      } as AppendInput<D>)
-    } else if (chunk.type === 'tool-output-error') {
-      await 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: await resultId(),
-        payload,
-      } as AppendInput<D>)
-    } else if (chunk.type === 'tool-output-denied') {
-      await 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: await resultId(),
-        payload,
-      } as AppendInput<D>)
-    } else if (chunk.type === 'tool-approval-request') {
-      await flush(chunk.toolCallId)
-      const payload: ApprovalRequestedPayload = {
-        requestId: options.requestId,
-        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: await aiEventId(
-          'a2.ai.approval.requested',
-          options.generationId,
-          chunk.approvalId,
-        ),
-        payload,
-      } as AppendInput<D>)
-    } else if (chunk.type === 'tool-approval-response') {
-      result.push({
-        type: 'ai.approval.responded',
-        id: await aiEventId(
-          'a2.ai.approval.automatic-response',
-          options.generationId,
-          chunk.approvalId,
-        ),
-        payload: {
-          requestId: options.requestId,
-          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 }
-}
-
-const validateCompaction = <
-  M extends UIMessage,
-  D extends AIEventDefs<M> & EventDefs,
-  T extends ToolSet,
->(options: {
-  compaction: CompactionOptions<M, D>
-  explicit: boolean
-  generation: AgentGenerationSettings<T> | undefined
-  tools: T | undefined
-}): CompactionOptions<M, D> => {
-  let compaction = options.compaction
-  if (
-    compaction !== false &&
-    (typeof compaction !== 'object' || compaction === null)
-  ) {
-    throw new TypeError('compaction must resolve to false or a policy object')
-  }
-  if (compaction !== false && 'then' in compaction) {
-    void Promise.resolve(compaction).catch(() => {})
-    throw new TypeError('compaction options must be a policy or a resolver')
-  }
-  if (compaction !== false && !('shouldCompact' in compaction)) {
-    if (
-      compaction.thresholdTokens !== undefined &&
-      (!Number.isSafeInteger(compaction.thresholdTokens) ||
-        compaction.thresholdTokens < 1)
-    ) {
-      throw new TypeError(
-        'compaction.thresholdTokens must be a positive safe integer',
-      )
-    }
-    const choice = options.generation?.toolChoice
-    const unsupported =
-      options.generation?.output !== undefined
-        ? 'structured output'
-        : choice !== undefined && choice !== 'auto' && choice !== 'none'
-          ? 'forced tool choice'
-          : Object.values(options.tools ?? {}).some(
-                (tool) =>
-                  tool.type === 'provider' && tool.isProviderExecuted === true,
-              )
-            ? 'provider-executed tools'
-            : undefined
-    if (unsupported !== undefined) {
-      if (options.explicit) {
-        throw new TypeError(
-          `automatic compaction does not support ${unsupported}; use a custom policy or compaction: false`,
-        )
-      }
-      compaction = false
-    }
-  }
-
-  return compaction
-}
-
-/**
- * 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 configuredCompaction =
-    options.compaction ?? (options.generate === undefined ? {} : false)
-  const staticCompaction =
-    typeof configuredCompaction === 'function'
-      ? undefined
-      : validateCompaction({
-          compaction: configuredCompaction,
-          explicit: options.compaction !== undefined,
-          generation: options.generation,
-          tools: options.tools,
-        })
-
-  const tools = options.tools ?? ({} as T)
-  const generation: AgentGenerationSettings<T> = options.generation ?? {}
-  const maxSteps = options.maxSteps ?? Number.POSITIVE_INFINITY
-  const control = createControlRuntime({ agent: options.agent })
-  const coordinator = control.coordinator
-  const contextReducer = createContextReducer({ agent: options.agent })
-  const readContext = async (
-    session: HandlerContext<D>['session'],
-    through: number | 'latest',
-  ) => {
-    const snapshot = await session.state(contextReducer, { through })
-    return { state: contextReducer.view(snapshot.state), index: snapshot.index }
-  }
-  const promptCache = new Map<string, Promise<ModelMessage[]>>()
-
-  type RuntimeTool = {
-    execute?: (
-      input: unknown,
-      options: {
-        toolCallId: string
-        messages: ModelMessage[]
-        abortSignal?: AbortSignal
-      },
-    ) => unknown
-  }
-
-  type ToolHandlerContext = HandlerContext<D, 'ai.tool.execution.requested'>
-
-  const resultEvent = async (
-    call: ToolCalledPayload,
-    suffix: string,
-    result: {
-      output?: unknown
-      error?: string
-      denied?: boolean
-      preliminary?: boolean
-    },
-  ): Promise<AppendInput<D>> =>
-    ({
-      type: 'ai.tool.result',
-      id: await aiEventId(
-        'a2.ai.tool.result',
-        call.generationId,
-        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 = (input: {
-    ctx: ToolHandlerContext
-    call: ToolCalledPayload
-    generation: GenerationStartedPayload
-  }): Promise<ModelMessage[]> => {
-    const { ctx, call, generation: owner } = input
-    const key = promptCacheKey(ctx.event.sessionId, call.generationId)
-    const cached = promptCache.get(key)
-    if (cached) return cached
-    const computation = (async () => {
-      const frontier = owner.promptThroughIndex
-      if (frontier === undefined)
-        throw new TypeError('AI work requires a prompt checkpoint')
-      const snapshot = await readContext(ctx.session, ctx.event.index)
-      if (
-        snapshot.state.generation?.owner.generationId !== owner.generationId ||
-        snapshot.state.generation.owner.requestId !== owner.requestId ||
-        snapshot.state.activeProjection?.generationId !== owner.generationId
-      )
-        throw new TypeError(
-          'Tool prompt checkpoint does not own its generation',
-        )
-      const state = generationBase(snapshot.state)
-      return modelContext({
-        messages: state.messages.filter(
-          (message) => state.messageIndexes[message.id]! <= frontier,
-        ),
-        state,
-        tools,
-      })
-    })()
-    promptCache.set(key, computation)
-    void computation.catch(() => {
-      if (promptCache.get(key) === computation) promptCache.delete(key)
-    })
-    return computation
-  }
-
-  const toolExecutionFailure = async (
-    ctx: ToolHandlerContext,
-    call: ToolCalledPayload,
-    error: unknown,
-  ): Promise<AppendInput<D> | void> => {
-    const schedulerFailure = consumeSchedulerSendFailure(error)
-    if (checkAbort(ctx.signal)) return
-    if (schedulerFailure === 'retryable') throw error
-    return resultEvent(call, `${ctx.event.id}: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, `${ctx.event.id}:execution:0`, { output })
-    }
-    let last: unknown
-    let sequence = 0
-    let done = false
-    try {
-      for (;;) {
-        let result: IteratorResult<unknown>
-        try {
-          result = await iterator.next()
-        } catch (error) {
-          return toolExecutionFailure(ctx, call, error)
-        }
-        if (result.done) {
-          if (ctx.signal.reason instanceof A2Error) throw ctx.signal.reason
-          done = true
-          break
-        }
-        if (checkAbort(ctx.signal)) return
-        last = result.value
-        await control.append({
-          ctx,
-          name: `tool:${call.toolCallId}:preliminary:${sequence}`,
-          events: [
-            await resultEvent(
-              call,
-              `${ctx.event.id}:execution:${ctx.attempt}:${sequence}:preliminary`,
-              {
-                output: result.value,
-                preliminary: true,
-              },
-            ),
-          ],
-        })
-        sequence += 1
-      }
-    } finally {
-      if (!done) {
-        try {
-          await iterator.return?.()
-        } catch {
-          // Preserve the failure or cancellation that ended execution.
-        }
-      }
-    }
-    return resultEvent(
-      call,
-      `${ctx.event.id}:execution:${sequence}:final`,
-      sequence === 0 ? {} : { output: last },
-    )
-  }
-
-  const executeTool = async (input: {
-    ctx: ToolHandlerContext
-    call: ToolCalledPayload
-    generation: GenerationStartedPayload
-  }): Promise<AppendInput<D> | void> => {
-    const { ctx, call } = input
-    const tool = tools[call.toolName] as RuntimeTool | undefined
-    const execute = tool?.execute
-    if (execute === undefined) {
-      return resultEvent(call, `${ctx.event.id}:execution:error`, {
-        error: `Tool '${call.toolName}' has no server executor`,
-      })
-    }
-    const messages = await promptMessages(input)
-    if (checkAbort(ctx.signal)) return
-    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 handleToolExecution = async (
-    ctx: ToolHandlerContext,
-  ): Promise<AppendInput<D>> => {
-    try {
-      const state = (
-        await ctx.session.state(control.reducer, { through: 'latest' })
-      ).state
-      const request = ctx.event.payload
-      const call = state.coordinator.response?.calls.find(
-        (candidate) => candidate.work?.id === ctx.event.id,
-      )
-      if (
-        state.active?.turnId !== request.turnId ||
-        Object.values(state.pendingStops).includes(request.turnId) ||
-        state.active.suspended ||
-        state.active.version !== request.version ||
-        state.coordinator.response?.failure !== undefined ||
-        !call ||
-        call.terminal ||
-        call.work?.settled
-      )
-        return control.settled({ ctx, events: undefined })
-      return control.settled({
-        ctx,
-        events: await executeTool({
-          ctx,
-          call: request.call,
-          generation: request.generation,
-        }),
-      })
-    } catch (error) {
-      if (control.cancelled({ error, signal: ctx.signal }))
-        return control.settled({ ctx, events: undefined })
-      throw error
-    }
-  }
-
-  const generationHandler = async (
-    ctx: HandlerContext<D, 'ai.generation.requested'>,
-  ): Promise<void | AppendInput<D> | readonly AppendInput<D>[]> => {
-    if (checkAbort(ctx.signal)) return
-    const requestId = ctx.event.id
-    const request = ctx.event.payload
-    const snapshot = await readContext(ctx.session, 'latest')
-    if (
-      snapshot.state.closed ||
-      snapshot.state.authority?.requestId !== requestId ||
-      snapshot.state.authority?.phase === 'paused' ||
-      snapshot.state.authority?.phase === 'pausing'
-    )
-      return
-    const controlState = (
-      await ctx.session.state(control.reducer, { through: snapshot.index })
-    ).state
-    if (
-      request.control !== undefined &&
-      Object.values(controlState.pendingStops).includes(request.control.turnId)
-    )
-      return
-    const coordinatorState = controlState.coordinator
-    if (
-      coordinatorState.closed ||
-      coordinatorState.response?.activeRequestId !== requestId
-    )
-      return
-    const response = coordinatorState.response
-    const current =
-      response.generation?.requestId === requestId
-        ? response.generation
-        : undefined
-    if (
-      current !== undefined &&
-      (response.completion !== undefined ||
-        (response.failure !== undefined &&
-          response.failure.superseded !== true))
-    )
-      return
-    if (current !== undefined && current.attempt >= ctx.attempt) return
-    const attempt = ctx.attempt
-    const generationId = await aiEventId(
-      'a2.ai.generation',
-      requestId,
-      String(attempt),
-    )
-    const responseMessageId = request.responseMessageId
-    const responseStepCount = response.stepCount
-    if (
-      request.reason === 'tool' &&
-      (request.sourceGenerationId !==
-        response.source?.generation.generationId ||
-        response.responseMessageId !== request.messageId ||
-        response.responseMessageId !== request.responseMessageId)
-    )
-      return
-    const previous = current
-    const state =
-      previous === undefined
-        ? snapshot.state
-        : contextForAttempt(snapshot.state)
-    const resolverContext: AgentResolverContext<M, D> = {
-      event: ctx.event,
-      messages: contextMessages({ state, coordinator: coordinatorState }),
-      session: {
-        state: (reducer, readOptions) =>
-          ctx.session.state(reducer, {
-            ...readOptions,
-            through: readOptions?.through ?? snapshot.index,
-          }),
-      },
-      signal: ctx.signal,
-    }
-
-    let generationStarted = false
-    try {
-      const resolvedModel = await resolve(options.model, resolverContext)
-      if (resolvedModel === undefined) {
-        throw new TypeError('the model resolver returned undefined')
-      }
-      if (checkAbort(ctx.signal)) return
-      const resolvedInstructions =
-        options.instructions === undefined
-          ? undefined
-          : await resolve(options.instructions, resolverContext)
-      if (checkAbort(ctx.signal)) return
-      const compaction =
-        typeof configuredCompaction === 'function'
-          ? validateCompaction({
-              compaction: await resolve(configuredCompaction, resolverContext),
-              explicit: true,
-              generation: options.generation,
-              tools: options.tools,
-            })
-          : staticCompaction!
-      if (checkAbort(ctx.signal)) return
-
-      if (request.reason === 'tool' && responseStepCount >= maxSteps) {
-        const source = response.source?.generation
-        if (source === undefined) return
-        return {
-          type: 'ai.generation.failed',
-          id: await aiEventId('a2.ai.step-limit', requestId),
-          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),
-        promptThroughIndex: snapshot.index,
-      }
-      const catalogModelId = gatewayModelId(resolvedModel)
-      const gatewayOptions = options.generation?.providerOptions?.['gateway']
-      const usesFallbackModels =
-        Array.isArray(gatewayOptions?.['models']) &&
-        gatewayOptions['models'].length > 0
-      const discoversMetadata =
-        compaction !== false &&
-        !('shouldCompact' in compaction) &&
-        compaction.thresholdTokens === undefined &&
-        !usesFallbackModels &&
-        catalogModelId !== undefined
-      const startEvents: AppendInput<D>[] = []
-      if (
-        discoversMetadata &&
-        !Object.hasOwn(state.modelMetadata, catalogModelId)
-      ) {
-        startEvents.push({
-          type: 'ai.model.metadata.requested',
-          id: await aiEventId(
-            'a2.ai.model.metadata',
-            options.agent.contract.name,
-            ctx.event.sessionId,
-            catalogModelId,
-          ),
-          payload: { modelId: catalogModelId },
-        } as AppendInput<D>)
-      }
-      if (previous) {
-        const payload = previous
-        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: await aiEventId('a2.ai.superseded', payload.generationId),
-          payload: superseded,
-        } as AppendInput<D>)
-      }
-      startEvents.push({
-        type: 'ai.generation.started',
-        id: generationId,
-        payload: started,
-      } as AppendInput<D>)
-      const generationEvents = await control.append({
-        ctx,
-        name: 'generation-start',
-        events: startEvents,
-      })
-      generationStarted = true
-
-      if (checkAbort(ctx.signal)) return
-
-      const promptCoordinatorState = coordinatorState
-      const messages = contextMessages({
-        state,
-        coordinator: promptCoordinatorState,
-      })
-      let generationMessages = messages
-      let modelMessages = await modelContext({ messages, state, tools })
-      const baseContext: AgentGenerateContext<M, D, T> = {
-        request: ctx.event,
-        requestId,
-        generationId,
-        responseMessageId,
-        messages,
-        modelMessages,
-        session: resolverContext.session,
-        signal: ctx.signal,
-        model: resolvedModel,
-        tools,
-        ...(resolvedInstructions === undefined
-          ? {}
-          : { instructions: resolvedInstructions }),
-        generation,
-      }
-      const policy = compaction
-      const tracksInput =
-        policy !== false &&
-        !('shouldCompact' in policy) &&
-        (policy.thresholdTokens !== undefined || discoversMetadata)
-      const metadata =
-        catalogModelId === undefined
-          ? undefined
-          : state.modelMetadata[catalogModelId]
-      const limits =
-        metadata?.status === 'resolved' && !usesFallbackModels
-          ? metadata.limits
-          : undefined
-      let inputTokenEstimate: number | undefined
-      let compacted = false
-      let compactionEstimate:
-        | Pick<
-            CompactionRequestedPayload,
-            'inputTokenEstimate' | 'inputTokens' | 'thresholdTokens'
-          >
-        | undefined
-      const hasPendingTools = messages.some((message) =>
-        message.parts.some(
-          (part) =>
-            isToolUIPart(part) &&
-            !(
-              part.state === 'output-error' ||
-              part.state === 'output-denied' ||
-              (part.state === 'output-available' && part.preliminary !== true)
-            ),
-        ),
-      )
-      if (policy && !hasPendingTools) {
-        const compactionContext = {
-          ...resolverContext,
-          messages,
-          modelMessages,
-        }
-        let shouldCompact: boolean
-        if ('shouldCompact' in policy) {
-          shouldCompact = await policy.shouldCompact(compactionContext)
-        } else if (tracksInput) {
-          inputTokenEstimate = await estimateInputTokens({
-            messages: modelMessages,
-            instructions: resolvedInstructions,
-            tools,
-          })
-          const inputTokens = measuredInputTokens({
-            estimate: inputTokenEstimate,
-            model: modelName(resolvedModel),
-            calibration: coordinatorState.calibration,
-          })
-          const threshold =
-            policy.thresholdTokens ??
-            (limits === undefined
-              ? undefined
-              : Math.floor(
-                  Math.min(
-                    limits.contextWindow * 0.75,
-                    limits.contextWindow - (generation.maxOutputTokens ?? 0),
-                  ),
-                ))
-          if (
-            limits !== undefined &&
-            threshold !== undefined &&
-            threshold <= 0
-          ) {
-            throw new Error(
-              `output allowance exhausts the ${limits.contextWindow}-token context window`,
-            )
-          }
-          shouldCompact = threshold !== undefined && inputTokens >= threshold
-          if (threshold !== undefined && shouldCompact) {
-            compactionEstimate = {
-              inputTokenEstimate,
-              inputTokens,
-              thresholdTokens: threshold,
-            }
-          }
-        } else {
-          shouldCompact = false
-        }
-        if (checkAbort(ctx.signal)) return
-        if (shouldCompact) {
-          const latest = (
-            await ctx.session.state(coordinator, { through: 'latest' })
-          ).state
-          shouldCompact = Object.keys(latest.unsettledTools ?? {}).length === 0
-        }
-        if (checkAbort(ctx.signal)) return
-        if (shouldCompact) {
-          const throughMessageId =
-            state.messages.findLast(
-              (message) =>
-                !promptCoordinatorState.queued.some(
-                  (queued) => queued.messageId === message.id,
-                ),
-            )?.id ?? request.messageId
-          const throughIndex = snapshot.index
-          generationEvents.push(
-            ...(await control.append({
-              ctx,
-              name: 'compaction-requested',
-              events: [
-                {
-                  type: 'ai.compaction.requested',
-                  id: await aiEventId(
-                    'a2.ai.compaction.requested',
-                    generationId,
-                  ),
-                  payload: {
-                    generationId,
-                    throughMessageId,
-                    throughIndex,
-                    ...compactionEstimate,
-                  },
-                } as AppendInput<D>,
-              ],
-            })),
-          )
-          const result = !('shouldCompact' in policy)
-            ? {
-                messages: [] as M[],
-                ...(await summarize({
-                  agentName: options.agent.contract.name,
-                  context: baseContext,
-                  instructions: policy.instructions,
-                })),
-              }
-            : { messages: await policy.compact(compactionContext) }
-          if (checkAbort(ctx.signal)) return
-          const completed: CompactionCompletedPayload<M> = {
-            generationId,
-            throughMessageId,
-            throughIndex,
-            ...result,
-            ...(promptCoordinatorState.queued.length === 0
-              ? {}
-              : {
-                  retainedMessageIds: promptCoordinatorState.queued.map(
-                    (item) => item.messageId,
-                  ),
-                }),
-          }
-          generationEvents.push(
-            ...(await control.append({
-              ctx,
-              name: 'compaction-completed',
-              events: [
-                {
-                  type: 'ai.compaction.completed',
-                  id: await aiEventId(
-                    'a2.ai.compaction.completed',
-                    generationId,
-                  ),
-                  payload: completed,
-                } as AppendInput<D>,
-              ],
-            })),
-          )
-          const queued = new Set(
-            promptCoordinatorState.queued.map((item) => item.messageId),
-          )
-          generationMessages = result.messages.filter(
-            (message) => !queued.has(message.id),
-          )
-          compacted = true
-        }
-      }
-
-      const currentState = foldAIEvents({
-        reducer: contextReducer[aiStateReducer],
-        events: generationEvents,
-        state,
-      })
-      if (request.reason === 'retry' || previous !== undefined) {
-        generationMessages = contextMessages({
-          state: currentState,
-          coordinator: promptCoordinatorState,
-        })
-      }
-      if (
-        (policy && 'shouldCompact' in policy) ||
-        generationMessages !== messages ||
-        activeCompaction(currentState)?.summary !==
-          activeCompaction(state)?.summary
-      ) {
-        modelMessages = await modelContext({
-          messages: generationMessages,
-          state: currentState,
-          tools,
-        })
-      }
-      promptCache.set(
-        promptCacheKey(ctx.event.sessionId, generationId),
-        Promise.resolve(modelMessages),
-      )
-      if (tracksInput && (inputTokenEstimate === undefined || compacted)) {
-        inputTokenEstimate = await estimateInputTokens({
-          messages: modelMessages,
-          instructions: resolvedInstructions,
-          tools,
-        })
-      }
-
-      let pendingToolCalls: PendingToolCall[] = []
-      if (checkAbort(ctx.signal)) return
-      const generateContext: AgentGenerateContext<M, D, T> = {
-        request: ctx.event,
-        requestId,
-        generationId,
-        responseMessageId,
-        messages: generationMessages,
-        modelMessages,
-        session: resolverContext.session,
-        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({
-              agentName: options.agent.contract.name,
-              context: generateContext,
-              messageMetadata: 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 = await lifecycleEvents<D, T>({
-          requestId,
-          messageId: responseMessageId,
-          generationId,
-          sequence,
-          chunks: update.chunks,
-          pending: pendingToolCalls,
-          tools,
-          generation,
-          custom,
-        })
-        pendingToolCalls = lifecycle.pending
-        await control.append({
-          ctx,
-          name: `generation-progress:${sequence}`,
-          events: [
-            {
-              type: 'ai.generation.progress',
-              id: await aiEventId(
-                'a2.ai.progress',
-                generationId,
-                String(sequence),
-              ),
-              payload: progress,
-            } as AppendInput<D>,
-            ...lifecycle.events,
-          ],
-        })
-        sequence += 1
-      }
-
-      if (!finish) throw new Error('agent generation finished without output')
-      const completed: GenerationCompletedPayload = {
-        requestId,
-        messageId: request.messageId,
-        generationId,
-        responseMessageId,
-        ...(inputTokenEstimate === undefined ? {} : { inputTokenEstimate }),
-        ...(finish.finishReason === undefined
-          ? {}
-          : { finishReason: finish.finishReason }),
-        ...(finish.usage === undefined ? {} : { usage: finish.usage }),
-      }
-      const completionEvent = {
-        type: 'ai.generation.completed',
-        id: await aiEventId('a2.ai.completed', generationId),
-        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 = await Promise.all(
-        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: await aiEventId('a2.ai.message.completed', generationId),
-          payload: {
-            messageId: responseMessageId,
-          } satisfies MessageCompletedPayload,
-        } as AppendInput<D>,
-      ]
-    } catch (error) {
-      if (error instanceof ControlCancelled) throw error
-      if (error instanceof A2Error) {
-        checkAbort(ctx.signal)
-        throw error
-      }
-      if (checkAbort(ctx.signal)) return
-      if (!generationStarted) throw error
-      const failed: GenerationFailedPayload = {
-        requestId,
-        messageId: request.messageId,
-        generationId,
-        responseMessageId,
-        error: errorMessage(error),
-      }
-      return {
-        type: 'ai.generation.failed',
-        id: await aiEventId('a2.ai.failed', generationId),
-        payload: failed,
-      } as AppendInput<D>
-    }
-  }
-
-  const clearPromptCache = (sessionId: string): void => {
-    const prefix = `${sessionId}\u001f`
-    for (const key of promptCache.keys()) {
-      if (key.startsWith(prefix)) promptCache.delete(key)
-    }
-  }
-
-  return {
-    'ai.model.metadata.requested': {
-      handler: async (ctx) => {
-        const limits = await readModelLimits({
-          modelId: ctx.event.payload.modelId,
-          signal: ctx.signal,
-        })
-        ctx.signal.throwIfAborted()
-        return {
-          type: 'ai.model.metadata.resolved',
-          id: await aiEventId('a2.ai.model.metadata.resolved', ctx.event.id),
-          payload: { modelId: ctx.event.payload.modelId, limits },
-        } as AppendInput<D>
-      },
-    },
-    'ai.control.requested': {
-      lane: ({ event }) => {
-        const command = event.payload as ControlCommand<M>
-        if (event.id === '')
-          throw new A2Error(
-            'INVALID_PAYLOAD',
-            'AI command IDs must be nonempty',
-          )
-        if (event.id?.startsWith(AI_EVENT_ID_PREFIX))
-          throw new A2Error(
-            'INVALID_PAYLOAD',
-            `AI command IDs cannot use the reserved '${AI_EVENT_ID_PREFIX}' prefix`,
-          )
-        if (
-          (command.action === 'send' || command.action === 'steer') &&
-          event.id !== command.message.id
-        )
-          throw new A2Error(
-            'INVALID_PAYLOAD',
-            'AI input event ID must equal message.id',
-          )
-        return 'a2.ai.control'
-      },
-      handler: control.handler,
-    },
-    'ai.work.reported': { lane: 'a2.ai.control', handler: control.handler },
-    'ai.message.completed': {
-      handler: async (ctx) => {
-        clearPromptCache(ctx.event.sessionId)
-      },
-    },
-    'ai.message.interrupted': {
-      handler: async (ctx) => {
-        clearPromptCache(ctx.event.sessionId)
-      },
-    },
-    'ai.session.closed': {
-      lane: 'a2.ai.control',
-      handler: async (ctx) => {
-        clearPromptCache(ctx.event.sessionId)
-        return control.handler(ctx)
-      },
-    },
-    'ai.generation.failed': {
-      handler: (ctx) => {
-        promptCache.delete(
-          promptCacheKey(ctx.event.sessionId, ctx.event.payload.generationId),
-        )
-        return Promise.resolve()
-      },
-    },
-    'ai.generation.requested': {
-      lane: 'a2.ai.model',
-      abortOn: {
-        'ai.control.requested': (event, trigger) =>
-          event.payload.action === 'stop' &&
-          event.payload.turnId === trigger.payload.control?.turnId,
-        'ai.control.committed': (event, trigger) => {
-          const active = (event.payload as ControlCommit).view
-          return (
-            active?.turnId !== trigger.payload.control?.turnId ||
-            active?.version !== trigger.payload.control?.version
-          )
-        },
-        'ai.session.closed': true,
-      },
-      handler: async (ctx) => {
-        try {
-          return control.settled({ ctx, events: await generationHandler(ctx) })
-        } catch (error) {
-          if (control.cancelled({ error, signal: ctx.signal }))
-            return control.settled({ ctx, events: undefined })
-          throw error
-        }
-      },
-    },
-    'ai.tool.execution.requested': {
-      abortOn: {
-        'ai.control.requested': (event, trigger) =>
-          event.payload.action === 'stop' &&
-          event.payload.turnId === trigger.payload.turnId,
-        'ai.generation.failed': (event, trigger) =>
-          event.payload.generationId === trigger.payload.call.generationId,
-        'ai.control.committed': (event, trigger) => {
-          const active = (event.payload as ControlCommit).view
-          return (
-            active?.turnId !== trigger.payload.turnId ||
-            active?.version !== trigger.payload.version
-          )
-        },
-        'ai.session.closed': true,
-      },
-      handler: handleToolExecution,
-    },
-  } 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 }),
-  })
-  const server = createServer({
-    ...serverOptions,
-    contract: definition.contract,
-    handlers: { ...builtIns, ...handlers },
-  })
-  setServerFetchHooks(server, { validateIngress: validateAgentIngress })
-  return server
-}
-
-export type { Instructions, LanguageModel, ToolSet }
+} from './ai-agent.ts'