experimental-a2 0.17.0 → 0.18.0

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, crashesAllowed } from '../server'
 import { SessionProvider } from '../session'
 
 /** An app, from its current state; the provider follows its log from there. */
@@ -17,24 +17,29 @@ 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}
+        harness={harness}
         devtools={
           <DevTools
             appId={appId}

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/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 })
     },
   },
 })

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(),
+      }
+    },
+  }
+}