experimental-a2 0.16.1 → 0.18.0

package/examples/playground/app/a0/preview-pane.tsx

@@ -0,0 +1,145 @@
+'use client'
+import type { ReactNode } from 'react'
+import { useEffect, useMemo, useState } from 'react'
+import { AppWindow, LoaderCircle } from 'lucide-react'
+import { appPort } from './model'
+import { shownPreview } from './preview'
+import { useSession } from './session'
+
+// Checks come quickly until the app answers, then only as often as keeping
+// its sandbox up needs, since each one runs a command in it.
+const CHECK_MS = 3000
+const KEEP_UP_MS = 2 * 60 * 1000
+
+/** Has the server make sure the app is up; says whether it answers. */
+export async function checkApp({
+  appId,
+  newApp = false,
+  signal,
+}: {
+  appId: string
+  /** An app nobody has prompted yet, whose sandbox goes if nobody does. */
+  newApp?: boolean
+  signal?: AbortSignal
+}): Promise<boolean> {
+  const response = await fetch(`/a0/apps/${appId}/preview`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ newApp }),
+    ...(signal ? { signal } : {}),
+  })
+  return ((await response.json()) as { up?: boolean }).up === true
+}
+
+type Liveness = {
+  up: boolean | null
+  /** How many times it came back after being down. */
+  returns: number
+}
+
+/**
+ * Whether the app answers, asked while the page is visible, which keeps its
+ * sandbox up. One ask at a time.
+ */
+function useAppUp({
+  appId,
+  watching,
+}: {
+  appId: string
+  watching: boolean
+}): Liveness {
+  const [liveness, setLiveness] = useState<Liveness>({
+    up: null,
+    returns: 0,
+  })
+  useEffect(() => {
+    if (!watching) return
+    const controller = new AbortController()
+    let timer: ReturnType<typeof setTimeout> | undefined
+    const check = async (): Promise<void> => {
+      clearTimeout(timer)
+      let answering = false
+      try {
+        answering = await checkApp({ appId, signal: controller.signal })
+      } catch {}
+      if (controller.signal.aborted) return
+      setLiveness(({ up, returns }) => ({
+        up: answering,
+        returns: answering && up === false ? returns + 1 : returns,
+      }))
+      if (document.visibilityState === 'visible')
+        timer = setTimeout(check, answering ? KEEP_UP_MS : CHECK_MS)
+    }
+    const resume = (): void => {
+      if (document.visibilityState === 'visible') void check()
+    }
+    void check()
+    document.addEventListener('visibilitychange', resume)
+    return () => {
+      controller.abort()
+      clearTimeout(timer)
+      document.removeEventListener('visibilitychange', resume)
+    }
+  }, [appId, watching])
+  return liveness
+}
+
+/** The app the agent last showed the user, as its sandbox serves it. */
+export function PreviewPane({ appId }: { appId: string }): ReactNode {
+  const { state } = useSession()
+  const shown = useMemo(() => shownPreview(state.messages), [state.messages])
+  // An app with a conversation stays up while it's on screen.
+  const { up, returns } = useAppUp({
+    appId,
+    watching: state.messages.length > 0,
+  })
+  const live = shown && up ? shown.url : null
+
+  return (
+    <section aria-label="Preview" className="a0-preview">
+      {live ? (
+        <iframe
+          // Showing the app again, or its server coming back, loads it again.
+          key={`${live}:${shown?.callId}:${returns}`}
+          title="App"
+          src={live}
+          allow="clipboard-write"
+          sandbox="allow-scripts allow-same-origin allow-forms allow-popups allow-modals allow-downloads"
+        />
+      ) : (
+        <Placeholder shown={shown !== null} checking={up === null} />
+      )}
+    </section>
+  )
+}
+
+function Placeholder({
+  shown,
+  checking,
+}: {
+  shown: boolean
+  checking: boolean
+}): ReactNode {
+  return (
+    <div className="a0-placeholder">
+      {shown && checking ? (
+        <p>
+          <LoaderCircle size={14} className="a0-spin" aria-hidden />
+          Connecting to port {appPort}
+        </p>
+      ) : (
+        <div>
+          <AppWindow size={24} strokeWidth={1.5} aria-hidden />
+          <p className="a0-placeholder-title">
+            {shown ? `Nothing is running on port ${appPort}` : 'No app yet'}
+          </p>
+          <p>
+            {shown
+              ? 'Ask the agent to start it again.'
+              : 'It shows up here when the agent is done.'}
+          </p>
+        </div>
+      )}
+    </div>
+  )
+}

package/examples/playground/app/a0/preview.test.ts

@@ -0,0 +1,53 @@
+import { expect, it } from 'vitest'
+import type { AppMessage } from './model'
+import { shownPreview } from './preview'
+
+type Part = AppMessage['parts'][number]
+
+const message = (role: AppMessage['role'], ...parts: Part[]): AppMessage => ({
+  id: crypto.randomUUID(),
+  role,
+  parts,
+})
+
+const shown = (callId: string, output: unknown): Part =>
+  ({
+    type: 'tool-show_preview',
+    toolCallId: callId,
+    state: 'output-available',
+    input: { path: '/' },
+    output,
+  }) as Part
+
+const url = 'https://sb-3000.vercel.run/'
+
+it('shows nothing until the agent shows the app', () => {
+  expect(shownPreview([])).toBeNull()
+})
+
+it('follows the latest preview the agent showed', () => {
+  const messages = [
+    message('assistant', shown('p1', { url })),
+    message('assistant', shown('p2', { url: `${url}about` })),
+    message(
+      'assistant',
+      shown('p3', { error: 'Nothing is serving port 3000.' }),
+    ),
+  ]
+  expect(shownPreview(messages)).toEqual({ url: `${url}about`, callId: 'p2' })
+})
+
+it('ignores previews a user message carries', () => {
+  expect(shownPreview([message('user', shown('p1', { url }))])).toBeNull()
+})
+
+it('frames only https sandbox hosts, and survives malformed output', () => {
+  for (const output of [
+    null,
+    url,
+    { url: 'https://example.com/' },
+    { url: 'http://sb-3000.vercel.run/' },
+    { url: 'javascript:alert(1)' },
+  ])
+    expect(shownPreview([message('assistant', shown('p1', output))])).toBeNull()
+})

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

@@ -0,0 +1,26 @@
+import { z } from 'zod'
+import type { AppMessage } from './model'
+
+// Only the agent's own show_preview results, which point at a sandbox's
+// public host. Anything else in the log never reaches the iframe.
+const previewSchema = z.object({
+  url: z.url({ protocol: /^https$/, hostname: /\.vercel\.run$/ }),
+})
+
+/** The app the agent last showed the user, so a reload shows it again. */
+export function shownPreview(
+  messages: readonly AppMessage[],
+): { url: string; callId: string } | null {
+  let shown: { url: string; callId: string } | null = null
+  for (const message of messages) {
+    if (message.role !== 'assistant') continue
+    for (const part of message.parts) {
+      if (part.type !== 'tool-show_preview') continue
+      if (!('state' in part) || part.state !== 'output-available') continue
+      const parsed = previewSchema.safeParse(part.output)
+      if (parsed.success)
+        shown = { url: parsed.data.url, callId: part.toolCallId }
+    }
+  }
+  return shown
+}

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

@@ -0,0 +1,75 @@
+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 { agentServers } 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, 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 })
+    },
+  },
+})
+
+/**
+ * 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-session.ts

@@ -0,0 +1,152 @@
+import 'server-only'
+import type { Sandbox } from '@vercel/sandbox'
+import type { Experimental_SandboxSession } from 'ai'
+import { appDir } from './sandbox'
+
+// A job the command backgrounds, like `next dev &`, keeps whatever output it
+// started with, and a read of a pipe would wait on it forever. Output goes to
+// a file instead; background jobs live on.
+const CAPTURE = `out=$(mktemp); bash -lc "$0" > "$out" 2>&1 < /dev/null; code=$?; cat "$out"; rm -f "$out"; exit $code`
+
+type Run = Parameters<Experimental_SandboxSession['run']>[0]
+
+/**
+ * The app's Vercel Sandbox as an AI SDK sandbox session, for harnesses whose
+ * own tools need one. Commands run in the app's directory.
+ */
+export function sandboxSession(sandbox: Sandbox): Experimental_SandboxSession {
+  const params = ({ command, workingDirectory, env, abortSignal }: Run) => ({
+    cmd: 'bash',
+    args: ['-c', CAPTURE, command],
+    cwd: workingDirectory ?? appDir,
+    ...(env ? { env } : {}),
+    ...(abortSignal ? { signal: abortSignal } : {}),
+  })
+  const readBinaryFile = async ({
+    path,
+    abortSignal,
+  }: {
+    path: string
+    abortSignal?: AbortSignal
+  }): Promise<Uint8Array | null> => {
+    const buffer = await sandbox.readFileToBuffer(
+      { path, cwd: appDir },
+      abortSignal ? { signal: abortSignal } : {},
+    )
+    return buffer && new Uint8Array(buffer)
+  }
+  // The sandbox extracts written files at its root, creating their directories.
+  const write = (path: string, content: Uint8Array, signal?: AbortSignal) =>
+    sandbox.writeFiles(
+      [{ path: path.startsWith('/') ? path : `${appDir}/${path}`, content }],
+      signal ? { signal } : {},
+    )
+
+  return {
+    description: `A Vercel Sandbox. The app is in ${appDir}.`,
+    // Streams, so a reader that stops early stops the download.
+    readFile: async ({ path, abortSignal }) => {
+      const stream = await sandbox.readFile(
+        { path, cwd: appDir },
+        abortSignal ? { signal: abortSignal } : {},
+      )
+      if (stream === null) return null
+      const chunks = stream[Symbol.asyncIterator]()
+      return new ReadableStream<Uint8Array>({
+        pull: async (controller) => {
+          const { done, value } = await chunks.next()
+          if (done) controller.close()
+          else
+            controller.enqueue(
+              typeof value === 'string'
+                ? new TextEncoder().encode(value)
+                : value,
+            )
+        },
+        cancel: async () => {
+          await chunks.return?.()
+        },
+      })
+    },
+    readBinaryFile,
+    readTextFile: async ({ encoding, startLine, endLine, ...options }) => {
+      const bytes = await readBinaryFile(options)
+      if (bytes === null) return null
+      const text = new TextDecoder(encoding).decode(bytes)
+      if (startLine === undefined && endLine === undefined) return text
+      return text
+        .split('\n')
+        .slice((startLine ?? 1) - 1, endLine)
+        .join('\n')
+    },
+    writeFile: async ({ path, content, abortSignal }) =>
+      write(
+        path,
+        new Uint8Array(await new Response(content).arrayBuffer()),
+        abortSignal,
+      ),
+    writeBinaryFile: ({ path, content, abortSignal }) =>
+      write(path, content, abortSignal),
+    writeTextFile: ({ path, content, abortSignal }) =>
+      write(path, new TextEncoder().encode(content), abortSignal),
+    run: async (options) => {
+      const finished = await sandbox.runCommand(params(options))
+      return {
+        exitCode: finished.exitCode,
+        stdout: await finished.stdout(),
+        stderr: await finished.stderr(),
+      }
+    },
+    spawn: async (options) => {
+      const { abortSignal } = options
+      const command = await sandbox.runCommand({
+        ...params(options),
+        detached: true,
+      })
+      // For a detached command the signal only cancels its start; aborting
+      // kills it, as the AI SDK's sandbox contract says.
+      const kill = () => void command.kill().catch(() => {})
+      if (abortSignal?.aborted) kill()
+      abortSignal?.addEventListener('abort', kill, { once: true })
+      const encoder = new TextEncoder()
+      let stdout!: ReadableStreamDefaultController<Uint8Array>
+      let stderr!: ReadableStreamDefaultController<Uint8Array>
+      const streams = {
+        stdout: new ReadableStream<Uint8Array>({
+          start: (c) => void (stdout = c),
+        }),
+        stderr: new ReadableStream<Uint8Array>({
+          start: (c) => void (stderr = c),
+        }),
+      }
+      // The command's log ends when it exits, and closes both streams.
+      void (async () => {
+        try {
+          for await (const line of command.logs())
+            (line.stream === 'stdout' ? stdout : stderr).enqueue(
+              encoder.encode(line.data),
+            )
+          stdout.close()
+          stderr.close()
+        } catch (error) {
+          stdout.error(error)
+          stderr.error(error)
+        }
+      })()
+      return {
+        ...streams,
+        wait: async () => {
+          try {
+            const finished = await command.wait(
+              abortSignal ? { signal: abortSignal } : {},
+            )
+            return { exitCode: finished.exitCode }
+          } finally {
+            abortSignal?.removeEventListener('abort', kill)
+          }
+        },
+        kill: () => command.kill(),
+      }
+    },
+  }
+}

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, appSchedulers } from '../server'
+
+export const POST =
+  appSchedulers['ai-sdk']?.handler(agentServer) ??
+  (() => new Response('a0 scheduler is not configured', { status: 503 }))
+
+export const maxDuration = 300