experimental-a2 0.20.0 → 0.21.1

package/docs/stores/04-postgres.mdx

@@ -11,9 +11,9 @@ import { orders } from '@/contracts'
 export const ordersServer = createServer({
   contract: orders,
   store: postgres({ connectionString: process.env.DATABASE_URL }),
-  handlers: {
+  consumers: [
     /* ... */
-  },
+  ],
 })
 ```
 
@@ -26,22 +26,70 @@ poolers.
 
 ## Create the tables
 
-A2 doesn't create tables in your database. This is the SQL it needs:
+A2 doesn't create or change tables in your database. This is the SQL it needs:
 [`schema.sql`](https://github.com/vercel-labs/a2/blob/main/packages/a2/sql/postgres/schema.sql),
 also in the package at `node_modules/experimental-a2/sql/postgres/schema.sql`.
-Apply it once before your first deploy, however you run SQL against your
-database, as the role your app connects with.
+Apply it before your first deploy, however you run SQL against your database
+or as one of your migrations, as the role your app connects with. A breakpoint
+comment ends each statement, for tools that send one statement per query.
+`a2_batch` runs the statements it's handed, so only its owner may call it,
+whatever your default privileges grant new functions. An app that connects as
+another role needs `grant execute on function a2_batch(text[], jsonb)` beside
+its grants on the tables, and keeps it when you apply the file again.
+
+A2 checks nothing up front. It relies on the table and column names, the
+column types, the primary keys, the unique index on `a2_events.event_id`, and
+the `a2_batch` function; the other indexes keep its queries fast. A query that
+finds a table, column, or the function missing throws `STORE_NOT_CONFIGURED`,
+naming the file. Once it's applied, the next request works, with no redeploy.
+
+`a2_batch` runs several statements in one round trip. Each append, claim,
+completion, and `consume` poll is one call of it, so they hold a session's lock
+only while the database runs the call, not across round trips from your app.
+That's what keeps one busy session fast on a database a few milliseconds
+away. It needs `read committed`, Postgres's default isolation level, and
+throws `STORE_NOT_CONFIGURED` under a stricter default.
+
+## With Drizzle
+
+[`drizzle-schema.ts`](https://github.com/vercel-labs/a2/blob/main/packages/a2/sql/postgres/drizzle-schema.ts),
+next to `schema.sql`, shows the same tables as Drizzle definitions. It's an
+example, not an API: one way to fit A2's tables into a Drizzle project is a
+copy next to your own schema, so your migrations create them with yours.
+
+```ts drizzle.config.ts
+import { defineConfig } from 'drizzle-kit'
+
+export default defineConfig({
+  dialect: 'postgresql',
+  // your tables, and a copy of drizzle-schema.ts:
+  schema: ['./db/schema.ts', './db/a2.ts'],
+  out: './drizzle',
+  dbCredentials: { url: process.env.DATABASE_URL ?? '' },
+})
+```
 
-## Upgrade
+`drizzle-kit generate` then writes A2's tables into a migration you can read,
+and `drizzle-kit migrate` applies it. Adapt the copy to your Drizzle version
+and layout, as long as the names and types stay A2's.
 
-When a release changes the schema, its changelog says so. Apply that
-release's `schema.sql` before you deploy it. The version you're running keeps
-working against the new schema.
+Drizzle can't declare a function, so add `a2_batch` as a custom migration:
+run `drizzle-kit generate --custom`, and paste the `do` block that creates
+`a2_batch` from `schema.sql` into the file it makes. It creates the function
+only if it's missing, so the migration is safe on any database.
+
+A generated migration only creates tables. On a database that already has
+A2's tables, from an earlier release or a `schema.sql` applied by hand, put
+`schema.sql` in place of the SQL drizzle-kit generated for them: it creates
+what's missing and upgrades the rest, keeping their events, and your schema
+still describes them for the next `generate`. To keep a table of your own
+from A2's logs, see [SQL projections](/server/sql-projections).
+
+## Upgrade
 
-If the tables are missing or out of date, the store's first query throws
-`STORE_NOT_CONFIGURED` naming the file to apply. Once it's applied, the next
-request works, with no redeploy. The store checks with one read before its
-first query, which never waits on or blocks writes.
+A release that changes A2's tables says so in its changelog, and its
+[upgrade page](/upgrades/overview) says when to apply its `schema.sql`. With
+Drizzle, bring your copy of `drizzle-schema.ts` in line with the new one.
 
 ## Live updates (polling)
 
@@ -56,7 +104,10 @@ run in different invocations.
 For instant updates, pass `listenConnectionString`, a direct connection to the
 same database (not through a pooler), and apply
 [`notifications.sql`](https://github.com/vercel-labs/a2/blob/main/packages/a2/sql/postgres/notifications.sql)
-once, the same way as `schema.sql`.
+once, the same way as `schema.sql` (with Drizzle, as a custom migration:
+`drizzle-kit generate --custom`). A missing trigger fails no query, so this is
+the one thing A2 looks for: a listening store's first subscription throws
+`STORE_NOT_CONFIGURED` until the triggers exist.
 
 Its triggers notify listeners of every write, including writes from stores
 without the option. Notifications arrive after commit, a reconnect catches up

package/docs/stores/05-sqlite.mdx

@@ -11,9 +11,9 @@ import { orders } from '@/contracts'
 export const ordersServer = createServer({
   contract: orders,
   store: sqlite({ path: '.a2/orders.db' }),
-  handlers: {
+  consumers: [
     /* ... */
-  },
+  ],
 })
 ```
 
@@ -22,7 +22,9 @@ your sessions survive `next dev` restarts. Pass it yourself to pick another
 file.
 
 It runs on `node:sqlite`, with no dependencies, and creates its tables when it
-opens the file. It's for development: a serverless filesystem doesn't last or
+opens the file. A file a release before [0.21](/upgrades/0-21) wrote throws
+`STORE_NOT_CONFIGURED` when it opens: delete it, or pass another `path`. It's
+for development: a serverless filesystem doesn't last or
 share one file across instances, so production needs another
 [store](/stores/overview).
 

package/docs/upgrades/01-overview.mdx

@@ -0,0 +1,30 @@
+---
+title: Overview
+description: What to do when you move to a new release. One page per release that needs steps from you, newest first.
+---
+
+## The releases
+
+| Release | What you do |
+| --- | --- |
+| [0.21](/upgrades/0-21) | Rewrite handlers as consumers. Let earlier deployments finish; on Postgres, then apply the new `schema.sql`. SQLite starts fresh. |
+| [0.20](/upgrades/0-20) | Postgres: apply `schema.sql` yourself, before you deploy. |
+| [0.19](/upgrades/0-19) | Start new agent sessions: earlier ones don't fold. |
+| [0.18](/upgrades/0-18) | Move the AI SDK loop's options into `harness`. |
+| [0.17](/upgrades/0-17) | Redis: use a fresh `keyPrefix`. Serve agents with `agent()`. |
+
+## Across several releases
+
+Read every page between the release you run and the one you're moving to,
+oldest first. Code changes add up: make each page's changes. Store steps
+don't always: each release's `schema.sql` covers a database from any earlier
+release, so a Postgres database needs only the newest one, applied the way the
+newest page says, and one fresh Redis `keyPrefix` covers every release that
+asks for one.
+
+## Everything else
+
+Each release's changelog lists everything it changes, including what needs no
+steps: [`CHANGELOG.md`](https://github.com/vercel-labs/a2/blob/main/packages/a2/CHANGELOG.md),
+also in the package at `node_modules/experimental-a2/CHANGELOG.md`. Releases
+before 0.17 are only there.

package/docs/upgrades/79-0-21.mdx

@@ -0,0 +1,165 @@
+---
+title: '0.21'
+description: Handlers become consumers, and every store keeps their places in a new layout.
+---
+
+## Handlers become consumers
+
+```ts
+// before: server/orders.ts on 0.20
+export const ordersServer = createServer({
+  contract: orders,
+  handlers: {
+    created: async ({ event }) => {
+      // await sendEmailToShop(event.payload.shopId, { idempotencyKey: event.id })
+      return { type: 'shop.notified', payload: {} }
+    },
+    'shop.started': { lane: 'shop', handler: async () => {} },
+    'shop.notified': { lane: 'shop', handler: async () => {} },
+  },
+})
+```
+
+```ts server/orders.ts
+import { createServer } from 'experimental-a2/server'
+import { orders } from '@/contracts'
+
+export const ordersServer = createServer({
+  contract: orders,
+  consumers: [
+    {
+      name: 'notify-shop',
+      types: ['created'],
+      run: async ({ event }) => {
+        // await sendEmailToShop(event.payload.shopId, { idempotencyKey: event.id })
+        return { type: 'shop.notified', payload: {} }
+      },
+    },
+    // the types that shared the 'shop' lane, as one consumer:
+    {
+      name: 'shop-work',
+      types: ['shop.started', 'shop.notified'],
+      lane: () => 'shop',
+      run: async ({ event }) => {
+        // your work for event.type
+      },
+    },
+  ],
+})
+```
+
+`handlers` are gone: [consumers](/server/consumers) are the one way to react
+to events. Each entry of a handler table becomes a consumer that takes its
+type, with the same function as its `run`, and its `abortOn` if it had one. A
+lane belongs to one consumer, so entries that shared a lane become one consumer
+that takes all their types, with a lane function returning that lane. A
+consumer's name is its identity: its cursors, failures, and dead letters key
+on it, so pick names you'll keep.
+
+| Before | 0.21 |
+| --- | --- |
+| `createServer({ handlers })` | `createServer({ consumers })` |
+| `handler(entry)` | `{ name, types?, lane?, run }` in `consumers`, or `consumer({ contract, ... }).run(fn)` |
+| `Handler`, `HandlerEntry` | removed: `consumer()` types `run`'s context |
+| `Lane` | `ConsumerLane` |
+| `HandlerContext` | `ConsumerContext` |
+| `HandlerAppend` | `ConsumerAppend` |
+| `handlerContext()`, from `experimental-a2/ai` | `consumerContext()` |
+| `runWithHandlerContext`, from `experimental-a2/ai/server` | `runWithConsumerContext` |
+| `agent({ handlers })` | `agent({ consumers })` |
+| `session.redrive(index, { action })` | `session.redrive({ consumer, index }, { action })` |
+| `a2.append.source` = `handler` | `a2.append.source` = `consumer` |
+
+- **Dead letters name their consumer.** An event dead-letters for one
+  consumer, so each entry from `session.deadLetters()` carries `consumer`.
+  Pass it to `redrive` with the index. See
+  [Resolve a dead letter](/server/consumers#resolve-a-dead-letter).
+- **Agents take `consumers`.** Write them with `consumer()` against the agent's
+  contract, as in [Conversations](/agents/conversations). A consumer of an AI
+  event type runs beside the agent's own, so `agent()` no longer rejects one.
+- **Actors keep `actor({ handlers })`.** Nothing changes in an actor's code.
+- **A2's own consumers start with `a2.`** Actors and agents run on consumers
+  named `a2.actor`, `a2.actor.concurrent`, `a2.ai.metadata`, `a2.ai.control`,
+  `a2.ai.model`, and `a2.ai.tools`, which their dead letters name. Their event
+  ids are unchanged. Names starting with `a2.` are reserved.
+- **Telemetry.** Dashboards that filter `a2.append.source` on `handler` read
+  `consumer` instead. Each `a2.event` span also carries `a2.event.consumer`;
+  see [Telemetry](/reference/telemetry).
+- **Custom stores** implement the cursor contract: `cursors()`, `wakeLog`, and
+  the cursor-keyed claim, completion, failure, and redrive methods. See
+  [`A2Store`](/reference/server#a2store).
+
+## Postgres
+
+0.21 keeps each consumer's place in new tables, `a2_cursors` and
+`a2_lane_events`. Its `schema.sql` creates them, then drops the columns earlier
+releases dispatched by, and the `a2_schema` table 0.20 reads on a cold start.
+Earlier deployments can't run against the new tables, and 0.21 needs them.
+
+1. **Let earlier deployments finish their work.** Applying the schema drops
+   any work their handlers haven't finished, since 0.21 runs no handlers to
+   finish it. This query counts that work, dead letters included (retry or
+   skip those first, or accept that they're dropped):
+
+   ```sql
+   select count(*) from a2_events where processed_at is null
+   ```
+
+   It doesn't count timers. On [Vercel Queues](/schedulers/vercel-queues#deployments),
+   each one goes to the deployment that scheduled it, which can't write once
+   the schema is applied, so a timer still waiting then is lost. Let them fire,
+   or schedule the ones you need again on 0.21.
+
+2. **Apply 0.21's `schema.sql` while none of them is running**, as the role
+   your app connects with:
+   `node_modules/experimental-a2/sql/postgres/schema.sql`. Every event is
+   kept. There's no separate migration: the file is the whole schema, and
+   each statement creates what's missing or removes what an earlier release
+   used, so it brings a database from any release to 0.21 and changes nothing
+   when you apply it again.
+3. **Deploy 0.21.** Deployed before the schema, its queries that reach a
+   missing table throw `STORE_NOT_CONFIGURED`, naming the file, and the next
+   request after you apply it works, with no redeploy.
+
+0.21's `schema.sql` also creates a function, `a2_batch`, that each append,
+claim, completion, and `consume` poll runs through in one round trip. Applying
+the file creates it; with Drizzle, add it as a custom migration (see
+[With Drizzle](/stores/postgres#with-drizzle)). Without it, 0.21's writes throw
+`STORE_NOT_CONFIGURED`, naming `schema.sql`.
+
+0.21 also checks nothing up front: no schema version read before the first
+query. A query that finds a table or column missing, or that its role can't
+use, throws `STORE_NOT_CONFIGURED`, naming the file to apply or the grant to
+make. With Drizzle, `drizzle-schema.ts` shows the new tables; on a database
+that already has A2's tables, use `schema.sql` as the migration for them. See
+[With Drizzle](/stores/postgres#with-drizzle).
+
+## SQLite
+
+A file an earlier release wrote throws `STORE_NOT_CONFIGURED` when the store
+opens it. Delete it, `.a2/dev.db` by default, or pass another `path`. Its
+sessions don't carry over.
+
+## Redis
+
+0.21 keeps each consumer's place in keys of its own, and reads the log,
+snapshots, and clears that earlier releases wrote as they are. Keep your
+`keyPrefix`.
+
+1. **Let earlier deployments finish their work, then stop them.** 0.21 runs
+   no handlers, so the work theirs haven't finished, dead letters included, is
+   dropped. An earlier deployment still running beside 0.21 keeps its own lanes
+   on the same prefix, so one lane's events can run on both at once. On
+   [Vercel Queues](/schedulers/vercel-queues#deployments) it also keeps
+   receiving the timers it scheduled, until they fire: let them, or remove the
+   deployment and schedule the ones you need again on 0.21.
+2. **Deploy 0.21.** Every event is kept. A consumer starts at the next event
+   appended, or with `backfill` at the beginning of the log.
+
+The keys earlier releases dispatched by (`meta`, `meta:{n}`, `meta-split`,
+`pending`, `ready`, `snapshot-pins:{n}`, `snapshot-pin-counts`, under each
+session) stay until you delete them; 0.21 never reads them.
+
+## Memory
+
+Nothing to do: the memory store starts empty in every process.

package/docs/upgrades/80-0-20.mdx

@@ -0,0 +1,43 @@
+---
+title: '0.20'
+description: The Postgres store no longer creates its tables. You apply them, before you deploy.
+---
+
+## Postgres
+
+Before you deploy 0.20, apply the SQL its store needs,
+`node_modules/experimental-a2/sql/postgres/schema.sql`, once per database,
+however you run SQL against it. It creates only what's missing and leaves
+existing data alone, so it's safe on a database an earlier release set up, and
+the deployment running now keeps working against it, without waiting on its
+writes.
+
+- **Apply it as the role your app connects with.** It records a schema version
+  in a new `a2_schema` table, which the store reads on a cold start. If
+  another role applies it, grant your app's role `select` on it:
+
+  ```sql
+  grant select on a2_schema to your_app_role;
+  ```
+
+- **With `listenConnectionString`**, also apply
+  `sql/postgres/notifications.sql`. It installs the triggers the store used to
+  install for you.
+- **The app's role needs no DDL rights.** Read and write access to A2's tables
+  is enough.
+
+## If you deploy first
+
+The store throws `STORE_NOT_CONFIGURED` on its first query, naming the file to
+apply. Until you apply it, nothing is written: appends fail, and scheduled work
+waits. Vercel Queues keeps redelivering it, and the QStash scheduler hands each
+task to a later message, 30 seconds out and backing off to one day. The next
+call after you apply the file succeeds, with no redeploy.
+
+## Other stores
+
+Nothing to do. SQLite still creates its tables when it opens its file, and
+Redis creates its keys as it writes.
+
+Moving past 0.20 to 0.21 or later? Apply that release's `schema.sql` instead,
+the way [0.21](/upgrades/0-21) says. It drops `a2_schema`.

package/docs/upgrades/81-0-19.mdx

@@ -0,0 +1,33 @@
+---
+title: '0.19'
+description: An agent's log stores each message once, so agent sessions from earlier releases don't fold.
+---
+
+## Start new agent sessions
+
+0.19 stores each message's content once, in the `ai.control.requested` command
+that brought it in. The AI reducers advance to `a2.ai.state.v27`,
+`a2.ai.context.v7`, and `a2.ai.control.v6`, and a log written before 0.19
+doesn't fold: `reduceAIState()` and `deriveUIMessages()` throw on an
+`ai.message.created` that no command explains. Start new agent sessions after
+you deploy. Earlier sessions keep their events in history, but their state
+can't be read.
+
+## Payloads and types
+
+Code that reads the AI log directly changes with it:
+
+- **`ai.message.created`** records an admission as
+  `{ messageId, role, generate? }`, without the message.
+  `MessageCreatedPayload` takes no type argument.
+- **`ai.control.committed`** carries no message content. Queued inputs and
+  `AIState.active.input` are `InputRef`s, `{ id, role, generate, afterStepOf? }`,
+  and `ActiveTurn` takes no type argument. `AIState.inbox.items` keep their
+  `message`, now with `role`.
+
+## Provider tools under `fx()` and `pi()`
+
+`agent()` throws a `TypeError` when a provider-defined tool
+(`type: 'provider'`, such as a provider's web search) is passed with `fx()` or
+`pi()`. Before, both harnesses dropped it without a word, so the model never
+saw it. Take it out of those agents' `tools`.

package/docs/upgrades/82-0-18.mdx

@@ -0,0 +1,33 @@
+---
+title: '0.18'
+description: An agent's loop is its harness, and the AI SDK loop's options move into it.
+---
+
+## Move loop options into `harness`
+
+```ts server/assistant.ts
+import { agent } from 'experimental-a2/ai/server'
+
+export const assistant = agent({
+  name: 'support-agent',
+  model: 'openai/gpt-5.6-terra',
+  instructions: 'Help the customer. Be concise.',
+  harness: {
+    type: 'ai-sdk',
+    // generation, generate, compaction, and messageMetadata go here:
+    compaction: { thresholdTokens: 80_000 },
+  },
+})
+```
+
+`agent()` takes its loop as `harness`. The AI SDK's loop is the default,
+`{ type: 'ai-sdk' }`, and its options move into it: `generation`, `generate`,
+`compaction`, and `messageMetadata` are no longer top-level `agent()` options,
+and passing one there throws a `TypeError`. See
+[Harnesses](/agents/harnesses).
+
+## Models are AI Gateway IDs
+
+`model` is an AI Gateway model ID, or `ModelSettings` with one, under every
+harness. `agent()` no longer takes AI SDK provider model objects, and
+`HarnessModelSettings` is gone: use `ModelSettings`.

package/docs/upgrades/83-0-17.mdx

@@ -0,0 +1,69 @@
+---
+title: '0.17'
+description: Redis stores need a fresh key prefix, and agents are served with `agent()`.
+---
+
+## Redis: a fresh `keyPrefix`
+
+```ts server/store.ts
+import { redis } from 'experimental-a2/store-redis'
+
+export const store = redis({
+  url: process.env.REDIS_URL,
+  // a prefix no earlier release wrote under:
+  keyPrefix: 'a2-017',
+})
+```
+
+Both Redis stores change how they keep event ids and per-event metadata: one
+key per event id instead of one shared hash, and metadata in hashes of 1,000
+events. 0.17 no longer reads the shared id hash, and earlier releases can't
+see what 0.17 writes, so on a shared prefix a retry on either side can append
+a duplicate event, re-run work, or stall a lane. Switch to a fresh `keyPrefix`
+when you upgrade, and don't roll back to an earlier release on a prefix 0.17
+has written. Vercel Queues keeps running recovery and scheduled work on the
+deployment that published it for up to seven days, so earlier deployments keep
+touching their sessions after you upgrade.
+
+## Before you clear sessions
+
+0.17 adds [`session.clear()`](/contract/sessions#clearing-a-session). Upgrade
+every instance before you clear any session: an earlier release ignores the
+clear and can run cleared events in the new lifetime. Upgrade every scheduler
+route before you schedule clears, and don't roll back while clear tasks are
+pending.
+
+## Vercel Queues
+
+`vercelQueues({ scheduledAppends })` is replaced by
+`deploymentId?: string | null`: leave it out to deliver to the current
+deployment, pass a deployment ID to target one, or pass `null` for
+deploymentless delivery. It applies to every task, recovery included, so
+`null` makes recovery deploymentless too, unlike `'deploymentless'` did.
+Changing it doesn't move tasks already queued. A custom `QueueTransport.send`
+no longer takes a fourth routing argument. See
+[Deployments](/schedulers/vercel-queues#deployments).
+
+## Agents
+
+| Before | 0.17 |
+| --- | --- |
+| `createAgentServer({ agent: definition, ... })` | `agent({ name, ... })`, or `agent({ contract, ... })` with a shared contract |
+| `agent()` from `experimental-a2/ai` | `agentContract()` |
+| `createReducer()`, `reducerName` | `agentContract({ reducer })` |
+| `createHandlers()`, `authorizeAgentIngress` | removed: pass `handlers` and `events` to `agent()` |
+| `handlerContext(agent)` | `handlerContext()`, or `handlerContext(contract)` |
+| `request` in `generate` and `messageMetadata` | `event` |
+| `requestId` | `event.id` |
+| `responseMessageId` | `event.payload.responseMessageId` |
+
+- **`agent({ contract })` takes only an `agentContract()`.** Any other contract
+  throws. A fully custom contract is core A2, served by `createServer()`.
+- **Upgrade clients with the server.** A client from before 0.17 ignores the
+  new shape of streamed progress, so a response's output doesn't appear in it
+  until it reloads.
+- **Custom telemetry recorders** must accept the new span names: core claim
+  and commit spans, and `a2.ai.*`.
+
+0.21 later renames `handlers` to `consumers` and `handlerContext()` to
+`consumerContext()`; see [0.21](/upgrades/0-21).

package/docs/upgrades/meta.ts

@@ -0,0 +1,3 @@
+// A release's page is numbered 100 minus its minor version (79-0-21.mdx for
+// 0.21), so the newest sorts first without renaming the others.
+export default { order: 9 }

package/examples/playground/DEPLOY.md

@@ -24,13 +24,31 @@ Redis, poll cadence elsewhere. Upstash is durable by default; use its TCP
 `rediss://` URL, not the REST one. Each feature creates its own server with
 the shared store; storage remains namespaced per contract. Without either variable, a
 production boot fails fast with `STORE_NOT_CONFIGURED` (by design).
-Redis needs no setup. With Postgres, create A2's tables once before the
-first deploy (A2 never creates them at runtime):
+Redis needs no setup. Postgres is migrated by every Vercel build: the
+`vercel-build` script runs `scripts/migrate.mjs` (Drizzle's migrator, which,
+unlike `drizzle-kit migrate`, prints the error when one fails) before the
+usual `turbo run build`, through `DATABASE_URL_UNPOOLED` when it's set (the Neon
+integration's direct connection). Previews and production share one database here, so a branch's
+migration reaches it when its preview builds: keep migrations additive.
+Elsewhere, migrate by hand (A2 never creates its tables at runtime):
 
 ```sh
-psql "$DATABASE_URL" -v ON_ERROR_STOP=1 -f node_modules/experimental-a2/sql/postgres/schema.sql
+DATABASE_URL=postgres://… pnpm --filter playground db:migrate
 ```
 
+It applies every migration in `app/a2slack/db/migrations`. A2's tables are in
+the Drizzle schema with a2slack's: `app/a2slack/db/a2.ts` is a copy of
+`experimental-a2`'s `sql/postgres/drizzle-schema.ts`. drizzle-kit generated
+their migration (`0002_a2.sql`) from it, and its SQL is `schema.sql`'s
+instead of the generated `CREATE TABLE`s, because the shared database already
+had A2's tables: it creates what's missing and upgrades the rest. Drizzle
+can't declare A2's `a2_batch` function, so `0003_a2_batch.sql` is a custom
+migration (`drizzle-kit generate --custom`) holding `schema.sql`'s block for
+it. When a
+release of `experimental-a2` changes its tables (its changelog says so),
+update `a2.ts` from the new file, run `pnpm db:generate`, and read the SQL it
+writes.
+
 To verify a provider before leaning on it, run the full conformance
 kit against it (throwaway database; the suite isolates by key prefix
 and sweeps after itself):
@@ -42,6 +60,19 @@ TEST_REDIS_URL=rediss://… pnpm --filter a2 exec vitest run test/store-redis.co
 `pg` and `ioredis` are optional peer dependencies of `experimental-a2` and direct
 dependencies of this app.
 
+a2slack keeps its tables in the Postgres at `DATABASE_URL`, defined with
+Drizzle in `app/a2slack/db/schema.ts`. With `REDIS_URL` set too, A2 runs on
+Redis and only a2slack's tables are used in Postgres (A2's are created there
+too, and stay empty). Generate a migration with `pnpm db:generate` after
+changing the schema; SQL drizzle-kit can't express, like an extension, goes
+in a custom one (`pnpm db:generate --custom --name …`).
+
+Its search index lives in Upstash Redis Search, through the Redis's REST
+credentials (`KV_REST_API_URL` and `KV_REST_API_TOKEN`, or this project's
+`REDIS_KV_REST_API_*`). The index is created the first time it's written.
+Without them, search reads the Postgres table instead. In development the
+tables live in PGlite at `.a2/a2slack`, migrated when it opens.
+
 ## 2. Vercel Queues scheduler
 
 Queues need no configuration beyond the triggers in `vercel.json`. A0, Orders,
@@ -153,10 +184,11 @@ vercel deploy
 ```
 
 The Recovery lab tests a real function timeout. Its dedicated trigger and
-queue consumer both export `maxDuration = 20`. The pipeline has four 8-second
-handlers, so every handler fits in a fresh invocation but the 32-second chain
-does not. A2 keeps dispatching events. Vercel stops the first invocation while
-the third handler is running, leaving that event without a processed marker.
+queue consumer both export `maxDuration = 20`. The pipeline is four 8-second
+steps, run in order by one A2 consumer, so every step fits in a fresh
+invocation but the 32-second chain does not. A2 keeps dispatching events.
+Vercel stops the first invocation while the third step is running, leaving
+the consumer's cursor on that event.
 The deadline-capped claim expires, its watchdog retries the same event in a
 fresh function, and already completed events do not run again. The dedicated
 `a2-recovery` topic keeps this artificial budget away from the

package/examples/playground/app/a0/chat.test.tsx

@@ -10,7 +10,7 @@ import {
   within,
 } from '@testing-library/react'
 import { tool } from 'ai'
-import { handlerContext, inputs } from 'experimental-a2/ai'
+import { consumerContext, inputs } from 'experimental-a2/ai'
 import { agent } from 'experimental-a2/ai/server'
 import type { A2Operation } from 'experimental-a2/server'
 import { memory } from 'experimental-a2/store-memory'
@@ -57,7 +57,7 @@ const tools = {
   bash: tool({
     inputSchema: z.object({ command: z.string() }),
     execute: async () => {
-      const { signal } = handlerContext()
+      const { signal } = consumerContext()
       await new Promise<void>((resolve, reject) => {
         void bashDone.promise.then(resolve)
         signal.addEventListener('abort', () => reject(signal.reason), {

package/examples/playground/app/a0/sandbox-log.ts

@@ -1,7 +1,7 @@
 import 'server-only'
 import { contract } from 'experimental-a2'
 import { vercelQueues } from 'experimental-a2/scheduler-vercel'
-import { createServer } from 'experimental-a2/server'
+import { consumer, createServer } from 'experimental-a2/server'
 import { z } from 'zod'
 import { store } from '@/lib/store'
 import { isAppId } from './apps'
@@ -31,24 +31,26 @@ export const sandboxScheduler =
     ? vercelQueues({ topic: 'a2-a0-sandboxes' })
     : undefined
 
+const deleteIdleSandbox = consumer({
+  contract: sandboxLog,
+  name: 'delete-idle-sandbox',
+  types: ['sandbox.idle.checked'],
+}).run(async ({ event }) => {
+  const { appId } = event.payload
+  // A prompt since the sandbox opened makes it a real app's, whichever
+  // harness's agent got it.
+  const reads = await Promise.all(
+    Object.values(agentServers).map((server) => server.session(appId).state()),
+  )
+  if (reads.every(({ state }) => state.messages.length === 0))
+    await deleteAppSandbox({ appId })
+})
+
 export const sandboxServer = createServer({
   ...(store ? { store } : {}),
   ...(sandboxScheduler ? { scheduler: sandboxScheduler } : {}),
   contract: sandboxLog,
-  handlers: {
-    'sandbox.idle.checked': async ({ event }) => {
-      const { appId } = event.payload
-      // A prompt since the sandbox opened makes it a real app's, whichever
-      // harness's agent got it.
-      const reads = await Promise.all(
-        Object.values(agentServers).map((server) =>
-          server.session(appId).state(),
-        ),
-      )
-      if (reads.every(({ state }) => state.messages.length === 0))
-        await deleteAppSandbox({ appId })
-    },
-  },
+  consumers: [deleteIdleSandbox],
 })
 
 /**