experimental-a2 0.16.1 → 0.18.0

package/examples/playground/app/agent/[agentId]/agent-client.tsx

@@ -4,20 +4,21 @@ import type {
   KeyboardEvent as ReactKeyboardEvent,
   ReactNode,
 } from 'react'
-import { useEffect, useRef, useState } from 'react'
+import { useEffect, useId, useRef, useState } from 'react'
 import type { UIMessage } from 'ai'
-import {
-  inputs,
-  type ControlCommand,
-  type PendingApproval,
-} from 'experimental-a2/ai'
+import { isCompactionPart } from 'experimental-a2/ai'
+import { useAgent, type AgentIndicator } from 'experimental-a2/ai/react'
+import type { InitialSnapshot } from 'experimental-a2'
 import { ActivityFeed } from '@/app/components/activity-feed'
 import { ConnectionPill } from '@/app/components/connection-pill'
-import { useSession } from '../session'
-import { compactionTimeline } from '../compaction-timeline'
+import { agentClient } from '../session'
+import type { AgentState } from '../model'
+import { ModelInput } from '../model-input'
 import { CompactionEvent } from './compaction-event'
 import { CompactionPanel } from './compaction-panel'
 import { AgentQueue } from './agent-queue'
+import { CommandReceipt } from './command-receipt'
+import { traceUrl } from '../trace'
 
 type MessagePart = UIMessage['parts'][number]
 type ToolPartView = {
@@ -110,34 +111,34 @@ function ToolCard({ part }: { part: ToolPartView }): ReactNode {
 
 function MessagePartView({ part }: { part: MessagePart }): ReactNode {
   if (part.type === 'text') return part.text ? <p>{part.text}</p> : null
+  if (isCompactionPart(part)) return <CompactionEvent data={part.data} />
   const tool = toolPartView(part)
   if (tool) return <ToolCard part={tool} />
   return null
 }
 
-const hasVisibleParts = (message: UIMessage): boolean =>
-  message.parts.some(
-    (part) =>
-      (part.type === 'text' && part.text.length > 0) ||
-      toolPartView(part) !== null,
-  )
-
-function Thinking({ starting = false }: { starting?: boolean }): ReactNode {
+function Thinking({
+  indicator,
+}: {
+  indicator: Exclude<AgentIndicator, null>
+}): ReactNode {
   return (
     <p className="agent-thinking" role="status">
       <span aria-hidden="true" />
-      {starting ? 'Starting…' : 'Thinking…'}
+      {indicator === 'starting' ? 'Starting…' : 'Thinking…'}
     </p>
   )
 }
 
 function AgentMessage({
   message,
-  thinking,
+  indicator,
 }: {
   message: UIMessage
-  thinking: boolean
+  indicator: AgentIndicator
 }): ReactNode {
+  const traceHref =
+    message.role === 'assistant' ? traceUrl(message.metadata) : undefined
   const role =
     message.role === 'user'
       ? message.id.startsWith('reminder:')
@@ -152,7 +153,17 @@ function AgentMessage({
         {message.parts.map((part, partIndex) => (
           <MessagePartView key={`${message.id}:${partIndex}`} part={part} />
         ))}
-        {thinking ? <Thinking /> : null}
+        {indicator ? <Thinking indicator={indicator} /> : null}
+        {traceHref ? (
+          <a
+            className="agent-trace"
+            href={traceHref}
+            target="_blank"
+            rel="noreferrer"
+          >
+            View trace ↗
+          </a>
+        ) : null}
       </div>
     </div>
   )
@@ -170,27 +181,41 @@ function submitOnEnter(event: ReactKeyboardEvent<HTMLTextAreaElement>): void {
   event.currentTarget.form?.requestSubmit()
 }
 
-export function AgentClient({ agentId }: { agentId: string }): ReactNode {
-  const { state, push, events, index, connection } = useSession()
-  const { inbox } = state
+export function AgentClient({
+  agentId,
+  initial,
+}: {
+  agentId: string
+  initial: InitialSnapshot<AgentState>
+}): ReactNode {
+  const agent = useAgent({ client: agentClient, id: agentId, initial })
+  const { state, messages, indicator } = agent
+  const promptId = useId()
   const promptRef = useRef<HTMLTextAreaElement>(null)
   const [prompt, setPrompt] = useState('')
   const [error, setError] = useState<string | null>(null)
   const [responding, setResponding] = useState(false)
-
-  const generating = state.status === 'generating'
-  const compacting = state.compaction?.status === 'running'
+  const [stopCommandIds, setStopCommandIds] = useState<string[]>([])
   const canSend = state.status !== 'closed'
-  const responseMessageId =
-    state.activeGeneration?.responseMessageId ??
-    state.activeResponseMessageId ??
-    state.activeProjection?.responseMessageId
-  const timeline = compactionTimeline({ state, events })
+  // The indicator joins the response it belongs to, or opens a row for it.
+  const thinking =
+    indicator === 'starting' || indicator === 'thinking' ? indicator : null
+  const last = messages.at(-1)
+  const joinsLast = thinking !== null && last?.role === 'assistant'
 
   useEffect(() => {
     if (canSend) promptRef.current?.focus({ preventScroll: true })
   }, [canSend])
 
+  const run = async (action: () => Promise<unknown>): Promise<void> => {
+    setError(null)
+    try {
+      await action()
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err))
+    }
+  }
+
   const send = async (event?: FormEvent, steer = false): Promise<void> => {
     event?.preventDefault()
     const submittedPrompt = prompt
@@ -200,77 +225,22 @@ export function AgentClient({ agentId }: { agentId: string }): ReactNode {
     promptRef.current?.focus({ preventScroll: true })
     setError(null)
     try {
-      const message: UIMessage = {
-        id: crypto.randomUUID(),
-        role: 'user',
-        parts: [{ type: 'text', text }],
-      }
-      await push(
-        ...(steer && state.active
-          ? inputs.steer({
-              turnId: state.active.turnId,
-              message,
-            })
-          : inputs.message(message)),
-      )
+      await (steer ? agent.steer(text) : agent.sendMessage(text))
     } catch (err) {
       setPrompt((current) => (current === '' ? submittedPrompt : current))
       setError(err instanceof Error ? err.message : String(err))
     }
   }
 
-  const answerApproval = async ({
-    approval,
-    approved,
-  }: {
-    approval: PendingApproval
-    approved: boolean
-  }): Promise<void> => {
-    setResponding(true)
-    setError(null)
-    try {
-      await push(
-        ...inputs.approval({
-          requestId: approval.requestId,
-          messageId: approval.messageId,
-          generationId: approval.generationId,
-          approvalId: approval.approvalId,
-          approved,
-          ...(!approved ? { reason: 'operator denied the restart' } : {}),
-        }),
-      )
-    } catch (err) {
-      setError(err instanceof Error ? err.message : String(err))
-    } finally {
-      setResponding(false)
-    }
-  }
-
-  const command = async (
-    commands: {
-      type: 'ai.control.requested'
-      payload: ControlCommand
-      id?: string
-    }[],
-  ): Promise<void> => {
-    setError(null)
-    try {
-      await push(...commands)
-    } catch (err) {
-      setError(err instanceof Error ? err.message : String(err))
-    }
+  const stop = async (): Promise<void> => {
+    const stops = await agent.stop()
+    setStopCommandIds((ids) => [...ids, ...stops.map((event) => event.id)])
   }
 
-  const stop = async (): Promise<void> => {
-    if (!state.active) return
-    setError(null)
-    try {
-      await push(
-        ...inputs.stop({ turnId: state.active.turnId, lastSeenIndex: index }),
-      )
-    } catch (err) {
-      setError(err instanceof Error ? err.message : String(err))
-    }
+  const answer = async (action: () => Promise<unknown>): Promise<void> => {
+    setResponding(true)
+    await run(action)
+    setResponding(false)
   }
 
   return (
@@ -279,62 +249,44 @@ export function AgentClient({ agentId }: { agentId: string }): ReactNode {
         <h1>
           Agent <code>{agentId}</code>
         </h1>
-        <ConnectionPill connection={connection} />
+        <ConnectionPill connection={agent.connection} />
         <span
-          className={`badge${generating ? ' live' : ''}${
-            state.status === 'waiting' ? ' waiting' : ''
-          }${state.status === 'failed' ? ' cut' : ''}`}
+          className={`badge${agent.status === 'generating' ? ' live' : ''}${
+            agent.status === 'waiting' ? ' waiting' : ''
+          }${agent.status === 'failed' ? ' cut' : ''}`}
         >
-          {state.starting
+          {indicator === 'starting'
             ? 'starting…'
-            : compacting
+            : indicator === 'compacting'
               ? 'compacting…'
-              : STATUS_LABEL[state.status]}
+              : STATUS_LABEL[agent.status]}
         </span>
       </header>
 
-      <CompactionPanel agentId={agentId} state={state} events={events} />
+      <CompactionPanel key={agentId} session={agent} />
 
       <section className="agent-conversation" aria-label="Conversation">
         <div className="agent-transcript" aria-live="polite">
-          {timeline.length === 0 ? (
+          {messages.length === 0 && thinking === null ? (
             <p className="agent-empty">
               Ask the agent to investigate an incident, run a Bash command, or
               set a reminder for itself. Its tools and decisions will appear
               here as they enter the log.
             </p>
           ) : (
-            timeline.map((entry) =>
-              entry.type === 'compaction' ? (
-                <CompactionEvent key={entry.id} entry={entry} />
-              ) : (
-                <AgentMessage
-                  key={entry.id}
-                  message={entry.message}
-                  thinking={
-                    generating &&
-                    !state.starting &&
-                    !compacting &&
-                    entry.lastSegment &&
-                    entry.message.id ===
-                      state.activeGeneration?.responseMessageId &&
-                    !hasVisibleParts(entry.message)
-                  }
-                />
-              ),
-            )
+            messages.map((message) => (
+              <AgentMessage
+                key={message.id}
+                message={message}
+                indicator={joinsLast && message === last ? thinking : null}
+              />
+            ))
           )}
-          {state.starting ||
-          (generating &&
-            !compacting &&
-            state.messages.at(-1)?.role === 'user' &&
-            !state.messages.some(
-              (message) => message.id === responseMessageId,
-            )) ? (
+          {thinking !== null && !joinsLast ? (
             <div className="agent-message assistant">
               <span className="agent-role">Agent</span>
               <div>
-                <Thinking starting={state.starting} />
+                <Thinking indicator={thinking} />
               </div>
             </div>
           ) : null}
@@ -354,9 +306,7 @@ export function AgentClient({ agentId }: { agentId: string }): ReactNode {
               <button
                 type="button"
                 disabled={responding}
-                onClick={() =>
-                  void answerApproval({ approval, approved: true })
-                }
+                onClick={() => void answer(() => agent.approve(approval))}
               >
                 Approve restart
               </button>
@@ -365,7 +315,11 @@ export function AgentClient({ agentId }: { agentId: string }): ReactNode {
                 className="secondary"
                 disabled={responding}
                 onClick={() =>
-                  void answerApproval({ approval, approved: false })
+                  void answer(() =>
+                    agent.deny(approval, {
+                      reason: 'operator denied the restart',
+                    }),
+                  )
                 }
               >
                 Deny
@@ -381,45 +335,52 @@ export function AgentClient({ agentId }: { agentId: string }): ReactNode {
         ) : null}
 
         <AgentQueue
-          items={inbox.items}
-          paused={inbox.paused}
-          remove={async (inputId) => {
-            await command(inputs.queue.remove({ inputId }))
-          }}
-          sendNow={async (inputId) => {
-            await command(
-              inputs.queue.sendNow({
-                inputId,
-                turnId: state.active?.turnId ?? null,
-              }),
-            )
-          }}
+          items={state.inbox.items}
+          paused={state.inbox.paused}
+          remove={(inputId) => run(() => agent.queue.remove(inputId))}
+          sendNow={(inputId) => run(() => agent.queue.sendNow(inputId))}
           edit={async (message) => {
-            await push(...inputs.queue.edit({ message }))
+            await agent.queue.edit(message)
           }}
           move={(inputId, beforeId) =>
-            void command(inputs.queue.move({ inputId, beforeId }))
+            void run(() => agent.queue.move({ inputId, beforeId }))
           }
         />
-        {state.receipt?.outcome === 'rejected' ? (
-          <p className="error" role="alert">
-            Command rejected: {state.receipt.reason}. Refresh the input or turn
-            you want to change.
-          </p>
-        ) : null}
+        <CommandReceipt
+          receipt={state.receipt}
+          stopCommandIds={stopCommandIds}
+        />
 
         <form className="agent-form" onSubmit={(event) => void send(event)}>
-          <label>
-            Message
-            <textarea
-              ref={promptRef}
-              rows={3}
-              value={prompt}
-              onChange={(event) => setPrompt(event.target.value)}
-              onKeyDown={submitOnEnter}
-              disabled={!canSend}
-            />
-          </label>
+          <div className="agent-message-field">
+            <label htmlFor={promptId}>Message</label>
+            <div className="agent-composer">
+              <textarea
+                id={promptId}
+                ref={promptRef}
+                rows={3}
+                placeholder="Message the agent…"
+                value={prompt}
+                onChange={(event) => setPrompt(event.target.value)}
+                onKeyDown={submitOnEnter}
+                disabled={!canSend}
+              />
+              <div className="agent-composer-toolbar">
+                <ModelInput
+                  value={state.modelChoice}
+                  onChange={(next) =>
+                    void run(() =>
+                      agent.push({
+                        type: 'model.choice.updated',
+                        payload: next,
+                      }),
+                    )
+                  }
+                  disabled={!canSend}
+                />
+              </div>
+            </div>
+          </div>
           <div className="agent-form-actions">
             <button type="submit" disabled={!canSend || !prompt.trim()}>
               Send to agent
@@ -428,12 +389,13 @@ export function AgentClient({ agentId }: { agentId: string }): ReactNode {
               type="button"
               className="danger"
               disabled={!state.active}
-              onClick={() => void stop()}
+              onClick={() => void run(stop)}
             >
               Stop
             </button>
             <button
               type="button"
+              className="secondary"
               disabled={!canSend || !prompt.trim()}
               onClick={() => void send(undefined, true)}
             >
@@ -442,7 +404,8 @@ export function AgentClient({ agentId }: { agentId: string }): ReactNode {
             {state.inbox.paused ? (
               <button
                 type="button"
-                onClick={() => void command(inputs.resume())}
+                className="secondary"
+                onClick={() => void run(agent.resume)}
               >
                 Resume
               </button>
@@ -450,15 +413,17 @@ export function AgentClient({ agentId }: { agentId: string }): ReactNode {
               <>
                 <button
                   type="button"
+                  className="secondary"
                   onClick={() =>
-                    void command(inputs.pause({ when: 'after-turn' }))
+                    void run(() => agent.pause({ when: 'after-turn' }))
                   }
                 >
                   Pause after turn
                 </button>
                 <button
                   type="button"
-                  onClick={() => void command(inputs.pause({ when: 'now' }))}
+                  className="secondary"
+                  onClick={() => void run(() => agent.pause({ when: 'now' }))}
                 >
                   Pause now
                 </button>
@@ -469,12 +434,17 @@ export function AgentClient({ agentId }: { agentId: string }): ReactNode {
       </section>
       {error ? <p className="error">{error}</p> : null}
       <p className="hint">
-        The browser only appends inputs. <code>createAgentServer()</code>{' '}
-        records the generation, progress snapshots, tool activity, and pause;
-        approving or delivering a reminder wakes the same durable session.
+        The browser only appends inputs. <code>agent()</code> records the
+        generation, progress snapshots, tool activity, and pause; approving or
+        delivering a reminder wakes the same durable session.
       </p>
 
-      <ActivityFeed events={events} index={index} />
+      <ActivityFeed
+        events={agent.events}
+        index={agent.index}
+        history={agent.history}
+        loadHistory={agent.loadHistory}
+      />
     </article>
   )
 }

package/examples/playground/app/agent/[agentId]/command-receipt.test.tsx

@@ -0,0 +1,65 @@
+// @vitest-environment jsdom
+import { cleanup, render, screen } from '@testing-library/react'
+import { afterEach, expect, it } from 'vitest'
+import { CommandReceipt } from './command-receipt'
+
+afterEach(cleanup)
+
+it('reports a Stop that arrived after its turn finished as a status', () => {
+  render(
+    <CommandReceipt
+      receipt={{
+        commandId: 'stop-1',
+        outcome: 'rejected',
+        reason: 'stale-turn',
+      }}
+      stopCommandIds={['stop-1']}
+    />,
+  )
+  expect(screen.getByRole('status').textContent).toBe(
+    'That turn had already finished.',
+  )
+  expect(screen.queryByRole('alert')).toBeNull()
+})
+
+it('keeps other rejections as alerts', () => {
+  render(
+    <CommandReceipt
+      receipt={{
+        commandId: 'send-now-1',
+        outcome: 'rejected',
+        reason: 'stale-turn',
+      }}
+      stopCommandIds={['stop-1']}
+    />,
+  )
+  expect(screen.getByRole('alert').textContent).toContain(
+    'Command rejected: stale-turn.',
+  )
+})
+
+it('renders nothing for applied commands', () => {
+  const { container } = render(
+    <CommandReceipt
+      receipt={{ commandId: 'stop-1', outcome: 'applied' }}
+      stopCommandIds={['stop-1']}
+    />,
+  )
+  expect(container.textContent).toBe('')
+})
+
+it('reports an earlier Stop after a later Stop was issued', () => {
+  render(
+    <CommandReceipt
+      receipt={{
+        commandId: 'stop-1',
+        outcome: 'rejected',
+        reason: 'stale-turn',
+      }}
+      stopCommandIds={['stop-1', 'stop-2']}
+    />,
+  )
+  expect(screen.getByRole('status').textContent).toBe(
+    'That turn had already finished.',
+  )
+})

package/examples/playground/app/agent/[agentId]/command-receipt.tsx

@@ -0,0 +1,27 @@
+import type { ControlReceipt } from 'experimental-a2/ai'
+
+export function CommandReceipt({
+  receipt,
+  stopCommandIds,
+}: {
+  receipt: ControlReceipt | null
+  stopCommandIds: readonly string[]
+}) {
+  if (receipt?.outcome !== 'rejected') return null
+  if (
+    receipt.reason === 'stale-turn' &&
+    stopCommandIds.includes(receipt.commandId)
+  ) {
+    return (
+      <p className="hint" role="status">
+        That turn had already finished.
+      </p>
+    )
+  }
+  return (
+    <p className="error" role="alert">
+      Command rejected: {receipt.reason}. Refresh the input or turn you want to
+      change.
+    </p>
+  )
+}

package/examples/playground/app/agent/[agentId]/compaction-event.tsx

@@ -1,38 +1,39 @@
 import type { ReactNode } from 'react'
-import { formatActivityTime } from '@/app/components/activity-feed'
-import type { CompactionEntry } from '../compaction-timeline'
+import type { CompactionPartData } from 'experimental-a2/ai'
+
+const number = new Intl.NumberFormat('en-US')
 
 export function CompactionEvent({
-  entry,
+  data,
 }: {
-  entry: CompactionEntry
+  data: CompactionPartData
 }): ReactNode {
-  const { event, running, outcome } = entry
-  const completed = event.type === 'ai.compaction.completed'
-  const label = completed
-    ? 'Context compacted'
-    : running
-      ? 'Compacting…'
-      : 'Compaction did not complete'
+  const { status, summary, inputTokens, thresholdTokens } = data
+  const running = status === 'running'
+  const label =
+    status === 'completed'
+      ? 'Context compacted'
+      : running
+        ? 'Compacting…'
+        : 'Compaction did not complete'
+  const hint = [
+    inputTokens === undefined || thresholdTokens === undefined
+      ? undefined
+      : `${number.format(inputTokens)} tokens against a ${number.format(thresholdTokens)} token threshold`,
+    status === 'failed' || status === 'interrupted'
+      ? `Generation ${status}`
+      : undefined,
+  ]
+    .filter((line) => line !== undefined)
+    .join(' · ')
 
   return (
     <details className="agent-compaction-event">
       <summary>
         <span role={running ? 'status' : undefined}>{label}</span>
-        <time dateTime={event.createdAt.toISOString()}>
-          {formatActivityTime(event.createdAt)}
-        </time>
       </summary>
-      <p className="hint">
-        Event #{event.index} ·{' '}
-        {event.payload.throughIndex === undefined
-          ? `Through message ${event.payload.throughMessageId}`
-          : `Summarized through event #${event.payload.throughIndex}`}
-        {outcome === undefined ? null : ` · Generation ${outcome}`}
-      </p>
-      {completed && event.payload.summary ? (
-        <pre>{event.payload.summary}</pre>
-      ) : null}
+      {hint ? <p className="hint">{hint}</p> : null}
+      {summary ? <pre>{summary}</pre> : null}
     </details>
   )
 }