experimental-a2 0.16.1 → 0.18.0

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

@@ -1,1318 +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()` defines an isomorphic event contract, normalized `AIStoredState`,
-and its `AIState` view. The same reducer types server snapshots, hydration,
-and optimistic client updates.
-
-```ts assistant.ts
-import { agent } from 'experimental-a2/ai'
-
-export const assistant = agent({
-  name: 'support-agent',
-})
-```
-
-Keep this module isomorphic. Model providers, secrets, tools, and storage belong
-in the server module.
-
-## Connect the model
-
-`createAgentServer()` adds the AI SDK runner and A2's ordinary store,
-scheduler, telemetry, and handler machinery:
-
-```ts server/assistant.ts
-import { createAgentServer } from 'experimental-a2/ai/server'
-import { assistant } from '../assistant'
-
-export const assistantServer = createAgentServer({
-  agent: assistant,
-  model: 'openai/gpt-5.6-terra',
-  instructions: 'Help the customer. Be concise.',
-  generation: {
-    temperature: 0.2,
-    maxOutputTokens: 2_000,
-  },
-})
-```
-
-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.
-
-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.
-
-### Store assistant metadata
-
-Extend the agent's `UIMessage` type to keep generation status and usage on the
-assistant message:
-
-```ts metadata-assistant.ts
-import type { LanguageModelUsage, UIMessage } from 'ai'
-import { agent } from 'experimental-a2/ai'
-
-export type MetadataAssistantMessage = UIMessage<{
-  status: 'writing' | 'complete'
-  usage?: LanguageModelUsage
-}>
-
-export const metadataAssistant = agent<MetadataAssistantMessage>({
-  name: 'metadata-assistant',
-})
-```
-
-Map the AI SDK's standard stream parts to that metadata type:
-
-```ts server/metadata-assistant.ts
-import { createAgentServer } from 'experimental-a2/ai/server'
-import { metadataAssistant } from '../metadata-assistant'
-
-export const metadataAssistantServer = createAgentServer({
-  agent: metadataAssistant,
-  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 generation context and its
-current `TextStreamPart`. 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.
-
-`experimental-a2/ai/server` is server-only. The isomorphic
-`experimental-a2/ai` entry point contains the contract, reducer, schemas,
-`handlerContext()`, and pure inputs; it never imports a model provider or
-backend.
-
-## Expose the event stream
-
-One HTTP route gives the browser a read and write path. `GET` streams events;
-`POST` accepts optimistic pushes:
-
-```ts app/api/agent-events/route.ts
-import { assistantServer } from '@/server/assistant'
-
-export const GET = assistantServer.fetch
-export const POST = assistantServer.fetch
-```
-
-The route never calls the model directly. The browser appends
-`ai.control.requested` commands. The controller admits inputs and schedules
-`ai.generation.requested`; workers run the AI SDK and append progress to the
-same log.
-
-## Bind the reducer to React
-
-Create the typed provider and hook in a client module:
-
-```tsx app/agent/session.ts
-'use client'
-import { createClient } from 'experimental-a2/client'
-import { createReact } from 'experimental-a2/react'
-import { assistant } from '@/assistant'
-
-export const assistantClient = createClient({
-  reducer: assistant.reducer,
-  api: '/api/agent-events',
-})
-
-export const { SessionProvider, useSession } = createReact({
-  client: assistantClient,
-})
-```
-
-Fold the initial state on the server, then let the provider resume the event
-stream from that exact index:
-
-```tsx app/agent/[sessionId]/page.tsx
-import { assistant } from '@/assistant'
-import { assistantServer } from '@/server/assistant'
-import { AgentClient } from './agent-client'
-import { SessionProvider } from '../session'
-
-export default async function AgentPage({
-  params,
-}: {
-  params: Promise<{ sessionId: string }>
-}) {
-  const { sessionId } = await params
-  const session = assistantServer.session(sessionId)
-  const { state, index } = await session.state(assistant.reducer)
-
-  return (
-    <SessionProvider
-      sessionId={sessionId}
-      initialState={state}
-      initialIndex={index}
-    >
-      <AgentClient />
-    </SessionProvider>
-  )
-}
-```
-
-An empty session folds to the initial `AIState`. Its log is created lazily when
-the first message is pushed.
-
-Start the session from the previous route, but wait for its durable append
-before navigating. The destination server render then sees the message in its
-folded state instead of racing the `POST`:
-
-```tsx app/agent/new-agent-session.tsx
-'use client'
-import type { UIMessage } from 'ai'
-import { inputs } from 'experimental-a2/ai'
-import { assistantClient } from './session'
-
-export async function openAgent(
-  sessionId: string,
-  message: UIMessage,
-  router: { push(href: string): void },
-): Promise<void> {
-  await assistantClient.session(sessionId).push(...inputs.message(message))
-  router.push(`/agent/${sessionId}`)
-}
-```
-
-The draft clears immediately while the append is in flight and can be restored
-if it fails. Once navigation begins, SSR already has folded state at a durable
-frontier. When the destination provider mounts, it resolves the same live
-session and reconciles that server render without replacing the object. Idle
-session objects expire after five minutes by default; configure `gcTime` on
-`createClient` when a different lifetime fits the app.
-
-## Send messages from the client
-
-Build the message inline and pass the resulting events straight to `push()`:
-
-```tsx app/agent/[sessionId]/agent-client.tsx
-'use client'
-import type { FormEvent } from 'react'
-import { useState } from 'react'
-import { inputs } from 'experimental-a2/ai'
-import { useSession } from '../session'
-
-export function AgentClient() {
-  const { state, push } = useSession()
-  const [draft, setDraft] = useState('')
-  const [error, setError] = useState<string | null>(null)
-
-  const canSend = state.status !== 'closed'
-  const lastMessage = state.messages.at(-1)
-  const lastText =
-    lastMessage?.parts
-      .flatMap((part) => (part.type === 'text' ? [part.text] : []))
-      .join('\n') ?? ''
-  const showThinking =
-    state.status === 'generating' &&
-    (lastMessage?.role !== 'assistant' || lastText.length === 0)
-
-  async function send(event: FormEvent<HTMLFormElement>): Promise<void> {
-    event.preventDefault()
-    const previousDraft = draft
-    const text = previousDraft.trim()
-    if (!text || !canSend) return
-
-    setDraft('')
-    setError(null)
-
-    try {
-      await push(
-        ...inputs.message({
-          id: crypto.randomUUID(),
-          role: 'user',
-          parts: [{ type: 'text', text }],
-        }),
-      )
-    } catch (cause) {
-      setDraft(previousDraft)
-      setError(cause instanceof Error ? cause.message : String(cause))
-    }
-  }
-
-  return (
-    <main>
-      <section aria-label="Conversation">
-        {state.messages.map((message) => {
-          const text = message.parts
-            .flatMap((part) => (part.type === 'text' ? [part.text] : []))
-            .join('\n')
-          if (!text) return null
-
-          return (
-            <article key={message.id}>
-              <strong>{message.role === 'user' ? 'You' : 'Agent'}</strong>
-              <p>{text}</p>
-            </article>
-          )
-        })}
-
-        {showThinking ? (
-          <article aria-live="polite">
-            <strong>Agent</strong>
-            <p>Thinking…</p>
-          </article>
-        ) : null}
-      </section>
-
-      <form onSubmit={send}>
-        <input
-          aria-label="Message"
-          value={draft}
-          onChange={(event) => setDraft(event.currentTarget.value)}
-        />
-        <button disabled={!draft.trim() || !canSend}>Send</button>
-      </form>
-
-      {error ? <p role="alert">{error}</p> : null}
-    </main>
-  )
-}
-```
-
-`push()` persists the command. Its receipt confirms admission to the inbox.
-`state.inbox.items` contains pending inputs; `state.messages` contains the
-admitted conversation. If persistence fails, the component restores the draft.
-
-The form gives Enter its normal submit behavior. The thinking row is also
-derived from `AIState`: it appears with the Agent label when the server's
-generation request folds, then the first visible assistant content replaces
-it. Empty stream-start messages never create a blank conversation row.
-
-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:
-
-```ts app/agent/passive-message.ts
-import type { UIMessage } from 'ai'
-import { inputs } from 'experimental-a2/ai'
-import { assistantClient } from './session'
-
-export async function recordPassiveMessage(
-  sessionId: string,
-  message: UIMessage,
-): Promise<void> {
-  await assistantClient
-    .session(sessionId)
-    .push(...inputs.message(message, { 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.
-
-## What happens after `push()`
-
-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 every AI SDK chunk once. 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`, `activeGeneration`, `activeRequestId`,
-`activeResponseMessageId`, `activeProjection`, `responseOwners`,
-`terminalRequestIds`, `terminalGenerations`, `pendingApprovals`,
-`pendingInputs`, `tools`, `compaction`, per-generation `usage`, and the last
-generation `error`.
-`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.
-
-Approval and application-input events carry both `requestId` and `generationId`.
-Copy both from the pending approval, pending input, or active generation when
-sending a response. `activeRequestReason` and `activeRequestSourceGenerationId`
-describe the current request independently from the message projection.
-
-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.
-
-## The built-in inputs
-
-`inputs` contains pure, isomorphic builders for protocol interactions:
-
-| Input | Events |
-| --- | --- |
-| `inputs.message(message, { generate? })` | queues input; `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 })` | 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 `push()` accepts 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.
-
-## 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 { createAgentServer } from 'experimental-a2/ai/server'
-import { assistant } from '../assistant'
-
-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 assistantServerWithTools = createAgentServer({
-  agent: assistant,
-  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(agent)` from `experimental-a2/ai`: it returns the same
-typed context bag 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. The agent argument carries the types; A2 verifies it against the
-server executing the tool and throws when a tool written for one agent
-runs under another, or when `handlerContext()` is called outside a tool
-execution. The scope survives awaited helpers and async iteration, so
-any code below `execute` can read it.
-
-`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 agent argument supplies types, not infrastructure. The context's
-`session` belongs to the server executing the tool, so its `schedule()`
-method uses that server'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'
-import { assistant } from '../assistant'
-
-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(assistant)
-    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 server'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` for any agent.
-
-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`. Respond from the same optimistic client path:
-
-```tsx app/agent/[sessionId]/approval-controls.tsx
-'use client'
-import { inputs } from 'experimental-a2/ai'
-import { useSession } from '../session'
-
-export function ApprovalControls() {
-  const { state, push } = useSession()
-
-  return state.pendingApprovals.map((approval) => (
-    <div key={approval.approvalId}>
-      <span>Allow tool call {approval.toolCallId}?</span>
-      <button
-        onClick={() =>
-          void push(
-            ...inputs.approval({
-              requestId: approval.requestId,
-              messageId: approval.messageId,
-              generationId: approval.generationId,
-              approvalId: approval.approvalId,
-              approved: true,
-            }),
-          )
-        }
-      >
-        Allow
-      </button>
-      <button
-        onClick={() =>
-          void push(
-            ...inputs.approval({
-              requestId: approval.requestId,
-              messageId: approval.messageId,
-              generationId: approval.generationId,
-              approvalId: approval.approvalId,
-              approved: false,
-              reason: 'Denied by the user',
-            }),
-          )
-        }
-      >
-        Deny
-      </button>
-    </div>
-  ))
-}
-```
-
-`inputs.approval()` records only the decision and 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. 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 `push()` rejects lifecycle
-events, including provider results.
-
-`inputs.input()` provides the same durable request/response shape for
-application-defined input. Its value stays in raw history and
-`state.pendingInputs`; resolve instructions dynamically or replace `generate`
-when the value should become model context.
-
-Approval and application-input request/response facts carry the active
-`generationId`. Echo that value from the pending request so a delayed UI action
-cannot authorize or resume a later model step.
-
-## Interrupt and retry
-
-Interrupt the active response from the client:
-
-```tsx app/agent/[sessionId]/stop-button.tsx
-'use client'
-import { inputs } from 'experimental-a2/ai'
-import { useSession } from '../session'
-
-export function StopButton() {
-  const { state, push, index } = useSession()
-  const active = state.active
-  if (!active) return null
-
-  return (
-    <button
-      onClick={() =>
-        void push(
-          ...inputs.stop({
-            turnId: active.turnId,
-            lastSeenIndex: index,
-          }),
-        )
-      }
-    >
-      Stop
-    </button>
-  )
-}
-```
-
-The client immediately previews Stop for the observed turn. `lastSeenIndex` is the exact confirmed log frontier visible when the
-user clicked. 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.
-
-For the lower-level `inputs.interrupt()` builder, 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.
-
-After a failed model call, `inputs.retry({ messageId, responseMessageId,
-retryId })` records a retry request. 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.
-`retryId` identifies the user's action, so 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.
-
-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 should use `push()` for instant state. Server-originated
-turns use the same inputs with `append()`:
-
-```ts server/append-message.ts
-import { inputs } from 'experimental-a2/ai'
-import { assistantServer } from './assistant'
-
-export async function appendServerMessage(sessionId: string, text: string) {
-  await assistantServer.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.
-
-## 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 { createAgentServer } from 'experimental-a2/ai/server'
-import { assistant } from '../assistant'
-
-export const compactedAssistantServer = createAgentServer({
-  agent: assistant,
-  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 agent servers, 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 through an explicit transcript reducer read.
-
-`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.
-The raw log and transcript from `agent.reducer` remain available in full.
-Server execution uses a separate model-context reducer and checkpoint. Successful
-compaction permanently replaces covered context. Callbacks receive their prompt
-messages and request information, not reducer state or execution internals.
-Application reducers remain explicit reads through `session.state(reducer)`.
-To read the full transcript, load `session.state(agent.reducer)` and pass its
-`state` to `agent.reducer.view()`. Client hooks continue to expose `AIState`.
-
-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 UI messages, so a summary does not
-need your message metadata or schema.
-
-Render compaction as activity alongside the conversation:
-
-```tsx app/agent/compaction-status.tsx
-'use client'
-import { useSession } from './session'
-
-export function CompactionStatus() {
-  const { state } = useSession()
-  return state.compaction?.status === 'running' ? (
-    <p role="status">Compacting…</p>
-  ) : null
-}
-```
-
-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`.
-
-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.
-
-## Extend the assembly
-
-The convenience API is ordinary A2 parts:
-
-- `events` and `createEvents()` export the built-in schemas.
-- `createReducer({ contract })` builds the normalized state and `AIState` view for a
-  compatible contract.
-- `agent()` combines the built-in protocol, application events, and reducer.
-- `tool()` binds an AI SDK function-tool definition to an agent's typed A2
-  handler context.
-- `createHandlers({ agent, ... })` returns the AI handler table.
-- `createAgentServer()` combines those handlers with `createServer()`.
-
-Use the lower-level pieces when an application needs more handlers or a
-different server assembly:
-
-```ts server/custom.ts
-import { z } from 'zod'
-import { agent } from 'experimental-a2/ai'
-import { createHandlers } from 'experimental-a2/ai/server'
-import { createServer } from 'experimental-a2/server'
-
-const supportAgent = agent({
-  name: 'extended-support-agent',
-  events: {
-    'ticket.linked': z.object({ ticketId: z.string() }),
-  },
-})
-
-const aiHandlers = createHandlers({
-  agent: supportAgent,
-  model: 'openai/gpt-5.6-terra',
-})
-
-export const customAssistantServer = createServer({
-  contract: supportAgent.contract,
-  handlers: {
-    ...aiHandlers,
-    'ticket.linked': async ({ event }) => {
-      // your side effect; event.id makes a stable idempotency key:
-      // await indexTicket(event.payload.ticketId, { idempotencyKey: event.id })
-    },
-  },
-})
-```
-
-Application events stay fully typed. The standard AI reducer ignores unknown
-events, so another reducer can project application state without forking the AI
-protocol. A custom `createServer()` assembly owns its browser ingress policy.
-Use `server.fetch(request, { authorize })` to authorize operations, and reject
-server-only AI event names there before they reach the custom server.
-`createAgentServer()` applies its stricter built-in ingress allowlist
-automatically.
-
-### 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 { createAgentServer } from 'experimental-a2/ai/server'
-import { assistant } from '../assistant'
-
-export const customGenerationServer = createAgentServer({
-  agent: assistant,
-  model: 'openai/gpt-5.6-terra',
-  generate: async ({
-    messages,
-    model,
-    instructions,
-    responseMessageId,
-    signal,
-  }) => {
-    const result = streamText({
-      model,
-      messages: await convertToModelMessages(messages),
-      abortSignal: signal,
-      ...(instructions === undefined ? {} : { instructions }),
-    })
-
-    return result.toUIMessageStream({
-      originalMessages: messages,
-      generateMessageId: () => responseMessageId,
-    })
-  },
-})
-```
-
-`generate` receives compacted messages, resolved model and instructions, tools,
-generation settings, durable request identity, current state, and
-the abort signal. 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
-
-The AI reducer stores normalized `AIStoredState`. `session.state(agent.reducer)`
-returns that state and its log index, ready to pass to `SessionProvider` or client
-hydration. Client and React snapshots derive the familiar `AIState` view
-immediately, including streamed message parts and tool activity.
-
-For server-side inspection, use the reducer's view:
-
-```ts server/read-agent.ts
-import type { UIMessage } from 'ai'
-import { assistantServer } from './assistant'
-import { assistant } from '../assistant'
-
-export async function readMessages(sessionId: string): Promise<UIMessage[]> {
-  const snapshot = await assistantServer.session(sessionId).state(assistant.reducer)
-  return assistant.reducer.view(snapshot.state).messages
-}
-```
-
-Each snapshot stores repeated payloads once and keeps only the changes needed
-to restore the current generation's prompt and projection. The live view is cached while
-events fold; normalization does not run for every token. Reading or serializing
-the stored fields materializes the records. The log and displayed conversation
-retain their full content.
-
-Model steps read the model-context reducer and coordinator at a fixed log
-boundary. Model, instruction, compaction, and custom-generation callbacks
-receive prompt messages and request information without reducer state. Custom transcript folds and
-schemas apply only to the transcript; read application state explicitly with
-`session.state(yourReducer)` when a callback needs it.
-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.
-
-`inputs.message(message)` 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.
-
-```ts client/turn-controls.ts
-import { inputs, type AIState } from 'experimental-a2/ai'
-import type { UIMessage } from 'ai'
-
-export function editPending(message: UIMessage) {
-  return inputs.queue.edit({ message })
-}
-
-export function movePending(inputId: string, beforeId: string | null) {
-  return inputs.queue.move({ inputId, beforeId })
-}
-
-export function removePending(inputId: string) {
-  return inputs.queue.remove({ inputId })
-}
-
-export function sendPendingNow(state: AIState, inputId: string) {
-  return inputs.queue.sendNow({ inputId, turnId: state.active?.turnId ?? null })
-}
-
-export function stopCurrent(state: AIState) {
-  return state.active ? inputs.stop({ turnId: state.active.turnId }) : []
-}
-
-export function steerCurrent(state: AIState, message: UIMessage) {
-  return state.active
-    ? inputs.steer({ turnId: state.active.turnId, message })
-    : inputs.message(message)
-}
-
-export const pauseAfterTurn = () => inputs.pause({ when: 'after-turn' })
-export const pauseNow = () => inputs.pause({ when: 'now' })
-export const resume = () => inputs.resume()
-```
-
-Pass these arrays to `push(...events)` from `useSession()`, or to a server
-session's `append(...events)`. `beforeId: null` moves 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.
-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.
-
-Send now uses the selected queued message's existing identity and latest
-accepted content. It validates the selected input and the observed `turnId`,
-then moves the input first for the same handoff after the current step. Use
-`turnId: null` when no turn is active. 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
-
-With `agent().reducer` or `createReducer()`, the client state is already optimistic.
-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.
-
-```tsx app/agent/[sessionId]/conversation.tsx
-'use client'
-import { useSession } from '../session'
-
-export function Conversation() {
-  const { state } = useSession()
-  const { messages, inbox, starting } = state
-  const text = (message: (typeof messages)[number]) =>
-    message.parts.filter((part) => part.type === 'text').map((part) => part.text).join(' ')
-  return (
-    <section>
-      <div aria-label="Conversation">
-        {messages.map((message) => <p key={message.id}>{text(message)}</p>)}
-        {starting ? <p role="status">Starting…</p> : null}
-      </div>
-      <ol aria-label="Queued messages">
-        {inbox.items.map((item) => <li key={item.id}>{text(item.message)}</li>)}
-      </ol>
-    </section>
-  )
-}
-```
-
-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)`, 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.
-A custom reducer can keep normalized AI state by nesting `agent.reducer.fold()`
-and derive its view with `agent.reducer.view()`. It does not inherit the built-in
-optimistic client display. `reduceAIState()` remains a pure transition over the
-confirmed `AIState` view for applications that project raw event histories.
-`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
-
-`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`.
-`state.receipt` exposes the most recent user command receipt. Applications that
-have several commands in flight correlate receipts through the existing event
-stream. 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 ingress rejects this server-only input.