experimental-a2 0.18.1 → 0.20.0

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/next.config.ts

@@ -6,13 +6,16 @@ import type { NextConfig } from 'next'
 
 const nextConfig: NextConfig = {
   // libfx loads a native binary for the platform, falling back to its
-  // WebAssembly, by paths the bundler cannot follow; Node loads both from
-  // node_modules at runtime.
-  serverExternalPackages: ['libfx'],
+  // WebAssembly, and photon, which Pi resizes images with, loads its
+  // WebAssembly, by paths the bundler cannot follow; Node loads them from
+  // node_modules at runtime. Pi stays bundled (externalized, it makes
+  // Turbopack panic on its WebAssembly), so it finds photon through this
+  // app: package.json depends on photon at the version Pi pins, and the two
+  // move together.
+  serverExternalPackages: ['libfx', '@silvia-odwyer/photon-node'],
   turbopack: {
     // WebAssembly Pi's code reaches that the bundler cannot trace.
     resolveAlias: {
-      '@silvia-odwyer/photon-node': './app/a0/no-photon.cjs',
       'quickjs-wasi': './app/a0/no-quickjs.cjs',
       'quickjs-wasi/quickjs.wasm': './app/a0/no-quickjs.cjs',
     },

package/examples/playground/package.json

@@ -22,13 +22,15 @@
     "@earendil-works/pi-ai": "1.0.3",
     "@earendil-works/pi-coding-agent": "1.0.2",
     "@opentelemetry/api": "^1.9.0",
+    "@silvia-odwyer/photon-node": "0.3.4",
+    "@vercel/blob": "^2.8.0",
     "@vercel/functions": "^3.9.3",
     "@vercel/otel": "^2.1.0",
     "@vercel/queue": "^0.2.0",
     "@vercel/sandbox": "^3.0.0",
     "ai": "^7.0.58",
     "codemirror": "^6.0.2",
-    "experimental-a2": "0.18.1",
+    "experimental-a2": "0.20.0",
     "geist": "^1.7.2",
     "ioredis": "^5.9.0",
     "libfx": "0.0.12",
@@ -54,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>>

package/examples/playground/test/model.ts

@@ -0,0 +1,149 @@
+/**
+ * The model behind an agent under test. Agents take AI Gateway model IDs;
+ * the AI SDK's global provider serves every one of them from this model,
+ * whose steps the test writes part by part.
+ */
+
+import { MockLanguageModelV4 } from 'ai/test'
+import { vi } from 'vitest'
+
+export type StreamPart =
+  Awaited<
+    ReturnType<MockLanguageModelV4['doStream']>
+  >['stream'] extends ReadableStream<infer Part>
+    ? Part
+    : never
+
+export type CallOptions = MockLanguageModelV4['doStreamCalls'][number]
+
+/** One model step, open until the test ends it or the agent aborts it. */
+export type ModelStep = {
+  /** What the agent sent the model for this step. */
+  options: CallOptions
+  write(...parts: StreamPart[]): void
+  /** Ends the step the way a model does: with a finish part. */
+  finish(reason?: 'stop' | 'tool-calls'): void
+}
+
+const usage = {
+  inputTokens: { total: 1, noCache: 1, cacheRead: 0, cacheWrite: 0 },
+  outputTokens: { total: 1, text: 1, reasoning: 0 },
+}
+
+/** A text part, whole. */
+export const say = ({ id, text }: { id: string; text: string }) =>
+  [
+    { type: 'text-start', id },
+    { type: 'text-delta', id, delta: text },
+    { type: 'text-end', id },
+  ] satisfies StreamPart[]
+
+/** A tool call whose input streams in as the given chunks of its JSON. */
+export const toolCall = ({
+  id,
+  name,
+  chunks,
+}: {
+  id: string
+  name: string
+  chunks: string[]
+}) =>
+  [
+    { type: 'tool-input-start', id, toolName: name },
+    ...chunks.map((delta) => ({
+      type: 'tool-input-delta' as const,
+      id,
+      delta,
+    })),
+    { type: 'tool-input-end', id },
+    {
+      type: 'tool-call',
+      toolCallId: id,
+      toolName: name,
+      input: chunks.join(''),
+    },
+  ] satisfies StreamPart[]
+
+let models = 0
+
+/**
+ * Installs a model the test drives step by step, served for `id` alone, so
+ * an agent left over from an earlier test can't take its steps. Remove it
+ * with `vi.unstubAllGlobals()`.
+ */
+export function testModel({
+  id = `test-model-${++models}`,
+}: {
+  /** The model ID the agent asks for. */
+  id?: string
+} = {}): {
+  /** The agent's `model`. */
+  id: string
+  /** Every step the agent asked for, in order. */
+  steps: ModelStep[]
+  /** The `n`th step (from 0), once the agent asks for it. */
+  step(n: number): Promise<ModelStep>
+  /** Ends every step still open, and each one asked for from now on. */
+  close(): void
+} {
+  const steps: ModelStep[] = []
+  const arrivals: PromiseWithResolvers<ModelStep>[] = []
+  const arrival = (n: number): PromiseWithResolvers<ModelStep> =>
+    (arrivals[n] ??= Promise.withResolvers<ModelStep>())
+  const ends: (() => void)[] = []
+  let closed = false
+  const model = new MockLanguageModelV4({
+    modelId: id,
+    doStream: async (options) => {
+      let controller!: ReadableStreamDefaultController<StreamPart>
+      let open = true
+      const end = (): void => {
+        if (!open) return
+        open = false
+        controller.close()
+      }
+      const stream = new ReadableStream<StreamPart>({
+        start(value) {
+          controller = value
+          controller.enqueue({ type: 'stream-start', warnings: [] })
+        },
+      })
+      options.abortSignal?.addEventListener('abort', end, { once: true })
+      const step: ModelStep = {
+        options,
+        write(...parts) {
+          for (const part of parts) if (open) controller.enqueue(part)
+        },
+        finish(reason = 'stop') {
+          step.write({
+            type: 'finish',
+            finishReason: { unified: reason, raw: reason },
+            usage,
+          })
+          end()
+        },
+      }
+      ends.push(end)
+      arrival(steps.length).resolve(step)
+      steps.push(step)
+      if (closed) step.finish()
+      return { stream }
+    },
+  })
+  vi.stubGlobal('AI_SDK_DEFAULT_PROVIDER', {
+    specificationVersion: 'v4',
+    languageModel: (requested: string) => {
+      if (requested !== id) throw new Error(`no test model '${requested}'`)
+      return model
+    },
+  })
+  return {
+    id,
+    steps,
+    step: (n) => arrival(n).promise,
+    close: () => {
+      closed = true
+      for (const end of ends) end()
+    },
+  }
+}