experimental-a2 0.18.1 → 0.20.0

package/examples/playground/app/a0/context-menu.tsx

@@ -1,5 +1,5 @@
 'use client'
-import type { KeyboardEvent, ReactNode } from 'react'
+import type { KeyboardEvent, ReactNode, RefObject } from 'react'
 import {
   useEffect,
   useEffectEvent,
@@ -7,27 +7,38 @@ import {
   useRef,
   useState,
 } from 'react'
+import { Check } from 'lucide-react'
 
 export type MenuItem = {
   label: string
   onSelect: () => void
   danger?: boolean
+  /** One of a set of choices; a checked one is the current choice. */
+  checked?: boolean
 }
 
+const ITEMS = '[role="menuitem"], [role="menuitemradio"]'
+
 // Keeps the menu this far inside the window's edges.
 const MARGIN = 8
 
 /**
- * A menu at a point, as a right-click opens one. It takes focus, moves with
- * the arrow keys, and closes on Escape, a press outside, or a pick; Escape
- * and a pick hand focus back through `onClose`.
+ * A menu at a point, as a right-click opens one. The point is the menu's top
+ * left corner, or its bottom right for a button near the window's foot. It
+ * takes focus, moves with the arrow keys, and closes on Escape, a press
+ * outside, or a pick; Escape and a pick hand focus back through `onClose`.
  */
 export function ContextMenu({
   at,
+  corner = 'top-left',
+  trigger,
   items,
   onClose,
 }: {
   at: { x: number; y: number }
+  corner?: 'top-left' | 'bottom-right'
+  /** The button that opens the menu; a press on it is its own, not outside. */
+  trigger?: RefObject<HTMLElement | null>
   items: MenuItem[]
   onClose: (closed: { returnFocus: boolean }) => void
 }): ReactNode {
@@ -39,19 +50,26 @@ export function ContextMenu({
     const element = menu.current
     if (!element) return
     const { width, height } = element.getBoundingClientRect()
+    const x = corner === 'top-left' ? at.x : at.x - width
+    const y = corner === 'top-left' ? at.y : at.y - height
     setPosition({
-      x: Math.max(MARGIN, Math.min(at.x, innerWidth - width - MARGIN)),
-      y: Math.max(MARGIN, Math.min(at.y, innerHeight - height - MARGIN)),
+      x: Math.max(MARGIN, Math.min(x, innerWidth - width - MARGIN)),
+      y: Math.max(MARGIN, Math.min(y, innerHeight - height - MARGIN)),
     })
-    element.querySelector<HTMLElement>('[role="menuitem"]')?.focus()
-  }, [at])
+    element.querySelector<HTMLElement>(ITEMS)?.focus()
+  }, [at, corner])
 
   const dismiss = useEffectEvent((returnFocus: boolean) =>
     onClose({ returnFocus }),
   )
   useEffect(() => {
     const outside = (event: PointerEvent): void => {
-      if (!menu.current?.contains(event.target as Node)) dismiss(false)
+      const target = event.target as Node
+      if (
+        !menu.current?.contains(target) &&
+        !trigger?.current?.contains(target)
+      )
+        dismiss(false)
     }
     const away = (): void => dismiss(false)
     document.addEventListener('pointerdown', outside, true)
@@ -66,7 +84,7 @@ export function ContextMenu({
 
   const move = (event: KeyboardEvent<HTMLDivElement>): void => {
     const buttons = [
-      ...event.currentTarget.querySelectorAll<HTMLElement>('[role="menuitem"]'),
+      ...event.currentTarget.querySelectorAll<HTMLElement>(ITEMS),
     ]
     const focused = buttons.indexOf(document.activeElement as HTMLElement)
     const next =
@@ -101,13 +119,22 @@ export function ContextMenu({
         <button
           key={item.label}
           type="button"
-          role="menuitem"
+          role={item.checked === undefined ? 'menuitem' : 'menuitemradio'}
+          aria-checked={item.checked}
           data-danger={item.danger || undefined}
           onClick={() => {
             onClose({ returnFocus: true })
             item.onSelect()
           }}
         >
+          {item.checked !== undefined && (
+            <Check
+              size={12}
+              className="a0-menu-check"
+              visibility={item.checked ? 'visible' : 'hidden'}
+              aria-hidden
+            />
+          )}
           {item.label}
         </button>
       ))}

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

@@ -71,3 +71,31 @@ it("reads the app's harness from its URL, the AI SDK's by default", () => {
     'a0-pi',
   ])
 })
+
+const sendWithFile = (url: string) =>
+  appAgent.events['ai.control.requested']['~standard'].validate({
+    action: 'send',
+    message: {
+      id: 'u1',
+      role: 'user',
+      parts: [
+        { type: 'file', mediaType: 'image/png', url },
+        { type: 'text', text: 'Like this.' },
+      ],
+    },
+  })
+
+it("only takes a user's files from the playground's Blob store", () => {
+  expect(
+    sendWithFile(
+      'https://store.public.blob.vercel-storage.com/a0/app/shot-x1.png',
+    ),
+  ).not.toHaveProperty('issues')
+  for (const url of [
+    'data:image/png;base64,iVBORw0KGgo=',
+    'http://store.public.blob.vercel-storage.com/shot.png',
+    'http://169.254.169.254/latest/meta-data',
+    'https://example.com/shot.png',
+  ])
+    expect(sendWithFile(url)).toHaveProperty('issues')
+})

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

@@ -35,6 +35,35 @@ export const defaultModelChoice: ModelChoice = {
 
 export type AppMessage = UIMessage
 
+/** A file the user attached, uploaded to the playground's public Blob store. */
+export function isAttachmentUrl(value: string): boolean {
+  try {
+    const { protocol, hostname } = new URL(value)
+    return (
+      protocol === 'https:' &&
+      hostname.endsWith('.public.blob.vercel-storage.com')
+    )
+  } catch {
+    return false
+  }
+}
+
+/**
+ * A user's files must be attachments. Whatever hands them to the model
+ * fetches them by URL, so the URL can't point anywhere else, and a message
+ * never holds a file's bytes.
+ */
+const messageSchema = z
+  .custom<AppMessage>()
+  .refine(
+    (message) =>
+      message.role !== 'user' ||
+      message.parts.every(
+        (part) => part.type !== 'file' || isAttachmentUrl(part.url),
+      ),
+    "A message's files must be uploaded attachments",
+  )
+
 /**
  * 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.
@@ -56,6 +85,7 @@ export const harnessFrom = (value: unknown): Harness =>
 const appContract = (name: string) =>
   agentContract({
     name,
+    messageSchema,
     events: { 'model.chosen': modelChoiceSchema },
     reducer: {
       name: 'a0.model-choice.v1',

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

@@ -5,6 +5,7 @@ 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 { otel } from 'experimental-a2/otel'
 import { createServer } from 'experimental-a2/server'
 import { vercelQueues } from 'experimental-a2/scheduler-vercel'
 import { z } from 'zod'
@@ -33,6 +34,7 @@ const instructions = (
 - If the preview stops answering, read /tmp/next.log, then start next dev with \`${START_DEV}\`; it does nothing while one is already running.
 - next.config allows the preview's *.vercel.run host (allowedDevOrigins); keep that when you edit it.
 - Background anything long-running; a bash call stops after its timeout.
+- The user can attach files. Images come with their message; any other file is a "name: URL" line in it. Download one with curl when you need its contents.
 - Keep replies short and in plain text, without Markdown: what you changed.`
 
 /** A tool's result, with how long it took; the chat shows it. */
@@ -118,10 +120,13 @@ function chosenModel({
   return { model, reasoning, speed: fast ? 'fast' : 'standard' } as const
 }
 
+const telemetry = otel()
+
 const shared = (harness: Harness) => ({
   ...(store ? { store } : {}),
   ...(appSchedulers[harness] ? { scheduler: appSchedulers[harness] } : {}),
   contract: harnessAgents[harness],
+  telemetry,
   maxSteps: 80,
 })
 

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

@@ -106,7 +106,7 @@ export function A0Shell({
   const remove = async (target: App): Promise<void> => {
     if (
       !confirm(
-        `Delete ${target.name}? This deletes its sandbox, with everything the agent built in it.`,
+        `Delete ${target.name}? This deletes its conversation and its sandbox, with everything the agent built in it.`,
       )
     )
       return

package/examples/playground/app/a0/uploads/route.test.ts

@@ -0,0 +1,59 @@
+import { afterEach, beforeEach, expect, it, vi } from 'vitest'
+import { POST } from './route'
+
+const appId = crypto.randomUUID()
+
+beforeEach(() => {
+  vi.stubEnv('BLOB_READ_WRITE_TOKEN', 'vercel_blob_rw_teststore_secret')
+})
+
+afterEach(() => {
+  vi.unstubAllEnvs()
+  vi.restoreAllMocks()
+})
+
+/** What the browser's `upload()` asks its `handleUploadUrl` for first. */
+const tokenRequest = (pathname: string, clientPayload: string | null) =>
+  POST(
+    new Request('http://test/a0/uploads', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({
+        type: 'blob.generate-client-token',
+        payload: { pathname, clientPayload, multipart: false },
+      }),
+    }),
+  )
+
+/** The upload a client token allows, as Blob reads it from the token. */
+const allowed = (clientToken: string): unknown => {
+  const [, encoded] = /^vercel_blob_client_teststore_(.+)$/.exec(clientToken)!
+  const signed = Buffer.from(encoded!, 'base64').toString()
+  const payload = signed.slice(signed.indexOf('.') + 1)
+  return JSON.parse(Buffer.from(payload, 'base64').toString())
+}
+
+it("signs an upload into the app's own folder, without a request of its own", async () => {
+  const fetch = vi.spyOn(globalThis, 'fetch')
+  const response = await tokenRequest(`a0/${appId}/shot.png`, appId)
+  expect(response.status).toBe(200)
+  const body = (await response.json()) as { type: string; clientToken: string }
+  expect(body.type).toBe('blob.generate-client-token')
+  expect(allowed(body.clientToken)).toMatchObject({
+    pathname: `a0/${appId}/shot.png`,
+    addRandomSuffix: true,
+  })
+  expect(fetch).not.toHaveBeenCalled()
+})
+
+it.each([
+  ['another app', `a0/${crypto.randomUUID()}/shot.png`, appId],
+  ['no app', `a0/${appId}/shot.png`, null],
+  ['something other than an app', 'a0/list/shot.png', 'list'],
+])('refuses an upload for %s', async (_, pathname, clientPayload) => {
+  const response = await tokenRequest(pathname, clientPayload)
+  expect(response.status).toBe(400)
+  expect(await response.json()).toEqual({
+    error: "An attachment goes in its app's folder",
+  })
+})

package/examples/playground/app/a0/uploads/route.ts

@@ -0,0 +1,29 @@
+import { handleUpload, type HandleUploadBody } from '@vercel/blob/client'
+import { isAppId } from '../apps'
+
+/** Tokens for the browser to upload an app's attachments straight to Blob. */
+export async function POST(request: Request): Promise<Response> {
+  const body = (await request.json()) as HandleUploadBody
+  try {
+    return Response.json(
+      await handleUpload({
+        request,
+        body,
+        onBeforeGenerateToken: async (pathname, appId) => {
+          if (
+            appId === null ||
+            !isAppId(appId) ||
+            !pathname.startsWith(`a0/${appId}/`)
+          )
+            throw new Error("An attachment goes in its app's folder")
+          return { addRandomSuffix: true }
+        },
+      }),
+    )
+  } catch (cause) {
+    return Response.json(
+      { error: cause instanceof Error ? cause.message : String(cause) },
+      { status: 400 },
+    )
+  }
+}

package/examples/playground/app/agent/[agentId]/agent-client.tsx

@@ -393,10 +393,11 @@ export function AgentClient({
             >
               Stop
             </button>
+            {/* With no turn to steer, steering would only send. */}
             <button
               type="button"
               className="secondary"
-              disabled={!canSend || !prompt.trim()}
+              disabled={!canSend || !prompt.trim() || !state.active}
               onClick={() => void send(undefined, true)}
             >
               Steer

package/examples/playground/app/agent/[agentId]/agent-queue.test.tsx

@@ -1,123 +1,150 @@
 // @vitest-environment jsdom
-import { act, cleanup, fireEvent, render, screen } from '@testing-library/react'
-import { afterEach, expect, it, vi } from 'vitest'
-import type { UIMessage } from 'ai'
-import { AgentQueue } from './agent-queue'
+import {
+  act,
+  cleanup,
+  fireEvent,
+  render,
+  screen,
+  waitFor,
+} from '@testing-library/react'
+import { inputs } from 'experimental-a2/ai'
+import type { A2Operation } from 'experimental-a2/server'
+import { afterEach, beforeEach, expect, it } from 'vitest'
+import { serveAgent, type ServedAgent } from '@/test/agent'
+import { AgentClient } from './agent-client'
 
-afterEach(cleanup)
+let served: ServedAgent
+let server: ServedAgent['server']
+let probe: ServedAgent['probe']
+let id: string
 
-type Edit = (message: UIMessage) => Promise<void>
+beforeEach(async () => {
+  served = await serveAgent()
+  ;({ server, probe } = served)
+  id = crypto.randomUUID()
+  // Paused, so the message waits in the queue rather than starting a turn.
+  await server.session(id).append(
+    ...inputs.pause({ when: 'now' }),
+    ...inputs.message({
+      id: 'queued',
+      role: 'user',
+      parts: [{ type: 'text', text: 'Original' }],
+    }),
+  )
+})
+
+afterEach(async () => {
+  cleanup()
+  await served.close()
+})
 
-const queue = (edit: Edit) =>
+const page = async () =>
   render(
-    <AgentQueue
-      items={[
-        {
-          id: 'queued',
-          message: {
-            id: 'queued',
-            role: 'user',
-            parts: [{ type: 'text', text: 'Original' }],
-          },
-          generate: true,
-        },
-      ]}
-      paused
-      edit={edit}
-      move={vi.fn<() => void>()}
-      remove={vi.fn<() => Promise<void>>().mockResolvedValue(undefined)}
-      sendNow={vi.fn<() => Promise<void>>().mockResolvedValue(undefined)}
-    />,
+    <AgentClient agentId={id} initial={await server.session(id).state()} />,
   )
 
+const isEdit = (operation: A2Operation): boolean =>
+  operation.type === 'push' &&
+  operation.sessionId === id &&
+  operation.events.some(
+    (event) =>
+      event.type === 'ai.control.requested' &&
+      (event.payload as { action?: unknown }).action === 'edit',
+  )
+
+/** The texts each edit pushed to the server carried. */
+const editsReceived = (): string[] =>
+  probe.operations.filter(isEdit).flatMap((operation) =>
+    operation.type === 'push'
+      ? operation.events.map(
+          (event) =>
+            (
+              event.payload as {
+                message: { parts: { text: string }[] }
+              }
+            ).message.parts[0]!.text,
+        )
+      : [],
+  )
+
+const queuedText = async (): Promise<string | undefined> => {
+  const { state } = await server.session(id).state()
+  const part = state.inbox.items[0]?.message.parts[0]
+  return part?.type === 'text' ? part.text : undefined
+}
+
+/** The queued message's text, as the queue shows it. */
+const shownText = (): string | null | undefined =>
+  document.querySelector('.agent-queue-text')?.textContent
+
+const editor = () =>
+  screen.queryByLabelText(
+    'Edit text for queued message 1',
+  ) as HTMLTextAreaElement | null
+const button = (name: string) =>
+  screen.getByRole('button', { name }) as HTMLButtonElement
+
 const open = (): void => {
-  fireEvent.click(screen.getByRole('button', { name: 'Edit queued message 1' }))
+  fireEvent.click(button('Edit queued message 1'))
 }
 const save = (text: string): void => {
-  fireEvent.change(screen.getByRole('textbox'), { target: { value: text } })
-  fireEvent.click(screen.getByRole('button', { name: 'Save' }))
+  fireEvent.change(editor()!, { target: { value: text } })
+  fireEvent.click(button('Save'))
 }
 
 it('closes immediately and permits another edit while saves remain in flight', async () => {
-  const first = Promise.withResolvers<void>()
-  const second = Promise.withResolvers<void>()
-  const edit = vi
-    .fn<Edit>()
-    .mockImplementationOnce(() => first.promise)
-    .mockImplementationOnce(() => second.promise)
-  queue(edit)
+  await page()
+  const first = probe.hold(isEdit)
   open()
   save('First')
-  expect(screen.queryByRole('textbox')).toBeNull()
-  expect(
-    (
-      screen.getByRole('button', {
-        name: 'Edit queued message 1',
-      }) as HTMLButtonElement
-    ).disabled,
-  ).toBe(false)
-  expect(
-    (
-      screen.getByRole('button', {
-        name: 'Send queued message 1 after current step',
-      }) as HTMLButtonElement
-    ).disabled,
-  ).toBe(false)
+  expect(editor()).toBeNull()
+  expect(button('Edit queued message 1').disabled).toBe(false)
+  expect(button('Send queued message 1 after current step').disabled).toBe(
+    false,
+  )
+  await first.arrived
   open()
   save('Second')
-  expect(edit.mock.calls.map(([message]) => message.parts)).toEqual([
-    [{ type: 'text', text: 'First' }],
-    [{ type: 'text', text: 'Second' }],
-  ])
-  await act(async () => {
-    first.reject(new Error('Earlier save failed'))
-    await first.promise.catch(() => {})
-  })
-  expect(screen.queryByRole('textbox')).toBeNull()
+  first.deny()
+  await waitFor(async () => expect(await queuedText()).toBe('Second'))
+  expect(editsReceived()).toEqual(['First', 'Second'])
+  expect(editor()).toBeNull()
   expect(screen.queryByRole('alert')).toBeNull()
-  await act(async () => {
-    second.resolve()
-    await second.promise
-  })
+  expect(shownText()).toBe('Second')
 })
 
-it('restores the latest submitted draft on transport failure', async () => {
-  const pending = Promise.withResolvers<void>()
-  queue(() => pending.promise)
+it('restores the latest submitted draft when its save fails', async () => {
+  await page()
+  const pending = probe.hold(isEdit)
   open()
   save('Keep this draft')
-  expect(screen.queryByRole('textbox')).toBeNull()
-  await act(async () => {
-    pending.reject(new Error('Save failed'))
-    await pending.promise.catch(() => {})
-  })
-  expect((screen.getByRole('textbox') as HTMLTextAreaElement).value).toBe(
-    'Keep this draft',
+  expect(editor()).toBeNull()
+  await pending.arrived
+  pending.deny()
+  await waitFor(() => expect(editor()?.value).toBe('Keep this draft'))
+  expect(screen.getByRole('alert').textContent).toBe(
+    'the operation is not authorized',
   )
-  expect(screen.getByRole('alert').textContent).toBe('Save failed')
+  expect(await queuedText()).toBe('Original')
 })
 
 it.each(['open', 'cancel'] as const)(
   'does not restore an old failed save after a newer draft is %s',
   async (action) => {
-    const pending = Promise.withResolvers<void>()
-    queue(() => pending.promise)
+    await page()
+    const pending = probe.hold(isEdit)
     open()
     save('Old draft')
+    await pending.arrived
     open()
-    fireEvent.change(screen.getByRole('textbox'), {
-      target: { value: 'New draft' },
-    })
-    if (action === 'cancel')
-      fireEvent.click(screen.getByRole('button', { name: 'Cancel' }))
-    await act(async () => {
-      pending.reject(new Error('Old save failed'))
-      await pending.promise.catch(() => {})
-    })
-    expect(
-      (screen.queryByRole('textbox') as HTMLTextAreaElement | null)?.value ??
-        null,
-    ).toBe(action === 'open' ? 'New draft' : null)
+    fireEvent.change(editor()!, { target: { value: 'New draft' } })
+    if (action === 'cancel') fireEvent.click(button('Cancel'))
+    pending.deny()
+    // The failed save leaves the queue; then its handler has had its turn.
+    await waitFor(() => expect(shownText()).toBe('Original'))
+    await act(() => new Promise((resolve) => setTimeout(resolve, 10)))
+    expect(editor()?.value ?? null).toBe(action === 'open' ? 'New draft' : null)
     expect(screen.queryByRole('alert')).toBeNull()
+    expect(await queuedText()).toBe('Original')
   },
 )