experimental-a2 0.20.0 → 0.22.0

package/docs/stores/03-redis-http.mdx

@@ -15,14 +15,15 @@ if (!url || !token) throw new Error('set the Upstash REST URL and token')
 export const ordersServer = createServer({
   contract: orders,
   store: redisHttp({ url, token }),
-  handlers: {
+  consumers: [
     /* ... */
-  },
+  ],
 })
 ```
 
 Stores sessions exactly like [Redis](/stores/redis), with no client dependency
-and nothing to set up. Use it when your provider only offers a REST API.
+and nothing to set up. Use it when your provider only offers a REST API. On
+Upstash, each script locks only its session's keys, never the whole database.
 
 :::warning
 Live streams trust the messages on the store's `:notify` channels. Browsers
@@ -37,7 +38,7 @@ credentials that can also write the store.
 | Option | |
 | --- | --- |
 | `url`, `token` | your provider's REST endpoint and token |
-| `keyPrefix` | isolates several apps on one Redis. Default `'a2'` |
+| `keyPrefix` | isolates several apps on one Redis. Default `'a2'`; no braces |
 | `clock`, `ids` | test seams for timestamps and generated event ids |
 
 ## Live updates
@@ -46,8 +47,9 @@ credentials that can also write the store.
   same URL and token. Each active channel holds one outbound HTTP subscription
   per store instance, shared by its viewers and closed when the last one
   leaves.
-- Writes publish their wake-ups in the same Redis script as the append. A
-  rejected notification doesn't fail the write.
+- Each write publishes its wake-up after its script commits, so a slow
+  subscriber never holds the script's lock. A rejected notification doesn't
+  fail the write.
 - Idle streams re-read every ten seconds to recover a missed notification.
   Subscriptions reconnect on their own and catch up from the event cursor.
 - After a reconnect, A2 re-reads presence and clears fields deleted during the

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 (session_id,
+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,31 @@
+---
+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.22](/upgrades/0-22) | Event ids are unique per session. Postgres: apply the new `schema.sql`, then deploy. Redis: use a new `keyPrefix`. |
+| [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/78-0-22.mdx

@@ -0,0 +1,115 @@
+---
+title: '0.22'
+description: Event ids are unique per session, not per store, and a presence clear keeps its stamp.
+---
+
+## Event ids are unique per session
+
+The same event id in two sessions is now two events. Before, appending an id
+that another session already used threw `PARTIAL_DUPLICATE_BATCH`. Inside one
+session nothing changes: an identical retry returns the original rows, a batch
+that mixes sent and fresh events throws, and a consumer's retried completion
+returns the events it committed.
+
+- **Ids you derive need only the session's scope.** An
+  [`idempotentId()`](/reference/core#idempotentidparts) recipe that includes
+  the session still works; one that leaves it out no longer collides with
+  another session's events.
+- **Idempotency keys built from ids.** `event.id` and an actor's `ctx.id` are
+  unique within their session. Ids your callers pick, and the ids A2 derives
+  from them, can now repeat in another session, so a key for an external side
+  effect built from one alone can too. When yours can repeat, add the session
+  to the key; see
+  [Consumers can run twice](/server/consumers#consumers-can-run-twice).
+- **Clear markers** follow the same rule.
+- **Custom stores** check ids against the session's own rows only: the
+  idempotent-replay and partial-batch checks in `append` and
+  `completeAttempt` ignore other sessions. See
+  [`A2Store`](/reference/server#a2store).
+
+## Postgres
+
+0.22's `schema.sql` replaces the unique index on `a2_events (event_id)`,
+`a2_events_event_id`, with one on `a2_events (session_id, event_id)`,
+`a2_events_session_event_id`. Every row is kept, and building the new index
+can't fail: the old one already keeps those pairs unique.
+
+1. **Apply 0.22's `schema.sql`**, as the role your app connects with:
+   `node_modules/experimental-a2/sql/postgres/schema.sql`.
+2. **Deploy 0.22.**
+
+The first time it runs, the swap locks `a2_events` against every read and write
+until the new index is built, then drops the old one. On a large table, make
+both changes by hand instead, with nothing blocked. Run each statement on its
+own, outside a transaction:
+
+```sql
+create unique index concurrently if not exists a2_events_session_event_id
+  on a2_events (session_id, event_id);
+```
+
+A concurrent build that fails leaves an invalid index of the same name behind.
+Check that this returns `true` before you drop the old index; if it doesn't,
+drop the new one and build it again:
+
+```sql
+select indisvalid from pg_index
+ where indexrelid = 'a2_events_session_event_id'::regclass;
+```
+
+```sql
+drop index concurrently if exists a2_events_event_id;
+```
+
+Then apply `schema.sql`: it finds both done and waits on nothing. It drops the
+old index only once the new one is valid.
+
+With Drizzle, update your copy of `drizzle-schema.ts`:
+`a2_events_session_event_id` on `(session_id, event_id)` replaces
+`a2_events_event_id`. On a large table, run the statements above by hand
+instead, and take them out of the migration Drizzle generates.
+
+## SQLite
+
+Nothing to do. The store creates the new index and drops the old one when it
+opens the file. Once 0.22 has opened a file, don't open it with an earlier
+release: that release builds the old index again, and can't open the file at
+all once two sessions share an id.
+
+## Redis
+
+Redis names every key differently in this release, so it starts fresh:
+**point the store at a new `keyPrefix`**, then deploy. Under its new prefix,
+0.22 never reads what an earlier release wrote; delete the old prefix's keys
+whenever convenient. On a prefix 0.21 wrote, 0.22 refuses to start with
+`STORE_NOT_CONFIGURED`. A `keyPrefix` can't contain braces.
+
+What changes:
+
+- **Scripts lock only their session on Upstash.** Every key of a session
+  shares one hash tag, so each script sets Upstash's `allow-key-locking` and
+  locks its session's keys instead of the whole database. The store asks the
+  server once whether it accepts the flag; Redis and Valkey don't, and run one
+  command at a time anyway.
+- **No script publishes.** Each write publishes its wake-up after its script,
+  so a slow subscriber never holds a lock.
+- **`clear()` works on Upstash.** It used to rename the log aside, which
+  Upstash refuses for streams. The marker now joins the same log, and the old
+  lifetime's entries stay below it, unread, until `clear()` finishes deleting
+  them. A session that stays empty after its clear keeps only its clear marker,
+  the log holding it, and its log consumers' positions.
+
+## Memory
+
+Nothing to do: the memory store starts empty in every process.
+
+## Presence clears keep their stamp
+
+A `null` from `setPresence()` now leaves a tombstone in the store, carrying the
+clear's `at`, until the field's TTL runs out. An older value that reaches the
+store after the clear, such as one sent through another server instance, still
+loses. Before, it brought the field back. Nothing to do: Postgres and SQLite
+keep tombstones in `a2_presence` as a JSON `null` value.
+
+Custom stores with presence keep a tombstone for each `null`, compare it by
+`at` like a value until it expires, and leave tombstones out of `read`.

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 }