experimental-a2 0.16.0 → 0.17.0

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

@@ -0,0 +1,211 @@
+'use client'
+import type { ReactNode } from 'react'
+import { useEffect, useRef, useState } from 'react'
+import { useSearchParams } from 'next/navigation'
+import { Asterisk, Plus } from 'lucide-react'
+import { FastLink } from '../components/fast-link'
+import { type App, timeAgo } from './apps'
+import { ContextMenu, type MenuItem } from './context-menu'
+import { queryString } from './flags'
+
+/** The clock the list's times read from: the server's at first, then ticking. */
+function useNow(renderedAt: number): number {
+  const [now, setNow] = useState(renderedAt)
+  useEffect(() => {
+    const timer = setInterval(() => setNow(Date.now()), 30_000)
+    return () => clearInterval(timer)
+  }, [])
+  return now
+}
+
+export function AppList({
+  apps,
+  currentId,
+  renderedAt,
+  newAppId,
+  onRename,
+  onDelete,
+}: {
+  /** Most recently prompted first. */
+  apps: App[]
+  currentId: string | null
+  renderedAt: number
+  newAppId: string
+  onRename: (app: { id: string; name: string }) => void
+  onDelete: (app: App) => void
+}): ReactNode {
+  const now = useNow(renderedAt)
+  // Links keep the dev tools' state from app to app.
+  const params = useSearchParams()
+  const query = queryString(new URLSearchParams(params))
+  // 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
+  return (
+    <>
+      <div className="a0-label">
+        <span>Apps</span>
+        <span className="a0-rule" />
+        <FastLink
+          href={`/a0/${newAppId}${query}`}
+          prefetch={prefetch}
+          className="a0-icon-button"
+          aria-label="New app"
+          title="New app"
+        >
+          <Plus size={14} />
+        </FastLink>
+      </div>
+      <nav aria-label="Apps">
+        {apps.map((app) => (
+          <AppItem
+            key={app.id}
+            app={app}
+            when={timeAgo({ at: app.promptedAt, now })}
+            current={app.id === currentId}
+            href={`/a0/${app.id}${query}`}
+            prefetch={prefetch}
+            onRename={(name) => onRename({ id: app.id, name })}
+            onDelete={() => onDelete(app)}
+          />
+        ))}
+      </nav>
+    </>
+  )
+}
+
+const under = (row: HTMLElement): { x: number; y: number } => {
+  const box = row.getBoundingClientRect()
+  return { x: box.left + 16, y: box.bottom }
+}
+
+/**
+ * Clicking the current app renames it in place. Right-clicking any app, or
+ * its context-menu key, opens its menu.
+ */
+function AppItem({
+  app,
+  when,
+  current,
+  href,
+  prefetch,
+  onRename,
+  onDelete,
+}: {
+  app: App
+  when: string
+  current: boolean
+  href: string
+  prefetch: boolean | null
+  onRename: (name: string) => void
+  onDelete: () => void
+}): ReactNode {
+  const [editing, setEditing] = useState(false)
+  const [menu, setMenu] = useState<{ x: number; y: number } | null>(null)
+  const row = useRef<HTMLDivElement>(null)
+  const cancelled = useRef(false)
+  const rename = (): void => {
+    cancelled.current = false
+    setEditing(true)
+  }
+  const link = (): string => new URL(href, location.origin).href
+  const items: MenuItem[] = [
+    { label: 'Open in new tab', onSelect: () => window.open(link(), '_blank') },
+    {
+      label: 'Copy link',
+      onSelect: () => void navigator.clipboard.writeText(link()),
+    },
+    { label: 'Rename', onSelect: rename },
+    { label: 'Delete', onSelect: onDelete, danger: true },
+  ]
+  const icon = <Asterisk size={14} aria-hidden />
+  const lines = (
+    <span className="a0-app-lines">
+      <span className="a0-app-name">{app.name}</span>
+      <span className="a0-app-when">{when}</span>
+    </span>
+  )
+
+  if (editing)
+    return (
+      <div className="a0-app" data-current>
+        {icon}
+        <input
+          aria-label={`Rename ${app.name}`}
+          defaultValue={app.name}
+          maxLength={80}
+          autoFocus
+          onFocus={(event) => event.currentTarget.select()}
+          onBlur={(event) => {
+            setEditing(false)
+            const next = event.currentTarget.value.trim()
+            if (!cancelled.current && next && next !== app.name) onRename(next)
+          }}
+          onKeyDown={(event) => {
+            if (event.key === 'Enter') event.currentTarget.blur()
+            if (event.key === 'Escape') {
+              cancelled.current = true
+              event.currentTarget.blur()
+            }
+          }}
+        />
+      </div>
+    )
+
+  return (
+    <div
+      ref={row}
+      className="a0-app"
+      data-current={current || undefined}
+      data-menu={menu ? '' : undefined}
+      onContextMenu={(event) => {
+        event.preventDefault()
+        // The keyboard's menu key has no pointer, so it opens under the row.
+        setMenu(
+          event.clientX || event.clientY
+            ? { x: event.clientX, y: event.clientY }
+            : under(event.currentTarget),
+        )
+      }}
+      // Not every browser turns these keys into a contextmenu event.
+      onKeyDown={(event) => {
+        if (
+          event.key !== 'ContextMenu' &&
+          !(event.key === 'F10' && event.shiftKey)
+        )
+          return
+        event.preventDefault()
+        setMenu(under(event.currentTarget))
+      }}
+    >
+      {current ? (
+        <button
+          type="button"
+          className="a0-app-open"
+          aria-current="page"
+          title="Rename"
+          onClick={rename}
+        >
+          {icon}
+          {lines}
+        </button>
+      ) : (
+        <FastLink className="a0-app-open" href={href} prefetch={prefetch}>
+          {icon}
+          {lines}
+        </FastLink>
+      )}
+      {menu && (
+        <ContextMenu
+          at={menu}
+          items={items}
+          onClose={({ returnFocus }) => {
+            setMenu(null)
+            if (returnFocus)
+              row.current?.querySelector<HTMLElement>('.a0-app-open')?.focus()
+          }}
+        />
+      )}
+    </div>
+  )
+}

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

@@ -0,0 +1,55 @@
+'use client'
+import type { ReactNode } from 'react'
+import { useEffect } from 'react'
+import { useSearchParams } from 'next/navigation'
+import { titleFromPrompt } from './apps'
+import { Chat } from './chat'
+import { ColumnEdge } from './columns'
+import { checkApp, PreviewPane } from './preview-pane'
+import { useSession } from './session'
+import { useApps } from './shell'
+
+/** One app: its chat with the agent, and the app it builds. */
+export function AppView({
+  appId,
+  devtools,
+}: {
+  appId: string
+  /** Shown while the query has `devtools`. */
+  devtools: ReactNode
+}): ReactNode {
+  const { listed, prompted, opened } = useApps()
+  const { state } = useSession()
+  const showDevtools = useSearchParams().has('devtools')
+  const app = listed(appId)
+  const prompt = state.messages
+    .find((message) => message.role === 'user')
+    ?.parts.flatMap((part) => (part.type === 'text' ? [part.text] : []))
+    .join(' ')
+  const name = app?.name ?? (prompt ? titleFromPrompt(prompt) : 'New app')
+  // A new app's sandbox opens on sight, so it's ready by the first prompt;
+  // if none comes, its idle check deletes it.
+  const newApp = state.messages.length === 0
+  useEffect(() => {
+    if (!newApp) return
+    opened(appId)
+    checkApp({ appId, newApp }).catch(() => {})
+  }, [appId])
+
+  return (
+    <>
+      <section aria-label="Chat" className="a0-chat">
+        <h1 className="a0-title">{name}</h1>
+        <Chat
+          onPrompt={(text) =>
+            prompted({ id: appId, name: titleFromPrompt(prompt ?? text) })
+          }
+          autoFocus={!app}
+        />
+        <ColumnEdge column="chat" />
+      </section>
+      <PreviewPane appId={appId} />
+      {showDevtools && devtools}
+    </>
+  )
+}

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

@@ -0,0 +1,27 @@
+import { z } from 'zod'
+import { isAppId } from '../../../apps'
+import { ensureApp } from '../../../sandbox'
+import { checkWhenIdle } from '../../../sandbox-log'
+
+const body = z.object({ newApp: z.boolean().default(false) })
+
+/**
+ * Makes sure the app is up, and says whether it answers. The browser calls
+ * it while the app is on screen, which keeps its sandbox running. A new
+ * app's sandbox also gets its idle check; the check itself decides, so a
+ * wrong `newApp` costs nothing.
+ */
+export async function POST(
+  request: Request,
+  context: { params: Promise<{ appId: string }> },
+): Promise<Response> {
+  const { appId } = await context.params
+  if (!isAppId(appId))
+    return Response.json({ error: 'Unknown app.' }, { status: 404 })
+  const { newApp } = body
+    .catch({ newApp: false })
+    .parse(await request.json().catch(() => ({})))
+  const { up, createdAt } = await ensureApp({ appId })
+  if (newApp) await checkWhenIdle({ appId, createdAt })
+  return Response.json({ up }, { headers: { 'cache-control': 'no-store' } })
+}

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

@@ -0,0 +1,23 @@
+import { inputs } from 'experimental-a2/ai'
+import { isAppId } from '../../apps'
+import { deleteAppSandbox } from '../../sandbox'
+import { agentServer } from '../../server'
+
+/**
+ * Stops the agent's current turn, so no later tool call brings the sandbox
+ * back, then deletes it. The conversation stays in the A2 log.
+ */
+export async function DELETE(
+  _request: Request,
+  context: { params: Promise<{ appId: string }> },
+): Promise<Response> {
+  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 }))
+  await deleteAppSandbox({ appId })
+  return Response.json({ ok: true })
+}

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

@@ -0,0 +1,116 @@
+import type { ContractEvent } from 'experimental-a2'
+import { expect, it } from 'vitest'
+import {
+  type App,
+  appList,
+  byLatestPrompt,
+  isAppId,
+  timeAgo,
+  titleFromPrompt,
+} from './apps'
+import { parseWidths, serializeWidths } from './cookies'
+
+type ListEvents = typeof appList.events
+
+const first = '6f1c1c3e-2f7a-4f0e-9d4e-5b8a9f1d2c3b'
+const second = '0d9a8b7c-6e5f-4a3b-8c2d-1e0f9a8b7c6d'
+
+const fold = (
+  ...events: [type: keyof ListEvents & string, payload: object, at: number][]
+): App[] =>
+  events.reduce(
+    (apps, [type, payload, at], index) =>
+      appList.reducer.fold(apps, {
+        id: `event-${index}`,
+        type,
+        payload,
+        index: index + 1,
+        sessionId: 'list-1',
+        createdAt: new Date(at),
+      } as ContractEvent<ListEvents>),
+    appList.reducer.initialState,
+  )
+
+it('lists apps with the server time of their latest prompt', () => {
+  expect(
+    fold(
+      ['app.created', { appId: first, name: 'todo app' }, 1_000],
+      ['app.created', { appId: second, name: 'counter' }, 2_000],
+      ['app.prompted', { appId: first }, 3_000],
+    ),
+  ).toEqual([
+    { id: first, name: 'todo app', promptedAt: 3_000 },
+    { id: second, name: 'counter', promptedAt: 2_000 },
+  ])
+})
+
+it('renames and deletes apps, and lists each one once', () => {
+  expect(
+    fold(
+      ['app.created', { appId: first, name: 'todo app' }, 1_000],
+      ['app.created', { appId: first, name: 'again' }, 2_000],
+      ['app.renamed', { appId: first, name: 'Tasks' }, 3_000],
+      ['app.created', { appId: second, name: 'counter' }, 4_000],
+      ['app.deleted', { appId: second }, 5_000],
+    ),
+  ).toEqual([{ id: first, name: 'Tasks', promptedAt: 1_000 }])
+})
+
+it('sorts by the latest prompt first', () => {
+  const apps = [
+    { id: first, name: 'older', promptedAt: 1_000 },
+    { id: second, name: 'newer', promptedAt: 2_000 },
+  ]
+  expect(byLatestPrompt(apps).map((app) => app.name)).toEqual([
+    'newer',
+    'older',
+  ])
+})
+
+it('rejects names and ids the list would not show', () => {
+  const created = appList.events['app.created']
+  const valid = (payload: object): boolean =>
+    !('issues' in created['~standard'].validate(payload))
+  expect(valid({ appId: first, name: 'todo app' })).toBe(true)
+  expect(valid({ appId: first, name: '   ' })).toBe(false)
+  expect(valid({ appId: first, name: 'x'.repeat(81) })).toBe(false)
+  expect(valid({ appId: 'not-a-uuid', name: 'todo app' })).toBe(false)
+  expect(isAppId(first)).toBe(true)
+  expect(isAppId('not-a-uuid')).toBe(false)
+})
+
+it('names an app after the first line of its prompt, cut to fit', () => {
+  expect(titleFromPrompt('  make a   todo app\nwith tags ')).toBe(
+    'make a todo app',
+  )
+  const long = titleFromPrompt(
+    'build a landing page for a coffee shop called Ember with a menu',
+  )
+  expect(long).toBe('build a landing page for a coffee shop…')
+  expect(long.length).toBeLessThanOrEqual(40)
+})
+
+it('says how long ago in words', () => {
+  const now = Date.UTC(2026, 8, 26, 12)
+  const ago = (ms: number): string => timeAgo({ at: now - ms, now })
+  expect(ago(-5_000)).toBe('just now')
+  expect(ago(30_000)).toBe('just now')
+  expect(ago(60_000)).toBe('1 minute ago')
+  expect(ago(5 * 60_000)).toBe('5 minutes ago')
+  expect(ago(3 * 60 * 60_000)).toBe('3 hours ago')
+  expect(ago(30 * 60 * 60_000)).toBe('yesterday')
+  expect(ago(10 * 24 * 60 * 60_000)).toBe('last week')
+  expect(ago(400 * 24 * 60 * 60_000)).toBe('last year')
+})
+
+it('reads the widths someone dragged to, and ignores bad ones', () => {
+  expect(parseWidths(undefined)).toEqual({ apps: 216, chat: null })
+  expect(parseWidths('240,520')).toEqual({ apps: 240, chat: 520 })
+  expect(parseWidths('240')).toEqual({ apps: 240, chat: null })
+  expect(parseWidths('9999,10')).toEqual({ apps: 216, chat: null })
+  expect(parseWidths('abc,def')).toEqual({ apps: 216, chat: null })
+  expect(parseWidths(serializeWidths({ apps: 200, chat: 480 }))).toEqual({
+    apps: 200,
+    chat: 480,
+  })
+})

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

@@ -0,0 +1,87 @@
+import { contract } from 'experimental-a2'
+import { z } from 'zod'
+
+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.
+ */
+export type App = { id: string; name: string; promptedAt: number }
+
+const appId = z.uuid()
+const name = z.string().trim().min(1).max(80)
+
+/**
+ * One browser's apps. Each app is a session of its own; this one lists the
+ * apps this browser has prompted, since knowing an app's id is what lets you
+ * open it.
+ */
+export const appList = contract({
+  name: 'a0-apps',
+  events: {
+    'app.created': z.object({ appId, name }),
+    'app.prompted': z.object({ appId }),
+    'app.renamed': z.object({ appId, name }),
+    'app.deleted': z.object({ appId }),
+  },
+  reducer: {
+    name: 'a0-apps.v1',
+    initialState: [] as App[],
+    fold: (apps, event): App[] => {
+      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.prompted':
+          return apps.map((app) =>
+            app.id === id ? { ...app, promptedAt } : app,
+          )
+        case 'app.renamed': {
+          const { name: renamed } = event.payload
+          return apps.map((app) =>
+            app.id === id ? { ...app, name: renamed } : app,
+          )
+        }
+        case 'app.deleted':
+          return apps.filter((app) => app.id !== id)
+      }
+    },
+  },
+})
+
+export const byLatestPrompt = (apps: readonly App[]): App[] =>
+  apps.toSorted((a, b) => b.promptedAt - a.promptedAt)
+
+const maxTitle = 40
+
+/** An app's name from its prompt: the first line, cut to fit. */
+export function titleFromPrompt(prompt: string): string {
+  const line = (prompt.trim().split('\n')[0] ?? '').replace(/\s+/g, ' ')
+  return line.length > maxTitle
+    ? `${line.slice(0, maxTitle - 1).trimEnd()}…`
+    : line
+}
+
+const relative = new Intl.RelativeTimeFormat('en', { numeric: 'auto' })
+const units = [
+  ['year', 365 * 24 * 60 * 60_000],
+  ['month', 30 * 24 * 60 * 60_000],
+  ['week', 7 * 24 * 60 * 60_000],
+  ['day', 24 * 60 * 60_000],
+  ['hour', 60 * 60_000],
+  ['minute', 60_000],
+] as const
+
+/** How long ago, in words: "just now", "5 minutes ago", "yesterday". */
+export function timeAgo({ at, now }: { at: number; now: number }): string {
+  const elapsed = now - at
+  for (const [unit, size] of units)
+    if (elapsed >= size)
+      return relative.format(-Math.floor(elapsed / size), unit)
+  return 'just now'
+}