experimental-a2 0.17.0 → 0.18.1

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

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

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

@@ -2,6 +2,8 @@ import 'server-only'
 import { waitUntil } from '@vercel/functions'
 import { tool } from 'ai'
 import { handlerContext } from 'experimental-a2/ai'
+import { fx } from 'experimental-a2/ai/fx'
+import { pi } from 'experimental-a2/ai/pi'
 import { agent } from 'experimental-a2/ai/server'
 import { createServer } from 'experimental-a2/server'
 import { vercelQueues } from 'experimental-a2/scheduler-vercel'
@@ -10,7 +12,7 @@ import { store } from '@/lib/store'
 import { appList, isAppId } from './apps'
 import { crashOnRequest } from './crash-on-request'
 import { crashLog, crashLogId, isCrashLogId } from './crashes'
-import { appAgent, appPort } from './model'
+import { appPort, type Harness, harnessAgents, type ModelChoice } from './model'
 import {
   appDir,
   appSandbox,
@@ -19,8 +21,11 @@ import {
   START_DEV,
   workspace,
 } from './sandbox'
+import { sandboxSession } from './sandbox-session'
 
-const INSTRUCTIONS = `You are a coding agent that builds a Next.js app in your own Linux sandbox, through the bash tool. The user watches the app in a live preview next to this chat.
+const instructions = (
+  tools: string,
+): string => `You are a coding agent that builds a Next.js app in your own Linux sandbox, ${tools}. The user watches the app in a live preview next to this chat.
 - ${appDir} already holds a blank Next.js app (App Router, TypeScript, Tailwind) with its dependencies installed, and next dev serves it on port ${appPort} with hot reload. It may still be starting when you begin: don't wait for it, poll it, or start another one. Build what the user asks for there; don't create another app.
 - Until you change them, app/page.tsx renders an empty <main />, app/layout.tsx only sets the title, and app/globals.css only imports Tailwind. Write them directly; there's no need to look first.
 - Assume your edits work. Don't curl the dev server, sleep, or read the page back to check, and don't run builds, type checks or lint unless the user asks.
@@ -48,9 +53,7 @@ const tools = {
     execute: ({ path }) =>
       timed(async () =>
         previewUrl({
-          sandbox: await appSandbox({
-            appId: handlerContext(appAgent).session.id,
-          }),
+          sandbox: await appSandbox({ appId: handlerContext().session.id }),
           path,
         }),
       ),
@@ -63,7 +66,7 @@ const tools = {
       timeoutSeconds: z.number().int().min(1).max(240).default(120),
     }),
     execute: ({ command, timeoutSeconds }) => {
-      const context = handlerContext(appAgent)
+      const context = handlerContext()
       return timed(async () =>
         bash({
           sandbox: await appSandbox({ appId: context.session.id }),
@@ -76,56 +79,106 @@ const tools = {
   }),
 }
 
+const queued = !!(process.env.VERCEL || process.env.A2_QUEUES)
+
 /**
  * Wakes agent work in a fresh invocation when the one that started it ends,
- * and recovers from crashed ones.
+ * and recovers from crashed ones. Each harness's agent has its own topic.
  */
-export const appScheduler =
-  process.env.VERCEL || process.env.A2_QUEUES
-    ? vercelQueues({ topic: 'a2-a0' })
-    : undefined
+export const appSchedulers = {
+  'ai-sdk': queued ? vercelQueues({ topic: 'a2-a0' }) : undefined,
+  fx: queued ? vercelQueues({ topic: 'a2-a0-fx' }) : undefined,
+  pi: queued ? vercelQueues({ topic: 'a2-a0-pi' }) : undefined,
+}
 
-// Each step runs with the app's model choice. The browser pushes it, and the
-// contract's schema checks it on the way in.
-export const agentServer = agent({
+/**
+ * The app's model choice for a step. The browser pushes it, and the
+ * contract's schema checks it on the way in.
+ */
+function chosenModel({
+  harness,
+  event,
+  state,
+}: {
+  harness: Harness
+  event: { sessionId: string }
+  state: { modelChoice: ModelChoice }
+}) {
+  // Every step starts here, in the process that runs it, which is what
+  // the dev tools' crash has to end.
+  const appId = event.sessionId
+  waitUntil(
+    crashOnRequest({
+      appId,
+      app: agentServers[harness].session(appId),
+      log: crashServer.session(crashLogId(appId)),
+    }).catch(() => {}),
+  )
+  const { model, reasoning, fast } = state.modelChoice
+  return { model, reasoning, speed: fast ? 'fast' : 'standard' } as const
+}
+
+const shared = (harness: Harness) => ({
   ...(store ? { store } : {}),
-  ...(appScheduler ? { scheduler: appScheduler } : {}),
-  contract: appAgent,
-  model: ({ event, state }) => {
-    // Every step starts here, in the process that runs it, which is what
-    // the dev tools' crash has to end.
-    if (crashesAllowed) {
-      const appId = event.sessionId
-      waitUntil(
-        crashOnRequest({
-          appId,
-          app: agentServer.session(appId),
-          log: crashServer.session(crashLogId(appId)),
-        }).catch(() => {}),
-      )
-    }
-    const { model, reasoning, fast } = state.modelChoice
-    return { model, reasoning, speed: fast ? 'fast' : 'standard' }
+  ...(appSchedulers[harness] ? { scheduler: appSchedulers[harness] } : {}),
+  contract: harnessAgents[harness],
+  maxSteps: 80,
+})
+
+export const agentServer = agent({
+  ...shared('ai-sdk'),
+  model: ({ event, state }) => chosenModel({ harness: 'ai-sdk', event, state }),
+  harness: {
+    type: 'ai-sdk',
+    generation: () => ({
+      // Claude leaves its thinking's text out unless asked for a summary.
+      providerOptions: {
+        anthropic: { thinking: { type: 'adaptive', display: 'summarized' } },
+      },
+    }),
   },
-  generation: () => ({
-    // Claude leaves its thinking's text out unless asked for a summary.
-    providerOptions: {
-      anthropic: { thinking: { type: 'adaptive', display: 'summarized' } },
-    },
-  }),
-  instructions: INSTRUCTIONS,
+  instructions: instructions('through the bash tool'),
   tools,
-  maxSteps: 80,
 })
 
-/** The app's event stream and pushes; only an app id names a session. */
-export function appEvents(request: Request): Promise<Response> {
-  return agentServer.fetch(request, {
-    // The agent refuses the AI protocol's server-authored events itself.
-    authorize: (operation) => isAppId(operation.sessionId),
-  })
+/** FX's own loop, with the same tools and prompt. */
+const fxServer = agent({
+  ...shared('fx'),
+  harness: fx(),
+  model: ({ event, state }) => chosenModel({ harness: 'fx', event, state }),
+  instructions: instructions('through the bash tool'),
+  tools,
+})
+
+/** Pi's own loop and tools, working in the app's sandbox, plus the preview. */
+const piServer = agent({
+  ...shared('pi'),
+  harness: pi({
+    sandbox: async ({ session }) =>
+      sandboxSession(await appSandbox({ appId: session.id })),
+  }),
+  model: ({ event, state }) => chosenModel({ harness: 'pi', event, state }),
+  instructions: instructions('with your tools'),
+  tools: { show_preview: tools.show_preview },
+})
+
+export const agentServers = {
+  'ai-sdk': agentServer,
+  fx: fxServer,
+  pi: piServer,
 }
 
+/** An app's event stream and pushes, for one harness's agent; only an app id names a session. */
+export const harnessEvents =
+  (harness: Harness) =>
+  (request: Request): Promise<Response> =>
+    agentServers[harness].fetch(request, {
+      // The agent refuses the AI protocol's server-authored events itself.
+      authorize: (operation) => isAppId(operation.sessionId),
+    })
+
+export const appEvents = harnessEvents('ai-sdk')
+
 /** The apps sidebar's lists, which only the browser writes. */
 export const listServer = createServer({
   ...(store ? { store } : {}),
@@ -138,20 +191,11 @@ export const crashServer = createServer({
   contract: crashLog,
 })
 
-/**
- * A crash ends the function instance, and anything else it's serving, so
- * only previews allow it, behind Deployment Protection, unless A0_CRASHES
- * is on. Under next dev it would take the dev server down.
- */
-export const crashesAllowed =
-  process.env.VERCEL_ENV === 'preview' || process.env.A0_CRASHES === 'on'
-
 /** The browser can only ask for a crash; the process it ends records it. */
 export function crashEvents(request: Request): Promise<Response> {
   return crashServer.fetch(request, {
     authorize: (operation) =>
       isCrashLogId(operation.sessionId) &&
-      (crashesAllowed || operation.type !== 'push') &&
       (operation.type !== 'push' ||
         operation.events.every((event) => event.type === 'crash.requested')),
   })

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

@@ -3,7 +3,7 @@ import { createClient } from 'experimental-a2/client'
 import { createReact } from 'experimental-a2/react'
 import { appList } from './apps'
 import { crashLog } from './crashes'
-import { appAgent } from './model'
+import { appAgent, type Harness, harnessFrom } from './model'
 
 /** The dev tools' switch, `?limit=5s`, for the app at this URL, while they're open. */
 export function shortFunctions(appId: string): boolean {
@@ -15,17 +15,29 @@ export function shortFunctions(appId: string): boolean {
   )
 }
 
+/** The harness the app at this URL runs, from `?harness=`. */
+export function appHarness(appId: string): Harness {
+  return location.pathname === `/a0/${appId}`
+    ? harnessFrom(new URLSearchParams(location.search).get('harness'))
+    : 'ai-sdk'
+}
+
+const routes = (appId: string): string => {
+  const harness = appHarness(appId)
+  return harness === 'ai-sdk' ? '/a0' : `/a0/${harness}`
+}
+
 /**
- * Follows an app's conversation log over the events route. Pushes go to a
- * 5-second function instead while the dev tools' switch is on.
+ * Follows an app's conversation log over its harness's events route. Pushes
+ * go to a 5-second function instead while the dev tools' switch is on.
  */
 export const appClient = createClient({
   contract: appAgent,
   api: {
     type: 'http',
-    stream: '/a0/events',
+    stream: (appId) => `${routes(appId)}/events`,
     push: (appId) =>
-      shortFunctions(appId) ? '/a0/short/events' : '/a0/events',
+      `${routes(appId)}${shortFunctions(appId) ? '/short' : ''}/events`,
   },
 })
 

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

@@ -4,6 +4,7 @@ import { createContext, useContext, useEffect, useState } from 'react'
 import { usePathname, useRouter, useSearchParams } from 'next/navigation'
 import { SiteNav } from '../components/site-header'
 import { type App, byLatestPrompt } from './apps'
+import type { Harness } from './model'
 import { AppList } from './app-list'
 import { ColumnEdge, Columns } from './columns'
 import { listCookie, readCookie, type Widths, writeCookie } from './cookies'
@@ -13,7 +14,7 @@ import { useList } from './session'
 type Apps = {
   listed: (id: string) => App | null
   /** Records a prompt to an app, listing it under `name` the first time. */
-  prompted: (app: { id: string; name: string }) => void
+  prompted: (app: { id: string; name: string; harness: Harness }) => void
   /** Makes a new app on screen the one "+" opens until it's prompted. */
   opened: (appId: string) => void
 }
@@ -85,12 +86,19 @@ export function A0Shell({
     apps.find((app) => app.id === id) ?? null
   const context: Apps = {
     listed,
-    prompted: ({ id, name }) => {
+    prompted: ({ id, name, harness }) => {
       if (listed(id)) {
         write({ type: 'app.prompted', payload: { appId: id } })
         return
       }
-      write({ type: 'app.created', payload: { appId: id, name } })
+      write({
+        type: 'app.created',
+        payload: {
+          appId: id,
+          name,
+          ...(harness === 'ai-sdk' ? {} : { harness }),
+        },
+      })
       if (id === ready) setReady(crypto.randomUUID())
     },
     opened: setReady,

package/examples/playground/app/agent/ingress.test.ts

@@ -19,9 +19,12 @@ const server = () => {
     contract: demoAgent,
     store: memory(),
     model: 'test/model',
-    generate: () => {
-      generations += 1
-      return new ReadableStream({ start: (controller) => controller.close() })
+    harness: {
+      type: 'ai-sdk',
+      generate: () => {
+        generations += 1
+        return new ReadableStream({ start: (controller) => controller.close() })
+      },
     },
   })
   return { agentServer, generations: () => generations }

package/examples/playground/app/agent/server.ts

@@ -137,8 +137,15 @@ export const agentServer = agent({
   ...(agentScheduler ? { scheduler: agentScheduler } : {}),
   telemetry,
   model: ({ state }) => modelSettings(state.modelChoice),
-  messageMetadata: traceMetadata,
-  compaction: ({ state }) => compactionOptions(state.compactionSettings),
+  harness: {
+    type: 'ai-sdk',
+    messageMetadata: traceMetadata,
+    compaction: ({ state }) => compactionOptions(state.compactionSettings),
+    generation: () => ({
+      telemetry: modelTelemetry(),
+      toolApproval: { restartService: 'user-approval' },
+    }),
+  },
   tools,
   instructions: `You are an incident-response agent for the playground.
 When responding to an incident, inspect checkout-api before taking action. Its
@@ -154,8 +161,4 @@ it again.
 
 When the operator asks you to run a shell command, call bash. Make one bash call
 at a time and wait for its result before calling it again. Be concise.`,
-  generation: () => ({
-    telemetry: modelTelemetry(),
-    toolApproval: { restartService: 'user-approval' },
-  }),
 })

package/examples/playground/app/agent/telemetry.test.ts

@@ -11,7 +11,15 @@ import { inputs } from 'experimental-a2/ai'
 import { agent } from 'experimental-a2/ai/server'
 import { memory } from 'experimental-a2/store-memory'
 import { otel } from 'experimental-a2/otel'
-import { afterAll, beforeAll, beforeEach, expect, it, vi } from 'vitest'
+import {
+  afterAll,
+  beforeAll,
+  beforeEach,
+  expect,
+  it,
+  onTestFinished,
+  vi,
+} from 'vitest'
 import { demoAgent } from './model'
 import { modelTelemetry, traceMetadata } from './telemetry'
 import { traceUrl } from './trace'
@@ -51,60 +59,73 @@ afterAll(async () => {
 it.each(['complete', 'stop'] as const)(
   'correlates standard SDK traces and releases spans when generation ends with %s',
   async (outcome) => {
-    const server = agent({
-      contract: demoAgent,
-      store: memory(),
-      telemetry: otel(),
-      generation: { telemetry: modelTelemetry() },
-      messageMetadata: traceMetadata,
-      model: new MockLanguageModelV4({
-        modelId: 'test-model',
-        doStream: async ({ abortSignal }) => ({
-          stream:
-            outcome === 'complete'
-              ? simulateReadableStream({
-                  chunks: [
-                    { type: 'stream-start', warnings: [] },
-                    { type: 'text-start', id: 'text' },
-                    { type: 'text-delta', id: 'text', delta: 'PRIVATE_OUTPUT' },
-                    { type: 'text-end', id: 'text' },
-                    {
-                      type: 'finish',
-                      finishReason: { unified: 'stop', raw: 'stop' },
-                      usage: {
-                        inputTokens: {
-                          total: 5,
-                          noCache: 5,
-                          cacheRead: 0,
-                          cacheWrite: 0,
-                        },
-                        outputTokens: { total: 2, text: 2, reasoning: 0 },
-                      },
-                      providerMetadata: {
-                        test: { secret: 'PRIVATE_METADATA' },
+    const model = new MockLanguageModelV4({
+      modelId: 'test-model',
+      doStream: async ({ abortSignal }) => ({
+        stream:
+          outcome === 'complete'
+            ? simulateReadableStream({
+                chunks: [
+                  { type: 'stream-start', warnings: [] },
+                  { type: 'text-start', id: 'text' },
+                  { type: 'text-delta', id: 'text', delta: 'PRIVATE_OUTPUT' },
+                  { type: 'text-end', id: 'text' },
+                  {
+                    type: 'finish',
+                    finishReason: { unified: 'stop', raw: 'stop' },
+                    usage: {
+                      inputTokens: {
+                        total: 5,
+                        noCache: 5,
+                        cacheRead: 0,
+                        cacheWrite: 0,
                       },
+                      outputTokens: { total: 2, text: 2, reasoning: 0 },
+                    },
+                    providerMetadata: {
+                      test: { secret: 'PRIVATE_METADATA' },
                     },
-                  ],
-                })
-              : new ReadableStream({
-                  start(controller) {
-                    controller.enqueue({ type: 'stream-start', warnings: [] })
-                    controller.enqueue({ type: 'text-start', id: 'text' })
-                    controller.enqueue({
-                      type: 'text-delta',
-                      id: 'text',
-                      delta: 'PRIVATE_PARTIAL',
-                    })
-                    abortSignal?.addEventListener(
-                      'abort',
-                      () => controller.close(),
-                      { once: true },
-                    )
                   },
-                }),
-        }),
+                ],
+              })
+            : new ReadableStream({
+                start(controller) {
+                  controller.enqueue({ type: 'stream-start', warnings: [] })
+                  controller.enqueue({ type: 'text-start', id: 'text' })
+                  controller.enqueue({
+                    type: 'text-delta',
+                    id: 'text',
+                    delta: 'PRIVATE_PARTIAL',
+                  })
+                  abortSignal?.addEventListener(
+                    'abort',
+                    () => controller.close(),
+                    { once: true },
+                  )
+                },
+              }),
       }),
     })
+    // Agents take AI Gateway model IDs; the AI SDK's global provider serves
+    // this one from the mock.
+    vi.stubGlobal('AI_SDK_DEFAULT_PROVIDER', {
+      specificationVersion: 'v4',
+      languageModel: () => model,
+    })
+    onTestFinished(() => {
+      vi.unstubAllGlobals()
+    })
+    const server = agent({
+      contract: demoAgent,
+      store: memory(),
+      telemetry: otel(),
+      harness: {
+        type: 'ai-sdk',
+        generation: { telemetry: modelTelemetry() },
+        messageMetadata: traceMetadata,
+      },
+      model: 'test-model',
+    })
     const session = server.session(`trace-${outcome}`)
     await session.append(
       ...inputs.message({

package/examples/playground/app/canvas/[canvasId]/canvas-client.tsx

@@ -330,7 +330,7 @@ function CanvasClient({
 
   // A ghost is dead once the log has moved past it: show `dragging`
   // only while its `seen` frontier reaches the shape's durable
-  // `movedAt` (/guides/presence#reconciling-the-planes-seen).
+  // `movedAt` (/client/presence#reconciling-the-planes-seen).
   const ghosts = new Map<
     string,
     { x: number; y: number; color: PaletteColor }