experimental-a2 0.16.1 → 0.18.0

package/src/ai-agent.ts

@@ -0,0 +1,2517 @@
+/**
+ * The server-only implementation of the experimental-a2/ai protocol: the
+ * handler table and `agent()`, its assembly as an 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 { isAgentContract } from './ai-app-state.ts'
+import { boundedCache } from './bounded-cache.ts'
+import type { Reducer } from './reducer.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 {
+  Experimental_SandboxSession,
+  FinishReason,
+  Instructions,
+  LanguageModelUsage,
+  ModelMessage,
+  TextStreamPart,
+  ToolSet,
+  UIMessage,
+  UIMessageChunk,
+} from 'ai'
+import { generateAISDKStep, type AISDKStepSettings } from './ai-sdk-step.ts'
+import {
+  harnessDriver,
+  harnessLog,
+  harnessStates,
+  registerHarnessStates,
+  type Harness,
+  type HarnessDriver,
+  type HarnessStates,
+} from './ai-harness.ts'
+import { gatewayModelId, readModelLimits } from './ai-model-metadata.ts'
+import { estimateInputTokens, measuredInputTokens } from './ai-input-tokens.ts'
+import { AI_STATE_REDUCER, agentContract, events as aiEvents } from './ai.ts'
+import type {
+  AIEventDefs,
+  AIMessageOf,
+  AIState,
+  AgentToolContext,
+  AgentToolEventDefs,
+  ApprovalRequestedPayload,
+  CompactionCompletedPayload,
+  CompactionRequestedPayload,
+  GenerationCompletedPayload,
+  GenerationFailedPayload,
+  GenerationProgressPayload,
+  GenerationStartedPayload,
+  MessageCompletedPayload,
+  ReasoningLevel,
+  ToolCalledPayload,
+  ToolResultPayload,
+} from './ai.ts'
+import type { StandardSchemaV1 } from './standard-schema.ts'
+import type { AICoordinatorState } from './ai-coordinator.ts'
+import type {
+  AppendInput,
+  Contract,
+  ContractEvent,
+  EventDefs,
+} from './contract.ts'
+import { A2Error } from './errors.ts'
+import {
+  consumeSchedulerSendFailure,
+  failedPreviousAttempt,
+  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'
+import { CONSOLE_TELEMETRY, type A2Telemetry } from './telemetry.ts'
+
+const isAgentIngressEvent = (event: {
+  type: string
+  payload: unknown
+}): boolean => {
+  if (event.type !== 'ai.control.requested') return false
+  const command = event.payload
+  if (typeof command !== 'object' || command === null) return false
+  const action = (command as { action?: unknown }).action
+  if (action === 'request-input' || action === 'tool-result') return false
+  if (action === 'send' || action === 'edit' || action === 'steer')
+    return (
+      (command as { message?: { role?: unknown } }).message?.role === 'user'
+    )
+  return true
+}
+
+// With a shared contract, browsers push application events like any A2
+// client, under the route's `authorize`. Events declared with `name` have no
+// client that can push them, so they stay server-only.
+const validateAgentIngress = ({
+  context,
+  applicationEvents,
+}: {
+  context: ServerIngressContext
+  applicationEvents: boolean
+}): void => {
+  const rejected = context.events.find((event) =>
+    Object.hasOwn(aiEvents, event.type)
+      ? !isAgentIngressEvent(event)
+      : !applicationEvents,
+  )
+  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,
+  X extends object = Record<never, never>,
+> = AgentResolverContext<M, D, X> & {
+  generationId: string
+  modelMessages: ModelMessage[]
+  /** The resolved AI Gateway model ID. */
+  model: string
+  tools: T
+  instructions?: Instructions
+  generation: AgentGenerationSettings<T>
+}
+
+export type AgentGenerate<
+  M extends UIMessage,
+  D extends AIEventDefs<M> & EventDefs,
+  T extends ToolSet,
+  X extends object = Record<never, never>,
+> = (
+  context: AgentGenerateContext<M, D, T, X>,
+) => 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,
+  X extends object = Record<never, never>,
+> = (
+  context: AgentGenerateContext<M, D, T, X> & { part: TextStreamPart<T> },
+) => UIMessageMetadata<M> | undefined
+
+export type AgentResolverContext<
+  M extends UIMessage,
+  D extends AIEventDefs<M> & EventDefs,
+  X extends object = Record<never, never>,
+> = {
+  event: ContractEvent<D, 'ai.generation.requested'>
+  messages: M[]
+  /**
+   * The contract's application state, as of the captured snapshot. It rides
+   * in the checkpoint the generation already reads, so it costs no I/O.
+   */
+  state: X
+  session: Pick<HandlerContext<D>['session'], 'state'>
+  signal: AbortSignal
+}
+
+export type Resolvable<T, C> = T | ((context: C) => T | Promise<T>)
+
+/** A model with its reasoning level and speed, chosen together. */
+export type ModelSettings = {
+  /** An AI Gateway model ID, such as `'anthropic/claude-sonnet-5.5'`. */
+  model: string
+  /** Overrides `generation.reasoning`. */
+  reasoning?: ReasoningLevel
+  /** `fast` prefers AI Gateway's faster tier when the model offers one. */
+  speed?: 'fast' | 'standard'
+}
+
+export type CompactionPolicy<
+  M extends UIMessage,
+  D extends AIEventDefs<M> & EventDefs,
+  X extends object = Record<never, never>,
+> = {
+  shouldCompact(
+    context: AgentResolverContext<M, D, X> & {
+      messages: M[]
+      modelMessages: ModelMessage[]
+    },
+  ): boolean | Promise<boolean>
+  compact(
+    context: AgentResolverContext<M, D, X> & {
+      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,
+  X extends object = Record<never, never>,
+> = false | AutomaticCompaction | CompactionPolicy<M, D, X>
+
+export type AgentGenerationSettings<T extends ToolSet> = AISDKStepSettings<T>
+
+export type HandlersOptions<
+  M extends UIMessage,
+  D extends AIEventDefs<M> & EventDefs,
+  T extends ToolSet = ToolSet,
+  X extends object = Record<never, never>,
+> = AgentModelOptions<M, D, T, X> & {
+  contract: Contract<D, Record<never, never>, unknown>
+  telemetry?: A2Telemetry
+  /** Where harness steps keep their saved states; one per agent. */
+  harnessStates?: HarnessStates
+}
+
+/** What a tool call does when a crash or a cancellation may have cut it short. */
+export type ToolRecovery = 'rerun' | 'report'
+
+/**
+ * The AI SDK harness, the default: one AI SDK `streamText()` step per
+ * durable generation, with A2 running tools, approvals, and compaction.
+ */
+export type AISDKHarness<
+  M extends UIMessage = UIMessage,
+  D extends AIEventDefs<M> & EventDefs = AIEventDefs<M> & EventDefs,
+  T extends ToolSet = ToolSet,
+  X extends object = Record<never, never>,
+> = {
+  type: 'ai-sdk'
+  /** Settings for each one-step AI SDK streamText call, resolved per generation. */
+  generation?: Resolvable<
+    AgentGenerationSettings<T>,
+    AgentResolverContext<M, D, X>
+  >
+  /** Map default AI SDK stream parts to typed assistant message metadata. */
+  messageMetadata?: AgentMessageMetadata<M, D, T, X>
+  /**
+   * Replace model generation with an AI SDK UI message chunk stream.
+   * The custom stream owns its metadata chunks.
+   */
+  generate?: AgentGenerate<M, D, T, X>
+  compaction?: Resolvable<
+    CompactionOptions<M, D, X>,
+    AgentResolverContext<M, D, X>
+  >
+}
+
+type AgentLoopOptions<
+  M extends UIMessage,
+  D extends AIEventDefs<M> & EventDefs,
+  T extends ToolSet,
+  X extends object,
+  H extends string,
+> =
+  | {
+      /** The agent's loop: the AI SDK's (the default), or `fx()` or `pi()`. */
+      harness?: AISDKHarness<M, D, T, X>
+      /** Per tool name: rerun an interrupted call (the default) or report it to the model. */
+      toolRecovery?: Readonly<
+        Partial<Record<NoInfer<keyof T & string>, ToolRecovery>>
+      >
+    }
+  | {
+      harness: Harness<'fx' | 'pi', H>
+      /** Per tool name, the harness's own tools included: rerun an interrupted call (the default) or report it. */
+      toolRecovery?: Readonly<
+        Partial<Record<NoInfer<(keyof T & string) | H>, ToolRecovery>>
+      >
+    }
+
+export type AgentModelOptions<
+  M extends UIMessage,
+  D extends AIEventDefs<M> & EventDefs,
+  T extends ToolSet = ToolSet,
+  X extends object = Record<never, never>,
+  /** The tool names a harness from `fx()` or `pi()` brings. */
+  H extends string = string,
+> = {
+  /**
+   * An AI Gateway model ID, or `ModelSettings` to choose its reasoning level
+   * and speed with it, optionally resolved per generation.
+   */
+  model: Resolvable<string | ModelSettings, AgentResolverContext<M, D, X>>
+  tools?: T
+  instructions?: Resolvable<
+    Instructions | undefined,
+    AgentResolverContext<M, D, X>
+  >
+  /**
+   * Maximum model steps in one assistant response. Defaults to Infinity.
+   */
+  maxSteps?: number
+  /** Progress is durably flushed at either limit, whichever is reached first. */
+  progress?: { maxChunks?: number; maxDelayMs?: number }
+  /**
+   * Run local tool executions one at a time on this lane. By default,
+   * independent tools run concurrently.
+   */
+  toolLane?: string
+} & AgentLoopOptions<M, D, T, X, H>
+
+type AgentServerOptions<
+  M extends UIMessage,
+  D extends AIEventDefs<M> & EventDefs,
+  S,
+  T extends ToolSet,
+  X extends object = Record<never, never>,
+  H extends string = string,
+> = AgentModelOptions<M, D, T, X, H> &
+  Omit<
+    ServerOptions<D, Record<never, never>, Reducer<D, S>>,
+    'contract' | 'handlers'
+  > & {
+    /** Handlers for application events. */
+    handlers?: ServerOptions<D, Record<never, never>, Reducer<D, S>>['handlers']
+  }
+
+export type AgentOptions<
+  M extends UIMessage,
+  E extends EventDefs,
+  T extends ToolSet,
+  H extends string = string,
+> = AgentServerOptions<
+  NoInfer<M>,
+  AIEventDefs<NoInfer<M>> & E,
+  AIState<NoInfer<M>>,
+  T,
+  Record<never, never>,
+  H
+> & {
+  /** Identity: prefixes storage keys and queue messages. */
+  name: string
+  /**
+   * Server-only application events. Browsers push application events through
+   * a shared `agentContract()`.
+   */
+  events?: E
+  /** Optional stricter schema for custom UIMessage metadata/data/tool types. */
+  messageSchema?: StandardSchemaV1<M>
+}
+
+export type AgentFromContractOptions<
+  D extends AIEventDefs<AIMessageOf<D>> & EventDefs,
+  S,
+  T extends ToolSet,
+  Name extends string = string,
+  X extends object = Record<never, never>,
+  H extends string = string,
+> = AgentServerOptions<AIMessageOf<D>, D, S, T, X, H> & {
+  /**
+   * A shared `agentContract()`. Its application state reaches every resolver
+   * as `state`; a fully custom contract is core A2, served by `createServer()`.
+   */
+  contract: Contract<
+    D,
+    Record<never, never>,
+    Reducer<D, S> & { readonly name: Name; readonly '~appState': X }
+  >
+}
+
+/**
+ * An A2 server for the AI protocol; `typeof` it types `useAgent`. `Name` is
+ * its reducer's name: the built-in one lets contract-free clients fold state.
+ */
+export type Agent<
+  D extends EventDefs,
+  S,
+  Name extends string = string,
+> = A2Server<D, Record<never, never>, Reducer<D, S> & { readonly name: Name }>
+
+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 withModelSettings = <T extends ToolSet>(options: {
+  generation: AgentGenerationSettings<T>
+  settings: ModelSettings
+}): AgentGenerationSettings<T> => {
+  const { generation, settings } = options
+  if (settings.reasoning === undefined && settings.speed === undefined)
+    return generation
+  const { speed: _speed, ...gateway } =
+    generation.providerOptions?.['gateway'] ?? {}
+  return {
+    ...generation,
+    ...(settings.reasoning === undefined
+      ? {}
+      : { reasoning: settings.reasoning }),
+    ...(settings.speed === undefined
+      ? {}
+      : {
+          providerOptions: {
+            ...generation.providerOptions,
+            gateway:
+              settings.speed === 'fast'
+                ? { ...gateway, speed: 'fast' }
+                : gateway,
+          },
+        }),
+  }
+}
+
+const instructionTexts = (instructions: Instructions | undefined): string[] =>
+  instructions === undefined
+    ? []
+    : typeof instructions === 'string'
+      ? [instructions]
+      : (Array.isArray(instructions) ? instructions : [instructions]).map(
+          (message) => message.content,
+        )
+
+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)
+}
+
+/** Sessions whose latest step prompt one process keeps for that step's tools. */
+const PROMPT_SESSIONS = 64
+
+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 DeltaChunk = Extract<
+  UIMessageChunk,
+  { type: 'text-delta' | 'reasoning-delta' | 'tool-input-delta' }
+>
+
+const DELTA_KEYS: Record<DeltaChunk['type'], ReadonlySet<string>> = {
+  'text-delta': new Set(['type', 'id', 'delta', 'providerMetadata']),
+  'reasoning-delta': new Set(['type', 'id', 'delta', 'providerMetadata']),
+  'tool-input-delta': new Set(['type', 'toolCallId', 'inputTextDelta']),
+}
+
+const isDeltaChunk = (chunk: UIMessageChunk): chunk is DeltaChunk =>
+  Object.hasOwn(DELTA_KEYS, chunk.type) &&
+  Object.keys(chunk).every((key) =>
+    DELTA_KEYS[chunk.type as DeltaChunk['type']].has(key),
+  ) &&
+  typeof (chunk.type === 'tool-input-delta'
+    ? chunk.inputTextDelta
+    : (chunk as { delta?: unknown }).delta) === 'string'
+
+// Adjacent deltas of one part project exactly as their concatenation: the text
+// appends and the last defined `providerMetadata` wins.
+const joinDeltas = (
+  left: DeltaChunk,
+  right: DeltaChunk,
+): DeltaChunk | undefined => {
+  if (left.type === 'tool-input-delta')
+    return right.type === 'tool-input-delta' &&
+      right.toolCallId === left.toolCallId
+      ? { ...left, inputTextDelta: left.inputTextDelta + right.inputTextDelta }
+      : undefined
+  if (
+    right.type === 'tool-input-delta' ||
+    right.type !== left.type ||
+    right.id !== left.id
+  )
+    return undefined
+  const providerMetadata =
+    right.providerMetadata !== undefined
+      ? right.providerMetadata
+      : left.providerMetadata
+  return {
+    ...left,
+    delta: left.delta + right.delta,
+    ...(providerMetadata === undefined ? {} : { providerMetadata }),
+  }
+}
+
+const mergeDeltas = (chunks: UIMessageChunk[]): UIMessageChunk[] => {
+  const merged: UIMessageChunk[] = []
+  for (const chunk of chunks) {
+    const previous = merged.at(-1)
+    const joined =
+      previous !== undefined && isDeltaChunk(previous) && isDeltaChunk(chunk)
+        ? joinDeltas(previous, chunk)
+        : undefined
+    if (joined === undefined) merged.push(chunk)
+    else merged[merged.length - 1] = joined
+  }
+  return merged
+}
+
+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,
+  X extends object,
+>(options: {
+  agentName: string
+  context: AgentGenerateContext<M, D, T, X>
+  messageMetadata: AgentMessageMetadata<M, D, T, X> | 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.event.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.event.payload.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
+  // Flush as soon as the previous write finishes: chunks that arrive while
+  // it is in flight wait in the stream and share the next batch.
+  const maxChunks = options.progress?.maxChunks ?? 128
+  const maxDelayMs = options.progress?.maxDelayMs ?? 0
+  let lastFlush = Date.now()
+  const batch = (): AgentGenerationProgress => ({
+    type: 'progress',
+    chunks: mergeDeltas(pending.splice(0)),
+  })
+  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 batch()
+          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 batch()
+        lastFlush = Date.now()
+      }
+    }
+  } catch (error) {
+    if (pending.length > 0) yield batch()
+    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 batch()
+    }
+    throw error
+  }
+  if (pending.length > 0) {
+    yield batch()
+  }
+  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 },
+      ],
+    },
+    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>
+  /** A harness's tool calls run without approval. */
+  approvals?: 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 =
+        options.approvals === false
+          ? 'automatic'
+          : 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
+}
+
+// Options of the AI SDK harness, which live in it, not on agent().
+const AI_SDK_HARNESS_OPTIONS = [
+  'generation',
+  'generate',
+  'compaction',
+  'messageMetadata',
+] as const
+
+const assertNoLoopOptions = (options: { harness?: { type: string } }): void => {
+  const harness = options.harness?.type ?? 'ai-sdk'
+  for (const key of AI_SDK_HARNESS_OPTIONS) {
+    if (!Object.hasOwn(options, key)) continue
+    throw new TypeError(
+      harness === 'ai-sdk'
+        ? `${key} belongs to the harness: agent({ harness: { type: 'ai-sdk', ${key} } })`
+        : `${key} is an option of the AI SDK harness; ${harness}() runs its own loop`,
+    )
+  }
+}
+
+export function createHandlers<
+  M extends UIMessage,
+  D extends AIEventDefs<M> & EventDefs,
+  T extends ToolSet = ToolSet,
+  X extends object = Record<never, never>,
+>(
+  options: HandlersOptions<M, D, T, X>,
+): NonNullable<ServerOptions<D>['handlers']> {
+  if (options.model === undefined) {
+    throw new TypeError('agent 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')
+  }
+
+  assertNoLoopOptions(options)
+  const configured = options.harness
+  const loop: Omit<AISDKHarness<M, D, T, X>, 'type'> = configured?.type ===
+  'ai-sdk'
+    ? configured
+    : {}
+  const harness: HarnessDriver | undefined =
+    configured === undefined || configured.type === 'ai-sdk'
+      ? undefined
+      : harnessDriver(configured)
+  const states = options.harnessStates ?? harnessStates()
+  if (harness !== undefined) {
+    for (const [name, tool] of Object.entries(options.tools ?? {})) {
+      const needsApproval = (tool as { needsApproval?: unknown }).needsApproval
+      if (needsApproval !== undefined && needsApproval !== false)
+        throw new TypeError(
+          `a harness runs tools without approval; '${name}' sets needsApproval`,
+        )
+    }
+  }
+
+  const configuredCompaction =
+    loop.compaction ??
+    (loop.generate === undefined && harness === undefined ? {} : false)
+  const staticCompaction =
+    typeof configuredCompaction === 'function'
+      ? undefined
+      : validateCompaction({
+          compaction: configuredCompaction,
+          explicit: loop.compaction !== undefined,
+          generation:
+            typeof loop.generation === 'function' ? undefined : loop.generation,
+          tools: options.tools,
+        })
+
+  // The harness's own tools come first, so an agent tool with a name replaces them.
+  const tools = (
+    harness === undefined
+      ? (options.tools ?? {})
+      : { ...harness.tools, ...options.tools }
+  ) as T
+  const toolRecovery: Readonly<Record<string, ToolRecovery | undefined>> =
+    options.toolRecovery ?? {}
+  for (const [name, recovery] of Object.entries(toolRecovery)) {
+    if (!Object.hasOwn(tools, name))
+      throw new TypeError(
+        `toolRecovery names '${name}', which is not one of the agent's tools`,
+      )
+    if (typeof (tools[name] as RuntimeTool).execute !== 'function')
+      throw new TypeError(
+        `toolRecovery names '${name}', which has no execute function`,
+      )
+    if (recovery !== 'rerun' && recovery !== 'report')
+      throw new TypeError(
+        `toolRecovery for '${name}' must be 'rerun' or 'report'`,
+      )
+  }
+  const telemetry = options.telemetry ?? CONSOLE_TELEMETRY
+  const maxSteps = options.maxSteps ?? Number.POSITIVE_INFINITY
+  const control = createControlRuntime({
+    contract: options.contract,
+    telemetry,
+  })
+  const controlHandler: typeof control.handler = (ctx) =>
+    telemetry.span(
+      'a2.ai.control',
+      {
+        'a2.contract': options.contract.name,
+        'a2.session_id': ctx.event.sessionId,
+        'a2.ai.control.type': ctx.event.type,
+        'a2.ai.control.id': ctx.event.id,
+        'a2.ai.control.attempt': ctx.attempt,
+      },
+      () => control.handler(ctx),
+    )
+  const coordinator = control.coordinator
+  const contextReducer = createContextReducer<M, D>({
+    contract: options.contract,
+  })
+  const readContext = async (
+    session: HandlerContext<D>['session'],
+    through: number | 'latest',
+  ) => {
+    const snapshot = await session.state(contextReducer, { through })
+    return snapshot
+  }
+  // A session's next step starts only after its tools settle, so only its
+  // latest step's prompt is ever reused. A miss rebuilds the prompt from the
+  // context checkpoint, so eviction is memory policy, never correctness.
+  const prompts = boundedCache<
+    string,
+    { generationId: string; messages: Promise<ModelMessage[]> }
+  >({ maxEntries: PROMPT_SESSIONS, maxBytes: PROMPT_SESSIONS })
+  const cachePrompt = ({
+    sessionId,
+    generationId,
+    messages,
+  }: {
+    sessionId: string
+    generationId: string
+    messages: Promise<ModelMessage[]>
+  }): void =>
+    // Entries count as one byte, so the bound is the session count.
+    prompts.set(sessionId, { generationId, messages }, 1)
+  const forgetPrompt = (sessionId: string, generationId: string): void => {
+    if (prompts.get(sessionId)?.generationId === generationId)
+      prompts.delete(sessionId)
+  }
+
+  type RuntimeTool = {
+    execute?: (
+      input: unknown,
+      options: {
+        toolCallId: string
+        messages: ModelMessage[]
+        abortSignal?: AbortSignal
+        experimental_sandbox?: Experimental_SandboxSession
+      },
+    ) => 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 sessionId = ctx.event.sessionId
+    const cached = prompts.get(sessionId)
+    if (cached?.generationId === call.generationId) return cached.messages
+    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 telemetry.span(
+        'a2.ai.context',
+        {
+          'a2.contract': options.contract.name,
+          'a2.session_id': ctx.event.sessionId,
+          'a2.ai.context.request_id': call.requestId,
+          'a2.ai.context.phase': 'tool',
+        },
+        () =>
+          modelContext({
+            messages: state.messages.filter(
+              (message) => state.messageIndexes[message.id]! <= frontier,
+            ),
+            state,
+            tools,
+          }),
+      )
+    })()
+    cachePrompt({
+      sessionId,
+      generationId: call.generationId,
+      messages: computation,
+    })
+    void computation.catch(() => forgetPrompt(sessionId, call.generationId))
+    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[],
+    sandbox: Experimental_SandboxSession | undefined,
+  ): Promise<AppendInput<D> | void> => {
+    let output: unknown
+    try {
+      output = await execute(call.input, {
+        toolCallId: call.toolCallId,
+        messages,
+        abortSignal: ctx.signal,
+        ...(sandbox === undefined ? {} : { experimental_sandbox: sandbox }),
+      })
+    } 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 report = toolRecovery[call.toolName] === 'report'
+    const interrupted = () =>
+      resultEvent(call, `${ctx.event.id}:execution:error`, {
+        error: `Tool '${call.toolName}' was interrupted and may have partly run.`,
+      })
+    // A thrown failure never follows `execute` for a reported tool (see
+    // below), so only a lapsed attempt may have reached it.
+    if (report && ctx.attempt > 1 && !failedPreviousAttempt.has(ctx))
+      return interrupted()
+    const messages = await promptMessages(input)
+    // A sandbox that fails to resolve fails the attempt, which A2 retries;
+    // it is not the tool's failure to report to the model.
+    const sandbox =
+      harness?.sandbox === undefined
+        ? undefined
+        : await resolve(harness.sandbox, {
+            session: { id: ctx.session.id },
+            signal: ctx.signal,
+          })
+    if (checkAbort(ctx.signal)) return
+    const scope: AmbientToolScope = {
+      contract: options.contract,
+      context: ctx,
+    }
+    // Async iteration resumes in the caller's context, so the whole
+    // execution, not just the execute call, runs inside the scope.
+    const run = () =>
+      toolScopeStorage.run(scope, () =>
+        runToolExecution(ctx, call, execute, messages, sandbox),
+      )
+    if (!report) return run()
+    try {
+      // Undefined means a user cancellation after `execute` started.
+      return (await run()) ?? (await interrupted())
+    } catch {
+      // A lapsed claim surrenders; the next attempt reports the call.
+      checkAbort(ctx.signal)
+      return interrupted()
+    }
+  }
+
+  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, X> = {
+      event: ctx.event,
+      messages: contextMessages({ state, coordinator: coordinatorState }),
+      // The contract registered this reducer with its declared state type.
+      state: (snapshot.state.app ?? {}) as X,
+      session: {
+        state: (reducer, readOptions) =>
+          ctx.session.state(reducer, {
+            ...readOptions,
+            through: readOptions?.through ?? snapshot.index,
+          }),
+      },
+      signal: ctx.signal,
+    }
+
+    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 startEvents = async (
+      started: GenerationStartedPayload,
+      metadataModelId?: string,
+    ): Promise<AppendInput<D>[]> => {
+      const events: AppendInput<D>[] = []
+      if (metadataModelId !== undefined) {
+        events.push({
+          type: 'ai.model.metadata.requested',
+          id: await aiEventId(
+            'a2.ai.model.metadata',
+            options.contract.name,
+            ctx.event.sessionId,
+            metadataModelId,
+          ),
+          payload: { modelId: metadataModelId },
+        } as AppendInput<D>)
+      }
+      if (previous) {
+        const superseded: GenerationFailedPayload = {
+          requestId,
+          messageId: previous.messageId,
+          generationId: previous.generationId,
+          responseMessageId: previous.responseMessageId,
+          error: 'generation attempt was superseded after an incomplete run',
+          superseded: true,
+        }
+        events.push({
+          type: 'ai.generation.failed',
+          id: await aiEventId('a2.ai.superseded', previous.generationId),
+          payload: superseded,
+        } as AppendInput<D>)
+      }
+      events.push({
+        type: 'ai.generation.started',
+        id: generationId,
+        payload: started,
+      } as AppendInput<D>)
+      return events
+    }
+    const startedPayload = (model?: string): GenerationStartedPayload => ({
+      requestId,
+      messageId: request.messageId,
+      generationId,
+      responseMessageId,
+      attempt,
+      ...(model === undefined ? {} : { model }),
+      promptThroughIndex: snapshot.index,
+    })
+
+    let resolvedModel: string | undefined
+    let resolving = true
+    let generationStarted = false
+    try {
+      const choice = await resolve(options.model, resolverContext)
+      if (choice === undefined) {
+        throw new TypeError('the model resolver returned undefined')
+      }
+      const settings: ModelSettings =
+        typeof choice === 'string' ? { model: choice } : choice
+      const model = settings.model
+      if (typeof model !== 'string' || model === '')
+        throw new TypeError('the model must be an AI Gateway model ID')
+      resolvedModel = model
+      if (checkAbort(ctx.signal)) return
+      const resolvedInstructions =
+        options.instructions === undefined
+          ? undefined
+          : await resolve(options.instructions, resolverContext)
+      if (checkAbort(ctx.signal)) return
+      const resolvedGeneration: AgentGenerationSettings<T> = await resolve(
+        loop.generation ?? {},
+        resolverContext,
+      )
+      if (checkAbort(ctx.signal)) return
+      if (
+        resolvedGeneration === null ||
+        typeof resolvedGeneration !== 'object' ||
+        Array.isArray(resolvedGeneration)
+      )
+        throw new TypeError('the generation resolver must return settings')
+      const generation = withModelSettings({
+        generation: resolvedGeneration,
+        settings,
+      })
+      const compaction =
+        typeof configuredCompaction === 'function' ||
+        typeof loop.generation === 'function'
+          ? validateCompaction({
+              compaction:
+                typeof configuredCompaction === 'function'
+                  ? await resolve(configuredCompaction, resolverContext)
+                  : staticCompaction!,
+              explicit: loop.compaction !== undefined,
+              generation,
+              tools: options.tools,
+            })
+          : staticCompaction!
+      if (checkAbort(ctx.signal)) return
+      resolving = false
+
+      const catalogModelId = gatewayModelId(model)
+      const gatewayOptions = 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 generationEvents = await control.append({
+        ctx,
+        name: 'generation-start',
+        events: await startEvents(
+          startedPayload(model),
+          discoversMetadata &&
+            !Object.hasOwn(state.modelMetadata, catalogModelId)
+            ? catalogModelId
+            : undefined,
+        ),
+      })
+      const startIndex = generationEvents.find(
+        (event) => event.id === generationId,
+      )!.index
+      generationStarted = true
+
+      if (checkAbort(ctx.signal)) return
+
+      const promptCoordinatorState = coordinatorState
+      const { messages } = resolverContext
+      let generationMessages = messages
+      let modelMessages = await telemetry.span(
+        'a2.ai.context',
+        {
+          'a2.contract': options.contract.name,
+          'a2.session_id': ctx.event.sessionId,
+          'a2.ai.context.request_id': requestId,
+          'a2.ai.context.phase': 'generation',
+        },
+        () => modelContext({ messages, state, tools }),
+      )
+      const baseContext: AgentGenerateContext<M, D, T, X> = {
+        ...resolverContext,
+        generationId,
+        modelMessages,
+        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: 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 = await telemetry.span(
+            'a2.ai.compaction',
+            {
+              'a2.contract': options.contract.name,
+              'a2.session_id': ctx.event.sessionId,
+              'a2.ai.compaction.request_id': requestId,
+              'a2.ai.compaction.generation_id': generationId,
+              'a2.ai.compaction.policy':
+                'shouldCompact' in policy ? 'custom' : 'automatic',
+            },
+            async () =>
+              !('shouldCompact' in policy)
+                ? {
+                    messages: [] as M[],
+                    ...(await summarize({
+                      agentName: options.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,
+        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 telemetry.span(
+          'a2.ai.context',
+          {
+            'a2.contract': options.contract.name,
+            'a2.session_id': ctx.event.sessionId,
+            'a2.ai.context.request_id': requestId,
+            'a2.ai.context.phase': 'refresh',
+          },
+          () =>
+            modelContext({
+              messages: generationMessages,
+              state: currentState,
+              tools,
+            }),
+        )
+      }
+      cachePrompt({
+        sessionId: ctx.event.sessionId,
+        generationId,
+        messages: 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, X> = {
+        ...baseContext,
+        messages: generationMessages,
+        modelMessages,
+      }
+      const source =
+        harness !== undefined
+          ? await harness.step({
+              agentName: options.contract.name,
+              sessionId: ctx.event.sessionId,
+              requestIndex: ctx.event.index,
+              generationId,
+              responseMessageId,
+              throughIndex: snapshot.index,
+              messages: generationMessages,
+              model,
+              ...(settings.reasoning === undefined
+                ? {}
+                : { reasoning: settings.reasoning }),
+              ...(settings.speed === undefined
+                ? {}
+                : { speed: settings.speed }),
+              instructions: instructionTexts(resolvedInstructions),
+              tools,
+              log: harnessLog({
+                states,
+                session: ctx.session as Parameters<
+                  typeof harnessLog
+                >[0]['session'],
+              }),
+              signal: ctx.signal,
+            })
+          : loop.generate === undefined
+            ? await generateWithAISDK({
+                agentName: options.contract.name,
+                context: generateContext,
+                messageMetadata: loop.messageMetadata,
+              })
+            : { stream: await loop.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 = {
+          startIndex,
+          chunks: update.chunks,
+        }
+        const lifecycle = await lifecycleEvents<D, T>({
+          requestId,
+          messageId: responseMessageId,
+          generationId,
+          sequence,
+          chunks: update.chunks,
+          pending: pendingToolCalls,
+          tools,
+          generation,
+          approvals: harness === undefined,
+        })
+        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 = loop.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' ||
+              (loop.generate === undefined &&
+                pending.classification === 'unknown'),
+          )
+          .map((pending) => toolCalledEvent<D>(pending.call)),
+      )
+      if (finish.finishReason === 'tool-calls') {
+        return [...pendingEvents, completionEvent]
+      }
+      forgetPrompt(ctx.event.sessionId, generationId)
+      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 && !resolving) throw error
+      // A resolver or its result failed before the model ran: record the
+      // attempt and fail it once, like a provider error, rather than retrying.
+      if (!generationStarted)
+        await control.append({
+          ctx,
+          name: 'generation-start',
+          events: await startEvents(startedPayload(resolvedModel)),
+        })
+      forgetPrompt(ctx.event.sessionId, generationId)
+      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>
+    }
+  }
+
+  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: controlHandler,
+    },
+    'ai.work.reported': { lane: 'a2.ai.control', handler: controlHandler },
+    'ai.session.closed': { lane: 'a2.ai.control', handler: controlHandler },
+    '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: (ctx) =>
+        telemetry.span(
+          'a2.ai.generate',
+          {
+            'a2.contract': options.contract.name,
+            'a2.session_id': ctx.event.sessionId,
+            'a2.ai.generate.request_id': ctx.event.id,
+            'a2.ai.generate.attempt': ctx.attempt,
+          },
+          async () => {
+            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': {
+      ...(options.toolLane === undefined ? {} : { lane: options.toolLane }),
+      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: (ctx) =>
+        telemetry.span(
+          'a2.ai.tool',
+          {
+            'a2.contract': options.contract.name,
+            'a2.session_id': ctx.event.sessionId,
+            'a2.ai.tool.request_id': ctx.event.payload.call.requestId,
+            'a2.ai.tool.call_id': ctx.event.payload.call.toolCallId,
+            'a2.ai.tool.name': ctx.event.payload.call.toolName,
+            'a2.ai.tool.attempt': ctx.attempt,
+          },
+          () => handleToolExecution(ctx),
+        ),
+    },
+  } as NonNullable<ServerOptions<D>['handlers']>
+}
+
+/**
+ * Serve an AI agent: the built-in protocol, its handlers, and A2's store,
+ * scheduler, and telemetry, as one ordinary A2 server. Pass `name` for the
+ * built-in protocol, or a shared `agentContract()` when clients fold
+ * application state.
+ */
+export function agent<
+  T extends ToolSet = ToolSet,
+  M extends UIMessage = UIMessage,
+  E extends EventDefs = Record<never, never>,
+  H extends string = never,
+>(
+  options: AgentOptions<M, E, T, H>,
+): Agent<AIEventDefs<M> & E, AIState<M>, typeof AI_STATE_REDUCER>
+export function agent<
+  D extends AIEventDefs<AIMessageOf<D>> & EventDefs,
+  S,
+  T extends ToolSet = ToolSet,
+  Name extends string = string,
+  X extends object = Record<never, never>,
+  H extends string = never,
+>(options: AgentFromContractOptions<D, S, T, Name, X, H>): Agent<D, S, Name>
+export function agent(
+  options:
+    | AgentOptions<UIMessage, EventDefs, ToolSet>
+    | AgentFromContractOptions<AIEventDefs & EventDefs, AIState, ToolSet>,
+): Agent<AIEventDefs & EventDefs, AIState> {
+  type D = AIEventDefs & EventDefs
+  assertNoLoopOptions(options)
+  const {
+    model,
+    tools,
+    instructions,
+    maxSteps,
+    harness,
+    toolRecovery,
+    progress,
+    toolLane,
+    handlers,
+    ...rest
+  } = options
+  let contract: Contract<D, Record<never, never>, Reducer<D, AIState>>
+  let serverOptions: Omit<
+    ServerOptions<D, Record<never, never>, Reducer<D, AIState>>,
+    'contract' | 'handlers'
+  >
+  if ('contract' in rest) {
+    const { contract: shared, ...remaining } = rest
+    if ('name' in remaining)
+      throw new TypeError('agent takes either name or contract, not both')
+    if (!isAgentContract(shared))
+      throw new TypeError('agent({ contract }) takes an agentContract()')
+    contract = shared
+    serverOptions = remaining
+  } else {
+    const { name, events, messageSchema, ...remaining } = rest
+    contract = agentContract({
+      name,
+      ...(events === undefined ? {} : { events }),
+      ...(messageSchema === undefined ? {} : { messageSchema }),
+    })
+    serverOptions = remaining
+  }
+  const states = harnessStates()
+  const builtIns = createHandlers<UIMessage, D>({
+    contract,
+    model,
+    harnessStates: states,
+    ...(serverOptions.telemetry === undefined
+      ? {}
+      : { telemetry: serverOptions.telemetry }),
+    ...(tools === undefined ? {} : { tools }),
+    ...(instructions === undefined ? {} : { instructions }),
+    ...(maxSteps === undefined ? {} : { maxSteps }),
+    ...(harness === undefined ? {} : { harness }),
+    ...(toolRecovery === undefined ? {} : { toolRecovery }),
+    ...(progress === undefined ? {} : { progress }),
+    ...(toolLane === undefined ? {} : { toolLane }),
+  } as HandlersOptions<UIMessage, D>)
+  for (const type of Object.keys(handlers ?? {})) {
+    if (Object.hasOwn(builtIns, type))
+      throw new TypeError(`agent handles '${type}' itself`)
+  }
+  const server = createServer({
+    ...serverOptions,
+    contract,
+    handlers: { ...builtIns, ...handlers },
+  })
+  registerHarnessStates(server, states)
+  const applicationEvents = 'contract' in rest
+  setServerFetchHooks(server, {
+    validateIngress: (context) =>
+      validateAgentIngress({ context, applicationEvents }),
+  })
+  return server
+}
+
+export type { Instructions, ToolSet }