experimental-a2 0.16.1 → 0.18.0

package/docs/reference/04-ai.mdx

@@ -0,0 +1,722 @@
+---
+title: AI
+description: "`experimental-a2/ai`, `experimental-a2/ai/server`, `experimental-a2/ai/client`, and `experimental-a2/ai/react`."
+---
+
+## `experimental-a2/ai`
+
+The isomorphic AI protocol: event schemas, the `AIState` reducer, pure input
+builders, and `agentContract()` for extending both. Its peer dependency, AI SDK
+v7, is used as types only here. See [Agents](/agents/introduction) for the
+protocol and complete examples.
+
+### `agentContract(options)`
+
+```ts
+agentContract<M extends UIMessage = UIMessage>(options: {
+  name: string
+  events?: Record<string, StandardSchemaV1>
+  messageSchema?: StandardSchemaV1<M>
+  reducer?: {
+    name: string // snapshot identity: rename it when fold changes
+    initialState: X // its keys may not shadow AIState's
+    fold: (state: X, event: ContractEvent) => X
+  }
+}): Contract<Events, {}, AgentReducer<M, Events, X>>
+```
+
+A core contract with the built-in AI protocol plus `events`; the session's
+state is `AIState<M> & X`. Share it when a client needs application events or
+state: serve it with `agent({ contract })` and use it with
+[`useAgent({ api, id, contract })`](#useagentoptions). Otherwise
+`agent({ name })` builds one on the server.
+
+- `events` cannot replace built-in event names.
+- `messageSchema` validates a narrower `UIMessage` in message payloads; without
+  it, the type argument types messages.
+- `reducer.fold` sees `X` and every event, never the transcript, and runs after
+  the AI fold on the server and in every client, so optimistic display carries
+  through.
+- An `initialState` key that `AIState` also has throws a `TypeError` and fails
+  to typecheck.
+- The reducer name is `AI_STATE_REDUCER` (`a2.ai.state.v26`) without
+  `reducer`, else `${reducer.name}+a2.ai.state.v26`, so checkpoints advance when
+  either fold changes. `AgentReducer` types that name (so
+  [`createAgentClient()`](#createagentclientoptions) accepts a plain
+  `agentContract()`) and carries `X` to `agent()`'s resolvers.
+
+See [Add your own events and state](/agents/conversations#add-your-own-events-and-state).
+
+### `TranscriptMessage<M>`
+
+```ts
+type TranscriptMessage<M extends UIMessage> = Omit<M, 'parts'> & {
+  parts: Array<M['parts'][number] | CompactionPart>
+}
+```
+
+The message type of `AIState<M>['messages']` and `deriveUIMessages()`: `M` plus
+the [compaction part](#iscompactionpartpart), so `isCompactionPart()` narrows
+even when `M` declares its own data parts.
+
+### `AIMessageOf<Events>`
+
+The `UIMessage` type a contract's `ai.message.created` schema carries, such as
+`AIMessageOf<typeof contract.events>`; `UIMessage` otherwise. `agent()` types
+messages with it.
+
+### `handlerContext(contract?)`
+
+Returns the current tool execution's durable handler context, an
+`AgentToolContext<D>` with `event`, `attempt`, `session`, and `signal`.
+
+- Tools are plain AI SDK `tool()` definitions, passed through uninterpreted;
+  each local `execute` runs inside the ambient scope. Call it anywhere below
+  `execute`, including awaited helpers and async iteration; elsewhere it throws
+  a `TypeError`.
+- Typed for the built-in protocol by default. Pass the shared `agentContract()`
+  to type application events; a mismatch with the executing agent throws a
+  `TypeError`.
+- `event` is the `ai.tool.execution.requested` work event, whose payload holds
+  the admitted `call`, `generation`, `turnId`, and execution `version`.
+  `ctx.session.schedule()` uses the executing agent's scheduler.
+- Built per attempt, never persisted, never sent to the model or a
+  provider-executed tool; each retry gets a fresh one.
+- Model-phase tool options (`contextSchema`, dynamic descriptions,
+  `needsApproval` predicates, input lifecycle callbacks) pass through untouched,
+  durable execution passes no AI SDK `context` option, and model-phase hooks see
+  tools without local `execute`.
+- `needsApproval` and `generation.toolApproval` predicates are re-evaluated on
+  recovery for the same durable call: keep them deterministic over the input.
+
+See [Tools and approvals](/agents/tools).
+
+### `inputs`
+
+Pure typed builders of `ai.control.requested` commands, for `append()` and
+`push()`. The `useAgent()` actions build the browser ones.
+
+| Input | Events |
+| --- | --- |
+| `inputs.message(message, { generate? })` | queues input; `generate: false` records passive context at admission |
+| `inputs.seed(message)` | queues passive context; non-user roles require a trusted append |
+| `inputs.approval(response)` | answers a pending tool approval |
+| `inputs.input(response)` | answers a pending application input |
+| `inputs.requestInput(request)` | requests application input from trusted server code |
+| `inputs.retry(options)` | retries a failed response |
+| `inputs.stop({ turnId, lastSeenIndex? })` | ends the observed turn and advances when admission is open |
+| `inputs.steer({ turnId, message, lastSeenIndex? })` | puts the new input first for a handoff after the observed turn's current step |
+| `inputs.queue.edit({ message })` | changes a pending input; its ID stays fixed |
+| `inputs.queue.move({ inputId, beforeId })` | moves pending input before an ID; `null` means the end |
+| `inputs.queue.remove({ inputId })` | removes pending input; its submission stays in the log |
+| `inputs.queue.sendNow({ inputId, turnId, lastSeenIndex? })` | promotes an existing queued input for a handoff after the current step; preserves pause |
+| `inputs.pause({ when: 'now' \| 'after-turn' })` | pauses execution now or inbox admission after the turn |
+| `inputs.resume()` | resumes retained work, then inbox admission |
+| `inputs.toolResult(result)` | records a deferred provider-executed tool result from trusted server code |
+| `inputs.interrupt(options)` | interrupts a specific generation/request owner |
+
+- **Receipts.** A push confirms persistence; `ai.control.decided` confirms
+  application with `{ commandId, outcome, reason? }` on the existing stream.
+  `outcome` is `applied` or `rejected`; reasons include `not-pending`,
+  `role-mismatch`, `stale-turn`, `not-found`, `not-user-input`, and `closed`.
+  `state.receipt` holds the latest user receipt.
+- **Trust.** Browser ingress accepts user messages, approval and input
+  responses, interruptions, and explicit retries. `inputs.requestInput()`,
+  `inputs.toolResult()`, and non-user `inputs.seed()` messages are trusted
+  server appends; only built-in handlers append generation requests and AI
+  lifecycle events. No builder covers session lifecycle: append
+  `ai.session.created` and `ai.session.closed` from trusted server code.
+- **IDs.** Message, seed, and steer commands use the input message ID as their
+  event ID, and must. Approval, input-response, and retry builders use stable
+  interaction IDs; other commands use the ID `push()` or `append()` assigns,
+  kept across transport retries. Caller IDs are nonempty, never start with the
+  reserved `a2.ai:`, and are unique across the store; identical events replay
+  and conflicting reuse rejects before append. A2's own IDs are opaque,
+  fixed-length, deterministic `a2.ai:` values; an assistant message's ID is its
+  initial model-request event's ID.
+- **Passive input.** `generate: false` is valid browser input: it admits the
+  user message to `AIState.messages` without a turn. The next generating user
+  message includes the passive ones before it; later ones wait. `inputs.seed()`
+  sets the same flag. Trusted assistant and system seeds are context, not queue
+  cutpoints, and never scheduled, whatever `generate` says. Model output is
+  generation progress, not `ai.message.created`, so a response never starts a
+  turn.
+- **Queue.** Edits are last-write-wins in log order, keep identity and role,
+  and need no confirmation between edits; after admission they return
+  `not-pending`. Removal keeps the submission in the log, so replay cannot
+  recreate it.
+- **Steer and Send now.** Steering prioritizes new input even after the
+  observed turn ends; a matching active turn yields after its current model
+  response and tool batch settle, including authorized deferred provider
+  results (unanswered approval and input waits can close; a denied approval
+  never blocks the handoff); otherwise it starts when idle or waits first
+  behind a different active turn. Both the reprioritization and the later
+  handoff commit atomically. Send now keeps the queued input's ID and content,
+  needs an observed `turnId` (`null` when idle), accepts only user-role input,
+  and promotes passive input; missing targets and stale turns reject before the
+  queue changes. Neither resumes a pause or cuts output at `lastSeenIndex`.
+- **Resume** uses a fresh model request and execution version. Tools without a
+  terminal outcome can rerun; key external effects on their stable
+  `toolCallId`.
+- **Approvals and input.** Request and response payloads carry the active
+  `requestId` and `generationId`, copied from the pending request, so a late
+  response cannot satisfy a newer step.
+- **Retry.** `ai.retry.requested` carries `{ messageId, responseMessageId,
+  retryId }` (one `retryId` per user action) and becomes an
+  `ai.generation.requested` with reason `retry`. It reruns the failed model
+  call, keeping earlier completed steps, their tool results, and committed
+  compactions, and drops the failed call's uncommitted step. Forks and
+  edit-and-resend are application-owned.
+- **Generation events.** `ai.generation.requested` requires
+  `responseMessageId`, plus `sourceGenerationId` for a tool continuation.
+  `ai.generation.failed` sets `stepLimit: true` when `maxSteps` rejects a
+  continuation.
+- **Interruption.** `ai.message.interrupted` is `{ messageId, requestId,
+  reason?, lastSeenIndex? }` or `{ messageId, generationId, reason?,
+  lastSeenIndex? }`: copy `activeRequestId` before the generation starts,
+  `activeGeneration.generationId` after. A request-owned interruption survives
+  that request starting first. An older or mismatched message/owner pair is a
+  no-op. An accepted one fences its owner for good: later events stay in raw
+  history but cannot alter `AIState`, satisfy pending work, or reactivate the
+  response. Tool results completed at or before `lastSeenIndex` stay
+  completed; a final tool result racing a generation failure wins in either
+  order, and the generation stays failed. Interruption and failure drop
+  `input-streaming` tool drafts from the projection and later prompts (raw
+  progress stays); other tool parts keep their terminal handling.
+
+See [Inbox and turn controls](/agents/conversations#inbox-and-turn-controls)
+and [Interrupt and retry](/agents/tools#interrupt-and-retry).
+
+### `reasoningLevels`
+
+```ts
+type ReasoningLevel = 'provider-default' | 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh'
+const reasoningLevels: readonly ReasoningLevel[]
+```
+
+Every `ReasoningLevel`, in order, for pickers. A `model` option returns one in
+[`ModelSettings`](#modelsettings).
+
+### `isCompactionPart(part)`
+
+```ts
+isCompactionPart(part: { type: string }): part is CompactionPart
+
+type CompactionPart = {
+  type: 'data-a2-compaction'
+  id: string // the compacting generation's ID
+  data: {
+    status: 'running' | 'completed' | 'failed' | 'interrupted'
+    inputTokens?: number
+    thresholdTokens?: number
+    summary?: string
+    usage?: LanguageModelUsage
+  }
+}
+```
+
+The transcript part that marks a compaction.
+
+- Folding `ai.compaction.requested` appends it to the active response before
+  the step it compacts for (or opens the response with it). It counts toward
+  that step's recovery base, so Stop cutoffs, failures, and retries keep it.
+- `ai.compaction.completed` settles it in place with `summary` and `usage`. If
+  its generation ends first: `interrupted` (Stop, Pause now, session close) or
+  `failed`. A pending Stop previews `interrupted` on the client.
+- A superseded worker attempt's part is removed; the replacement compacts again
+  if needed.
+- `convertToModelMessages()` skips data parts by default; model context never
+  contains it.
+
+See [Show compaction in the conversation](/agents/conversations#show-compaction-in-the-conversation).
+
+### `events` and `createEvents(options?)`
+
+The built-in Standard Schema definitions, both isomorphic: `events` for the
+default AI SDK `UIMessage`, `createEvents({ messageSchema })` for a more
+specific message type.
+
+### Optimistic AI client state
+
+Every client folding an AI reducer (`agentContract({ reducer })` included)
+shows pending send, edit, move, remove, Send now, steer, pause, resume, and
+Stop commands in `state.messages`, `state.inbox`, and `state.starting`, with no
+extra I/O or raw-history reads.
+
+- An idle, unpaused send joins the conversation immediately with
+  `starting: true` (a speculative turn, not model execution); other sends
+  queue. Turn identities come only from accepted decisions; confirmed turns
+  win.
+- Steer, and Send now against an active turn, show in `state.messages` after
+  the current response, not the inbox, until admission; they stay out of the
+  prompt. Several steering inputs show in admission order, most recent first,
+  and the display survives receipt and hydration, including while paused.
+- A pending Stop clears the displayed `state.active`, generation, and pending
+  approvals and inputs, previews an idle status (paused when the inbox is), and
+  freezes the retained projection at `lastSeenIndex`, until its decision; a
+  rejection restores them.
+- Later local edits stay visible through earlier receipts. Pending commands
+  retire on their `ai.control.decided` receipt or session close; failed pushes
+  roll back.
+- Server reads and folds hold confirmed entries only (`starting: false`).
+  Custom reducers that call `reduceAIState()` or nest the AI fold don't get
+  this display.
+
+See [Optimistic conversation display](/agents/conversations#optimistic-conversation-display).
+
+### `AIState`
+
+The type of the AI reducer's `initialState` and `fold`, server
+`session.state()`, and client snapshots. Hydrate with state and its log index
+together, so seen history never folds twice. The AI fold ignores application
+events. Encoding is internal; no event or tool payload is truncated.
+
+| Field | What it holds |
+| --- | --- |
+| `messages` | [`TranscriptMessage<M>`](#transcriptmessagem) values; server-side, without pending inputs |
+| `inbox` | `{ paused, items }`; items are `{ id, message, generate, afterStepOf? }`, where `afterStepOf` is an observed steering turn that hands off after its current step (removal cancels it, admission consumes it) |
+| `active` | `null` or `{ turnId, input, phase }`; admission freezes `input` |
+| `status` | generation status |
+| `starting` | a speculative optimistic turn |
+| `receipt` | the latest user command receipt |
+| `pendingQueueCommands` | the unresolved queue commands, for the optimistic display |
+| `session` | session lifecycle |
+| `pendingApprovals`, `pendingInputs` | pending tool approvals and application input |
+| `tools` | tool activity, identity and status only; payloads live in message parts |
+| `compaction` | the current or latest compaction |
+| `modelMetadata` | each model's pending, resolved, or unavailable limits |
+| `usage`, `error` | usage per generation; the last error |
+| `activeGeneration` | the started generation |
+| `activeRequestId` | the server-authorized generation request; fences delayed requests before start |
+| `activeRequestReason`, `activeRequestSourceGenerationId` | that request's reason and source generation |
+| `activeResponseMessageId` | the requested response, until `activeGeneration` exists |
+| `activeProjection` | the indexed generation frontier, for exact interruption cutoffs |
+| `responseOwners` | `Record<string, { generationId: string; requestId: string; attempt: number }>`: each response's latest owner, so a superseded owner's late events change nothing |
+| `terminalRequestIds`, `terminalGenerations` | optional `Record<string, true>` and `Record<string, 'completed' \| 'failed' \| 'interrupted' \| 'superseded'>` fences, kept across snapshots and recovery |
+
+- The `paused` status and the `pausing` and `paused` phases mean retained work.
+- `activeProjection` lives from generation start until the response completes,
+  is interrupted or superseded, or a retry or later generation replaces it,
+  including while a step waits on tool, approval, or input barriers, while
+  paused, and while a failed generation awaits retry or interruption. Ordered
+  progress applies only new chunks. It is plain JSON, so checkpoints serialize
+  and clone, but their size grows with retained progress.
+- `input-streaming` tool parts carry best-effort partial JSON for display until
+  the completed input arrives; it never authorizes execution or changes
+  interruption.
+
+See [What happens after a send](/agents/introduction#what-happens-after-a-send).
+
+### `deriveUIMessages(history)` and `reduceAIState(state, event)`
+
+`deriveUIMessages()` folds a raw event history into `TranscriptMessage<M>[]`.
+`reduceAIState()` is the event-at-a-time form the standard reducer uses. Both
+project the same chunk-only protocol synchronously.
+
+## `experimental-a2/ai/server`
+
+### `agent(options)`
+
+```ts
+agent({
+  name: string, // or contract: agentContract(...), never both
+  events?, messageSchema?, // with name: server-only application events
+  model: string | ModelSettings | (context => string | ModelSettings), // an AI Gateway model ID
+  tools?,
+  instructions?,
+  maxSteps?,
+  harness?: // the agent's loop; defaults to { type: 'ai-sdk' }
+    | { type: 'ai-sdk', generation?, generate?, compaction?, messageMetadata? }
+    | Harness, // fx() or pi()
+  progress?,
+  toolLane?: string, // run local tool executions one at a time on this lane
+  toolRecovery?: { [tool]?: ToolRecovery }, // 'rerun' (default) | 'report'
+  handlers?, // application event handlers
+  store?, scheduler?, telemetry?,
+}): Agent<Events, State, Name> // an A2Server
+```
+
+Serves an agent as one ordinary A2 server, returning an `A2Server` (`fetch`,
+`session(id)`, `drain()`, `contract`). Server-only: the browser gets a throwing
+stub.
+
+| Option | What it does |
+| --- | --- |
+| `name` | the built-in protocol, with optional server-only `events` and `messageSchema` |
+| `contract` | a shared `agentContract()`, when clients fold application state |
+| `model` | an AI Gateway model ID, or [`ModelSettings`](#modelsettings) with one, under every harness; a value or per-generation async resolver |
+| `tools` | AI SDK `tool()` definitions; local tools read context with [`handlerContext()`](#handlercontextcontract) |
+| `instructions` | a value or per-generation async resolver |
+| `maxSteps` | a positive integer capping one complete assistant response, under every harness; no limit by default |
+| `harness` | the agent's loop: `{ type: 'ai-sdk', … }` (`AISDKHarness`, the default), [`fx()`](#fx), or [`pi()`](#pisandbox) |
+| `harness.generation` | per-step settings, or a resolver |
+| `harness.messageMetadata` | maps default stream parts to message metadata |
+| `harness.generate` | replaces the default model step |
+| `harness.compaction` | automatic for supported Gateway requests by default |
+| `progress` | durable batching: `maxChunks` (128), `maxDelayMs` (0) |
+| `toolLane` | one lane for every local tool execution, one at a time in admission order; model steps keep their own lane |
+| `toolRecovery` | `'rerun'` (default) or `'report'` per tool, the harness's own tools included |
+| `handlers` | application event handlers; naming an event the agent handles throws a `TypeError` |
+| `store`, `scheduler`, `telemetry` | as for any A2 server; `telemetry` covers Core and AI in one trace ([span catalogue](/reference/adapters#the-span-catalogue)) |
+
+**Contracts.** A contract not built by `agentContract()` throws a `TypeError`
+and fails to typecheck (serve custom contracts with `createServer()`). Messages
+are typed through [`AIMessageOf`](#aimessageofevents). `typeof` the agent types
+`useAgent()` and `createAgentClient()` through a type-only import; `Name`, its
+reducer name, decides whether the contract-free client accepts it.
+
+**AI Gateway.** For Gateway models, A2 merges `caching: 'auto'` into
+`generation.providerOptions.gateway`, and automatic compaction uses the same
+default; your values take precedence and other options are kept. A custom
+`generate` receives your original settings and owns its caching. Gateway calls
+also send an `x-session-affinity` header, stable for the session and free of
+the raw session ID, so supporting providers can reuse their cache; it selects
+no provider and guarantees no hit. Override or suppress it (`undefined`) in
+`generation.headers`, in any casing, not on the model: A2's per-call default
+overrides model headers. See
+[Gateway automatic caching](https://vercel.com/docs/ai-gateway/models-and-providers/automatic-caching).
+
+**`harness`** is the agent's loop. `{ type: 'ai-sdk' }` (`AISDKHarness`), the
+default, runs one AI SDK `streamText()` step per durable generation, with the
+`generation`, `messageMetadata`, `generate`, and `compaction` options below.
+[`fx()`](#fx) and [`pi()`](#pisandbox) run a coding agent's own loop instead.
+The four options exist only in `{ type: 'ai-sdk' }`; passing one to `agent()`
+itself throws a `TypeError` naming where it belongs.
+
+**`fetch`** accepts reads and pushes of `ai.control.requested`, except the
+server-authored `request-input` and `tool-result`, with `send`, `edit`, and
+`steer` limited to user messages. With `contract` it also accepts the
+contract's events; `events` given with `name` stay server-only. Other pushed
+events answer `400`. `fetch(request, { authorize })` adds per-operation policy.
+
+**Model steps.** Under `{ type: 'ai-sdk' }`, each durable generation runs one AI
+SDK `streamText()` step, whose chunks A2 persists once in durable progress
+batches. It passes the model ID to the AI SDK, which resolves it through its
+global provider, AI Gateway unless replaced. Generation requests
+share one durable lane, so a session's model calls never overlap, and a later
+user message waits until the active response and its tool loop reach a terminal
+event (a failed response, until retried or interrupted). A `model`,
+`instructions`, or `generation` resolver that throws or returns an invalid
+value fails the turn once, like a provider error, without retrying; that
+attempt's `ai.generation.started` omits `model` if it never resolved, and
+`retry()` runs the step again. Store failures (`A2Error`) still retry durably.
+See [What happens after a send](/agents/introduction#what-happens-after-a-send).
+
+**Resolver context.** `model`, `instructions`, and `generation` resolvers get
+`{ event, messages, state, session, signal }`, where `state` is the
+application state (`{}` without a contract `reducer`) at the captured
+snapshot, read for free from the model-context checkpoint. Compaction,
+`messageMetadata`, and `generate` callbacks also get `modelMessages`, the
+model-ready prompt with committed summaries. No context exposes raw history or
+an `execution` argument. `context.session.state(reducer)` reads at the captured
+prompt frontier by default; `context.session.state()` returns `AIState` with
+its log index.
+
+**`harness.generation`** holds per-step settings such as `temperature`,
+`maxOutputTokens`, `topP`, provider options, and tool approval policy, as the
+provider supports them. It excludes `stopWhen`, tool execution callbacks, tool
+callers, sandbox execution, and the tool approval secret; everything else,
+`toolsContext` included, reaches the AI SDK untouched. Model-step timeouts work;
+tool-execution timeouts don't. A resolver returns `AgentGenerationSettings` (or
+a promise) once per attempt, before compaction and model dispatch, and also
+governs tool approvals and automatic-compaction compatibility. Static settings
+are validated at construction, resolved ones before use; failures and
+cancellation follow model resolution.
+
+**`harness.messageMetadata(context)`** synchronously maps each default stream part to
+your `UIMessage` metadata type. It gets the `generate` context plus the
+`TextStreamPart` as `part`; its `generation` includes A2's Gateway defaults.
+Metadata for `start` and `finish` parts is recorded with progress and
+shallow-merged onto the assistant message (use `finish`'s `totalUsage` for
+final usage). A custom `generate` skips it. See
+[Store assistant metadata](/agents/conversations#store-assistant-metadata).
+
+**`harness.generate(context)`** gets the resolver context plus the step's
+`generationId`, `modelMessages`, and the resolved `model`, `instructions`,
+`tools`, and `generation`; `messages` and `modelMessages` reflect this step's
+compaction. It returns exactly one model step as a
+`ReadableStream<UIMessageChunk>` writing message
+`event.payload.responseMessageId`; A2 keeps tool execution, continuation, and
+the durable lifecycle. See
+[Replace generation, not durability](/agents/conversations#replace-generation-not-durability).
+
+**Tools.** Independent authorized tool handlers run concurrently with no
+fixed limit. Results and generation completion arrive in either order; a
+continuation needs the closed step and every required terminal result.
+Single-owner terminal events commit atomically with the parent handler's
+completion and carry its durable cause; many-owner joins and preliminary
+outputs append immediately and idempotently. Provider calls and external side
+effects are at least once: give them their own idempotency. An approved
+provider-executed call can satisfy the join from its approval response, and a
+provider tool with declared deferred-result support waits for its provider
+result, which trusted server code submits with
+[`inputs.toolResult(result)`](#inputs); the controller checks it against the
+admitted call (`fetch` rejects it from browsers).
+
+**`toolRecovery`**
+
+- `'report'` skips `execute` when the previous attempt lapsed (its claim
+  expired after a crash, timeout, or frozen process), recording an error result
+  saying the call was interrupted and may have partly run; the model continues
+  from it. A2 can't tell whether the lapsed attempt reached the tool, so a call
+  that never started is reported too.
+- Once `execute` has started, a cancelling Stop or Pause now, or a failure A2
+  would otherwise retry (such as a transient scheduler send failure), records
+  the same result; resuming after Pause now doesn't rerun the call.
+- These still retry and run the tool: an attempt that failed with an error
+  before `execute` (such as a failed store read), and a failure inside A2 while
+  or just after the tool runs (its abort subscription, its result validation).
+- An unknown tool name, a tool without `execute`, or another value throws a
+  `TypeError` at construction.
+
+See [Delivery semantics](/agents/conversations#delivery-semantics).
+
+**`harness.compaction`**
+
+| Value | Behavior |
+| --- | --- |
+| omitted | automatic for supported Gateway requests |
+| `false` | no compaction and no model metadata discovery |
+| `{ thresholdTokens?, instructions? }` | tunes automatic compaction. `thresholdTokens`: a positive safe integer. `instructions`: added to A2's summary prompt; the agent's instructions stay |
+| `{ shouldCompact(context), compact(context) }` | a custom policy |
+| `(context: AgentResolverContext) => CompactionOptions \| Promise<CompactionOptions>` | resolves once per generation to a valid policy or `false`; can await `context.session.state(reducer)` |
+
+- Static options are validated at construction, resolved ones before their
+  generation; each session uses its own value.
+- Discovery: without an explicit threshold, the first generation batches a
+  metadata request into its start write, and an independent handler records the
+  model's limits from the public Gateway catalog in `state.modelMetadata`
+  without delaying dispatch (shared one-hour cache, five-second timeout; no new
+  request per turn, even after exhausted retries). The default threshold is 75%
+  of the context window, lowered for a larger output allowance. While it is
+  unknown, the first request proceeds and context-limit errors fail normally.
+- Direct or custom providers, fallback model lists, and custom generators need
+  explicit configuration. Provider-executed tools, structured output, and
+  forced tool choices skip implicit compaction and reject explicit automatic
+  policies.
+- The estimate is serialized bytes of messages, tools, and instructions,
+  excluding message and part provider options (they still reach the model
+  unchanged); not a tokenizer. A preceding same-model completion calibrates it
+  to reported input usage until a smaller prompt, retry, compaction, or model
+  change.
+- Completed generations record `inputTokenEstimate`. Automatic
+  `ai.compaction.requested` events also record the pre-compaction
+  `inputTokenEstimate`, the calibrated `inputTokens`, and `thresholdTokens`
+  (custom policies omit them), at no extra model call or round trip.
+- The built-in summary is one extra model request that keeps the request prefix
+  for caching and runs no application callbacks, transforms, or tool hooks.
+  A2 stores built-in summaries apart from your typed messages, so a summary
+  needs no message metadata and need not match `messageSchema`.
+  `state.messages` stays intact, marked with a
+  [`data-a2-compaction` part](#iscompactionpartpart);
+  `state.compaction?.status === 'running'` shows activity.
+- Successful compaction is permanent across failure, interruption, retry, and
+  recovery. It defers while tool exchanges or A2-owned tool work are unsettled
+  (one coordinator state read per candidate), and while dead-lettered tool
+  work awaits repair and settlement or session close.
+
+See [Compact long conversations](/agents/conversations#compact-long-conversations).
+
+**Harnesses.** Under `fx()` and `pi()`, each model call the harness makes is one
+durable step of the response, with the same events, progress, steering,
+interruption, `maxSteps`, and recovery as any step. Tool calls it makes become
+ordinary A2 tool calls, executed by A2's tool handlers, and `toolRecovery` may
+name the harness's own tools, such as Pi's `bash`. `model` is resolved per step
+as for any agent. `instructions` and `tools` reach the harness; how they
+combine with its own prompt and tools depends on the harness. Tool approval
+policy lives in `harness.generation`, so a harness agent's tools run without
+approval, and a tool that sets `needsApproval` is rejected.
+
+A harness resumes after a crash at the interrupted step. Finished model calls
+are not made again and finished tool calls do not run again. A2 rebuilds the
+harness for each step from the log, and stores nothing outside it. Each agent
+keeps, in its process's memory, the harness's state at the end of the last
+response it ran there, FX's checkpoint or Pi's session, so a warm process reads
+and replays only the log since; a cold one reads and replays the session from
+its start. A saved state counts only once the step that wrote it is committed,
+so a stale or unusable one costs a longer rebuild, never correctness. See
+[Harnesses](/agents/harnesses).
+
+**`progress`.** A batch is written as soon as the previous write finishes;
+chunks arriving mid-write share the next batch, up to `maxChunks` (128).
+`maxDelayMs` (default 0) lets a batch collect that long after the previous
+write; boundary chunks and `maxChunks` write sooner. Raising it trades token
+latency for fewer progress events.
+
+### `ModelSettings`
+
+```ts
+type ModelSettings = {
+  model: string // an AI Gateway model ID
+  reasoning?: ReasoningLevel
+  speed?: 'fast' | 'standard'
+}
+```
+
+A model with its reasoning level and speed, returned by a `model` option or
+resolver. `reasoning` becomes the AI SDK `reasoning` call option
+([`reasoningLevels`](#reasoninglevels)), FX's effort, or Pi's thinking level. `speed: 'fast'` sets
+`providerOptions.gateway.speed` to prefer AI Gateway's faster tier when the
+model has one; `'standard'` removes a configured speed. Both override the same
+settings in `generation`. See [Choose the model](/agents/introduction#choose-the-model).
+
+### `runWithHandlerContext(ctx, fn)`
+
+The test seam for context-reading tools: runs `fn` with `ctx` as the ambient
+handler context, so tests can call `execute` directly. Inside `fn`,
+`handlerContext()` returns `ctx`, with or without a contract argument.
+
+## `experimental-a2/ai/fx`
+
+### `fx()`
+
+```ts
+fx(): Harness<'fx'>
+```
+
+The [FX](https://fx.sh) harness for `agent({ harness })`, running FX's kernel
+from `libfx` (an optional peer dependency) in the server process. FX adds no
+system prompt and brings no tools: `instructions` is the whole system prompt
+and the agent's `tools` are all FX can call. `reasoning` becomes FX's effort and
+`speed: 'fast'` its fast tier. FX compacts its own context; a compaction
+appears in the transcript as a `data-a2-compaction` part with its summary.
+
+Every model call FX makes goes through A2, which records it as a step. To
+continue a response, A2 restores FX's latest checkpoint and replays the
+response so far from the log: recorded model responses and tool results answer
+the kernel without network calls or tool runs, then FX makes its next model
+call. Replay grows with the response, roughly 0.1 to 0.5 seconds for one of 80
+to 200 tool calls. FX checkpoints hold at most 4 MiB of conversation; past that,
+A2 replays from an earlier checkpoint.
+
+Credentials come from `AI_GATEWAY_API_KEY`, or Vercel's OIDC token on Vercel.
+This entry point is server-only.
+
+## `experimental-a2/ai/pi`
+
+### `pi({ sandbox })`
+
+```ts
+pi({
+  sandbox: ({ session, signal }) => SandboxSession | Promise<SandboxSession>,
+}): Harness<'pi'>
+```
+
+The [Pi](https://pi.dev) harness for `agent({ harness })`, running Pi's own
+agent session from `@earendil-works/pi-coding-agent` (with
+`@earendil-works/pi-ai`, both optional peer dependencies). Pi brings its system
+prompt and its `read`, `write`, `edit`, and `bash` tools, which run in the
+session's sandbox. `instructions` is added to Pi's prompt. The agent's `tools`
+are added to Pi's; a tool with one of their names replaces Pi's. `reasoning`
+becomes Pi's thinking level, and `model` is one of the Gateway models Pi's
+catalog lists. Pi works in the sandbox's working directory; its `bash` runs
+with the sandbox's environment, never the server's. Pi compacts its own
+context; a compaction appears in the transcript as a `data-a2-compaction` part
+with its summary.
+
+- `sandbox` (`HarnessSandbox`, given a `HarnessSandboxContext`) resolves the
+  session's AI SDK sandbox session (`Experimental_SandboxSession` from `ai`).
+  It runs for each local tool execution, whose `execute` receives the sandbox
+  as `experimental_sandbox`, Pi's tools and the agent's alike, and for a step
+  until Pi's session records the sandbox's working directory.
+- It must return the same sandbox for a session every time, and concurrent tool
+  calls call it concurrently. A resolver failure fails that attempt, which A2
+  retries. A2 never closes the sandbox. `pi()` without a `sandbox` function
+  throws a `TypeError`.
+- For each step, A2 restores Pi's session from the end of the last response,
+  replays the response so far from the log, and lets Pi make its next model
+  call. Pi's tool calls are ordinary A2 tool calls: A2 runs Pi's real tool
+  implementations against the sandbox and records their results.
+- Pi's tools move at most 4 MiB from the sandbox to your server per file read
+  or command. A larger file fails `read` or `edit`, and a command whose output
+  passes 4 MiB is stopped and fails `bash`; both errors tell the model to read
+  in parts. Files arrive through the sandbox's `readFile`, so implement it as a
+  stream for the limit to bound the download too.
+
+`pi()` takes `PiOptions`. Credentials come from `AI_GATEWAY_API_KEY`, or
+Vercel's OIDC token on Vercel. This entry point is server-only.
+
+## `experimental-a2/ai/client`
+
+### `createAgentClient(options)`
+
+```ts
+createAgentClient<typeof agent>(options: {
+  api: ClientApi
+  gcTime?: number
+  participant?: string
+  reconnect?, fetch?, webSocket?, // as createClient
+}): AgentClient // an A2Client over the built-in AI protocol
+```
+
+A contract-free client for an `agent()` route, typed by a type-only import of
+the server module. It pushes the built-in AI controls only.
+
+- Accepts only agents whose reducer has the built-in name
+  (`typeof AI_STATE_REDUCER`): `agent({ name })`, or `agent({ contract })` with
+  an `agentContract()` without `reducer`. Extended contracts use
+  `createClient({ contract })`, so the client folds the same state.
+- Use it for pushes outside React, such as a first message before navigating,
+  and pass it to `useAgent({ client })` to share its sessions.
+
+See [Start a session from another page](/agents/introduction#start-a-session-from-another-page).
+
+## `experimental-a2/ai/react`
+
+### `useAgent(options)`
+
+```ts
+useAgent<typeof agent>(options: {
+  id: string
+  initial?: InitialSnapshot<AIState>
+  participant?: string
+} & ({ api: string } | { client: AgentClient })): UseAgentResult
+
+useAgent(options: {
+  id: string
+  initial?: InitialSnapshot<State>
+  participant?: string
+} & (
+  | { api: string; contract: Contract } // a shared agentContract(), imported for real
+  | { client: A2Client } // createClient({ contract, api })
+)): UseAgentResult
+```
+
+One agent session in React: its live optimistic `AIState` and actions that
+fill in protocol identities.
+
+- `api`: one shared client per route for the page's lifetime, reading
+  `globalThis.fetch` per request. `client`: yours, for a custom `fetch`,
+  headers, or `gcTime`. Both accept only built-in-name agents.
+- `contract`: also folds its application state, one client per contract and
+  route; `state` is `AIState & X` and `push` accepts its events. Pass
+  `createClient({ contract, api })` as `client` to share it outside React.
+- Contracts not built by `agentContract()` use core `useSession()` and
+  `inputs`.
+- Keep one options form per call site, unchanged between renders.
+
+The result is the session result (`state`, `index`, `connection`, `push`,
+`events`, `hydrated`, `reconnect`, `loadHistory`, `history`) plus:
+
+| Member | Does |
+| --- | --- |
+| `messages` | `state.messages` |
+| `status` | `state.status` |
+| `indicator` | `'starting'` for an optimistic turn awaiting acceptance, `'compacting'` while a summary runs, `'thinking'` while the current step has no visible part (reasoning and step boundaries don't count), else `null` |
+| `sendMessage(message, { generate? })` | queues a string (one text part) or a `UIMessage` |
+| `steer(message)` | steers the active turn after its current step, or sends when idle |
+| `stop()` | stops the active turn at the rendered frontier |
+| `approve(approval)`, `deny(approval, { reason? })` | answers a pending approval |
+| `respond(input, value)` | answers a pending application input |
+| `retry()` | retries the failed response with a fresh `retryId` |
+| `pause({ when })`, `resume()` | pauses and resumes |
+| `queue.edit(message)`, `queue.move({ inputId, beforeId })`, `queue.remove(inputId)`, `queue.sendNow(inputId)` | edits the inbox |
+
+Every action returns a `PushResult`, like `push()`: it resolves to the
+persisted command events (each `id` is its receipt's `commandId`), rejects
+when the push fails, and its `.confirmed` resolves when the stream delivers
+them back. Actions read identities from the render that created them, so
+`stop()` and `queue.sendNow()` carry the frontier the user saw. An action with
+nothing to address (`stop()` with no active turn, `retry()` with no failed
+one) resolves to an empty array. Actions are rebuilt every render; their
+identity is not stable.