experimental-a2 0.16.0 → 0.17.0

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

@@ -0,0 +1,69 @@
+import 'server-only'
+import { contract } from 'experimental-a2'
+import { vercelQueues } from 'experimental-a2/scheduler-vercel'
+import { createServer } from 'experimental-a2/server'
+import { z } from 'zod'
+import { store } from '@/lib/store'
+import { isAppId } from './apps'
+import { deleteAppSandbox } from './sandbox'
+import { agentServer } from './server'
+
+// How long a new app's sandbox waits for a first prompt.
+const IDLE_GRACE_MS = 10 * 60 * 1000
+
+/**
+ * An app's sandbox lifecycle, in a log of its own so the app's log stays
+ * its conversation. A new app's sandbox opens on sight, before anyone
+ * prompts it, so each one schedules a check that deletes it if the app is
+ * still empty when the grace period ends.
+ */
+const sandboxLog = contract({
+  name: 'a0-sandboxes',
+  events: {
+    'sandbox.idle.checked': z.object({ appId: z.uuid() }),
+  },
+})
+
+const sandboxLogId = (appId: string): string => `${appId}:sandbox`
+
+export const sandboxScheduler =
+  process.env.VERCEL || process.env.A2_QUEUES
+    ? vercelQueues({ topic: 'a2-a0-sandboxes' })
+    : undefined
+
+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.
+      const { state } = await agentServer.session(appId).state()
+      if (state.messages.length === 0) await deleteAppSandbox({ appId })
+    },
+  },
+})
+
+/**
+ * Schedules the check for a new app's sandbox. It's keyed to the sandbox's
+ * creation, so repeating it converges on one check, and a sandbox made
+ * again later gets its own. Without a scheduler, as under next dev, the
+ * sandbox just waits for its session to time out.
+ */
+export async function checkWhenIdle({
+  appId,
+  createdAt,
+}: {
+  appId: string
+  createdAt: Date
+}): Promise<void> {
+  if (!sandboxScheduler || !isAppId(appId)) return
+  await sandboxServer
+    .session(sandboxLogId(appId))
+    .schedule(
+      `idle-check-${createdAt.getTime()}`,
+      { at: new Date(createdAt.getTime() + IDLE_GRACE_MS) },
+      { type: 'sandbox.idle.checked', payload: { appId } },
+    )
+}

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

@@ -0,0 +1,191 @@
+import 'server-only'
+import { APIError, Sandbox } from '@vercel/sandbox'
+import { appPort } from './model'
+
+// Each app has one persistent Vercel Sandbox, started from a template that
+// already holds a Next.js app with its dependencies (scripts/a0-template.ts).
+
+// The default image's home, owned by the user commands run as.
+export const workspace = '/vercel'
+export const appDir = `${workspace}/app`
+// A sandbox's session lasts this long from its start unless kept alive.
+const SESSION_TIMEOUT_MS = 15 * 60 * 1000
+// Each tool call keeps the sandbox up at least this much longer.
+const KEEP_ALIVE_MS = 10 * 60 * 1000
+// Abandoned apps lose their files after this long.
+const SNAPSHOT_EXPIRATION_MS = 14 * 24 * 60 * 60 * 1000
+const OUTPUT_LIMIT = 32 * 1024
+
+// Local runs and deployments share the project's sandboxes, so each name
+// says where it came from.
+const scope = process.env.VERCEL_ENV ?? 'local'
+const sandboxName = (appId: string): string => `a2-a0-${scope}-${appId}`
+
+const status = (error: unknown): number | undefined =>
+  error instanceof APIError ? error.response.status : undefined
+const notFound = (error: unknown): boolean => status(error) === 404
+
+// Starts next dev unless one is already running or booting: it holds a lock
+// for as long as it runs, so another start exits at once, and a server that
+// dies frees it. A server started without the lock, by older code or by hand,
+// still owns the port, which a bare TCP connect checks without asking it for a
+// page. A command only finishes once every process in its group exits, so
+// next dev gets its own session (setsid -f), and appends to its log.
+export const START_DEV = `cd ${appDir} && { (: < /dev/tcp/127.0.0.1/${appPort}) 2>/dev/null || setsid -f flock -n /tmp/next.lock npm run dev -- --port ${appPort} >> /tmp/next.log 2>&1 < /dev/null; }`
+
+// Starts next dev, then asks it for the home page in the background, so the
+// page is compiled by the time anyone looks. Neither is waited for.
+const WARM_UP = `${START_DEV}; setsid -f timeout 60 bash -c 'until curl -s -o /dev/null localhost:${appPort}; do sleep 0.5; done' > /dev/null 2>&1 < /dev/null`
+
+const startDev = async (sandbox: Sandbox): Promise<void> => {
+  await sandbox.runCommand({ cmd: 'bash', args: ['-c', WARM_UP] })
+}
+
+function templateSnapshot(): string {
+  const snapshotId = process.env.A0_TEMPLATE_SNAPSHOT_ID
+  if (!snapshotId)
+    throw new Error(
+      'A0_TEMPLATE_SNAPSHOT_ID is not set. Build the template with `pnpm --filter playground a0:template` and set the id it prints.',
+    )
+  return snapshotId
+}
+
+async function openApp(appId: string): Promise<Sandbox> {
+  const name = sandboxName(appId)
+  const existing = () => Sandbox.get({ name, resume: true, onResume: startDev })
+  try {
+    return await existing()
+  } catch (error) {
+    if (!notFound(error)) throw error
+  }
+  let sandbox: Sandbox
+  try {
+    sandbox = await Sandbox.create({
+      name,
+      source: { type: 'snapshot', snapshotId: templateSnapshot() },
+      ports: [appPort],
+      timeout: SESSION_TIMEOUT_MS,
+      persistent: true,
+      snapshotExpiration: SNAPSHOT_EXPIRATION_MS,
+      keepLastSnapshots: { count: 1 },
+    })
+  } catch (error) {
+    // Another instance created it first. The API holds a racing create until
+    // the first one finishes, then refuses it: 409, or 400 "already exists".
+    if (status(error) !== 409 && status(error) !== 400) throw error
+    return existing().catch((missing: unknown) => {
+      throw notFound(missing) ? error : missing
+    })
+  }
+  await startDev(sandbox)
+  return sandbox
+}
+
+// Parallel tool calls on a new app share one create within this instance.
+const opening = new Map<string, Promise<Sandbox>>()
+
+/** The app's sandbox, created or resumed, and kept up while it's used. */
+export async function appSandbox({
+  appId,
+}: {
+  appId: string
+}): Promise<Sandbox> {
+  const pending =
+    opening.get(appId) ?? openApp(appId).finally(() => opening.delete(appId))
+  opening.set(appId, pending)
+  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
+}
+
+// A server that's booting refuses connections for a moment, and a page
+// that's still compiling answers late; the probe waits out both.
+const ANSWER_WAIT_SECONDS = 30
+const PROBE = `curl -s -o /dev/null -w '%{http_code}' --retry ${ANSWER_WAIT_SECONDS} --retry-delay 1 --retry-connrefused --retry-max-time ${ANSWER_WAIT_SECONDS} --max-time ${ANSWER_WAIT_SECONDS} http://localhost:${appPort}/`
+
+/**
+ * Makes sure the app is up: opens its sandbox, creating or resuming it and
+ * keeping it running, starts next dev if it isn't running, and says whether
+ * the app answers. Safe to repeat; it only does what's missing.
+ */
+export async function ensureApp({
+  appId,
+}: {
+  appId: string
+}): Promise<{ up: boolean; createdAt: Date }> {
+  const sandbox = await appSandbox({ appId })
+  const probe = await sandbox.runCommand({
+    cmd: 'bash',
+    args: ['-c', `${START_DEV}; ${PROBE}`],
+  })
+  return {
+    up: Number(await probe.stdout()) > 0,
+    createdAt: sandbox.createdAt,
+  }
+}
+
+/**
+ * The public URL of a path on the app. It doesn't ask the dev server; the
+ * preview pane waits for the page itself.
+ */
+export const previewUrl = ({
+  sandbox,
+  path,
+}: {
+  sandbox: Sandbox
+  path: string
+}): { url: string } => ({ url: new URL(path, sandbox.domain(appPort)).href })
+
+export async function deleteAppSandbox({
+  appId,
+}: {
+  appId: string
+}): Promise<void> {
+  try {
+    const sandbox = await Sandbox.get({
+      name: sandboxName(appId),
+      resume: false,
+    })
+    await sandbox.delete()
+  } catch (error) {
+    if (!notFound(error)) throw error
+  }
+}
+
+// Runs the command with its output in a file rather than the sandbox's pipe:
+// a job it backgrounds, like `a && b && server &`, keeps whatever output it
+// started with, and on the pipe the call would wait for it forever.
+// coreutils' timeout ends it; background jobs live on. Only the first
+// OUTPUT_LIMIT bytes leave the sandbox.
+const RUN = `out=$(mktemp); timeout "$1" bash -lc "$0" > "$out" 2>&1 < /dev/null; code=$?; size=$(wc -c < "$out"); head -c ${OUTPUT_LIMIT} "$out"; if [ "$size" -gt ${OUTPUT_LIMIT} ]; then printf '\\n… %d more bytes' $((size - ${OUTPUT_LIMIT})); fi; rm -f "$out"; exit $code`
+
+/** Runs a shell command in the app's workspace, with output capped. */
+export async function bash({
+  sandbox,
+  command,
+  timeoutSeconds,
+  signal,
+}: {
+  sandbox: Sandbox
+  command: string
+  timeoutSeconds: number
+  signal?: AbortSignal
+}): Promise<{ exitCode: number; timedOut?: string; output: string }> {
+  const result = await sandbox.runCommand({
+    cmd: 'bash',
+    args: ['-c', RUN, command, `${timeoutSeconds}s`],
+    cwd: workspace,
+    ...(signal ? { signal } : {}),
+  })
+  return {
+    exitCode: result.exitCode,
+    ...(result.exitCode === 124 && {
+      timedOut: `Stopped after ${timeoutSeconds}s. Background long-running servers.`,
+    }),
+    output: await result.stdout(),
+  }
+}

package/examples/playground/app/a0/sandboxes/scheduler/route.ts

@@ -0,0 +1,6 @@
+import { sandboxScheduler, sandboxServer } from '../../sandbox-log'
+
+export const POST =
+  sandboxScheduler?.handler(sandboxServer) ??
+  (() =>
+    new Response('a0 sandbox scheduler is not configured', { status: 503 }))

package/examples/playground/app/a0/scheduler/route.ts

@@ -0,0 +1,7 @@
+import { agentServer, appScheduler } from '../server'
+
+export const POST =
+  appScheduler?.handler(agentServer) ??
+  (() => new Response('a0 scheduler is not configured', { status: 503 }))
+
+export const maxDuration = 300

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

@@ -0,0 +1,158 @@
+import 'server-only'
+import { waitUntil } from '@vercel/functions'
+import { tool } from 'ai'
+import { handlerContext } from 'experimental-a2/ai'
+import { agent } from 'experimental-a2/ai/server'
+import { createServer } from 'experimental-a2/server'
+import { vercelQueues } from 'experimental-a2/scheduler-vercel'
+import { z } from 'zod'
+import { store } from '@/lib/store'
+import { appList, isAppId } from './apps'
+import { crashOnRequest } from './crash-on-request'
+import { crashLog, crashLogId, isCrashLogId } from './crashes'
+import { appAgent, appPort } from './model'
+import {
+  appDir,
+  appSandbox,
+  bash,
+  previewUrl,
+  START_DEV,
+  workspace,
+} from './sandbox'
+
+const INSTRUCTIONS = `You are a coding agent that builds a Next.js app in your own Linux sandbox, through the bash tool. The user watches the app in a live preview next to this chat.
+- ${appDir} already holds a blank Next.js app (App Router, TypeScript, Tailwind) with its dependencies installed, and next dev serves it on port ${appPort} with hot reload. It may still be starting when you begin: don't wait for it, poll it, or start another one. Build what the user asks for there; don't create another app.
+- Until you change them, app/page.tsx renders an empty <main />, app/layout.tsx only sets the title, and app/globals.css only imports Tailwind. Write them directly; there's no need to look first.
+- Assume your edits work. Don't curl the dev server, sleep, or read the page back to check, and don't run builds, type checks or lint unless the user asks.
+- When the change is ready, call show_preview once, as your last step, so the user sees the result; until then they see no app. After that first time, saved files show up in their preview on their own, so call it again only to show a different path.
+- If the preview stops answering, read /tmp/next.log, then start next dev with \`${START_DEV}\`; it does nothing while one is already running.
+- next.config allows the preview's *.vercel.run host (allowedDevOrigins); keep that when you edit it.
+- Background anything long-running; a bash call stops after its timeout.
+- Keep replies short and in plain text, without Markdown: what you changed.`
+
+/** A tool's result, with how long it took; the chat shows it. */
+async function timed<T extends object>(
+  run: () => Promise<T>,
+): Promise<T & { durationMs: number }> {
+  const started = performance.now()
+  const result = await run()
+  return { ...result, durationMs: Math.round(performance.now() - started) }
+}
+
+const tools = {
+  show_preview: tool({
+    description: `Show the user the app, as the dev server on port ${appPort} serves it, next to this chat. It doesn't check or start the server. Returns the public URL.`,
+    inputSchema: z.object({
+      path: z.string().startsWith('/').default('/'),
+    }),
+    execute: ({ path }) =>
+      timed(async () =>
+        previewUrl({
+          sandbox: await appSandbox({
+            appId: handlerContext(appAgent).session.id,
+          }),
+          path,
+        }),
+      ),
+  }),
+  bash: tool({
+    description: `Run a shell command in ${workspace}. Files persist between commands. Background long-running servers.`,
+    inputSchema: z.object({
+      command: z.string().min(1),
+      // Within one function invocation; see maxDuration on the routes.
+      timeoutSeconds: z.number().int().min(1).max(240).default(120),
+    }),
+    execute: ({ command, timeoutSeconds }) => {
+      const context = handlerContext(appAgent)
+      return timed(async () =>
+        bash({
+          sandbox: await appSandbox({ appId: context.session.id }),
+          command,
+          timeoutSeconds,
+          signal: context.signal,
+        }),
+      )
+    },
+  }),
+}
+
+/**
+ * Wakes agent work in a fresh invocation when the one that started it ends,
+ * and recovers from crashed ones.
+ */
+export const appScheduler =
+  process.env.VERCEL || process.env.A2_QUEUES
+    ? vercelQueues({ topic: 'a2-a0' })
+    : undefined
+
+// Each step runs with the app's model choice. The browser pushes it, and the
+// contract's schema checks it on the way in.
+export const agentServer = agent({
+  ...(store ? { store } : {}),
+  ...(appScheduler ? { scheduler: appScheduler } : {}),
+  contract: appAgent,
+  model: ({ event, state }) => {
+    // Every step starts here, in the process that runs it, which is what
+    // the dev tools' crash has to end.
+    if (crashesAllowed) {
+      const appId = event.sessionId
+      waitUntil(
+        crashOnRequest({
+          appId,
+          app: agentServer.session(appId),
+          log: crashServer.session(crashLogId(appId)),
+        }).catch(() => {}),
+      )
+    }
+    const { model, reasoning, fast } = state.modelChoice
+    return { model, reasoning, speed: fast ? 'fast' : 'standard' }
+  },
+  generation: () => ({
+    // Claude leaves its thinking's text out unless asked for a summary.
+    providerOptions: {
+      anthropic: { thinking: { type: 'adaptive', display: 'summarized' } },
+    },
+  }),
+  instructions: INSTRUCTIONS,
+  tools,
+  maxSteps: 80,
+})
+
+/** The app's event stream and pushes; only an app id names a session. */
+export function appEvents(request: Request): Promise<Response> {
+  return agentServer.fetch(request, {
+    // The agent refuses the AI protocol's server-authored events itself.
+    authorize: (operation) => isAppId(operation.sessionId),
+  })
+}
+
+/** The apps sidebar's lists, which only the browser writes. */
+export const listServer = createServer({
+  ...(store ? { store } : {}),
+  contract: appList,
+})
+
+/** The dev tools' crash logs, one per app. They have no handlers. */
+export const crashServer = createServer({
+  ...(store ? { store } : {}),
+  contract: crashLog,
+})
+
+/**
+ * A crash ends the function instance, and anything else it's serving, so
+ * only previews allow it, behind Deployment Protection, unless A0_CRASHES
+ * is on. Under next dev it would take the dev server down.
+ */
+export const crashesAllowed =
+  process.env.VERCEL_ENV === 'preview' || process.env.A0_CRASHES === 'on'
+
+/** The browser can only ask for a crash; the process it ends records it. */
+export function crashEvents(request: Request): Promise<Response> {
+  return crashServer.fetch(request, {
+    authorize: (operation) =>
+      isCrashLogId(operation.sessionId) &&
+      (crashesAllowed || operation.type !== 'push') &&
+      (operation.type !== 'push' ||
+        operation.events.every((event) => event.type === 'crash.requested')),
+  })
+}

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

@@ -0,0 +1,47 @@
+'use client'
+import { createClient } from 'experimental-a2/client'
+import { createReact } from 'experimental-a2/react'
+import { appList } from './apps'
+import { crashLog } from './crashes'
+import { appAgent } from './model'
+
+/** The dev tools' switch, `?limit=5s`, for the app at this URL, while they're open. */
+export function shortFunctions(appId: string): boolean {
+  const params = new URLSearchParams(location.search)
+  return (
+    location.pathname === `/a0/${appId}` &&
+    params.has('devtools') &&
+    params.get('limit') === '5s'
+  )
+}
+
+/**
+ * Follows an app's conversation log over the events route. Pushes go to a
+ * 5-second function instead while the dev tools' switch is on.
+ */
+export const appClient = createClient({
+  contract: appAgent,
+  api: {
+    type: 'http',
+    stream: '/a0/events',
+    push: (appId) =>
+      shortFunctions(appId) ? '/a0/short/events' : '/a0/events',
+  },
+})
+
+export const { SessionProvider, useSession } = createReact({
+  client: appClient,
+})
+
+/** Follows this browser's app list. */
+export const listClient = createClient({ contract: appList, api: '/a0/list' })
+
+export const { useSession: useList } = createReact({ client: listClient })
+
+/** Follows an app's crash log, for the dev tools. */
+export const crashClient = createClient({
+  contract: crashLog,
+  api: '/a0/crashes',
+})
+
+export const { useSession: useCrashLog } = createReact({ client: crashClient })

package/examples/playground/app/a0/shell.tsx

@@ -0,0 +1,150 @@
+'use client'
+import type { ReactNode } from 'react'
+import { createContext, useContext, useEffect, useState } from 'react'
+import { usePathname, useRouter, useSearchParams } from 'next/navigation'
+import { SiteNav } from '../components/site-header'
+import { type App, byLatestPrompt } from './apps'
+import { AppList } from './app-list'
+import { ColumnEdge, Columns } from './columns'
+import { listCookie, readCookie, type Widths, writeCookie } from './cookies'
+import { toggleDevtools } from './flags'
+import { useList } from './session'
+
+type Apps = {
+  listed: (id: string) => App | null
+  /** Records a prompt to an app, listing it under `name` the first time. */
+  prompted: (app: { id: string; name: string }) => void
+  /** Makes a new app on screen the one "+" opens until it's prompted. */
+  opened: (appId: string) => void
+}
+
+const AppsContext = createContext<Apps | null>(null)
+
+export function useApps(): Apps {
+  const apps = useContext(AppsContext)
+  if (!apps) throw new Error('useApps needs the A0 layout.')
+  return apps
+}
+
+type ListSeed = NonNullable<Parameters<typeof useList>[0]>['initial']
+
+const idFromPath = (pathname: string): string | null =>
+  pathname.split('/')[2] || null
+
+/** A0's frame: this browser's apps, beside whichever app is open. */
+export function A0Shell({
+  list,
+  widths,
+  renderedAt,
+  newAppId,
+  children,
+}: {
+  list: { id: string; initial: ListSeed }
+  widths: Widths
+  renderedAt: number
+  /** A new app is an id with no log yet. */
+  newAppId: string
+  children: ReactNode
+}): ReactNode {
+  const router = useRouter()
+  const current = idFromPath(usePathname())
+  const devtools = useSearchParams().has('devtools')
+  const { state: apps, push } = useList({
+    sessionId: list.id,
+    initial: list.initial,
+  })
+  const [listError, setListError] = useState<string | null>(null)
+  // The new app "+" opens: the one last on screen, so its sandbox is likely
+  // warm, until it's prompted.
+  const [ready, setReady] = useState(newAppId)
+
+  useEffect(() => {
+    const toggle = (event: KeyboardEvent): void => {
+      if (event.key.toLowerCase() !== 'j' || !(event.metaKey || event.ctrlKey))
+        return
+      event.preventDefault()
+      toggleDevtools()
+    }
+    document.addEventListener('keydown', toggle)
+    return () => document.removeEventListener('keydown', toggle)
+  }, [])
+
+  const write = (...event: Parameters<typeof push>): void => {
+    // The list is this browser's from its first write.
+    if (!readCookie(listCookie))
+      writeCookie({ name: listCookie, value: list.id })
+    setListError(null)
+    // A failed write has already been rolled back out of the list.
+    push(...event).catch((cause: unknown) =>
+      setListError(
+        `Couldn't save that: ${cause instanceof Error ? cause.message : String(cause)}`,
+      ),
+    )
+  }
+  const listed = (id: string): App | null =>
+    apps.find((app) => app.id === id) ?? null
+  const context: Apps = {
+    listed,
+    prompted: ({ id, name }) => {
+      if (listed(id)) {
+        write({ type: 'app.prompted', payload: { appId: id } })
+        return
+      }
+      write({ type: 'app.created', payload: { appId: id, name } })
+      if (id === ready) setReady(crypto.randomUUID())
+    },
+    opened: setReady,
+  }
+  const remove = async (target: App): Promise<void> => {
+    if (
+      !confirm(
+        `Delete ${target.name}? This deletes its sandbox, with everything the agent built in it.`,
+      )
+    )
+      return
+    const response = await fetch(`/a0/apps/${target.id}`, { method: 'DELETE' })
+    if (!response.ok) {
+      alert(`Could not delete ${target.name}.`)
+      return
+    }
+    write({ type: 'app.deleted', payload: { appId: target.id } })
+    if (target.id === current) router.replace(`/a0/${ready}${location.search}`)
+  }
+
+  return (
+    <AppsContext value={context}>
+      <Columns saved={widths} panel={devtools}>
+        <aside aria-label="A0" className="a0-apps">
+          <div className="site-header a0-head">
+            <SiteNav />
+          </div>
+          <AppList
+            apps={byLatestPrompt(apps)}
+            currentId={current}
+            renderedAt={renderedAt}
+            newAppId={ready}
+            onRename={({ id, name }) =>
+              write({ type: 'app.renamed', payload: { appId: id, name } })
+            }
+            onDelete={(target) => void remove(target)}
+          />
+          {listError && (
+            <p role="alert" className="a0-error a0-list-error">
+              {listError}
+            </p>
+          )}
+          <button
+            type="button"
+            className="a0-devtools-toggle"
+            aria-pressed={devtools}
+            onClick={toggleDevtools}
+          >
+            Dev tools <kbd>⌘J</kbd>
+          </button>
+          <ColumnEdge column="apps" />
+        </aside>
+        {children}
+      </Columns>
+    </AppsContext>
+  )
+}

package/examples/playground/app/a0/short/events/route.ts

@@ -0,0 +1,9 @@
+import { appEvents } from '../../server'
+
+/**
+ * Pushes from the dev tools' 5-second switch. Agent work they start stops
+ * with the function, and the scheduler resumes it in a full-length one.
+ */
+export { appEvents as POST }
+
+export const maxDuration = 5