experimental-a2 0.17.0 → 0.18.0

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,108 @@ 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.
+  if (crashesAllowed) {
+    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 } : {}),

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 }

package/examples/playground/app/chat/server.test.ts

@@ -26,32 +26,36 @@ vi.mock('experimental-a2/ai/server', async (importActual) => {
     agent: (options: Parameters<typeof actual.agent>[0]) =>
       actual.agent({
         ...options,
-        generate: ({
-          event,
-          messages,
-        }: {
-          event: { payload: { reason: string } }
-          messages: { role: string; id: string }[]
-        }) => {
-          prompts.push(
-            messages.map((message) => `${message.role}:${message.id}`).join(),
-          )
-          return step(
-            event.payload.reason === 'message'
-              ? [
-                  { type: 'start' },
-                  ...['Hello', 'there'].map(
-                    (message, call): UIMessageChunk => ({
-                      type: 'tool-input-available',
-                      toolCallId: `call-${call}`,
-                      toolName: 'post',
-                      input: { message },
-                    }),
-                  ),
-                  { type: 'finish', finishReason: 'tool-calls' },
-                ]
-              : [{ type: 'start' }, { type: 'finish', finishReason: 'stop' }],
-          )
+        harness: {
+          ...(options.harness?.type === 'ai-sdk' ? options.harness : {}),
+          type: 'ai-sdk',
+          generate: ({
+            event,
+            messages,
+          }: {
+            event: { payload: { reason: string } }
+            messages: { role: string; id: string }[]
+          }) => {
+            prompts.push(
+              messages.map((message) => `${message.role}:${message.id}`).join(),
+            )
+            return step(
+              event.payload.reason === 'message'
+                ? [
+                    { type: 'start' },
+                    ...['Hello', 'there'].map(
+                      (message, call): UIMessageChunk => ({
+                        type: 'tool-input-available',
+                        toolCallId: `call-${call}`,
+                        toolName: 'post',
+                        input: { message },
+                      }),
+                    ),
+                    { type: 'finish', finishReason: 'tool-calls' },
+                  ]
+                : [{ type: 'start' }, { type: 'finish', finishReason: 'stop' }],
+            )
+          },
         },
       } as never),
   }

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

@@ -61,57 +61,57 @@ Sound like a sharp, relaxed person in the chat, not a customer-support bot. Matc
 Only contribute when you have something useful, relevant, or friendly to add. It is fine to stay silent or stop whenever you have nothing else to say.
 To speak, call post once for each visible chat bubble. Never communicate through ordinary assistant text because it is private and is not shown in the room.
 Use as many post calls as the moment naturally calls for. Several short messages are welcome when they create better rhythm, separate distinct thoughts, or fulfill a request for a sequence. A single message is fine too. Do not spam. After post results, continue only when another message genuinely improves the conversation.`,
-  generation: {
-    maxOutputTokens: 500,
-    temperature: 0.4,
+  harness: {
+    type: 'ai-sdk',
+    generation: {
+      maxOutputTokens: 500,
+      temperature: 0.4,
+    },
+    messageMetadata: (context) => {
+      const previous = context.messages.find(
+        (message) => message.id === context.event.payload.responseMessageId,
+      )?.metadata
+      const trigger = context.messages.find(
+        (message) => message.id === context.event.payload.messageId,
+      )?.metadata
+      const steps = previous?.kind === 'agent' ? previous.steps : []
+      const mode: ChatAgentMode | undefined =
+        previous?.kind === 'agent'
+          ? previous.mode
+          : trigger?.kind === 'participant' && trigger.mode !== 'passive'
+            ? trigger.mode
+            : undefined
+      if (mode === undefined) return undefined
+      const metadata = {
+        kind: 'agent' as const,
+        author: 'agent' as const,
+        mode,
+        steps,
+      }
+      if (context.part.type === 'start') return metadata
+      if (context.part.type !== 'finish') return undefined
+      return {
+        ...metadata,
+        steps: [
+          ...steps,
+          {
+            generationId: context.generationId,
+            model: context.model,
+            finishReason: context.part.finishReason,
+            ...(context.part.rawFinishReason === undefined
+              ? {}
+              : { rawFinishReason: context.part.rawFinishReason }),
+            usage: context.part.totalUsage,
+            completedAt: new Date().toISOString(),
+          },
+        ],
+      }
+    },
   },
   progress: {
     maxChunks: 4,
     maxDelayMs: 30,
   },
-  messageMetadata: (context) => {
-    const previous = context.messages.find(
-      (message) => message.id === context.event.payload.responseMessageId,
-    )?.metadata
-    const trigger = context.messages.find(
-      (message) => message.id === context.event.payload.messageId,
-    )?.metadata
-    const steps = previous?.kind === 'agent' ? previous.steps : []
-    const mode: ChatAgentMode | undefined =
-      previous?.kind === 'agent'
-        ? previous.mode
-        : trigger?.kind === 'participant' && trigger.mode !== 'passive'
-          ? trigger.mode
-          : undefined
-    if (mode === undefined) return undefined
-    const metadata = {
-      kind: 'agent' as const,
-      author: 'agent' as const,
-      mode,
-      steps,
-    }
-    if (context.part.type === 'start') return metadata
-    if (context.part.type !== 'finish') return undefined
-    return {
-      ...metadata,
-      steps: [
-        ...steps,
-        {
-          generationId: context.generationId,
-          model:
-            typeof context.model === 'string'
-              ? context.model
-              : context.model.modelId,
-          finishReason: context.part.finishReason,
-          ...(context.part.rawFinishReason === undefined
-            ? {}
-            : { rawFinishReason: context.part.rawFinishReason }),
-          usage: context.part.totalUsage,
-          completedAt: new Date().toISOString(),
-        },
-      ],
-    }
-  },
 })
 
 /** The room. Each message goes on to the agent's session, marked for whether it should answer. */