experimental-a2 0.16.0 → 0.17.0

package/examples/playground/app/initial-state.test.tsx

@@ -0,0 +1,54 @@
+import type { ReactElement } from 'react'
+import { beforeEach, expect, it, vi } from 'vitest'
+import AgentPage from './agent/[agentId]/page'
+import ChatPage from './chat/[chatId]/page'
+
+const agentReads = vi.hoisted(() => ({
+  initial: { state: { agent: true }, index: 7 },
+  state: vi.fn<() => Promise<{ state: { agent: boolean }; index: number }>>(),
+  history: vi.fn<() => never>(),
+}))
+const reads = vi.hoisted(() => ({
+  initial: { state: { marker: true }, index: 42 },
+  state: vi.fn<() => Promise<{ state: { marker: boolean }; index: number }>>(),
+  history: vi.fn<() => never>(),
+}))
+vi.mock('./agent/server', () => ({ agentServer: { session: () => reads } }))
+vi.mock('./chat/server', () => ({
+  chatServer: { session: () => reads },
+  chatAgentServer: { session: () => agentReads },
+}))
+vi.mock('./agent/[agentId]/agent-client', () => ({ AgentClient: () => null }))
+vi.mock('./chat/[chatId]/chat-client', () => ({ ChatClient: () => null }))
+
+beforeEach(() => {
+  reads.state.mockReset().mockResolvedValue(reads.initial)
+  agentReads.state.mockReset().mockResolvedValue(agentReads.initial)
+  reads.history.mockReset().mockImplementation(() => {
+    throw new Error('unexpected history read')
+  })
+})
+
+it.each(['agent', 'chat'] as const)(
+  'seeds %s from one state read without fetching raw history',
+  async (page) => {
+    const element = (await (page === 'agent'
+      ? AgentPage({ params: Promise.resolve({ agentId: 'one' }) })
+      : ChatPage({
+          params: Promise.resolve({ chatId: 'one' }),
+        }))) as ReactElement<{ initial: unknown; initialEvents?: unknown }>
+    expect(reads.state).toHaveBeenCalledExactlyOnceWith()
+    expect(reads.history).not.toHaveBeenCalled()
+    expect(element.props.initial).toBe(reads.initial)
+    expect(element.props.initialEvents).toBeUndefined()
+  },
+)
+
+it("seeds the chat's agent session from its own state read", async () => {
+  const element = (await ChatPage({
+    params: Promise.resolve({ chatId: 'one' }),
+  })) as ReactElement<{ children: ReactElement<{ agentInitial: unknown }> }>
+  expect(agentReads.state).toHaveBeenCalledExactlyOnceWith()
+  expect(agentReads.history).not.toHaveBeenCalled()
+  expect(element.props.children.props.agentInitial).toBe(agentReads.initial)
+})

package/examples/playground/app/layout.tsx

@@ -1,6 +1,7 @@
-import type { Metadata } from 'next'
+import type { Metadata, Viewport } from 'next'
 import type { ReactNode } from 'react'
-import Link from 'next/link'
+import { GeistMono } from 'geist/font/mono'
+import { SiteHeader } from './components/site-header'
 import './globals.css'
 
 export const metadata: Metadata = {
@@ -9,35 +10,18 @@ export const metadata: Metadata = {
     'A durable event log for serverless apps — counters, agents, orders, streaming, cancellation, multiplayer documents, and a shared canvas.',
 }
 
+export const viewport: Viewport = { colorScheme: 'light dark' }
+
 export default function RootLayout({
   children,
 }: {
   children: ReactNode
 }): ReactNode {
   return (
-    <html lang="en">
+    <html lang="en" className={GeistMono.variable}>
       <body>
-        <header className="site-header">
-          <nav>
-            <Link href="/" className="brand">
-              a2 <span>example</span>
-            </Link>
-            <Link href="/orders">Orders</Link>
-            <Link href="/chat">Chat</Link>
-            <Link href="/agent">Agent</Link>
-            <Link href="/canvas">Canvas</Link>
-            <Link href="/documents">Documents</Link>
-            <Link href="/recovery">Recovery</Link>
-            <Link href="/counter">Counter</Link>
-          </nav>
-        </header>
+        <SiteHeader />
         <main>{children}</main>
-        <footer className="site-footer">
-          <p>
-            Everything on these pages is a fold over an append-only log — check{' '}
-            <code>.a2/dev.db</code>.
-          </p>
-        </footer>
       </body>
     </html>
   )

package/examples/playground/app/orders/[orderId]/page.tsx

@@ -20,8 +20,7 @@ export default async function OrderPage({
     <SessionProvider
       sessionId={decodeURIComponent(orderId)}
       api="/orders/events"
-      initialState={state}
-      initialIndex={index}
+      initial={{ state: state, index: index }}
     >
       <OrderClient sessionId={decodeURIComponent(orderId)} />
     </SessionProvider>

package/examples/playground/app/orders/[orderId]/session.ts

@@ -4,8 +4,8 @@
  * pair. Nothing in this file touches the machine module.
  */
 import { createReact } from 'experimental-a2/react'
-import { ordersReducer } from '../model'
+import { orders } from '../model'
 
 export const { SessionProvider, useSession } = createReact({
-  reducer: ordersReducer,
+  contract: orders,
 })

package/examples/playground/app/orders/model.ts

@@ -1,21 +1,6 @@
 import * as a2 from 'experimental-a2'
 import { z } from 'zod'
 
-export const orders = a2.contract({
-  name: 'orders',
-  events: {
-    created: z.object({
-      shopId: z.string(),
-      items: z.array(z.string()).min(1),
-    }),
-    'shop.notified': z.object({}),
-    'shop.started': z.object({}),
-    'driver.notified': z.object({ driverId: z.string() }),
-    'courier.picked_up': z.object({ etaMinutes: z.number().int().positive() }),
-    delivered: z.object({}),
-  },
-})
-
 const orderState = z.object({
   status: z.enum([
     'new',
@@ -34,8 +19,21 @@ const orderState = z.object({
 
 export type OrderState = z.output<typeof orderState>
 
-export const ordersReducer = orders
-  .reducer({
+export const orders = a2.contract({
+  name: 'orders',
+  events: {
+    created: z.object({
+      shopId: z.string(),
+      items: z.array(z.string()).min(1),
+    }),
+    'shop.notified': z.object({}),
+    'shop.started': z.object({}),
+    'driver.notified': z.object({ driverId: z.string() }),
+    'courier.picked_up': z.object({ etaMinutes: z.number().int().positive() }),
+    delivered: z.object({}),
+  },
+
+  reducer: {
     name: 'order-status',
     initialState: {
       status: 'new',
@@ -45,35 +43,37 @@ export const ordersReducer = orders
       etaMinutes: null,
     },
     stateSchema: orderState,
-  })
-  .fold((state, event) => {
-    switch (event.type) {
-      case 'created':
-        return {
-          ...state,
-          status: 'created',
-          shopId: event.payload.shopId,
-          items: event.payload.items,
-        }
-      case 'shop.notified':
-        return { ...state, status: 'notified' }
-      case 'shop.started':
-        return { ...state, status: 'preparing' }
-      case 'driver.notified':
-        return {
-          ...state,
-          status: 'courier-assigned',
-          driverId: event.payload.driverId,
-        }
-      case 'courier.picked_up':
-        return {
-          ...state,
-          status: 'delivering',
-          etaMinutes: event.payload.etaMinutes,
-        }
-      case 'delivered':
-        return { ...state, status: 'delivered', etaMinutes: null }
-      default:
-        return state
-    }
-  })
+    fold: (state, event): OrderState => {
+      switch (event.type) {
+        case 'created':
+          return {
+            ...state,
+            status: 'created',
+            shopId: event.payload.shopId,
+            items: event.payload.items,
+          }
+        case 'shop.notified':
+          return { ...state, status: 'notified' }
+        case 'shop.started':
+          return { ...state, status: 'preparing' }
+        case 'driver.notified':
+          return {
+            ...state,
+            status: 'courier-assigned',
+            driverId: event.payload.driverId,
+          }
+        case 'courier.picked_up':
+          return {
+            ...state,
+            status: 'delivering',
+            etaMinutes: event.payload.etaMinutes,
+          }
+        case 'delivered':
+          return { ...state, status: 'delivered', etaMinutes: null }
+        default:
+          return state
+      }
+    },
+  },
+})
+export const ordersReducer = orders.reducer

package/examples/playground/app/page.tsx

@@ -1,111 +1,22 @@
 import type { ReactNode } from 'react'
-import Link from 'next/link'
+import { FastLink } from './components/fast-link'
+import { demos } from './components/demos'
 
 export default function HomePage(): ReactNode {
   return (
     <article>
-      <h1>A durable event log, live in your browser</h1>
-      <p className="lede">
-        Eight small demos, one model: append an event, let a handler react, fold
-        the log into a view — on the server for the first paint, in the browser
-        for every moment after.
-      </p>
-
-      <div className="card-grid">
-        <Link className="card" href="/orders">
-          <h2>Order tracker</h2>
-          <p>
-            A form appends <code>created</code>, and handlers chain the rest —
-            shop notified, courier assigned, picked up, delivered — while the
-            page watches over a live stream. One optimistic click, then the
-            order runs itself to the end.
-          </p>
-        </Link>
-        <Link className="card" href="/chat">
-          <h2>Multiplayer chat + agent</h2>
-          <p>
-            Messages, “is typing…” presence, and an AI participant share one
-            stream. Mention <code>@agent</code>, or enable ambient mode for the
-            room. The model can stay silent or call a durable <code>post</code>{' '}
-            tool; its private generation appears only as “thinking” or
-            “writing.”
-          </p>
-        </Link>
-        <Link className="card" href="/agent">
-          <h2>Agent</h2>
-          <p>
-            A durable AI agent inspects a service, records tool calls, pauses
-            for approval, runs Bash in a persistent Vercel Sandbox, and sets
-            reminders that return as new user messages. Messages, progress,
-            tools, timers, and the human decision are all ordinary A2 events.
-          </p>
-        </Link>
-        <Link className="card" href="/canvas">
-          <h2>Multiplayer canvas</h2>
-          <p>
-            Shapes are durable events you can scrub back through after the
-            server snapshot. Cursors and drag ghosts are presence: replicated
-            live, stored never.
-          </p>
-        </Link>
-        <Link className="card" href="/documents">
-          <h2>Multiplayer document</h2>
-          <p>
-            Two CodeMirror editors share one Yjs document. A2 durably orders the
-            CRDT updates while Yjs Awareness — live cursors and selections —
-            rides the session's presence plane, never touching the log.
-          </p>
-        </Link>
-        <Link className="card" href="/recovery">
-          <h2>Cross-invocation recovery</h2>
-          <p>
-            Chain four 8-second handlers under a 20-second function limit, then
-            watch Vercel stop one mid-handler and A2 retry that pending event
-            under a fresh claim.
-          </p>
-        </Link>
-        <Link className="card" href="/vault">
-          <h2>Vault (actor)</h2>
-          <p>
-            A durable actor: send messages to one vault's mailbox, watch it
-            process them one at a time against its state — serialized
-            read-modify-write, refusals as answers, and the whole transcript in
-            the log. Built on <code>experimental-a2/actor</code>.
-          </p>
-        </Link>
-        <Link className="card" href="/counter">
-          <h2>Counter</h2>
-          <p>
-            Increment and decrement one shared value. Every click is a durable
-            event applied optimistically in the browser, then confirmed by the
-            stream — open two tabs and watch both folds converge.
-          </p>
-        </Link>
-      </div>
-
-      <section>
-        <h2>Where things live</h2>
-        <ul>
-          <li>
-            Each demo owns a <code>model.ts</code> with its contract, reducer,
-            and shared types.
-          </li>
-          <li>
-            Its <code>server.ts</code> implements handlers and configures the
-            production store and scheduler it actually needs.
-          </li>
-          <li>
-            Its <code>events/route.ts</code> exposes <code>server.fetch</code>{' '}
-            directly, adding only feature-specific authorization or WebSocket
-            capabilities.
-          </li>
-          <li>
-            Demos with handlers or timers own a private{' '}
-            <code>scheduler/route.ts</code> and queue topic. Counter, canvas,
-            and documents need no scheduler.
+      <h1>A durable event log</h1>
+      <p className="lede">Every demo here is a fold over an append-only log.</p>
+      <ul className="app-grid" aria-label="Demos">
+        {demos.map((demo) => (
+          <li key={demo.href}>
+            <FastLink href={demo.href} className="app-tile">
+              <span className="app-icon">{demo.icon}</span>
+              <span>{demo.name}</span>
+            </FastLink>
           </li>
-        </ul>
-      </section>
+        ))}
+      </ul>
     </article>
   )
 }

package/examples/playground/app/recovery/[recoveryId]/page.tsx

@@ -19,8 +19,7 @@ export default async function RecoveryRunPage({
     <SessionProvider
       sessionId={sessionId}
       api="/recovery/events"
-      initialState={state}
-      initialIndex={index}
+      initial={{ state: state, index: index }}
     >
       <RecoveryClient
         sessionId={sessionId}

package/examples/playground/app/recovery/[recoveryId]/session.ts

@@ -1,7 +1,7 @@
 'use client'
 import { createReact } from 'experimental-a2/react'
-import { recoveryReducer } from '../model'
+import { recovery } from '../model'
 
 export const { SessionProvider, useSession } = createReact({
-  reducer: recoveryReducer,
+  contract: recovery,
 })

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

@@ -1,6 +1,15 @@
 import * as a2 from 'experimental-a2'
 import { z } from 'zod'
 
+const recoveryState = z.object({
+  phase: z.enum(['idle', 'running', 'completed']),
+  stepCount: z.number().int().positive().nullable(),
+  stepDurationSeconds: z.number().int().positive().nullable(),
+  completedSteps: z.number().int().nonnegative(),
+})
+
+export type RecoveryState = z.output<typeof recoveryState>
+
 export const recovery = a2.contract({
   name: 'recovery',
   events: {
@@ -14,19 +23,8 @@ export const recovery = a2.contract({
     }),
     'pipeline.completed': z.object({ stepCount: z.literal(4) }),
   },
-})
-
-const recoveryState = z.object({
-  phase: z.enum(['idle', 'running', 'completed']),
-  stepCount: z.number().int().positive().nullable(),
-  stepDurationSeconds: z.number().int().positive().nullable(),
-  completedSteps: z.number().int().nonnegative(),
-})
 
-export type RecoveryState = z.output<typeof recoveryState>
-
-export const recoveryReducer = recovery
-  .reducer({
+  reducer: {
     name: 'recovery',
     initialState: {
       phase: 'idle',
@@ -35,21 +33,23 @@ export const recoveryReducer = recovery
       completedSteps: 0,
     },
     stateSchema: recoveryState,
-  })
-  .fold((state, event) => {
-    switch (event.type) {
-      case 'pipeline.started':
-        return {
-          ...state,
-          phase: 'running',
-          stepCount: event.payload.stepCount,
-          stepDurationSeconds: event.payload.stepDurationSeconds,
-        }
-      case 'step.completed':
-        return { ...state, completedSteps: event.payload.step }
-      case 'pipeline.completed':
-        return { ...state, phase: 'completed' }
-      default:
-        return state
-    }
-  })
+    fold: (state, event): RecoveryState => {
+      switch (event.type) {
+        case 'pipeline.started':
+          return {
+            ...state,
+            phase: 'running',
+            stepCount: event.payload.stepCount,
+            stepDurationSeconds: event.payload.stepDurationSeconds,
+          }
+        case 'step.completed':
+          return { ...state, completedSteps: event.payload.step }
+        case 'pipeline.completed':
+          return { ...state, phase: 'completed' }
+        default:
+          return state
+      }
+    },
+  },
+})
+export const recoveryReducer = recovery.reducer

package/examples/playground/instrumentation.ts

@@ -0,0 +1,5 @@
+import { registerOTel } from '@vercel/otel'
+
+export function register(): void {
+  registerOTel({ serviceName: 'a2-playground' })
+}

package/examples/playground/package.json

@@ -12,18 +12,24 @@
     "dev": "next dev",
     "build": "next build",
     "test": "vitest run",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "a0:template": "node --env-file-if-exists=.env.local scripts/a0-template.ts"
   },
   "dependencies": {
+    "@ai-sdk/otel": "1.0.58",
     "@codemirror/state": "^6.7.1",
     "@codemirror/view": "^6.43.8",
+    "@opentelemetry/api": "^1.9.0",
     "@vercel/functions": "^3.9.3",
+    "@vercel/otel": "^2.1.0",
     "@vercel/queue": "^0.2.0",
     "@vercel/sandbox": "^3.0.0",
     "ai": "^7.0.58",
     "codemirror": "^6.0.2",
-    "experimental-a2": "0.16.0",
+    "experimental-a2": "0.17.0",
+    "geist": "^1.7.2",
     "ioredis": "^5.9.0",
+    "lucide-react": "^1.34.0",
     "next": "^16.3.0",
     "pg": "^8.16.0",
     "react": "^19.0.0",
@@ -36,6 +42,8 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
+    "@opentelemetry/context-async-hooks": "^2.0.0",
+    "@opentelemetry/sdk-trace-base": "^2.0.0",
     "@testing-library/react": "^16.1.0",
     "jsdom": "^26.0.0",
     "@types/node": "^24.0.0",

package/examples/playground/scripts/a0-template.ts

@@ -0,0 +1,77 @@
+/**
+ * Builds A0's template: a sandbox with a blank Next.js app, its
+ * dependencies installed and its dev cache warm, snapshotted with no
+ * expiry. Prints the snapshot id to set as A0_TEMPLATE_SNAPSHOT_ID.
+ *
+ *   pnpm --filter playground a0:template
+ *
+ * Run it again when the recipe changes, then update the variable.
+ */
+import { Sandbox } from '@vercel/sandbox'
+
+const appDir = '/vercel/app'
+const appPort = 3000
+
+const RECIPE = `set -e
+cd /vercel
+npx --yes create-next-app@latest app --yes --use-npm --disable-git
+cd ${appDir}
+rm -f public/*.svg
+cat > next.config.ts <<'EOF'
+import type { NextConfig } from 'next'
+
+// The preview is served from the sandbox's public *.vercel.run host.
+const nextConfig: NextConfig = { allowedDevOrigins: ['*.vercel.run'] }
+
+export default nextConfig
+EOF
+cat > app/globals.css <<'EOF'
+@import 'tailwindcss';
+EOF
+cat > app/layout.tsx <<'EOF'
+import type { Metadata } from 'next'
+import './globals.css'
+
+export const metadata: Metadata = { title: 'App' }
+
+export default function RootLayout({
+  children,
+}: Readonly<{ children: React.ReactNode }>) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  )
+}
+EOF
+cat > app/page.tsx <<'EOF'
+export default function Home() {
+  return <main />
+}
+EOF
+# Warms the dev cache: next dev compiles the page once, then stops with the
+# snapshot. setsid -f keeps the command from waiting on the server.
+setsid -f npm run dev -- --port ${appPort} > /tmp/next.log 2>&1 < /dev/null
+timeout 120 bash -c 'until curl -sf localhost:${appPort} > /dev/null; do sleep 1; done'`
+
+// The snapshot outlives its builder, so nothing but the snapshot stays.
+const builder = await Sandbox.create({
+  persistent: false,
+  timeout: 10 * 60 * 1000,
+})
+try {
+  const result = await builder.runCommand({
+    cmd: 'bash',
+    args: ['-lc', RECIPE],
+  })
+  if (result.exitCode !== 0) {
+    const output = await result.output('both')
+    throw new Error(
+      `The template didn't build (exit ${result.exitCode}):\n${output.slice(-2000)}`,
+    )
+  }
+  const { snapshotId } = await builder.snapshot({ expiration: 0 })
+  process.stdout.write(`A0_TEMPLATE_SNAPSHOT_ID=${snapshotId}\n`)
+} finally {
+  await builder.delete().catch(() => {})
+}

package/examples/playground/vercel.json

@@ -35,6 +35,24 @@
           "retryAfterSeconds": 30
         }
       ]
+    },
+    "app/a0/scheduler/route.ts": {
+      "experimentalTriggers": [
+        {
+          "type": "queue/v2beta",
+          "topic": "a2-a0",
+          "retryAfterSeconds": 30
+        }
+      ]
+    },
+    "app/a0/sandboxes/scheduler/route.ts": {
+      "experimentalTriggers": [
+        {
+          "type": "queue/v2beta",
+          "topic": "a2-a0-sandboxes",
+          "retryAfterSeconds": 30
+        }
+      ]
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "experimental-a2",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Durable sync and reactions for things with a lifecycle: one event log, derived state, and live client per session.",
   "license": "MIT",
   "type": "module",
@@ -39,6 +39,8 @@
       "browser": "./dist/ai-server.browser.js",
       "default": "./dist/ai-server.js"
     },
+    "./ai/client": "./dist/ai-client.js",
+    "./ai/react": "./dist/ai-react.js",
     "./actor": {
       "browser": "./dist/actor.browser.js",
       "default": "./dist/actor.js"