experimental-a2 0.16.1 → 0.18.0

package/docs/reference/01-api.mdx

@@ -1,1896 +0,0 @@
----
-title: API
-description: "The whole surface, small enough to read in one sitting: contract, server, session, reducer, and the React and HTTP helpers."
----
-
-## `experimental-a2`
-
-### `a2.contract(options)`
-
-```ts
-a2.contract(options: {
-  name: string
-  events: Record<string, StandardSchemaV1>
-  presence?: Record<string, StandardSchemaV1>
-}): 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
-implements it, reducers derive from it, the browser types its pushes off it.
-See [Contracts and sessions](/concepts/contracts).
-
-`presence` is the optional second vocabulary: each key a field of one
-participant's ephemeral state, each value its schema. Presence fields are
-replicated last-writer-wins and never stored in the log; reducers cannot
-see them. See [Presence](/guides/presence).
-
-Schemas are [Standard Schema](https://standardschema.dev): Zod, Valibot,
-ArkType, anything that implements it. Validators must be synchronous
-(async ones are rejected here, at definition time), and the validated
-output is what's stored.
-
-### `contract.batch(...events)`
-
-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)`
-
-```ts
-contract.reducer(options: {
-  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
-fixes the state and event types, so `.fold()` receives fully concrete
-ones. Literal unions in your state survive, with zero annotations.
-
-The name is the reducer's identity; it keys cached snapshots, so rename it
-when the fold's logic changes. Two reducers never fight over a cache
-entry, and a rename (or a `stateSchema` mismatch, when present)
-invalidates, and the next read refolds from raw events. See
-[Reading state](/concepts/state).
-
-### `A2Error`
-
-The shared base for A2 failures, discriminated by `code`. The session
-client exposes its `A2ClientError` subclass. See
-[Errors](/reference/errors).
-
-### `idempotentId(...parts)`
-
-`idempotentId(...parts: string[]): Promise<string>` derives a stable UUIDv8
-from an ordered tuple of strings. It runs on the server and in the browser.
-
-```ts shared/request-id.ts
-import { idempotentId } from 'experimental-a2'
-
-export const id = await idempotentId('orders', 'shop-7', 'request-42')
-```
-
-Pass the result as an event's `id` when retries should converge on the same
-event. The same tuple produces the same ID across runtimes and A2 versions.
-String boundaries, order, and case matter; strings are not normalized.
-Empty strings and an empty tuple are valid inputs.
-
-Every argument has the same role. A prefix such as `'orders'` is a namespace
-by convention. Include enough context to distinguish operations across
-contracts and sessions, since event IDs are globally unique within a store.
-
-The helper performs no I/O. A2 preserves explicit IDs and keeps its automatic
-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.
-
-## `experimental-a2/server`
-
-### `handler(entry)`
-
-Define handlers inline in `createServer({ handlers })` for ordinary use.
-Use this helper when composing an existing handler.
-
-Accepts a handler function or an object with `handler` and optional `lane` and
-`abortOn`. Returns the object shape: a function becomes `{ handler: entry }`,
-and an object is returned unchanged. The original function and object types
-are preserved. Use it to compose an existing handler without branching on its
-shape.
-
-```ts server/composed-orders.ts
-import * as a2 from 'experimental-a2'
-import { createServer, handler, type HandlerContext } from 'experimental-a2/server'
-import { z } from 'zod'
-
-const orders = a2.contract({
-  name: 'composed-orders',
-  events: {
-    created: z.object({ shopId: z.string() }),
-    notified: z.object({ shopId: z.string() }),
-  },
-})
-
-const created = handler({
-  lane: 'orders',
-  handler: async (ctx: HandlerContext<typeof orders.events, 'created'>) => {
-    return orders.batch({ type: 'notified', payload: ctx.event.payload })
-  },
-})
-
-export const ordersServer = createServer({
-  contract: orders,
-  handlers: {
-    created: {
-      ...created,
-      handler: async (ctx) => {
-        const result = await created.handler(ctx)
-        // Your additional work goes here:
-        // await notifyShop(ctx.event.payload, { idempotencyKey: ctx.event.id })
-        return result
-      },
-    },
-  },
-})
-```
-
-Spreading the object preserves its `lane` and `abortOn`. Set either property
-after the spread to override it. Changing a built-in AI handler's lane can
-separate it from the handlers it coordinates with.
-
-Composition runs in one handler attempt. Work after the original function
-resolves still runs before its returned events commit. A thrown error fails
-the composed attempt; on retry, the wrapper and original handler can run again.
-For a new handler, annotate its context as above or pass an already typed
-function. `handler` does not bind a handler to a contract;
-`createServer({ handlers })` checks that it matches the contract.
-
-### `createServer(options)`
-
-```ts
-createServer(options: {
-  contract: Contract // the vocabulary this server implements
-  store?: A2Store    // default: sqlite in dev, memory in tests, required in prod
-  scheduler?: A2Scheduler
-  telemetry?: A2Telemetry // optional instrumentation; see experimental-a2/otel
-  presence?: { ttlMs?: number } // presence expiry policy; default 60s
-  handlers?: {
-    [type]:
-      | Handler
-      | {
-          abortOn?: AbortSpec
-          lane?: string | ((ctx: LaneContext) => string)
-          handler: Handler
-        }
-  }
-}): A2Server
-
-type Handler = (
-  ctx: Context,
-) => Promise<void | AppendInput | readonly AppendInput[]>
-```
-
-Implements a contract: binds the vocabulary to storage and reactions.
-Handlers are one table, complete at construction, so a handler can never
-be silently missing because the module that registered it wasn't
-imported. Compose across files by spreading objects into `handlers`
-(note: a duplicate key under spread silently last-wins).
-
-Handlers are concurrent by default. A2 starts every eligible event after its
-append commits. Add `lane` when events share a resource and must not overlap.
-Within one session, events with the same lane value run one at a time in log
-order. Different lanes and events without a lane run concurrently. A lane
-resolver receives `{ sessionId, event }`; A2 resolves and stores the value when
-the event is appended, so a later deployment cannot reinterpret pending work.
-For example, `lane: ({ event }) => event.payload.warehouseId` serializes work
-per warehouse while different warehouses continue concurrently.
-
-Handlers can return one event or an array. A2 marks the triggering event
-processed and appends the returned batch in one atomic store operation. Returned
-events do not exist when the handler throws. `ctx.session.append(name, ...events)`
-is different: it commits immediately, so its events may run while the current
-handler is still active unless a lane orders them.
-`ctx.session.schedule(name, timing, ...events)` waits for provider acceptance;
-its events append later and are not part of the parent completion transaction.
-
-Handlers are optional per event type. An event type without one settles in
-the append transaction with no dispatch attempt. If the session has no older
-pending handler work, A2 starts no drain or scheduler arm. A server with no
-handlers is a durable event log with no reaction infrastructure. See
-[Events without handlers](/concepts/handlers#events-without-handlers).
-
-Server-only by construction: `experimental-a2/server` is the only entry point that
-can reach a store backend, and its exports map resolves to a loud error
-under the browser condition.
-
-`presence.ttlMs` sets how long a presence value survives without a
-refreshing set (default 60 seconds, as a positive integer of
-milliseconds). Expiry counts on the storage's own clock, never on the
-sender's stamp. The option is valid only on contracts that declare
-`presence`; anywhere else construction throws a `TypeError`.
-
-`abortOn` names the events that fire `ctx.signal` while a handler runs.
-an array matches by type; an object takes per-type predicates for
-targeted cancellation:
-
-```ts
-generate: {
-  abortOn: {
-    cancelled: (event, trigger, { attempt }) =>
-      event.payload.of === `${trigger.id}:${attempt}`,
-  },
-  handler: async (ctx) => { /* ... */ },
-}
-```
-
-The predicate's third argument contains the triggering event's durable
-`attempt`, so a cancellation can fence a specific recovered run.
-
-The context every handler receives:
-
-| Property      | Type                                                      |
-| ------------- | --------------------------------------------------------- |
-| `ctx.event`   | `Event`: the triggering event                             |
-| `ctx.attempt` | durable 1-based dispatch claim ordinal                    |
-| `ctx.session` | this session's `id`, `append`, `schedule`, `history`, `state`, `stream`, `setPresence` |
-| `ctx.signal`  | `AbortSignal`: fires on lease lapse (`CLAIM_EXPIRED`), proven supersession (`SUPERSEDED_ATTEMPT`), and matching `abortOn` events |
-
-`ctx.attempt` starts at `1` and increments on every durable claim. It may skip
-when a process dies before handler entry.
-
-`ctx.session.id` equals `ctx.event.sessionId`. Its `history`, `state`, and
-`stream` methods share the session surface returned by `server.session(id)`,
-with one causal default: `ctx.session.state(reducer)` folds through the
-triggering event's index. The same event sees the same state across concurrent
-appends and retries. Ask for `{ through: 'latest' }` when a handler intentionally
-needs the committed frontier captured when that read runs.
-
-The handler-local append is specialized:
-
-```ts
-ctx.session.append(name: string, ...events: AppendInput[]): Promise<Event[]>
-```
-
-The name is an idempotency key scoped to the triggering event for events whose
-`id` is omitted. A2 derives each omitted id from the trigger id, name, and event
-position. The same name and generated-id batch returns the existing rows
-across retries. Changing that batch conflicts with those rows. An explicit
-event `id` wins over the generated id, which lets different triggering events
-converge on one fact. A root `server.session(id).append(...events)` takes no
-name.
-
-`ctx.session.schedule(name, timing, ...events)` includes the triggering event
-in its stable task identity. A relative delay is anchored to that event's
-durable `createdAt`, so a handler retry keeps the same delivery time. The call
-returns `Promise<void>` after the configured scheduler accepts the task.
-
-A latest state read and following append are not atomic. Concurrent appends and
-retries may move the frontier between them. A generic join should read with
-`{ through: 'latest' }`, use a monotone readiness predicate, and give its output
-a stable explicit event `id`, so every eligible attempt converges on the same
-append.
-
-### `server.fetch(request, options?)`
-
-```ts
-server.fetch(
-  request: Request,
-  options?: {
-    authorize?: (operation: A2Operation) => boolean | Promise<boolean>
-    upgradeWebSocket?: (
-      attach: (socket: A2Socket) => void,
-    ) => Response | Promise<Response>
-    multiplexWebSocket?: boolean
-  },
-): Promise<Response>
-
-type A2Operation =
-  | {
-      type: 'stream'
-      sessionId: string
-      startAfter: number
-      transport: 'http' | 'websocket'
-    }
-  | {
-      type: 'history'
-      sessionId: string
-      gte: number
-      lte: number
-      transport: 'http'
-    }
-  | {
-      type: 'push'
-      sessionId: string
-      events: readonly {
-        type: ContractEventType | string
-        payload: unknown
-        id?: string
-      }[]
-      presence?: {
-        participant: string
-        values: Readonly<Record<string, unknown>>
-        seen?: number
-        at?: number
-      }
-      transport: 'http' | 'websocket'
-    }
-```
-
-The bound Fetch API route for this server. An unprotected route can export it
-directly:
-
-```ts app/api/public-order-events/route.ts
-import { ordersServer } from '@/server/orders'
-
-export const GET = ordersServer.fetch
-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.
-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.
-
-`authorize` runs after the request or socket frame has been parsed, but before
-contract schema validation, presence validation, or I/O. Event names and
-presence field names are typed from the contract. Their unvalidated values stay
-`unknown`. Return `false` to deny the operation with `FORBIDDEN`. A thrown error
-becomes `STORE_UNAVAILABLE`, because authorization infrastructure failed rather
-than denied access. Operation objects, push events, event arrays, and presence
-patches are frozen. Authorize them, do not rewrite them.
-
-Authentication stays outside A2, where the route can read headers, cookies, and
-framework context. Capture the authenticated principal in `authorize`:
-
-```ts app/api/protected-order-events/route.ts
-import { ordersServer } from '@/server/orders'
-
-async function fetchOrders(request: Request): Promise<Response> {
-  // your authentication:
-  const user = { id: 'user-1' }
-  if (!user) return new Response(null, { status: 401 })
-
-  return ordersServer.fetch(request, {
-    authorize(operation) {
-      // your per-session and per-operation authorization:
-      // return canAccess(user, operation)
-      return true
-    },
-  })
-}
-
-export const GET = fetchOrders
-export const POST = fetchOrders
-```
-
-Direct `session.append`, handler appends, scheduled appends, and server-side
-`setPresence` bypass `authorize`. It is an ingress policy for this fetch call,
-not a global server policy.
-
-A GET with `Upgrade: websocket` uses `upgradeWebSocket`. Without that option it
-returns 426. The upgrade function receives an `attach` callback for the
-platform socket:
-
-```ts app/api/socket-order-events/route.ts
-import { experimental_upgradeWebSocket } from '@vercel/functions'
-import { ordersServer } from '@/server/orders'
-
-export const POST = ordersServer.fetch
-
-export function GET(request: Request): Promise<Response> {
-  return ordersServer.fetch(request, {
-    upgradeWebSocket: (attach) =>
-      experimental_upgradeWebSocket(attach, {
-        maxPayload: 4 * 1024 * 1024,
-      }),
-  })
-}
-```
-
-By default, the `sessionId` and `index` query parameters bind one session to the
-socket. A2 authorizes the stream before upgrading. Frames on that socket cannot
-select another session.
-
-Set `multiplexWebSocket: true` here and `multiplex: true` in the client's `ws`
-API to share one socket.
-Authenticate the physical WebSocket GET before calling `server.fetch`. Validate
-`Origin` too when browser cookies authenticate it; WebSocket handshakes do not
-use a CORS preflight. Use `authorize` for each session subscribe and each event
-or presence push. Only enable multiplexing when that request context may access
-every session accepted by `authorize`. A denied subscribe receives
-`unsubscribed` and does not affect other sessions. A denied event push receives
-a `FORBIDDEN` ack. Denied presence is silently dropped because it is
-fire-and-forget.
-
-SSE and WebSocket lifetimes use the platform's ambient invocation deadline.
-A2 also uses the platform's ambient `waitUntil` capability for background work.
-Neither capability is reordered or passed through `server.fetch` options.
-
-### `server.session(id)`
-
-```ts
-server.session(id: string): Session
-```
-
-A handle on one instance of the contract. The session is the unit of log
-ordering, lane keys, recovery, state, and live sync. Handler execution is
-concurrent unless events share a lane. Creating the handle does no I/O;
-nothing loads until you append, read, or stream.
-
-```ts
-const session = server.session('order-42')
-
-session.id
-session.append(...events)
-session.schedule('expire-order', { delay: '5d' }, {
-  type: 'expired',
-  payload: {},
-})
-session.history({ gte, lte })
-session.state(reducer)
-session.stream({ startAfter })
-```
-
-`session.id` is the id passed to `server.session(id)`. Root `append` takes only
-events. The handler-local form at `ctx.session.append` adds its required name
-before the events. Both root and handler sessions expose `schedule`.
-
-### `server.drain(sessionId)`
-
-```ts
-server.drain(sessionId: string): Promise<{ settled: boolean }>
-```
-
-Claims every currently eligible event and runs their handlers concurrently.
-`settled` means no actionable or live-claimed work remains. A dead-lettered
-event can leave later work in its lane blocked while other lanes continue.
-You'll rarely call this yourself; it is the primitive scheduler callbacks use.
-The public result stays this simple boolean.
-
-### `A2Store`
-
-Custom adapters implement these atomic drain methods:
-
-```ts
-// Custom server store adapter:
-type EventCause = {
-  index: number
-  attempt: number
-  batchSize?: number // present on named handler appends
-}
-
-type AppendEvent = {
-  type: string
-  payload: unknown
-  id?: string
-  cause?: EventCause
-  lane?: string
-  settled?: true // internal: no handler is registered for this event type
-}
-
-type ReturnedEvent = AppendEvent & { id: string }
-
-type StoredEvent = Event & {
-  cause: EventCause | null
-  lane: string | null
-  processedAt: Date | null
-  processedByAttempt: number | null
-  returnedEventIds: string[] | null
-  firstClaimedAt: Date | null
-  lastClaimedAt: Date | null
-  attemptCount: number
-  claimHolder: string | null
-  claimExpiresAt: Date | null
-  failureCount: number
-  lastFailedAt: Date | null
-  lastFailedAttempt: number | null
-  lastError: string | null
-  failedAt: Date | null
-}
-
-type StoreAppendResult = {
-  events: StoredEvent[]
-  hasPending: boolean
-}
-
-type StoreClaimAvailableResult =
-  | { outcome: 'claimed'; events: StoredEvent[] }
-  | { outcome: 'busy'; retryAt: Date }
-  | { outcome: 'settled' }
-
-type CompleteAttemptResult =
-  | { outcome: 'completed'; events: StoredEvent[] }
-  | { outcome: 'superseded' }
-
-interface A2Store {
-  append(
-    sessionId: string,
-    events: AppendEvent[],
-  ): Promise<StoreAppendResult>
-
-  claimAvailable(options: {
-    sessionId: string
-    holder: string
-    ttlMs: number
-    expiresAtMs?: number
-    excludeIndexes?: readonly number[]
-  }): Promise<StoreClaimAvailableResult>
-
-  renewClaims(options: {
-    sessionId: string
-    holder: string
-    claims: readonly { index: number; attempt: number }[]
-    ttlMs: number
-    expiresAtMs?: number
-  }): Promise<{ renewed: number[]; superseded: number[] }>
-
-  completeAttempt(options: {
-    sessionId: string
-    index: number
-    attempt: number
-    events: ReturnedEvent[]
-  }): Promise<CompleteAttemptResult>
-
-  failAttempt(options: {
-    sessionId: string
-    index: number
-    attempt: number
-    error: string
-    maxFailures: number
-  }): Promise<{
-    outcome: 'failed' | 'dead_lettered' | 'superseded'
-    failureCount: number
-  }>
-}
-```
-
-| Method | Atomic effect |
-| --- | --- |
-| `append` | Write a consecutive batch. Events carrying core's internal `settled` flag receive `processedAt` in the same transaction, with no dispatch attempt. An event carrying `cause` is fenced by attempt currency: it commits only while `cause.attempt` is still the parent's latest attempt and the parent is not dead-lettered, throwing `SUPERSEDED_ATTEMPT` otherwise (the check serializes against a concurrent claim; the idempotent-replay path runs first). |
-| `claimAvailable` | Claim every eligible event. All unlaned events are independent; only the lowest-index unfinished event in each lane is eligible. A claim records its holder, expiry, timestamps, and next `attemptCount`. |
-| `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`. |
-
-`attemptCount` counts claims, including abandoned ones. `failureCount` counts
-caught failures and dead-letters at ten. See
-[Durability](/concepts/durability#one-event-many-attempts) for the recovery
-model. `cause` identifies the event and handler attempt whose
-`ctx.session.append` or return value first persisted the child. A null cause
-means a top-level event.
-`lane` is the session-scoped serialized group resolved before append.
-`returnedEventIds` makes a lost completion
-acknowledgment recoverable without accepting a partial child batch. Lifecycle
-timestamps are adapter clock values for their atomic store operations, not exact
-database commit times.
-Built-in adapters persist these fields inside their existing atomic operations,
-with no extra backend round trip.
-
-### `A2Scheduler`
-
-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 |
-
-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`.
-
-| 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` |
-| `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`.
-
-Custom adapters deliver an authenticated, normalized append task through the
-server helper:
-
-```ts custom-scheduler.ts
-import {
-  deliverSchedulerAppend,
-  type DrainableServer,
-  type SchedulerAppendTask,
-} from 'experimental-a2/server'
-
-export async function deliver(
-  server: DrainableServer,
-  task: SchedulerAppendTask,
-) {
-  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.
-
-## Session
-
-### `session.append(...events)`
-
-```ts
-session.append(
-  ...events: Array<{ type: string; payload: unknown; id?: string }>
-): Promise<Event[]>
-```
-
-The only way to move a session forward. Payloads are validated against
-the contract's schemas before anything is written. A multi-event append
-is atomic: all-or-nothing, consecutive positions, one transaction. Pass
-`id` to make an append idempotent across retries; re-sending an
-identical batch returns the original rows. (Events that arrived through
-`server.fetch`'s push lane are accepted directly.) See
-[Durability](/concepts/durability).
-
-After the write, A2 dispatches only event types with registered handlers.
-Other event types are already settled by the append itself. An unhandled
-append still starts session healing when older handled work is pending. The
-store reports that session-wide pending state as part of the atomic append, so
-this decision needs no follow-up read.
-
-### `session.append.dispatch(...events)`
-
-```ts
-session.append.dispatch(
-  ...events: Array<{ type: string; payload: unknown; id?: string }>
-): Promise<Event[]>
-```
-
-Commits the same atomic batch, but sends pending work directly to configured
-scheduler instead of starting an inline drain. The call awaits acceptance of an
-immediate scheduler message. It throws before writing if the server has no
-scheduler adapter.
-
-If the queue send fails, the events are already durable. Give them explicit
-IDs and retry the same dispatch safely. A batch that leaves no pending handler
-work does not send a scheduler message. Dispatch chooses how this append wakes
-the session; it does not reserve events for one worker. A drain that is already
-active may still claim newly eligible work first.
-
-`dispatch` exists only on a server session's top-level append. Handler-scoped
-`ctx.session.append(name, ...events)` already runs inside an active drain and
-does not expose `dispatch`. Its immediate children and atomically returned
-children become eligible in that drain.
-
-### `session.schedule(name, timing, ...events)`
-
-`schedule` returns `Promise<void>` and is available on both root and handler
-sessions. `name` must be non-empty. At least one event is required.
-`ScheduleDelay`, `ScheduleTiming`, and `SessionSchedule` are exported from
-`experimental-a2/server`.
-
-| Timing | Meaning |
-| --- | --- |
-| `{ delay: '30s' }` | relative delay with unit `ms`, `s`, `m`, `h`, or `d` |
-| `{ at: Date }` | absolute delivery time |
-
-The template type checks the unit suffix. At runtime, the delay number must be
-an unsigned base-10 decimal without leading zeros, finite, and greater than
-zero. `0s`, signs, exponent notation, malformed durations, invalid dates, and
-objects containing both timing fields are rejected. A root relative delay
-starts from that call's wall clock. A handler relative delay starts from the
-triggering event's durable `createdAt`, so retries preserve its delivery time.
-Use `{ at }` when a retried root call needs one target time. The requested
-target is the earliest useful delivery time. Adapters encode provider timing
-in whole-second slots. An already-due target is sent immediately.
-
-The stable task id derives from the contract, session, and name. Handler tasks
-also include the triggering event id. Omitted event ids derive from that task
-id and event position; explicit ids win. Reuse a name only for an identical
-timing and event batch. Provider deduplication is an optimization. Stable event
-ids make later duplicate deliveries converge in the store.
-
-A2 snapshots payloads into plain JSON trees, then validates the event schemas
-before sending. Encode dates as ISO strings and custom classes as plain data;
-values such as `undefined`, bigint, functions, symbols, cycles, accessors, and
-non-plain prototypes are rejected. The promise resolves after provider
-acceptance, not after append. Shared object references become independent JSON
-values. The task carries the snapshotted JSON schema input. At delivery, the
-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.
-
-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.history()`
-
-```ts
-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.
-
-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
-uses one indexed range query selecting only public event columns. Custom store
-adapters can implement `readHistory(sessionId, options)` with the same exclusive
-`afterIndex` and inclusive `throughIndex` bounds as `read()`. A2 falls back to
-`read()` when that capability is absent.
-
-### `session.state(reducer, options?)`
-
-```ts
-session.state(
-  reducer: Reducer<S>,
-  options?: { through?: number | 'latest' },
-): Promise<{ state: S; index: number }>
-```
-
-The log folded through one committed prefix. `index` is its exact boundary,
-an append-order cursor rather than a handler-settlement marker. Hand it to the
-client to resume there. Snapshot write-back uses platform `waitUntil`; this
-read never dispatches handlers or waits for pending work.
-
-On a root session from `server.session(id)`, omitting `through` reads the latest
-committed frontier. On the handler-scoped `ctx.session`, omitting it reads
-through `ctx.event.index`. That boundary is inclusive and stable across retries.
-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.
-
-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
-other unfinished handler uses it. There are no retention options. Handler
-`{ through: 'latest' }` reads and all root reads do not retain history.
-
-If the latest snapshot is ahead of a numeric boundary, A2 can use the greatest
-eligible retained checkpoint. A root historical read never creates retention
-or writes a stale checkpoint behind the latest snapshot; it folds from the log
-when no eligible checkpoint exists.
-
-Operational snapshot-read failures preserve existing A2 errors; other errors
-become `STORE_UNAVAILABLE` with the original error as the cause. They do not retry through individual
-reads or raw history. Cache misses and `stateSchema` rejection still rebuild
-from the log. Snapshot write-back remains background work; failures are reported
-through `a2.snapshot` telemetry or the default console sink, without failing the
-completed read or attaching snapshot contents.
-
-### `session.stream(options?)`
-
-```ts
-session.stream(options?: { startAfter?: number }): AsyncIterable<Event>
-session.stream(options: {
-  startAfter?: number
-  presence: true
-}): AsyncIterable<Event | PresencePatch | PresenceSnapshot>
-```
-
-A live feed of the session's events. `startAfter` is a non-negative safe integer;
-`startAfter: 20` begins with event 21.
-Server-side only; `server.fetch` exposes it over SSE and WebSocket. Subscribing
-never dispatches handlers.
-
-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
-events. The stream response sends both as named SSE frames, so clients
-that don't know them skip them. The return type widens only under the
-literal `presence: true`; without it, existing consumers keep
-`AsyncIterable<Event>`. The option itself exists only on sessions of
-contracts that declare `presence`; elsewhere it is a type error, not a
-runtime throw. A `PresencePatch` is `{ participant, values, seen, at }`
-with `values` typed by the contract's presence schemas (`null` marks a
-cleared field).
-
-### `session.setPresence(patch)`
-
-```ts
-session.setPresence(patch: {
-  participant: string
-  values: { [field]: payload | null } // partial; null clears a field
-  seen?: number
-  at?: number // the sender's LWW stamp, epoch ms; receipt time when absent
-}): Promise<void>
-```
-
-Validates each field against the contract's `presence` schemas, then
-broadcasts. Last writer wins per participant per field, ordered by
-`at`, the sender's stamp in epoch milliseconds (the browser client
-stamps its sends automatically). When `at` is absent, receipt time
-stands in: a stampless caller is a single writer, so receipt order is
-its send order. No log row, no
-dispatch, no scheduler arm; `history()` and `state()` never see it. A
-bad payload throws `INVALID_PAYLOAD`; an unknown field throws
-`UNKNOWN_PRESENCE_FIELD`; a non-finite or negative `at` throws a
-`TypeError`. `seen` is the sender's stream frontier, the
-stamp view code uses to reconcile presence against the fold (see
-[Presence](/guides/presence#reconciling-the-planes-seen)). Values expire
-by backend TTL when a participant goes silent (default 60 seconds; set
-`createServer({ presence: { ttlMs } })` to change it). Expiry counts on
-the storage clock, not the sender stamp, so a hostile stamp can only
-vandalize its own field and still expires on schedule.
-
-The patch is structurally the `presence` sibling of the push envelope;
-`server.fetch`'s push lane forwards it whole to `session.setPresence(presence)`.
-The API mirrors the wire.
-
-The handler-scoped form `ctx.session.setPresence(...)` is the same
-operation; `seen` defaults to the triggering event's `index`.
-
-### `session.presence()`
-
-```ts
-session.presence(): Promise<{
-  [participant: string]: {
-    [field: string]: { value: unknown; seen: number; at: Date }
-  }
-}>
-```
-
-The current presence map, expired values pruned. A point-in-time read
-for server renders; live consumers use `stream({ presence: true })`.
-Each entry's `at` is the sender's stamp for when the value was set,
-the last-writer-wins comparator; how long a value stays painted is
-still view logic, decided at render time.
-
-## Event
-
-```ts
-type Event = {
-  id: string
-  type: string
-  payload: unknown // typed by the contract's schema for `type`
-  index: number // position in the session's log, from 1
-  sessionId: string
-  createdAt: Date
-}
-```
-
-## `experimental-a2/react`
-
-### `createReact(options)`
-
-```ts
-createReact(options: {
-  client: A2Client          // bind a shared client: api + reducer + session identity
-}): { SessionProvider, useSession }
-
-// or, standalone (one client per provider mount):
-createReact(options: {
-  reducer: Reducer          // types everything: state, pushes, the feed
-  cache?: A2ClientCache     // optional; see local-first
-}): { SessionProvider, useSession }
-```
-
-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).
-
-`createReact({ reducer })` 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.
-
-### `<SessionProvider>`
-
-| 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 |
-| `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
-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
-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()`
-
-```ts
-const { state, push, reconnect, events, index, loadHistory, history, connection,
-  presence, setPresence } = useSession()
-```
-
-`state` starts from the initial 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
-the latest server-confirmed state index, the `lastSeenIndex` for
-[cancellation](/guides/cancellation).
-
-`loadHistory({ before?, limit? })` backscrolls: it fetches a bounded
-slice of the log from below the frontier (the same route, `gte`/`lte`
-query parameters) and merges it into `events`, deduped, ordered, and
-shared across every handle of the session. It resolves with the events
-in the requested range. Defaults walk backward 50 at a time from the
-oldest loaded event; `before` is an exclusive upper bound. After a
-newer snapshot hydrates the session, default paging still continues from
-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`
-throws a `TypeError`.
-
-`presence` is the replicated ephemeral map,
-`Record<participantId, { [field]: { value, seen, at } }>`, including
-this client. `setPresence(values)` is fire-and-forget: validated
-locally, merged into the local map immediately, coalesced on the wire
-to a fixed cadence (a leading send immediately, then at most one
-merged send per interval; later values win per field), stamped with
-the frontier at send time as `seen`. Parallel sends are safe: merges
-are last-writer-wins by `at`, and the client's stamps are monotonic
-per session (wall-seeded, guarded so overlapping sends can never
-invert). No ack, no `confirmed`, no retry.
-
-Both members exist only when the contract declares `presence`; their
-value and field types come from its schemas, through the reducer, with
-no type arguments (the reducer is the client's typed handle on the
-contract; it still never folds presence). `setPresence` requires a
-`participant`: the client's default, or the provider's override. See
-[Presence](/guides/presence).
-
-`push` appends optimistically: validated locally, rolled back on
-rejection, retried for `STORE_UNAVAILABLE` and transport failures. Awaiting it gives the
-server ack; the same result carries `confirmed`, a lazy promise for
-the later moment when the live stream has delivered the batch back and
-the view shows server truth:
-
-```ts
-const t0 = performance.now()
-const result = push({ type: 'created', payload })
-await result // the server ack: push→ack latency
-await result.confirmed // the stream round-trip: ack→stream latency
-const roundtripMs = performance.now() - t0
-```
-
-Overlapping calls through the same session client update the view
-immediately, then enter the transport in invocation order. Each call waits
-only for the previous call's ack or final rejection, not for `confirmed`.
-Other session IDs and clients remain concurrent; they converge on the log's
-durable order.
-
-A rejected push rejects both promises with the same `A2ClientError`;
-`confirmed` is materialized only when accessed, so ignoring it costs
-nothing. It also reads as intent: `await push(...).confirmed` is
-"continue once this is server truth".
-
-`session.reconnect(): void` immediately restarts a leased subscription,
-including one paused by the reconnection policy,
-from its current cursor. It preserves state, pending writes, and leases, and
-does nothing without an active lease. The React `useSession()` result exposes
-the same `reconnect` function. Use it after a custom REST mutation; it requests
-a restart rather than returning a promise for catch-up completion. A
-multiplexed WebSocket keeps its physical socket and other session lanes;
-a single-session WebSocket replaces its socket.
-
-`connection` is a discriminated union; impossible states are
-unrepresentable (an `error` only exists while disconnected):
-
-```ts
-// in a client module:
-import type { A2ClientError } from 'experimental-a2/client'
-
-type Connection =
-  | { status: 'idle' }
-  | { status: 'connecting'; reconnects: number; error: A2ClientError | null }
-  | { status: 'paused'; reconnects: number; error: A2ClientError | null }
-  | { status: 'live'; reconnects: number }
-  | { status: 'closed' }
-```
-
-"Reconnecting…" is `status === 'connecting' && reconnects > 0`. And
-it's honest about silence: the server heartbeats the stream (`: ping`
-every 15s), and a client that hears nothing for two beats treats the
-connection as dead (aborts it and reconnects), so `live` means bytes
-are actually flowing, not "the socket hasn't errored yet". See
-[Live UI](/guides/react).
-
-### `useSession(client, sessionId, options?)`
-
-```ts
-useSession(client: A2Client, sessionId: string, options?: {
-  participant?: string // overrides the client's participant
-  hydrate?: { state: S; index: number }
-}): UseSessionResult
-```
-
-The standalone, provider-less hook. It returns the same result shape
-as the bound hook, for apps whose components reach sessions ad hoc (a
-sidebar of channel sessions, a user session read from a menu). The
-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).
-
-## `experimental-a2/ai`
-
-### `agent(options)`
-
-```ts
-agent(options: {
-  name: string
-  events?: Record<string, StandardSchemaV1>
-  messageSchema?: StandardSchemaV1<UIMessage>
-  reducerName?: string
-}): AgentDefinition
-```
-
-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`.
-
-Built-in event names cannot be replaced by `options.events`.
-
-### `handlerContext(agent)`
-
-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`.
-
-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.
-
-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
-provider-executed tool. Each retry reads that attempt's fresh context.
-Model-phase tool options (`contextSchema`, dynamic descriptions,
-`needsApproval` predicates, input lifecycle callbacks) are the AI SDK's
-own; A2 forwards them untouched, and durable execution passes no AI SDK
-`context` option. `needsApproval` and `generation.toolApproval`
-predicates run during the model step and are re-evaluated on recovery
-for the same durable tool call, so keep them deterministic over the tool
-input. Model-phase hooks see tool definitions without local `execute`
-functions.
-
-### `inputs`
-
-Pure typed inputs for `append()` and `push()`:
-
-| Input | Events |
-| --- | --- |
-| `inputs.message(message, { generate? })` | queues input; `generate: false` records passive context at admission |
-| `inputs.seed(message)` | queues passive context; non-user roles require a trusted append |
-| `inputs.approval(response)` | answers a pending tool approval |
-| `inputs.input(response)` | answers a pending application input |
-| `inputs.requestInput(request)` | requests application input from trusted server code |
-| `inputs.retry(options)` | retries a failed response |
-| `inputs.stop({ turnId, lastSeenIndex? })` | ends the observed turn and advances when admission is open |
-| `inputs.steer({ turnId, message, lastSeenIndex? })` | puts the new input first for a handoff after the observed turn's current step |
-| `inputs.queue.edit({ message })` | changes a pending input; its ID stays fixed |
-| `inputs.queue.move({ inputId, beforeId })` | moves pending input before an ID; `null` means the end |
-| `inputs.queue.remove({ inputId })` | removes pending input; its submission stays in the log |
-| `inputs.queue.sendNow({ inputId, turnId, lastSeenIndex? })` | promotes an existing queued input for a handoff after the current step; preserves pause |
-| `inputs.pause({ when: 'now' \| 'after-turn' })` | pauses execution now or inbox admission after the turn |
-| `inputs.resume()` | resumes retained work, then inbox admission |
-| `inputs.toolResult(result)` | records a deferred provider-executed tool result from trusted server code |
-| `inputs.interrupt(options)` | interrupts a specific generation/request owner |
-
-Edits are last-write-wins in session log order and preserve the pending message's
-identity and role. They require no revision or confirmation before another edit.
-Admission freezes the message; subsequent edits return `not-pending`.
-
-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.
-
-Steering validates and prioritizes new input even if the observed turn has
-finished. A matching active turn finishes its current model response and tool
-batch, then yields before another model step. Running local workers and deferred
-provider results settle first; unanswered human approval/input waits can be
-closed at that point. Pause stays closed. Otherwise the input starts when idle
-or waits first behind a different active turn. The priority change is atomic;
-the later handoff and new work are committed atomically at the step boundary.
-Steer and Send now do not use `lastSeenIndex` to cut output.
-
-Queue removal leaves the original submission in the log, so replay does not recreate the input.
-Send now preserves the queued input ID and latest accepted content. It requires
-an observed `turnId` (or null for idle), preserves pause, and only accepts
-user-role input. It promotes passive user input to generation. Missing targets
-and stale turns reject before any queue change.
-
-`state.inbox` contains `paused` and ordered `items`. Each item contains
-`{ id, message, generate, afterStepOf? }`. The optional turn ID
-`afterStepOf` records the observed steering turn while that item remains queued;
-a matching active turn hands off after its current step.
-Removal cancels it and admission consumes it. `state.active` is null or contains
-`{ turnId, input, phase }`; admission freezes `input`. On the server, pending
-inputs are absent from `messages` and model context. The `paused` status and the `pausing`/`paused`
-active phases represent retained work. Resume uses a fresh model request and
-execution version. Tools without terminal outcomes can retry; their stable
-`toolCallId` supports external idempotency.
-
-`inputs` deliberately has no session lifecycle methods. Append explicit
-`ai.session.created` and `ai.session.closed` events from trusted server code
-when an application uses them. Message, seed, and steering builders set the event ID to the input message ID.
-The two IDs must match for all new-input commands. Caller command/input IDs must
-be nonempty and cannot use the reserved `a2.ai:` prefix. Identical events replay;
-conflicting ID reuse rejects before append under core deduplication rules. IDs
-are unique across the store, including different contracts and sessions.
-Approval, input-response, and retry builders use stable interaction IDs.
-Other commands use IDs assigned by `push()` or `append()`; transport retries
-preserve those IDs. Browser
-ingress accepts user messages, approval and input responses, interruptions,
-and explicit retries. Only built-in server handlers append generation requests
-and AI lifecycle events. `inputs.requestInput()`, `inputs.toolResult()`, and non-user messages built
-with `inputs.seed()` are for trusted server appends.
-
-`inputs.message(message, { generate: false })` is valid browser input. It admits
-the user message to `AIState.messages` without starting a model turn. The next
-user message that allows generation includes passive user messages before it
-in model context. Passive user messages after that trigger wait for a later
-generating message. Omitting the option preserves the default scheduling
-behavior. `inputs.seed()` writes
-the same passive flag. Trusted assistant and system seeds are context, not user
-queue cutpoints. The server never schedules them, regardless of the `generate`
-field. Model output is generation progress rather than another
-`ai.message.created` fact, so an assistant response cannot recursively start a
-new turn.
-
-Approval and input request/response payloads require the active
-`requestId` and `generationId`. Clients copy both from the pending request, which prevents a
-delayed response from satisfying a newer model step.
-
-`ai.retry.requested` carries `{ messageId, responseMessageId, retryId }`.
-`retryId` identifies one user action. The server converts the fact into an
-`ai.generation.requested` whose reason is `retry`.
-Retry reruns the failed model call while retaining earlier completed model steps,
-their tool results, and committed compactions, including steps completed after
-the latest compaction.
-The failed model call's uncommitted step is removed from the active prompt and
-response. Conversation forks and edit-and-resend flows for admitted messages are
-application-owned.
-
-A2-generated requests, generations, assistant responses, worker jobs, reports,
-and lifecycle events have fixed-length deterministic IDs in the reserved
-`a2.ai:` namespace. An assistant message's ID equals its initial model-request
-event ID. Control state keeps no lifetime input/response-ID registry. IDs are opaque;
-ownership is carried by event fields. `ai.generation.requested` requires
-`responseMessageId`; a tool continuation also requires `sourceGenerationId`.
-
-`ai.generation.failed` sets `stepLimit: true` when `maxSteps` rejects a
-continuation before another model step starts.
-
-`ai.message.interrupted` carries either `{ messageId, requestId, reason?,
-lastSeenIndex? }` or `{ messageId, generationId, reason?, lastSeenIndex? }`.
-Exactly one owner ID is required. Clients copy `requestId` from
-`activeRequestId` before generation start and switch to the observed
-`activeGeneration.generationId` after start. A request-owned interruption
-remains valid if that same request starts before the append commits. A delayed
-interruption for an older owner is a projection and cancellation no-op.
-The message and owner IDs are validated as one pair. If either ID does not
-identify that same response owner, the interruption is stale and is a no-op.
-
-An accepted interruption terminally fences its request or generation. Later
-generation, tool, approval, input, and compaction events remain in raw history
-but cannot alter `AIState`, satisfy pending work, or reactivate the response.
-Completed tool results at or before `lastSeenIndex` remain completed. A final
-tool result that races an ordinary generation failure remains authoritative in
-either commit order, while the generation stays failed.
-
-Interruption and failure projections discard tool parts still in
-`input-streaming`. These argument drafts are not completed tool calls and do not
-enter later model prompts. Raw progress remains in the log. Available inputs,
-approval-waiting calls, and completed results retain their existing terminal
-handling.
-
-### `events` and `createEvents(options?)`
-
-The built-in Standard Schema definitions. Use `events` for the default AI SDK
-`UIMessage`; use `createEvents({ messageSchema })` to validate a more specific
-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
-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
-indicate model execution. Confirmed turns take precedence during reconciliation.
-Steering inputs, and Send now inputs targeting an active turn, appear in
-`state.messages` after the current response and are omitted from the client
-inbox. This display survives receipt and hydration, including while paused.
-They remain pending server inputs until admission and do not enter the model
-prompt early. Multiple steering inputs follow inbox admission order.
-
-New active turn identities come from accepted control decisions. A pending Stop
-for that turn clears the displayed `state.active`, generation, and pending
-approvals/inputs, and previews an idle status (or paused when the inbox is paused). With
-`lastSeenIndex`, its retained generation projection freezes at the observed
-frontier. The preview lasts through the request echo until the controller's
-decision; rejected requests restore the confirmed active turn and output.
-Server reads and reducer folds retain confirmed messages and inbox entries;
-`state.starting` is false there. Custom reducers that call `reduceAIState()` or
-nest the AI fold do not inherit the client display behavior. Repeat editing and
-Send now remain available while earlier edits are pending. Later local edits
-stay visible through earlier commands' acknowledgments and receipts.
-
-The pending-command ledger survives request echo and retires on the matching
-`ai.control.decided` receipt or session close. Failed pushes roll back through
-the client's existing optimistic overlay. This display adds no I/O and does not
-read raw history.
-
-### `createReducer(options)`
-
-```ts
-createReducer({ contract, name?, fold?, stateSchema? }): AIStoredReducer
-```
-
-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`
-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
-`activeRequestId`, `activeRequestReason`, `activeRequestSourceGenerationId`, `activeResponseMessageId`,
-`responseOwners: Record<string, { generationId: string; requestId: string; attempt: number }>`, and terminal request and
-generation ownership fences.
-`activeRequestId` is the server-authorized generation request and fences
-delayed requests before their generation starts. `activeResponseMessageId`
-identifies the requested response until `activeGeneration` exists.
-`activeProjection` holds the indexed generation frontier while a generation is
-active, after a generation step completes while its response waits on tool,
-approval, or input barriers, while paused, and after a generation fails while it awaits retry
-or interruption. Response completion, interruption, supersession, retry, or a
-later generation clears or replaces it. `responseOwners` keeps the
-latest generation owner for each response message, so late events from a
-superseded owner cannot alter the projection. `terminalRequestIds` and
-`terminalGenerations` preserve accepted completion, failure, interruption,
-and supersession fences across snapshots and recovery. They are optional
-snapshot-compatible fields with the shapes `Record<string, true>` and
-`Record<string, 'completed' | 'failed' | 'interrupted' | 'superseded'>`.
-The active projection also stores its prompt boundary and a serializable stream
-cursor for open text, reasoning, and tool-input parts. Ordered progress applies
-only its new chunks. `activeProjection.batches` stores indexed batches as
-`{ length, tail, blocks }`: a bounded tail and shared completed blocks. Appending
-ordered progress does not copy the full retained batch list. The blocks are
-ordinary JSON with logarithmic nesting depth, so checkpoints can be serialized
-and cloned. Retained batches support exact interruption cutoffs and out-of-order
-reconstruction. The cursor and blocks share the active projection's lifetime.
-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`.
-
-### `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
-standard reducer. Both synchronously project the same chunk-only protocol.
-
-## `experimental-a2/ai/server`
-
-### `createAgentServer(options)`
-
-```ts
-createAgentServer({
-  agent: AgentDefinition,
-  model: LanguageModel | (context => LanguageModel),
-  tools?,
-  instructions?,
-  generation?,
-  maxSteps?,
-  messageMetadata?,
-  generate?,
-  compaction?,
-  progress?,
-  store?, scheduler?, telemetry?, handlers?,
-}): 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.
-
-`generation` contains per-step settings such as `temperature`,
-`maxOutputTokens`, `topP`, provider options, and tool approval policy. A2 owns
-the one-step stop condition, local tool execution, and continuation. Responses
-have no step limit by default. Set `maxSteps` to a positive integer to limit one
-complete assistant response. Support for individual model settings depends on
-the selected model and provider. `generation` excludes `stopWhen`, tool
-execution callbacks, tool callers, sandbox execution, and the tool approval
-secret. Everything else, including `toolsContext`, passes through to the AI SDK
-untouched. A local tool reads its durable context with `handlerContext()` when
-its handler executes. Model-step timeouts remain available; tool-execution
-timeouts are not.
-
-`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.
-
-`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,
-continuation, and the durable lifecycle around that stream.
-
-Generation requests use one durable lane, so model calls for a session do not
-overlap. Queued-turn policy also waits to schedule a later user message until
-the active assistant response, including its complete tool loop, reaches a
-terminal event. The policy matters in addition to lane FIFO because a tool
-continuation may be appended after the later user message. A generation
-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,
-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
-snapshot plus log tail because these joins intentionally observe concurrent
-tool results. Process memory is not authoritative. Concurrent join checks return
-the same deterministic continuation event, so they use `ctx.session.append()`
-and storage deduplicates the race.
-
-Tool results and generation completion have no fixed relative order. The
-continuation predicate needs both the closed model step and every required
-terminal result.
-
-Single-owner terminal events use returned-event causality. They commit
-atomically with parent completion and receive the parent's durable cause.
-Many-owner joins and preliminary streaming outputs use immediate idempotent
-appends. Provider calls and external tool side effects are at least once and
-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.
-
-`compaction` defaults to automatic for supported Gateway requests. It accepts
-`false` to disable compaction and discovery, `{ thresholdTokens?, instructions? }`
-to override automatic behavior, or the existing custom
-`{ shouldCompact(context), compact(context) }` policy. It also accepts a
-resolver `(context: AgentResolverContext) => CompactionOptions | Promise<CompactionOptions>`.
-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.
-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
-prompt without replacing the agent's instructions.
-
-Without an explicit threshold, the first generation batches a metadata request
-into its existing start write. An independent handler reads the public Gateway
-catalog and records that session/model's limits. It does not delay model dispatch.
-The default threshold is 75% of the context window, lowered for a larger configured
-output allowance. A pending or unavailable lookup leaves the threshold unknown;
-the first request proceeds, and provider context-limit errors fail normally.
-`state.modelMetadata` retains each model's pending, resolved, or unavailable state.
-Pending also covers exhausted handler retries; no new request is added per turn.
-The catalog has a shared one-hour process cache and a five-second fetch timeout.
-
-Direct/custom providers, fallback model lists, and custom generators need explicit
-compaction configuration. Provider-executed tools, structured output, and forced
-tool choices skip implicit compaction and reject explicit automatic policies.
-Custom policies remain available for these configurations.
-
-The raw input estimate uses serialized bytes of messages, tools, and instructions,
-excluding provider options on messages and content parts. These options still reach
-the model unchanged. It is not a provider tokenizer. A preceding same-model
-completion anchors later growth to reported input usage, correcting both overestimates
-and underestimates. A smaller prompt, retry, compaction, or model change stops
-that calibration.
-
-Completed generations record the raw `inputTokenEstimate` beside usage.
-Automatic `ai.compaction.requested` events also record the pre-compaction
-`inputTokenEstimate`, the calibrated `inputTokens` used for the decision, and
-`thresholdTokens`. Custom-policy requests omit these diagnostics. They add no
-model calls or database round trips.
-
-The built-in summary adds one model request and preserves the request prefix for
-caching. It does not invoke application generation callbacks, transforms, or tool
-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
-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`.
-
-This entry point is server-only and resolves to a throwing browser stub.
-
-### `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.
-
-### `createHandlers(options)`
-
-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`.
-
-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.
-
-See [Durable AI agents](/guides/ai-agents) for the protocol and complete
-examples.
-
-## `experimental-a2/client`
-
-```ts
-createClient(options: {
-  reducer: Reducer
-  api: ClientApi
-  gcTime?: number // idle session lifetime; 5 minutes by default
-  participant?: string // default presence identity for every session
-  reconnect?: (failure: {
-    sessionId: string
-    error: A2ClientError | null
-    attempt: number
-  }) => number | false
-}): A2Client
-
-type ClientApi =
-  | SessionUrl // one route: GET SSE stream + POST push
-  | { type: 'http'; push: SessionUrl; stream: SessionUrl }
-  | { type: 'ws'; url: SessionUrl; multiplex?: false }
-  | { type: 'ws'; url: string; multiplex: true }
-
-type SessionUrl = string | ((sessionId: string) => string)
-```
-
-`reconnect` runs after a failed connection or a stream ending, including a
-clean end with `error: null`. Return the delay in milliseconds before the next
-attempt, or `false` to pause automatic reconnection. Delays must be finite,
-non-negative, and at most 2,147,483,647 ms. The callback is synchronous; a
-throw or invalid result pauses the connection with an `A2ClientError`.
-
-`attempt` starts at 1 for the first retry. It counts consecutive attempts
-per session and resets when the stream becomes live or `session.reconnect()`
-explicitly restarts it. It is separate from the lifetime `reconnects` count.
-Without a callback, A2 retries indefinitely with delays starting at 500 ms,
-doubling up to five seconds. The callback does not run for an explicit
-restart, an idle-stream refresh, or a caller closing the stream.
-
-While paused, `connection.status` is `paused` and its last error remains
-available. State, hydration, optimistic writes, and connection leases remain
-intact. Another consumer taking a lease does not resume a paused stream.
-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
-hydration has advanced state while paused.
-
-A `SessionUrl` function runs for each HTTP request or WebSocket connection.
-Use it for session-specific paths. A2 still adds its `sessionId` and read-bound
-query parameters. The function does not authorize that ID. Bind any path scope
-or URL token to `operation.sessionId` in `authorize`; keep URL tokens short-lived
-because URLs can appear in infrastructure logs. A multiplexed WebSocket URL is
-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
-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:
-leases refcount per handle (the first connects, releasing the last
-closes, releasing twice is a no-op), so independent consumers of one
-identity-mapped handle never fight over the stream. `close()` is the
-hard stop: it drops every outstanding lease and closes now; a later
-`connect()` starts fresh.
-Snapshots carry `state`, `events`, `index`, `history`, and `connection`
-(the same fields `useSession` exposes), and `push` returns the same
-ack-then-`confirmed` result. On contracts that declare `presence` the handle also carries
-`setPresence()` and snapshots carry the `presence` map, exactly like
-the hook; `participant` is the identity `setPresence` sends under:
-stated once on `createClient` as the default for every handle, or per
-session as the override. Use
-it directly from any other framework, or none.
-
-Within one `A2Client`, repeated `session(id)` calls return the same live
-handle. A later call with a further server-rendered frontier advances the
-handle and does not drop pending optimistic events; a stale render cannot move
-it backward. Optional `initialEvents` seed earlier raw events for history UIs
-and merge into that feed. They do not affect the folded state or stream
-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.
-
-## `experimental-a2/cache-indexeddb`
-
-```ts
-indexedDb(): A2ClientCache
-```
-
-A browser-side cache for `SessionProvider`: the session's events
-(immutable; writes are idempotent by index), a folded snapshot
-(invalidated by a reducer rename), and the pending-push queue.
-`cache.clear(sessionId?)` is the logout story. Create instances in client
-code; they're live objects, not serializable props. See
-[Local-first](/guides/local-first).
-
-## `experimental-a2/otel`
-
-```ts
-otel(options?: { tracer?: Tracer; tracerName?: string }): A2Telemetry
-```
-
-OpenTelemetry instrumentation for a server (`@opentelemetry/api` is a
-peer dependency). Pass it as `telemetry`; spans nest through the active
-context, so the happy path lands in one trace: request → append → drain →
-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            |
-
-Attributes arrive in two waves: **at start** (passed to `span()`) and
-**mid-span** (via `handle.setAttribute`; outcomes and counts aren't
-known until the work ran). A recorder must merge both; the ones you
-alert on are all mid-span.
-
-| Attribute             | Span        | When  | Values                                                |
-| --------------------- | ----------- | ----- | ----------------------------------------------------- |
-| `a2.append.source`    | `a2.append` | start | `external` \| `handler`                                |
-| `a2.append.mode`      | `a2.append` | start | `inline` \| `dispatch`                                |
-| `a2.append.types`     | `a2.append` | start | comma-joined event types                              |
-| `a2.append.count`     | `a2.append` | start | batch size                                            |
-| `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.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                                              |
-| `a2.event.attempt`    | `a2.event`  | start | same durable 1-based ordinal as `ctx.attempt`          |
-| `a2.event.lane`       | `a2.event`  | start | stored lane value; absent for concurrent unlaned work  |
-| `a2.event.handled`    | `a2.event`  | start | normally `true`; `false` when a custom-adapter row has no handler |
-| `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.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           |
-
-Drain outcomes: `settled` means nothing actionable is left; `busy` means live
-per-event claims remain; `stalled` means a caught failure needs a later retry.
-A dead-lettered event blocks only later events in its lane. Other lanes remain
-eligible.
-
-A failing handler marks its `a2.event` span with the exception and
-error status; `a2.event.outcome = dead_lettered` is the attribute to
-alert on. `superseded` means a stale completion or failure did not change the
-log.
-`A2Telemetry` is a one-method interface; anything with
-`span(name, attributes, fn)` works;
-`otel()` is simply the adapter A2 ships. This catalogue is a contract:
-renames and additions are breaking for dashboards, and are called out in the
-package's `CHANGELOG.md`.
-
-## `experimental-a2/scheduler-vercel`
-
-`vercelQueues(options?)` returns an `A2Scheduler` backed by Vercel Queues.
-
-```ts server/scheduler-vercel.ts
-import { vercelQueues } from 'experimental-a2/scheduler-vercel'
-
-export const scheduler = vercelQueues()
-```
-
-| Option | Type | Default |
-| --- | --- | --- |
-| `topic` | `string` matching `[A-Za-z0-9_-]+` | `'a2'` |
-| `scheduledAppends` | `'deployment' \| 'deploymentless'` | `'deployment'` |
-| `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.
-
-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.
-
-## `experimental-a2/scheduler-qstash`
-
-`qstash(options?)` returns an `A2Scheduler` backed by QStash HTTP delivery.
-Vercel Queues remains the recommended default on Vercel. Use QStash when you
-want a scheduler that calls a stable public endpoint.
-
-```ts server/scheduler-qstash.ts
-import { qstash } from 'experimental-a2/scheduler-qstash'
-
-export const scheduler = qstash()
-```
-
-| Option | Type | Default |
-| --- | --- | --- |
-| `url` | `string` | conventional local or Vercel callback; required for process-less runtimes, other production, and custom routes |
-| `token` | `string` | `QSTASH_TOKEN` |
-| `currentSigningKey` | `string` | `QSTASH_CURRENT_SIGNING_KEY` |
-| `nextSigningKey` | `string` | `QSTASH_NEXT_SIGNING_KEY` |
-| `headers` | `Readonly<Record<string, string>>` | no additional callback headers |
-| `client` | `QStashPublishingClient` | lazy `@upstash/qstash` client |
-| `retries` | non-negative integer | the QStash provider default |
-| `maxBodyBytes` | positive integer | `1_048_576` (1 MiB) for callbacks and reserved outbound bodies |
-| `transport` | `QStashTransport` | lazy `@upstash/qstash` client and receiver |
-| `clock` | `{ now(): Date }` | system clock |
-
-`headers` adds static headers to every callback delivery, including recovery
-successors. A2 validates and snapshots the record when `qstash()` runs, then
-asks QStash to redact every configured value from its dashboard and API. QStash
-still receives, stores, and delivers the original values. Header names are
-case-insensitive. Provider-owned `Upstash-*` headers, `Content-Type*`, HTTP
-framing headers, and A2's managed Vercel identity headers are reserved.
-
-`client` accepts the structural `publishJSON(...)` part of a configured
-`@upstash/qstash` `Client`. A2 still creates the `Receiver` lazily from the
-signing-key options. `client` cannot be combined with `token` or `transport`.
-Use it to configure the QStash API endpoint, publish-request retry policy, or
-telemetry. Use A2's `headers` option for callback credentials. Client-global
-callback headers and redaction are outside A2's merge contract. The injected
-client receives raw callback credentials, including an automatic preview
-identity, and must honor the per-publish redaction request.
-
-`transport` and `clock` are advanced injection seams for tests and custom
-delivery. A `QStashTransport` implements `publish(request)` and
-`verify(request)`. Publish requests contain the callback `url`, a complete
-`SchedulerTask` body, optional callback `headers`, optional `redact.header`
-names, optional Unix-seconds `notBefore`, and a deterministic
-`deduplicationId`. Store-outage successors add provider-private generation
-metadata to that body. Custom transports must preserve the body, deliver every
-header, and apply every redaction request. An explicit `retries` value is
-forwarded; omission lets QStash use its provider default. Verify requests
-contain the signature, raw body, exact callback URL, and optional Upstash
-region.
-
-An explicit `url` always wins. Otherwise, Vercel production resolves to
-`https://${VERCEL_PROJECT_PRODUCTION_URL}/api/a2/scheduler` and preview resolves
-to `https://${VERCEL_BRANCH_URL}/api/a2/scheduler`. Outside those deployments,
-a runtime that exposes `process.env` and is not in `NODE_ENV=production`
-resolves to `http://localhost:${PORT ?? 3000}/api/a2/scheduler` and passes
-`devMode: true` to the SDK client and receiver. `QSTASH_DEV` is not required.
-`PORT` must be an integer from 1 through 65535. `QSTASH_DEV_PORT` configures the
-local QStash server, not the application callback. Automatic startup requires
-`@upstash/qstash` 2.11.0 or newer in a Node.js runtime. The lazy transport
-starts it on the first publish or verification. The direct SDK override means
-`QSTASH_DEV=false` does not disable an inferred local route.
-
-A non-Vercel production runtime or a process-less runtime requires an explicit
-absolute URL. Pass one for a custom host or path, an application port not
-available through `PORT`, or Docker networking. An Edge runtime that exposes
-`process.env` can infer the local URL, but it must start the QStash development
-server separately. Outside production, an explicit URL does not override the
-SDK's development mode, so `QSTASH_DEV` and manually supplied `QSTASH_URL` plus
-credentials retain their SDK-defined behavior. A2 passes `devMode: false` in
-production. The inferred Vercel hosts are moving aliases, so pending tasks can
-reach later deployments on the same production or branch URL.
-
-Mount the application handler once and pass every server that shares the
-scheduler:
-
-```ts app/api/a2/scheduler/route.ts
-import { billingServer, ordersServer, scheduler } from '@/server'
-
-export const POST = scheduler.handler(ordersServer, billingServer)
-```
-
-The route must be reachable by the selected QStash server after any platform
-edge authentication. The development server calls localhost directly. The
-adapter reads its raw body once and verifies `Upstash-Signature`, the exact URL,
-and `Upstash-Region` before it parses the delivery or touches a server. Missing
-or invalid signatures return 401, so ordinary unsigned traffic cannot execute
-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
-`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
-when needed. Keep one value across every deployment that can receive this
-callback URL. A lower value deployed while older tasks remain can return a
-non-retryable 489 for a task accepted by the previous value.
-
-For an inferred Vercel preview callback, the adapter reads the current
-invocation's `x-vercel-oidc-token` for each publish. When it is a parseable JWT
-whose expiration remains at least 60 seconds after the task's first due time,
-the adapter supplies it as `x-vercel-trusted-oidc-idp-token` and requests QStash
-header redaction. A matching Vercel Trusted Sources rule can then admit the
-first delivery. QStash receives the credential even though its dashboard and
-API redact it.
-
-This is opportunistic, not durable. Missing, malformed, and near-expiry tokens
-fall back to an ordinary publish, preserving public-preview behavior. An
-explicit `url` opts out. Inferred production and local callbacks never forward
-the token. QStash stores the static header and reuses it on retries, so delayed
-tasks and retries can outlive it. Use an explicit automation bypass or public
-ingress when every protected delivery must remain authorized. Applications can
-supply a dedicated bypass through `headers`; A2 requests redaction for its
-value, but pending messages retain the captured credential after rotation. A
-delivery-time Vercel relay remains a separate application architecture that
-requires a Trusted Sources rule, strict target allowlisting, and a versioned
-routing envelope. QStash signature verification remains mandatory after the
-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
-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
-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.
-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.
-
-The adapter leaves `retries` unset by default so QStash applies its provider
-default. An explicit non-negative value is passed through. Every delivery
-attempt is billable. A prolonged outage in which QStash cannot reach the
-callback still requires DLQ monitoring and redrive because no running callback
-can publish a successor. QStash's
-documented 10-minute deduplication window can reduce duplicate watchdogs but is
-not part of A2's correctness model. Stable scheduled-event ids also make timer
-redelivery safe after that window. One-shot delays are currently capped at 7
-days on free plans and 1 year on usage-based plans, with no fixed maximum on
-fixed plans. Leave at least one second of margin at a plan maximum because
-`notBefore` uses whole Unix seconds. The adapter carries both recovery watchdogs and
-`session.schedule` tasks.
-
-The built-in QStash and Vercel adapters preserve the original provider error
-from a rejected send. A recognized definite 4xx status or error is terminal
-except for 408, 409, 425, and 429. Those statuses, 5xx responses, network
-failures, and errors with no recognized status remain retryable. The Vercel
-adapter also recognizes the SDK's name-only `BadRequestError`,
-`UnauthorizedError`, and `ForbiddenError` as terminal. Its native
-duplicate-message error is success. A2's durable AI tool execution uses this
-private classification. Direct `session.schedule()` calls still reject with
-the original error object.
-
-## Entry points
-
-| Entry point          | Ships                              | Peer dependency |
-| -------------------- | ---------------------------------- | --------------- |
-| `experimental-a2`                 | `contract`, `A2Error`: isomorphic core    | none     |
-| `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/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 |
-| `experimental-a2/store-sqlite`      | SQLite store backend                 | none            |
-| `experimental-a2/store-memory`      | in-memory store backend              | none            |
-| `experimental-a2/scheduler-vercel` | `vercelQueues`: recovery and timers | `@vercel/queue` |
-| `experimental-a2/scheduler-qstash` | `qstash`: signed recovery and timers | `@upstash/qstash` |
-| `experimental-a2/cache-indexeddb` | `indexedDb` browser cache          | none            |
-| `experimental-a2/otel`            | `otel` telemetry adapter           | `@opentelemetry/api` |
-
-Core `experimental-a2` imports none of the backends, enforced by a browser-bundle
-test in CI, not just convention. Importing `experimental-a2/store-postgres` is what
-pulls in Postgres, never `experimental-a2` itself, and never your client bundle.