experimental-a2 0.19.0 → 0.21.1

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

@@ -1,6 +1,6 @@
 import 'server-only'
 import { vercelQueues } from 'experimental-a2/scheduler-vercel'
-import { createServer } from 'experimental-a2/server'
+import { consumer, createServer } from 'experimental-a2/server'
 import { store } from '@/lib/store'
 import { recovery } from './model'
 
@@ -15,39 +15,30 @@ export const recoveryScheduler =
     ? vercelQueues({ topic: 'a2-recovery' })
     : undefined
 
+/** Each step waits its 8 seconds, then returns the next one, in one lane. */
+const runPipeline = consumer({
+  contract: recovery,
+  name: 'run-pipeline',
+  types: ['pipeline.started', 'step.completed'],
+  lane: 'pipeline',
+}).run(async ({ event }) => {
+  const step = event.type === 'step.completed' ? event.payload.step : 0
+  if (step === stepCount) {
+    return {
+      type: 'pipeline.completed',
+      payload: { stepCount },
+    }
+  }
+  await wait(stepDurationSeconds * 1_000)
+  return {
+    type: 'step.completed',
+    payload: { step: step + 1, durationSeconds: stepDurationSeconds },
+  }
+})
+
 export const recoveryServer = createServer({
   ...(store ? { store } : {}),
   ...(recoveryScheduler ? { scheduler: recoveryScheduler } : {}),
   contract: recovery,
-  handlers: {
-    'pipeline.started': {
-      lane: 'pipeline',
-      handler: async () => {
-        await wait(stepDurationSeconds * 1_000)
-        return {
-          type: 'step.completed',
-          payload: { step: 1, durationSeconds: stepDurationSeconds },
-        }
-      },
-    },
-    'step.completed': {
-      lane: 'pipeline',
-      handler: async ({ event }) => {
-        if (event.payload.step === stepCount) {
-          return {
-            type: 'pipeline.completed',
-            payload: { stepCount },
-          }
-        }
-        await wait(stepDurationSeconds * 1_000)
-        return {
-          type: 'step.completed',
-          payload: {
-            step: event.payload.step + 1,
-            durationSeconds: stepDurationSeconds,
-          },
-        }
-      },
-    },
-  },
+  consumers: [runPipeline],
 })

package/examples/playground/drizzle.config.ts

@@ -0,0 +1,14 @@
+// The Postgres at DATABASE_URL: a2slack's tables, and A2's (db/a2.ts, a copy
+// of experimental-a2's drizzle-schema.ts). tablesFilter keeps push and
+// studio to these, since other apps share the database.
+import { defineConfig } from 'drizzle-kit'
+
+export default defineConfig({
+  dialect: 'postgresql',
+  schema: './app/a2slack/db/schema.ts',
+  out: './app/a2slack/db/migrations',
+  casing: 'snake_case',
+  dbCredentials: { url: process.env.DATABASE_URL ?? '' },
+  tablesFilter: ['a2slack_*', 'a2_*'],
+  migrations: { table: 'a2slack_migrations', schema: 'public' },
+})

package/examples/playground/next.config.ts

@@ -12,7 +12,12 @@ const nextConfig: NextConfig = {
   // Turbopack panic on its WebAssembly), so it finds photon through this
   // app: package.json depends on photon at the version Pi pins, and the two
   // move together.
-  serverExternalPackages: ['libfx', '@silvia-odwyer/photon-node'],
+  serverExternalPackages: [
+    'libfx',
+    '@silvia-odwyer/photon-node',
+    // a2slack's development database, PGlite, loads its WebAssembly by path.
+    '@electric-sql/pglite',
+  ],
   turbopack: {
     // WebAssembly Pi's code reaches that the bundler cannot trace.
     resolveAlias: {

package/examples/playground/package.json

@@ -11,18 +11,26 @@
   "scripts": {
     "dev": "next dev",
     "build": "next build",
+    "vercel-build": "node scripts/migrate.mjs && turbo run build",
     "test": "vitest run",
+    "drills": "vitest run --config vitest.drills.config.ts",
     "typecheck": "tsc --noEmit",
+    "db:generate": "drizzle-kit generate",
+    "db:migrate": "node scripts/migrate.mjs",
     "a0:template": "node --env-file-if-exists=.env.local scripts/a0-template.ts"
   },
   "dependencies": {
     "@ai-sdk/otel": "1.0.58",
+    "@base-ui/react": "^1.7.0",
     "@codemirror/state": "^6.7.1",
     "@codemirror/view": "^6.43.8",
+    "@electric-sql/pglite": "^0.3.14",
     "@earendil-works/pi-ai": "1.0.3",
     "@earendil-works/pi-coding-agent": "1.0.2",
     "@opentelemetry/api": "^1.9.0",
+    "@paper-design/shaders-react": "^0.0.80",
     "@silvia-odwyer/photon-node": "0.3.4",
+    "@upstash/redis": "^1.39.0",
     "@vercel/blob": "^2.8.0",
     "@vercel/functions": "^3.9.3",
     "@vercel/otel": "^2.1.0",
@@ -30,7 +38,8 @@
     "@vercel/sandbox": "^3.0.0",
     "ai": "^7.0.58",
     "codemirror": "^6.0.2",
-    "experimental-a2": "0.19.0",
+    "drizzle-orm": "^0.45.3",
+    "experimental-a2": "0.21.1",
     "geist": "^1.7.2",
     "ioredis": "^5.9.0",
     "libfx": "0.0.12",
@@ -52,10 +61,13 @@
     "@testing-library/react": "^16.1.0",
     "jsdom": "^26.0.0",
     "@types/node": "^24.0.0",
+    "@types/pg": "^8.15.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "@types/ws": "^8.18.1",
+    "drizzle-kit": "^0.31.11",
     "typescript": "^7.0.2",
+    "undici": "^8.10.2",
     "vitest": "^4.1.10"
   }
 }

package/examples/playground/scripts/migrate.mjs

@@ -0,0 +1,31 @@
+/**
+ * Applies app/a2slack/db/migrations to the Postgres at DATABASE_URL_UNPOOLED
+ * (the Neon integration's direct connection) or DATABASE_URL. drizzle-kit
+ * migrate does the same, but hides the database's error when one fails.
+ *
+ *   DATABASE_URL=postgres://… pnpm --filter playground db:migrate
+ */
+import { drizzle } from 'drizzle-orm/node-postgres'
+import { migrate } from 'drizzle-orm/node-postgres/migrator'
+
+const url = process.env.DATABASE_URL_UNPOOLED || process.env.DATABASE_URL
+if (!url) {
+  console.error('error: set DATABASE_URL to the Postgres to migrate')
+  process.exit(1)
+}
+
+const db = drizzle({ connection: url })
+try {
+  await migrate(db, {
+    migrationsFolder: new URL('../app/a2slack/db/migrations', import.meta.url)
+      .pathname,
+    migrationsTable: 'a2slack_migrations',
+    migrationsSchema: 'public',
+  })
+  console.log('migrations applied')
+} catch (error) {
+  console.error('error: migrations failed, and none were applied:', error)
+  process.exitCode = 1
+} finally {
+  await db.$client.end()
+}

package/examples/playground/test/agent.ts

@@ -0,0 +1,35 @@
+import { agent } from 'experimental-a2/ai/server'
+import { memory } from 'experimental-a2/store-memory'
+import { demoAgent } from '@/app/agent/model'
+import { authorizer, serve } from './serve'
+
+/**
+ * The playground's agent on a memory store, served where the page's own
+ * client finds it: `/agent/events` on the origin relative URLs resolve
+ * against. Its tests never start a turn, so its model never runs.
+ */
+export async function serveAgent() {
+  const server = agent({
+    contract: demoAgent,
+    store: memory(),
+    model: 'test-model',
+  })
+  const probe = authorizer()
+  const served = await serve({
+    routes: {
+      '/agent/events': (request) =>
+        server.fetch(request, { authorize: probe.authorize }),
+    },
+  })
+  return {
+    server,
+    probe,
+    url: `${served.origin}/agent/events`,
+    close: async (): Promise<void> => {
+      probe.release()
+      await served.close()
+    },
+  }
+}
+
+export type ServedAgent = Awaited<ReturnType<typeof serveAgent>>

package/examples/playground/test/model.ts

@@ -0,0 +1,149 @@
+/**
+ * The model behind an agent under test. Agents take AI Gateway model IDs;
+ * the AI SDK's global provider serves every one of them from this model,
+ * whose steps the test writes part by part.
+ */
+
+import { MockLanguageModelV4 } from 'ai/test'
+import { vi } from 'vitest'
+
+export type StreamPart =
+  Awaited<
+    ReturnType<MockLanguageModelV4['doStream']>
+  >['stream'] extends ReadableStream<infer Part>
+    ? Part
+    : never
+
+export type CallOptions = MockLanguageModelV4['doStreamCalls'][number]
+
+/** One model step, open until the test ends it or the agent aborts it. */
+export type ModelStep = {
+  /** What the agent sent the model for this step. */
+  options: CallOptions
+  write(...parts: StreamPart[]): void
+  /** Ends the step the way a model does: with a finish part. */
+  finish(reason?: 'stop' | 'tool-calls'): void
+}
+
+const usage = {
+  inputTokens: { total: 1, noCache: 1, cacheRead: 0, cacheWrite: 0 },
+  outputTokens: { total: 1, text: 1, reasoning: 0 },
+}
+
+/** A text part, whole. */
+export const say = ({ id, text }: { id: string; text: string }) =>
+  [
+    { type: 'text-start', id },
+    { type: 'text-delta', id, delta: text },
+    { type: 'text-end', id },
+  ] satisfies StreamPart[]
+
+/** A tool call whose input streams in as the given chunks of its JSON. */
+export const toolCall = ({
+  id,
+  name,
+  chunks,
+}: {
+  id: string
+  name: string
+  chunks: string[]
+}) =>
+  [
+    { type: 'tool-input-start', id, toolName: name },
+    ...chunks.map((delta) => ({
+      type: 'tool-input-delta' as const,
+      id,
+      delta,
+    })),
+    { type: 'tool-input-end', id },
+    {
+      type: 'tool-call',
+      toolCallId: id,
+      toolName: name,
+      input: chunks.join(''),
+    },
+  ] satisfies StreamPart[]
+
+let models = 0
+
+/**
+ * Installs a model the test drives step by step, served for `id` alone, so
+ * an agent left over from an earlier test can't take its steps. Remove it
+ * with `vi.unstubAllGlobals()`.
+ */
+export function testModel({
+  id = `test-model-${++models}`,
+}: {
+  /** The model ID the agent asks for. */
+  id?: string
+} = {}): {
+  /** The agent's `model`. */
+  id: string
+  /** Every step the agent asked for, in order. */
+  steps: ModelStep[]
+  /** The `n`th step (from 0), once the agent asks for it. */
+  step(n: number): Promise<ModelStep>
+  /** Ends every step still open, and each one asked for from now on. */
+  close(): void
+} {
+  const steps: ModelStep[] = []
+  const arrivals: PromiseWithResolvers<ModelStep>[] = []
+  const arrival = (n: number): PromiseWithResolvers<ModelStep> =>
+    (arrivals[n] ??= Promise.withResolvers<ModelStep>())
+  const ends: (() => void)[] = []
+  let closed = false
+  const model = new MockLanguageModelV4({
+    modelId: id,
+    doStream: async (options) => {
+      let controller!: ReadableStreamDefaultController<StreamPart>
+      let open = true
+      const end = (): void => {
+        if (!open) return
+        open = false
+        controller.close()
+      }
+      const stream = new ReadableStream<StreamPart>({
+        start(value) {
+          controller = value
+          controller.enqueue({ type: 'stream-start', warnings: [] })
+        },
+      })
+      options.abortSignal?.addEventListener('abort', end, { once: true })
+      const step: ModelStep = {
+        options,
+        write(...parts) {
+          for (const part of parts) if (open) controller.enqueue(part)
+        },
+        finish(reason = 'stop') {
+          step.write({
+            type: 'finish',
+            finishReason: { unified: reason, raw: reason },
+            usage,
+          })
+          end()
+        },
+      }
+      ends.push(end)
+      arrival(steps.length).resolve(step)
+      steps.push(step)
+      if (closed) step.finish()
+      return { stream }
+    },
+  })
+  vi.stubGlobal('AI_SDK_DEFAULT_PROVIDER', {
+    specificationVersion: 'v4',
+    languageModel: (requested: string) => {
+      if (requested !== id) throw new Error(`no test model '${requested}'`)
+      return model
+    },
+  })
+  return {
+    id,
+    steps,
+    step: (n) => arrival(n).promise,
+    close: () => {
+      closed = true
+      for (const end of ends) end()
+    },
+  }
+}

package/examples/playground/test/serve.ts

@@ -0,0 +1,184 @@
+/**
+ * A real HTTP server for the app's route handlers, so the browser's clients
+ * reach A2 servers over the actual wire format.
+ */
+
+import { createServer, type ServerResponse } from 'node:http'
+import type { AddressInfo, Socket } from 'node:net'
+import type { A2Operation } from 'experimental-a2/server'
+import { setGlobalOrigin } from 'undici'
+
+type Handler = (request: Request) => Response | Promise<Response>
+
+export type Served = {
+  /** Where the server listens; relative URLs resolve against it until it closes. */
+  origin: string
+  close(): Promise<void>
+}
+
+const writeResponse = async (
+  res: ServerResponse,
+  response: Response,
+): Promise<void> => {
+  res.writeHead(response.status, Object.fromEntries(response.headers.entries()))
+  res.flushHeaders()
+  if (!response.body) {
+    res.end()
+    return
+  }
+  const reader = response.body.getReader()
+  // A disconnecting client must cancel the web stream, which closes the
+  // store subscription behind it.
+  res.on('close', () => {
+    reader.cancel().catch(() => {})
+  })
+  try {
+    for (;;) {
+      // oxlint-disable-next-line no-await-in-loop -- stream pump
+      const { done, value } = await reader.read()
+      if (done) break
+      res.write(value)
+    }
+    res.end()
+  } catch {
+    res.destroy()
+  }
+}
+
+/**
+ * Serves each route's handler at its path. The page and `fetch` resolve
+ * relative URLs, like a module-level client's `api`, against this server
+ * until it closes.
+ */
+export async function serve({
+  routes,
+}: {
+  routes: Readonly<Record<string, Handler>>
+}): Promise<Served> {
+  let origin = ''
+  const server = createServer((req, res) => {
+    void (async () => {
+      try {
+        const url = new URL(req.url ?? '/', origin)
+        const handler = routes[url.pathname]
+        if (handler === undefined) {
+          res.writeHead(404).end()
+          return
+        }
+        const chunks: Buffer[] = []
+        for await (const chunk of req) chunks.push(chunk as Buffer)
+        const request = new Request(url, {
+          method: req.method ?? 'GET',
+          headers: Object.entries(req.headers).flatMap(([name, value]) =>
+            value === undefined
+              ? []
+              : (Array.isArray(value) ? value : [value]).map(
+                  (item): [string, string] => [name, item],
+                ),
+          ),
+          ...(chunks.length === 0 ? {} : { body: Buffer.concat(chunks) }),
+        })
+        await writeResponse(res, await handler(request))
+      } catch (error) {
+        // A handler's bug answers as one, not as a dropped connection the
+        // client would retry.
+        if (res.headersSent) res.destroy()
+        else res.writeHead(500).end(String(error))
+      }
+    })()
+  })
+  // close() must never wait on a request a test parked.
+  const sockets = new Set<Socket>()
+  server.on('connection', (socket) => {
+    sockets.add(socket)
+    socket.on('close', () => sockets.delete(socket))
+  })
+  // The address clients use: on macOS, another process can bind 127.0.0.1 on
+  // a port this server holds on every address, and take its connections.
+  await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve))
+  const { port } = server.address() as AddressInfo
+  origin = `http://127.0.0.1:${port}`
+  setGlobalOrigin(origin)
+  // Vitest's jsdom environment exposes its JSDOM, which sets the page's URL.
+  ;(
+    globalThis as { jsdom?: { reconfigure(settings: { url: string }): void } }
+  ).jsdom?.reconfigure({ url: `${origin}/` })
+  return {
+    origin,
+    close: () =>
+      new Promise((resolve) => {
+        setGlobalOrigin(undefined)
+        for (const socket of sockets) socket.destroy()
+        server.close(() => resolve())
+      }),
+  }
+}
+
+type Match = (operation: A2Operation) => boolean
+
+export type Held = {
+  /** The parked operation, once it arrives. */
+  arrived: Promise<A2Operation>
+  allow(): void
+  deny(): void
+}
+
+/**
+ * An `authorize` for `server.fetch` that records every operation it sees,
+ * and can park or deny the next one a test names.
+ */
+export function authorizer(): {
+  authorize: (operation: A2Operation) => Promise<boolean>
+  /** Every operation so far, in arrival order. */
+  operations: A2Operation[]
+  /** Parks the next matching operation until the test decides it. */
+  hold(match: Match): Held
+  /** Denies the next matching operation. */
+  deny(match: Match): void
+  /** Forgets the rules not yet used, and denies what is still parked. */
+  release(): void
+} {
+  const operations: A2Operation[] = []
+  const rules: {
+    match: Match
+    decide: (operation: A2Operation) => Promise<boolean>
+  }[] = []
+  const parked = new Set<Held>()
+  return {
+    operations,
+    authorize: async (operation) => {
+      operations.push(operation)
+      const at = rules.findIndex((rule) => rule.match(operation))
+      return at === -1 || rules.splice(at, 1)[0]!.decide(operation)
+    },
+    hold(match) {
+      const arrival = Promise.withResolvers<A2Operation>()
+      const decision = Promise.withResolvers<boolean>()
+      const decide = (allowed: boolean): void => {
+        parked.delete(held)
+        decision.resolve(allowed)
+      }
+      const held: Held = {
+        arrived: arrival.promise,
+        allow: () => decide(true),
+        deny: () => decide(false),
+      }
+      parked.add(held)
+      rules.push({
+        match,
+        decide: (operation) => {
+          arrival.resolve(operation)
+          return decision.promise
+        },
+      })
+      return held
+    },
+    deny(match) {
+      rules.push({ match, decide: async () => false })
+    },
+    release() {
+      rules.length = 0
+      for (const held of parked) held.deny()
+    },
+  }
+}

package/examples/playground/test/server-only.ts

@@ -0,0 +1 @@
+export {}

package/examples/playground/vercel.json

@@ -71,6 +71,15 @@
           "retryAfterSeconds": 30
         }
       ]
+    },
+    "app/a2slack/scheduler/route.ts": {
+      "experimentalTriggers": [
+        {
+          "type": "queue/v2beta",
+          "topic": "a2-a2slack",
+          "retryAfterSeconds": 30
+        }
+      ]
     }
   }
 }

package/examples/playground/vitest.config.ts

@@ -0,0 +1,27 @@
+import { fileURLToPath } from 'node:url'
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  resolve: {
+    tsconfigPaths: true,
+    alias: {
+      'server-only': fileURLToPath(
+        new URL('./test/server-only.ts', import.meta.url),
+      ),
+    },
+  },
+  test: {
+    // The app's servers run in-process: with no store URL they use A2's
+    // memory store, never a database a dev shell points at, and with no
+    // queues their work drains in the background of the append. Without
+    // credentials, nothing can reach the AI Gateway.
+    env: {
+      REDIS_URL: '',
+      DATABASE_URL: '',
+      VERCEL: '',
+      A2_QUEUES: '',
+      AI_GATEWAY_API_KEY: '',
+      VERCEL_OIDC_TOKEN: '',
+    },
+  },
+})

package/examples/playground/vitest.drills.config.ts

@@ -0,0 +1,32 @@
+// The a2slack drills (app/a2slack/drills): load, rebuild, and failure runs
+// against a throwaway Redis and Postgres they start themselves. Not part of
+// `pnpm test`; run them with `pnpm drills`.
+import { fileURLToPath } from 'node:url'
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  resolve: {
+    tsconfigPaths: true,
+    alias: {
+      'server-only': fileURLToPath(
+        new URL('./test/server-only.ts', import.meta.url),
+      ),
+    },
+  },
+  test: {
+    include: ['app/a2slack/drills/*.drill.ts'],
+    fileParallelism: false,
+    testTimeout: 15 * 60_000,
+    hookTimeout: 120_000,
+    env: {
+      VERCEL: '',
+      A2_QUEUES: '',
+      AI_GATEWAY_API_KEY: '',
+      VERCEL_OIDC_TOKEN: '',
+      KV_REST_API_URL: '',
+      KV_REST_API_TOKEN: '',
+      REDIS_KV_REST_API_URL: '',
+      REDIS_KV_REST_API_TOKEN: '',
+    },
+  },
+})

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "experimental-a2",
-  "version": "0.19.0",
+  "version": "0.21.1",
   "description": "Syncs your immutable event log, from server to browser: one contract, handlers, derived state, and a live client per session.",
   "license": "MIT",
   "type": "module",
@@ -21,6 +21,7 @@
     "dist",
     "docs",
     "examples",
+    "sql",
     "src",
     "AGENTS.md",
     "CHANGELOG.md",
@@ -112,6 +113,9 @@
   },
   "devDependencies": {
     "@electric-sql/pglite": "^0.3.14",
+    "experimental-a2-0-20": "npm:experimental-a2@0.20.0",
+    "drizzle-kit": "^0.31.11",
+    "drizzle-orm": "^0.45.3",
     "@upstash/qstash": "^2.11.3",
     "ai": "^7.0.58",
     "ioredis": "^5.9.0",
@@ -120,6 +124,7 @@
     "@types/ws": "^8.18.1",
     "@vercel/queue": "^0.2.0",
     "pg": "^8.16.0",
+    "postgres": "^3.4.9",
     "ws": "^8.21.3",
     "@testing-library/react": "^16.1.0",
     "@types/react": "^19.0.0",
@@ -144,7 +149,7 @@
   "scripts": {
     "build": "tsdown",
     "dev": "tsdown --watch",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.reference.json",
     "test": "vitest run",
     "test:watch": "vitest"
   }