experimental-a2 0.16.0 → 0.17.0

package/docs/reference/02-errors.mdx

@@ -40,7 +40,8 @@ export async function POST(req: Request) {
 | `UNKNOWN_PRESENCE_FIELD`  | a presence field isn't in the contract's `presence` map             | no        |
 | `PRESENCE_NOT_SUPPORTED`  | the contract declares `presence` but the configured store has no presence capability (thrown at construction; for environment-resolved stores, deferred to the first store use) | no |
 | `PARTIAL_DUPLICATE_BATCH` | a batch mixed already-appended and fresh events                     | no        |
-| `SUPERSEDED_ATTEMPT`      | a handler append from an attempt a recovery claim has replaced; nothing was written, the successor owns the event. Also the abort reason on that handler's `ctx.signal` | no        |
+| `SUPERSEDED_ATTEMPT`      | a handler append or clear from an attempt that a recovery claim or a session clear has replaced; nothing was written. Also the abort reason on that handler's `ctx.signal` | no        |
+| `SESSION_CLEARED`         | a state read reached below the latest clear, a handler read state past a clear of its event, or an actor call was cleared before it received its answer | no |
 | `CLAIM_EXPIRED`           | never thrown; only the `ctx.signal` abort reason when the attempt's lease lapsed without renewal (assumed loss, decided locally, not proof) | no        |
 | `STORE_UNAVAILABLE`       | the store backend failed; nothing was written, original error as `cause` | **yes**   |
 | `STORE_NOT_CONFIGURED`    | production boot with no `store` configured (during `next build` page collection, deferred to first use) | no |

package/examples/playground/DEPLOY.md

@@ -1,7 +1,7 @@
 # Deploying the playground
 
 The event log runs with zero setup in development (SQLite at `.a2/dev.db`,
-no scheduler). The Agent demo also needs AI Gateway and Vercel Sandbox
+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/guides/05-production.mdx`.
 
@@ -38,7 +38,7 @@ dependencies of this app.
 
 ## 2. Vercel Queues scheduler
 
-Queues need no configuration beyond the triggers in `vercel.json`. Orders,
+Queues need no configuration beyond the triggers in `vercel.json`. A0, Orders,
 Chat, Agent, and Recovery each own a scheduler route and queue topic alongside
 their contract and server. Each topic is created on first send, and its trigger
 makes the scheduler route private (no public URL). Schedulers turn on
@@ -54,8 +54,11 @@ A2_QUEUES=1 pnpm dev
 
 ## 3. AI Gateway
 
-The Agent demo uses the AI SDK with `openai/gpt-5.6-luna`, while the Chat demo
-uses `openai/gpt-5.4`. Both resolve through Vercel AI Gateway. Vercel
+The Agent demo uses the AI SDK with `openai/gpt-5.6-luna`, the Chat demo uses
+`openai/gpt-5.4`, and A0 defaults to `anthropic/claude-opus-5.5` in fast mode;
+the Agent demo and A0 let you pick another model, which the session keeps and
+every client of it sees. All of them
+resolve through Vercel AI Gateway. Vercel
 deployments use their OIDC token automatically. For local generation, link the
 project and pull its environment or set an `AI_GATEWAY_API_KEY`:
 
@@ -77,7 +80,50 @@ to later Bash calls in that conversation. Vercel deployments authenticate with
 OIDC automatically; the `vercel link` and `vercel env pull` commands above
 supply the same credentials during local development.
 
-## 5. WebSockets for the canvas
+## 5. A0's sandboxes
+
+Each A0 app gets its own persistent Vercel Sandbox, started from a template
+snapshot that already holds a blank Next.js app with its dependencies
+installed and its dev cache warm. Build it once per project, with the same
+credentials as above:
+
+```sh
+pnpm --filter playground a0:template
+```
+
+It takes about a minute and prints `A0_TEMPLATE_SNAPSHOT_ID=snap_…`. Set that
+variable for local development and for each deployed environment. Add it to
+the project's Development environment too, so `vercel env pull` brings it to
+local runs; without it, A0 throws as soon as it opens a sandbox. The
+snapshot never expires, and nothing else stays behind. Run the script again
+when the recipe in `scripts/a0-template.ts` changes, then update the variable;
+apps that already have a sandbox keep theirs.
+
+A new app's sandbox opens as soon as the app is on screen, so it's ready by the
+first prompt. If none comes within 10 minutes, a scheduled check deletes it.
+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.
+
+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
+sandbox and a public URL for the app the agent serves. Put
+[Deployment Protection](https://vercel.com/docs/deployment-protection) in front
+of a public deployment. A0's sandboxes are named `a2-a0-*`, which is where to
+look when cleaning up. The sidebar lists the apps this browser opened, from a
+cookie.
+
+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.
+Crashing ends everything else that instance is serving, so only preview
+deployments allow it, behind Deployment Protection. Set `A0_CRASHES=on` to
+allow it anywhere else. Under `next dev` that takes the dev server down with
+it, so it's for trying recovery, not for everyday local runs.
+
+## 6. WebSockets for the canvas
 
 Deployed, the canvas demo upgrades its route to a WebSocket
 (`experimental_upgradeWebSocket` from `@vercel/functions`, with `ws`
@@ -88,7 +134,7 @@ dev server drops the handshake), so the demo's session module picks
 the SSE + POST pair in development — same route, same protocol
 semantics, different wire.
 
-## 6. Deploy
+## 7. Deploy
 
 ```sh
 vercel deploy

package/examples/playground/app/a0/[appId]/loading.tsx

@@ -0,0 +1,16 @@
+import type { ReactNode } from 'react'
+import { ColumnEdge } from '../columns'
+
+/** The chat and preview columns, empty, while an app the server hasn't sent yet loads. */
+export default function Loading(): ReactNode {
+  return (
+    <>
+      <section aria-label="Chat" aria-busy className="a0-chat">
+        <ColumnEdge column="chat" />
+      </section>
+      <section aria-label="Preview" aria-busy className="a0-preview">
+        <div className="a0-placeholder" />
+      </section>
+    </>
+  )
+}

package/examples/playground/app/a0/[appId]/page.tsx

@@ -0,0 +1,48 @@
+import type { ReactNode } from 'react'
+import { notFound } from 'next/navigation'
+import { AppView } from '../app-view'
+import { isAppId } from '../apps'
+import { DevTools } from '../devtools'
+import { logPage } from '../model'
+import { agentServer, crashesAllowed } from '../server'
+import { SessionProvider } from '../session'
+
+/** An app, from its current state; the provider follows its log from there. */
+export default async function A0App({
+  params,
+  searchParams,
+}: {
+  params: Promise<{ appId: string }>
+  searchParams: Promise<Record<string, string | string[] | undefined>>
+}): Promise<ReactNode> {
+  const { appId } = await params
+  if (!isAppId(appId)) notFound()
+  const initial = await agentServer.session(appId).state()
+  // Open dev tools show the log itself, starting with its latest page.
+  const events =
+    (await searchParams).devtools !== undefined && initial.index > 0
+      ? await agentServer.session(appId).history({
+          gte: Math.max(1, initial.index - logPage + 1),
+          lte: initial.index,
+        })
+      : undefined
+  return (
+    <SessionProvider
+      key={appId}
+      sessionId={appId}
+      initial={initial}
+      initialEvents={events}
+    >
+      <AppView
+        appId={appId}
+        devtools={
+          <DevTools
+            appId={appId}
+            deployed={!!process.env.VERCEL}
+            crashesAllowed={crashesAllowed}
+          />
+        }
+      />
+    </SessionProvider>
+  )
+}