experimental-a2 0.12.0 → 0.14.0

package/src/ai-server.ts

@@ -8,8 +8,10 @@
 // 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 type { ControlCommit } from './ai-control.ts'
 import { AsyncLocalStorage } from 'node:async_hooks'
-import { convertToModelMessages } from 'ai'
+import { asSchema, convertToModelMessages } from 'ai'
 import type {
   FinishReason,
   Instructions,
@@ -22,6 +24,7 @@ import type {
   UIMessageChunk,
 } from 'ai'
 import { generateAISDKStep, type AISDKStepSettings } from './ai-sdk-step.ts'
+import { gatewayModelId, readModelLimits } from './ai-model-metadata.ts'
 import type {
   AIEventDefs,
   AIState,
@@ -33,17 +36,13 @@ import type {
   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'
@@ -66,24 +65,23 @@ import {
 
 function validateAgentIngress(context: ServerIngressContext): 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'
+    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'
       )
     }
-    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'
-    )
+    return false
   })
   if (rejected !== undefined) {
     throw new A2Error(
@@ -116,8 +114,9 @@ export type AgentGenerateContext<
   generationId: string
   responseMessageId: string
   messages: M[]
+  modelMessages: ModelMessage[]
   state: AIState<M>
-  history: ContractEvent<D>[]
+  session: Pick<HandlerContext<D>['session'], 'state'>
   signal: AbortSignal
   model: LanguageModel
   tools: T
@@ -150,7 +149,7 @@ export type AgentResolverContext<
 > = {
   event: ContractEvent<D, 'ai.generation.requested'>
   state: AIState<M>
-  history: ContractEvent<D>[]
+  session: Pick<HandlerContext<D>['session'], 'state'>
   signal: AbortSignal
 }
 
@@ -161,13 +160,29 @@ export type CompactionPolicy<
   D extends AIEventDefs<M> & EventDefs,
 > = {
   shouldCompact(
-    context: AgentResolverContext<M, D> & { messages: M[] },
+    context: AgentResolverContext<M, D> & {
+      messages: M[]
+      modelMessages: ModelMessage[]
+    },
   ): boolean | Promise<boolean>
   compact(
-    context: AgentResolverContext<M, D> & { messages: M[] },
+    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<
@@ -196,7 +211,7 @@ export type CreateHandlersOptions<
    * The custom stream owns its metadata chunks.
    */
   generate?: AgentGenerate<M, D, T>
-  compaction?: CompactionPolicy<M, D>
+  compaction?: Resolvable<CompactionOptions<M, D>, AgentResolverContext<M, D>>
   /** Progress is durably flushed at either limit, whichever is reached first. */
   progress?: { maxChunks?: number; maxDelayMs?: number }
 }
@@ -210,13 +225,35 @@ export type CreateAgentServerOptions<
     handlers?: ServerOptions<D>['handlers']
   }
 
-const resolve = async <T, C>(
+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> =>
-  typeof value === 'function'
-    ? await (value as (context: C) => T | Promise<T>)(context)
-    : value
+): 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
@@ -265,10 +302,12 @@ const isBoundaryChunk = (chunk: UIMessageChunk | undefined): boolean =>
     chunk.type === 'abort' ||
     chunk.type === 'error')
 
+type StreamRead<T> = Awaited<ReturnType<ReadableStreamDefaultReader<T>['read']>>
+
 const nextOrTimer = async <T>(
-  next: Promise<IteratorResult<T>>,
+  next: Promise<StreamRead<T>>,
   delayMs: number,
-): Promise<{ type: 'next'; result: IteratorResult<T> } | { type: 'timer' }> => {
+): Promise<{ type: 'next'; result: StreamRead<T> } | { type: 'timer' }> => {
   let timer: ReturnType<typeof setTimeout> | undefined
   try {
     return await Promise.race([
@@ -305,6 +344,7 @@ async function generateWithAISDK<
     model: context.model,
     tools: context.tools,
     messages: context.messages,
+    modelMessages: context.modelMessages,
     responseMessageId: context.responseMessageId,
     abortSignal: context.signal,
     ...(context.instructions === undefined
@@ -333,11 +373,11 @@ async function* consumeGeneration(options: {
   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()
+  const reader = options.source.stream.getReader()
+  let pendingChunk = reader.read()
   try {
     for (;;) {
-      let result: IteratorResult<UIMessageChunk>
+      let result: StreamRead<UIMessageChunk>
       if (pending.length > 0) {
         const remaining = Math.max(0, maxDelayMs - (Date.now() - lastFlush))
         const outcome = await nextOrTimer(pendingChunk, remaining)
@@ -355,7 +395,7 @@ async function* consumeGeneration(options: {
       pending.push(chunk)
       if (chunk.type === 'finish') streamedFinishReason = chunk.finishReason
       if (chunk.type === 'error') streamedError = chunk.errorText
-      pendingChunk = chunks.next()
+      pendingChunk = reader.read()
 
       if (pending.length >= maxChunks || isBoundaryChunk(pending.at(-1))) {
         yield { type: 'progress', chunks: pending.splice(0) }
@@ -366,6 +406,15 @@ async function* consumeGeneration(options: {
     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
@@ -389,46 +438,249 @@ async function* consumeGeneration(options: {
   }
 }
 
-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)
+const foldAIEvents = <
+  M extends UIMessage,
+  D extends AIEventDefs<M> & EventDefs,
+>(options: {
+  agent: AgentDefinition<M, D>
+  state: AIState<M>
+  events: ContractEvent<D>[]
+}): AIState<M> => {
+  let state = options.state
+  for (const event of options.events)
+    state = options.agent.reducer.fold(state, event)
   return state
 }
 
-const contextMessages = <M extends UIMessage>(state: AIState<M>): M[] => {
+const summarize = async <
+  M extends UIMessage,
+  D extends AIEventDefs<M> & EventDefs,
+  T extends ToolSet,
+>(options: {
+  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(
+    {
+      ...options.context,
+      generation,
+      tools,
+      modelMessages: [
+        ...options.context.modelMessages,
+        { role: 'user', content: instruction },
+      ],
+      responseMessageId: `${options.context.generationId}:summary`,
+    },
+    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: AIState<M>,
+): AIState<M>['compaction'] => {
   const compaction = state.compaction
-  if (compaction?.status !== 'completed' || !compaction.messages) {
-    return state.messages
+  return compaction?.status === 'completed' &&
+    compaction.messages !== undefined &&
+    state.messages.some((message) => message.id === compaction.throughMessageId)
+    ? compaction
+    : null
+}
+
+const contextMessages = async <
+  M extends UIMessage,
+  D extends AIEventDefs<M> & EventDefs,
+>(options: {
+  agent: AgentDefinition<M, D>
+  session: HandlerContext<D>['session']
+  snapshot: { state: AIState<M>; index: number }
+  coordinator: AICoordinatorState
+  appended?: ContractEvent<D>[]
+  excluded?: ReadonlySet<string>
+}): Promise<M[]> => {
+  const { agent, session, snapshot } = options
+  const appended = options.appended ?? []
+  const state = foldAIEvents({ agent, events: appended, state: snapshot.state })
+  const compaction = activeCompaction(state)
+  const queued = new Set(
+    options.coordinator.queued.map((item) => item.messageId),
+  )
+  const visible = (messages: M[]): M[] =>
+    messages.filter((message) => !queued.has(message.id))
+  if (compaction === null) return visible(state.messages)
+  const retained = new Set(compaction.retainedMessageIds ?? [])
+  const throughIndex = compaction.throughIndex
+  if (throughIndex !== undefined) {
+    const [prefix, priorCoordinator, tail] = await Promise.all([
+      throughIndex === snapshot.index
+        ? Promise.resolve(snapshot)
+        : session.state(agent.reducer, { through: throughIndex }),
+      session.state(aiCoordinatorReducer(agent.contract), {
+        through: throughIndex,
+      }),
+      throughIndex >= snapshot.index
+        ? Promise.resolve([])
+        : session.history({ gte: throughIndex + 1, lte: snapshot.index }),
+    ])
+    for (const item of priorCoordinator.state.queued)
+      retained.add(item.messageId)
+    const events =
+      options.excluded === undefined
+        ? tail
+        : withoutGenerationLifecycle(tail, options.excluded)
+    const context = foldAIEvents({
+      agent,
+      events: [...events, ...appended],
+      state: {
+        ...prefix.state,
+        messages: [
+          ...compaction.messages!,
+          ...prefix.state.messages.filter((message) =>
+            retained.has(message.id),
+          ),
+        ],
+        activeProjection: null,
+      },
+    })
+    const positions = new Map<string, number>()
+    for (const message of [...compaction.messages!, ...state.messages]) {
+      if (!positions.has(message.id)) positions.set(message.id, positions.size)
+    }
+    return visible(
+      context.messages.toSorted(
+        (left, right) =>
+          (positions.get(left.id) ?? positions.size) -
+          (positions.get(right.id) ?? positions.size),
+      ),
+    )
   }
   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),
-      ]
+  return visible([
+    ...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 modelContext = async <M extends UIMessage>(options: {
+  messages: M[]
+  state: AIState<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]
+}
+
+const estimateInputTokens = async (options: {
+  messages: ModelMessage[]
+  instructions: Instructions | undefined
+  tools: ToolSet
+}): Promise<number> => {
+  const tools = await Promise.all(
+    Object.entries(options.tools).map(async ([name, tool]) => ({
+      name,
+      description: tool.description,
+      inputSchema: await asSchema(tool.inputSchema).jsonSchema,
+    })),
+  )
+  return Math.ceil(
+    new TextEncoder().encode(
+      JSON.stringify({
+        messages: options.messages,
+        instructions: options.instructions,
+        tools,
+      }),
+    ).byteLength / 4,
+  )
 }
 
-const generationRequestId = (generationId: string): string | undefined => {
-  const markerIndex = generationId.lastIndexOf(':generation:')
-  return markerIndex === -1 ? undefined : generationId.slice(0, markerIndex)
+const measuredInputTokens = (options: {
+  estimate: number
+  model: string
+  calibration: AICoordinatorState['calibration']
+}): number => {
+  const previous = options.calibration
+  return previous !== undefined &&
+    previous.model === options.model &&
+    options.estimate >= previous.estimate
+    ? Math.max(
+        options.estimate,
+        Math.ceil(previous.inputTokens + options.estimate - previous.estimate),
+      )
+    : options.estimate
 }
 
 type ToolCallClassification = 'automatic' | 'approval' | 'unknown'
@@ -675,36 +927,6 @@ const lifecycleEvents = <D extends EventDefs, T extends ToolSet>(options: {
   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>,
@@ -772,6 +994,62 @@ function withoutGenerationLifecycle<D extends EventDefs>(
   })
 }
 
+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.
@@ -808,92 +1086,25 @@ export function createHandlers<
     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 = options.generation ?? {}
+  const generation: AgentGenerationSettings<T> = options.generation ?? {}
   const maxSteps = options.maxSteps ?? Number.POSITIVE_INFINITY
-  const coordinator = aiCoordinatorReducer(options.agent.contract)
+  const control = createControlRuntime({ agent: options.agent })
+  const coordinator = control.coordinator
   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, { through: 'latest' })).state,
-    )
-
-  const continueIfReady = async (
-    ctx: Pick<HandlerContext<D>, 'session'>,
-    generationId: string,
-  ): Promise<void> => {
-    const state = (await ctx.session.state(coordinator, { through: 'latest' }))
-      .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,
@@ -905,9 +1116,7 @@ export function createHandlers<
     ) => unknown
   }
 
-  type ToolHandlerContext =
-    | HandlerContext<D, 'ai.tool.called'>
-    | HandlerContext<D, 'ai.approval.responded'>
+  type ToolHandlerContext = HandlerContext<D, 'ai.tool.execution.requested'>
 
   const resultEvent = (
     call: ToolCalledPayload,
@@ -946,49 +1155,48 @@ export function createHandlers<
       },
     }) as AppendInput<D>
 
-  const promptMessages = (
-    sessionId: string,
-    call: ToolCalledPayload,
-    readHistory: () => Promise<ContractEvent<D>[]>,
-  ): Promise<ModelMessage[]> => {
-    const key = promptCacheKey(sessionId, call.generationId)
+  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 history = await readHistory()
-      const coordinatorState = coordinatorStateAt(history)
-      const compaction = history.find(
+      const frontier = owner.promptThroughIndex
+      if (frontier === undefined)
+        throw new TypeError('AI work requires a prompt checkpoint')
+      const [snapshot, atPrompt, tail] = await Promise.all([
+        ctx.session.state(options.agent.reducer, { through: frontier }),
+        ctx.session.state(coordinator, { through: frontier }),
+        ctx.session.history({ gte: frontier + 1, lte: ctx.event.index }),
+      ])
+      const appended = tail.filter(
         (event) =>
-          event.type === 'ai.compaction.completed' &&
-          (event.payload as CompactionCompletedPayload<M>).generationId ===
+          (event.type === 'ai.generation.started' ||
+            event.type === 'ai.compaction.requested' ||
+            event.type === 'ai.compaction.completed') &&
+          (event.payload as { generationId: string }).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 },
-      )
+      const state = foldAIEvents({
+        agent: options.agent,
+        events: appended,
+        state: snapshot.state,
+      })
+      return modelContext({
+        messages: await contextMessages({
+          agent: options.agent,
+          session: ctx.session,
+          snapshot,
+          coordinator: atPrompt.state,
+          appended,
+        }),
+        state,
+        tools,
+      })
     })()
     promptCache.set(key, computation)
     void computation.catch(() => {
@@ -1003,9 +1211,9 @@ export function createHandlers<
     error: unknown,
   ): AppendInput<D> | void => {
     const schedulerFailure = consumeSchedulerSendFailure(error)
-    if (ctx.signal.aborted) return
+    if (checkAbort(ctx.signal)) return
     if (schedulerFailure === 'retryable') throw error
-    return resultEvent(call, 'execution:error', {
+    return resultEvent(call, `${ctx.event.id}:execution:error`, {
       error: errorMessage(error),
     })
   }
@@ -1033,69 +1241,73 @@ export function createHandlers<
       return toolExecutionFailure(ctx, call, error)
     }
     if (iterator === undefined) {
-      return resultEvent(call, 'execution:0', { output })
+      return resultEvent(call, `${ctx.event.id}: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) {
+    let done = false
+    try {
+      for (;;) {
+        let result: IteratorResult<unknown>
         try {
-          await iterator.return?.()
-        } catch {
-          // The aborted handler cannot record an iterator cleanup failure.
+          result = await iterator.next()
+        } catch (error) {
+          return toolExecutionFailure(ctx, call, error)
         }
-        return
+        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: [
+            resultEvent(
+              call,
+              `${ctx.event.id}:execution:${ctx.attempt}:${sequence}:preliminary`,
+              {
+                output: result.value,
+                preliminary: true,
+              },
+            ),
+          ],
+        })
+        sequence += 1
       }
-      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) {
+    } finally {
+      if (!done) {
         try {
           await iterator.return?.()
         } catch {
-          // Preserve the append failure that makes the durable handler retry.
+          // Preserve the failure or cancellation that ended execution.
         }
-        throw error
       }
-      sequence += 1
     }
     return resultEvent(
       call,
-      `execution:${sequence}:final`,
+      `${ctx.event.id}:execution:${sequence}:final`,
       sequence === 0 ? {} : { output: last },
     )
   }
 
-  const executeTool = async (
-    ctx: ToolHandlerContext,
-    call: ToolCalledPayload,
-  ): Promise<AppendInput<D> | void> => {
+  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, 'execution:error', {
+      return resultEvent(call, `${ctx.event.id}:execution:error`, {
         error: `Tool '${call.toolName}' has no server executor`,
       })
     }
-    const messages = await promptMessages(
-      ctx.event.sessionId,
-      call,
-      ctx.session.history,
-    )
-    if (ctx.signal.aborted) return
+    const messages = await promptMessages(input)
+    if (checkAbort(ctx.signal)) return
     const scope: AmbientToolScope = {
       contract: options.agent.contract,
       context: ctx,
@@ -1107,100 +1319,77 @@ export function createHandlers<
     )
   }
 
-  const handleToolCall = async (
-    ctx: HandlerContext<D, 'ai.tool.called'>,
-  ): Promise<AppendInput<D> | void> => {
-    const state = (await ctx.session.state(coordinator, { through: 'latest' }))
-      .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, { through: 'latest' }))
-      .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 })
+  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 ||
+        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
     }
-    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()
+    if (checkAbort(ctx.signal)) return
     const requestId = ctx.event.id
     const request = ctx.event.payload
+    const snapshot = await ctx.session.state(options.agent.reducer, {
+      through: 'latest',
+    })
+    if (
+      snapshot.state.active?.phase === 'paused' ||
+      snapshot.state.active?.phase === 'pausing'
+    )
+      return
     const coordinatorState = (
-      await ctx.session.state(coordinator, { through: 'latest' })
+      await ctx.session.state(coordinator, { through: snapshot.index })
     ).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,
+      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))
     )
-    if (priorAttempts.some((priorAttempt) => priorAttempt >= ctx.attempt)) {
       return
-    }
+    if (current !== undefined && current.attempt >= ctx.attempt) return
     const attempt = ctx.attempt
     const generationId = `${requestId}:generation:${attempt}`
     const responseMessageId =
@@ -1208,202 +1397,363 @@ export function createHandlers<
       (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)
+    const responseStepCount = response.stepCount
     if (
-      request.reason === 'retry' &&
-      sourceCoordinatorState.response?.failure?.generationId !== undefined
-    ) {
-      replacedGenerationIds.add(
-        sourceCoordinatorState.response.failure.generationId,
-      )
+      request.reason === 'tool' &&
+      (requestId !==
+        `ai.generate:tools:${response.source?.generation.generationId}` ||
+        response.responseMessageId !== request.messageId ||
+        response.responseMessageId !== request.responseMessageId)
+    )
+      return
+    const previous = current
+    const replaced =
+      previous === undefined
+        ? []
+        : [{ generation: previous, frontier: response.promptThroughIndex! }]
+    if (request.reason === 'retry' && response.source?.failed) {
+      replaced.push({
+        generation: response.source.generation,
+        frontier: response.source.promptThroughIndex,
+      })
     }
-    const promptHistory = withoutGenerationLifecycle(
-      history,
-      replacedGenerationIds,
+    const replacedGenerationIds = new Set(
+      replaced.map(({ generation: owner }) => owner.generationId),
     )
-    let state = replay(options.agent, promptHistory)
+    let state = snapshot.state
+    if (replaced.length > 0) {
+      const through = Math.min(...replaced.map(({ frontier }) => frontier))
+      const baseline = await ctx.session.state(options.agent.reducer, {
+        through,
+      })
+      const tail = await ctx.session.history({
+        gte: through + 1,
+        lte: snapshot.index,
+      })
+      state = foldAIEvents({
+        agent: options.agent,
+        events: withoutGenerationLifecycle(tail, replacedGenerationIds),
+        state: baseline.state,
+      })
+    }
     const resolverContext: AgentResolverContext<M, D> = {
       event: ctx.event,
       state,
-      history,
+      session: {
+        state: (reducer, readOptions) =>
+          ctx.session.state(reducer, {
+            ...readOptions,
+            through: readOptions?.through ?? snapshot.index,
+          }),
+      },
       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>
-    }
+    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: `${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 = {
+      const started: GenerationStartedPayload = {
         requestId,
-        messageId: payload.messageId,
-        generationId: payload.generationId,
-        responseMessageId: payload.responseMessageId,
-        error: 'generation attempt was superseded after an incomplete run',
-        superseded: true,
+        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: `ai.model.metadata:${encodeURIComponent(options.agent.contract.name)}:${encodeURIComponent(ctx.event.sessionId)}:${encodeURIComponent(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: `${payload.generationId}:superseded`,
+          payload: superseded,
+        } as AppendInput<D>)
       }
       startEvents.push({
-        type: 'ai.generation.failed',
-        id: `${payload.generationId}:superseded`,
-        payload: superseded,
+        type: 'ai.generation.started',
+        id: generationId,
+        payload: started,
       } 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, { through: 'latest' })
-    ).state
-    if (
-      startedCoordinatorState.response?.activeRequestId !== requestId ||
-      startedCoordinatorState.response.generation?.generationId !== generationId
-    ) {
-      return
-    }
+      const generationEvents = await control.append({
+        ctx,
+        name: 'generation-start',
+        events: startEvents,
+      })
+      generationStarted = true
 
-    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,
+      if (checkAbort(ctx.signal)) return
+
+      const promptCoordinatorState = coordinatorState
+      const messages = await contextMessages({
+        agent: options.agent,
+        session: ctx.session,
+        snapshot: { state, index: snapshot.index },
+        coordinator: promptCoordinatorState,
+        excluded: replacedGenerationIds,
+      })
+      let generationMessages = messages
+      let modelMessages = await modelContext({ messages, state, tools })
+      const baseContext: AgentGenerateContext<M, D, T> = {
+        request: ctx.event,
+        requestId,
+        generationId,
+        responseMessageId,
+        messages,
+        modelMessages,
+        state,
+        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
+      const canCompact = response.source?.canCompact ?? true
+      if (policy && canCompact) {
+        const compactionContext = {
+          ...resolverContext,
           messages,
-          ...(promptCoordinatorState.queued.length === 0
-            ? {}
-            : {
-                retainedMessageIds: promptCoordinatorState.queued.map(
-                  (item) => item.messageId,
-                ),
-              }),
+          modelMessages,
         }
-        await ctx.session.append('compaction-completed', {
-          type: 'ai.compaction.completed',
-          id: `${generationId}:compaction:completed`,
-          payload: completed,
-        })
-        state = {
-          ...state,
-          compaction: { status: 'completed', ...completed },
+        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
+        } else {
+          shouldCompact = false
+        }
+        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: `${generationId}:compaction:requested`,
+                  payload: { generationId, throughMessageId, throughIndex },
+                } as AppendInput<D>,
+              ],
+            })),
+          )
+          const result = !('shouldCompact' in policy)
+            ? {
+                messages: [] as M[],
+                ...(await summarize({
+                  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: `${generationId}:compaction:completed`,
+                  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 = (
-      await ctx.session.state(options.agent.reducer, { through: 'latest' })
-    ).state
-    const currentCoordinatorState = (
-      await ctx.session.state(coordinator, { through: 'latest' })
-    ).state
-    const generationMessages = activeContextMessages(
-      currentState,
-      currentCoordinatorState,
-    )
-    promptCache.set(
-      promptCacheKey(ctx.event.sessionId, generationId),
-      convertToModelMessages(generationMessages, { tools }),
-    )
+      const currentState = foldAIEvents({
+        agent: options.agent,
+        events: generationEvents,
+        state: snapshot.state,
+      })
+      if (request.reason === 'retry' || previous !== undefined) {
+        generationMessages = await contextMessages({
+          agent: options.agent,
+          session: ctx.session,
+          snapshot,
+          coordinator: promptCoordinatorState,
+          appended: generationEvents,
+        })
+      }
+      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[] = []
-    try {
-      const resolvedInstructions =
-        options.instructions === undefined
-          ? undefined
-          : await resolve(options.instructions, resolverContext)
-      if (ctx.signal.aborted) return
+      let pendingToolCalls: PendingToolCall[] = []
+      if (checkAbort(ctx.signal)) return
       const generateContext: AgentGenerateContext<M, D, T> = {
         request: ctx.event,
         requestId,
         generationId,
         responseMessageId,
         messages: generationMessages,
+        modelMessages,
         state: currentState,
-        history,
+        session: resolverContext.session,
         signal: ctx.signal,
         model: resolvedModel,
         tools,
@@ -1452,15 +1802,18 @@ export function createHandlers<
           custom,
         })
         pendingToolCalls = lifecycle.pending
-        await ctx.session.append(
-          `generation-progress:${sequence}`,
-          {
-            type: 'ai.generation.progress',
-            id: `${generationId}:progress:${sequence}`,
-            payload: progress,
-          },
-          ...lifecycle.events,
-        )
+        await control.append({
+          ctx,
+          name: `generation-progress:${sequence}`,
+          events: [
+            {
+              type: 'ai.generation.progress',
+              id: `${generationId}:progress:${sequence}`,
+              payload: progress,
+            } as AppendInput<D>,
+            ...lifecycle.events,
+          ],
+        })
         sequence += 1
       }
 
@@ -1470,6 +1823,7 @@ export function createHandlers<
         messageId: request.messageId,
         generationId,
         responseMessageId,
+        ...(inputTokenEstimate === undefined ? {} : { inputTokenEstimate }),
         ...(finish.finishReason === undefined
           ? {}
           : { finishReason: finish.finishReason }),
@@ -1513,19 +1867,13 @@ export function createHandlers<
         } 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>
+      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,
@@ -1541,59 +1889,6 @@ export function createHandlers<
     }
   }
 
-  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, { through: 'latest' }))
-      .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, { through: 'latest' }))
-      .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()) {
@@ -1601,32 +1896,38 @@ export function createHandlers<
     }
   }
 
-  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.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: `${ctx.event.id}:resolved`,
+          payload: { modelId: ctx.event.payload.modelId, limits },
+        } as AppendInput<D>
+      },
     },
+    'ai.control.requested': { lane: 'a2.ai.control', handler: control.handler },
+    'ai.work.reported': { lane: 'a2.ai.control', handler: control.handler },
     'ai.message.completed': {
-      lane: 'a2.ai.turn',
-      handler: handleResponseEnded,
+      handler: async (ctx) => {
+        clearPromptCache(ctx.event.sessionId)
+      },
     },
     'ai.message.interrupted': {
-      lane: 'a2.ai.turn',
-      handler: handleResponseEnded,
+      handler: async (ctx) => {
+        clearPromptCache(ctx.event.sessionId)
+      },
     },
     'ai.session.closed': {
-      handler: (ctx) => {
+      lane: 'a2.ai.control',
+      handler: async (ctx) => {
         clearPromptCache(ctx.event.sessionId)
-        return Promise.resolve()
+        return control.handler(ctx)
       },
     },
     'ai.generation.failed': {
@@ -1638,60 +1939,41 @@ export function createHandlers<
       },
     },
     'ai.generation.requested': {
-      lane: 'a2.ai.turn',
+      lane: 'a2.ai.model',
       abortOn: {
-        'ai.message.interrupted': (event, trigger, context) => {
-          const responseMessageId =
-            trigger.payload.responseMessageId ??
-            (trigger.payload.reason === 'message'
-              ? `${trigger.payload.messageId}:assistant`
-              : trigger.payload.messageId)
+        'ai.control.committed': (event, trigger) => {
+          const active = (event.payload as ControlCommit).view
           return (
-            event.payload.messageId === responseMessageId &&
-            (event.payload.requestId === trigger.id ||
-              event.payload.generationId ===
-                `${trigger.id}:generation:${context.attempt}`)
+            active?.turnId !== trigger.payload.control?.turnId ||
+            active?.version !== trigger.payload.control?.version
           )
         },
         '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: 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
+        }
       },
-      handler: handleToolCall,
     },
-    'ai.approval.responded': {
+    'ai.tool.execution.requested': {
       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),
+          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: handleApproval,
-    },
-    'ai.tool.result': {
-      handler: async (ctx) => {
-        if (ctx.event.payload.preliminary === true) return
-        await continueIfReady(ctx, ctx.event.payload.generationId)
-      },
+      handler: handleToolExecution,
     },
   } as NonNullable<ServerOptions<D>['handlers']>
 }