experimental-a2 0.16.0 → 0.17.0

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

@@ -0,0 +1,3 @@
+import { crashEvents } from '../server'
+
+export { crashEvents as GET, crashEvents as POST }

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

@@ -0,0 +1,33 @@
+import type { ContractEvent } from 'experimental-a2'
+import { expect, it } from 'vitest'
+import { crashLog, crashLogId, isCrashLogId } from './crashes'
+
+type CrashEvents = typeof crashLog.events
+
+const pending = (...types: (keyof CrashEvents & string)[]): boolean =>
+  types.reduce(
+    (state, type, index) =>
+      crashLog.reducer.fold(state, {
+        id: `event-${index}`,
+        type,
+        payload: {},
+        index: index + 1,
+        sessionId: 'log-1',
+        createdAt: new Date(index * 1000),
+      } as ContractEvent<CrashEvents>),
+    crashLog.reducer.initialState,
+  )
+
+it('holds a crash from its request until it happens', () => {
+  expect(pending()).toBe(false)
+  expect(pending('crash.requested')).toBe(true)
+  expect(pending('crash.requested', 'crashed')).toBe(false)
+  expect(pending('crash.requested', 'crashed', 'crash.requested')).toBe(true)
+})
+
+it("names one crash log per app, and only an app's", () => {
+  const appId = '6f1c1c3e-2f7a-4f0e-9d4e-5b8a9f1d2c3b'
+  expect(isCrashLogId(crashLogId(appId))).toBe(true)
+  expect(isCrashLogId(appId)).toBe(false)
+  expect(isCrashLogId('not-a-uuid:crashes')).toBe(false)
+})

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

@@ -0,0 +1,28 @@
+import { contract } from 'experimental-a2'
+import { z } from 'zod'
+import { isAppId } from './apps'
+
+/**
+ * The dev tools' crashes for one app, in a log of their own so the app's
+ * log stays its conversation: a request, then the crash that carried it
+ * out. The state is whether one is still pending.
+ */
+export const crashLog = contract({
+  name: 'a0-crashes',
+  events: {
+    'crash.requested': z.object({}),
+    crashed: z.object({}),
+  },
+  reducer: {
+    name: 'a0-crashes.v1',
+    initialState: false as boolean,
+    fold: (_pending, event) => event.type === 'crash.requested',
+  },
+})
+
+const suffix = ':crashes'
+
+export const crashLogId = (appId: string): string => `${appId}${suffix}`
+
+export const isCrashLogId = (id: string): boolean =>
+  id.endsWith(suffix) && isAppId(id.slice(0, -suffix.length))

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

@@ -0,0 +1,164 @@
+'use client'
+import type { ReactNode } from 'react'
+import { memo, useEffect, useState } from 'react'
+import { useSearchParams } from 'next/navigation'
+import { X, Zap } from 'lucide-react'
+import { crashLogId } from './crashes'
+import { setFlag, toggleDevtools } from './flags'
+import { logPage } from './model'
+import { useCrashLog, useSession } from './session'
+
+type LogEvent = ReturnType<typeof useSession>['events'][number]
+
+const gap = (ms: number): string =>
+  ms < 1000 ? `+${Math.round(ms)}ms` : `+${(ms / 1000).toFixed(2)}s`
+
+/**
+ * The app's raw A2 log, and ways to break the function running its agent:
+ * a crash, or a 5-second time limit, so the recovery is there to watch.
+ */
+export function DevTools({
+  appId,
+  deployed,
+  crashesAllowed,
+}: {
+  appId: string
+  /** Function limits and crashes only mean something on Vercel. */
+  deployed: boolean
+  crashesAllowed: boolean
+}): ReactNode {
+  const { state, events, index, history, hydrated, loadHistory } = useSession()
+  const short = useSearchParams().get('limit') === '5s'
+  const crashes = useCrashLog({ sessionId: crashLogId(appId) })
+  const [error, setError] = useState<string | null>(null)
+
+  const load = (options: { before?: number }): void => {
+    loadHistory({ ...options, limit: logPage }).catch((cause: unknown) =>
+      setError(cause instanceof Error ? cause.message : String(cause)),
+    )
+  }
+  // Opening reads the latest page. The client skips what it already holds,
+  // such as the server's seed, so this reads nothing when there's one.
+  useEffect(() => {
+    if (hydrated && !history.complete) load({ before: index + 1 })
+  }, [hydrated])
+
+  const crash = (): void => {
+    setError(null)
+    crashes
+      .push({ type: 'crash.requested', payload: {} })
+      .catch((cause: unknown) =>
+        setError(cause instanceof Error ? cause.message : String(cause)),
+      )
+  }
+
+  const localOnly = deployed ? undefined : "next dev doesn't limit functions"
+  return (
+    <section aria-label="Dev tools" className="a0-devtools">
+      <header className="a0-devtools-bar">
+        <span className="a0-devtools-title">
+          Log <span>{events.length} events</span>
+        </span>
+        {error && (
+          <span role="alert" className="a0-error">
+            {error}
+          </span>
+        )}
+        <label className="a0-devtools-switch" title={localOnly}>
+          <input
+            type="checkbox"
+            checked={short}
+            disabled={!deployed}
+            onChange={(event) =>
+              setFlag({
+                name: 'limit',
+                value: event.currentTarget.checked ? '5s' : null,
+              })
+            }
+          />
+          5-second functions
+        </label>
+        {/* A crash only means something while the agent works. */}
+        {state.active && (
+          <button
+            type="button"
+            className="a0-ghost a0-devtools-crash"
+            disabled={!crashesAllowed || crashes.state}
+            title={
+              crashesAllowed
+                ? 'Ends the process running the agent, right now'
+                : 'Crashes need a preview deployment, or A0_CRASHES=on'
+            }
+            onClick={crash}
+          >
+            <Zap size={13} aria-hidden />
+            {crashes.state ? 'Crashing…' : 'Crash'}
+          </button>
+        )}
+        <button
+          type="button"
+          className="a0-icon-button"
+          aria-label="Close dev tools"
+          title="Close (⌘J)"
+          onClick={toggleDevtools}
+        >
+          <X size={14} />
+        </button>
+      </header>
+      {/* Reversed, so the view stays pinned to the newest event. */}
+      <div className="a0-log-scroll">
+        <ol className="a0-log">
+          {!history.complete && (
+            <li>
+              <button
+                type="button"
+                className="a0-ghost a0-log-older"
+                disabled={history.loading}
+                onClick={() => load({})}
+              >
+                {history.loading ? 'Loading…' : 'Load older'}
+              </button>
+            </li>
+          )}
+          {events.map((event, position) => (
+            <LogRow
+              key={event.id}
+              event={event}
+              previous={events[position - 1]}
+            />
+          ))}
+        </ol>
+      </div>
+    </section>
+  )
+}
+
+// Rows keep their events' identity, so a new event renders only its own row.
+const LogRow = memo(function LogRow({
+  event,
+  previous,
+}: {
+  event: LogEvent
+  previous: LogEvent | undefined
+}): ReactNode {
+  const payload = JSON.stringify(event.payload)
+  return (
+    <li>
+      <details className="a0-log-row">
+        <summary title={event.createdAt.toISOString()}>
+          <span className="a0-log-index">{event.index}</span>
+          <span className="a0-log-gap">
+            {previous
+              ? gap(event.createdAt.getTime() - previous.createdAt.getTime())
+              : ''}
+          </span>
+          <span className="a0-log-type">{event.type}</span>
+          <code>
+            {payload.length > 240 ? `${payload.slice(0, 240)}…` : payload}
+          </code>
+        </summary>
+        <pre>{JSON.stringify(event.payload, null, 2)}</pre>
+      </details>
+    </li>
+  )
+})

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

@@ -0,0 +1,6 @@
+import { appEvents } from '../server'
+
+export { appEvents as GET, appEvents as POST }
+
+// Agent work started by a push runs after the response, up to this long.
+export const maxDuration = 300

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

@@ -0,0 +1,30 @@
+/**
+ * The dev tools' state lives in the query: `?devtools` while they're open,
+ * and `limit=5s` for the 5-second switch. Setting a flag is browser-only.
+ */
+
+/** A query string for a URL, with bare flags as `?devtools`, not `?devtools=`. */
+export function queryString(params: URLSearchParams): string {
+  const query = params.toString().replace(/=(?=&|$)/g, '')
+  return query && `?${query}`
+}
+
+/** Sets or clears one flag, in place, without a navigation. */
+export function setFlag({
+  name,
+  value,
+}: {
+  name: 'devtools' | 'limit'
+  value: string | null
+}): void {
+  const params = new URLSearchParams(location.search)
+  if (value === null) params.delete(name)
+  else params.set(name, value)
+  history.replaceState(null, '', `${location.pathname}${queryString(params)}`)
+}
+
+export const toggleDevtools = (): void =>
+  setFlag({
+    name: 'devtools',
+    value: new URLSearchParams(location.search).has('devtools') ? null : '',
+  })

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

@@ -0,0 +1,38 @@
+import type { Metadata } from 'next'
+import type { ReactNode } from 'react'
+import { cookies } from 'next/headers'
+import { appList, isAppId } from './apps'
+import { listCookie, parseWidths, widthsCookie } from './cookies'
+import { listServer } from './server'
+import { A0Shell } from './shell'
+import './a0.css'
+
+export const metadata: Metadata = { title: 'A0 · a2 example' }
+
+/** The apps list and the columns stay put while the app beside them changes. */
+export default async function A0Layout({
+  children,
+}: {
+  children: ReactNode
+}): Promise<ReactNode> {
+  const jar = await cookies()
+  const saved = jar.get(listCookie)?.value
+  const listId = saved && isAppId(saved) ? saved : null
+  const list = listId
+    ? { id: listId, initial: await listServer.session(listId).state() }
+    : {
+        // Becomes this browser's list with its first write.
+        id: crypto.randomUUID(),
+        initial: { state: appList.reducer.initialState, index: 0 },
+      }
+  return (
+    <A0Shell
+      list={list}
+      widths={parseWidths(jar.get(widthsCookie)?.value)}
+      renderedAt={Date.now()}
+      newAppId={crypto.randomUUID()}
+    >
+      {children}
+    </A0Shell>
+  )
+}

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

@@ -0,0 +1,10 @@
+import { isAppId } from '../apps'
+import { listServer } from '../server'
+
+function list(request: Request): Promise<Response> {
+  return listServer.fetch(request, {
+    authorize: (operation) => isAppId(operation.sessionId),
+  })
+}
+
+export { list as GET, list as POST }

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

@@ -0,0 +1,56 @@
+import type { ContractEvent } from 'experimental-a2'
+import { expect, it } from 'vitest'
+import { appAgent, defaultModelChoice } from './model'
+
+const chosen = (payload: unknown): ContractEvent<typeof appAgent.events> =>
+  ({
+    id: 'choice',
+    index: 1,
+    sessionId: 'app',
+    createdAt: new Date(0),
+    type: 'model.chosen',
+    payload,
+  }) as ContractEvent<typeof appAgent.events>
+
+const validate = (payload: unknown) =>
+  appAgent.events['model.chosen']['~standard'].validate(payload)
+
+it('defaults to Opus 5.5 in fast mode', () => {
+  expect(appAgent.reducer.initialState.modelChoice).toEqual({
+    model: 'anthropic/claude-opus-5.5',
+    reasoning: 'provider-default',
+    fast: true,
+  })
+  expect(defaultModelChoice).toEqual(appAgent.reducer.initialState.modelChoice)
+})
+
+it("keeps the latest choice in the app's state", () => {
+  const choice = {
+    model: 'openai/gpt-5.6-luna',
+    reasoning: 'high',
+    fast: false,
+  }
+  const state = appAgent.reducer.fold(
+    appAgent.reducer.initialState,
+    chosen(choice),
+  )
+  expect(state.modelChoice).toEqual(choice)
+  expect(state.messages).toEqual([])
+})
+
+it('fills in defaults and rejects choices a browser could write badly', () => {
+  expect(validate({ model: ' anthropic/claude-sonnet-5 ' })).toEqual({
+    value: {
+      model: 'anthropic/claude-sonnet-5',
+      reasoning: 'provider-default',
+      fast: false,
+    },
+  })
+  for (const payload of [
+    {},
+    { model: '   ' },
+    { model: 'openai/gpt-5.6-luna', reasoning: 'maximum' },
+    { model: 'openai/gpt-5.6-luna', fast: 'yes' },
+  ])
+    expect(validate(payload)).toHaveProperty('issues')
+})

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

@@ -0,0 +1,58 @@
+import type { UIMessage } from 'ai'
+import { agentContract } from 'experimental-a2/ai'
+import { z } from 'zod'
+
+/** Log events the dev tools read at a time. */
+export const logPage = 200
+
+/** The port the agent serves its Next.js app on, and the preview shows. */
+export const appPort = 3000
+
+export const reasoningSchema = z.enum([
+  'provider-default',
+  'none',
+  'minimal',
+  'low',
+  'medium',
+  'high',
+  'xhigh',
+])
+
+/** What the app's next request runs with. The browser picks it and the log keeps it. */
+const modelChoiceSchema = z.object({
+  model: z.string().trim().min(1),
+  reasoning: reasoningSchema.default('provider-default'),
+  fast: z.boolean().default(false),
+})
+
+export type ModelChoice = z.output<typeof modelChoiceSchema>
+
+export const defaultModelChoice: ModelChoice = {
+  model: 'anthropic/claude-opus-5.5',
+  reasoning: 'provider-default',
+  fast: true,
+}
+
+export type AppMessage = UIMessage
+
+/** The coding agent's contract, shared by the server and the browser. */
+export const appAgent = agentContract({
+  name: 'a0',
+  events: { 'model.chosen': modelChoiceSchema },
+  reducer: {
+    name: 'a0.model-choice.v1',
+    initialState: { modelChoice: defaultModelChoice },
+    fold: (state, event) =>
+      event.type === 'model.chosen' ? { modelChoice: event.payload } : state,
+  },
+})
+
+export const toolLabels: Record<string, string> = {
+  bash: 'Running a command',
+  show_preview: 'Showing the app',
+}
+
+/** While the model is still writing a call's input. */
+export const writingLabels: Record<string, string> = {
+  bash: 'Writing a command',
+}

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

@@ -0,0 +1,14 @@
+import { redirect } from 'next/navigation'
+import { queryString } from './flags'
+
+/** A new app is just an id with no log yet; the query keeps the dev tools. */
+export default async function NewApp({
+  searchParams,
+}: {
+  searchParams: Promise<Record<string, string | string[] | undefined>>
+}): Promise<never> {
+  const params = new URLSearchParams()
+  for (const [name, value] of Object.entries(await searchParams))
+    for (const one of [value ?? []].flat()) params.append(name, one)
+  redirect(`/a0/${crypto.randomUUID()}${queryString(params)}`)
+}

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
+}