experimental-a2 0.20.0 → 0.22.0

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],
 })
 
 /**

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

@@ -68,6 +68,7 @@ async function openApp(appId: string): Promise<Sandbox> {
       persistent: true,
       snapshotExpiration: SNAPSHOT_EXPIRATION_MS,
       keepLastSnapshots: { count: 1 },
+      onResume: startDev,
     })
   } catch (error) {
     // Another instance created it first. The API holds a racing create until
@@ -81,8 +82,54 @@ async function openApp(appId: string): Promise<Sandbox> {
   return sandbox
 }
 
-// Parallel tool calls on a new app share one create within this instance.
-const opening = new Map<string, Promise<Sandbox>>()
+// Each instance keeps one handle per app, so parallel tool calls share an
+// open and later ones skip the lookup. A handle resumes a stopped session on
+// its next call; a deleted sandbox fails with a 404 until it's forgotten.
+// An empty app's idle check deletes its sandbox from whichever instance runs
+// it, 10 minutes after the sandbox opened. By then the session's 15 minutes
+// leave less than KEEP_ALIVE_MS, so every call extends it, and the extension's
+// 404 is how a kept handle finds out.
+const handles = new Map<string, Promise<Sandbox>>()
+const MAX_HANDLES = 100
+
+const forget = (appId: string): void => {
+  handles.delete(appId)
+}
+
+const open = (appId: string): Promise<Sandbox> => {
+  const opened = openApp(appId)
+  opened.catch(() => {
+    if (handles.get(appId) === opened) forget(appId)
+  })
+  return opened
+}
+
+const kept = (appId: string): Promise<Sandbox> => {
+  const pending = handles.get(appId) ?? open(appId)
+  // Most recently used last, so the cap drops the stalest.
+  handles.delete(appId)
+  handles.set(appId, pending)
+  const stalest = handles.keys().next().value
+  if (handles.size > MAX_HANDLES && stalest !== undefined) forget(stalest)
+  return pending
+}
+
+/**
+ * Whether the sandbox is still there. Extends it only by the shortfall, so
+ * repeated calls never stack up time.
+ */
+const keepAlive = async (sandbox: Sandbox): Promise<boolean> => {
+  const shortfall =
+    Date.now() + KEEP_ALIVE_MS - (sandbox.expiresAt?.getTime() ?? 0)
+  if (shortfall <= 0) return true
+  try {
+    await sandbox.extendTimeout(shortfall)
+  } catch (error) {
+    // Throws past the plan's session limit; the sandbox still works until then.
+    return !notFound(error)
+  }
+  return true
+}
 
 /** The app's sandbox, created or resumed, and kept up while it's used. */
 export async function appSandbox({
@@ -90,16 +137,13 @@ export async function appSandbox({
 }: {
   appId: string
 }): Promise<Sandbox> {
-  const pending =
-    opening.get(appId) ?? openApp(appId).finally(() => opening.delete(appId))
-  opening.set(appId, pending)
+  const pending = kept(appId)
   const sandbox = await pending
-  // Extends only by the shortfall, so repeated calls never stack up time.
-  const shortfall =
-    Date.now() + KEEP_ALIVE_MS - (sandbox.expiresAt?.getTime() ?? 0)
-  // Throws past the plan's session limit; the sandbox still works until then.
-  if (shortfall > 0) await sandbox.extendTimeout(shortfall).catch(() => {})
-  return sandbox
+  if (await keepAlive(sandbox)) return sandbox
+  if (handles.get(appId) === pending) forget(appId)
+  const reopened = await kept(appId)
+  await keepAlive(reopened)
+  return reopened
 }
 
 // A server that's booting refuses connections for a moment, and a page
@@ -118,12 +162,12 @@ export async function ensureApp({
   appId: string
 }): Promise<{ up: boolean; createdAt: Date }> {
   const sandbox = await appSandbox({ appId })
-  const probe = await sandbox.runCommand({
+  const answer = await sandbox.runCommand({
     cmd: 'bash',
     args: ['-c', `${START_DEV}; ${PROBE}`],
   })
   return {
-    up: Number(await probe.stdout()) > 0,
+    up: Number(await answer.stdout()) > 0,
     createdAt: sandbox.createdAt,
   }
 }
@@ -145,6 +189,7 @@ export async function deleteAppSandbox({
 }: {
   appId: string
 }): Promise<void> {
+  forget(appId)
   try {
     const sandbox = await Sandbox.get({
       name: sandboxName(appId),

package/examples/playground/app/a0/server.ts

@@ -1,7 +1,7 @@
 import 'server-only'
 import { waitUntil } from '@vercel/functions'
 import { tool } from 'ai'
-import { handlerContext } from 'experimental-a2/ai'
+import { consumerContext } from 'experimental-a2/ai'
 import { fx } from 'experimental-a2/ai/fx'
 import { pi } from 'experimental-a2/ai/pi'
 import { agent } from 'experimental-a2/ai/server'
@@ -55,7 +55,7 @@ const tools = {
     execute: ({ path }) =>
       timed(async () =>
         previewUrl({
-          sandbox: await appSandbox({ appId: handlerContext().session.id }),
+          sandbox: await appSandbox({ appId: consumerContext().session.id }),
           path,
         }),
       ),
@@ -68,7 +68,7 @@ const tools = {
       timeoutSeconds: z.number().int().min(1).max(240).default(120),
     }),
     execute: ({ command, timeoutSeconds }) => {
-      const context = handlerContext()
+      const context = consumerContext()
       return timed(async () =>
         bash({
           sandbox: await appSandbox({ appId: context.session.id }),
@@ -190,7 +190,7 @@ export const listServer = createServer({
   contract: appList,
 })
 
-/** The dev tools' crash logs, one per app. They have no handlers. */
+/** The dev tools' crash logs, one per app. They have no consumers. */
 export const crashServer = createServer({
   ...(store ? { store } : {}),
   contract: crashLog,