experimental-a2 0.17.0 → 0.18.0

package/docs/guides/06-ai-agents.mdx

@@ -1,1408 +0,0 @@
----
-title: Durable AI agents
-description: Build an AI SDK agent whose messages, streaming progress, tools, approvals, and recovery live in an A2 event log.
----
-
-## Install
-
-Install A2, the AI SDK, and Zod for the examples below:
-
-```bash
-pnpm add experimental-a2 ai zod
-```
-
-The examples use the AI SDK's default global provider, AI Gateway. Add its key
-to your environment:
-
-```bash .env.local
-AI_GATEWAY_API_KEY=your_api_key
-```
-
-## Define the agent
-
-`agent()` is the whole server: the built-in AI protocol, the AI SDK runner, and
-A2's ordinary store, scheduler, telemetry, and handler machinery, assembled as
-one A2 server.
-
-```ts server/assistant.ts
-import { agent } from 'experimental-a2/ai/server'
-
-export const assistant = agent({
-  name: 'support-agent',
-  model: 'openai/gpt-5.6-terra',
-  instructions: 'Help the customer. Be concise.',
-  generation: {
-    temperature: 0.2,
-    maxOutputTokens: 2_000,
-  },
-})
-```
-
-`name` is the agent's identity: it prefixes storage keys and queue messages.
-`experimental-a2/ai/server` is server-only, and a browser bundle that imports it
-fails loudly. Browser code reaches the agent through its route and a type-only
-import, shown below.
-
-A string model id uses the AI SDK's global provider, which is AI Gateway by
-default. `model` also accepts any AI SDK `LanguageModel`, such as a provider
-model returned by `openai('gpt-5.6-terra')`, or an async resolver that chooses a
-model for each generation.
-
-Each durable generation runs one AI SDK `streamText()` step. `generation`
-contains per-step settings such as sampling, token limits, provider options,
-and tool approval policy. A2 owns the stop condition, local tool execution,
-and continuation between steps. Responses have no step limit by default. Set
-`maxSteps` to a positive integer to limit one complete assistant response.
-Individual providers decide which model settings they support. `generation`
-therefore excludes `stopWhen`, tool execution callbacks, tool callers, sandbox
-execution, and the tool approval secret. A2 preserves all other supplied
-settings, including `toolsContext`, when calling the AI SDK. A local tool
-reads its durable execution context later, from the handler that runs it. Model-step
-timeouts are supported; tool-execution timeouts are not.
-
-`generation` also accepts a sync or async resolver with the same context as
-`model`, called once per attempt before compaction and model dispatch. Read
-application state with `session.state()`, which defaults to the captured
-generation snapshot. See the
-[API reference](/reference/api#agentoptions).
-
-For AI Gateway models, the default generator sets
-`generation.providerOptions.gateway.caching` to `'auto'`. A2 merges this
-default with your provider options, with caller-supplied values taking
-precedence. Other Gateway options and provider namespaces are preserved.
-The same default applies to automatic compaction. A custom `generate`
-function receives your original settings and owns its caching policy.
-
-Gateway calls also send an `x-session-affinity` header derived from a SHA-256
-hash of the agent name and session ID. The value stays stable across turns,
-retries, worker restarts, and automatic compaction. No raw session identifier
-is sent in this header. A caller-supplied `generation.headers` entry takes
-precedence, regardless of header casing; an explicit `undefined` suppresses
-A2's default header. Set overrides here, since A2's per-call default can
-override headers configured on the model itself.
-Affinity helps supporting providers reuse their cache; it does not select
-Gateway's provider or guarantee a cache hit.
-See [Gateway automatic caching](https://vercel.com/docs/ai-gateway/models-and-providers/automatic-caching)
-for provider support and cache-write costs.
-
-## Expose the route
-
-One HTTP route gives the browser a read and write path. `GET` streams events;
-`POST` accepts optimistic pushes:
-
-```ts app/api/agent/route.ts
-import { assistant } from '@/server/assistant'
-
-export const GET = assistant.fetch
-export const POST = assistant.fetch
-```
-
-The route never calls the model directly. The browser pushes user messages and
-controls as `ai.control.requested` commands, and `fetch` rejects every
-server-authored event with `400`. The controller admits inputs and schedules
-`ai.generation.requested`; workers run the AI SDK and append progress to the
-same log.
-
-Authentication stays in your route. Here's where you'd do auth, or any other
-checks, then hand the request to `assistant.fetch(request, { authorize })` for
-per-operation policy.
-
-## Render the conversation
-
-Fold the initial state on the server and hand it to a client component:
-
-```tsx app/agent/[sessionId]/page.tsx
-import { assistant } from '@/server/assistant'
-import { Chat } from './chat'
-
-export default async function AgentPage({
-  params,
-}: {
-  params: Promise<{ sessionId: string }>
-}) {
-  const { sessionId } = await params
-  const initial = await assistant.session(sessionId).state()
-  return <Chat sessionId={sessionId} initial={initial} />
-}
-```
-
-An empty session folds to the initial `AIState`. Its log is created lazily when
-the first message is pushed.
-
-`useAgent()` keeps that state live and returns the actions a chat needs:
-
-```tsx app/agent/[sessionId]/chat.tsx
-'use client'
-import type { FormEvent } from 'react'
-import { useState } from 'react'
-import type { StateSnapshot } from 'experimental-a2'
-import type { AIState } from 'experimental-a2/ai'
-import { useAgent } from 'experimental-a2/ai/react'
-import type { assistant } from '@/server/assistant'
-
-const indicatorLabel = {
-  starting: 'Starting…',
-  thinking: 'Thinking…',
-  compacting: 'Compacting…',
-}
-
-export function Chat({
-  sessionId,
-  initial,
-}: {
-  sessionId: string
-  initial: StateSnapshot<AIState>
-}) {
-  const { messages, status, indicator, sendMessage } =
-    useAgent<typeof assistant>({ api: '/api/agent', id: sessionId, initial })
-  const [draft, setDraft] = useState('')
-  const [error, setError] = useState<string | null>(null)
-
-  async function send(event: FormEvent<HTMLFormElement>): Promise<void> {
-    event.preventDefault()
-    const text = draft.trim()
-    if (!text) return
-    setDraft('')
-    setError(null)
-    try {
-      await sendMessage(text)
-    } catch (cause) {
-      setDraft(text)
-      setError(cause instanceof Error ? cause.message : String(cause))
-    }
-  }
-
-  return (
-    <main>
-      <section aria-label="Conversation">
-        {messages.map((message) => (
-          <article key={message.id}>
-            <strong>{message.role === 'user' ? 'You' : 'Agent'}</strong>
-            {message.parts.map((part, index) =>
-              part.type === 'text' ? <p key={index}>{part.text}</p> : null,
-            )}
-          </article>
-        ))}
-        {indicator ? (
-          <p role="status">{indicatorLabel[indicator]}</p>
-        ) : null}
-      </section>
-
-      <form onSubmit={send}>
-        <input
-          aria-label="Message"
-          value={draft}
-          onChange={(event) => setDraft(event.currentTarget.value)}
-        />
-        <button disabled={!draft.trim() || status === 'closed'}>Send</button>
-      </form>
-
-      {error ? <p role="alert">{error}</p> : null}
-    </main>
-  )
-}
-```
-
-The `import type` of the server module is erased at build time, so neither the
-server nor a contract enters the client bundle. The AI protocol and its reducer
-are library code; the type argument only carries the agent's message types. The hook keeps one client per `api` for the page's lifetime,
-and every component that calls `useAgent()` with the same `api` and `id` shares
-one live session. That client reads `globalThis.fetch` on each request; pass
-`client` instead of `api` for a custom `fetch`, headers, or `gcTime`. Actions are
-rebuilt on every render, so do not rely on their identity.
-
-The result is the ordinary session result (`state`, `index`, `connection`,
-`push`, `events`, and history) plus actions, `messages` (the same array as
-`state.messages`), `status`, and `indicator`. `indicator` names what the UI
-shows while nothing new is visible yet: `starting` for an optimistic turn
-awaiting acceptance, `compacting` while a summary runs, `thinking` while the
-current model step has produced no visible part, and `null` otherwise. Reasoning
-and step boundaries do not count as visible output, so the indicator returns
-between tool steps.
-
-`sendMessage()` turns a string into one text part with a fresh message ID, or
-takes a complete `UIMessage`. Every action returns the same result as `push()`:
-it resolves to the persisted command events once they are stored, and its
-`.confirmed` promise resolves when the stream delivers them back. The draft
-clears immediately and returns if the push fails. `state.inbox.items`
-contains pending inputs; `state.messages` contains the admitted conversation.
-
-Users can send another message while a response is active. The message enters
-the durable log immediately, but its turn waits until the active assistant
-response, including every tool step and approval, reaches a terminal event.
-Inbox order defaults to arrival order and can be edited explicitly.
-
-Pass `{ generate: false }` when a user message should update the conversation
-without starting a model turn, as in
-`sendMessage('Order #4411 shipped this morning.', { generate: false })`.
-
-The passive user message appears in `AIState.messages` when admitted. A later user
-message with the default generation behavior includes passive user messages
-before it in model context. Passive user messages after that trigger remain
-outside its prompt and wait for the next generating message. This ordering
-supports ambient agents without letting new background context leak into an
-already queued turn.
-
-## Start a session from another page
-
-Wait for the durable append before navigating, so the destination's server
-render sees the message in its folded state instead of racing the `POST`.
-`createAgentClient()` is the same contract-free client outside React:
-
-```ts app/agent/client.ts
-'use client'
-import { createAgentClient } from 'experimental-a2/ai/client'
-import type { assistant } from '@/server/assistant'
-
-export const assistantClient = createAgentClient<typeof assistant>({
-  api: '/api/agent',
-})
-```
-
-```ts app/agent/open-agent.ts
-'use client'
-import { inputs } from 'experimental-a2/ai'
-import { assistantClient } from './client'
-
-export async function openAgent({
-  sessionId,
-  text,
-  router,
-}: {
-  sessionId: string
-  text: string
-  router: { push(href: string): void }
-}): Promise<void> {
-  await assistantClient.session(sessionId).push(
-    ...inputs.message({
-      id: crypto.randomUUID(),
-      role: 'user',
-      parts: [{ type: 'text', text }],
-    }),
-  )
-  router.push(`/agent/${sessionId}`)
-}
-```
-
-Pass the same client to the destination's hook,
-`useAgent<typeof assistant>({ client: assistantClient, id: sessionId, initial })`,
-so it resolves the live session the push created and reconciles the server
-render without replacing it. Idle session objects expire after five minutes by
-default; configure `gcTime` on `createAgentClient` when a different lifetime
-fits the app.
-
-## Choose the model
-
-`model` takes a model, or `ModelSettings` to choose its reasoning level and
-speed with it:
-
-```ts server/fast-assistant.ts
-import { agent } from 'experimental-a2/ai/server'
-
-export const fastAssistant = agent({
-  name: 'fast-support',
-  model: { model: 'openai/gpt-5.6-terra', reasoning: 'low', speed: 'fast' },
-})
-```
-
-A resolver returns the same shape for each generation, so the choice can come
-from anything it reads, such as the conversation so far:
-
-```ts server/routed-assistant.ts
-import { agent } from 'experimental-a2/ai/server'
-
-export const routedAssistant = agent({
-  name: 'routed-support',
-  model: ({ messages }) =>
-    messages.length > 20
-      ? { model: 'openai/gpt-5.6-terra', reasoning: 'high' }
-      : { model: 'openai/gpt-5.6-luna', speed: 'fast' },
-})
-```
-
-`reasoning` becomes the AI SDK's `reasoning` call option. `speed: 'fast'` sets
-`providerOptions.gateway.speed` to prefer AI Gateway's faster tier when the
-model offers one; `'standard'` removes a configured speed. Both override the
-same settings in `generation`. `reasoningLevels` from `experimental-a2/ai`
-lists the levels, for building a picker. To choose from your app's state, such
-as the user's plan or a picker's selection, see
-[Add your own events and state](#add-your-own-events-and-state).
-
-## What happens after a send
-
-One generating user interaction becomes a durable sequence:
-
-```text
-browser  ai.control.requested           durable input command
-server   ai.message.created             input admitted
-server   ai.control.committed           accepted state changes
-server   ai.control.decided             command receipt
-server   ai.generation.requested         scheduled from durable facts
-server   ai.generation.started
-server   ai.generation.progress          batched UIMessageChunk[]
-server   ai.tool.called                  when present
-server   ai.approval.requested           when present
-server   ai.tool.result                  after concurrent execution or denial
-server   ai.generation.completed         closes this model step
-server   ai.generation.requested         after all sibling tools are terminal
-         ...                             another one-step generation
-server   ai.message.completed
-server   ai.generation.requested         next queued user turn, when present
-```
-
-Tool results and generation completion may arrive in either order. A fast
-automatic tool can finish while the model stream is still open. The join waits
-for both step closure and every required terminal result.
-
-The SSE connection delivers the server events to the same reducer. Progress
-stores streamed output once. Within a batch, adjacent text, reasoning, and
-tool-input deltas of one part are joined into a single chunk. The reducer and the exported
-`deriveUIMessages()` apply those chunks synchronously to produce the current
-`UIMessage`; cumulative message snapshots are not duplicated in the log.
-
-`AIState` exposes `messages`, `status`, `inbox`, `active`,
-`pendingApprovals`, `pendingInputs`, `tools`, `compaction`, per-generation
-`usage`, the latest command `receipt`, and the last generation `error`. It also
-carries the protocol's ownership bookkeeping: `activeGeneration`,
-`activeRequestId`, `activeResponseMessageId`, `activeProjection`,
-`responseOwners`, `terminalRequestIds`, and `terminalGenerations`. The hook's
-actions read these fields for you; lower-level `inputs` builders need them
-explicitly.
-
-`activeProjection` is the temporary indexed generation frontier used for exact
-interruption. It remains available after a generation step completes while the
-response waits on tool, approval, or input barriers, and after a generation
-fails while it awaits retry or interruption. It clears when the response
-completes, is interrupted or superseded, a retry begins, or a later generation
-replaces it.
-
-`activeRequestId` identifies the server-authorized generation request. It
-prevents a delayed request or recovered attempt from taking ownership from the
-current response before its generation starts. `activeResponseMessageId`
-identifies that request's response before `activeGeneration` exists. It is
-`null` after the generation starts.
-
-`responseOwners` keeps the latest generation ID, request ID, and attempt for each response
-message. Late lifecycle events from a superseded generation stay in raw
-history but cannot alter the projected message, even after its replacement
-finishes.
-
-A2 generates fixed-length deterministic IDs in its reserved `a2.ai:` namespace
-for requests, generations, responses, and worker lifecycle events. Treat those
-IDs as opaque. An assistant response uses its first model-request event's ID. Generation requests carry
-`responseMessageId` explicitly; tool continuations also carry `sourceGenerationId`.
-Ownership comes from these fields and the generation's `requestId` and `attempt`,
-so ID strings never embed the preceding tool loop.
-
-Generation requests share one durable lane, so model calls do not overlap.
-The queued-turn policy is the stronger ordering rule: a later user message is
-not scheduled until the current response's complete tool loop finishes. Lane
-FIFO alone would not prevent a newly appended user turn from overtaking a tool
-continuation that has not been appended yet.
-
-## Add tools and approval
-
-Tools are ordinary AI SDK `tool()` definitions. A2 passes them through to
-the AI SDK without interpreting or restricting them. Approval policy
-belongs in `generation`, beside the other per-step settings:
-
-```ts server/with-tools.ts
-import { tool } from 'ai'
-import { z } from 'zod'
-import { agent } from 'experimental-a2/ai/server'
-
-const tools = {
-  closeTicket: tool({
-    description: 'Close a resolved support ticket',
-    inputSchema: z.object({ ticketId: z.string() }),
-    execute: async ({ ticketId }, { toolCallId }) => {
-      // your side effect; toolCallId makes a stable idempotency key:
-      // await closeTicket(ticketId, { idempotencyKey: toolCallId })
-      return { ticketId, closed: true }
-    },
-  }),
-}
-
-export const toolsAssistant = agent({
-  name: 'support-tools',
-  model: 'openai/gpt-5.6-terra',
-  tools,
-  generation: {
-    toolApproval: {
-      closeTicket: 'user-approval',
-    },
-  },
-})
-```
-
-The AI SDK infers the tool input and output from its schemas and
-`execute`. A2 additionally runs each local `execute` inside an ambient
-scope carrying the current durable handler attempt. Read it with
-`handlerContext()` from `experimental-a2/ai`: it returns the same context an
-event handler receives, with `event`, `attempt`, `session`, and `signal`. Tools
-execute an `ai.tool.execution.requested` event after authorization. Its payload
-contains the admitted `call`, its `generation`, and its turn and execution
-version. `handlerContext()` throws when called outside a tool execution. The
-scope survives awaited helpers and async iteration, so any code below `execute`
-can read it. Because the call takes no argument, a tool can live inside the
-`agent()` call that serves it. Pass a shared `agentContract()` to type
-application events on `ctx.session`; A2 checks it against the executing agent.
-
-`generation.toolApproval` is evaluated during the model step, before A2 has a
-durable tool handler. Static policies such as the example above are simplest.
-An input-dependent policy may be a function that returns `user-approval` or
-`approved` from the validated tool input. Approval predicates are
-re-evaluated on recovery for the same durable tool call, so they must be
-deterministic over the tool input; an impure predicate can fork one
-durable call's flow. Model-phase options such as `toolsContext` and
-per-tool `contextSchema` are yours and pass through to the AI SDK
-untouched. Any model-phase hook that receives tool definitions sees
-them without local `execute` functions. The durable A2 context is
-ambient only inside `execute`.
-
-The context's `session` belongs to the agent executing the tool, so its
-`schedule()` method uses that agent's scheduler. For example, this tool
-schedules a reminder as a new user message:
-
-```ts server/set-reminder.ts
-import { tool } from 'ai'
-import { handlerContext, inputs } from 'experimental-a2/ai'
-import { z } from 'zod'
-
-export const setReminder = tool({
-  description: 'Set a reminder for yourself',
-  inputSchema: z.object({
-    delaySeconds: z.number().int().min(1).max(6 * 24 * 60 * 60),
-    reminder: z.string(),
-  }),
-  execute: async ({ delaySeconds, reminder }, { toolCallId }) => {
-    const ctx = handlerContext()
-    await ctx.session.schedule(
-      `reminder:${toolCallId}`,
-      { delay: `${delaySeconds}s` },
-      ...inputs.message({
-        id: `reminder:${ctx.event.id}`,
-        role: 'user',
-        parts: [{ type: 'text', text: `Reminder: ${reminder}` }],
-      }),
-    )
-
-    return { scheduled: true, delaySeconds }
-  },
-})
-```
-
-Add `setReminder` to the agent's `tools` and configure a
-[scheduler](/guides/production).
-The numeric schema lets the model choose any whole-second delay in the
-provider's supported range instead of selecting from a fixed application enum.
-The example uses A2's six-day Vercel Queues limit. The seventh retention day is
-reserved for delivery and retries. Adjust the maximum to match your scheduler
-and plan.
-The schedule name uses `toolCallId`, and the message id uses the durable
-triggering event id. A retry therefore converges on the same timer and message,
-even if a provider reuses tool-call ids in a later generation. When the timer
-arrives, `inputs.message()` queues a durable input command. The
-queued-turn policy starts a fresh response after the active response completes
-or is interrupted. A failed response must be retried or interrupted first.
-If the scheduler send fails ambiguously or transiently, A2 retries the same
-durable tool handler so that identity and target time stay fixed. Deterministic
-adapter rejections are terminal tool errors. A missing scheduler is also a
-normal tool error, so configure one before exposing the tool.
-
-A tool that never reads `handlerContext()` is just an AI SDK tool;
-nothing else changes. To test a context-reading tool directly, wrap the
-call with `runWithHandlerContext(ctx, fn)` from
-`experimental-a2/ai/server`: inside `fn`, `handlerContext()` returns
-`ctx`.
-
-The AI SDK emits an approval request instead of executing the tool. A2 records
-it as `ai.approval.requested`, and the reducer adds it to
-`state.pendingApprovals`. Answer it from the hook:
-
-```tsx app/tools/[sessionId]/approval-controls.tsx
-'use client'
-import { useAgent } from 'experimental-a2/ai/react'
-import type { toolsAssistant } from '@/server/with-tools'
-
-export function ApprovalControls({ sessionId }: { sessionId: string }) {
-  const { state, approve, deny } = useAgent<typeof toolsAssistant>({
-    api: '/api/tools',
-    id: sessionId,
-  })
-
-  return state.pendingApprovals.map((approval) => (
-    <div key={approval.approvalId}>
-      <span>Allow tool call {approval.toolCallId}?</span>
-      <button onClick={() => void approve(approval)}>Allow</button>
-      <button
-        onClick={() => void deny(approval, { reason: 'Denied by the user' })}
-      >
-        Deny
-      </button>
-    </div>
-  ))
-}
-```
-
-`approve()` and `deny()` copy the request, message, generation, and approval
-IDs from the pending approval, so a delayed click cannot authorize a later
-model step. The decision updates the approval part in the projected
-`UIMessage`. A built-in handler executes the approved tool or records a denied
-result. It never bypasses the same sibling join used by automatic tools.
-
-Tool activity follows the full AI SDK chunk lifecycle. Input validation errors,
-execution errors, denials, and preliminary and final outputs become durable
-`ai.tool.result` events. Preliminary outputs keep the tool `running`; a final
-output completes it. Each result has its own event id, so a preliminary result
-cannot deduplicate the final one. Dynamic-tool, provider-executed, provider
-metadata, and tool metadata fields are preserved in the projection.
-
-Independent tool handlers run concurrently as soon as their durable inputs and
-authorization are ready. There is no fixed tool concurrency limit. Set
-`toolLane: 'tools'` on the agent when local tools must run one at a time, for
-example because they share a sandbox; every local tool execution then queues on
-that lane. A private
-coordinator reducer tracks generation closure, cancellation, calls, approvals,
-and terminal results for the active response. Its retained state is bounded;
-completed responses do not accumulate in the coordinator. Each join reads a
-durable reducer snapshot plus the log tail through
-`ctx.session.state(coordinator, { through: 'latest' })`. The snapshot
-is only a cache. Recovery can rebuild the same coordinator state from the event
-log after process death.
-
-A continuation needs the generation to close and every sibling tool to have a
-terminal success, error, or denied result. Racing join handlers call
-`ctx.session.append()` with the same deterministic continuation ID, so append
-idempotency resolves the race. A handler's single-owner terminal result is
-returned and committed atomically with that handler's completion. Preliminary
-streaming tool outputs use immediate appends. An approved provider-executed
-call can satisfy the join through its response. A provider tool that declares
-deferred-result support can wait for its provider result instead of a local
-executor. The authenticated provider callback appends that `ai.tool.result`
-through the trusted server session API. Browser pushes reject lifecycle
-events, including provider results.
-
-`state.pendingInputs` provides the same durable request/response shape for
-application-defined input. Answer one with `respond(input, value)` from the
-hook. Its value stays in raw history and `state.pendingInputs`; resolve
-instructions dynamically or replace `generate` when the value should become
-model context.
-
-## Interrupt and retry
-
-Stop the active turn, or retry a failed response, from the hook:
-
-```tsx app/agent/[sessionId]/turn-controls.tsx
-'use client'
-import { useAgent } from 'experimental-a2/ai/react'
-import type { assistant } from '@/server/assistant'
-
-export function TurnControls({ sessionId }: { sessionId: string }) {
-  const { state, status, stop, retry } = useAgent<typeof assistant>({
-    api: '/api/agent',
-    id: sessionId,
-  })
-
-  if (status === 'failed')
-    return <button onClick={() => void retry()}>Retry</button>
-  return state.active ? (
-    <button onClick={() => void stop()}>Stop</button>
-  ) : null
-}
-```
-
-`stop()` addresses the observed turn and sends the exact confirmed log frontier
-the rendered state showed, not whatever arrived before the click was handled.
-The client immediately previews Stop for that turn. While that generation's
-indexed projection is retained, the client freezes the response at that
-frontier through the request echo and controller decision. A rejected push or
-decision removes the preview.
-The reducer rewinds the indexed generation projection to that
-frontier and keeps the partial text the user actually saw. Tool parts whose
-arguments are still streaming are drafts: interruption removes them from the
-conversation and subsequent model prompts, even if their current JSON parses.
-Their progress remains in the raw log. Accepted tools still awaiting completion
-become `output-error`. An accepted interruption
-terminally fences that request or generation. Later generation, tool, approval,
-input, and compaction events remain in raw history but cannot reactivate it or
-alter the projection.
-Completed tool results at or before the visible frontier remain completed.
-
-Once Stop is persisted, A2's existing cancellation stream aborts running model
-and tool work for that turn without waiting for the control handler. Startup
-checks also skip matching jobs created while Stop is pending. Cancellation is
-cooperative: tools must honor their abort signal. The control handler remains
-responsible for recording the interruption and advancing the inbox; a Stop for
-an older turn cannot cancel its successor.
-
-`retry()` records `inputs.retry()` for the failed response, with a fresh
-`retryId` for each click. The server reruns that failed model call.
-Earlier completed model steps and their tool results remain, including steps
-completed after the latest compaction. The committed summary also remains. For
-example, if a tool succeeds after compaction and the next model call fails, retry
-uses the summary and that tool's result.
-Resending one retry is safe while a later retry remains distinct. The failed
-model call's uncommitted step remains in
-raw history but is excluded from the new prompt and response. Later user messages remain queued while
-the failed response awaits an explicit retry or interruption.
-
-The lower-level `inputs.interrupt()` builder addresses a specific owner. Between
-`ai.generation.requested` and `ai.generation.started`, copy
-`activeRequestId` as `requestId` and `activeResponseMessageId` as `messageId`.
-Once `activeGeneration` exists, send its `generationId` and
-`responseMessageId` instead. A request-owned interruption remains valid if
-that same request starts before the append commits. Every interruption has
-exactly one of `requestId` or `generationId`, so a delayed action cannot stop
-later work that reuses the response message. After a generation completes,
-copy the owner from a pending approval, pending input, or running tool while
-the response is still waiting.
-
-Applications own conversation forks and edit-and-resend flows for previously
-admitted messages. A2's retry operation continues the current response.
-
-## Append from the server
-
-Browser interactions go through the hook for instant state. Server-originated
-turns use the same inputs with `append()`:
-
-```ts server/append-message.ts
-import { inputs } from 'experimental-a2/ai'
-import { assistant } from './assistant'
-
-export async function appendServerMessage(sessionId: string, text: string) {
-  await assistant.session(sessionId).append(
-    ...inputs.message({
-      id: crypto.randomUUID(),
-      role: 'user',
-      parts: [{ type: 'text', text }],
-    }),
-  )
-}
-```
-
-This path fits webhooks, jobs, and other backend sources. A connected browser
-still receives the events over SSE, but it has no optimistic overlay for an
-interaction that began elsewhere.
-
-## The built-in inputs
-
-The hook's actions build these commands. `inputs` exposes the same pure,
-isomorphic builders for raw `push()` and server `append()`:
-
-| Input | Events |
-| --- | --- |
-| `inputs.message(message, { generate? })` | queues input; `generate: false` queues passive context |
-| `inputs.seed(message)` | records `generate: false`; non-user roles require a trusted append |
-| `inputs.approval(response)` | requests a decision on a pending approval |
-| `inputs.input(response)` | records an application input response fact |
-| `inputs.requestInput(request)` | records a trusted server request for application input |
-| `inputs.retry(options)` | requests a fresh attempt for a failed response |
-| `inputs.stop({ turnId, lastSeenIndex? })` | ends the observed turn and advances |
-| `inputs.steer({ turnId, message })` | prioritizes input after the observed turn's current step finishes |
-| `inputs.queue.edit({ message })` | edits a pending input |
-| `inputs.queue.move({ inputId, beforeId })` | reorders pending input; `null` means the end |
-| `inputs.queue.remove({ inputId })` | removes pending input from the inbox |
-| `inputs.queue.sendNow({ inputId, turnId })` | atomically prioritizes queued input and interrupts the observed turn |
-| `inputs.pause({ when })` | pauses now or after the active turn |
-| `inputs.resume()` | resumes retained work and inbox admission |
-| `inputs.toolResult(result)` | records a trusted deferred provider-tool result |
-| `inputs.interrupt(options)` | addresses a specific generation or request |
-
-Builders return `ai.control.requested` commands. Message, approval, input, and
-retry builders identify a stable interaction. Other controls use the event ID
-assigned by `push()` or `append()`; transport retries preserve that ID.
-Generation scheduling considers only user-role `ai.message.created` facts.
-Assistant and system message facts remain context regardless of the `generate`
-field, and model output is recorded as generation progress rather than a new
-message fact, so an assistant reply cannot recursively schedule another turn.
-Browser pushes accept user messages, approval and input responses,
-interruptions, and explicit retries. `inputs.requestInput()` and non-user
-messages built with `inputs.seed()` are for trusted server appends.
-Browser inputs never append server scheduling, seeded non-user messages, or
-lifecycle events.
-Approval and input request/response payloads carry the active `generationId`;
-clients copy it from the pending request so a stale interaction cannot satisfy
-a later model step.
-
-`inputs` deliberately has no session lifecycle methods. The A2 log begins with
-the first append. Apps that use explicit `ai.session.created` or
-`ai.session.closed` lifecycle events append those trusted server facts
-directly.
-
-## Compact long conversations
-
-Compaction is automatic for supported Gateway models. A2 uses the active model
-with the same instructions, tool definitions, and provider settings, and appends
-an internal user message asking for a summary. This preserves the request prefix
-for prompt caching when the provider has a matching cache entry.
-
-```ts server/compacted.ts
-import { agent } from 'experimental-a2/ai/server'
-
-export const compactedAssistant = agent({
-  name: 'compacted-agent',
-  model: 'openai/gpt-5.6-terra',
-})
-```
-
-On first use of each Gateway model in a session, A2 includes
-`ai.model.metadata.requested` in the existing generation-start append. A separate
-handler fetches the public Gateway model catalog and records the selected limits
-in `ai.model.metadata.resolved`. It runs outside the AI turn lane. The first model
-request proceeds immediately; metadata that arrives afterward is available to
-later steps. Returning to a previously used model reuses its durable metadata.
-The catalog is also cached in memory for one hour across agents, with one
-shared in-flight request and a five-second timeout. A failed lookup follows A2's
-handler retry policy without failing the model generation. A model absent from
-the catalog is recorded as unavailable. A pending entry means no result has been
-recorded, including when the metadata handler exhausts its retry budget. A2 does
-not start a fresh lookup on every turn after exhaustion. Inspect the handler
-failure or use an explicit threshold in that case.
-
-The default threshold is 75% of the context window. A larger configured
-`generation.maxOutputTokens` lowers the threshold further to reserve that output
-allowance. This is an input-context policy, not a new output limit. Limits and
-metadata status are available in `state.modelMetadata`.
-
-`compaction: { thresholdTokens: 80_000 }` overrides discovery with an explicit
-positive safe integer. `compaction: { instructions: 'Preserve exact IDs.' }`
-adds guidance to the built-in summary prompt while keeping the derived threshold.
-`compaction: false` disables both compaction and metadata lookup. The `compaction`
-option can also be a resolver receiving the same
-`{ event, messages, session, signal }` context as `model` and
-`instructions`. It returns `false`, automatic options, or a custom policy once
-per generation and can await `session.state(settingsReducer)` to read
-application settings. Use this to select a threshold from application settings
-at the prompt boundary.
-Changes after resolution apply to a later model step. Disabling compaction
-preserves summaries that were already recorded. Custom provider
-models and custom global SDK providers need an explicit threshold. A custom
-`generate` callback keeps compaction disabled unless explicitly configured. Gateway
-fallback model lists also need an explicit threshold appropriate for every model
-they may use.
-
-The input estimate starts from serialized UTF-8 bytes divided by four, including
-model messages, instructions, and tool schemas. When a preceding model call has
-reported token usage for the same model and context, A2 uses that measurement as
-an anchor and estimates subsequent growth. It is not a provider tokenizer and
-does not precisely measure new image or audio tokens. A2 performs no remote token
-counting.
-
-On a cold session without recorded metadata or an explicit threshold, automatic
-compaction waits for discovery. An oversized first prompt is sent normally and
-its provider error becomes a generation failure. A2 does not silently truncate
-it or attempt automatic recovery from a context-limit error. Use an explicit threshold for
-applications that import a large initial conversation. The estimate is a
-compaction trigger, not a definitive overflow check. Provider context-limit
-errors during generation or summarization remain generation failures.
-
-Crossing the threshold adds one summary model request. Application generation
-callbacks, stream transforms, and tool hooks do not run for the summary, and it
-never executes local tools. Provider-executed tools, structured output, and forced
-tool choices disable implicit automatic compaction; explicitly configuring
-automatic compaction for those requests throws. Use a custom policy for them.
-An empty summary or a summary tool call fails the generation instead of replacing
-its context.
-
-A2 records `ai.compaction.requested` before the call and
-`ai.compaction.completed` after a successful summary. The completed event stores
-the summary, its usage, and the exact event frontier it covers. Later model
-requests receive the summary plus everything produced after that frontier,
-including later tool steps in the same assistant message. Queued user messages
-remain queued. Compaction waits until earlier tool calls have terminal results.
-Server execution uses a separate model-context reducer and checkpoint.
-Successful compaction permanently replaces covered context in model requests;
-the raw log and the transcript in `AIState.messages` stay complete.
-
-### Show compaction in the conversation
-
-The transcript marks where each compaction happened. When compaction is
-requested, the reducer adds a `data-a2-compaction` part to the assistant
-response, between the steps before it and the model step it compacted for. A
-compaction before the first step opens the response with that part. Render it
-in the same loop as the other parts:
-
-```tsx app/agent/message-view.tsx
-'use client'
-import type { UIMessage } from 'ai'
-import { isCompactionPart, type TranscriptMessage } from 'experimental-a2/ai'
-
-const compactionLabel = {
-  running: 'Compacting…',
-  completed: 'Context compacted',
-  failed: 'Compaction did not complete',
-  interrupted: 'Compaction stopped',
-}
-
-export function MessageView({
-  message,
-}: {
-  message: TranscriptMessage<UIMessage>
-}) {
-  return (
-    <article>
-      {message.parts.map((part, index) => {
-        if (isCompactionPart(part))
-          return (
-            <details key={index}>
-              <summary>{compactionLabel[part.data.status]}</summary>
-              {part.data.summary ? <p>{part.data.summary}</p> : null}
-            </details>
-          )
-        return part.type === 'text' ? <p key={index}>{part.text}</p> : null
-      })}
-    </article>
-  )
-}
-```
-
-The part's `data` holds `status` plus, when known, `inputTokens`,
-`thresholdTokens`, the `summary`, and its `usage`. It starts `running` and
-settles in place: `completed` when the summary commits, `failed` when its
-generation fails first, and `interrupted` when Stop, Pause now, or session
-close ends it first. A pending Stop previews the part as `interrupted`
-immediately. A worker attempt that recovery supersedes removes its part; the
-replacement attempt compacts again if it still needs to. A completed part stays
-through Stop cutoffs, later failures, and retries of the step that compacted,
-because successful compaction is permanent. The part lives in the state, not the event
-feed, so it survives server rendering, reloads, and other tabs. AI SDK
-`convertToModelMessages()` skips data parts by default, and A2's model context
-never includes it. `state.messages` is typed as `TranscriptMessage<M>[]`: your
-message type with `CompactionPart` added to its parts, so `isCompactionPart()`
-narrows even when your message type declares its own data parts.
-
-`state.compaction` holds the current or latest compaction, and the hook's
-`indicator` reports `compacting` while one runs.
-
-Compaction runs only when retained tool exchanges have final results and all
-A2-owned tool work has settled, including work from stopped or superseded turns.
-A2 checks a fresh coordinator checkpoint before starting a candidate compaction.
-This adds one state read on that path. Unresolved dead-lettered tool work keeps
-compaction deferred until repair and settlement or session closure.
-
-Custom `shouldCompact(context)` and `compact(context)` callbacks remain
-available for deterministic replacement messages or application-specific
-retention. Both receive the typed UI messages and `modelMessages`, the model-ready
-context including any existing summary. Custom generation callbacks also receive
-`modelMessages`; use it when forwarding context to a provider. A2 stores built-in
-summaries separately from application-typed messages, so a summary does not
-need your message metadata or schema.
-
-Successful compaction is a permanent boundary. Failure, interruption, retry, and
-worker recovery never restore the messages it replaced. Retry reruns the failed
-model step from the latest committed context and preserves earlier completed
-steps. A failed summary attempt leaves the previous committed context intact.
-The synthetic summary request is not a user turn or an assistant reply in
-`state.messages`.
-
-## Store assistant metadata
-
-Give the agent a narrower `UIMessage` type to keep generation status and usage
-on the assistant message. `agentContract()` carries the type:
-
-```ts server/metadata-assistant.ts
-import type { LanguageModelUsage, UIMessage } from 'ai'
-import { agentContract } from 'experimental-a2/ai'
-import { agent } from 'experimental-a2/ai/server'
-
-export type MetadataAssistantMessage = UIMessage<{
-  status: 'writing' | 'complete'
-  usage?: LanguageModelUsage
-}>
-
-export const metadataAssistant = agent({
-  contract: agentContract<MetadataAssistantMessage>({
-    name: 'metadata-assistant',
-  }),
-  model: 'openai/gpt-5.6-terra',
-  messageMetadata: ({ part }) => {
-    if (part.type === 'start') return { status: 'writing' as const }
-    if (part.type === 'finish') {
-      return { status: 'complete' as const, usage: part.totalUsage }
-    }
-    return undefined
-  },
-})
-```
-
-The default generator passes `messageMetadata` to the AI SDK's
-`toUIMessageStream()`. The callback receives the same context as `generate`,
-plus its current `TextStreamPart` as `part`. Its return type follows the metadata type in the
-agent's `UIMessage`. Metadata on standard `start` and `finish` chunks enters
-the event log with the rest of the stream. A2 shallow-merges those values onto
-the projected assistant message, so the example exposes `writing` immediately
-and keeps final token usage after completion. The callback is synchronous.
-`useAgent<typeof metadataAssistant>()` types `messages` with the same metadata.
-
-## Add your own events and state
-
-Apps always carry more than the conversation: a plan, a selected ticket, a
-chosen model. Put those events and the state they fold into in a shared
-`agentContract()`. It takes a core `contract()`'s `events`, and its `reducer`
-takes the same `name`, `initialState`, and `fold`:
-
-```ts support-desk.ts
-import { z } from 'zod'
-import { agentContract } from 'experimental-a2/ai'
-
-const noFlags: string[] = []
-
-export const supportDesk = agentContract({
-  name: 'support-desk',
-  events: {
-    'plan.changed': z.object({ plan: z.enum(['free', 'pro']) }),
-    'ticket.flagged': z.object({ ticketId: z.string() }),
-  },
-  reducer: {
-    name: 'support-desk.v1',
-    initialState: { plan: 'free' as 'free' | 'pro', flagged: noFlags },
-    fold: (state, event) =>
-      event.type === 'plan.changed'
-        ? { ...state, plan: event.payload.plan }
-        : event.type === 'ticket.flagged'
-          ? { ...state, flagged: [...state.flagged, event.payload.ticketId] }
-          : state,
-  },
-})
-```
-
-Keep this module isomorphic. `fold` sees your state and every event, but not
-the transcript. The session's state is `AIState` merged with yours, so a key
-that shadows one of `AIState`'s is a type error. The reducer's `name` is its
-snapshot identity: rename it when `fold` changes.
-
-Serve it with `agent({ contract })`. Every resolver receives your state as
-`state`, so model, reasoning level, and speed follow the app:
-
-```ts server/support-desk.ts
-import { agent } from 'experimental-a2/ai/server'
-import { supportDesk } from '../support-desk'
-
-export const supportDeskAgent = agent({
-  contract: supportDesk,
-  model: ({ state }) =>
-    state.plan === 'pro'
-      ? { model: 'openai/gpt-5.6-terra', reasoning: 'high' }
-      : { model: 'openai/gpt-5.6-luna', speed: 'fast' },
-  handlers: {
-    'ticket.flagged': async ({ event }) => {
-      // your side effect; event.id makes a stable idempotency key:
-      // await notifyOnCall(event.payload.ticketId, { idempotencyKey: event.id })
-    },
-  },
-})
-```
-
-`state` is your state as of the snapshot the generation already captured. It
-rides in the checkpoint every model step reads, so it costs no extra read. Each
-model step resolves again, so a change during a turn applies from the next
-step. A resolver that throws fails the turn with its message, like a provider
-error; `retry()` runs it again.
-
-In the browser, pass the contract to `useAgent()`. This import is real, not
-type-only, because the browser folds your state too:
-
-```tsx app/support/desk.tsx
-'use client'
-import { useAgent } from 'experimental-a2/ai/react'
-import { supportDesk } from '@/support-desk'
-
-export function Desk({ id }: { id: string }) {
-  const { state, push, sendMessage } = useAgent({
-    api: '/api/support',
-    id,
-    contract: supportDesk,
-  })
-
-  return (
-    <section>
-      <p>
-        {state.plan} plan, {state.flagged.length} flagged tickets
-      </p>
-      <button
-        onClick={() =>
-          void push({ type: 'ticket.flagged', payload: { ticketId: 'T-1' } })
-        }
-      >
-        Flag T-1
-      </button>
-      <button onClick={() => void sendMessage('Summarize the flagged tickets.')}>
-        Ask
-      </button>
-    </section>
-  )
-}
-```
-
-Browsers push a shared contract's application events like any A2 client, and
-the route's `authorize` decides who may push what. The agent refuses only its
-own server-authored `ai.*` events. Here the plan comes from your billing code,
-not the browser:
-
-```ts app/api/support/route.ts
-import { supportDeskAgent } from '@/server/support-desk'
-
-function handle(request: Request): Promise<Response> {
-  // here's where you'd do auth, or any other checks:
-  return supportDeskAgent.fetch(request, {
-    authorize: (operation) =>
-      operation.type !== 'push' ||
-      operation.events.every((event) => event.type !== 'plan.changed'),
-  })
-}
-
-export const GET = handle
-export const POST = handle
-```
-
-Server appends, such as
-`supportDeskAgent.session(id).append({ type: 'plan.changed', payload })`, are
-trusted and skip `authorize`. `push()` also accepts any `inputs` builder, and
-`handlerContext(supportDesk)` types application events inside tools.
-
-`agent({ contract })` takes only an `agentContract()`, so every resolver gets
-your `state`. When the agent belongs inside something larger, such as a chat
-room several people share, keep them as two sessions. The room is an ordinary
-core A2 session. Its handler appends each message the agent should see to the
-agent's session with `inputs.message()`. Event ids are unique across a store's
-sessions, so derive the message id from the room event's id with
-`idempotentId()`; a retried handler then converges on the same message. A tool
-the agent calls to speak appends to the room's session with an `idempotentId()`
-of its `toolCallId`, so the room's log orders the agent's messages among
-everyone else's. Neither fold ever reads the other's state.
-
-The contract-free client, `createAgentClient()` and `useAgent({ api | client })`
-with a type-only import, folds the built-in reducer, so it accepts only agents
-whose reducer carries the built-in name: `agent({ name })`, or
-`agent({ contract })` with an `agentContract()` that has no `reducer`. The types
-enforce it through `AI_STATE_REDUCER`.
-
-`reduceAIState()` remains a pure transition over confirmed `AIState` for
-applications that project raw event histories.
-
-### Replace generation, not durability
-
-The default generator uses AI SDK `streamText()` for one model step. Replace
-only that model-facing step for fixtures, provider routing, or a different AI
-SDK assembly:
-
-```ts server/custom-generation.ts
-import { convertToModelMessages, streamText } from 'ai'
-import { agent } from 'experimental-a2/ai/server'
-
-export const customGeneration = agent({
-  name: 'custom-generation',
-  model: 'openai/gpt-5.6-terra',
-  generate: async ({ event, messages, model, instructions, signal }) => {
-    const result = streamText({
-      model,
-      messages: await convertToModelMessages(messages),
-      abortSignal: signal,
-      ...(instructions === undefined ? {} : { instructions }),
-    })
-
-    return result.toUIMessageStream({
-      originalMessages: messages,
-      generateMessageId: () => event.payload.responseMessageId,
-    })
-  },
-})
-```
-
-`generate` receives what every resolver does, `{ event, messages, state,
-session, signal }`, with `messages` already compacted. It also gets the
-resolved `model`, `instructions`, `tools`, and `generation` settings, the
-model-ready `modelMessages` with any compaction summary, and the step's
-`generationId`. Its stream writes the assistant message
-`event.payload.responseMessageId`. It returns exactly one model step as a
-`ReadableStream<UIMessageChunk>`. A tool-aware replacement sends definitions to
-the model without running local `execute` functions. A2 still owns durable
-progress, tool execution, approval, continuation, interruption, and failure.
-`messageMetadata` applies only to the default generator. A custom `generate`
-function owns its metadata and can pass a callback to `toUIMessageStream()` or
-emit typed metadata chunks itself.
-
-## Checkpoints and recovery reads
-
-`assistant.session(id).state()` returns `AIState` and its log index, ready for
-server code or client hydration. No conversion step is needed. The reducer's
-initial state and fold use that same type.
-
-```ts server/read-agent.ts
-import type { UIMessage } from 'ai'
-import type { TranscriptMessage } from 'experimental-a2/ai'
-import { assistant } from './assistant'
-
-export async function readMessages(
-  sessionId: string,
-): Promise<TranscriptMessage<UIMessage>[]> {
-  const snapshot = await assistant.session(sessionId).state()
-  return snapshot.state.messages
-}
-```
-
-Tool payloads live in message parts. `state.tools` keeps only identities and
-execution status; it does not repeat inputs, outputs, or provider metadata.
-Checkpoint and subscription encoding remain internal. The active step retains
-its events and the information needed to restore overwritten message fields
-for interruption cutoffs and retry. It does not copy the whole prior message.
-Recovery is released when the response completes; completed model
-context is kept by the separate context reducer.
-
-Model steps read the model-context reducer and coordinator at a fixed log
-boundary. Model, instruction, compaction, and custom-generation callbacks
-receive prompt messages, request information, and the contract's application
-`state`, which rides in the model-context checkpoint. Read any other reducer
-with `session.state(yourReducer)`. They do not receive a raw history array. Their `session.state(reducer)` reads
-application reducers at the captured prompt boundary by default; explicit
-`through` options follow the ordinary state-read contract. Compaction selection
-can be asynchronous when it needs a settings-state read.
-
-Ordinary generation uses the model-context checkpoint without reading the
-transcript or replaying history to apply an existing compaction. The context
-checkpoint has its own identity and fold. Recovery and explicit retry discard
-only the unfinished model step. Completed compactions remain committed, so these
-paths never reconstruct pre-compaction prompts or retain rollback copies.
-
-Tools recovering in a fresh process read context at their tool-admission index.
-The saved generation projection restores their original prompt, preserving the
-committed summary and excluding later arrivals. No separate history read is
-needed. A2 core can rebuild a missing or invalid reducer snapshot from the log.
-
-Compaction immediately releases covered message and tool content from model
-context. Execution retains the active turn, queued inputs, unsettled tool work
-IDs, and token calibration. Model metadata is cached per distinct model.
-Historical input uniqueness comes from core event deduplication. The full
-transcript remains available independently.
-
-Streaming progress updates the current message incrementally. Snapshots preserve
-open text and reasoning parts and partial tool inputs. Indexed progress remains
-available for exact interruption cutoffs; reordered events rebuild the projection.
-
-While tool arguments arrive, `input-streaming` parts expose a best-effort partial
-JSON value in `input`. A command string can appear and grow before its closing
-quote arrives. This is a display draft, not validated execution input.
-`tool-input-available` supplies the completed input. Interruption still discards
-streaming drafts even when their partial JSON is readable.
-
-## Delivery semantics
-
-Model steps and tools run inside at-least-once A2 handlers. The returned-event
-transaction makes each successful handler completion and its terminal events
-one atomic durable operation. Deterministic ids make scheduling and lifecycle
-appends effectively once, and A2 marks an incomplete model attempt
-`superseded` before starting its replacement.
-
-An expired claim or superseded attempt preserves its abort reason through model,
-resolver, compaction-policy, and tool calls. A2 retries that attempt without
-spending its failure budget. Explicit user interruption remains terminal.
-Streaming tool progress belongs to an execution attempt, so a retry can produce
-different preliminary output while preserving the tool-call id for idempotency.
-
-Provider calls and external tool side effects remain outside that transaction.
-A process can die after an external effect succeeds and before its handler
-completion commits, so recovery may run the call again. Give side-effecting
-tools their own idempotency strategy, normally keyed by the AI SDK tool call
-id. This is the same at-least-once boundary as every other A2 handler. A fast
-tool may also start before its model step later fails. The failure prevents a
-continuation, but it cannot roll back that external effect.
-
-Configure a [production scheduler](/guides/production) exactly as for any other A2
-server. It recovers an incomplete generation attempt after the original
-serverless invocation disappears.
-
-## Inbox and turn controls
-
-This input protocol requires matching client and server versions. Start a new
-agent session when adopting it. Existing event logs remain readable; finish
-pending work with the runtime that created it before upgrading.
-
-`sendMessage()` places a message in the durable inbox. The controller
-admits one input at a time, freezes its content, and adds it to
-`state.messages`. Pending inputs appear in `state.inbox.items`; they do not enter
-the model prompt. Each item has an `id`, `message`, and `generate` flag.
-
-New-input commands from `inputs.message()`, `inputs.seed()`, and `inputs.steer()`
-use the message ID as their event ID. Those IDs must match on hand-written
-commands too. Caller IDs cannot start with the reserved `a2.ai:` prefix. IDs must
-be unique within the store; include contract/session scope when deriving them
-with `idempotentId()`.
-
-An identical submission replays its original event without creating more work,
-even after removal or compaction. Reusing the ID with different content, a
-different command action, or another session rejects at append with
-`PARTIAL_DUPLICATE_BATCH`. Use `queue.edit()` to change a pending input and a fresh
-message ID to create another input. Edit, move, remove, and other commands have
-their own event IDs. The controller stores no historical input-ID registry.
-
-`state.active` identifies the logical turn, its frozen `input`, and its `phase`.
-The turn ID stays the same across model steps, tools, and a pause. Stop ends that
-turn and admits the next queued input when admission is running.
-
-```tsx app/agent/[sessionId]/queue.tsx
-'use client'
-import { useAgent } from 'experimental-a2/ai/react'
-import type { assistant } from '@/server/assistant'
-
-export function Queue({ sessionId }: { sessionId: string }) {
-  const { state, queue, steer, pause, resume } = useAgent<typeof assistant>({
-    api: '/api/agent',
-    id: sessionId,
-  })
-
-  return (
-    <section>
-      <ol aria-label="Queued messages">
-        {state.inbox.items.map((item) => (
-          <li key={item.id}>
-            {item.message.parts.map((part, index) =>
-              part.type === 'text' ? <span key={index}>{part.text}</span> : null,
-            )}
-            <button onClick={() => void queue.sendNow(item.id)}>Send now</button>
-            <button
-              onClick={() =>
-                void queue.move({ inputId: item.id, beforeId: null })
-              }
-            >
-              Move to end
-            </button>
-            <button onClick={() => void queue.remove(item.id)}>Remove</button>
-          </li>
-        ))}
-      </ol>
-      <button onClick={() => void steer('Check the billing service first.')}>
-        Steer
-      </button>
-      {state.inbox.paused ? (
-        <button onClick={() => void resume()}>Resume</button>
-      ) : (
-        <button onClick={() => void pause({ when: 'after-turn' })}>
-          Pause after this turn
-        </button>
-      )}
-    </section>
-  )
-}
-```
-
-`queue.edit(message)` replaces a pending input's content. `queue.move()` takes
-`beforeId: null` to move an item to the end. Removal only applies to pending
-input. It preserves the immutable log and keeps
-its original submission event, so replay cannot recreate a removed prompt.
-Removing an input that is no longer pending returns `not-pending`, whether it was
-admitted, removed, or never queued.
-
-Edits to pending input use last-write-wins in session log order. Clients can send
-another edit before an earlier one is confirmed. Editing preserves the message's
-identity and role; changing its role returns `role-mismatch`. An edit
-that loses to admission returns `not-pending`. A Stop aimed at a completed turn
-returns `stale-turn`.
-
-`steer()` validates the new input and places it ahead of the inbox in one
-decision. With no active turn, it sends like `sendMessage()`.
-If the observed turn is still active, it finishes its current model response and
-the tools produced by that response before handing off. Parallel tools all
-settle, and steering runs before the old turn starts another model step.
-Text and tool results produced after the click remain in the conversation.
-`lastSeenIndex` is not used to truncate output for steering or Send now.
-
-When running work settles, unanswered approval or application-input requests
-are closed so the steering message can take over. The unapproved tool never
-executes. Provider-executed deferred results still count as running work when
-execution is authorized; a denied approval cannot block handoff.
-If the targeted turn has already finished, the input starts when idle or waits
-first behind a different active turn. Stop remains an immediate interruption.
-
-Steering preserves the admission gate: steering while paused does not resume
-execution. Duplicate input identities and closed sessions still reject the command.
-
-`queue.sendNow()` uses the selected queued message's existing identity and
-latest accepted content. It validates the selected input and the observed turn,
-then moves the input first for the same handoff after the current step. If that
-expectation is stale, the command returns `stale-turn` without changing the queue.
-
-Send now preserves pause just like steering. A paused queue keeps the selected
-input first until Resume. It accepts user-role inputs, including passive user
-input, which it marks for generation. Non-user context returns `not-user-input`;
-reserved internal IDs are rejected before append. Unsaved editor text
-is separate from the accepted queue content; save it before sending.
-
-A queued item's optional `afterStepOf` records the observed turn for steering.
-A matching active turn hands off after its current step.
-Editing preserves this intent; removing the item cancels it. Reordering the
-queue controls which input is admitted at that boundary.
-
-### Optimistic conversation display
-
-The AI reducer is optimistic in every client, including one built from an
-extended `agentContract()`. An idle, unpaused send appears in `state.messages`
-immediately, with `state.starting: true`. Another send waits in
-`state.inbox.items` while that optimistic turn or a confirmed turn is active.
-Paused sessions keep new sends in the inbox. Render the conversation and queue
-from `state`. A pending Stop clears the displayed `state.active` turn
-immediately; rejection restores it. New active turn identities still come from
-accepted control decisions.
-Steering appears immediately in `state.messages`, after the current response,
-and stays there while that step finishes. Send now has the same display when
-an active turn is targeted. These inputs are omitted from the client inbox,
-including while paused, but remain pending on the server until admission.
-Accepted steering survives receipt and hydration in this display. Multiple
-steering inputs appear in admission order, with the most recent first.
-No additional request, subscription, or component-owned queue is needed.
-
-The request echo keeps the optimistic display until `ai.control.decided` arrives. Accepted
-commits replace the confirmed base; rejected receipts remove the pending intent.
-A failed POST rolls back through the ordinary client optimistic overlay.
-Another client's accepted turn can move a speculative ordinary send back into
-the queue. Steering stays visible as a message while waiting behind that turn.
-`state.starting` describes an optimistic turn awaiting acceptance; it does
-not indicate a running model.
-
-Server `session.state()`, reducer folds, checkpoints, and model prompts
-contain confirmed messages and inbox entries, with `starting: false`. The client
-applies pending intent and displays accepted steering only when returning its
-state, after folding events.
-`state.pendingQueueCommands` tracks unresolved queue commands and Stops incrementally, so
-the client does not scan raw history. Pending edits apply in order, so the latest
-local edit stays visible while earlier commands are confirmed. Editing and Send
-now can remain available while an edit awaits its receipt. Close an editor as
-soon as its save is pushed; retain the draft if the push fails.
-
-### Persistence and application are separate
-
-A push confirms that the command is persisted. The `ai.control.decided` event
-confirms its application, using the submitted event's ID as `commandId`. Its
-`outcome` is `applied` or `rejected`; a rejection includes a `reason`, such as
-`not-pending` or `stale-turn`.
-`state.receipt` exposes the most recent user command receipt. Applications that
-have several commands in flight correlate receipts through the existing event
-stream: a hook action resolves to its persisted command events, and each
-event's `id` is the `commandId` of its receipt. An action with nothing to
-address, such as Stop with no active turn, resolves to an empty array. A
-rejection is a normal result and does not spend a handler retry.
-
-### Pause and resume
-
-Pause after the turn closes inbox admission and lets the active turn finish.
-Pause now also cancels current model and tool execution. `state.active.phase`
-becomes `pausing` while old work settles, then `paused`. Resume reopens admission
-and resumes retained work before admitting another input.
-
-Resume starts a fresh model request from durable state. It does not resume the
-provider's old stream or undo completed tool effects. The controller retains
-accepted tool calls and records their outcomes while paused. A cancelled tool
-without a terminal result can execute again after resume; use the stable SDK
-`toolCallId` for external idempotency. No model or tool claim is held merely to
-keep a turn paused.
-
-The controller runs on a short lane. Each decision commits accepted facts,
-compact state changes, work requests, and its receipt atomically. Workers use
-separate claims, report lifecycle batches, and wait for acceptance at model-start
-and compaction boundaries. Token progress appends directly. Explicit AI history
-reads remain bounded to a relevant generation suffix; core checkpoint rebuilding
-can replay older events when a snapshot is missing.
-
-For a deferred provider-executed tool, trusted server code submits
-`inputs.toolResult(result)`. The controller checks its admitted call and records
-the result before continuing. Browser pushes reject this server-only input.