experimental-a2 0.19.0 → 0.20.0

package/examples/playground/app/agent/model-input.test.tsx

@@ -1,58 +1,107 @@
 // @vitest-environment jsdom
-import { cleanup, fireEvent, render, screen } from '@testing-library/react'
-import { afterEach, expect, it, vi } from 'vitest'
+import {
+  cleanup,
+  fireEvent,
+  render,
+  screen,
+  waitFor,
+} from '@testing-library/react'
+import { afterEach, beforeEach, expect, it } from 'vitest'
+import { serveAgent, type ServedAgent } from '@/test/agent'
+import { AgentClient } from './[agentId]/agent-client'
 import type { ModelChoice } from './model'
-import { ModelInput } from './model-input'
 
-afterEach(cleanup)
+let served: ServedAgent
+let server: ServedAgent['server']
+let probe: ServedAgent['probe']
+let id: string
 
-const renderInput = (value: ModelChoice) => {
-  const onChange = vi.fn<(settings: ModelChoice) => void>()
-  const view = render(
-    <ModelInput value={value} onChange={onChange} disabled={false} />,
+beforeEach(async () => {
+  served = await serveAgent()
+  ;({ server, probe } = served)
+  id = crypto.randomUUID()
+})
+
+afterEach(async () => {
+  cleanup()
+  await served.close()
+})
+
+/** The agent page, after an earlier choice. */
+const page = async (choice: ModelChoice) => {
+  await server
+    .session(id)
+    .append({ type: 'model.choice.updated', payload: choice })
+  render(
+    <AgentClient agentId={id} initial={await server.session(id).state()} />,
+  )
+  await waitFor(() =>
+    expect(ofSession().map(({ type }) => type)).toContain('stream'),
   )
-  return {
-    onChange,
-    model: screen.getByRole('textbox') as HTMLInputElement,
-    update: (next: ModelChoice) =>
-      view.rerender(
-        <ModelInput value={next} onChange={onChange} disabled={false} />,
-      ),
-  }
 }
 
-it('commits a typed model on blur or Enter, not per keystroke', () => {
-  const { onChange, model, update } = renderInput({ reasoning: 'high' })
-  fireEvent.change(model, { target: { value: 'openai/gpt' } })
-  fireEvent.change(model, { target: { value: ' provider/model ' } })
-  expect(onChange).not.toHaveBeenCalled()
-  expect(model.value).toBe(' provider/model ')
-  fireEvent.blur(model)
-  expect(onChange).toHaveBeenCalledExactlyOnceWith({
-    reasoning: 'high',
-    model: 'provider/model',
-  })
+/** The page's own client serves every test's session. */
+const ofSession = () =>
+  probe.operations.filter((operation) => operation.sessionId === id)
+
+/** The choices the page pushed, in order. */
+const pushed = (): unknown[] =>
+  ofSession().flatMap((operation) =>
+    operation.type === 'push'
+      ? operation.events.map((event) => [event.type, event.payload])
+      : [],
+  )
+
+const chosen = async (): Promise<ModelChoice> =>
+  (await server.session(id).state()).state.modelChoice
 
-  update({ reasoning: 'high', model: 'provider/model' })
-  expect(model.value).toBe('provider/model')
-  fireEvent.change(model, { target: { value: '' } })
-  fireEvent.keyDown(model, { key: 'Enter' })
-  expect(onChange).toHaveBeenLastCalledWith({ reasoning: 'high' })
+const model = () =>
+  screen.getByRole('textbox', { name: 'Model' }) as HTMLInputElement
+
+it('commits a typed model on blur or Enter, not per keystroke', async () => {
+  await page({ reasoning: 'high' })
+  fireEvent.change(model(), { target: { value: 'openai/gpt' } })
+  fireEvent.change(model(), { target: { value: ' provider/model ' } })
+  expect(model().value).toBe(' provider/model ')
+  fireEvent.blur(model())
+  await waitFor(async () =>
+    expect(await chosen()).toEqual({
+      reasoning: 'high',
+      model: 'provider/model',
+    }),
+  )
+  expect(pushed()).toEqual([
+    ['model.choice.updated', { reasoning: 'high', model: 'provider/model' }],
+  ])
+  expect(model().value).toBe('provider/model')
+
+  fireEvent.change(model(), { target: { value: '' } })
+  fireEvent.keyDown(model(), { key: 'Enter' })
+  await waitFor(async () =>
+    expect(await chosen()).toEqual({ reasoning: 'high' }),
+  )
+  expect(pushed()).toHaveLength(2)
 })
 
-it('commits reasoning and speed immediately and omits defaults', () => {
-  const { onChange } = renderInput({
-    model: 'provider/model',
-    reasoning: 'low',
-  })
+it('commits reasoning and speed immediately and omits defaults', async () => {
+  await page({ model: 'provider/model', reasoning: 'low' })
   fireEvent.change(screen.getByTitle('Thinking level'), {
     target: { value: 'provider-default' },
   })
-  expect(onChange).toHaveBeenLastCalledWith({ model: 'provider/model' })
+  await waitFor(async () =>
+    expect(await chosen()).toEqual({ model: 'provider/model' }),
+  )
   fireEvent.click(screen.getByRole('button', { name: 'Prefer fast' }))
-  expect(onChange).toHaveBeenLastCalledWith({
-    model: 'provider/model',
-    reasoning: 'low',
-    speed: 'fast',
-  })
+  await waitFor(async () =>
+    expect(await chosen()).toEqual({ model: 'provider/model', speed: 'fast' }),
+  )
+  expect(pushed()).toEqual([
+    ['model.choice.updated', { model: 'provider/model' }],
+    ['model.choice.updated', { model: 'provider/model', speed: 'fast' }],
+  ])
+  expect(
+    screen
+      .getByRole('button', { name: 'Prefer fast' })
+      .getAttribute('aria-pressed'),
+  ).toBe('true')
 })

package/examples/playground/app/chat/[chatId]/agent-stream-drawer.test.tsx

@@ -1,5 +1,5 @@
 import { renderToStaticMarkup } from 'react-dom/server'
-import { describe, expect, it, vi } from 'vitest'
+import { describe, expect, it } from 'vitest'
 import type { ChatAgentMessage } from '../model'
 import { AgentStreamDrawer } from './agent-stream-drawer'
 import type { AgentMessageMetadata, AgentStreamSelection } from './chat-view'
@@ -89,7 +89,7 @@ describe('AgentStreamDrawer', () => {
         selection={selection}
         summary="ambient · 35 tokens · 2 model steps"
         status="completed"
-        onClose={vi.fn<() => void>()}
+        onClose={() => {}}
       />,
     )
 

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

@@ -1,68 +1,13 @@
-import type { UIMessageChunk } from 'ai'
-import { expect, it, vi } from 'vitest'
+import { afterEach, expect, it, vi } from 'vitest'
+import { testModel, toolCall } from '@/test/model'
+import { chatAgentServer, chatServer } from './server'
 
-vi.mock('server-only', () => ({}))
-vi.mock('@/lib/store', async () => {
-  const { memory } = await import('experimental-a2/store-memory')
-  return { store: memory() }
-})
-
-// The chat's real agent, with a scripted model: two `post` calls, then done.
-const { prompts, step } = vi.hoisted(() => ({
-  prompts: [] as string[],
-  step: (chunks: UIMessageChunk[]) =>
-    new ReadableStream<UIMessageChunk>({
-      start(controller) {
-        for (const chunk of chunks) controller.enqueue(chunk)
-        controller.close()
-      },
-    }),
-}))
-vi.mock('experimental-a2/ai/server', async (importActual) => {
-  const actual =
-    await importActual<typeof import('experimental-a2/ai/server')>()
-  return {
-    ...actual,
-    agent: (options: Parameters<typeof actual.agent>[0]) =>
-      actual.agent({
-        ...options,
-        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),
-  }
+afterEach(() => {
+  vi.unstubAllGlobals()
 })
 
 it('forwards room messages to the agent, whose posts land in the room', async () => {
-  const { chatAgentServer, chatServer } = await import('./server')
+  const model = testModel({ id: 'openai/gpt-5.4' })
   const room = chatServer.session('room')
   const agent = chatAgentServer.session('room')
   await room.append({
@@ -74,6 +19,20 @@ it('forwards room messages to the agent, whose posts land in the room', async ()
     payload: { author: 'bob', text: '@agent say hi' },
   })
 
+  // The mention's step posts twice; the step after the posts ends the turn.
+  const posting = await model.step(0)
+  posting.write(
+    ...['Hello', 'there'].flatMap((message, call) =>
+      toolCall({
+        id: `call-${call}`,
+        name: 'post',
+        chunks: [JSON.stringify({ message })],
+      }),
+    ),
+  )
+  posting.finish('tool-calls')
+  ;(await model.step(1)).finish('stop')
+
   // Without a scheduler, appends run in background drains.
   await vi.waitFor(
     async () => {
@@ -92,19 +51,33 @@ it('forwards room messages to the agent, whose posts land in the room', async ()
   expect(state.posts[0]!.index).toBeGreaterThan(state.messages[1]!.index)
   // The passive message reached the agent as context without a reply of its
   // own; only the mention generated, and it saw both.
-  expect(prompts).toHaveLength(2)
+  expect(model.steps).toHaveLength(2)
   expect(
-    prompts[0]!.split(',').filter((id) => id.startsWith('user:')),
-  ).toHaveLength(2)
+    JSON.stringify(
+      model.steps[0]!.options.prompt.filter(
+        (message) => message.role === 'user',
+      ),
+    ),
+  ).toMatch(/alice: just chatting.*bob: @agent say hi/)
   const messages = (await agent.state()).state.messages
   expect(messages.map((message) => message.role)).toEqual([
     'user',
     'user',
     'assistant',
   ])
+  // One response, both of its steps recorded on it.
+  expect(messages[2]!.metadata).toMatchObject({
+    kind: 'agent',
+    author: 'agent',
+    mode: 'mention',
+    steps: [
+      { model: 'openai/gpt-5.4', finishReason: 'tool-calls' },
+      { model: 'openai/gpt-5.4', finishReason: 'stop' },
+    ],
+  })
 
   // Replaying the post tool's append converges on the stored event.
-  const [post] = (await room.history()).filter(
+  const post = (await room.history()).find(
     (event) => event.type === 'agent.message.posted',
   )
   await room.append({ type: post!.type, id: post!.id, payload: post!.payload })

package/examples/playground/app/components/activity-history.test.tsx

@@ -1,35 +1,77 @@
 // @vitest-environment jsdom
-import { act, cleanup, fireEvent, render, screen } from '@testing-library/react'
-import { afterEach, expect, it, vi } from 'vitest'
+import {
+  act,
+  cleanup,
+  fireEvent,
+  render,
+  screen,
+  waitFor,
+} from '@testing-library/react'
+import type { InitialSnapshot } from 'experimental-a2'
+import { useAgent } from 'experimental-a2/ai/react'
+import { createClient } from 'experimental-a2/client'
+import type { ReactNode } from 'react'
+import { afterEach, expect, it } from 'vitest'
+import { serveAgent, type ServedAgent } from '@/test/agent'
+import { demoAgent, type AgentState } from '../agent/model'
 import { ActivityFeed } from './activity-feed'
 
-afterEach(cleanup)
+let served: ServedAgent | undefined
+
+afterEach(async () => {
+  cleanup()
+  await served?.close()
+})
 
 it('loads an earlier page only on request and keeps failures retryable', async () => {
-  const loadHistory = vi
-    .fn<() => Promise<unknown>>()
-    .mockRejectedValueOnce(new Error('Read failed'))
-    .mockResolvedValueOnce([])
-  render(
-    <ActivityFeed
-      events={[]}
-      index={100}
-      history={{ loading: false, complete: false, oldestLoaded: null }}
-      loadHistory={loadHistory}
-    />,
-  )
-  expect(loadHistory).not.toHaveBeenCalled()
+  served = await serveAgent()
+  const { server, probe } = served
+  const client = createClient({ contract: demoAgent, api: served.url })
+  const id = crypto.randomUUID()
+  await server.session(id).append({
+    type: 'compaction.settings.updated',
+    payload: { mode: 'disabled' },
+  })
+  const operations = () => probe.operations.map(({ type }) => type)
+
+  function Feed({
+    initial,
+  }: {
+    initial: InitialSnapshot<AgentState>
+  }): ReactNode {
+    const session = useAgent({ client, id, initial })
+    return (
+      <ActivityFeed
+        events={session.events}
+        index={session.index}
+        history={session.history}
+        loadHistory={session.loadHistory}
+      />
+    )
+  }
+
+  probe.deny(({ type }) => type === 'history')
+  render(<Feed initial={await server.session(id).state()} />)
+  await waitFor(() => expect(operations()).toContain('stream'))
+  expect(operations()).not.toContain('history')
   await act(async () =>
     fireEvent.click(
       screen.getByRole('button', { name: 'Load earlier events' }),
     ),
   )
-  expect(screen.getByRole('alert').textContent).toBe('Read failed')
+  expect((await screen.findByRole('alert')).textContent).toBe(
+    'the operation is not authorized',
+  )
   await act(async () =>
     fireEvent.click(
       screen.getByRole('button', { name: 'Load earlier events' }),
     ),
   )
+  await waitFor(() =>
+    expect(screen.getByRole('list').textContent).toContain(
+      'compaction.settings.updated',
+    ),
+  )
   expect(screen.queryByRole('alert')).toBeNull()
-  expect(loadHistory).toHaveBeenCalledTimes(2)
+  expect(operations().filter((type) => type === 'history')).toHaveLength(2)
 })

package/examples/playground/app/components/fast-link.test.tsx

@@ -9,8 +9,8 @@ import {
 import { afterEach, beforeEach, expect, it, vi } from 'vitest'
 import { FastLink } from './fast-link'
 
-const push = vi.fn<(href: string) => void>()
-vi.mock('next/navigation', () => ({ useRouter: () => ({ push }) }))
+// The App Router's router only exists inside a Next.js app.
+vi.mock('next/navigation', () => ({ useRouter: () => ({ push: () => {} }) }))
 
 // Whether each click reached the browser's default; then stop jsdom's
 // unimplemented navigation.
@@ -20,7 +20,6 @@ const record = (event: MouseEvent): void => {
   event.preventDefault()
 }
 beforeEach(() => {
-  push.mockReset()
   navigatedByClick = []
   document.addEventListener('click', record)
 })
@@ -40,10 +39,9 @@ const press = (): void => {
   fireEvent(link(), event)
 }
 
-it('navigates on the press and swallows only that click', () => {
+it('swallows only the click that follows a press', () => {
   render(<FastLink href="/a0">Apps</FastLink>)
   press()
-  expect(push).toHaveBeenCalledWith('/a0')
   fireEvent.click(link(), { detail: 1 })
   fireEvent.click(link(), { detail: 1 })
   expect(navigatedByClick).toEqual([false, true])

package/examples/playground/app/initial-state.test.tsx

@@ -1,54 +1,95 @@
 import type { ReactElement } from 'react'
-import { beforeEach, expect, it, vi } from 'vitest'
+import { afterEach, expect, it, vi, type Mock } from 'vitest'
 import AgentPage from './agent/[agentId]/page'
+import { agentServer } from './agent/server'
 import ChatPage from './chat/[chatId]/page'
+import { chatAgentServer, chatServer } from './chat/server'
 
-const agentReads = vi.hoisted(() => ({
-  initial: { state: { agent: true }, index: 7 },
-  state: vi.fn<() => Promise<{ state: { agent: boolean }; index: number }>>(),
-  history: vi.fn<() => never>(),
-}))
-const reads = vi.hoisted(() => ({
-  initial: { state: { marker: true }, index: 42 },
-  state: vi.fn<() => Promise<{ state: { marker: boolean }; index: number }>>(),
-  history: vi.fn<() => never>(),
-}))
-vi.mock('./agent/server', () => ({ agentServer: { session: () => reads } }))
-vi.mock('./chat/server', () => ({
-  chatServer: { session: () => reads },
-  chatAgentServer: { session: () => agentReads },
-}))
-vi.mock('./agent/[agentId]/agent-client', () => ({ AgentClient: () => null }))
-vi.mock('./chat/[chatId]/chat-client', () => ({ ChatClient: () => null }))
-
-beforeEach(() => {
-  reads.state.mockReset().mockResolvedValue(reads.initial)
-  agentReads.state.mockReset().mockResolvedValue(agentReads.initial)
-  reads.history.mockReset().mockImplementation(() => {
-    throw new Error('unexpected history read')
+afterEach(() => {
+  vi.restoreAllMocks()
+})
+
+type Read = (...args: never[]) => unknown
+type Handle = { state: Read; history: Read }
+type Reads = { state: Mock<Read>; history: Mock<Read> }
+
+/** The reads made through each session handle `server` hands out from now on. */
+const readsOf = <H extends Handle>(server: {
+  session(id: string): H
+}): Reads[] => {
+  const session = server.session.bind(server)
+  const handles: Reads[] = []
+  vi.spyOn(server, 'session').mockImplementation((id) => {
+    const handle = session(id)
+    const reads: Reads = {
+      state: vi.fn<Read>(handle.state),
+      history: vi.fn<Read>(handle.history),
+    }
+    handles.push(reads)
+    return { ...handle, ...reads }
+  })
+  return handles
+}
+
+const oneStateRead = (handles: Reads[]): void => {
+  expect(handles).toHaveLength(1)
+  expect(handles[0]!.state).toHaveBeenCalledExactlyOnceWith()
+  expect(handles[0]!.history).not.toHaveBeenCalled()
+}
+
+it('seeds agent from one state read without fetching raw history', async () => {
+  const agentId = crypto.randomUUID()
+  const session = agentServer.session(agentId)
+  await session.append({
+    type: 'compaction.settings.updated',
+    payload: { mode: 'manual', thresholdTokens: 1234 },
   })
+  await agentServer.drain(agentId)
+  const expected = await session.state()
+  expect(expected.state.compactionSettings).toEqual({
+    mode: 'manual',
+    thresholdTokens: 1234,
+  })
+
+  const reads = readsOf(agentServer)
+  const element = (await AgentPage({
+    params: Promise.resolve({ agentId }),
+  })) as ReactElement<{ initial: unknown; initialEvents?: unknown }>
+  oneStateRead(reads)
+  expect(element.props.initial).toEqual(expected)
+  expect(element.props.initialEvents).toBeUndefined()
 })
 
-it.each(['agent', 'chat'] as const)(
-  'seeds %s from one state read without fetching raw history',
-  async (page) => {
-    const element = (await (page === 'agent'
-      ? AgentPage({ params: Promise.resolve({ agentId: 'one' }) })
-      : ChatPage({
-          params: Promise.resolve({ chatId: 'one' }),
-        }))) as ReactElement<{ initial: unknown; initialEvents?: unknown }>
-    expect(reads.state).toHaveBeenCalledExactlyOnceWith()
-    expect(reads.history).not.toHaveBeenCalled()
-    expect(element.props.initial).toBe(reads.initial)
-    expect(element.props.initialEvents).toBeUndefined()
-  },
-)
-
-it("seeds the chat's agent session from its own state read", async () => {
+it('seeds chat and its agent session, each from one state read', async () => {
+  const chatId = crypto.randomUUID()
+  await chatServer.session(chatId).append({
+    type: 'message.sent',
+    payload: { author: 'alice', text: 'just chatting' },
+  })
+  // The room forwards the message to its agent in a background drain.
+  await vi.waitFor(async () => {
+    expect(
+      (await chatAgentServer.session(chatId).state()).state.messages,
+    ).toHaveLength(1)
+  })
+  await chatServer.drain(chatId)
+  await chatAgentServer.drain(chatId)
+  const room = await chatServer.session(chatId).state()
+  const agent = await chatAgentServer.session(chatId).state()
+  expect(room.state.messages).toHaveLength(1)
+
+  const roomReads = readsOf(chatServer)
+  const agentReads = readsOf(chatAgentServer)
   const element = (await ChatPage({
-    params: Promise.resolve({ chatId: 'one' }),
-  })) as ReactElement<{ children: ReactElement<{ agentInitial: unknown }> }>
-  expect(agentReads.state).toHaveBeenCalledExactlyOnceWith()
-  expect(agentReads.history).not.toHaveBeenCalled()
-  expect(element.props.children.props.agentInitial).toBe(agentReads.initial)
+    params: Promise.resolve({ chatId }),
+  })) as ReactElement<{
+    initial: unknown
+    initialEvents?: unknown
+    children: ReactElement<{ agentInitial: unknown }>
+  }>
+  oneStateRead(roomReads)
+  oneStateRead(agentReads)
+  expect(element.props.initial).toEqual(room)
+  expect(element.props.initialEvents).toBeUndefined()
+  expect(element.props.children.props.agentInitial).toEqual(agent)
 })

package/examples/playground/package.json

@@ -30,7 +30,7 @@
     "@vercel/sandbox": "^3.0.0",
     "ai": "^7.0.58",
     "codemirror": "^6.0.2",
-    "experimental-a2": "0.19.0",
+    "experimental-a2": "0.20.0",
     "geist": "^1.7.2",
     "ioredis": "^5.9.0",
     "libfx": "0.0.12",
@@ -56,6 +56,7 @@
     "@types/react-dom": "^19.0.0",
     "@types/ws": "^8.18.1",
     "typescript": "^7.0.2",
+    "undici": "^8.10.2",
     "vitest": "^4.1.10"
   }
 }

package/examples/playground/test/agent.ts

@@ -0,0 +1,35 @@
+import { agent } from 'experimental-a2/ai/server'
+import { memory } from 'experimental-a2/store-memory'
+import { demoAgent } from '@/app/agent/model'
+import { authorizer, serve } from './serve'
+
+/**
+ * The playground's agent on a memory store, served where the page's own
+ * client finds it: `/agent/events` on the origin relative URLs resolve
+ * against. Its tests never start a turn, so its model never runs.
+ */
+export async function serveAgent() {
+  const server = agent({
+    contract: demoAgent,
+    store: memory(),
+    model: 'test-model',
+  })
+  const probe = authorizer()
+  const served = await serve({
+    routes: {
+      '/agent/events': (request) =>
+        server.fetch(request, { authorize: probe.authorize }),
+    },
+  })
+  return {
+    server,
+    probe,
+    url: `${served.origin}/agent/events`,
+    close: async (): Promise<void> => {
+      probe.release()
+      await served.close()
+    },
+  }
+}
+
+export type ServedAgent = Awaited<ReturnType<typeof serveAgent>>