experimental-a2 0.19.0 → 0.21.1

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

@@ -2,8 +2,9 @@
 
 The event log runs with zero setup in development (SQLite at `.a2/dev.db`,
 no scheduler). The Agent demo and A0 also need AI Gateway and Vercel Sandbox
-credentials. Production needs the deliberate pieces from
-`node_modules/experimental-a2/docs/server/05-production.mdx`.
+credentials. Production needs a store
+(`node_modules/experimental-a2/docs/stores/01-overview.mdx`) and a scheduler
+(`node_modules/experimental-a2/docs/schedulers/01-overview.mdx`).
 
 ## 1. A store
 
@@ -23,7 +24,30 @@ 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).
-Schemas/keys are created lazily on first use; no migration step.
+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
+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
@@ -36,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,
@@ -105,8 +142,8 @@ A sandbox stays up while it's used: each tool call keeps it running at least
 10 more minutes, and so does the preview while it's on screen. Otherwise it
 stops, and resumes with its files the next time it's needed. A new or resumed
 sandbox starts `next dev` in the background, so commands don't wait for it;
-the preview does. Deleting an app stops its turn and deletes its sandbox; its
-conversation stays in the log. An app nobody uses for 14 days loses its files.
+the preview does. Deleting an app clears its conversation from the log and
+deletes its sandbox. An app nobody uses for 14 days loses its files.
 
 App ids are the only access control: anyone with an A0 URL can open that app,
 and anyone who can reach the deployment can start new apps, each with its own
@@ -122,8 +159,7 @@ the project, which sets `BLOB_READ_WRITE_TOKEN`; `vercel env pull` brings it
 to local runs. Images go to the model with the message; other files go into
 its text as links, which the agent downloads in its sandbox. Each lives at an
 unguessable public URL under `a0/<app id>/`, which anyone with the URL can
-read. Nothing deletes them: the conversation that stays in the log still links
-them.
+read. Nothing deletes them, not even deleting their app.
 
 A0's dev tools have a Crash button, which ends the function instance running
 an app's agent, mid-turn, so the scheduler resumes the turn in a fresh one.
@@ -148,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/apps/[appId]/route.ts

@@ -1,11 +1,11 @@
-import { inputs } from 'experimental-a2/ai'
 import { isAppId } from '../../apps'
 import { deleteAppSandbox } from '../../sandbox'
 import { agentServers } from '../../server'
 
 /**
- * Stops the agent's current turn, so no later tool call brings the sandbox
- * back, then deletes it. The conversation stays in the A2 log.
+ * Deletes the app: its conversation, then its sandbox. A clear reads no
+ * state, so it also deletes a log this A2 can no longer fold, and no pending
+ * step of the old conversation runs to bring the sandbox back.
  */
 export async function DELETE(
   _request: Request,
@@ -14,14 +14,10 @@ export async function DELETE(
   const { appId } = await context.params
   if (!isAppId(appId))
     return Response.json({ error: 'Unknown app.' }, { status: 404 })
-  // The app's agent is whichever harness's agent has its log.
+  // Only one harness's agent has the app's log; clearing the others writes
+  // nothing.
   await Promise.all(
-    Object.values(agentServers).map(async (server) => {
-      const session = server.session(appId)
-      const { state } = await session.state()
-      if (state.active)
-        await session.append(...inputs.stop({ turnId: state.active.turnId }))
-    }),
+    Object.values(agentServers).map((server) => server.session(appId).clear()),
   )
   await deleteAppSandbox({ appId })
   return Response.json({ ok: true })