experimental-a2 0.19.0 → 0.20.0

package/docs/server/01-handlers.mdx

@@ -24,7 +24,7 @@ database, hit an API, or stream a model response. A2 claims the event while it
 runs and retries it after a crash.
 
 `createServer` from `experimental-a2/server` binds the contract to a
-[store](/server/production#1-choose-a-store) and one complete handler table,
+[store](/stores/overview) and one complete handler table,
 so a handler can't go missing because its module was never imported. Compose
 the table across files by spreading objects into `handlers`. It is the only
 entry point that touches a store, and it fails loudly in a browser bundle.
@@ -194,7 +194,34 @@ records completion runs the handler again.
 Throwing means "retry me." A2 records the failure and retries with backoff.
 The failed event blocks only its lane. After ten failed attempts it
 dead-letters and keeps blocking its lane until
-[you retry or skip it](/server/production#3-when-an-event-dead-letters).
+[you retry or skip it](#resolve-a-dead-letter).
 
 When someone presses stop, catch the abort and return normally instead. See
 [Cancellation](/server/cancellation).
+
+## Resolve a dead letter
+
+A [dead-lettered](/server/guarantees#when-a-handler-keeps-failing) event waits
+for you. List a session's dead letters, then retry or skip each one:
+
+```ts
+// anywhere on the server, behind your own operator checks:
+import { ordersServer } from '@/server'
+
+const order = ordersServer.session(orderId)
+const [dead] = await order.deadLetters()
+if (dead) {
+  // dead.lastError says why (null if every attempt timed out or crashed);
+  // deploy the handler fix first, then:
+  await order.redrive(dead.index, { action: 'retry' })
+}
+```
+
+- **Retry.** `{ action: 'retry' }` runs the handler again with a fresh
+  ten-failure budget. Once it completes, its lane continues.
+- **Skip.** `{ action: 'skip' }` marks the event processed without running it,
+  accepting that its effects never happen. The next event in its lane runs.
+
+Each redrive is one atomic store operation, and it wakes the session like an
+append, so the lane resumes without another write. An event that isn't
+dead-lettered anymore is left alone: `redrive` reports `{ redriven: false }`.

package/docs/server/02-timers.mdx

@@ -34,7 +34,7 @@ export const ordersServer = createServer({
 
 Configure a scheduler, then call `session.schedule(name, timing, ...events)`.
 The scheduler route that handles recovery delivers timers too;
-[mount it once](/server/production#2-add-a-scheduler-for-handlers-and-timers).
+[mount it once](/schedulers/overview).
 
 `timing` is `{ delay }` (units `ms`, `s`, `m`, `h`, `d`, checked by the type)
 or `{ at: Date }`. A delay must be a finite, unsigned base-10 decimal above
@@ -103,7 +103,7 @@ If the receiving deployment changed or removed the event's schema, delivery
 can fail validation and then keeps retrying as a scheduler error. The Vercel
 adapter pins timers to their publishing deployment by default; with
 `deploymentId: null` or a stable URL like QStash's, keep schemas compatible.
-See [Deploy safely](/server/production#4-deploy-safely).
+See [Deploys and rollbacks](/schedulers/overview#deploys-and-rollbacks).
 
 ## Stale timers
 

package/docs/server/06-guarantees.mdx

@@ -71,7 +71,7 @@ up to two seconds for the watchdog send, never for handlers. A failed arm
 records `a2.append.armed = false` on the trace. Handler appends and returned
 events join the running drain and add no arm.
 
-[`append.dispatch`](/server/production#dispatch-in-a-fresh-invocation) skips
+[`append.dispatch`](/schedulers/overview#dispatch-in-a-fresh-invocation) skips
 the inline drain and hands the work to the scheduler instead.
 
 An event type without a handler settles in the append transaction. It starts
@@ -108,8 +108,11 @@ attempt takes its claim over. Ten failed attempts dead-letter the event: later
 events in its lane stay blocked, while unlaned events and other lanes continue.
 A crash costs every event it interrupts one attempt, so a session whose work
 keeps outrunning its function dead-letters: bound its fan-out, or put work that
-waits on the same resource in one lane. The event waits until you
-[retry or skip it](/server/production#3-when-an-event-dead-letters) with
+waits on the same resource in one lane. A `NonRetriableError`, or a returned
+batch the store refuses because it reuses an event id, dead-letters the event
+on that first attempt instead: a retry would fail the same way. The event
+waits until you
+[retry or skip it](/server/handlers#resolve-a-dead-letter) with
 `session.redrive()`.
 
 ## Limits

package/docs/stores/01-overview.mdx

@@ -0,0 +1,37 @@
+---
+title: Overview
+description: Where A2 keeps your session histories.
+---
+
+```ts server/orders.ts
+import { createServer } from 'experimental-a2/server'
+import { redis } from 'experimental-a2/store-redis'
+import { orders } from '@/contracts'
+
+export const ordersServer = createServer({
+  contract: orders,
+  store: redis({ url: process.env.REDIS_URL }),
+  handlers: {
+    /* ... */
+  },
+})
+```
+
+| Store | Use it for |
+| --- | --- |
+| [Redis](/stores/redis) | Production (recommended) |
+| [Redis over HTTP](/stores/redis-http) | Production, when your provider only offers a REST API |
+| [Postgres](/stores/postgres) | Production |
+| [SQLite](/stores/sqlite) | Development: the default |
+| [Memory](/stores/memory) | Tests: the default when `NODE_ENV=test` |
+
+When you omit `store`, development gets SQLite, so state survives `next dev`
+restarts, and tests get memory. Production has no default, on purpose: the
+server throws `STORE_NOT_CONFIGURED` at startup rather than write events to a
+filesystem that evaporates.
+
+A store holds A2's session histories. It doesn't connect A2 to your
+application tables; see
+[Sessions and your database](/contract/sessions#sessions-and-your-database).
+
+Servers with handlers or timers also need a [scheduler](/schedulers/overview).

package/docs/stores/02-redis.mdx

@@ -0,0 +1,49 @@
+---
+title: Redis
+description: The recommended production store. Live streams are pushed, not polled.
+---
+
+```ts server/orders.ts
+import { createServer } from 'experimental-a2/server'
+import { redis } from 'experimental-a2/store-redis'
+import { orders } from '@/contracts'
+
+export const ordersServer = createServer({
+  contract: orders,
+  store: redis({ url: process.env.REDIS_URL }),
+  handlers: {
+    /* ... */
+  },
+})
+```
+
+```package-install
+npm i ioredis
+```
+
+Works on a single Redis instance and on non-cluster providers such as Upstash,
+which is durable by default (use its TCP `rediss://` URL). There's nothing to
+set up: A2 creates its keys as it writes.
+
+## Options
+
+| Option | |
+| --- | --- |
+| `url` | creates an `ioredis` client |
+| `client` | your own `ioredis` client instead |
+| `keyPrefix` | isolates several apps on one Redis. Default `'a2'` |
+| `clock`, `ids` | test seams for timestamps and generated event ids |
+
+## How it works
+
+- Each session is a Redis Stream.
+- Every write publishes a wake-up, so live streams are push-driven, and
+  connections scale with your processes, not with your viewers.
+- A wake-up is disposable: a safety re-read recovers a lost one within ten
+  seconds.
+
+## Cost per command
+
+On providers that bill per command, such as Upstash, appending an event with a
+handler and running it takes 24 commands, and an idle live stream takes 6 a
+minute.

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

@@ -0,0 +1,56 @@
+---
+title: Redis over HTTP
+description: The same Redis store over fetch, for providers with only a REST API.
+---
+
+```ts server/orders.ts
+import { createServer } from 'experimental-a2/server'
+import { redisHttp } from 'experimental-a2/store-redis-http'
+import { orders } from '@/contracts'
+
+const url = process.env.UPSTASH_REDIS_REST_URL
+const token = process.env.UPSTASH_REDIS_REST_TOKEN
+if (!url || !token) throw new Error('set the Upstash REST URL and token')
+
+export const ordersServer = createServer({
+  contract: orders,
+  store: redisHttp({ url, token }),
+  handlers: {
+    /* ... */
+  },
+})
+```
+
+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.
+
+:::warning
+Live streams trust the messages on the store's `:notify` channels. Browsers
+never hold Redis credentials, so they can't reach those channels. The risk is a
+credential that can publish but not write, such as a token another service
+uses: it could add or hide events in live views. Grant publish access only to
+credentials that can also write the store.
+:::
+
+## Options
+
+| Option | |
+| --- | --- |
+| `url`, `token` | your provider's REST endpoint and token |
+| `keyPrefix` | isolates several apps on one Redis. Default `'a2'` |
+| `clock`, `ids` | test seams for timestamps and generated event ids |
+
+## Live updates
+
+- Live events and presence use Upstash's HTTP `SUBSCRIBE` endpoint, with the
+  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.
+- 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
+  gap, so presence may repeat its latest values.
+- If `SUBSCRIBE` answers 404, 405, or 501, the store polls instead, every 25ms
+  while busy and up to every two seconds when idle. Other errors stay errors.

package/docs/stores/04-postgres.mdx

@@ -0,0 +1,121 @@
+---
+title: Postgres
+description: Any Postgres database. You create A2's tables; A2 never changes your schema.
+---
+
+```ts server/orders.ts
+import { createServer } from 'experimental-a2/server'
+import { postgres } from 'experimental-a2/store-postgres'
+import { orders } from '@/contracts'
+
+export const ordersServer = createServer({
+  contract: orders,
+  store: postgres({ connectionString: process.env.DATABASE_URL }),
+  handlers: {
+    /* ... */
+  },
+})
+```
+
+```package-install
+npm i pg
+```
+
+Works with Neon, Supabase, RDS, or your own server, including transaction-mode
+poolers.
+
+## Create the tables
+
+A2 doesn't create 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.
+
+## Upgrade
+
+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.
+
+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.
+
+## Live updates (polling)
+
+By default, live streams poll every 25ms while a session is busy, backing off
+to every two seconds when it's quiet, so an update from another client can take
+up to two seconds, plus query latency, to reach a quiet stream. A client's own
+`push()` refreshes its stream immediately, even when the write and the stream
+run in different invocations.
+
+## Live updates (notifications)
+
+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`.
+
+Its triggers notify listeners of every write, including writes from stores
+without the option. Notifications arrive after commit, a reconnect catches up
+from the cursor, and subscriptions also reconcile every ten seconds. Every
+serverless instance opens its own direct connection, so leave connection
+headroom.
+
+## Use postgres.js
+
+`connectionString` creates a `pg` pool. To use
+[postgres.js](https://github.com/porsager/postgres) instead, wrap it as
+`client`:
+
+```ts server/store.ts
+import postgresJs from 'postgres'
+import { postgres } from 'experimental-a2/store-postgres'
+
+const url = process.env.DATABASE_URL
+if (!url) throw new Error('set DATABASE_URL')
+
+const sql = postgresJs(url, {
+  // A2 sends JSON as text; this keeps postgres.js from encoding it again.
+  types: {
+    json: {
+      to: 114,
+      from: [114, 3802],
+      serialize: (x: unknown) => (typeof x === 'string' ? x : JSON.stringify(x)),
+      parse: (x: string) => JSON.parse(x),
+    },
+  },
+})
+
+export const store = postgres({
+  client: {
+    query: async (text, values = []) => ({
+      rows: [...(await sql.unsafe(text, values))],
+    }),
+    connect: async () => {
+      const connection = await sql.reserve()
+      return {
+        query: async (text, values = []) => ({
+          rows: [...(await connection.unsafe(text, values))],
+        }),
+        release: () => connection.release(),
+      }
+    },
+    end: () => sql.end(),
+  },
+})
+```
+
+`listenConnectionString` still opens its listener with `pg`, so live
+notifications need `pg` installed too.
+
+## Options
+
+| Option | |
+| --- | --- |
+| `connectionString` | creates a `pg` pool, shared by stores with the same settings |
+| `client` | your own pool instead: a `pg` `Pool`, PGlite, or a pooler wrapper. Its lifecycle is yours |
+| `listenConnectionString` | a direct connection for notifications |
+| `clock`, `ids` | test seams for timestamps and generated event ids |

package/docs/stores/05-sqlite.mdx

@@ -0,0 +1,34 @@
+---
+title: SQLite
+description: The development default, in a file at `.a2/dev.db`.
+---
+
+```ts server/orders.ts
+import { createServer } from 'experimental-a2/server'
+import { sqlite } from 'experimental-a2/store-sqlite'
+import { orders } from '@/contracts'
+
+export const ordersServer = createServer({
+  contract: orders,
+  store: sqlite({ path: '.a2/orders.db' }),
+  handlers: {
+    /* ... */
+  },
+})
+```
+
+In development, a server without a `store` uses SQLite at `.a2/dev.db`, so
+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
+share one file across instances, so production needs another
+[store](/stores/overview).
+
+## Options
+
+| Option | |
+| --- | --- |
+| `path` | the database file. Default `.a2/dev.db`; `:memory:` works |
+| `clock`, `ids` | test seams for timestamps and generated event ids |

package/docs/stores/06-memory.mdx

@@ -0,0 +1,22 @@
+---
+title: Memory
+description: An in-process store for tests, the default when `NODE_ENV=test`.
+---
+
+```ts
+// in a test:
+import { createServer } from 'experimental-a2/server'
+import { memory } from 'experimental-a2/store-memory'
+import { orders } from '@/contracts'
+
+const ordersServer = createServer({ contract: orders, store: memory() })
+```
+
+Sessions live in the process and vanish when it exits. Under `NODE_ENV=test`, a
+server without a `store` already uses memory.
+
+## Options
+
+| Option | |
+| --- | --- |
+| `clock`, `ids` | test seams for timestamps and generated event ids |

package/docs/stores/meta.ts

@@ -0,0 +1 @@
+export default { order: 4 }

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,12 @@ 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. With Postgres, create A2's tables once before the
+first deploy (A2 never creates them at runtime):
+
+```sh
+psql "$DATABASE_URL" -v ON_ERROR_STOP=1 -f node_modules/experimental-a2/sql/postgres/schema.sql
+```
 
 To verify a provider before leaning on it, run the full conformance
 kit against it (throwaway database; the suite isolates by key prefix
@@ -105,8 +111,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 +128,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.

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 })