experimental-a2 0.19.0 → 0.21.1

package/docs/reference/04-ai.mdx

@@ -65,9 +65,10 @@ The `UIMessage` type a contract's input commands (`ai.control.requested`)
 carry, such as `AIMessageOf<typeof contract.events>`; `UIMessage` otherwise.
 `agent()` types messages with it.
 
-### `handlerContext(contract?)`
+### `consumerContext(contract?)`
 
-Returns the current tool execution's durable handler context, an
+Returns the current tool execution's durable
+[consumer context](/server/consumers#the-context), an
 `AgentToolContext<D>` with `event`, `attempt`, `session`, and `signal`.
 
 - Tools are plain AI SDK `tool()` definitions, passed through uninterpreted;
@@ -123,7 +124,7 @@ Pure typed builders of `ai.control.requested` commands, for `append()` and
 - **Trust.** Browser ingress accepts user messages, approval and input
   responses, interruptions, and explicit retries. `inputs.requestInput()`,
   `inputs.toolResult()`, and non-user `inputs.seed()` messages are trusted
-  server appends; only built-in handlers append generation requests and AI
+  server appends; only A2's own consumers append generation requests and AI
   lifecycle events. No builder covers session lifecycle: append
   `ai.session.created` and `ai.session.closed` from trusted server code.
 - **IDs.** Message, seed, and steer commands use the input message ID as their
@@ -336,7 +337,7 @@ agent({
   progress?,
   toolLane?: string, // run local tool executions one at a time on this lane
   toolRecovery?: { [tool]?: ToolRecovery }, // 'rerun' (default) | 'report'
-  handlers?, // application event handlers
+  consumers?, // your consumers, next to A2's own
   store?, scheduler?, telemetry?,
 }): Agent<Events, State, Name> // an A2Server
 ```
@@ -350,10 +351,10 @@ stub.
 | `name` | the built-in protocol, with optional server-only `events` and `messageSchema` |
 | `contract` | a shared `agentContract()`, when clients fold application state |
 | `model` | an AI Gateway model ID, or [`ModelSettings`](#modelsettings) with one, under every harness; a value or per-generation async resolver |
-| `tools` | AI SDK `tool()` definitions; local tools read context with [`handlerContext()`](#handlercontextcontract) |
+| `tools` | AI SDK `tool()` definitions; local tools read context with [`consumerContext()`](#consumercontextcontract) |
 | `instructions` | a value or per-generation async resolver |
 | `maxSteps` | a positive integer capping one complete assistant response, under every harness; no limit by default |
-| `harness` | the agent's loop: `{ type: 'ai-sdk', … }` (`AISDKHarness`, the default), [`fx()`](#fx), or [`pi()`](#pisandbox) |
+| `harness` | the agent's loop: `{ type: 'ai-sdk', … }` (`AISDKHarness`, the default), [`fx()`](#fx), or [`pi()`](#pi-sandbox-) |
 | `harness.generation` | per-step settings, or a resolver |
 | `harness.messageMetadata` | maps default stream parts to message metadata |
 | `harness.generate` | replaces the default model step |
@@ -361,8 +362,8 @@ stub.
 | `progress` | durable batching: `maxChunks` (128), `maxDelayMs` (0) |
 | `toolLane` | one lane for every local tool execution, one at a time in admission order; model steps keep their own lane |
 | `toolRecovery` | `'rerun'` (default) or `'report'` per tool, the harness's own tools included |
-| `handlers` | application event handlers; naming an event the agent handles throws a `TypeError` |
-| `store`, `scheduler`, `telemetry` | as for any A2 server; `telemetry` covers Core and AI in one trace ([span catalogue](/reference/adapters#the-span-catalogue)) |
+| `consumers` | your [consumers](/server/consumers), next to A2's own: `a2.ai.metadata` (concurrent), `a2.ai.control` (one lane for commands, work reports, and closes), `a2.ai.model` (one lane for generations), and `a2.ai.tools` (on `toolLane`, or concurrent). Yours may take any of the contract's events, the agent's own included, and run beside A2's. Names starting with `a2.` are reserved |
+| `store`, `scheduler`, `telemetry` | as for any A2 server; `telemetry` covers Core and AI in one trace ([span catalogue](/reference/telemetry#the-span-catalogue)) |
 
 **Contracts.** A contract not built by `agentContract()` throws a `TypeError`
 and fails to typecheck (serve custom contracts with `createServer()`). Messages
@@ -384,7 +385,7 @@ overrides model headers. See
 **`harness`** is the agent's loop. `{ type: 'ai-sdk' }` (`AISDKHarness`), the
 default, runs one AI SDK `streamText()` step per durable generation, with the
 `generation`, `messageMetadata`, `generate`, and `compaction` options below.
-[`fx()`](#fx) and [`pi()`](#pisandbox) run a coding agent's own loop instead.
+[`fx()`](#fx) and [`pi()`](#pi-sandbox-) run a coding agent's own loop instead.
 The four options exist only in `{ type: 'ai-sdk' }`; passing one to `agent()`
 itself throws a `TypeError` naming where it belongs.
 
@@ -445,11 +446,11 @@ compaction. It returns exactly one model step as a
 the durable lifecycle. See
 [Replace generation, not durability](/agents/conversations#replace-generation-not-durability).
 
-**Tools.** Independent authorized tool handlers run concurrently with no
-fixed limit. Results and generation completion arrive in either order; a
-continuation needs the closed step and every required terminal result.
-Single-owner terminal events commit atomically with the parent handler's
-completion and carry its durable cause; many-owner joins and preliminary
+**Tools.** Independent authorized tool executions run concurrently with no
+fixed limit, unless `toolLane` orders them. Results and generation completion
+arrive in either order; a continuation needs the closed step and every
+required terminal result. Single-owner terminal events commit atomically with
+the parent run's completion and carry its durable cause; many-owner joins and preliminary
 outputs append immediately and idempotently. Provider calls and external side
 effects are at least once: give them their own idempotency. An approved
 provider-executed call can satisfy the join from its approval response, and a
@@ -489,8 +490,8 @@ See [Delivery semantics](/agents/conversations#delivery-semantics).
 - Static options are validated at construction, resolved ones before their
   generation; each session uses its own value.
 - Discovery: without an explicit threshold, the first generation batches a
-  metadata request into its start write, and an independent handler records the
-  model's limits from the public Gateway catalog in `state.modelMetadata`
+  metadata request into its start write, and A2's `a2.ai.metadata` consumer
+  records the model's limits from the public Gateway catalog in `state.modelMetadata`
   without delaying dispatch (shared one-hour cache, five-second timeout; no new
   request per turn, even after exhausted retries). The default threshold is 75%
   of the context window, lowered for a larger output allowance. While it is
@@ -525,7 +526,7 @@ See [Compact long conversations](/agents/conversations#compact-long-conversation
 **Harnesses.** Under `fx()` and `pi()`, each model call the harness makes is one
 durable step of the response, with the same events, progress, steering,
 interruption, `maxSteps`, and recovery as any step. Tool calls it makes become
-ordinary A2 tool calls, executed by A2's tool handlers, and `toolRecovery` may
+ordinary A2 tool calls, executed by A2's `a2.ai.tools` consumer, and `toolRecovery` may
 name the harness's own tools, such as Pi's `bash`. `model` is resolved per step
 as for any agent. `instructions` and `tools` reach the harness; how they
 combine with its own prompt and tools depends on the harness. Tool approval
@@ -569,11 +570,11 @@ resolver. `reasoning` becomes the AI SDK `reasoning` call option
 model has one; `'standard'` removes a configured speed. Both override the same
 settings in `generation`. See [Choose the model](/agents/introduction#choose-the-model).
 
-### `runWithHandlerContext(ctx, fn)`
+### `runWithConsumerContext(ctx, fn)`
 
 The test seam for context-reading tools: runs `fn` with `ctx` as the ambient
-handler context, so tests can call `execute` directly. Inside `fn`,
-`handlerContext()` returns `ctx`, with or without a contract argument.
+consumer context, so tests can call `execute` directly. Inside `fn`,
+`consumerContext()` returns `ctx`, with or without a contract argument.
 
 ## `experimental-a2/ai/fx`
 
@@ -601,6 +602,14 @@ call. Replay grows with the response, roughly 0.1 to 0.5 seconds for one of 80
 to 200 tool calls. When libfx can't take a checkpoint, A2 replays from an
 earlier one.
 
+FX's model calls carry the same [AI Gateway](#agentoptions) defaults as the
+AI SDK harness: `caching: 'auto'`, under any Gateway options FX sets itself,
+and the session's stable `x-session-affinity` header in place of FX's own,
+which changes every time A2 rebuilds the kernel. A2 leaves every other byte of
+the request as FX wrote it, so it adds caching only where FX's own options come
+last in the request, as libfx writes them; otherwise the request goes
+unchanged.
+
 Credentials come from `AI_GATEWAY_API_KEY`, or Vercel's OIDC token on Vercel.
 This entry point is server-only.
 

package/docs/reference/05-telemetry.mdx

@@ -0,0 +1,146 @@
+---
+title: Telemetry
+description: "Trace A2 with OpenTelemetry, and the spans it reports."
+---
+
+```ts server/orders.ts
+import { createServer } from 'experimental-a2/server'
+import { otel } from 'experimental-a2/otel'
+import { orders } from '@/contracts'
+
+export const ordersServer = createServer({
+  contract: orders,
+  telemetry: otel(),
+  // ...store, scheduler, and consumers
+})
+```
+
+With any OpenTelemetry setup registered (on Vercel, `@vercel/otel`), one trace
+shows the request, `a2.append`, the inline `a2.drain`, an `a2.event` span per
+consumer run, and the appends those runs make. Failures mark their `a2.event`
+span, and `a2.event.outcome = dead_lettered` is the attribute to alert on.
+Agent servers add `a2.ai.*` spans.
+
+## `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. `A2Telemetry` is a one-method interface:
+anything with `span(name, attributes, fn)` works, and `otel()` is the adapter
+A2 ships.
+
+## The span catalogue
+
+This catalogue is a contract: renames and additions are breaking for
+dashboards and are called out in the package's `CHANGELOG.md`. All spans carry
+`a2.contract` and `a2.session_id`. Core spans describe the durable runtime;
+`a2.ai.*` spans describe the AI runtime's consumers.
+
+| Layer | Span | Wraps |
+| ----- | ---- | ----- |
+| Core | `a2.append` | validation + the store write (one batch) |
+| Core | `a2.drain` | one drain pass, including the consumer runs it starts |
+| Core | `a2.event` | one claimed head, including the consumer's run and its completion |
+| Core | `a2.claim` | one `claimAvailable` store operation |
+| Core | `a2.commit` | one `completeAttempt` or `failAttempt` store operation |
+| Core | `a2.state` | one `state()` read: snapshot-plus-tail load + reducer fold |
+| Core | `a2.snapshot` | one background batch of checkpoint writes |
+| Core | `a2.redrive` | one `session.redrive()`: the store operation and starting the session's wakeup |
+| Core | `a2.consume` | one `session.consume()`, including the drains it runs and the waits between them |
+| AI | `a2.ai.control` | applying an input/work report/session-close decision and preparing its returned events |
+| AI | `a2.ai.generate` | one generation run, including Core calls and model/SDK work |
+| AI | `a2.ai.context` | constructing model messages, including tool prompt reconstruction when uncached |
+| AI | `a2.ai.compaction` | automatic summarization or the custom compaction callback |
+| AI | `a2.ai.tool` | one durable tool run, including application execution |
+| AI | `a2.ai.ack` | waiting for a persisted work report's canonical events and control receipt |
+
+Durations include nested work: `a2.event` contains its AI run and later
+commit, AI runs call Core, and `a2.state` includes reducer code.
+Acknowledgements overlap control processing, claims can cover several events,
+and snapshots run in the background, so summing spans, or subtracting summed
+children, does not yield exclusive Core or AI overhead. Model and application
+I/O is included; its child spans have the detail.
+
+Attributes arrive in two waves: **at start** (passed to `span()`) and
+**mid-span** (via `handle.setAttribute`, for outcomes and counts known only
+after 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` \| `consumer`                               |
+| `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` \| `failed`          |
+| `a2.drain.processed`  | `a2.drain`  | mid   | events processed this pass                            |
+| `a2.claim.outcome` | `a2.claim` | mid | `claimed` \| `busy` \| `settled` |
+| `a2.claim.count` | `a2.claim` | mid | number of claimed events, or zero |
+| `a2.commit.operation` | `a2.commit` | start | `complete` \| `fail` |
+| `a2.commit.index` | `a2.commit` | start | event log position |
+| `a2.commit.attempt` | `a2.commit` | start | durable 1-based attempt ordinal |
+| `a2.commit.outcome` | `a2.commit` | mid | `completed` \| `failed` \| `dead_lettered` \| `superseded` |
+| `a2.event.type`       | `a2.event`  | start | the event's type                                      |
+| `a2.event.index`      | `a2.event`  | start | log position                                          |
+| `a2.event.id`         | `a2.event`  | start | event id                                              |
+| `a2.event.consumer`   | `a2.event`  | start | the consumer running the event                        |
+| `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 claimed head's consumer is not registered |
+| `a2.event.age_ms`    | `a2.event`  | start | milliseconds since the event was appended, when its run starts: how far behind its consumer is in time |
+| `a2.event.lag`       | `a2.event`  | start | events appended after this one when it was claimed: how far behind its consumer is in the log. Absent when the store doesn't report its head |
+| `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) \| `memory` (served from the server's in-memory state) |
+| `a2.state.folded`     | `a2.state`  | mid   | events folded past the snapshot                       |
+| `a2.state.index`      | `a2.state`  | mid   | the frontier the returned state reflects              |
+| `a2.snapshot.reducer` | `a2.snapshot` | start | the reducer's name                                  |
+| `a2.snapshot.index`   | `a2.snapshot` | start | greatest checkpoint index in the write batch       |
+| `a2.snapshot.count`   | `a2.snapshot` | start | number of checkpoints in the write batch           |
+| `a2.consume.consumer` | `a2.consume` | start | the consumer being consumed |
+| `a2.consume.through` | `a2.consume` | mid | the index it runs through |
+| `a2.consume.index` | `a2.consume` | mid | the index it handled every event through |
+| `a2.consume.drains` | `a2.consume` | mid | drains it ran to get there |
+| `a2.redrive.index` | `a2.redrive` | start | log position of the event being redriven |
+| `a2.redrive.consumer` | `a2.redrive` | start | the consumer the event is dead for |
+| `a2.redrive.action` | `a2.redrive` | start | `retry` \| `skip` |
+| `a2.redrive.redriven` | `a2.redrive` | mid | `true` when the event was dead-lettered and is now resolved |
+| `a2.redrive.armed` | `a2.redrive` | mid | `false` when the scheduler arm failed and the wakeup degraded to append-driven healing |
+| `a2.ai.control.type` | `a2.ai.control` | start | `ai.control.requested` \| `ai.work.reported` \| `ai.session.closed` |
+| `a2.ai.control.id` | `a2.ai.control` | start | triggering event id |
+| `a2.ai.control.attempt` | `a2.ai.control` | start | durable 1-based attempt ordinal |
+| `a2.ai.generate.request_id` | `a2.ai.generate` | start | generation request event id |
+| `a2.ai.generate.attempt` | `a2.ai.generate` | start | durable 1-based attempt ordinal |
+| `a2.ai.context.request_id` | `a2.ai.context` | start | generation request event id |
+| `a2.ai.context.phase` | `a2.ai.context` | start | `generation` \| `refresh` \| `tool` |
+| `a2.ai.compaction.request_id` | `a2.ai.compaction` | start | generation request event id |
+| `a2.ai.compaction.generation_id` | `a2.ai.compaction` | start | generation attempt id |
+| `a2.ai.compaction.policy` | `a2.ai.compaction` | start | `automatic` \| `custom` |
+| `a2.ai.tool.request_id` | `a2.ai.tool` | start | originating generation request event id |
+| `a2.ai.tool.call_id` | `a2.ai.tool` | start | tool call id |
+| `a2.ai.tool.name` | `a2.ai.tool` | start | tool name |
+| `a2.ai.tool.attempt` | `a2.ai.tool` | start | durable 1-based attempt ordinal |
+| `a2.ai.ack.request_id` | `a2.ai.ack` | start | reporting worker event id |
+| `a2.ai.ack.report_id` | `a2.ai.ack` | start | work report event id, matching the control span's id |
+
+- Consumer lag: group `a2.event` spans by `a2.event.consumer`. `a2.event.lag`
+  is how many events the session had appended after the one it claimed, and
+  `a2.event.age_ms` how old that event was when its run started. A consumer
+  that keeps up keeps both near zero; a rising `a2.event.lag` means it is
+  falling behind its log.
+- Drain outcomes: `settled` means nothing actionable is left; `busy` means live
+  per-event claims or a failed event's retry hold remain; `stalled` means a
+  caught failure in this drain needs a later retry. `failed` appears only on
+  scheduler deliveries: the drain threw after arming its successor watchdog,
+  the span records the error, and that successor retries the session.
+- A failing consumer run marks its `a2.event` span with the exception and
+  error status. Alert on `a2.event.outcome = dead_lettered`. A dead-lettered event
+  blocks only later events in its lane, until `session.redrive()` resolves it;
+  other lanes stay eligible.
+- `superseded` means a stale completion or failure did not change the log.

package/docs/reference/06-errors.mdx

@@ -10,7 +10,7 @@ exposes `A2ClientError`, which extends `A2Error`, for server failures and local
 ones alike, so `instanceof A2Error` matches both.
 
 ```ts
-// e.g. in a route handler:
+// e.g. in a route:
 import { A2Error } from 'experimental-a2'
 
 export async function POST(req: Request) {
@@ -40,16 +40,18 @@ export async function POST(req: Request) {
 | `UNKNOWN_PRESENCE_FIELD` | a presence field isn't in the contract's `presence` map | no |
 | `PRESENCE_NOT_SUPPORTED` | the contract declares `presence` but the store has no presence capability. Thrown at construction; for environment-resolved stores, at first store use | no |
 | `PARTIAL_DUPLICATE_BATCH` | a batch mixes already-appended and fresh events, contains the same id twice, or uses an id already used in a different session (event ids are globally unique). Always a caller bug; nothing was written | no |
-| `SUPERSEDED_ATTEMPT` | a handler append or clear comes from an attempt that a recovery claim or a session clear replaced; nothing was written. Also the abort reason on that handler's `ctx.signal` | no |
-| `SESSION_CLEARED` | a state read reaches below the latest clear, a handler reads state past a clear of its event, or an actor call is cleared before it receives its answer | no |
+| `SUPERSEDED_ATTEMPT` | a consumer's append or clear comes from an attempt that a recovery claim or a session clear replaced; nothing was written. Also the abort reason on that attempt's `ctx.signal` | no |
+| `SESSION_CLEARED` | a state read reaches below the latest clear, a consumer reads state past a clear of its event, or an actor call is cleared before it receives its answer | no |
 | `CLAIM_EXPIRED` | never thrown; only the `ctx.signal` abort reason when the attempt's lease lapsed without renewal (assumed loss, decided locally, not proof) | no |
+| `CONSUMER_DEAD_LETTERED` | `session.consume()` reached an event that dead-lettered for that consumer. Resolve it with `session.redrive()`, then consume again | no |
 | `STORE_UNAVAILABLE` | the store backend failed; nothing was written. The original error is the `cause` | **yes** |
-| `STORE_NOT_CONFIGURED` | production boots with no `store` configured (during `next build` page collection, deferred to first use) | no |
+| `STORE_NOT_CONFIGURED` | production boots with no `store` configured (during `next build` page collection, deferred to first use), a store's optional peer dependency is missing, or a Postgres query finds one of A2's tables or columns missing, or that its role can't use (and, with `listenConnectionString`, a subscription finds the notification triggers missing). The message names the fix | no |
 
 Retrying an *identical* batch is not `PARTIAL_DUPLICATE_BATCH`: it's an
 idempotent success that returns the previously appended events. A failing
-handler never makes `append` throw; handler failures retry and, if persistent,
-[dead-letter the event](/server/guarantees#when-a-handler-keeps-failing). See
+consumer never makes `append` throw; its failures retry and, if persistent,
+[dead-letter the event](/server/guarantees#when-a-consumer-keeps-failing) for
+that consumer. See
 [What append never throws for](/server/guarantees#what-append-never-throws-for).
 
 ## `A2ClientError`
@@ -82,33 +84,37 @@ or `RangeError`.
 
 ## NonRetriableError
 
-Throw it (or a subclass, matched by `instanceof`) from a handler when the
+Throw it (or a subclass, matched by `instanceof`) from a consumer when the
 failure is deterministic: a guard that refuses this attempt refuses every
-retry identically. The event dead-letters immediately instead of consuming the
-ten-failure retry budget. Any other thrown error keeps the
+retry identically. The event dead-letters for that consumer immediately,
+instead of spending the ten-failure retry budget. Any other thrown error keeps the
 ordinary retry contract.
 
 ```ts
 import { z } from 'zod'
 import * as a2 from 'experimental-a2'
 import { NonRetriableError } from 'experimental-a2'
-import { createServer } from 'experimental-a2/server'
+import { consumer, createServer } from 'experimental-a2/server'
 
 const orders = a2.contract({
   name: 'orders',
   events: { created: z.object({ chargeable: z.boolean() }) },
 })
 
+const charge = consumer({
+  contract: orders,
+  name: 'charge',
+  types: ['created'],
+}).run(async ({ event }) => {
+  if (!event.payload.chargeable) {
+    throw new NonRetriableError('this order cannot be charged')
+  }
+  // transient failures below retry as usual
+})
+
 export const ordersServer = createServer({
   contract: orders,
-  handlers: {
-    created: async ({ event }) => {
-      if (!event.payload.chargeable) {
-        throw new NonRetriableError('this order cannot be charged')
-      }
-      // transient failures below retry as usual
-    },
-  },
+  consumers: [charge],
 })
 ```
 

package/docs/reference/meta.ts

@@ -1 +1 @@
-export default { order: 7 }
+export default { order: 10 }

package/docs/schedulers/01-overview.mdx

@@ -0,0 +1,112 @@
+---
+title: Overview
+description: A clock for consumer retries and timers.
+---
+
+```ts server/orders.ts
+import { createServer } from 'experimental-a2/server'
+import { redis } from 'experimental-a2/store-redis'
+import { vercelQueues } from 'experimental-a2/scheduler-vercel'
+import { orders } from '@/contracts'
+
+export const scheduler = vercelQueues()
+
+export const ordersServer = createServer({
+  contract: orders,
+  store: redis({ url: process.env.REDIS_URL }),
+  scheduler,
+  consumers: [
+    /* ... */
+  ],
+})
+```
+
+```ts app/api/a2/scheduler/route.ts
+import { billingServer, ordersServer, scheduler } from '@/server'
+
+export const POST = scheduler.handler(ordersServer, billingServer)
+```
+
+A scheduler wakes sessions on a clock. It retries a consumer that failed or
+whose process died, and it delivers [timers](/server/timers), whose delays must
+fit the [provider's limit](/server/timers#provider-limits). Share one
+scheduler across your servers and mount its route once, with every server it
+delivers to. `scheduler.handler(...)` checks those servers when the module
+loads, so a bad route fails at startup.
+
+| Scheduler | Use it for |
+| --- | --- |
+| [Vercel Queues](/schedulers/vercel-queues) | Apps on Vercel (recommended) |
+| [QStash](/schedulers/qstash) | A stable public URL, called from separate infrastructure |
+
+## Without a scheduler
+
+If the server has no consumers and nothing calls `session.schedule`, skip it.
+Events settle as they're appended, with no queue messages. That's a complete
+production setup for history, reducers, and live sync.
+
+With consumers but no scheduler, a session only wakes on a top-level append or
+an explicit `server.drain()`. Reads never wake it, so a session nobody writes
+to stays stuck. That's fine for internal tools that can heal on the next
+write. For production, add a scheduler.
+
+## More than one scheduler
+
+Servers with different scheduler instances need separate routes, even from the
+same adapter. Give each QStash instance its own `url`, and each Vercel Queues
+instance its own `topic` and trigger.
+
+## Dispatch in a fresh invocation
+
+`append` starts consumers in the same request and uses the scheduler as a
+watchdog. `append.dispatch` stores the event and hands its consumers to the
+queue instead:
+
+```ts app/api/imports/route.ts
+import { ordersServer } from '@/server'
+
+export async function POST(request: Request) {
+  const { orderId, shopId, items } = await request.json()
+  await ordersServer.session(orderId).append.dispatch({
+    id: `created:${orderId}`,
+    type: 'created',
+    payload: { shopId, items },
+  })
+  return Response.json({ accepted: true }, { status: 202 })
+}
+```
+
+It needs a scheduler and waits for the queue to accept the message. If that
+send fails, the event may already be stored; its explicit `id` makes a retry
+safe.
+
+## Deploys and rollbacks
+
+Queued work can reach a different deployment than the one that sent it. Keep
+event schemas compatible across deployments. Each adapter's page explains
+where its tasks go: [Vercel Queues](/schedulers/vercel-queues#deployments) and
+[QStash](/schedulers/qstash#deployments).
+
+:::warning
+Don't roll back to an A2 version without timer delivery while scheduled tasks
+are outstanding. An old route can acknowledge a scheduled append without
+writing its events. Rolling back past scheduled clears fails too: an old
+Vercel Queues route keeps failing the clear until retention ends, and an old
+QStash route moves it to QStash's dead-letter queue. Roll forward, or wait for
+those tasks to deliver first.
+:::
+
+## Send errors
+
+When a provider rejects a send, both adapters keep the provider's original
+error.
+
+- **Terminal:** a definite 4xx status or error, except 408, 409, 425, and 429.
+  The Vercel adapter also treats the SDK's `BadRequestError`,
+  `UnauthorizedError`, and `ForbiddenError` as terminal.
+- **Retryable:** 408, 409, 425, 429, 5xx, network failures, and errors with no
+  recognized status.
+- Vercel Queues' duplicate-message error counts as success.
+
+A2's durable AI tools use this classification. Direct `session.schedule()`
+calls still reject with the original error.

package/docs/schedulers/02-vercel-queues.mdx

@@ -0,0 +1,87 @@
+---
+title: Vercel Queues
+description: The recommended scheduler on Vercel.
+---
+
+```ts server/orders.ts
+import { createServer } from 'experimental-a2/server'
+import { redis } from 'experimental-a2/store-redis'
+import { vercelQueues } from 'experimental-a2/scheduler-vercel'
+import { orders } from '@/contracts'
+
+export const scheduler = vercelQueues()
+
+export const ordersServer = createServer({
+  contract: orders,
+  store: redis({ url: process.env.REDIS_URL }),
+  scheduler,
+  consumers: [
+    /* ... */
+  ],
+})
+```
+
+```ts app/api/a2/scheduler/route.ts
+import { ordersServer, scheduler } from '@/server'
+
+export const POST = scheduler.handler(ordersServer)
+```
+
+```json vercel.json
+{
+  "functions": {
+    "app/api/a2/scheduler/route.ts": {
+      "experimentalTriggers": [
+        {
+          "type": "queue/v2beta",
+          "topic": "a2"
+        }
+      ]
+    }
+  }
+}
+```
+
+```package-install
+npm i @vercel/queue
+```
+
+The trigger is required. It connects the route to Vercel Queues and makes the
+function private, so only the queue can call it. Don't also expose the route
+publicly or wrap it in your own authentication.
+
+Messages are kept for seven days (Vercel Queues' default is 24 hours, and
+seven days is its maximum), so timers can be scheduled up to seven days out. A
+longer delay goes out as asked, and Vercel Queues refuses it.
+
+A drain delivery is acknowledged once its session settles or a later watchdog
+for it is stored, including when the drain fails after storing that watchdog.
+A drain that fails before then stays unacknowledged, so Vercel Queues
+redelivers it.
+
+## Options
+
+| Option | Default | |
+| --- | --- | --- |
+| `topic` | `'a2'` | must match the trigger's `topic`, and `[A-Za-z0-9_-]+` |
+| `deploymentId` | `VERCEL_DEPLOYMENT_ID` | which deployment receives tasks; see below |
+| `transport`, `clock` | the `@vercel/queue` client, the system clock | test seams for custom delivery |
+
+An injected `transport` receives the topic, the task, and send options, and
+owns its own provider configuration; `deploymentId` only configures the
+built-in client.
+
+## Deployments
+
+`deploymentId` applies to every task: retries, timers, and scheduled clears.
+Leave it out to deliver to the deployment that sent the task, pass an ID to
+target one deployment, or pass `null` to let Vercel pick. Every deployment that
+sends or receives must use the same setting.
+
+- **Tasks stay with their deployment.** Promoting a new deployment doesn't move
+  them, so older deployments keep receiving their own work until it's done or
+  expires. Upgrading doesn't fix an older deployment's route.
+- **`null` doesn't mean latest.** Vercel picks any eligible deployment, so every
+  one of them must use `deploymentId: null` and handle pending tasks.
+- **Changing the setting doesn't move queued tasks.** Keep the old deployments
+  running until those tasks finish.