experimental-a2 0.16.1 → 0.18.0

package/examples/playground/app/a0/crash-on-request.ts

@@ -0,0 +1,72 @@
+import 'server-only'
+import type { AIState } from 'experimental-a2/ai'
+import { type AppMessage, appAgent } from './model'
+import type { agentServer, crashServer } from './server'
+
+type AppSession = ReturnType<typeof agentServer.session>
+type CrashLog = ReturnType<typeof crashServer.session>
+
+const working = (state: AIState<AppMessage>): boolean =>
+  state.status === 'generating' ||
+  state.status === 'waiting' ||
+  !!state.pendingQueueCommands?.length
+
+/** Resolves once the app's agent stops working. */
+async function workDone(app: AppSession): Promise<void> {
+  const { state: initial, index } = await app.state()
+  let state = initial
+  if (!working(state)) return
+  for await (const event of app.stream({ startAfter: index })) {
+    // A cleared app has nothing left to work on.
+    if (event.type === 'a2.cleared') return
+    state = appAgent.reducer.fold(state, event)
+    if (!working(state)) return
+  }
+}
+
+async function listen({
+  app,
+  log,
+}: {
+  app: AppSession
+  log: CrashLog
+}): Promise<void> {
+  const crash = async (): Promise<never> => {
+    // Recorded first, so the resumed work doesn't crash again.
+    await log.append({ type: 'crashed', payload: {} })
+    process.exit(1)
+  }
+  const { state: pending, index } = await log.state()
+  if (pending) return crash()
+  const requests = log.stream({ startAfter: index })[Symbol.asyncIterator]()
+  // When the work ends, closing the stream ends the loop below.
+  const close = (): void => void requests.return?.()
+  void workDone(app).then(close, close)
+  for await (const event of { [Symbol.asyncIterator]: () => requests })
+    if (event.type === 'crash.requested') return crash()
+}
+
+// One listener per app in this process, while its agent works here.
+const listening = new Map<string, Promise<void>>()
+
+/**
+ * The dev tools' crash: while the app's agent works in this process, a
+ * request in its crash log ends the process at once, mid-stream or
+ * mid-command, and the scheduler resumes the turn in a fresh invocation.
+ * Each step calls this, so work resumed elsewhere gets a listener too.
+ */
+export function crashOnRequest({
+  appId,
+  app,
+  log,
+}: {
+  appId: string
+  app: AppSession
+  log: CrashLog
+}): Promise<void> {
+  const current = listening.get(appId)
+  if (current) return current
+  const started = listen({ app, log }).finally(() => listening.delete(appId))
+  listening.set(appId, started)
+  return started
+}

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/fx/events/route.ts

@@ -0,0 +1,9 @@
+import { harnessEvents } from '../../server'
+
+/** The events of apps whose agent runs FX's loop. */
+const events = harnessEvents('fx')
+
+export { events as GET, events 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/fx/scheduler/route.ts

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

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

@@ -0,0 +1,11 @@
+import { harnessEvents } 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.
+ */
+const events = harnessEvents('fx')
+
+export { events as POST }
+
+export const maxDuration = 5

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,73 @@
+import type { ContractEvent } from 'experimental-a2'
+import { expect, it } from 'vitest'
+import {
+  appAgent,
+  defaultModelChoice,
+  harnessAgents,
+  harnessFrom,
+} 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')
+})
+
+it("reads the app's harness from its URL, the AI SDK's by default", () => {
+  expect(harnessFrom('fx')).toBe('fx')
+  expect(harnessFrom(null)).toBe('ai-sdk')
+  expect(harnessFrom('other')).toBe('ai-sdk')
+  // Each harness's agent keeps its own logs.
+  expect(Object.values(harnessAgents).map((agent) => agent.name)).toEqual([
+    'a0',
+    'a0-fx',
+    'a0-pi',
+  ])
+})

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

@@ -0,0 +1,95 @@
+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 loop an app's agent runs: the AI SDK's, FX's, or Pi's. An
+ * app picks it before its first message and keeps it.
+ */
+export const harnessSchema = z.enum(['ai-sdk', 'fx', 'pi'])
+
+export type Harness = z.output<typeof harnessSchema>
+
+export const harnessLabels: Record<Harness, string> = {
+  'ai-sdk': 'AI SDK',
+  fx: 'FX',
+  pi: 'Pi',
+}
+
+/** The harness an app's URL names, `?harness=fx`; the AI SDK's without one. */
+export const harnessFrom = (value: unknown): Harness =>
+  harnessSchema.safeParse(value).data ?? 'ai-sdk'
+
+const appContract = (name: string) =>
+  agentContract({
+    name,
+    events: { 'model.chosen': modelChoiceSchema },
+    reducer: {
+      name: 'a0.model-choice.v1',
+      initialState: { modelChoice: defaultModelChoice },
+      fold: (state, event) =>
+        event.type === 'model.chosen' ? { modelChoice: event.payload } : state,
+    },
+  })
+
+/** The coding agent's contract, shared by the server and the browser. */
+export const appAgent = appContract('a0')
+
+/**
+ * Each harness's agent keeps its own logs. They differ only in name, so the
+ * browser follows any of them with `appAgent`.
+ */
+export const harnessAgents = {
+  'ai-sdk': appAgent,
+  fx: appContract('a0-fx'),
+  pi: appContract('a0-pi'),
+} satisfies Record<Harness, typeof appAgent>
+
+export const toolLabels: Record<string, string> = {
+  bash: 'Running a command',
+  show_preview: 'Showing the app',
+  // Pi's own tools.
+  read: 'Reading a file',
+  write: 'Writing a file',
+  edit: 'Editing a file',
+}
+
+/** While the model is still writing a call's input. */
+export const writingLabels: Record<string, string> = {
+  bash: 'Writing a command',
+  write: 'Writing a file',
+  edit: 'Writing an edit',
+}

package/examples/playground/app/a0/no-photon.cjs

@@ -0,0 +1,4 @@
+// Stands in for @silvia-odwyer/photon-node, whose WebAssembly the playground's
+// bundler cannot trace. Pi treats a photon that fails to load as no image
+// processing.
+throw new Error('photon is not available in the playground')

package/examples/playground/app/a0/no-quickjs.cjs

@@ -0,0 +1,3 @@
+// Stands in for quickjs-wasi, whose WebAssembly the playground's bundler
+// cannot trace. Only Pi's codemode extension imports it, and A0 never starts it.
+module.exports = {}

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/pi/events/route.ts

@@ -0,0 +1,9 @@
+import { harnessEvents } from '../../server'
+
+/** The events of apps whose agent runs Pi's loop. */
+const events = harnessEvents('pi')
+
+export { events as GET, events 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/pi/scheduler/route.ts

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

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

@@ -0,0 +1,11 @@
+import { harnessEvents } 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.
+ */
+const events = harnessEvents('pi')
+
+export { events as POST }
+
+export const maxDuration = 5