experimental-a2 0.16.1 → 0.17.0

package/docs/reference/01-api.mdx

@@ -12,12 +12,16 @@ a2.contract(options: {
   name: string
   events: Record<string, StandardSchemaV1>
   presence?: Record<string, StandardSchemaV1>
+  reducer?: { name: string; initialState: S; stateSchema?: StandardSchemaV1; fold: (state: S, event: Event) => S }
 }): Contract
 ```
 
 Defines one kind of lifecycle: a name plus the events it understands. The name
 must be unique per app; it identifies the contract in storage and queue
-messages. The result is a plain, importable, **isomorphic** value: the server
+messages. The name may not contain the control character U+001F, and event
+types may not start with `a2.`, which A2 reserves for its own events, such as
+`a2.cleared`. The result is a plain,
+importable, **isomorphic** value: the server
 implements it, reducers derive from it, the browser types its pushes off it.
 See [Contracts and sessions](/concepts/contracts).
 
@@ -37,17 +41,20 @@ Preserves the literal types in a heterogeneous handler-returned event array.
 It returns the same events as a readonly tuple; A2 validates them when the
 handler completes.
 
-### `contract.reducer(options)`
+### `reducer(options)`
 
 ```ts
-contract.reducer(options: {
+reducer(options: {
+  contract: Contract
   name: string                // identity; keys cached snapshots
   initialState: S             // the seed (schema input, when stateSchema is set)
   stateSchema?: StandardSchemaV1 // declares S, checks initialState, guards cached folds
 }): { fold(fn: (state: S, event: Event) => S): Reducer<S> }
 ```
 
-Derives a view from the contract. Two steps by design: the first call
+Builds a separate reducer for server reads or for the contract's optional
+`reducer` field. The contract publishes only that selected reducer to clients.
+Inline definitions include `fold` directly. The standalone builder uses two steps: the first call
 fixes the state and event types, so `.fold()` receives fully concrete
 ones. Literal unions in your state survive, with zero annotations.
 
@@ -88,6 +95,15 @@ ID generation unchanged. Changing an existing application's ID recipe changes
 retry identity, so retries of previously committed requests need to retain
 their original IDs.
 
+### `SessionCleared`
+
+The marker a [clear](#sessionclearoptions) leaves in `session.stream()`: an
+`Event` whose `type` is `'a2.cleared'` and whose `payload` is `null`. It
+never reaches handlers or `history()`. Comparing `event.type` with that string
+narrows a stream item to `SessionCleared`. The session client handles the
+marker on its own, so this matters only when you read the server stream
+yourself.
+
 ## `experimental-a2/server`
 
 ### `handler(entry)`
@@ -332,6 +348,9 @@ export const POST = ordersServer.fetch
 A plain GET streams one session over SSE, resumed after the `index` query
 parameter. A GET with `gte` and `lte` returns the closed history range as JSON
 and sets `a2-history-covered` to `true` when every requested index was returned.
+When the range includes the latest clear marker, it also sets `a2-clear-index`,
+and coverage counts only the requested indexes after that marker. A range
+entirely below the marker returns `[]`.
 POST accepts `{ sessionId, events, presence? }` and returns the appended events.
 Presence is inferred from the contract. A contract that declares presence
 streams it and accepts presence pushes automatically.
@@ -491,6 +510,7 @@ type StoredEvent = Event & {
   lastFailedAttempt: number | null
   lastError: string | null
   failedAt: Date | null
+  clearIndex?: number // on claimed events, once the session has been cleared
 }
 
 type StoreAppendResult = {
@@ -511,8 +531,17 @@ interface A2Store {
   append(
     sessionId: string,
     events: AppendEvent[],
+    options?: { originIndex?: number },
   ): Promise<StoreAppendResult>
 
+  // optional together; required for session.clear()
+  clear?(options: {
+    sessionId: string
+    ifLastIndex?: number
+    cause?: EventCause
+  }): Promise<{ cleared: boolean; index: number; clearIndex: number }>
+  reclaim?(sessionId: string): Promise<{ deleted: number; done: boolean }>
+
   claimAvailable(options: {
     sessionId: string
     holder: string
@@ -556,6 +585,22 @@ interface A2Store {
 | `renewClaims` | Extend the listed live claims still owned by the holder. `renewed` lists the claims that remain owned; `superseded` lists the claims whose event's `attemptCount` passed the listed attempt. An expired claim no successor took appears in neither: it may still complete. Renewal never revives an expired claim. |
 | `completeAttempt` | Fence on the current attempt, mark the parent processed, store its exact ordered `returnedEventIds`, and append the returned batch in the same transaction. A same-attempt retry returns the committed children; a stale attempt returns `superseded`. |
 | `failAttempt` | Record one current caught failure, clear its claim, and dead-letter at `maxFailures`. A repeated failure acknowledgment is idempotent; stale attempts return `superseded`. |
+| `clear` | Serialized with `append`. Check `ifLastIndex` against the head and the latest marker, and append a settled clear marker at the next index, touching no existing rows. A `cause` is fenced like a handler append. |
+| `reclaim` | Delete one bounded batch of rows below the latest clear marker, with their bookkeeping, event-id records, lane pointers, and cached state. Report how many rows went and `done` when nothing is left. Never wait on a lock that other methods hold. |
+
+A store that supports clearing treats every event at or below the latest clear
+marker as superseded, whether or not its row still exists. `claimAvailable`
+never claims it, lane readiness at append and at completion ignores it (a
+dead-lettered lane head stops blocking), `renewClaims` reports it in
+`superseded`, `completeAttempt` and `failAttempt` return `superseded`, and an
+`append` whose `cause` names it throws `SUPERSEDED_ATTEMPT`. An `append` whose
+`originIndex` is at or below the marker throws `SESSION_CLEARED`. Reads start
+at the marker, `readState` returns its index as `clearIndex`, and claimed
+events carry it as `clearIndex`. In `append` and `completeAttempt`, an event id
+whose row is below this session's marker is free to reuse. Each check belongs
+inside the operation's existing atomic step. Without `clear` and `reclaim`,
+`session.clear()` and `session.schedule.clear()` throw a `TypeError` before
+writing anything.
 
 `attemptCount` counts claims, including abandoned ones. `failureCount` counts
 caught failures and dead-letters at ten. See
@@ -578,49 +623,61 @@ Custom scheduler adapters implement two methods:
 | Method | Effect |
 | --- | --- |
 | `schedule(task: SchedulerTask): Promise<void>` | put one versioned task on durable delivery infrastructure |
-| `handler(...servers)` | return the route that receives drain and append tasks |
+| `handler(...servers)` | return the route that receives drain, append, and clear tasks |
 
 Application routes call `scheduler.handler(...servers)` on the configured
 adapter. The handler requires at least one drainable server and rejects
 duplicate contract names synchronously.
 
-`SchedulerTask` is `SchedulerDrainTask | SchedulerAppendTask`. These task types,
-plus `ScheduledEvent`, are exported from `experimental-a2/server`.
+`SchedulerTask` is `SchedulerDrainTask | SchedulerAppendTask |
+SchedulerClearTask`. These task types, plus `ScheduledEvent`, are exported
+from `experimental-a2/server`.
 
 | Task | Fields |
 | --- | --- |
 | `SchedulerDrainTask` | `version: 1`, `kind: 'drain'`, `contract`, `sessionId`, required epoch-ms `dueAt` |
-| `SchedulerAppendTask` | `version: 1`, `kind: 'append'`, stable `id`, `contract`, `sessionId`, required epoch-ms `dueAt`, readonly `events` |
+| `SchedulerAppendTask` | `version: 1`, `kind: 'append'`, stable `id`, `contract`, `sessionId`, required epoch-ms `dueAt`, readonly `events`, optional `originIndex` |
+| `SchedulerClearTask` | `version: 1`, `kind: 'clear'`, stable `id`, `contract`, `sessionId`, required epoch-ms `dueAt`, `ifLastIndex` |
 | `ScheduledEvent` | fixed `id`, `type`, and JSON `payload` |
 
 Drain tasks wake pending work and carry no application payload. Append tasks
-carry the events for `session.schedule`.
+carry the events for `session.schedule`; `originIndex` is the scheduling
+handler's event, absent for root schedules. Clear tasks carry the condition
+for `session.schedule.clear`.
 
-Custom adapters deliver an authenticated, normalized append task through the
-server helper:
+Custom adapters deliver an authenticated, normalized append or clear task
+through the server helpers:
 
 ```ts custom-scheduler.ts
 import {
   deliverSchedulerAppend,
+  deliverSchedulerClear,
   type DrainableServer,
   type SchedulerAppendTask,
+  type SchedulerClearTask,
 } from 'experimental-a2/server'
 
 export async function deliver(
   server: DrainableServer,
-  task: SchedulerAppendTask,
+  task: SchedulerAppendTask | SchedulerClearTask,
 ) {
-  await deliverSchedulerAppend(server, task)
+  if (task.kind === 'clear') await deliverSchedulerClear(server, task)
+  else await deliverSchedulerAppend(server, task)
 }
 ```
 
-Import `deliverSchedulerAppend` from `experimental-a2/server`. It verifies the
-task and server contract match, revalidates the carried event inputs, and uses
-the ordinary top-level append path. The target server must have a scheduler.
-When the append leaves pending handler work, the helper resolves only after a
-recovery watchdog is durable; a send failure keeps the provider delivery
-retryable. Authenticate the transport and validate the task envelope before
-calling it.
+Import both from `experimental-a2/server`. Each verifies the task and server
+contract match. `deliverSchedulerAppend` revalidates the carried event inputs
+and uses the ordinary top-level append path. The target server must have a
+scheduler. When the append leaves pending handler work, the helper resolves
+only after a recovery watchdog is durable; a send failure keeps the provider
+delivery retryable. A task whose `originIndex` was cleared resolves without
+appending.
+
+`deliverSchedulerClear` runs a conditional `clear({ ifLastIndex })` and
+resolves after its deletion finishes. A store failure rejects, so the provider
+redelivers and the retry finishes deleting. Authenticate the transport and
+validate the task envelope before calling either helper.
 
 ## Session
 
@@ -708,10 +765,100 @@ ordinary top-level append validates that input, so a schema
 transform produces the stored payload from the original input. The events have
 `cause: null` and enter normal handlers, lanes, state, and streams.
 
+A task scheduled from a handler belongs to its triggering event's lifetime. If
+the session is cleared before delivery, the task is acknowledged without
+appending. Once a session has been cleared, handler task ids also include the
+clear, so a trigger id reused in the new lifetime schedules a new task. A root
+task has no triggering event, so its events join whichever lifetime exists when
+it is delivered, and its name identifies one task across lifetimes. Put
+something from the new lifetime in the name when you schedule again after a
+clear.
+
 There is no cancellation, reschedule, cron, or timer-listing API. See
 [Timers and delays](/guides/timers) for stale-timer guards, provider limits,
 and deployment compatibility.
 
+### `session.clear(options?)`
+
+```ts
+session.clear(options?: { ifLastIndex?: number }): Promise<{
+  cleared: boolean
+  index: number
+}>
+```
+
+End the session's current lifetime. One atomic step checks the condition and
+appends a reserved clear marker at the next index. The session id stays usable
+and indexes never restart. `ifLastIndex` is a non-negative safe integer; the
+first matching rule decides:
+
+| When | Result |
+| --- | --- |
+| the latest marker is at `ifLastIndex + 1` | `{ cleared: true, index }`, a retry of that clear |
+| `ifLastIndex` is given and is not the head | `{ cleared: false, index }`, nothing changes |
+| the head is `0` or already a clear marker | `{ cleared: true, index }`, nothing changes |
+| otherwise | `{ cleared: true, index }`, the new marker |
+
+`index` is always the head after the call. Every event at or below the marker
+is superseded: it is never dispatched again and never blocks its lane, its
+running handler's appends throw `SUPERSEDED_ATTEMPT`, and that handler's state
+reads never fold the new lifetime: they throw `SESSION_CLEARED`, except that
+after a clear from another instance, a read bounded at its own event may return
+that event's state from memory until the handler's `ctx.signal` aborts. Pushes and appends after the marker start the
+new lifetime.
+
+`clear()` then deletes the old events, their bookkeeping and event-id records,
+and cached state below the marker in short batches, and resolves when they are
+gone. Other work on the session keeps running between batches. If deletion
+fails, the call rejects with the session already cleared; any later clear of
+the session, including a retry, finishes the deletion. There is no background
+sweep. Event ids from the old lifetime can be used again. Presence is not
+cleared.
+
+On `ctx.session`, the clear is fenced like the handler's appends and ends the
+handler's own attempt: `ctx.signal` aborts with `SUPERSEDED_ATTEMPT` and
+returned events are discarded. Its deletion keeps running under the platform's
+`waitUntil`. All built-in stores support clearing. See
+[Clearing a session](/concepts/contracts#clearing-a-session).
+
+### `session.schedule.clear(name, options)`
+
+```ts
+session.schedule.clear(
+  name: string,
+  options: ({ delay: ScheduleDelay } | { at: Date }) & {
+    ifLastIndex: number
+  },
+): Promise<void>
+```
+
+Publish a conditional clear to the configured scheduler. `name` is non-empty
+and `ifLastIndex` is required. Timing has the same meaning and provider limits
+as `session.schedule`. The task id derives from the contract, session, name,
+and condition, plus the triggering event id and any earlier clear inside a
+handler; reuse a name only for the same timing. The promise resolves after
+provider acceptance.
+
+Delivery runs `clear({ ifLastIndex })` and acknowledges after the deletion
+finishes. A stale or duplicate delivery changes nothing. No event is appended.
+Indexes never repeat, so a condition from an older lifetime never matches a
+newer one. Clear tasks, appends, and recovery drains all use the Vercel
+scheduler's `deploymentId` setting.
+
+`ifLastIndex: ctx.event.index` matches only while the handler's event is still
+the head. The handler's own appends and returned events move the head, so a
+handler that writes should use the index of its last `ctx.session.append`
+instead. Actor handlers always commit state, so they can't use the trigger's
+index. A delay short enough to deliver while the handler is still running can
+match before those writes land; the clear then ends the handler's attempt and
+discards its returned events.
+
+Each delivery attempt resumes the deletion where the last one stopped. Vercel
+Queues redelivers until retention ends. QStash retries one message up to its
+`retries` budget; a deletion that outlasts every retry leaves the message in
+QStash's dead-letter queue with the rest of the old history still invisible,
+and any later clear of the session finishes it.
+
 ### `session.history()`
 
 ```ts
@@ -721,6 +868,8 @@ session.history(options?: { gte?: number; lte?: number }): Promise<Event[]>
 Raw events from the session, oldest first. `gte` and `lte` are inclusive event
 indexes; omit a bound to leave that end of the log open.
 Bounds are non-negative safe integers. `lte: 0` returns `[]`; `gte > lte` throws.
+After a clear, history starts after the marker. The marker itself is not
+returned.
 
 Redis reads a fixed committed range in pages of at most 256 events, with up to
 sixteen page reads in flight. Public history omits dispatch metadata. PostgreSQL
@@ -735,7 +884,7 @@ adapters can implement `readHistory(sessionId, options)` with the same exclusive
 session.state(
   reducer: Reducer<S>,
   options?: { through?: number | 'latest' },
-): Promise<{ state: S; index: number }>
+): Promise<{ state: S; index: number; clearIndex?: number }>
 ```
 
 The log folded through one committed prefix. `index` is its exact boundary,
@@ -750,6 +899,14 @@ Use `{ through: 'latest' }` inside a handler only when later committed events
 are intentionally part of the decision. A numeric `through` is an inclusive,
 non-negative safe integer; `through: 0` returns the reducer's initial state.
 
+Once a session has been cleared, the result includes `clearIndex`, the latest
+marker, and state folds from there. Forward the whole result when hydrating a
+client. A positive `through` below `clearIndex` throws `SESSION_CLEARED`, and
+`through: 0` returns the seed without `clearIndex`. On
+`ctx.session`, every state read throws it once the triggering event has been
+cleared, including `{ through: 'latest' }`. Handler `history()` and `stream()`
+are not fenced.
+
 The default handler read and numeric handler reads automatically retain their
 exact folded checkpoint while the triggering event is unfinished. Completion
 or dead-lettering releases the reference and collects the checkpoint when no
@@ -771,11 +928,11 @@ completed read or attaching snapshot contents.
 ### `session.stream(options?)`
 
 ```ts
-session.stream(options?: { startAfter?: number }): AsyncIterable<Event>
+session.stream(options?: { startAfter?: number }): AsyncIterable<Event | SessionCleared>
 session.stream(options: {
   startAfter?: number
   presence: true
-}): AsyncIterable<Event | PresencePatch | PresenceSnapshot>
+}): AsyncIterable<Event | SessionCleared | PresencePatch | PresenceSnapshot>
 ```
 
 A live feed of the session's events. `startAfter` is a non-negative safe integer;
@@ -783,6 +940,12 @@ A live feed of the session's events. `startAfter` is a non-negative safe integer
 Server-side only; `server.fetch` exposes it over SSE and WebSocket. Subscribing
 never dispatches handlers.
 
+A clear arrives in order as a `SessionCleared` marker, whose `type` is
+`'a2.cleared'`. A stream that opens below the
+latest marker begins with it. A stream that is already running delivers the
+log in order, so events from before the clear can arrive ahead of the marker.
+Reset when the marker arrives. Clearing never closes a stream.
+
 With `presence: true`, the feed yields one `PresenceSnapshot` first:
 `{ snapshot }`, the current pruned map with each field's own `value`,
 `seen`, and `at` stamp. Live presence patches then interleave with
@@ -865,13 +1028,12 @@ type Event = {
 
 ```ts
 createReact(options: {
-  client: A2Client          // bind a shared client: api + reducer + session identity
+  client: A2Client          // bind a shared client: api + contract + session identity
 }): { SessionProvider, useSession }
 
-// or, standalone (one client per provider mount):
+// or, bind the contract and supply api through the Provider:
 createReact(options: {
-  reducer: Reducer          // types everything: state, pushes, the feed
-  cache?: A2ClientCache     // optional; see local-first
+  contract: Contract       // requires a public reducer
 }): { SessionProvider, useSession }
 ```
 
@@ -879,9 +1041,9 @@ A factory, like `createContext`: call it once in a `'use client'`
 module, export the bound pair. Server components import
 `SessionProvider` from that module as a client reference; client
 components import `useSession` from the same file. See
-[Live UI](/guides/react#the-session-module).
+[Live UI](/guides/react#bind-react-once).
 
-`createReact({ reducer })` is also supported for provider-bound clients. Use a
+`createReact({ contract })` is also supported for provider-bound clients. Use a
 shared `A2Client` when code outside the provider needs to push before a route
 transition and the destination should adopt the same optimistic session.
 
@@ -890,35 +1052,61 @@ transition and the destination should adopt the same optimistic session.
 | Prop            | What it is                                             |
 | --------------- | ------------------------------------------------------ |
 | `sessionId`     | which session to subscribe to                          |
-| `initialState`  | server-rendered state                                  |
-| `initialIndex`  | the fold's frontier, where a new session starts streaming |
+| `initial`       | optional snapshot or Promise of a snapshot; `null` means bootstrap |
 | `initialEvents` | optional earlier raw events for a history UI           |
 | `participant`   | overrides the client's `participant`; one of the two is required to call `setPresence` |
 
-Opens the stream on mount, closes it on unmount, reconnects with
-backoff from its last streamed event. `participant` binds at the session's
+Supplies scope and optional initial data. Mounted enabled hooks own
+connection leases and reconnect from the last streamed event. `participant` binds at the session's
 first resolution; a changed provider prop is ignored for the session's
 runtime lifetime.
 
-`initialState` and `initialIndex` are the complete server-to-client handoff.
-For a new session, the stream starts after `initialIndex`, including events
+`initial` carries the complete state/index snapshot, plus `clearIndex` when
+the session has been cleared.
+For a new session, the stream starts after `initial.index`, including events
 appended between the server render and the connection. `initialEvents` only preloads the raw
 `events` feed for a UI that needs entries from before that frontier. It does
 not affect state hydration or stream resumption. Later snapshots advance
 state while preserving the stream's resume position, so delayed events
 still enter the feed without folding into state again.
 
-### `useSession()`
+`initial` accepts `InitialSnapshot<S>`: `StateSnapshot<S> | null | undefined |
+Promise<StateSnapshot<S> | null | undefined>`. The type is exported from
+`experimental-a2` and `experimental-a2/client`. A cold session waits for a
+supplied Promise before connecting. A snapshot result seeds state; `null`
+or `undefined` selects subscription bootstrap. Rejection pauses cold startup
+and reports through `connection.error`; supply a new Promise, snapshot, or
+`null` to resume. A warm session keeps its current state and connection.
+The Provider itself does not suspend. Keep Promise identity stable.
+
+### `useSession(options?)`
 
 ```ts
-const { state, push, reconnect, events, index, loadHistory, history, connection,
-  presence, setPresence } = useSession()
+const { state, hydrated, push, reconnect, events, index, loadHistory, history, connection } = useSession()
 ```
 
-`state` starts from the initial snapshot and folds live events through the
+`state` has the reducer's client state type. A supplied snapshot seeds the
+first render. Otherwise it displays `reducer.initialState`, through the client
+projection when present, until a snapshot replaces it atomically. Without a
+supplied snapshot, the server sends one first on the same subscription.
+Bootstrap errors and retries use `connection`.
+`hydrated` is a boolean shared with `session.getSnapshot()`. It is `false`
+while only the reducer seed is available and becomes `true` when an initial
+snapshot or bootstrap is applied, even for an empty state at index 0.
+It stays `true` while cached state survives reconnects, disabled hooks, or a
+failed replacement preload. It does not imply a live connection or fresh data.
+The hook accepts `sessionId`, `client`, `participant`, `initial`, `enabled`, and
+`suspend` options; scope defaults come from its Provider and bound client.
+`suspend` defaults to `false`. With `true`, React `use()` reads the supplied
+`initial` Promise, using the nearest Suspense and Error boundaries. Automatic
+subscription bootstrap never suspends, including when the Promise resolves
+to `null` or `undefined`. The default renders the reducer seed while a cold
+initial Promise is pending. `enabled` controls connection ownership independently.
+
+`state` starts from that snapshot and folds live events through the
 shared reducer. `events` is the raw event feed: observed, explicitly
 seeded, or backscrolled. Unless `initialEvents` seeds earlier entries or
-`loadHistory` fetches them, it begins after `initialIndex`. `index` is
+`loadHistory` fetches them, it begins after `initial.index`. `index` is
 the latest server-confirmed state index, the `lastSeenIndex` for
 [cancellation](/guides/cancellation).
 
@@ -933,9 +1121,15 @@ the oldest loaded event. Pass an explicit `before` to read another range.
 It never touches `state` or the optimistic overlay. Calls
 serialize per session and already-loaded ranges are not refetched.
 `history` is the progress: `{ loading, complete, oldestLoaded }`, where
-`complete` means the feed reaches index 1 (or the log is empty). The `ws` api has no history lane; there `loadHistory`
+`complete` means the feed reaches index 1, or the first event after the latest
+clear (or the log is empty). The `ws` api has no history lane; there `loadHistory`
 throws a `TypeError`.
 
+When a clear reaches the session, `state` resets to the reducer's initial
+state and `events` drops everything at or below the marker. Unconfirmed pushes
+stay in the overlay and apply to the reset state. A push acked below the marker
+was cleared with it: it leaves the overlay and its `confirmed` resolves.
+
 `presence` is the replicated ephemeral map,
 `Record<participantId, { [field]: { value, seen, at } }>`, including
 this client. `setPresence(values)` is fire-and-forget: validated
@@ -1015,7 +1209,9 @@ are actually flowing, not "the socket hasn't errored yet". See
 ```ts
 useSession(client: A2Client, sessionId: string, options?: {
   participant?: string // overrides the client's participant
-  hydrate?: { state: S; index: number }
+  initial?: InitialSnapshot<S>
+  enabled?: boolean
+  suspend?: boolean
 }): UseSessionResult
 ```
 
@@ -1026,58 +1222,91 @@ handle is identity-mapped: every hook and provider mounting the same
 session shares one runtime. The stream is refcounted: the first mount
 connects, the last unmount closes (StrictMode-safe).
 
-`hydrate` is the hydration input, one atomic option: the
-`{ state, index }` pair `session.state(reducer)` returns, fetched by
-your app through its own route and handed over whenever it lands.
-While it is `undefined`, the hook holds the stream (connecting without
-a fold would replay the whole log). There is no pending flag on the
-result: whether the fold has been handed over is your own input, so
-your data layer's loading state is the pending state.
-When it arrives, the session hydrates under the usual
-never-move-backward rule and the stream connects at that frontier.
-For a deliberate full replay, hand the fold's true starting point:
-`{ state: reducer.initialState, index: 0 }`. State at index 0 is the
-reducer's seed by definition, so the explicit replay needs no special
-vocabulary. See
-[Client-first sessions](/guides/react#client-first-sessions).
+`initial` accepts the result of `session.state(reducer)` or its Promise. Pass it
+whole: its `clearIndex` lets a cached client drop history from before a clear
+it never streamed. The automatic snapshot carries it too. Without it,
+the subscription obtains a snapshot automatically. To defer automatic I/O,
+pass `enabled: false`. Disabled hooks keep observing cached state; other
+owners continue normally. Explicit pushes can still acquire a connection.
+For deliberate full replay, supply `{ state: reducer.initialState, index: 0 }`.
+See [Live UI](/guides/react).
 
 ## `experimental-a2/ai`
 
-### `agent(options)`
+The isomorphic AI protocol: event schemas, the `AIState` reducer, pure input
+builders, and `agentContract()` for extending both. It has a peer dependency on
+AI SDK v7, used as types only here.
+
+### `agentContract(options)`
 
 ```ts
-agent(options: {
+agentContract<M extends UIMessage = UIMessage>(options: {
   name: string
   events?: Record<string, StandardSchemaV1>
-  messageSchema?: StandardSchemaV1<UIMessage>
-  reducerName?: string
-}): AgentDefinition
+  messageSchema?: StandardSchemaV1<M>
+  reducer?: {
+    name: string // snapshot identity: rename it when fold changes
+    initialState: X // its keys may not shadow AIState's
+    fold: (state: X, event: ContractEvent) => X
+  }
+}): Contract<Events, {}, AgentReducer<M, Events, X>>
 ```
 
-Defines an isomorphic agent as ordinary A2 parts. Its `contract` contains the
-built-in AI protocol plus `events`, and its `reducer` projects `AIState`. The
-definition exposes only `contract` and `reducer`.
+A core contract carrying the built-in AI protocol plus `events`, with a reducer
+that folds `AIState` and, with `reducer`, your application state beside it.
+The session's state is `AIState<M> & X`. Share it when a client needs
+application events or state: serve it with `agent({ contract })` and use it
+with [`useAgent({ api, id, contract })`](#useagentoptions). Otherwise
+`agent({ name })` builds one on the server and clients use the built-in
+protocol.
+
+Built-in event names cannot be replaced by `options.events`. `messageSchema`
+validates a narrower `UIMessage` type in message payloads; the explicit type
+argument types messages without one. `reducer.fold` sees `X` and every event,
+never the transcript; it runs after the AI fold on the server and in every
+client, so optimistic display carries through. A key of `initialState` that
+`AIState` also has throws a `TypeError` and fails to typecheck. The reducer name
+is `AI_STATE_REDUCER` (`a2.ai.state.v26`) without `reducer`, and
+`${reducer.name}+a2.ai.state.v26` with one, so checkpoints advance when either
+fold changes. `AgentReducer` types that name, which is what lets
+[`createAgentClient()`](#createagentclientoptions) accept a plain
+`agentContract()`, and carries `X` to `agent()`'s resolvers.
+
+### `TranscriptMessage<M>`
 
-Built-in event names cannot be replaced by `options.events`.
+```ts
+type TranscriptMessage<M extends UIMessage> = Omit<M, 'parts'> & {
+  parts: Array<M['parts'][number] | CompactionPart>
+}
+```
 
-### `handlerContext(agent)`
+The message type of `AIState<M>['messages']` and `deriveUIMessages()`: your
+message type with the [compaction part](#iscompactionpartpart) added, so
+`isCompactionPart()` narrows even when `M` declares its own data parts.
+
+### `AIMessageOf<Events>`
+
+The `UIMessage` type a contract's `ai.message.created` schema carries, such as
+`AIMessageOf<typeof contract.events>`. It falls back to `UIMessage`. `agent()`
+uses it to type messages for any contract carrying the AI protocol.
+
+### `handlerContext(contract?)`
 
 Reads the durable A2 handler context ambient to the current tool
 execution. Tools are plain AI SDK `tool()` definitions; A2 passes their
 options through to the AI SDK without interpreting them and runs each
 local `execute` inside an ambient context scope. Call
-`handlerContext(agent)` (or pass a contract) anywhere below `execute`,
-including awaited helpers and async iteration. The argument types the
-result and is verified against the executing server's contract: a
-mismatched agent, or a call outside any tool execution, throws a
-`TypeError`.
+`handlerContext()` anywhere below `execute`, including awaited helpers and
+async iteration. A call outside any tool execution throws a `TypeError`.
+Without an argument, the context is typed for the built-in protocol. Pass a
+shared `agentContract()` to type application events; A2 verifies it against the
+executing agent and throws a `TypeError` on a mismatch.
 
 The returned `AgentToolContext<D>` supplies the current A2 handler's `event`,
 `attempt`, `session`, and `signal`. Local tools execute the explicit
 `ai.tool.execution.requested` work event. Its payload contains the admitted
-`call`, `generation`, `turnId`, and execution `version`. The session has the
-supplied agent's complete event vocabulary. Calls such as
-`ctx.session.schedule()` use the scheduler of the server executing the tool.
+`call`, `generation`, `turnId`, and execution `version`. Calls such as
+`ctx.session.schedule()` use the scheduler of the agent executing the tool.
 
 The context is runtime capability, not event data. A2 creates it for the
 current attempt, never persists it, and never sends it to the model or a
@@ -1093,7 +1322,8 @@ functions.
 
 ### `inputs`
 
-Pure typed inputs for `append()` and `push()`:
+Pure typed inputs for `append()` and `push()`. The `useAgent()` actions build
+the browser ones:
 
 | Input | Events |
 | --- | --- |
@@ -1122,7 +1352,8 @@ All builders emit `ai.control.requested`. Persistence and application are
 separate: `ai.control.decided` returns `{ commandId, outcome, reason? }` through
 the existing stream. Outcomes are `applied` or `rejected`. Rejection reasons
 include `not-pending`, `role-mismatch`, `stale-turn`, `not-found`,
-`not-user-input`, and `closed`. `state.receipt` holds the latest user receipt.
+`not-user-input`, and `closed`.
+`state.receipt` holds the latest user receipt.
 
 Steering validates and prioritizes new input even if the observed turn has
 finished. A matching active turn finishes its current model response and tool
@@ -1224,6 +1455,47 @@ enter later model prompts. Raw progress remains in the log. Available inputs,
 approval-waiting calls, and completed results retain their existing terminal
 handling.
 
+### `reasoningLevels`
+
+```ts
+type ReasoningLevel = 'provider-default' | 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh'
+const reasoningLevels: readonly ReasoningLevel[]
+```
+
+Every `ReasoningLevel`, in order, for pickers. A `model` option returns one in
+[`ModelSettings`](#modelsettings).
+
+### `isCompactionPart(part)`
+
+```ts
+isCompactionPart(part: { type: string }): part is CompactionPart
+
+type CompactionPart = {
+  type: 'data-a2-compaction'
+  id: string // the compacting generation's ID
+  data: {
+    status: 'running' | 'completed' | 'failed' | 'interrupted'
+    inputTokens?: number
+    thresholdTokens?: number
+    summary?: string
+    usage?: LanguageModelUsage
+  }
+}
+```
+
+The transcript part that marks a compaction. When `ai.compaction.requested`
+folds, the reducer appends it to the active response, between the steps
+before it and the model step it compacted for; a compaction before the first
+step creates the response with this part. The part counts toward that step's
+recovery base, so Stop cutoffs, failures, and retries of the step keep it.
+`ai.compaction.completed` settles it in place with the summary and usage. A
+running compaction whose generation ends first becomes `interrupted` (Stop,
+Pause now, or session close) or `failed` (failure). A pending Stop previews it
+as `interrupted` on the client. A superseded worker attempt's part is removed,
+and its replacement compacts again if it needs to. AI SDK
+`convertToModelMessages()` skips data parts by default, and model context never
+contains it.
+
 ### `events` and `createEvents(options?)`
 
 The built-in Standard Schema definitions. Use `events` for the default AI SDK
@@ -1232,9 +1504,10 @@ message type. Both are isomorphic.
 
 ### Optimistic AI client state
 
-Clients using `agent().reducer` or `createReducer()` expose `state.messages`,
-`state.inbox`, and `state.starting` with pending send, edit, move, remove,
-Send now, steer, pause, resume, and Stop commands applied for display. Idle, unpaused
+Every client folding an AI reducer exposes `state.messages`, `state.inbox`, and
+`state.starting` with pending send, edit, move, remove, Send now, steer, pause,
+resume, and Stop commands applied for display. This includes contracts with
+application state from `agentContract({ reducer })`. Idle, unpaused
 sends appear in the conversation immediately. A generating input occupies the
 optimistic turn, so subsequent sends queue. Busy or paused sessions queue new
 sends. `starting` indicates a speculative turn awaiting acceptance; it does not
@@ -1262,30 +1535,17 @@ The pending-command ledger survives request echo and retires on the matching
 the client's existing optimistic overlay. This display adds no I/O and does not
 read raw history.
 
-### `createReducer(options)`
+### `AIState`
 
-```ts
-createReducer({ contract, name?, fold?, stateSchema? }): AIStoredReducer
-```
+The AI reducer's `initialState`, `fold`, server `session.state()`, and client
+snapshots all use `AIState`. Keep state and its log index together when
+hydrating; do not fold already-seen history twice. `messages` holds
+[`TranscriptMessage<M>`](#transcriptmessagem) values. Model context has its own
+built-in fold and schema, which carries the contract's application state.
 
-Builds a normalized AI reducer for a compatible contract. Its `initialState`,
-`fold`, and server `session.state(reducer)` use `AIStoredState`. Client and
-React snapshots expose the inferred `AIState` view automatically.
-
-`reducer.view(storedState)` derives confirmed `AIState` for server code.
-`reducer.fromView(state)` converts a confirmed view into stored state, including
-when migrating an application-owned hydration value. Keep the stored state and
-its log index together when hydrating; do not fold already-seen history twice.
-`fold` can customize the confirmed `AIState` transition, and `stateSchema`
-validates that view after restoration. Both apply only to the transcript.
-Model context has its own built-in fold and schema. Changed custom fold semantics
-still require a new `name`.
-
-Stored state is versioned, serializable data. Shared payload records and
-inverse changes replace repeated tool values and complete recovery copies.
-The reducer caches its live view and builds the records when the stored fields
-are read or serialized. Treat state and views as immutable. No event or tool
-payload is truncated. `AIState`
+Persistence encoding is internal. Tool inputs, outputs, and provider metadata
+live in message parts; the tool activity list retains only identity and status.
+No event or tool payload is truncated. `AIState`
 contains `inbox`, `active`, `starting`, the latest command `receipt`, session lifecycle,
 messages, generation status, pending approvals
 and input, tool activity, compaction, usage, the last error, and
@@ -1318,22 +1578,23 @@ Checkpoint size and serialization cost still grow with retained progress.
 Tool-input deltas update `input-streaming` parts with best-effort partial JSON
 for display. The state stays `input-streaming` until a completed input arrives;
 partial parsing does not authorize execution or change interruption handling.
-Extension events are ignored. The default reducer name is `a2.ai.state.v22:records-v2`.
+Application events are ignored by the AI fold.
 
 ### `deriveUIMessages(history)` and `reduceAIState(state, event)`
 
-`deriveUIMessages()` folds a raw A2 event history directly into AI SDK
-`UIMessage[]`. `reduceAIState()` is the event-at-a-time form used by the
+`deriveUIMessages()` folds a raw A2 event history directly into
+`TranscriptMessage<M>[]`, AI SDK messages that include compaction parts. `reduceAIState()` is the event-at-a-time form used by the
 standard reducer. Both synchronously project the same chunk-only protocol.
 
 ## `experimental-a2/ai/server`
 
-### `createAgentServer(options)`
+### `agent(options)`
 
 ```ts
-createAgentServer({
-  agent: AgentDefinition,
-  model: LanguageModel | (context => LanguageModel),
+agent({
+  name: string, // or contract: agentContract(...), never both
+  events?, messageSchema?, // with name: server-only application events
+  model: LanguageModel | ModelSettings | (context => LanguageModel | ModelSettings),
   tools?,
   instructions?,
   generation?,
@@ -1342,17 +1603,49 @@ createAgentServer({
   generate?,
   compaction?,
   progress?,
-  store?, scheduler?, telemetry?, handlers?,
-}): A2Server
+  toolLane?: string, // run local tool executions one at a time on this lane
+  handlers?, // application event handlers
+  store?, scheduler?, telemetry?,
+}): Agent<Events, State, Name> // an A2Server
 ```
 
-Creates the standard server for an agent. A2 runs one AI SDK `streamText()`
-model step per durable generation, persists each `UIMessageChunk` once in a
-durable progress batch, projects messages synchronously, extracts tool and
-approval lifecycle events, executes local tools, and records completion,
-usage, interruption, and failure. `model` accepts an AI SDK model string or
-provider model. `model` and `instructions` can be values or per-generation
-async resolvers.
+Serves an AI agent as one ordinary A2 server: the built-in protocol, its model
+and tool handlers, and A2's store, scheduler, and telemetry. Pass `name` for the
+built-in protocol (with optional server-only `events` and `messageSchema`), or a
+shared `agentContract()` as `contract` when clients fold application state.
+Any other contract throws a `TypeError` and fails to typecheck; a fully custom
+contract is core A2, served by `createServer()`. Messages are typed by the
+contract's `ai.message.created` schema through
+[`AIMessageOf`](#aimessageofevents).
+The result is an `A2Server` with `fetch`, `session(id)`, `drain()`, and
+`contract`. `typeof` it types `useAgent()` and
+`createAgentClient()` through a type-only import; `Name` is its reducer name,
+which decides whether the contract-free client accepts it.
+
+A2 runs one AI SDK `streamText()` model step per durable generation, persists
+its `UIMessageChunk`s once in durable progress batches, projects messages
+synchronously, extracts tool and approval lifecycle events, executes local
+tools, and records completion, usage, interruption, and failure. `model`
+accepts an AI SDK model string or provider model, or
+[`ModelSettings`](#modelsettings) to choose its reasoning level and speed with
+it. `model`, `instructions`, and `generation` can be values or per-generation
+async resolvers. A resolver that throws, or returns an invalid value, fails the
+turn once with its message, like a provider error, instead of retrying; the
+attempt's `ai.generation.started` omits `model` when the model never resolved.
+`retry()` runs the step again. Store failures (`A2Error`) still retry durably.
+
+`fetch` accepts reads and pushes of public AI controls:
+`ai.control.requested` commands other than the server-authored
+`request-input` and `tool-result`, with
+`send`, `edit`, and `steer` limited to user messages. With a `contract`, it also
+accepts the contract's application events, like any A2 server; `events` passed
+with `name` stay server-only, since no client can push them. Every other pushed
+event answers `400`. `fetch(request, { authorize })` adds per-operation policy on
+top, such as who may push which application event. `handlers` handles application events; naming an
+event the agent handles itself throws a `TypeError` at construction.
+
+The agent's `telemetry` instruments both Core and AI operations in the same
+active trace. See the [span catalogue](#the-span-catalogue).
 
 `generation` contains per-step settings such as `temperature`,
 `maxOutputTokens`, `topP`, provider options, and tool approval policy. A2 owns
@@ -1366,18 +1659,30 @@ untouched. A local tool reads its durable context with `handlerContext()` when
 its handler executes. Model-step timeouts remain available; tool-execution
 timeouts are not.
 
+A `generation` resolver receives `{ event, messages, state, session, signal }`
+and returns `AgentGenerationSettings` or a promise. It runs once per attempt
+before compaction and model dispatch; its settings also govern tool approvals
+and automatic-compaction compatibility. Static settings are validated at
+construction, resolved settings before use. Failures and cancellation follow
+model resolution.
+
 `messageMetadata(context)` synchronously maps each default AI SDK stream part
-to the metadata type of the agent's `UIMessage`. The context includes the
-generation state and the current `TextStreamPart`. Metadata returned for
-standard `start` and `finish` parts is recorded with generation progress and
-shallow-merged onto the projected assistant message. Use the `finish` part's
-`totalUsage` to retain final token usage. A custom `generate` function owns its
-metadata chunks and does not use this mapper.
+to the metadata type of the agent's `UIMessage`. It receives the same context
+as `generate(context)`, plus the current `TextStreamPart` as `part`; its
+`generation` is the settings the default generator sends, with A2's Gateway
+defaults applied. Metadata returned for standard `start` and `finish` parts is
+recorded with generation progress and shallow-merged onto the projected
+assistant message. Use the `finish` part's `totalUsage` to retain final token
+usage. A custom `generate` function owns its metadata chunks and does not use
+this mapper.
 
 `generate(context)` optionally replaces the default AI SDK generation. It
-receives messages, the resolved model and instructions, tools, generation
-settings, request state, and the abort signal. It returns exactly one model
-step as a `ReadableStream<UIMessageChunk>`. A2 continues to own tool execution,
+receives the resolver context, `{ event, messages, state, session, signal }`,
+plus the step's `generationId`, `modelMessages`, and the resolved `model`,
+`instructions`, `tools`, and `generation` settings. `messages` and
+`modelMessages` reflect this step's compaction. Its stream writes the assistant
+message `event.payload.responseMessageId`. It returns exactly one model step as
+a `ReadableStream<UIMessageChunk>`. A2 continues to own tool execution,
 continuation, and the durable lifecycle around that stream.
 
 Generation requests use one durable lane, so model calls for a session do not
@@ -1389,7 +1694,8 @@ failure keeps later messages queued until the failed response is explicitly
 retried or interrupted.
 
 Independent authorized tool handlers run concurrently without a fixed
-concurrency limit. A private coordinator reducer tracks generation closure,
+concurrency limit. `toolLane` names a lane for every local tool execution, so
+they run one at a time in admission order; model steps keep their own lane. A private coordinator reducer tracks generation closure,
 cancellation, calls, approvals, and terminal results for the active response.
 Completed responses do not accumulate in its state. Its
 `ctx.session.state(coordinator, { through: 'latest' })` reads the durable
@@ -1410,7 +1716,7 @@ require their own idempotency. Approved provider-executed calls may satisfy the
 join from the approval response. Provider tools with declared deferred-result
 support wait for their provider result instead of a local executor. An
 authenticated provider callback appends the terminal `ai.tool.result` through
-the trusted server session API; the browser push allowlist rejects it.
+the trusted server session API; `fetch` rejects it from browsers.
 
 `compaction` defaults to automatic for supported Gateway requests. It accepts
 `false` to disable compaction and discovery, `{ thresholdTokens?, instructions? }`
@@ -1421,16 +1727,15 @@ The resolver runs once per generation and returns a valid policy or `false`.
 It can await application reducers through `context.session.state(reducer)`, whose
 default boundary is the captured prompt frontier. Model, instruction, compaction,
 metadata, and custom-generation contexts expose state access and omit raw history.
-Callbacks receive prompt messages and request identity, without `state` or
-`execution` arguments. Model and instruction resolvers receive
-`{ event, messages, session, signal }`. Compaction and generation callbacks also
-receive `modelMessages`, including committed summaries. Custom transcript folds
-and schemas apply only to the transcript. `agent.reducer` and `createReducer()`
-continue to expose the full
-transcript view. To read it explicitly, load
-`context.session.state(agent.reducer)` and pass its `state` to
-`agent.reducer.view()`. The stored state also remains suitable for client
-hydration.
+Callbacks receive prompt messages and the triggering `event`, without an
+`execution` argument. Model, instruction, and generation-setting resolvers receive
+`{ event, messages, state, session, signal }`, where `state` is the contract's
+application state (from `agentContract({ reducer })`, `{}` without one) as of the
+captured snapshot; it rides in the model-context checkpoint, so it costs no
+read. Compaction, metadata, and custom-generation callbacks receive the same
+context plus `modelMessages`, including committed summaries. The contract's reducer continues to expose the full
+transcript. `context.session.state()` returns its `AIState` directly, paired
+with its log index for hydration.
 Static options are validated at construction; resolved options are validated
 before that generation starts. Each session uses its own resolved value. `thresholdTokens` is an
 optional positive safe integer. `instructions` adds to A2's internal summary
@@ -1469,53 +1774,149 @@ caching. It does not invoke application generation callbacks, transforms, or too
 hooks. Both custom policy callbacks and `generate` receive `modelMessages`, the
 model-ready prompt including summaries, alongside typed UI `messages`.
 
-Built-in summaries remain separate from application-typed messages. Render
-`state.compaction?.status === 'running'` as current activity, and the durable
-`ai.compaction.*` events as historical timeline markers. The conversation in
-`state.messages` from the transcript reducer remains intact. Model execution
+Built-in summaries remain separate from application-typed messages. The
+transcript marks each compaction with a
+[`data-a2-compaction` part](#iscompactionpartpart), and
+`state.compaction?.status === 'running'` reports current activity. The
+conversation in `state.messages` remains intact. Model execution
 uses a separate context checkpoint; existing compactions do not require a
 transcript read. Successful compaction is permanent, including across failure,
 interruption, retry, and recovery. Retry reruns the failed step from the latest
 committed context. Compaction defers while tool exchanges or A2-owned tool work
 remain unsettled, checked with one fresh coordinator state read on each candidate.
 Unresolved dead-lettered tool work also defers compaction until repair and
-settlement or session closure. `progress` controls durable batching with
-`maxChunks` and `maxDelayMs`.
+settlement or session closure. `progress` controls durable batching. By
+default each batch is written as soon as the previous one finishes, so a slow
+model's chunks are written one at a time and chunks that arrive during a write
+share the next batch, up to `maxChunks` (128). `maxDelayMs` (default 0) lets a
+batch keep collecting chunks for up to that long after the previous write;
+boundary chunks and `maxChunks` write sooner. Raising it trades token latency
+for fewer progress events.
 
 This entry point is server-only and resolves to a throwing browser stub.
 
+### `ModelSettings`
+
+```ts
+type ModelSettings = {
+  model: LanguageModel
+  reasoning?: ReasoningLevel
+  speed?: 'fast' | 'standard'
+}
+```
+
+A model with its reasoning level and speed, which a `model` option or resolver
+returns to choose all three together. `reasoning` becomes the AI SDK
+`reasoning` call option. `speed: 'fast'` sets `providerOptions.gateway.speed`
+to prefer AI Gateway's faster tier when the model offers one, and `'standard'`
+removes a configured speed. Both override the same settings in `generation`.
+[`reasoningLevels`](#reasoninglevels) lists the levels.
+
 ### `runWithHandlerContext(ctx, fn)`
 
 The testing seam for context-reading tools: runs `fn` with `ctx`
 installed as the ambient handler context, so a tool's `execute` can be
 called directly in tests. Inside `fn`, `handlerContext()` returns `ctx`
-for any agent argument.
+with or without a contract argument.
+
+See [Durable AI agents](/guides/ai-agents) for the protocol and complete
+examples.
 
-### `createHandlers(options)`
+## `experimental-a2/ai/client`
 
-Returns the built-in A2 handler table without constructing a server. Spread
-it into `createServer({ handlers })` beside application handlers when you need
-a custom assembly. The table handles input facts, generation requests, model
-step completion, tool calls, approval responses, and terminal tool results.
-Application handlers spread later can deliberately replace a built-in
-handler. Use `handler` from `experimental-a2/server` to normalize an
-existing entry before wrapping its `handler` and spreading its execution
-policy. Entries in this table's type are optional; narrow an entry before
-passing it to `handler`.
+### `createAgentClient(options)`
 
-A custom assembly owns its browser ingress policy. Use
-`server.fetch(request, { authorize })` to reject server-authored AI event names
-before they reach the server. `createAgentServer()` installs the built-in
-browser allowlist automatically.
+```ts
+createAgentClient<typeof agent>(options: {
+  api: ClientApi
+  gcTime?: number
+  participant?: string
+  reconnect?, fetch?, webSocket?, // as createClient
+}): AgentClient // an A2Client over the built-in AI protocol
+```
 
-See [Durable AI agents](/guides/ai-agents) for the protocol and complete
-examples.
+A contract-free client for an `agent()` route. It accepts only agents whose
+reducer carries the built-in name (`typeof AI_STATE_REDUCER`): `agent({ name })`
+or `agent({ contract })` with an `agentContract()` that has no `reducer`. The AI protocol and its
+`AIState` reducer are library code, and the type argument, taken from a
+type-only import of the server module, types messages. Use it for pushes
+outside React, such as a first message sent before navigating, and pass it to
+`useAgent({ client })` so the hook shares its sessions. It pushes the built-in
+AI controls only. Agents built from an extended `agentContract()` use
+`createClient({ contract })` instead, so the client folds the same state.
+
+## `experimental-a2/ai/react`
+
+### `useAgent(options)`
+
+```ts
+useAgent<typeof agent>(options: {
+  id: string
+  initial?: InitialSnapshot<AIState>
+  participant?: string
+} & ({ api: string } | { client: AgentClient })): UseAgentResult
+
+useAgent(options: {
+  id: string
+  initial?: InitialSnapshot<State>
+  participant?: string
+} & (
+  | { api: string; contract: Contract } // a shared agentContract(), imported for real
+  | { client: A2Client } // createClient({ contract, api })
+)): UseAgentResult
+```
+
+One agent session in React: its live optimistic `AIState` and actions that
+fill in protocol identities. With `api`, the hook keeps one shared client per
+route for the page's lifetime, reading `globalThis.fetch` on each request; with
+`client`, it uses yours, for a custom `fetch`, headers, or `gcTime`. Both forms
+accept only agents whose reducer carries the built-in name, like
+`createAgentClient()`. With `contract`, it folds the contract's application
+state too, keeping one client per contract and route; `state` is
+`AIState & X` and `push` accepts the contract's events. Pass that contract's
+`createClient({ contract, api })` as `client` instead to share it with pushes
+outside React, such as a first message sent before navigating. A custom
+contract, one not built by `agentContract()`, uses core A2's `useSession()` and
+`inputs` directly. Keep one options form per call site;
+the form must not change between renders.
+
+The result is the session result (`state`, `index`, `connection`, `push`,
+`events`, `hydrated`, `reconnect`, `loadHistory`, `history`) plus:
+
+| Member | Does |
+| --- | --- |
+| `messages` | `state.messages` |
+| `status` | `state.status` |
+| `indicator` | `'starting'`, `'thinking'`, `'compacting'`, or `null` |
+| `sendMessage(message, { generate? })` | queues a string (one text part) or a `UIMessage` |
+| `steer(message)` | steers the active turn after its current step, or sends when idle |
+| `stop()` | stops the active turn at the rendered frontier |
+| `approve(approval)`, `deny(approval, { reason? })` | answers a pending approval |
+| `respond(input, value)` | answers a pending application input |
+| `retry()` | retries the failed response with a fresh `retryId` |
+| `pause({ when })`, `resume()` | pauses and resumes |
+| `queue.edit(message)`, `queue.move({ inputId, beforeId })`, `queue.remove(inputId)`, `queue.sendNow(inputId)` | edits the inbox |
+
+Every action returns a `PushResult`, like `push()`: it resolves to the
+persisted command events and rejects when the push fails, and `.confirmed`
+resolves when the stream delivers them back. Each event's `id` is the
+`commandId` of its `ai.control.decided` receipt. Actions read identities from
+the state of the render that created them, so `stop()` and `queue.sendNow()`
+carry the frontier the user saw. An action with nothing to address, such as
+`stop()` without an active turn or `retry()` without a failed one, resolves to
+an empty array. Actions are rebuilt on every render; their identity is not
+stable.
+
+`indicator` is `starting` for an optimistic turn awaiting acceptance,
+`compacting` while a summary runs, `thinking` while the current model step has
+no visible part (reasoning and step boundaries do not count), and `null`
+otherwise.
 
 ## `experimental-a2/client`
 
 ```ts
 createClient(options: {
-  reducer: Reducer
+  contract: Contract // requires a public reducer
   api: ClientApi
   gcTime?: number // idle session lifetime; 5 minutes by default
   participant?: string // default presence identity for every session
@@ -1555,8 +1956,13 @@ Call `session.reconnect()` to resume immediately with a fresh attempt count.
 Releasing the last lease still closes the stream. A later first lease starts
 a new connection. Push retries are independent of this policy; a push does
 not resume a paused stream. An acknowledged push's `confirmed` promise waits
-until streamed events or a newer hydrated snapshot cover the acknowledged
-state index. Resumption preserves the stream's own position, even when
+until the stream delivers through the acknowledged index. A bootstrap
+snapshot, or a stream that starts after a supplied initial index, delivers
+through that index. Hydration does not otherwise confirm an unobserved
+acknowledgement. A push never waits for bootstrap. An HTTP push does not
+wait for a pending initial Promise either; a WebSocket push rides its
+connection, which opens once that Promise settles.
+Resumption preserves the stream's own position, even when
 hydration has advanced state while paused.
 
 A `SessionUrl` function runs for each HTTP request or WebSocket connection.
@@ -1569,7 +1975,7 @@ a string because its connection carries more than one session.
 The framework-agnostic session client `experimental-a2/react` is built on: the SSE
 subscription with frontier resume and reconnection, the optimistic push
 queue with ack/rollback, and the local fold. `client.session(id, {
-initialState?, initialIndex?, initialEvents?, participant? })` returns a
+initial?, initialEvents?, participant? })` returns a
 handle with `getSnapshot()`/`subscribe()` (the `useSyncExternalStore`
 contract), `push()`, `loadHistory()`, `connect()`, `reconnect()`, and `close()`.
 `connect()` takes a lease on the live stream and returns its release:
@@ -1596,6 +2002,16 @@ frontier. Idle handles are evicted after `gcTime`. This memory layer is
 separate from `experimental-a2/cache-indexeddb`: memory preserves identity
 across route transitions, while IndexedDB preserves the replica across reloads.
 
+`initial` accepts the same `InitialSnapshot<S>` as React. A pending Promise
+delays cold connection startup, including a connection acquired by `push`.
+An HTTP push is sent without waiting; a WebSocket push waits for that
+connection. It does not start another request. Replacing the source or calling `close()`
+invalidates its pending result and any deferred adoption behind a write.
+Releasing the last connection lease does not cancel the caller's Promise;
+it can still seed cached data without reopening transport. Idle eviction
+detaches A2's listener. Repeating the same Promise within that cached runtime
+does not restart cancelled work.
+
 ## `experimental-a2/cache-indexeddb`
 
 ```ts
@@ -1622,15 +2038,31 @@ each handler → the events those handlers append.
 
 ### The span catalogue
 
-Five spans, all carrying `a2.contract` and `a2.session_id`:
-
-| Span        | Wraps                                                  |
-| ----------- | ------------------------------------------------------ |
-| `a2.append` | validation + the store write (one batch)               |
-| `a2.drain`  | one drain pass over a session's backlog                |
-| `a2.event`  | one claimed dispatch of one event                      |
-| `a2.state`  | one `state()` read: snapshot-plus-tail load + fold      |
-| `a2.snapshot` | one background batch of checkpoint writes            |
+All spans carry `a2.contract` and `a2.session_id`. Core spans describe the
+durable runtime; `a2.ai.*` spans describe the built-in AI handlers:
+
+| Layer | Span | Wraps |
+| ----- | ---- | ----- |
+| Core | `a2.append` | validation + the store write (one batch) |
+| Core | `a2.drain` | one drain pass, including concurrent handlers |
+| Core | `a2.event` | one claimed dispatch, including its handler and completion |
+| Core | `a2.claim` | one `claimAvailable` store operation |
+| Core | `a2.commit` | one `completeAttempt` or `failAttempt` store operation |
+| Core | `a2.state` | one `state()` read: snapshot-plus-tail load + reducer fold |
+| Core | `a2.snapshot` | one background batch of checkpoint writes |
+| AI | `a2.ai.control` | applying an input/work report/session-close decision and preparing its returned events |
+| AI | `a2.ai.generate` | one generation handler, including Core calls and model/SDK work |
+| AI | `a2.ai.context` | constructing model messages, including tool prompt reconstruction when uncached |
+| AI | `a2.ai.compaction` | automatic summarization or the custom compaction callback |
+| AI | `a2.ai.tool` | one durable tool handler, including application execution |
+| AI | `a2.ai.ack` | waiting for a persisted work report's canonical events and control receipt |
+
+Durations measure elapsed time, including nested work: `a2.event` contains its AI
+handler and later commit, AI handlers call Core, and `a2.state` includes reducer code.
+Acknowledgements overlap control processing; claims can cover several events,
+and snapshots run in the background. Summing spans or subtracting summed children
+does not yield exclusive Core/AI overhead. Model and application I/O is included;
+inspect its child spans for detail.
 
 Attributes arrive in two waves: **at start** (passed to `span()`) and
 **mid-span** (via `handle.setAttribute`; outcomes and counts aren't
@@ -1646,6 +2078,12 @@ alert on are all mid-span.
 | `a2.append.armed`     | `a2.append` | mid   | `false` when the scheduler arm failed and this append degraded to append-driven healing |
 | `a2.drain.outcome`    | `a2.drain`  | mid   | `settled` \| `busy` \| `stalled`                      |
 | `a2.drain.processed`  | `a2.drain`  | mid   | events processed this pass                            |
+| `a2.claim.outcome` | `a2.claim` | mid | `claimed` \| `busy` \| `settled` |
+| `a2.claim.count` | `a2.claim` | mid | number of claimed events, or zero |
+| `a2.commit.operation` | `a2.commit` | start | `complete` \| `fail` |
+| `a2.commit.index` | `a2.commit` | start | event log position |
+| `a2.commit.attempt` | `a2.commit` | start | durable 1-based attempt ordinal |
+| `a2.commit.outcome` | `a2.commit` | mid | `completed` \| `failed` \| `dead_lettered` \| `superseded` |
 | `a2.event.type`       | `a2.event`  | start | the event's type                                      |
 | `a2.event.index`      | `a2.event`  | start | log position                                          |
 | `a2.event.id`         | `a2.event`  | start | event id                                              |
@@ -1655,12 +2093,28 @@ alert on are all mid-span.
 | `a2.event.outcome`    | `a2.event`  | mid   | `processed` \| `failed` \| `dead_lettered` \| `superseded` \| `surrendered` |
 | `a2.event.aborted`    | `a2.event`  | mid   | `true` when `abortOn` fired during the run            |
 | `a2.state.reducer`    | `a2.state`  | start | the reducer's name                                    |
-| `a2.state.snapshot`   | `a2.state`  | mid   | `hit` \| `miss` \| `rejected` (schema guard discarded it) |
+| `a2.state.snapshot`   | `a2.state`  | mid   | `hit` \| `miss` \| `rejected` (schema guard discarded it) \| `memory` (served from the server's in-memory state) |
 | `a2.state.folded`     | `a2.state`  | mid   | events folded past the snapshot                       |
 | `a2.state.index`      | `a2.state`  | mid   | the frontier the returned state reflects              |
 | `a2.snapshot.reducer` | `a2.snapshot` | start | the reducer's name                                  |
 | `a2.snapshot.index`   | `a2.snapshot` | start | greatest checkpoint index in the write batch       |
 | `a2.snapshot.count`   | `a2.snapshot` | start | number of checkpoints in the write batch           |
+| `a2.ai.control.type` | `a2.ai.control` | start | `ai.control.requested` \| `ai.work.reported` \| `ai.session.closed` |
+| `a2.ai.control.id` | `a2.ai.control` | start | triggering event id |
+| `a2.ai.control.attempt` | `a2.ai.control` | start | durable 1-based attempt ordinal |
+| `a2.ai.generate.request_id` | `a2.ai.generate` | start | generation request event id |
+| `a2.ai.generate.attempt` | `a2.ai.generate` | start | durable 1-based attempt ordinal |
+| `a2.ai.context.request_id` | `a2.ai.context` | start | generation request event id |
+| `a2.ai.context.phase` | `a2.ai.context` | start | `generation` \| `refresh` \| `tool` |
+| `a2.ai.compaction.request_id` | `a2.ai.compaction` | start | generation request event id |
+| `a2.ai.compaction.generation_id` | `a2.ai.compaction` | start | generation attempt id |
+| `a2.ai.compaction.policy` | `a2.ai.compaction` | start | `automatic` \| `custom` |
+| `a2.ai.tool.request_id` | `a2.ai.tool` | start | originating generation request event id |
+| `a2.ai.tool.call_id` | `a2.ai.tool` | start | tool call id |
+| `a2.ai.tool.name` | `a2.ai.tool` | start | tool name |
+| `a2.ai.tool.attempt` | `a2.ai.tool` | start | durable 1-based attempt ordinal |
+| `a2.ai.ack.request_id` | `a2.ai.ack` | start | reporting worker event id |
+| `a2.ai.ack.report_id` | `a2.ai.ack` | start | work report event id, matching the control span's id |
 
 Drain outcomes: `settled` means nothing actionable is left; `busy` means live
 per-event claims remain; `stalled` means a caught failure needs a later retry.
@@ -1690,24 +2144,29 @@ export const scheduler = vercelQueues()
 | Option | Type | Default |
 | --- | --- | --- |
 | `topic` | `string` matching `[A-Za-z0-9_-]+` | `'a2'` |
-| `scheduledAppends` | `'deployment' \| 'deploymentless'` | `'deployment'` |
+| `deploymentId` | `string \| null` | `VERCEL_DEPLOYMENT_ID` |
 | `transport` | `QueueTransport` | lazy `@vercel/queue` client |
 | `clock` | `{ now(): Date }` | system clock |
 
-The default pins recovery watchdogs and scheduled appends to the deployment
-that publishes them. Recovery always remains pinned. Set `scheduledAppends` to
-`'deploymentless'` only when every eligible deploymentless consumer for the
-topic can decode pending tasks and validate their events. This option removes
-deployment affinity. It does not select the latest production deployment.
+`deploymentId` is passed to the Queue SDK unchanged and applies to every task,
+including recovery watchdogs. Omit it to use `VERCEL_DEPLOYMENT_ID`, pass a
+deployment ID to target that deployment, or pass `null` for deploymentless
+delivery. Publishing and consuming clients must use the same deployment scope.
+The same configured client handles sends, payload fetches, acknowledgements,
+and visibility changes. Callback contents never choose the client.
+
+Pinned tasks stay with their target deployment after another deployment is
+promoted. Deploymentless delivery lets Vercel choose an eligible consumer; it
+does not select the latest production deployment. Every eligible consumer must
+use `deploymentId: null` and remain compatible with pending tasks and session
+work.
 
 The adapter retains every task for seven days and accepts delays through six
 days, leaving the final day for delivery and retries. `transport` and `clock`
 are advanced injection seams for tests and custom delivery. An injected
-transport receives the selected deployment affinity as an optional fourth send
-argument while its message remains an exact `SchedulerTask`. It must honor that
-hint for `scheduledAppends: 'deploymentless'` to affect its provider-specific
-routing. The built-in transport adds its callback-routing metadata only after
-this injection seam.
+transport receives the topic, an exact `SchedulerTask`, and send options.
+`deploymentId` configures the built-in Queue SDK client only; an injected
+transport owns its provider configuration.
 
 ## `experimental-a2/scheduler-qstash`
 
@@ -1802,8 +2261,8 @@ scheduler work. A signed malformed envelope returns 489 with
 `Upstash-NonRetryable-Error: true`. The same non-retryable response applies
 when the declared or streamed body exceeds `maxBodyBytes`. Before an initial
 publish, the adapter checks the normalized task with enough reserved room for
-its largest possible private store-outage lineage. Append tasks reserve a
-maximum safe-integer generation. Drain tasks also reserve their actual root
+its largest possible private store-outage lineage. Append and clear tasks
+reserve a maximum safe-integer generation. Drain tasks also reserve their actual root
 `dueAt`. Store-outage successors check their actual body. The adapter therefore
 cannot initially accept a task that would exceed the same limit solely when
 lineage is added. Raise the option to match a larger paid-plan payload limit
@@ -1835,15 +2294,16 @@ edge-access check.
 Settled deliveries return 200. Busy deliveries await a durable successor
 watchdog before returning 200. Stalled deliveries publish a fresh successor
 before returning 200, which resets the per-message retry budget. A retryable
-store outage also hands both drain and append tasks to a fresh successor before
-acknowledging. Store-outage successors wait 30 seconds, then multiply the delay
+store outage also hands drain, append, and clear tasks to a fresh successor
+before acknowledging. Store-outage successors wait 30 seconds, then multiply the delay
 by four for each signed generation, capped at one day. Their generation keeps
 increasing after the cap so each handoff has a new deduplication id. Drain
-lineage includes the first failing task's `dueAt`, contract, and session. Append
-lineage includes its task id, contract, and session. Duplicate delivery of one
+lineage includes the first failing task's `dueAt`, contract, and session.
+Append and clear lineage includes the task id, contract, and session. Duplicate delivery of one
 generation therefore publishes the same successor key without merging a later
 drain episode. Append tasks otherwise return 200 after their ordinary fixed-id
 append succeeds and any recovery watchdog for pending handler work is durable.
+Clear tasks return 200 after their conditional clear and its deletion finish.
 Unknown contracts, missing scheduler configuration, schema failures, and
 successor publish failures keep the current delivery retryable. Delivery is at
 least once, so handler side effects still need idempotency keys.
@@ -1879,8 +2339,10 @@ the original error object.
 | `experimental-a2/server`          | `createServer`: implement a contract      | none     |
 | `experimental-a2/client`          | `createClient`: framework-agnostic session client | none |
 | `experimental-a2/react`           | `createReact`                      | `react`         |
-| `experimental-a2/ai`              | agent contract, `handlerContext`, reducer, and append builders: isomorphic | `ai` |
-| `experimental-a2/ai/server`       | AI SDK runner and built-in handlers | `ai`           |
+| `experimental-a2/ai`              | `agentContract`, `handlerContext`, `inputs`, and the AI reducer: isomorphic | `ai` |
+| `experimental-a2/ai/server`       | `agent`: the AI SDK runner as an A2 server | `ai`           |
+| `experimental-a2/ai/client`       | `createAgentClient`: contract-free agent client | `ai`   |
+| `experimental-a2/ai/react`        | `useAgent`                         | `ai`, `react`   |
 | `experimental-a2/store-postgres`    | `postgres`: Postgres store backend   | `pg` (or inject a client) |
 | `experimental-a2/store-redis`       | `redis`: Redis Streams store backend, push-native streaming | `ioredis` (or inject a client) |
 | `experimental-a2/store-redis-http`  | `redisHttp`: the same Redis store over provider REST APIs (Upstash) | none |