experimental-a2 0.13.0 → 0.14.1

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

@@ -0,0 +1,289 @@
+'use client'
+
+import { useEffect, useRef, useState, type ReactNode } from 'react'
+import type { UIMessage } from 'ai'
+import type { InboxItem } from 'experimental-a2/ai'
+
+type QueueProps = {
+  items: InboxItem[]
+  paused: boolean
+  pendingEdits: readonly string[]
+  edit(message: UIMessage, revision: number): Promise<void>
+  move(inputId: string, beforeId: string | null): void
+  remove(inputId: string): Promise<void>
+  sendNow(inputId: string): Promise<void>
+}
+
+const queueIconPaths = {
+  edit: 'm15 5 4 4M4 20l4-1L20 7a2.8 2.8 0 0 0-4-4L4 15z',
+  up: 'm6 14 6-6 6 6',
+  down: 'm6 10 6 6 6-6',
+  remove: 'm6 6 12 12M6 18 18 6',
+  send: 'M4 12h15m-6-6 6 6-6 6',
+}
+
+function QueueIcon({ name }: { name: keyof typeof queueIconPaths }): ReactNode {
+  return (
+    <svg
+      width="14"
+      height="14"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.7"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <path d={queueIconPaths[name]} />
+    </svg>
+  )
+}
+
+function QueuedInput({
+  item,
+  position,
+  count,
+  edit,
+  moveUp,
+  moveDown,
+  remove,
+  sendNow,
+  paused,
+  pendingEdit,
+}: {
+  item: InboxItem
+  position: number
+  count: number
+  edit: QueueProps['edit']
+  moveUp(): void
+  moveDown(): void
+  remove: QueueProps['remove']
+  sendNow: QueueProps['sendNow']
+  paused: boolean
+  pendingEdit: boolean
+}): ReactNode {
+  const [draft, setDraft] = useState<{ text: string; revision: number } | null>(
+    null,
+  )
+  const [pending, setPending] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+  const editButton = useRef<HTMLButtonElement>(null)
+  const restoreFocus = useRef(false)
+  useEffect(() => {
+    if (draft === null && !pending && !pendingEdit && restoreFocus.current) {
+      if (document.activeElement === document.body) editButton.current?.focus()
+      restoreFocus.current = false
+    }
+  }, [draft, pending, pendingEdit])
+  const text = item.message.parts
+    .filter((part) => part.type === 'text')
+    .map((part) => part.text)
+    .join('\n')
+  const cancel = (): void => {
+    restoreFocus.current = true
+    setDraft(null)
+    setError(null)
+  }
+  const perform = async (action: () => Promise<void>): Promise<void> => {
+    if (pending) return
+    setPending(true)
+    setError(null)
+    try {
+      await action()
+    } catch (failure) {
+      setError(failure instanceof Error ? failure.message : String(failure))
+    } finally {
+      setPending(false)
+    }
+  }
+  const save = async (): Promise<void> => {
+    if (!draft || pendingEdit || !draft.text.trim()) return
+    await perform(async () => {
+      await edit(
+        { ...item.message, parts: [{ type: 'text', text: draft.text }] },
+        draft.revision,
+      )
+      cancel()
+    })
+  }
+  return (
+    <li className={`agent-queue-item${draft ? ' editing' : ''}`}>
+      <div className="agent-queue-row">
+        <span
+          className="agent-queue-number"
+          aria-label={`Queue position ${position + 1}`}
+        >
+          {position + 1}
+        </span>
+        <p className="agent-queue-text" title={text}>
+          {text || 'Message'}
+        </p>
+        <div className="agent-queue-actions">
+          <button
+            type="button"
+            className="agent-queue-send"
+            title={
+              paused
+                ? 'Send next · waits for Resume while paused'
+                : 'Send after current step'
+            }
+            aria-label={`Send queued message ${position + 1} after current step`}
+            disabled={
+              pending ||
+              pendingEdit ||
+              draft !== null ||
+              item.message.role !== 'user'
+            }
+            onClick={() => void perform(() => sendNow(item.id))}
+          >
+            <QueueIcon name="send" />
+          </button>
+          <button
+            ref={editButton}
+            type="button"
+            title={
+              pendingEdit ? 'Waiting for edit confirmation' : 'Edit message'
+            }
+            aria-label={`Edit queued message ${position + 1}`}
+            aria-expanded={draft !== null}
+            disabled={pending || pendingEdit}
+            onClick={() =>
+              draft ? cancel() : setDraft({ text, revision: item.revision })
+            }
+          >
+            <QueueIcon name="edit" />
+          </button>
+          <button
+            type="button"
+            title="Move up"
+            aria-label={`Move queued message ${position + 1} up`}
+            disabled={position === 0 || pending}
+            onClick={moveUp}
+          >
+            <QueueIcon name="up" />
+          </button>
+          <button
+            type="button"
+            title="Move down"
+            aria-label={`Move queued message ${position + 1} down`}
+            disabled={position === count - 1 || pending}
+            onClick={moveDown}
+          >
+            <QueueIcon name="down" />
+          </button>
+          <button
+            type="button"
+            className="agent-queue-remove"
+            title="Remove from queue"
+            aria-label={`Remove queued message ${position + 1}`}
+            disabled={pending || draft !== null}
+            onClick={() => void perform(() => remove(item.id))}
+          >
+            <QueueIcon name="remove" />
+          </button>
+        </div>
+      </div>
+      {error ? (
+        <p className="error agent-queue-error" role="alert">
+          {error}
+        </p>
+      ) : null}
+      {draft ? (
+        <form
+          className="agent-queue-editor"
+          onSubmit={(event) => {
+            event.preventDefault()
+            void save()
+          }}
+        >
+          <textarea
+            autoFocus
+            aria-label={`Edit text for queued message ${position + 1}`}
+            rows={2}
+            value={draft.text}
+            disabled={pending}
+            onChange={(event) =>
+              setDraft({ ...draft, text: event.target.value })
+            }
+            onKeyDown={(event) => {
+              if (event.nativeEvent.isComposing) return
+              if (event.key === 'Escape' && !pending) {
+                event.preventDefault()
+                cancel()
+              }
+              if (event.key === 'Enter' && (event.metaKey || event.ctrlKey)) {
+                event.preventDefault()
+                void save()
+              }
+            }}
+          />
+          <div className="agent-queue-editor-actions">
+            <span>⌘ / Ctrl + Enter to save</span>
+            <button
+              type="button"
+              className="secondary"
+              disabled={pending}
+              onClick={cancel}
+            >
+              Cancel
+            </button>
+            <button
+              type="submit"
+              disabled={pending || pendingEdit || !draft.text.trim()}
+            >
+              {pending ? 'Saving…' : 'Save'}
+            </button>
+          </div>
+        </form>
+      ) : null}
+    </li>
+  )
+}
+
+export function AgentQueue({
+  items,
+  paused,
+  pendingEdits,
+  edit,
+  move,
+  remove,
+  sendNow,
+}: QueueProps): ReactNode {
+  if (items.length === 0) return null
+  return (
+    <section className="agent-queue" aria-label="Queued messages">
+      <div className="agent-queue-header">
+        <h3>
+          Queued <span>{items.length}</span>
+        </h3>
+        <span className={`agent-queue-status${paused ? ' paused' : ''}`}>
+          {paused ? 'Paused' : 'Pending'}
+        </span>
+      </div>
+      <ol className="agent-queue-list">
+        {items.map((item, position) => (
+          <QueuedInput
+            key={item.id}
+            item={item}
+            position={position}
+            count={items.length}
+            edit={edit}
+            remove={remove}
+            sendNow={sendNow}
+            paused={paused}
+            pendingEdit={pendingEdits.includes(item.id)}
+            moveUp={() => {
+              const previous = items[position - 1]
+              if (previous) move(item.id, previous.id)
+            }}
+            moveDown={() => {
+              if (position < items.length - 1)
+                move(item.id, items[position + 2]?.id ?? null)
+            }}
+          />
+        ))}
+      </ol>
+    </section>
+  )
+}

package/examples/playground/app/agent/compaction-settings.test.ts

@@ -1,7 +1,12 @@
 import { expect, it } from 'vitest'
 import { createAgentServer } from 'experimental-a2/ai/server'
 import { memory } from 'experimental-a2/store-memory'
-import { compactionOptions, demoAgent, latestCompactionSettings } from './model'
+import {
+  compactionOptions,
+  compactionSettings,
+  demoAgent,
+  latestCompactionSettings,
+} from './model'
 import { updateCompactionSettings } from './compaction-settings'
 
 const request = (
@@ -47,7 +52,8 @@ it('saves session settings durably and idempotently without starting a turn', as
     agent: demoAgent,
     store: memory(),
     model: 'test/model',
-    compaction: ({ history }) => compactionOptions(history),
+    compaction: async ({ session }) =>
+      compactionOptions((await session.state(compactionSettings)).state),
     generate: () => {
       generations += 1
       return new ReadableStream({
@@ -76,8 +82,14 @@ it('saves session settings durably and idempotently without starting a turn', as
     mode: 'manual',
     thresholdTokens: 1,
   })
-  expect(compactionOptions(history)).toEqual({ thresholdTokens: 1 })
-  expect(compactionOptions(await server.session('other').history())).toEqual({})
+  expect(
+    compactionOptions((await session.state(compactionSettings)).state),
+  ).toEqual({ thresholdTokens: 1 })
+  expect(
+    compactionOptions(
+      (await server.session('other').state(compactionSettings)).state,
+    ),
+  ).toEqual({})
   expect(generations).toBe(0)
 
   await updateCompactionSettings({
@@ -85,13 +97,17 @@ it('saves session settings durably and idempotently without starting a turn', as
     sessionId: session.id,
     append: (event) => session.append(event),
   })
-  expect(compactionOptions(await session.history())).toBe(false)
+  expect(
+    compactionOptions((await session.state(compactionSettings)).state),
+  ).toBe(false)
   await updateCompactionSettings({
     request: request({ mode: 'automatic' }),
     sessionId: session.id,
     append: (event) => session.append(event),
   })
-  expect(compactionOptions(await session.history())).toEqual({})
+  expect(
+    compactionOptions((await session.state(compactionSettings)).state),
+  ).toEqual({})
 })
 
 it.each([0, -1, 1.5, Number.MAX_SAFE_INTEGER + 1, '1', null])(

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

@@ -37,10 +37,19 @@ export function latestCompactionSettings(history: readonly AgentEvent[]): {
     : { settings: automatic, id: 'default' }
 }
 
+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 function compactionOptions(
-  history: readonly AgentEvent[],
+  settings: CompactionSettings,
 ): AutomaticCompaction | false {
-  const { settings } = latestCompactionSettings(history)
   return settings.mode === 'disabled'
     ? false
     : settings.mode === 'manual'

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

@@ -8,7 +8,12 @@ import { createAgentServer } from 'experimental-a2/ai/server'
 import { vercelQueues } from 'experimental-a2/scheduler-vercel'
 import { z } from 'zod'
 import { store } from '@/lib/store'
-import { agentModel, compactionOptions, demoAgent } from './model'
+import {
+  agentModel,
+  compactionOptions,
+  compactionSettings,
+  demoAgent,
+} from './model'
 
 const maxReminderDelaySeconds = 6 * 24 * 60 * 60
 const bashTimeoutMs = 120_000
@@ -132,7 +137,8 @@ export const agentServer = createAgentServer({
   ...(agentScheduler ? { scheduler: agentScheduler } : {}),
   agent: demoAgent,
   model: agentModel,
-  compaction: ({ history }) => compactionOptions(history),
+  compaction: async ({ session }) =>
+    compactionOptions((await session.state(compactionSettings)).state),
   tools,
   instructions: `You are an incident-response agent for the playground.
 When responding to an incident, inspect checkout-api before taking action. Its

package/examples/playground/app/chat/[chatId]/chat-client.tsx

@@ -539,22 +539,12 @@ export function ChatClient({ chatId }: { chatId: string }): ReactNode {
   }
 
   const stopAgent = async (): Promise<void> => {
-    if (!activeResponseId) return
-    const target = state.ai.activeGeneration
-      ? { generationId: state.ai.activeGeneration.generationId }
-      : runningTool
-        ? { generationId: runningTool.generationId }
-        : state.ai.activeRequestId
-          ? { requestId: state.ai.activeRequestId }
-          : null
-    if (target === null) return
+    if (!state.ai.active) return
     setError(null)
     try {
       await push(
-        ...inputs.interrupt({
-          messageId: activeResponseId,
-          ...target,
-          reason: 'a chat participant stopped the agent',
+        ...inputs.stop({
+          turnId: state.ai.active.turnId,
           lastSeenIndex: index,
         }),
       )

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

@@ -164,7 +164,7 @@ export const chatAgent = agent<ChatAgentMessage, typeof chatEvents>({
   name: 'chat',
   events: chatEvents,
   messageSchema: chatMessageSchema,
-  reducerName: 'a2.playground.chat.ai.v1',
+  reducerName: 'a2.playground.chat.ai.v3',
 })
 
 export const chat = chatAgent.contract
@@ -208,7 +208,7 @@ const initialChatState: ChatState = {
 
 export const chatReducer = chat
   .reducer({
-    name: 'a2.playground.chat.v1',
+    name: 'a2.playground.chat.v3',
     initialState: initialChatState,
   })
   .fold((state, event) => {

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

@@ -21,16 +21,13 @@ const tools = {
     inputSchema: chatPostInputSchema,
     execute: async ({ message }, { toolCallId }) => {
       const context = handlerContext(chatAgent)
-      if (context.event.type !== 'ai.tool.called') {
-        throw new Error('The chat post tool must execute automatically')
-      }
       context.signal.throwIfAborted()
       await context.session.append('post', {
         type: 'agent.message.posted',
         payload: {
           message,
-          generationId: context.event.payload.generationId,
-          responseMessageId: context.event.payload.messageId,
+          generationId: context.event.payload.call.generationId,
+          responseMessageId: context.event.payload.call.messageId,
           toolCallId,
         },
       })
@@ -118,23 +115,33 @@ export const authorizeChatOperation = (
       return false
     }
     return !(
-      event.type === 'ai.approval.responded' ||
-      event.type === 'ai.input.responded' ||
-      event.type === 'ai.message.interrupted' ||
-      event.type === 'ai.retry.requested'
+      event.type === 'ai.control.requested' &&
+      typeof event.payload === 'object' &&
+      event.payload !== null &&
+      'action' in event.payload &&
+      typeof event.payload.action === 'string' &&
+      [
+        'approval',
+        'input',
+        'interrupt',
+        'stop',
+        'retry',
+        'pause',
+        'resume',
+      ].includes(event.payload.action)
     )
   })
   return rejected === undefined
 }
 
-const toolCalledHandler = aiHandlers['ai.tool.called']
-if (toolCalledHandler === undefined) {
-  throw new Error('A2 AI handlers must include ai.tool.called')
+const toolExecutionHandler = aiHandlers['ai.tool.execution.requested']
+if (toolExecutionHandler === undefined) {
+  throw new Error('A2 AI handlers must include ai.tool.execution.requested')
 }
-const serializedToolCalledHandler =
-  typeof toolCalledHandler === 'function'
-    ? { handler: toolCalledHandler, lane: 'a2.chat.agent-tools' }
-    : { ...toolCalledHandler, lane: 'a2.chat.agent-tools' }
+const serializedToolExecutionHandler =
+  typeof toolExecutionHandler === 'function'
+    ? { handler: toolExecutionHandler, lane: 'a2.chat.agent-tools' }
+    : { ...toolExecutionHandler, lane: 'a2.chat.agent-tools' }
 
 export const chatScheduler =
   process.env.VERCEL || process.env.A2_QUEUES
@@ -147,7 +154,7 @@ export const chatServer = createServer({
   contract: chatAgent.contract,
   handlers: {
     ...aiHandlers,
-    'ai.tool.called': serializedToolCalledHandler,
+    'ai.tool.execution.requested': serializedToolExecutionHandler,
     'message.sent': {
       lane: 'a2.chat.ingress',
       handler: async (context) => {

package/examples/playground/app/globals.css

@@ -1799,6 +1799,185 @@ button.danger {
   flex: 0 0 auto;
 }
 
+.agent-queue {
+  margin: 0 1rem 0.85rem;
+  border: 1px solid var(--line);
+  border-radius: 9px;
+  background: var(--bg);
+  overflow: hidden;
+}
+
+.agent-queue-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.75rem;
+  padding: 0.55rem 0.8rem;
+  border-bottom: 1px solid var(--line);
+}
+
+.agent-queue-header h3 {
+  display: flex;
+  align-items: center;
+  gap: 0.45rem;
+  margin: 0;
+  color: var(--muted);
+  font-size: 0.75rem;
+  font-weight: 600;
+}
+
+.agent-queue-header h3 span {
+  min-width: 1.2rem;
+  padding: 0 0.3rem;
+  border-radius: 4px;
+  background: var(--line);
+  text-align: center;
+  font-size: 0.68rem;
+  font-variant-numeric: tabular-nums;
+}
+
+.agent-queue-status {
+  color: var(--muted);
+  font-size: 0.7rem;
+}
+
+.agent-queue-status.paused {
+  color: #885b12;
+}
+
+.agent-queue-list {
+  max-height: 17rem;
+  overflow-y: auto;
+  overscroll-behavior: contain;
+  list-style: none;
+  margin: 0;
+  padding: 0.15rem 0;
+}
+
+.agent-queue-item + .agent-queue-item {
+  border-top: 1px solid var(--line);
+}
+
+.agent-queue-row {
+  display: grid;
+  grid-template-columns: 1.25rem minmax(0, 1fr) auto;
+  align-items: center;
+  gap: 0.5rem;
+  min-height: 2.7rem;
+  padding: 0.25rem 0.55rem 0.25rem 0.8rem;
+}
+
+.agent-queue-number {
+  color: var(--muted);
+  font-size: 0.7rem;
+  font-variant-numeric: tabular-nums;
+}
+
+.agent-queue-text {
+  margin: 0;
+  overflow: hidden;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+  font-size: 0.83rem;
+}
+
+.agent-queue-actions {
+  display: flex;
+  gap: 0.1rem;
+}
+
+.agent-queue-actions button {
+  display: grid;
+  place-items: center;
+  width: 1.9rem;
+  height: 1.9rem;
+  padding: 0;
+  border: 0;
+  border-radius: 5px;
+  background: transparent;
+  color: var(--muted);
+}
+
+.agent-queue-actions button:hover:not(:disabled),
+.agent-queue-actions button[aria-expanded='true'] {
+  background: var(--line);
+  color: var(--ink);
+  filter: none;
+}
+
+.agent-queue-actions button:disabled {
+  opacity: 0.22;
+}
+
+.agent-queue-actions .agent-queue-send {
+  color: var(--accent);
+}
+
+.agent-queue-actions .agent-queue-remove:hover:not(:disabled) {
+  background: #f8e8e5;
+  color: var(--danger);
+}
+
+.agent-queue-error {
+  margin: 0;
+  padding: 0 0.75rem 0.65rem 2.55rem;
+  font-size: 0.75rem;
+}
+
+.agent-queue-item.editing {
+  background: var(--surface);
+}
+
+.agent-queue-editor {
+  gap: 0.45rem;
+  margin: 0;
+  padding: 0 0.75rem 0.65rem 2.55rem;
+  border: 0;
+  border-radius: 0;
+}
+
+.agent-queue-editor textarea {
+  width: 100%;
+  min-width: 0;
+  resize: vertical;
+  font-size: 0.83rem;
+  line-height: 1.5;
+}
+
+.agent-queue-editor-actions {
+  display: flex;
+  align-items: center;
+  justify-content: flex-end;
+  gap: 0.35rem;
+}
+
+.agent-queue-editor-actions span {
+  margin-right: auto;
+  color: var(--muted);
+  font-size: 0.65rem;
+}
+
+.agent-queue-editor-actions button {
+  padding: 0.3rem 0.6rem;
+  font-size: 0.72rem;
+}
+
+@media (pointer: coarse) {
+  .agent-queue-actions button {
+    width: 2.25rem;
+    height: 2.5rem;
+  }
+}
+
+@media (max-width: 420px) {
+  .agent-queue-editor {
+    padding-left: 0.75rem;
+  }
+  .agent-queue-editor-actions span {
+    display: none;
+  }
+}
+
 .agent-form {
   margin: 0;
   padding: 1rem;