experimental-a2 0.16.0 → 0.17.0

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

@@ -0,0 +1,364 @@
+'use client'
+import type { ReactNode } from 'react'
+import { useEffect, useRef, useState } from 'react'
+import { Asterisk, LoaderCircle, Zap } from 'lucide-react'
+import { inputs } from 'experimental-a2/ai'
+import {
+  type AppMessage,
+  type ModelChoice,
+  reasoningSchema,
+  toolLabels,
+  writingLabels,
+} from './model'
+import { useSession } from './session'
+
+type Part = AppMessage['parts'][number]
+
+const suggestions = [
+  'A pomodoro timer with start, pause and reset',
+  'A landing page for a coffee shop called Ember',
+  'A tip calculator that splits the bill',
+]
+
+/** The coding agent's conversation: its words, and one line per tool step. */
+export function Chat({
+  onPrompt,
+  autoFocus,
+}: {
+  onPrompt: (prompt: string) => void
+  autoFocus: boolean
+}): ReactNode {
+  const { state, push } = useSession()
+  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
+  // shows the app's choice, which every client sees.
+  const [chosen, setChosen] = useState<ModelChoice | null>(null)
+  const settings = chosen ?? state.modelChoice
+
+  const last = state.messages.at(-1)
+  // A send is optimistic, and so is the turn it starts, so this holds from
+  // the moment it's pushed rather than once the server accepts it.
+  const working =
+    state.starting || state.status === 'generating' || state.active !== null
+  const waiting =
+    working &&
+    (last?.role !== 'assistant' || !last.parts.some((part) => isVisible(part)))
+
+  const send = async (text: string): Promise<void> => {
+    setError(null)
+    onPrompt(text)
+    try {
+      await push(
+        ...(chosen === null
+          ? []
+          : [
+              {
+                type: 'model.chosen' as const,
+                payload: { ...chosen, model: chosen.model.trim() },
+              },
+            ]),
+        ...inputs.message({
+          id: crypto.randomUUID(),
+          role: 'user',
+          parts: [{ type: 'text', text }],
+        }),
+      )
+      setChosen(null)
+    } catch (cause) {
+      setError(cause instanceof Error ? cause.message : String(cause))
+      throw cause
+    }
+  }
+  const stop = (): void => {
+    if (!state.active) return
+    push(...inputs.stop({ turnId: state.active.turnId })).catch((cause) =>
+      setError(cause instanceof Error ? cause.message : String(cause)),
+    )
+  }
+
+  return (
+    <>
+      {/* Reversed, so it opens at the newest message and stays there. */}
+      <div className="a0-transcript-scroll">
+        <ol className="a0-transcript" aria-label="Conversation">
+          {!state.messages.length && (
+            <li className="a0-suggestions">
+              {suggestions.map((suggestion) => (
+                <button
+                  key={suggestion}
+                  type="button"
+                  className="a0-suggestion"
+                  disabled={!settings.model.trim()}
+                  onClick={() => void send(suggestion).catch(() => {})}
+                >
+                  <Asterisk size={12} aria-hidden />
+                  {suggestion}
+                </button>
+              ))}
+            </li>
+          )}
+          {state.messages.flatMap((message) =>
+            message.parts.map((part, index) => (
+              <MessagePart
+                key={`${message.id}:${index}`}
+                message={message}
+                part={part}
+              />
+            )),
+          )}
+          {waiting && (
+            <li className="a0-step">
+              <LoaderCircle size={12} className="a0-spin" aria-hidden />
+              Thinking
+            </li>
+          )}
+          {state.error && (
+            <li role="alert" className="a0-error">
+              {state.error}
+            </li>
+          )}
+        </ol>
+      </div>
+      {error && (
+        <p role="alert" className="a0-error a0-send-error">
+          {error}
+        </p>
+      )}
+      <Composer
+        onSend={send}
+        working={working}
+        // A turn can be stopped once it's accepted and has an id.
+        onStop={state.active ? stop : null}
+        queued={state.inbox.items.length}
+        settings={settings}
+        onSettings={setChosen}
+        autoFocus={autoFocus}
+      />
+    </>
+  )
+}
+
+const isVisible = (part: Part): boolean =>
+  ((part.type === 'text' || part.type === 'reasoning') && !!part.text.trim()) ||
+  part.type.startsWith('tool-')
+
+function MessagePart({
+  message,
+  part,
+}: {
+  message: AppMessage
+  part: Part
+}): ReactNode {
+  if (part.type === 'text' && part.text.trim())
+    return (
+      <li className="a0-text" data-role={message.role}>
+        {part.text}
+      </li>
+    )
+  if (part.type === 'reasoning' && part.text.trim()) {
+    const thinking = part.state === 'streaming'
+    return (
+      <li className="a0-reasoning">
+        {/* Open while the model thinks, folded once it's done. */}
+        <details open={thinking}>
+          <summary>
+            {thinking ? (
+              <LoaderCircle size={12} className="a0-spin" aria-hidden />
+            ) : (
+              <Asterisk size={12} aria-hidden />
+            )}
+            {thinking ? 'Thinking' : 'Thought'}
+          </summary>
+          <p>{part.text}</p>
+        </details>
+      </li>
+    )
+  }
+  if (!part.type.startsWith('tool-') || !('state' in part)) return null
+  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
+  const took = (part as { output?: { durationMs?: unknown } }).output
+    ?.durationMs
+  const label =
+    (part.state === 'input-streaming' && writingLabels[name]) ||
+    toolLabels[name] ||
+    name
+  return (
+    <li className="a0-step" data-tool={name} data-failed={failed || undefined}>
+      {done || failed ? (
+        <Asterisk size={12} className="a0-step-done" aria-hidden />
+      ) : (
+        <LoaderCircle size={12} className="a0-spin" aria-hidden />
+      )}
+      <span className="a0-step-label">{label}</span>
+      {typeof detail === 'string' && <code>{detail}</code>}
+      {done && typeof took === 'number' && (
+        <span className="a0-step-took">{duration(took)}</span>
+      )}
+    </li>
+  )
+}
+
+const duration = (ms: number): string =>
+  ms < 1000 ? `${ms}ms` : `${(ms / 1000).toFixed(1)}s`
+
+const reasoningLabel = (level: ModelChoice['reasoning']): string =>
+  level === 'provider-default'
+    ? 'default'
+    : level === 'xhigh'
+      ? 'extra high'
+      : level
+
+/** The message box: a dotted frame, then the model settings it sends with. */
+function Composer({
+  onSend,
+  working,
+  onStop,
+  queued,
+  settings,
+  onSettings,
+  autoFocus,
+}: {
+  onSend: (text: string) => Promise<void>
+  working: boolean
+  onStop: (() => void) | null
+  queued: number
+  settings: ModelChoice
+  onSettings: (settings: ModelChoice) => void
+  autoFocus: boolean
+}): ReactNode {
+  const [text, setText] = useState('')
+  const input = useRef<HTMLTextAreaElement>(null)
+  // Typing anywhere else starts a message. Focus moves on keydown, so the
+  // key itself lands in the box.
+  useEffect(() => {
+    const type = (event: KeyboardEvent): void => {
+      const { target } = event
+      if (
+        event.defaultPrevented ||
+        event.isComposing ||
+        event.metaKey ||
+        event.ctrlKey ||
+        event.altKey ||
+        event.key.length !== 1 ||
+        (event.key === ' ' && target !== document.body) ||
+        (target instanceof HTMLElement &&
+          (target.isContentEditable ||
+            target.closest('input, textarea, select')))
+      )
+        return
+      input.current?.focus()
+    }
+    document.addEventListener('keydown', type)
+    return () => document.removeEventListener('keydown', type)
+  }, [])
+  // Grows with its text, up to a point, then scrolls.
+  useEffect(() => {
+    const textarea = input.current
+    if (!textarea) return
+    textarea.style.height = 'auto'
+    textarea.style.height = `${Math.min(textarea.scrollHeight, 208)}px`
+  }, [text])
+  const ready = !!text.trim() && !!settings.model.trim()
+  return (
+    <form
+      className="a0-composer"
+      onSubmit={async (event) => {
+        event.preventDefault()
+        const message = text.trim()
+        if (!ready) return
+        setText('')
+        await onSend(message).catch(() =>
+          setText((current) => current || message),
+        )
+      }}
+    >
+      <textarea
+        ref={input}
+        aria-label="Message"
+        value={text}
+        rows={2}
+        autoFocus={autoFocus}
+        onChange={(event) => setText(event.target.value)}
+        onKeyDown={(event) => {
+          if (
+            event.key === 'Enter' &&
+            !event.shiftKey &&
+            !event.nativeEvent.isComposing
+          ) {
+            event.preventDefault()
+            event.currentTarget.form?.requestSubmit()
+          }
+        }}
+        placeholder="Ask the agent to build something"
+      />
+      <div className="a0-composer-bar">
+        <div className="a0-composer-model">
+          <input
+            aria-label="Model"
+            title="The Gateway model the next request runs with"
+            value={settings.model}
+            size={Math.max(settings.model.length, 12)}
+            onChange={(event) =>
+              onSettings({ ...settings, model: event.target.value })
+            }
+            autoComplete="off"
+            autoCorrect="off"
+            autoCapitalize="none"
+            spellCheck={false}
+          />
+          <select
+            aria-label="Reasoning"
+            title="Reasoning effort"
+            value={settings.reasoning}
+            onChange={(event) =>
+              onSettings({
+                ...settings,
+                reasoning: reasoningSchema.parse(event.target.value),
+              })
+            }
+          >
+            {reasoningSchema.options.map((level) => (
+              <option key={level} value={level}>
+                {reasoningLabel(level)}
+              </option>
+            ))}
+          </select>
+          <button
+            type="button"
+            className="a0-fast"
+            aria-label="Fast"
+            aria-pressed={settings.fast}
+            title="Fast: the faster tier when the model has one. May cost more."
+            onClick={() => onSettings({ ...settings, fast: !settings.fast })}
+          >
+            <Zap
+              size={13}
+              fill={settings.fast ? 'currentColor' : 'none'}
+              aria-hidden
+            />
+          </button>
+        </div>
+        <div className="a0-composer-actions">
+          {!!queued && <span className="a0-queued">{queued} queued</span>}
+          {working && (
+            <button
+              type="button"
+              className="a0-ghost"
+              disabled={!onStop}
+              onClick={onStop ?? undefined}
+            >
+              Stop
+            </button>
+          )}
+          <button type="submit" disabled={!ready}>
+            Send
+          </button>
+        </div>
+      </div>
+    </form>
+  )
+}

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

@@ -0,0 +1,109 @@
+'use client'
+import type { CSSProperties, ReactNode } from 'react'
+import { createContext, useContext, useRef, useState } from 'react'
+import {
+  appsWidth,
+  chatMin,
+  previewMin,
+  serializeWidths,
+  type Widths,
+  widthsCookie,
+  writeCookie,
+} from './cookies'
+import { Splitter } from './splitter'
+
+type Column = keyof Widths
+
+type Resize = (column: Column, width: number, done: boolean) => void
+
+const edges: Record<
+  Column,
+  { label: string; min: number; max: (widths: Widths) => number }
+> = {
+  apps: {
+    label: 'Resize the apps list',
+    min: appsWidth.min,
+    max: () => appsWidth.max,
+  },
+  chat: {
+    label: 'Resize the chat',
+    min: chatMin,
+    max: ({ apps }) => window.innerWidth - apps - previewMin,
+  },
+}
+
+const ColumnsContext = createContext<{
+  widths: Widths
+  resize: Resize
+} | null>(null)
+
+// A saved width still leaves the preview its minimum in a smaller window.
+const chatTrack = (width: number): string =>
+  `min(${width}px, 100% - var(--a0-apps-width) - ${previewMin}px)`
+
+const track = (column: Column, width: number): string =>
+  column === 'chat' ? chatTrack(width) : `${width}px`
+
+/**
+ * A0's columns, apps, chat and preview, with the widths someone dragged the
+ * first two to, kept in a cookie so the server renders them. `panel` keeps
+ * a row under the chat and preview for the dev tools, even while the page
+ * beside it loads.
+ */
+export function Columns({
+  saved,
+  panel,
+  children,
+}: {
+  saved: Widths
+  panel: boolean
+  children: ReactNode
+}): ReactNode {
+  const grid = useRef<HTMLDivElement>(null)
+  const [widths, setWidths] = useState(saved)
+  const resize: Resize = (column, width, done) => {
+    // Dragging sets the width directly, without rendering the page.
+    grid.current?.style.setProperty(
+      `--a0-${column}-width`,
+      track(column, width),
+    )
+    if (!done) return
+    const next = { ...widths, [column]: width }
+    setWidths(next)
+    writeCookie({ name: widthsCookie, value: serializeWidths(next) })
+  }
+  return (
+    <ColumnsContext value={{ widths, resize }}>
+      <div
+        ref={grid}
+        className="a0-page"
+        data-panel={panel || undefined}
+        style={
+          {
+            '--a0-apps-width': track('apps', widths.apps),
+            ...(widths.chat === null
+              ? {}
+              : { '--a0-chat-width': track('chat', widths.chat) }),
+          } as CSSProperties
+        }
+      >
+        {children}
+      </div>
+    </ColumnsContext>
+  )
+}
+
+/** The right edge of the column it sits in, which resizes that column. */
+export function ColumnEdge({ column }: { column: Column }): ReactNode {
+  const columns = useContext(ColumnsContext)
+  if (!columns) throw new Error('ColumnEdge needs Columns around it.')
+  const { label, min, max } = edges[column]
+  return (
+    <Splitter
+      label={label}
+      min={min}
+      max={() => max(columns.widths)}
+      onResize={({ width, done }) => columns.resize(column, width, done)}
+    />
+  )
+}

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

@@ -0,0 +1,116 @@
+'use client'
+import type { KeyboardEvent, ReactNode } from 'react'
+import {
+  useEffect,
+  useEffectEvent,
+  useLayoutEffect,
+  useRef,
+  useState,
+} from 'react'
+
+export type MenuItem = {
+  label: string
+  onSelect: () => void
+  danger?: boolean
+}
+
+// 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`.
+ */
+export function ContextMenu({
+  at,
+  items,
+  onClose,
+}: {
+  at: { x: number; y: number }
+  items: MenuItem[]
+  onClose: (closed: { returnFocus: boolean }) => void
+}): ReactNode {
+  const menu = useRef<HTMLDivElement>(null)
+  const [position, setPosition] = useState(at)
+
+  // Measured once it's drawn, so it can stay inside the window.
+  useLayoutEffect(() => {
+    const element = menu.current
+    if (!element) return
+    const { width, height } = element.getBoundingClientRect()
+    setPosition({
+      x: Math.max(MARGIN, Math.min(at.x, innerWidth - width - MARGIN)),
+      y: Math.max(MARGIN, Math.min(at.y, innerHeight - height - MARGIN)),
+    })
+    element.querySelector<HTMLElement>('[role="menuitem"]')?.focus()
+  }, [at])
+
+  const dismiss = useEffectEvent((returnFocus: boolean) =>
+    onClose({ returnFocus }),
+  )
+  useEffect(() => {
+    const outside = (event: PointerEvent): void => {
+      if (!menu.current?.contains(event.target as Node)) dismiss(false)
+    }
+    const away = (): void => dismiss(false)
+    document.addEventListener('pointerdown', outside, true)
+    window.addEventListener('blur', away)
+    window.addEventListener('resize', away)
+    return () => {
+      document.removeEventListener('pointerdown', outside, true)
+      window.removeEventListener('blur', away)
+      window.removeEventListener('resize', away)
+    }
+  }, [])
+
+  const move = (event: KeyboardEvent<HTMLDivElement>): void => {
+    const buttons = [
+      ...event.currentTarget.querySelectorAll<HTMLElement>('[role="menuitem"]'),
+    ]
+    const focused = buttons.indexOf(document.activeElement as HTMLElement)
+    const next =
+      event.key === 'ArrowDown'
+        ? (focused + 1) % buttons.length
+        : event.key === 'ArrowUp'
+          ? (focused - 1 + buttons.length) % buttons.length
+          : event.key === 'Home'
+            ? 0
+            : event.key === 'End'
+              ? buttons.length - 1
+              : null
+    if (event.key === 'Escape' || event.key === 'Tab') {
+      event.preventDefault()
+      onClose({ returnFocus: true })
+    } else if (next !== null) {
+      event.preventDefault()
+      buttons[next]?.focus()
+    }
+  }
+
+  return (
+    <div
+      ref={menu}
+      role="menu"
+      className="a0-menu"
+      style={{ left: position.x, top: position.y }}
+      onKeyDown={move}
+      onContextMenu={(event) => event.preventDefault()}
+    >
+      {items.map((item) => (
+        <button
+          key={item.label}
+          type="button"
+          role="menuitem"
+          data-danger={item.danger || undefined}
+          onClick={() => {
+            onClose({ returnFocus: true })
+            item.onSelect()
+          }}
+        >
+          {item.label}
+        </button>
+      ))}
+    </div>
+  )
+}

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

@@ -0,0 +1,46 @@
+/** The id of this browser's app list session. */
+export const listCookie = 'a0_list'
+
+/** The sidebar and chat widths someone dragged them to, in pixels. */
+export const widthsCookie = 'a0_widths'
+
+export type Widths = { apps: number; chat: number | null }
+
+export const defaultWidths: Widths = { apps: 216, chat: null }
+
+export const appsWidth = { min: 160, max: 400 }
+export const chatMin = 320
+export const previewMin = 320
+
+export function parseWidths(value: string | undefined): Widths {
+  const [apps, chat] = (value ?? '').split(',').map(Number)
+  return {
+    apps:
+      apps && apps >= appsWidth.min && apps <= appsWidth.max
+        ? apps
+        : defaultWidths.apps,
+    chat: chat && chat >= chatMin ? chat : null,
+  }
+}
+
+export const serializeWidths = ({ apps, chat }: Widths): string =>
+  chat === null ? String(apps) : `${apps},${chat}`
+
+/** Browser-only. */
+export function readCookie(name: string): string | undefined {
+  return document.cookie
+    .split('; ')
+    .find((entry) => entry.startsWith(`${name}=`))
+    ?.slice(name.length + 1)
+}
+
+/** Browser-only. */
+export function writeCookie({
+  name,
+  value,
+}: {
+  name: string
+  value: string
+}): void {
+  document.cookie = `${name}=${value}; path=/; max-age=31536000; samesite=lax`
+}

package/examples/playground/app/a0/crash-on-request.ts

@@ -0,0 +1,72 @@
+import 'server-only'
+import type { AIState } from 'experimental-a2/ai'
+import { type AppMessage, appAgent } from './model'
+import type { agentServer, crashServer } from './server'
+
+type AppSession = ReturnType<typeof agentServer.session>
+type CrashLog = ReturnType<typeof crashServer.session>
+
+const working = (state: AIState<AppMessage>): boolean =>
+  state.status === 'generating' ||
+  state.status === 'waiting' ||
+  !!state.pendingQueueCommands?.length
+
+/** Resolves once the app's agent stops working. */
+async function workDone(app: AppSession): Promise<void> {
+  const { state: initial, index } = await app.state()
+  let state = initial
+  if (!working(state)) return
+  for await (const event of app.stream({ startAfter: index })) {
+    // A cleared app has nothing left to work on.
+    if (event.type === 'a2.cleared') return
+    state = appAgent.reducer.fold(state, event)
+    if (!working(state)) return
+  }
+}
+
+async function listen({
+  app,
+  log,
+}: {
+  app: AppSession
+  log: CrashLog
+}): Promise<void> {
+  const crash = async (): Promise<never> => {
+    // Recorded first, so the resumed work doesn't crash again.
+    await log.append({ type: 'crashed', payload: {} })
+    process.exit(1)
+  }
+  const { state: pending, index } = await log.state()
+  if (pending) return crash()
+  const requests = log.stream({ startAfter: index })[Symbol.asyncIterator]()
+  // When the work ends, closing the stream ends the loop below.
+  const close = (): void => void requests.return?.()
+  void workDone(app).then(close, close)
+  for await (const event of { [Symbol.asyncIterator]: () => requests })
+    if (event.type === 'crash.requested') return crash()
+}
+
+// One listener per app in this process, while its agent works here.
+const listening = new Map<string, Promise<void>>()
+
+/**
+ * The dev tools' crash: while the app's agent works in this process, a
+ * request in its crash log ends the process at once, mid-stream or
+ * mid-command, and the scheduler resumes the turn in a fresh invocation.
+ * Each step calls this, so work resumed elsewhere gets a listener too.
+ */
+export function crashOnRequest({
+  appId,
+  app,
+  log,
+}: {
+  appId: string
+  app: AppSession
+  log: CrashLog
+}): Promise<void> {
+  const current = listening.get(appId)
+  if (current) return current
+  const started = listen({ app, log }).finally(() => listening.delete(appId))
+  listening.set(appId, started)
+  return started
+}