experimental-a2 0.16.0 → 0.17.0

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

@@ -20,32 +20,15 @@ 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.
+`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 assistant.ts
-import { agent } from 'experimental-a2/ai'
+```ts server/assistant.ts
+import { agent } from 'experimental-a2/ai/server'
 
 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: {
@@ -55,6 +38,11 @@ export const assistantServer = createAgentServer({
 })
 ```
 
+`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
@@ -72,6 +60,12 @@ 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
@@ -91,102 +85,35 @@ 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
+## 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-events/route.ts
-import { assistantServer } from '@/server/assistant'
+```ts app/api/agent/route.ts
+import { assistant } from '@/server/assistant'
 
-export const GET = assistantServer.fetch
-export const POST = assistantServer.fetch
+export const GET = assistant.fetch
+export const POST = assistant.fetch
 ```
 
-The route never calls the model directly. The browser appends
-`ai.control.requested` commands. The controller admits inputs and schedules
+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.
 
-## Bind the reducer to React
+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.
 
-Create the typed provider and hook in a client module:
+## Render the conversation
 
-```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:
+Fold the initial state on the server and hand it to a client component:
 
 ```tsx app/agent/[sessionId]/page.tsx
-import { assistant } from '@/assistant'
-import { assistantServer } from '@/server/assistant'
-import { AgentClient } from './agent-client'
-import { SessionProvider } from '../session'
+import { assistant } from '@/server/assistant'
+import { Chat } from './chat'
 
 export default async function AgentPage({
   params,
@@ -194,96 +121,53 @@ export default async function AgentPage({
   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>
-  )
+  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.
 
-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()`:
+`useAgent()` keeps that state live and returns the actions a chat needs:
 
-```tsx app/agent/[sessionId]/agent-client.tsx
+```tsx app/agent/[sessionId]/chat.tsx
 'use client'
 import type { FormEvent } from 'react'
 import { useState } from 'react'
-import { inputs } from 'experimental-a2/ai'
-import { useSession } from '../session'
+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 AgentClient() {
-  const { state, push } = useSession()
+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)
 
-  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
-
+    const text = draft.trim()
+    if (!text) return
     setDraft('')
     setError(null)
-
     try {
-      await push(
-        ...inputs.message({
-          id: crypto.randomUUID(),
-          role: 'user',
-          parts: [{ type: 'text', text }],
-        }),
-      )
+      await sendMessage(text)
     } catch (cause) {
-      setDraft(previousDraft)
+      setDraft(text)
       setError(cause instanceof Error ? cause.message : String(cause))
     }
   }
@@ -291,25 +175,16 @@ export function AgentClient() {
   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>
+        {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>
 
@@ -319,7 +194,7 @@ export function AgentClient() {
           value={draft}
           onChange={(event) => setDraft(event.currentTarget.value)}
         />
-        <button disabled={!draft.trim() || !canSend}>Send</button>
+        <button disabled={!draft.trim() || status === 'closed'}>Send</button>
       </form>
 
       {error ? <p role="alert">{error}</p> : null}
@@ -328,14 +203,29 @@ export function AgentClient() {
 }
 ```
 
-`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.
+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
@@ -343,22 +233,8 @@ 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 }))
-}
-```
+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
@@ -367,7 +243,92 @@ 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()`
+## 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:
 
@@ -394,15 +355,20 @@ 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
+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`, `activeGeneration`, `activeRequestId`,
-`activeResponseMessageId`, `activeProjection`, `responseOwners`,
-`terminalRequestIds`, `terminalGenerations`, `pendingApprovals`,
-`pendingInputs`, `tools`, `compaction`, per-generation `usage`, and the last
-generation `error`.
+`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
@@ -412,10 +378,9 @@ 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.
+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
@@ -429,61 +394,12 @@ IDs as opaque. An assistant response uses its first model-request event's ID. Ge
 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
@@ -493,8 +409,7 @@ 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'
+import { agent } from 'experimental-a2/ai/server'
 
 const tools = {
   closeTicket: tool({
@@ -508,8 +423,8 @@ const tools = {
   }),
 }
 
-export const assistantServerWithTools = createAgentServer({
-  agent: assistant,
+export const toolsAssistant = agent({
+  name: 'support-tools',
   model: 'openai/gpt-5.6-terra',
   tools,
   generation: {
@@ -523,15 +438,15 @@ export const assistantServerWithTools = createAgentServer({
 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.
+`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.
@@ -545,16 +460,14 @@ 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:
+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'
-import { assistant } from '../assistant'
 
 export const setReminder = tool({
   description: 'Set a reminder for yourself',
@@ -563,7 +476,7 @@ export const setReminder = tool({
     reminder: z.string(),
   }),
   execute: async ({ delaySeconds, reminder }, { toolCallId }) => {
-    const ctx = handlerContext(assistant)
+    const ctx = handlerContext()
     await ctx.session.schedule(
       `reminder:${toolCallId}`,
       { delay: `${delaySeconds}s` },
@@ -579,7 +492,7 @@ export const setReminder = tool({
 })
 ```
 
-Add `setReminder` to the server's `tools` and configure a
+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.
@@ -601,51 +514,29 @@ 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.
+`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`. Respond from the same optimistic client path:
+`state.pendingApprovals`. Answer it from the hook:
 
-```tsx app/agent/[sessionId]/approval-controls.tsx
+```tsx app/tools/[sessionId]/approval-controls.tsx
 'use client'
-import { inputs } from 'experimental-a2/ai'
-import { useSession } from '../session'
+import { useAgent } from 'experimental-a2/ai/react'
+import type { toolsAssistant } from '@/server/with-tools'
 
-export function ApprovalControls() {
-  const { state, push } = useSession()
+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 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',
-            }),
-          )
-        }
+        onClick={() => void deny(approval, { reason: 'Denied by the user' })}
       >
         Deny
       </button>
@@ -654,10 +545,11 @@ export function ApprovalControls() {
 }
 ```
 
-`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.
+`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
@@ -667,7 +559,10 @@ 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
+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
@@ -685,51 +580,45 @@ 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
+through the trusted server session API. Browser pushes reject 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.
+`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
 
-Interrupt the active response from the client:
+Stop the active turn, or retry a failed response, from the hook:
 
-```tsx app/agent/[sessionId]/stop-button.tsx
+```tsx app/agent/[sessionId]/turn-controls.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>
-  )
+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
 }
 ```
 
-The accepted command ends the turn and reaches A2's cancellation channel. `lastSeenIndex` is the exact confirmed log frontier visible when the
-user clicked. The reducer rewinds the indexed generation projection to that
+`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.
@@ -740,7 +629,25 @@ 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.
 
-For the lower-level `inputs.interrupt()` builder, between
+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
@@ -751,31 +658,20 @@ 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
+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 { assistantServer } from './assistant'
+import { assistant } from './assistant'
 
 export async function appendServerMessage(sessionId: string, text: string) {
-  await assistantServer.session(sessionId).append(
+  await assistant.session(sessionId).append(
     ...inputs.message({
       id: crypto.randomUUID(),
       role: 'user',
@@ -789,6 +685,51 @@ 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
@@ -797,11 +738,10 @@ 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'
+import { agent } from 'experimental-a2/ai/server'
 
-export const compactedAssistantServer = createAgentServer({
-  agent: assistant,
+export const compactedAssistant = agent({
+  name: 'compacted-agent',
   model: 'openai/gpt-5.6-terra',
 })
 ```
@@ -812,7 +752,7 @@ 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
+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
@@ -823,17 +763,18 @@ 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.
+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.
+`{ 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
@@ -870,36 +811,84 @@ 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`.
+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.
 
-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.
+### Show compaction in the conversation
 
-Render compaction as activity alongside 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/compaction-status.tsx
+```tsx app/agent/message-view.tsx
 'use client'
-import { useSession } from './session'
+import type { UIMessage } from 'ai'
+import { isCompactionPart, type TranscriptMessage } from 'experimental-a2/ai'
 
-export function CompactionStatus() {
-  const { state } = useSession()
-  return state.compaction?.status === 'running' ? (
-    <p role="status">Compacting…</p>
-  ) : null
+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
@@ -907,65 +896,190 @@ 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.
+## Store assistant metadata
 
-## Extend the assembly
+Give the agent a narrower `UIMessage` type to keep generation status and usage
+on the assistant message. `agentContract()` carries the type:
 
-The convenience API is ordinary A2 parts:
+```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.
 
-- `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()`.
+## Add your own events and state
 
-Use the lower-level pieces when an application needs more handlers or a
-different server assembly:
+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 server/custom.ts
+```ts support-desk.ts
 import { z } from 'zod'
-import { agent } from 'experimental-a2/ai'
-import { createHandlers } from 'experimental-a2/ai/server'
-import { createServer } from 'experimental-a2/server'
+import { agentContract } from 'experimental-a2/ai'
 
-const supportAgent = agent({
-  name: 'extended-support-agent',
+const noFlags: string[] = []
+
+export const supportDesk = agentContract({
+  name: 'support-desk',
   events: {
-    'ticket.linked': z.object({ ticketId: z.string() }),
+    '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,
   },
 })
+```
 
-const aiHandlers = createHandlers({
-  agent: supportAgent,
-  model: 'openai/gpt-5.6-terra',
-})
+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:
 
-export const customAssistantServer = createServer({
-  contract: supportAgent.contract,
+```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: {
-    ...aiHandlers,
-    'ticket.linked': async ({ event }) => {
+    'ticket.flagged': async ({ event }) => {
       // your side effect; event.id makes a stable idempotency key:
-      // await indexTicket(event.payload.ticketId, { idempotencyKey: event.id })
+      // await notifyOnCall(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.
+`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
 
@@ -975,19 +1089,12 @@ SDK assembly:
 
 ```ts server/custom-generation.ts
 import { convertToModelMessages, streamText } from 'ai'
-import { createAgentServer } from 'experimental-a2/ai/server'
-import { assistant } from '../assistant'
+import { agent } from 'experimental-a2/ai/server'
 
-export const customGenerationServer = createAgentServer({
-  agent: assistant,
+export const customGeneration = agent({
+  name: 'custom-generation',
   model: 'openai/gpt-5.6-terra',
-  generate: async ({
-    messages,
-    model,
-    instructions,
-    responseMessageId,
-    signal,
-  }) => {
+  generate: async ({ event, messages, model, instructions, signal }) => {
     const result = streamText({
       model,
       messages: await convertToModelMessages(messages),
@@ -997,15 +1104,18 @@ export const customGenerationServer = createAgentServer({
 
     return result.toUIMessageStream({
       originalMessages: messages,
-      generateMessageId: () => responseMessageId,
+      generateMessageId: () => event.payload.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
+`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.
@@ -1015,36 +1125,36 @@ 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:
+`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 { assistantServer } from './assistant'
-import { assistant } from '../assistant'
+import type { TranscriptMessage } from 'experimental-a2/ai'
+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
+export async function readMessages(
+  sessionId: string,
+): Promise<TranscriptMessage<UIMessage>[]> {
+  const snapshot = await assistant.session(sessionId).state()
+  return 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.
+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 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
+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.
@@ -1108,10 +1218,10 @@ 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.
+`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
@@ -1126,60 +1236,71 @@ different command action, or another session rejects at append with
 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 })
-}
+```tsx app/agent/[sessionId]/queue.tsx
+'use client'
+import { useAgent } from 'experimental-a2/ai/react'
+import type { assistant } from '@/server/assistant'
 
-export function stopCurrent(state: AIState) {
-  return state.active ? inputs.stop({ turnId: state.active.turnId }) : []
-}
+export function Queue({ sessionId }: { sessionId: string }) {
+  const { state, queue, steer, pause, resume } = useAgent<typeof assistant>({
+    api: '/api/agent',
+    id: sessionId,
+  })
 
-export function steerCurrent(state: AIState, message: UIMessage) {
-  return state.active
-    ? inputs.steer({ turnId: state.active.turnId, message })
-    : inputs.message(message)
+  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>
+  )
 }
-
-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
+`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`.
+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.
+`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.
@@ -1196,11 +1317,10 @@ 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.
+`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
@@ -1215,12 +1335,14 @@ 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`; `state.active` and
-execution controls remain server-confirmed.
+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,
@@ -1229,45 +1351,19 @@ 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
+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
+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.
-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 incrementally, so
+`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
@@ -1275,12 +1371,16 @@ 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
+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`.
+`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 rejection is a normal result and does not spend a handler retry.
+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
 
@@ -1305,4 +1405,4 @@ 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.
+the result before continuing. Browser pushes reject this server-only input.