experimental-a2 0.16.1 → 0.18.0

package/examples/playground/app/agent/ingress.test.ts

@@ -0,0 +1,101 @@
+import { expect, it, vi } from 'vitest'
+import { agent } from 'experimental-a2/ai/server'
+import { memory } from 'experimental-a2/store-memory'
+import { inputs } from 'experimental-a2/ai'
+import { demoAgent } from './model'
+
+const message = { id: 'message', role: 'user' as const, parts: [] }
+
+const post = (events: unknown[]): Request =>
+  new Request('http://test/events?sessionId=one', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ sessionId: 'one', events }),
+  })
+
+const server = () => {
+  let generations = 0
+  const agentServer = agent({
+    contract: demoAgent,
+    store: memory(),
+    model: 'test/model',
+    harness: {
+      type: 'ai-sdk',
+      generate: () => {
+        generations += 1
+        return new ReadableStream({ start: (controller) => controller.close() })
+      },
+    },
+  })
+  return { agentServer, generations: () => generations }
+}
+
+it('accepts compaction settings from the browser without starting a turn', async () => {
+  const { agentServer, generations } = server()
+  const response = await agentServer.fetch(
+    post([
+      {
+        type: 'compaction.settings.updated',
+        payload: { mode: 'manual', thresholdTokens: 1 },
+      },
+    ]),
+  )
+  expect(response.status).toBe(200)
+  await agentServer.drain('one')
+  const { state } = await agentServer.session('one').state()
+  expect(state.compactionSettings).toEqual({
+    mode: 'manual',
+    thresholdTokens: 1,
+  })
+  expect(generations()).toBe(0)
+})
+
+it.each([0, -1, 1.5, Number.MAX_SAFE_INTEGER + 1, '1', null])(
+  'rejects invalid threshold %s',
+  async (thresholdTokens) => {
+    const { agentServer } = server()
+    const response = await agentServer.fetch(
+      post([
+        {
+          type: 'compaction.settings.updated',
+          payload: { mode: 'manual', thresholdTokens },
+        },
+      ]),
+    )
+    expect(response.status).toBe(400)
+    expect(await agentServer.session('one').history()).toEqual([])
+  },
+)
+
+it('keeps lifecycle events server-only beside public controls', async () => {
+  const { agentServer } = server()
+  const rejected = await agentServer.fetch(
+    post([
+      ...inputs.message(message),
+      { type: 'ai.session.closed', payload: {} },
+    ]),
+  )
+  expect(rejected.status).toBe(400)
+  expect(await agentServer.session('one').history()).toEqual([])
+  const accepted = await agentServer.fetch(post(inputs.message(message)))
+  expect(accepted.status).toBe(200)
+})
+
+it('forwards both HTTP and WebSocket entry requests to the agent', async () => {
+  const fetch = vi
+    .fn<(request: Request) => Promise<Response>>()
+    .mockResolvedValue(new Response(null))
+  vi.doMock('./server', () => ({ agentServer: { fetch } }))
+  try {
+    const route = await import('./events/route')
+    const read = new Request('http://test/events', {
+      headers: { upgrade: 'websocket' },
+    })
+    const write = new Request('http://test/events', { method: 'POST' })
+    await route.GET(read)
+    await route.POST(write)
+    expect(fetch.mock.calls).toEqual([[read], [write]])
+  } finally {
+    vi.doUnmock('./server')
+  }
+})

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

@@ -0,0 +1,58 @@
+// @vitest-environment jsdom
+import { cleanup, fireEvent, render, screen } from '@testing-library/react'
+import { afterEach, expect, it, vi } from 'vitest'
+import type { ModelChoice } from './model'
+import { ModelInput } from './model-input'
+
+afterEach(cleanup)
+
+const renderInput = (value: ModelChoice) => {
+  const onChange = vi.fn<(settings: ModelChoice) => void>()
+  const view = render(
+    <ModelInput value={value} onChange={onChange} disabled={false} />,
+  )
+  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',
+  })
+
+  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' })
+})
+
+it('commits reasoning and speed immediately and omits defaults', () => {
+  const { onChange } = renderInput({
+    model: 'provider/model',
+    reasoning: 'low',
+  })
+  fireEvent.change(screen.getByTitle('Thinking level'), {
+    target: { value: 'provider-default' },
+  })
+  expect(onChange).toHaveBeenLastCalledWith({ model: 'provider/model' })
+  fireEvent.click(screen.getByRole('button', { name: 'Prefer fast' }))
+  expect(onChange).toHaveBeenLastCalledWith({
+    model: 'provider/model',
+    reasoning: 'low',
+    speed: 'fast',
+  })
+})

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

@@ -0,0 +1,115 @@
+'use client'
+
+import { useState, type ReactNode } from 'react'
+import { reasoningLevels, type ReasoningLevel } from 'experimental-a2/ai'
+import { agentModel, type ModelChoice } from './model'
+
+const choose = <K extends keyof ModelChoice>(
+  settings: ModelChoice,
+  key: K,
+  value: ModelChoice[K] | undefined,
+): ModelChoice => {
+  const { [key]: _previous, ...rest } = settings
+  return value === undefined ? rest : { ...rest, [key]: value }
+}
+
+export function ModelInput({
+  value,
+  onChange,
+  disabled,
+}: {
+  value: ModelChoice
+  onChange: (settings: ModelChoice) => void
+  disabled: boolean
+}): ReactNode {
+  // A choice is a durable session event, so a typed model id commits on
+  // blur or Enter rather than once per keystroke.
+  const [draft, setDraft] = useState<string | null>(null)
+  const model = draft ?? value.model ?? ''
+  const commit = (): void => {
+    if (draft === null) return
+    setDraft(null)
+    const next = draft.trim() || undefined
+    if (next !== value.model) onChange(choose(value, 'model', next))
+  }
+  return (
+    <div className="agent-model-controls">
+      <label className="agent-model-choice">
+        <span className="sr-only">Model</span>
+        <input
+          type="text"
+          value={model}
+          placeholder={agentModel}
+          size={Math.max(model.length || agentModel.length, 12)}
+          onChange={(event) => setDraft(event.target.value)}
+          onBlur={commit}
+          onKeyDown={(event) => {
+            if (event.key !== 'Enter' || event.nativeEvent.isComposing) return
+            event.preventDefault()
+            commit()
+          }}
+          disabled={disabled}
+          autoComplete="off"
+          autoCorrect="off"
+          autoCapitalize="none"
+          spellCheck={false}
+        />
+      </label>
+      <label className="agent-thinking-choice">
+        <span className="sr-only">Thinking level</span>
+        <select
+          title="Thinking level"
+          value={value.reasoning ?? 'provider-default'}
+          onChange={(event) => {
+            const level = event.target.value as ReasoningLevel
+            onChange(
+              choose(
+                value,
+                'reasoning',
+                level === 'provider-default' ? undefined : level,
+              ),
+            )
+          }}
+          disabled={disabled}
+        >
+          {reasoningLevels.map((level) => (
+            <option key={level} value={level}>
+              {level === 'provider-default'
+                ? 'Default'
+                : level === 'xhigh'
+                  ? 'Extra high'
+                  : level[0]!.toUpperCase() + level.slice(1)}
+            </option>
+          ))}
+        </select>
+      </label>
+      <button
+        type="button"
+        className="agent-fast-toggle"
+        aria-label="Prefer fast"
+        aria-pressed={value.speed === 'fast'}
+        title="Prefer fast: uses the faster tier when available. May cost more; otherwise runs at standard speed."
+        onClick={() =>
+          onChange(
+            choose(value, 'speed', value.speed === 'fast' ? undefined : 'fast'),
+          )
+        }
+        disabled={disabled}
+      >
+        <svg
+          width="18"
+          height="18"
+          viewBox="0 0 24 24"
+          fill={value.speed === 'fast' ? 'currentColor' : 'none'}
+          stroke="currentColor"
+          strokeWidth="1.7"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+          aria-hidden="true"
+        >
+          <path d="M13 2 3 14h9l-1 8 10-12h-9l1-8Z" />
+        </svg>
+      </button>
+    </div>
+  )
+}

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

@@ -0,0 +1,73 @@
+import { expect, it } from 'vitest'
+import {
+  agentModel,
+  compactionOptions,
+  demoAgent,
+  modelSettings,
+  type AgentEvent,
+} from './model'
+
+const event = <T extends AgentEvent['type']>(
+  index: number,
+  type: T,
+  payload: Extract<AgentEvent, { type: T }>['payload'],
+): AgentEvent =>
+  ({
+    id: `event-${index}`,
+    sessionId: 's',
+    index,
+    createdAt: new Date(0),
+    type,
+    payload,
+  }) as AgentEvent
+
+it('folds compaction settings beside the AI state', () => {
+  const { reducer } = demoAgent
+  let state = reducer.fold(
+    reducer.initialState,
+    event(1, 'compaction.settings.updated', { mode: 'disabled' }),
+  )
+  state = reducer.fold(
+    state,
+    event(2, 'ai.message.created', {
+      message: { id: 'user', role: 'user', parts: [] },
+    }),
+  )
+  expect(state.compactionSettings).toEqual({ mode: 'disabled' })
+  expect(state.compactionSettingsId).toBe('event-1')
+  expect(state.messages.map((message) => message.id)).toEqual(['user'])
+})
+
+it.each([
+  [{ mode: 'automatic' } as const, {}],
+  [{ mode: 'manual', thresholdTokens: 1 } as const, { thresholdTokens: 1 }],
+  [{ mode: 'disabled' } as const, false],
+])('maps %j to compaction options', (settings, options) => {
+  const state = demoAgent.reducer.fold(
+    demoAgent.reducer.initialState,
+    event(1, 'compaction.settings.updated', settings),
+  )
+  expect(compactionOptions(state.compactionSettings)).toEqual(options)
+})
+
+it('folds the model choice and fills in the default model', () => {
+  const { reducer } = demoAgent
+  const state = reducer.fold(
+    reducer.initialState,
+    event(1, 'model.choice.updated', { reasoning: 'high', speed: 'fast' }),
+  )
+  expect(reducer.initialState.modelChoice).toEqual({})
+  expect(modelSettings(state.modelChoice)).toEqual({
+    model: agentModel,
+    reasoning: 'high',
+    speed: 'fast',
+  })
+  expect(
+    modelSettings(
+      reducer.fold(
+        state,
+        event(2, 'model.choice.updated', { model: 'openai/gpt-5.6-terra' }),
+      ).modelChoice,
+    ),
+  ).toEqual({ model: 'openai/gpt-5.6-terra' })
+})

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

@@ -1,6 +1,13 @@
-import { agent } from 'experimental-a2/ai'
 import type { ContractEvent } from 'experimental-a2'
-import type { AutomaticCompaction } from 'experimental-a2/ai/server'
+import {
+  agentContract,
+  reasoningLevels,
+  type ReasoningLevel,
+} from 'experimental-a2/ai'
+import type {
+  AutomaticCompaction,
+  ModelSettings,
+} from 'experimental-a2/ai/server'
 import { z } from 'zod'
 
 export const agentModel = 'openai/gpt-5.6-luna'
@@ -16,36 +23,61 @@ export const compactionSettingsSchema = z.discriminatedUnion('mode', [
 
 export type CompactionSettings = z.infer<typeof compactionSettingsSchema>
 
-export const demoAgent = agent({
-  name: 'agent',
-  events: { 'compaction.settings.updated': compactionSettingsSchema },
+/** The picker's choice; an omitted field keeps the agent's default. */
+export const modelChoiceSchema = z.strictObject({
+  model: z.string().trim().min(1).optional(),
+  reasoning: z
+    .string()
+    .refine((value): value is ReasoningLevel =>
+      reasoningLevels.includes(value as ReasoningLevel),
+    )
+    .optional(),
+  speed: z.enum(['fast', 'standard']).optional(),
 })
 
-export type AgentEvent = ContractEvent<typeof demoAgent.contract.events>
+export type ModelChoice = z.infer<typeof modelChoiceSchema>
 
 const automatic: CompactionSettings = { mode: 'automatic' }
-
-export function latestCompactionSettings(history: readonly AgentEvent[]): {
-  settings: CompactionSettings
-  id: string
-} {
-  const event = history.findLast(
-    (candidate) => candidate.type === 'compaction.settings.updated',
-  )
-  return event
-    ? { settings: event.payload, id: event.id }
-    : { settings: automatic, id: 'default' }
+const noChoice: ModelChoice = {}
+const settingsState: {
+  compactionSettings: CompactionSettings
+  compactionSettingsId: string
+  modelChoice: ModelChoice
+} = {
+  compactionSettings: automatic,
+  compactionSettingsId: 'default',
+  modelChoice: noChoice,
 }
 
-export const compactionSettings = demoAgent.contract
-  .reducer({
-    name: 'agent.compaction-settings.v1',
-    initialState: automatic,
-    stateSchema: compactionSettingsSchema,
-  })
-  .fold((state, event): CompactionSettings =>
-    event.type === 'compaction.settings.updated' ? event.payload : state,
-  )
+export const demoAgent = agentContract({
+  name: 'agent',
+  events: {
+    'compaction.settings.updated': compactionSettingsSchema,
+    'model.choice.updated': modelChoiceSchema,
+  },
+  reducer: {
+    name: 'a2.playground.agent.v4',
+    initialState: settingsState,
+    fold: (state, event) =>
+      event.type === 'compaction.settings.updated'
+        ? {
+            ...state,
+            compactionSettings: event.payload,
+            compactionSettingsId: event.id,
+          }
+        : event.type === 'model.choice.updated'
+          ? { ...state, modelChoice: event.payload }
+          : state,
+  },
+})
+
+export type AgentEvent = ContractEvent<typeof demoAgent.events>
+export type AgentState = typeof demoAgent.reducer.initialState
+
+export const modelSettings = (choice: ModelChoice): ModelSettings => ({
+  ...choice,
+  model: choice.model ?? agentModel,
+})
 
 export function compactionOptions(
   settings: CompactionSettings,

package/examples/playground/app/agent/new-agent-session.tsx

@@ -4,11 +4,12 @@ import type {
   KeyboardEvent as ReactKeyboardEvent,
   ReactNode,
 } from 'react'
-import { useState } from 'react'
+import { useId, useState } from 'react'
 import { useRouter } from 'next/navigation'
-import type { UIMessage } from 'ai'
 import { inputs } from 'experimental-a2/ai'
+import type { ModelChoice } from './model'
 import { agentClient } from './session'
+import { ModelInput } from './model-input'
 
 const REMINDER_PROMPT =
   'Set a reminder for yourself in 37 seconds to check checkout-api again.'
@@ -33,6 +34,8 @@ export function NewAgentSession({
   remindersEnabled: boolean
 }): ReactNode {
   const router = useRouter()
+  const promptId = useId()
+  const [choice, setChoice] = useState<ModelChoice>({})
   const [prompt, setPrompt] = useState(
     remindersEnabled ? REMINDER_PROMPT : INCIDENT_PROMPT,
   )
@@ -46,17 +49,21 @@ export function NewAgentSession({
     if (!text || submitting) return
 
     const agentId = crypto.randomUUID().slice(0, 8)
-    const message: UIMessage = {
-      id: crypto.randomUUID(),
-      role: 'user',
-      parts: [{ type: 'text', text }],
-    }
 
     setPrompt('')
     setSubmitting(true)
     setError(null)
     try {
-      await agentClient.session(agentId).push(...inputs.message(message))
+      await agentClient.session(agentId).push(
+        ...(Object.keys(choice).length === 0
+          ? []
+          : [{ type: 'model.choice.updated' as const, payload: choice }]),
+        ...inputs.message({
+          id: crypto.randomUUID(),
+          role: 'user',
+          parts: [{ type: 'text', text }],
+        }),
+      )
       router.push(`/agent/${agentId}`)
     } catch (err) {
       setPrompt((current) => (current === '' ? submittedPrompt : current))
@@ -75,17 +82,28 @@ export function NewAgentSession({
         </p>
       </div>
       <form className="agent-form" onSubmit={(event) => void start(event)}>
-        <label>
-          Message
-          <textarea
-            autoFocus
-            rows={3}
-            value={prompt}
-            onChange={(event) => setPrompt(event.target.value)}
-            onKeyDown={submitOnEnter}
-            disabled={submitting}
-          />
-        </label>
+        <div className="agent-message-field">
+          <label htmlFor={promptId}>Message</label>
+          <div className="agent-composer">
+            <textarea
+              id={promptId}
+              autoFocus
+              rows={3}
+              placeholder="Message the agent…"
+              value={prompt}
+              onChange={(event) => setPrompt(event.target.value)}
+              onKeyDown={submitOnEnter}
+              disabled={submitting}
+            />
+            <div className="agent-composer-toolbar">
+              <ModelInput
+                value={choice}
+                onChange={setChoice}
+                disabled={submitting}
+              />
+            </div>
+          </div>
+        </div>
         <div className="agent-form-actions">
           <button type="submit" disabled={submitting || !prompt.trim()}>
             {submitting ? 'Opening…' : 'Send to agent'}

package/examples/playground/app/agent/page.tsx

@@ -15,10 +15,10 @@ export default function AgentPage(): ReactNode {
       <NewAgentSession remindersEnabled={agentScheduler !== undefined} />
       <p className="hint">
         Each durable generation runs one AI SDK <code>streamText</code> step
-        with <code>openai/gpt-5.6-luna</code> through Vercel AI Gateway. Local
-        development needs Gateway credentials and a linked Vercel project for
-        Sandbox; Vercel deployments use their OIDC token. Reminder delivery also
-        needs the configured scheduler.
+        with your chosen model through Vercel AI Gateway. Local development
+        needs Gateway credentials and a linked Vercel project for Sandbox;
+        Vercel deployments use their OIDC token. Reminder delivery also needs
+        the configured scheduler.
       </p>
     </article>
   )

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

@@ -4,16 +4,13 @@ import { createHash } from 'node:crypto'
 import { Sandbox } from '@vercel/sandbox'
 import { tool } from 'ai'
 import { handlerContext, inputs } from 'experimental-a2/ai'
-import { createAgentServer } from 'experimental-a2/ai/server'
+import { agent } from 'experimental-a2/ai/server'
 import { vercelQueues } from 'experimental-a2/scheduler-vercel'
+import { otel } from 'experimental-a2/otel'
 import { z } from 'zod'
 import { store } from '@/lib/store'
-import {
-  agentModel,
-  compactionOptions,
-  compactionSettings,
-  demoAgent,
-} from './model'
+import { modelTelemetry, traceMetadata } from './telemetry'
+import { compactionOptions, demoAgent, modelSettings } from './model'
 
 const maxReminderDelaySeconds = 6 * 24 * 60 * 60
 const bashTimeoutMs = 120_000
@@ -132,13 +129,23 @@ export const agentScheduler =
     ? vercelQueues({ topic: 'a2-agent' })
     : undefined
 
-export const agentServer = createAgentServer({
+const telemetry = otel()
+
+export const agentServer = agent({
+  contract: demoAgent,
   ...(store ? { store } : {}),
   ...(agentScheduler ? { scheduler: agentScheduler } : {}),
-  agent: demoAgent,
-  model: agentModel,
-  compaction: async ({ session }) =>
-    compactionOptions((await session.state(compactionSettings)).state),
+  telemetry,
+  model: ({ state }) => modelSettings(state.modelChoice),
+  harness: {
+    type: 'ai-sdk',
+    messageMetadata: traceMetadata,
+    compaction: ({ state }) => compactionOptions(state.compactionSettings),
+    generation: () => ({
+      telemetry: modelTelemetry(),
+      toolApproval: { restartService: 'user-approval' },
+    }),
+  },
   tools,
   instructions: `You are an incident-response agent for the playground.
 When responding to an incident, inspect checkout-api before taking action. Its
@@ -154,7 +161,4 @@ it again.
 
 When the operator asks you to run a shell command, call bash. Make one bash call
 at a time and wait for its result before calling it again. Be concise.`,
-  generation: {
-    toolApproval: { restartService: 'user-approval' },
-  },
 })

package/examples/playground/app/agent/session.ts

@@ -1,13 +1,12 @@
 'use client'
 import { createClient } from 'experimental-a2/client'
-import { createReact } from 'experimental-a2/react'
-import { demoAgent } from './model'
+import type { UseSessionResult } from 'experimental-a2/react'
+import { demoAgent, type AgentState } from './model'
 
+/** Shared by the first push and the session page, so one live session serves both. */
 export const agentClient = createClient({
-  reducer: demoAgent.reducer,
+  contract: demoAgent,
   api: '/agent/events',
 })
 
-export const { SessionProvider, useSession } = createReact({
-  client: agentClient,
-})
+export type AgentSession = UseSessionResult<typeof demoAgent.events, AgentState>