experimental-a2 0.17.0 → 0.18.1

package/examples/playground/DEPLOY.md

@@ -3,7 +3,7 @@
 The event log runs with zero setup in development (SQLite at `.a2/dev.db`,
 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`.
+`node_modules/experimental-a2/docs/server/05-production.mdx`.
 
 ## 1. A store
 
@@ -118,10 +118,8 @@ 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.
+Crashing ends everything else that instance is serving, and under `next dev`
+it takes the dev server down with it.
 
 ## 6. WebSockets for the canvas
 

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

@@ -3,8 +3,8 @@ 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 { harnessFrom, logPage } from '../model'
+import { agentServers } from '../server'
 import { SessionProvider } from '../session'
 
 /** An app, from its current state; the provider follows its log from there. */
@@ -17,31 +17,30 @@ export default async function A0App({
 }): Promise<ReactNode> {
   const { appId } = await params
   if (!isAppId(appId)) notFound()
-  const initial = await agentServer.session(appId).state()
+  const query = await searchParams
+  const harness = harnessFrom(query.harness)
+  const session = agentServers[harness].session(appId)
+  const initial = await session.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({
+    query.devtools !== undefined && initial.index > 0
+      ? await session.history({
           gte: Math.max(1, initial.index - logPage + 1),
           lte: initial.index,
         })
       : undefined
   return (
     <SessionProvider
-      key={appId}
+      // Another harness is another log, followed over its own route.
+      key={`${harness}:${appId}`}
       sessionId={appId}
       initial={initial}
       initialEvents={events}
     >
       <AppView
         appId={appId}
-        devtools={
-          <DevTools
-            appId={appId}
-            deployed={!!process.env.VERCEL}
-            crashesAllowed={crashesAllowed}
-          />
-        }
+        harness={harness}
+        devtools={<DevTools appId={appId} deployed={!!process.env.VERCEL} />}
       />
     </SessionProvider>
   )

package/examples/playground/app/a0/app-list.tsx

@@ -35,9 +35,16 @@ export function AppList({
   onDelete: (app: App) => void
 }): ReactNode {
   const now = useNow(renderedAt)
-  // Links keep the dev tools' state from app to app.
+  // Links keep the dev tools' state from app to app. A new app starts with
+  // the open app's harness; a listed one keeps its own.
   const params = useSearchParams()
   const query = queryString(new URLSearchParams(params))
+  const appQuery = (app: App): string => {
+    const own = new URLSearchParams(params)
+    own.delete('harness')
+    if (app.harness) own.set('harness', app.harness)
+    return queryString(own)
+  }
   // Open dev tools also read each page's log, so they don't prefetch every
   // app's in full.
   const prefetch = params.has('devtools') ? null : true
@@ -63,7 +70,7 @@ export function AppList({
             app={app}
             when={timeAgo({ at: app.promptedAt, now })}
             current={app.id === currentId}
-            href={`/a0/${app.id}${query}`}
+            href={`/a0/${app.id}${appQuery(app)}`}
             prefetch={prefetch}
             onRename={(name) => onRename({ id: app.id, name })}
             onDelete={() => onDelete(app)}

package/examples/playground/app/a0/app-view.tsx

@@ -5,6 +5,7 @@ import { useSearchParams } from 'next/navigation'
 import { titleFromPrompt } from './apps'
 import { Chat } from './chat'
 import { ColumnEdge } from './columns'
+import type { Harness } from './model'
 import { checkApp, PreviewPane } from './preview-pane'
 import { useSession } from './session'
 import { useApps } from './shell'
@@ -12,9 +13,11 @@ import { useApps } from './shell'
 /** One app: its chat with the agent, and the app it builds. */
 export function AppView({
   appId,
+  harness,
   devtools,
 }: {
   appId: string
+  harness: Harness
   /** Shown while the query has `devtools`. */
   devtools: ReactNode
 }): ReactNode {
@@ -41,8 +44,13 @@ export function AppView({
       <section aria-label="Chat" className="a0-chat">
         <h1 className="a0-title">{name}</h1>
         <Chat
+          harness={harness}
           onPrompt={(text) =>
-            prompted({ id: appId, name: titleFromPrompt(prompt ?? text) })
+            prompted({
+              id: appId,
+              name: titleFromPrompt(prompt ?? text),
+              harness,
+            })
           }
           autoFocus={!app}
         />

package/examples/playground/app/a0/apps/[appId]/route.ts

@@ -1,7 +1,7 @@
 import { inputs } from 'experimental-a2/ai'
 import { isAppId } from '../../apps'
 import { deleteAppSandbox } from '../../sandbox'
-import { agentServer } from '../../server'
+import { agentServers } from '../../server'
 
 /**
  * Stops the agent's current turn, so no later tool call brings the sandbox
@@ -14,10 +14,15 @@ export async function DELETE(
   const { appId } = await context.params
   if (!isAppId(appId))
     return Response.json({ error: 'Unknown app.' }, { status: 404 })
-  const session = agentServer.session(appId)
-  const { state } = await session.state()
-  if (state.active)
-    await session.append(...inputs.stop({ turnId: state.active.turnId }))
+  // The app's agent is whichever harness's agent has its log.
+  await Promise.all(
+    Object.values(agentServers).map(async (server) => {
+      const session = server.session(appId)
+      const { state } = await session.state()
+      if (state.active)
+        await session.append(...inputs.stop({ turnId: state.active.turnId }))
+    }),
+  )
   await deleteAppSandbox({ appId })
   return Response.json({ ok: true })
 }

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

@@ -114,3 +114,15 @@ it('reads the widths someone dragged to, and ignores bad ones', () => {
     chat: 480,
   })
 })
+
+it("keeps the harness an app's agent runs, for its link", () => {
+  expect(
+    fold(
+      ['app.created', { appId: first, name: 'todo app', harness: 'fx' }, 1_000],
+      ['app.created', { appId: second, name: 'counter' }, 2_000],
+    ),
+  ).toEqual([
+    { id: first, name: 'todo app', promptedAt: 1_000, harness: 'fx' },
+    { id: second, name: 'counter', promptedAt: 2_000 },
+  ])
+})

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

@@ -1,14 +1,21 @@
 import { contract } from 'experimental-a2'
 import { z } from 'zod'
+import { type Harness, harnessSchema } from './model'
 
 export const isAppId = (value: string): boolean =>
   z.uuid().safeParse(value).success
 
 /**
  * An app is one conversation with the coding agent and one sandbox. It's
- * listed with the time of its latest prompt, as the server recorded it.
+ * listed with the time of its latest prompt, as the server recorded it, and
+ * the harness its agent runs when that's not the AI SDK's.
  */
-export type App = { id: string; name: string; promptedAt: number }
+export type App = {
+  id: string
+  name: string
+  promptedAt: number
+  harness?: Harness
+}
 
 const appId = z.uuid()
 const name = z.string().trim().min(1).max(80)
@@ -21,7 +28,11 @@ const name = z.string().trim().min(1).max(80)
 export const appList = contract({
   name: 'a0-apps',
   events: {
-    'app.created': z.object({ appId, name }),
+    'app.created': z.object({
+      appId,
+      name,
+      harness: harnessSchema.optional(),
+    }),
     'app.prompted': z.object({ appId }),
     'app.renamed': z.object({ appId, name }),
     'app.deleted': z.object({ appId }),
@@ -33,10 +44,14 @@ export const appList = contract({
       const { appId: id } = event.payload
       const promptedAt = event.createdAt.getTime()
       switch (event.type) {
-        case 'app.created':
-          return apps.some((app) => app.id === id)
-            ? apps
-            : [...apps, { id, name: event.payload.name, promptedAt }]
+        case 'app.created': {
+          if (apps.some((app) => app.id === id)) return apps
+          const { name: created, harness } = event.payload
+          return [
+            ...apps,
+            { id, name: created, promptedAt, ...(harness ? { harness } : {}) },
+          ]
+        }
         case 'app.prompted':
           return apps.map((app) =>
             app.id === id ? { ...app, promptedAt } : app,

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

@@ -1,10 +1,15 @@
 'use client'
 import type { ReactNode } from 'react'
 import { useEffect, useRef, useState } from 'react'
+import { useRouter, useSearchParams } from 'next/navigation'
 import { Asterisk, LoaderCircle, Zap } from 'lucide-react'
 import { inputs } from 'experimental-a2/ai'
+import { queryString } from './flags'
 import {
   type AppMessage,
+  type Harness,
+  harnessLabels,
+  harnessSchema,
   type ModelChoice,
   reasoningSchema,
   toolLabels,
@@ -22,13 +27,25 @@ const suggestions = [
 
 /** The coding agent's conversation: its words, and one line per tool step. */
 export function Chat({
+  harness,
   onPrompt,
   autoFocus,
 }: {
+  harness: Harness
   onPrompt: (prompt: string) => void
   autoFocus: boolean
 }): ReactNode {
   const { state, push } = useSession()
+  const router = useRouter()
+  const params = useSearchParams()
+  // Each harness's agent has its own log, so an app picks one before its
+  // first message: the URL names it, and the page follows that agent.
+  const pickHarness = (next: Harness): void => {
+    const query = new URLSearchParams(params)
+    if (next === 'ai-sdk') query.delete('harness')
+    else query.set('harness', next)
+    router.replace(`${location.pathname}${queryString(query)}`)
+  }
   const [error, setError] = useState<string | null>(null)
   // A change here applies when the next message goes out with it, so typing a
   // model id doesn't record a choice per keystroke. Until then, the composer
@@ -133,6 +150,8 @@ export function Chat({
         queued={state.inbox.items.length}
         settings={settings}
         onSettings={setChosen}
+        harness={harness}
+        onHarness={state.messages.length ? null : pickHarness}
         autoFocus={autoFocus}
       />
     </>
@@ -179,7 +198,10 @@ function MessagePart({
   const name = part.type.slice('tool-'.length)
   const done = part.state === 'output-available'
   const failed = part.state === 'output-error'
-  const detail = (part as { input?: { command?: unknown } }).input?.command
+  // A command, or the file one of Pi's tools works on.
+  const input = (part as { input?: { command?: unknown; path?: unknown } })
+    .input
+  const detail = input?.command ?? input?.path
   const took = (part as { output?: { durationMs?: unknown } }).output
     ?.durationMs
   const label =
@@ -220,6 +242,8 @@ function Composer({
   queued,
   settings,
   onSettings,
+  harness,
+  onHarness,
   autoFocus,
 }: {
   onSend: (text: string) => Promise<void>
@@ -228,6 +252,9 @@ function Composer({
   queued: number
   settings: ModelChoice
   onSettings: (settings: ModelChoice) => void
+  harness: Harness
+  /** Until the app's first message; it keeps its harness after that. */
+  onHarness: ((harness: Harness) => void) | null
   autoFocus: boolean
 }): ReactNode {
   const [text, setText] = useState('')
@@ -297,6 +324,25 @@ function Composer({
       />
       <div className="a0-composer-bar">
         <div className="a0-composer-model">
+          <select
+            aria-label="Harness"
+            title={
+              onHarness
+                ? "The agent's loop: the AI SDK's, FX's, or Pi's"
+                : 'The agent loop this app runs'
+            }
+            value={harness}
+            disabled={!onHarness}
+            onChange={(event) =>
+              onHarness?.(harnessSchema.parse(event.target.value))
+            }
+          >
+            {harnessSchema.options.map((option) => (
+              <option key={option} value={option}>
+                {harnessLabels[option]}
+              </option>
+            ))}
+          </select>
           <input
             aria-label="Model"
             title="The Gateway model the next request runs with"

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

@@ -20,12 +20,10 @@ const gap = (ms: number): string =>
 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'
@@ -83,12 +81,8 @@ export function DevTools({
           <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'
-            }
+            disabled={crashes.state}
+            title="Ends the process running the agent, right now"
             onClick={crash}
           >
             <Zap size={13} aria-hidden />

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/model.test.ts

@@ -1,6 +1,11 @@
 import type { ContractEvent } from 'experimental-a2'
 import { expect, it } from 'vitest'
-import { appAgent, defaultModelChoice } from './model'
+import {
+  appAgent,
+  defaultModelChoice,
+  harnessAgents,
+  harnessFrom,
+} from './model'
 
 const chosen = (payload: unknown): ContractEvent<typeof appAgent.events> =>
   ({
@@ -54,3 +59,15 @@ it('fills in defaults and rejects choices a browser could write badly', () => {
   ])
     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

@@ -35,24 +35,61 @@ export const defaultModelChoice: ModelChoice = {
 
 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 = 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 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/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

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

@@ -6,7 +6,7 @@ import { z } from 'zod'
 import { store } from '@/lib/store'
 import { isAppId } from './apps'
 import { deleteAppSandbox } from './sandbox'
-import { agentServer } from './server'
+import { agentServers } from './server'
 
 // How long a new app's sandbox waits for a first prompt.
 const IDLE_GRACE_MS = 10 * 60 * 1000
@@ -38,9 +38,15 @@ export const sandboxServer = createServer({
   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 })
+      // 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 })
     },
   },
 })