experimental-a2 0.8.0 → 0.9.0

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

@@ -0,0 +1,376 @@
+'use client'
+import type {
+  FormEvent,
+  KeyboardEvent as ReactKeyboardEvent,
+  ReactNode,
+} from 'react'
+import { useEffect, useRef, useState } from 'react'
+import type { UIMessage } from 'ai'
+import { inputs } from 'experimental-a2/ai'
+import { ActivityFeed } from '@/app/components/activity-feed'
+import { ConnectionPill } from '@/app/components/connection-pill'
+import { useSession } from '../session'
+
+type MessagePart = UIMessage['parts'][number]
+type ToolPartView = {
+  name: string
+  state: string
+  input: unknown
+  output?: unknown
+  approved?: boolean
+}
+
+const STATUS_LABEL = {
+  idle: 'idle',
+  generating: 'working…',
+  waiting: 'approval needed',
+  failed: 'failed',
+  closed: 'closed',
+} as const
+
+const toolTitle = (name: string): string =>
+  name === 'inspectService'
+    ? 'Inspect service'
+    : name === 'restartService'
+      ? 'Restart service'
+      : name === 'setReminder'
+        ? 'Set reminder'
+        : name === 'bash'
+          ? 'Bash'
+          : name
+
+const toolState = (part: ToolPartView): string => {
+  switch (part.state) {
+    case 'approval-requested':
+      return 'waiting for approval'
+    case 'approval-responded':
+      return part.approved ? 'approved' : 'denied'
+    case 'output-available':
+      return 'completed'
+    case 'output-error':
+      return 'failed'
+    case 'output-denied':
+      return 'denied'
+    default:
+      return 'running'
+  }
+}
+
+const toolPartView = (part: MessagePart): ToolPartView | null => {
+  if (part.type !== 'dynamic-tool' && !part.type.startsWith('tool-'))
+    return null
+  const candidate = part as unknown as Record<string, unknown>
+  const name =
+    part.type === 'dynamic-tool'
+      ? candidate['toolName']
+      : part.type.slice('tool-'.length)
+  if (typeof name !== 'string' || typeof candidate['state'] !== 'string') {
+    return null
+  }
+  const approval = candidate['approval']
+  return {
+    name,
+    state: candidate['state'],
+    input: candidate['input'],
+    ...(candidate['output'] === undefined
+      ? {}
+      : { output: candidate['output'] }),
+    ...(typeof approval === 'object' &&
+    approval !== null &&
+    'approved' in approval &&
+    typeof approval.approved === 'boolean'
+      ? { approved: approval.approved }
+      : {}),
+  }
+}
+
+function ToolCard({ part }: { part: ToolPartView }): ReactNode {
+  return (
+    <div className={`tool-card ${part.state}`}>
+      <div>
+        <strong>{toolTitle(part.name)}</strong>
+        <span>{toolState(part)}</span>
+      </div>
+      <code>{JSON.stringify(part.input)}</code>
+      {part.output === undefined ? null : (
+        <pre>{JSON.stringify(part.output, null, 2)}</pre>
+      )}
+    </div>
+  )
+}
+
+function MessagePartView({ part }: { part: MessagePart }): ReactNode {
+  if (part.type === 'text') return part.text ? <p>{part.text}</p> : null
+  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(): ReactNode {
+  return (
+    <p className="agent-thinking" role="status">
+      <span aria-hidden="true" />
+      Thinking…
+    </p>
+  )
+}
+
+function AgentMessage({
+  message,
+  thinking,
+}: {
+  message: UIMessage
+  thinking: boolean
+}): ReactNode {
+  const role =
+    message.role === 'user'
+      ? message.id.startsWith('reminder:')
+        ? 'Reminder'
+        : 'You'
+      : 'Agent'
+
+  return (
+    <div className={`agent-message ${message.role}`}>
+      <span className="agent-role">{role}</span>
+      <div>
+        {message.parts.map((part, partIndex) => (
+          <MessagePartView key={`${message.id}:${partIndex}`} part={part} />
+        ))}
+        {thinking ? <Thinking /> : null}
+      </div>
+    </div>
+  )
+}
+
+function submitOnEnter(event: ReactKeyboardEvent<HTMLTextAreaElement>): void {
+  if (
+    event.key !== 'Enter' ||
+    event.shiftKey ||
+    event.nativeEvent.isComposing
+  ) {
+    return
+  }
+  event.preventDefault()
+  event.currentTarget.form?.requestSubmit()
+}
+
+export function AgentClient({ agentId }: { agentId: string }): ReactNode {
+  const { state, push, events, index, connection } = useSession()
+  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 canSend = state.status === 'idle' || state.status === 'failed'
+
+  useEffect(() => {
+    if (canSend) promptRef.current?.focus()
+  }, [canSend])
+
+  const send = async (event: FormEvent): Promise<void> => {
+    event.preventDefault()
+    const submittedPrompt = prompt
+    const text = prompt.trim()
+    if (!text || !canSend) return
+    setPrompt('')
+    setError(null)
+    try {
+      const message: UIMessage = {
+        id: crypto.randomUUID(),
+        role: 'user',
+        parts: [{ type: 'text', text }],
+      }
+      await push(...inputs.message(message))
+    } catch (err) {
+      setPrompt((current) => (current === '' ? submittedPrompt : current))
+      setError(err instanceof Error ? err.message : String(err))
+    }
+  }
+
+  const answerApproval = async (
+    messageId: string,
+    generationId: string,
+    approvalId: string,
+    approved: boolean,
+  ): Promise<void> => {
+    setResponding(true)
+    setError(null)
+    try {
+      await push(
+        ...inputs.approval({
+          messageId,
+          generationId,
+          approvalId,
+          approved,
+          ...(!approved ? { reason: 'operator denied the restart' } : {}),
+        }),
+      )
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err))
+    } finally {
+      setResponding(false)
+    }
+  }
+
+  const stop = async (): Promise<void> => {
+    const active = state.activeGeneration
+    if (!active) return
+    setError(null)
+    try {
+      await push(
+        ...inputs.interrupt({
+          messageId: active.responseMessageId,
+          generationId: active.generationId,
+          reason: 'operator stopped the agent',
+          lastSeenIndex: index,
+        }),
+      )
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err))
+    }
+  }
+
+  return (
+    <article>
+      <header className="session-header">
+        <h1>
+          Agent <code>{agentId}</code>
+        </h1>
+        <ConnectionPill connection={connection} />
+        <span
+          className={`badge${generating ? ' live' : ''}${
+            state.status === 'waiting' ? ' waiting' : ''
+          }${state.status === 'failed' ? ' cut' : ''}`}
+        >
+          {STATUS_LABEL[state.status]}
+        </span>
+      </header>
+
+      <section className="agent-conversation" aria-label="Conversation">
+        <div className="agent-transcript" aria-live="polite">
+          {state.messages.length === 0 ? (
+            <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>
+          ) : (
+            state.messages.map((message) => (
+              <AgentMessage
+                key={message.id}
+                message={message}
+                thinking={
+                  generating &&
+                  message.role === 'assistant' &&
+                  !hasVisibleParts(message)
+                }
+              />
+            ))
+          )}
+          {generating && state.messages.at(-1)?.role === 'user' ? (
+            <div className="agent-message assistant">
+              <span className="agent-role">Agent</span>
+              <div>
+                <Thinking />
+              </div>
+            </div>
+          ) : null}
+        </div>
+
+        {state.pendingApprovals.map((approval) => (
+          <section className="approval-card" key={approval.approvalId}>
+            <div>
+              <p className="eyebrow">Human approval</p>
+              <h2>Restart checkout-api?</h2>
+              <p>
+                The agent inspected a 12.4% error rate. The runbook recommends a
+                restart after a sustained 10%.
+              </p>
+            </div>
+            <div className="approval-actions">
+              <button
+                type="button"
+                disabled={responding}
+                onClick={() =>
+                  void answerApproval(
+                    approval.messageId,
+                    approval.generationId,
+                    approval.approvalId,
+                    true,
+                  )
+                }
+              >
+                Approve restart
+              </button>
+              <button
+                type="button"
+                className="secondary"
+                disabled={responding}
+                onClick={() =>
+                  void answerApproval(
+                    approval.messageId,
+                    approval.generationId,
+                    approval.approvalId,
+                    false,
+                  )
+                }
+              >
+                Deny
+              </button>
+            </div>
+          </section>
+        ))}
+
+        {state.error ? (
+          <p className="error agent-generation-error" role="alert">
+            {state.error}
+          </p>
+        ) : null}
+
+        <form className="agent-form" onSubmit={(event) => void send(event)}>
+          <label>
+            Message
+            <textarea
+              ref={promptRef}
+              autoFocus
+              rows={3}
+              value={prompt}
+              onChange={(event) => setPrompt(event.target.value)}
+              onKeyDown={submitOnEnter}
+              disabled={!canSend}
+            />
+          </label>
+          <div className="agent-form-actions">
+            <button type="submit" disabled={!canSend || !prompt.trim()}>
+              Send to agent
+            </button>
+            <button
+              type="button"
+              className="danger"
+              disabled={!generating}
+              onClick={() => void stop()}
+            >
+              Stop
+            </button>
+          </div>
+        </form>
+      </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.
+      </p>
+
+      <ActivityFeed events={events} index={index} />
+    </article>
+  )
+}

package/examples/playground/app/agent/[agentId]/page.tsx

@@ -0,0 +1,29 @@
+import type { ReactNode } from 'react'
+import { demoAgent } from '../model'
+import { agentServer } from '../server'
+import { SessionProvider } from '../session'
+import { AgentClient } from './agent-client'
+
+export default async function AgentSessionPage({
+  params,
+}: {
+  params: Promise<{ agentId: string }>
+}): Promise<ReactNode> {
+  const { agentId } = await params
+  const session = agentServer.session(agentId)
+  const { state, index } = await session.state(demoAgent.reducer)
+  const events = (await session.history()).filter(
+    (event) => event.index <= index,
+  )
+
+  return (
+    <SessionProvider
+      sessionId={agentId}
+      initialState={state}
+      initialIndex={index}
+      initialEvents={events}
+    >
+      <AgentClient agentId={agentId} />
+    </SessionProvider>
+  )
+}

package/examples/playground/app/agent/events/route.ts

@@ -0,0 +1,4 @@
+import { agentServer } from '../server'
+
+export const GET = agentServer.fetch
+export const POST = agentServer.fetch

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

@@ -0,0 +1,3 @@
+import { agent } from 'experimental-a2/ai'
+
+export const demoAgent = agent({ name: 'agent' })

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

@@ -0,0 +1,98 @@
+'use client'
+import type {
+  FormEvent,
+  KeyboardEvent as ReactKeyboardEvent,
+  ReactNode,
+} from 'react'
+import { useState } from 'react'
+import { useRouter } from 'next/navigation'
+import type { UIMessage } from 'ai'
+import { inputs } from 'experimental-a2/ai'
+import { agentClient } from './session'
+
+const REMINDER_PROMPT =
+  'Set a reminder for yourself in 37 seconds to check checkout-api again.'
+const INCIDENT_PROMPT =
+  'Investigate the checkout errors and take the safest action.'
+
+function submitOnEnter(event: ReactKeyboardEvent<HTMLTextAreaElement>): void {
+  if (
+    event.key !== 'Enter' ||
+    event.shiftKey ||
+    event.nativeEvent.isComposing
+  ) {
+    return
+  }
+  event.preventDefault()
+  event.currentTarget.form?.requestSubmit()
+}
+
+export function NewAgentSession({
+  remindersEnabled,
+}: {
+  remindersEnabled: boolean
+}): ReactNode {
+  const router = useRouter()
+  const [prompt, setPrompt] = useState(
+    remindersEnabled ? REMINDER_PROMPT : INCIDENT_PROMPT,
+  )
+  const [submitting, setSubmitting] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+
+  const start = async (event: FormEvent): Promise<void> => {
+    event.preventDefault()
+    const submittedPrompt = prompt
+    const text = prompt.trim()
+    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))
+      router.push(`/agent/${agentId}`)
+    } catch (err) {
+      setPrompt((current) => (current === '' ? submittedPrompt : current))
+      setSubmitting(false)
+      setError(err instanceof Error ? err.message : String(err))
+    }
+  }
+
+  return (
+    <section className="agent-conversation agent-new" aria-label="New agent">
+      <div className="agent-transcript">
+        <p className="agent-empty">
+          Ask the agent to investigate an incident or set a reminder for itself.
+          The conversation starts immediately while the durable events are sent
+          in the background.
+        </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-form-actions">
+          <button type="submit" disabled={submitting || !prompt.trim()}>
+            {submitting ? 'Opening…' : 'Send to agent'}
+          </button>
+        </div>
+      </form>
+      {error ? <p className="error agent-new-error">{error}</p> : null}
+    </section>
+  )
+}

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

@@ -0,0 +1,25 @@
+import type { ReactNode } from 'react'
+import { agentScheduler } from './server'
+import { NewAgentSession } from './new-agent-session'
+
+export default function AgentPage(): ReactNode {
+  return (
+    <article>
+      <h1>Agent</h1>
+      <p className="lede">
+        One agent turn becomes a durable trail of messages, model progress, tool
+        calls, sandboxed Bash commands, human approval, and scheduled reminders.
+        The agent can stop at a decision or timer and resume later because its
+        state lives in the log, not the request.
+      </p>
+      <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.
+      </p>
+    </article>
+  )
+}

package/examples/playground/app/agent/scheduler/route.ts

@@ -0,0 +1,5 @@
+import { agentScheduler, agentServer } from '../server'
+
+export const POST =
+  agentScheduler?.handler(agentServer) ??
+  (() => new Response('agent scheduler is not configured', { status: 503 }))

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

@@ -0,0 +1,153 @@
+import 'server-only'
+import { Buffer } from 'node:buffer'
+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 { vercelQueues } from 'experimental-a2/scheduler-vercel'
+import { z } from 'zod'
+import { store } from '@/lib/store'
+import { demoAgent } from './model'
+
+const maxReminderDelaySeconds = 6 * 24 * 60 * 60
+const bashTimeoutMs = 120_000
+const maxBashOutputBytes = 64 * 1024
+
+const sandboxName = (sessionId: string): string =>
+  `a2-playground-agent-${createHash('sha256').update(sessionId).digest('hex').slice(0, 32)}`
+
+const tools = {
+  inspectService: tool({
+    description: 'Inspect the current health and runbook for a service.',
+    inputSchema: z.object({ service: z.string() }),
+    execute: ({ service }) => ({
+      service,
+      errorRate: '12.4%',
+      runbook: 'restart after sustained 10%',
+    }),
+  }),
+  restartService: tool({
+    description: 'Restart every instance of a service.',
+    inputSchema: z.object({ service: z.string() }),
+    execute: ({ service }) => ({
+      service,
+      status: 'restarted',
+      instances: 3,
+    }),
+  }),
+  bash: tool({
+    description:
+      "Execute a Bash command in this session's persistent Vercel Sandbox. Files created by one command are available to later commands in the same session.",
+    inputSchema: z.object({
+      command: z.string().min(1).describe('The Bash command to execute.'),
+    }),
+    execute: async ({ command }) => {
+      const context = handlerContext(demoAgent)
+      const sandbox = await Sandbox.getOrCreate({
+        name: sandboxName(context.session.id),
+        persistent: true,
+        signal: context.signal,
+      })
+      const running = await sandbox.runCommand({
+        cmd: '/bin/bash',
+        args: ['-lc', command],
+        detached: true,
+        signal: context.signal,
+        timeoutMs: bashTimeoutMs,
+      })
+      const logs = running.logs({ signal: context.signal })
+      let stdout = ''
+      let stderr = ''
+      let remainingBytes = maxBashOutputBytes
+      let truncated = false
+      try {
+        for await (const log of logs) {
+          const bytes = Buffer.from(log.data)
+          const retained = bytes.subarray(0, remainingBytes)
+          const text =
+            retained.byteLength === bytes.byteLength
+              ? log.data
+              : new TextDecoder().decode(retained, { stream: true })
+          if (log.stream === 'stdout') stdout += text
+          else stderr += text
+          remainingBytes -= retained.byteLength
+          if (retained.byteLength < bytes.byteLength) {
+            truncated = true
+            break
+          }
+        }
+      } catch (error) {
+        try {
+          await running.kill('SIGKILL')
+        } catch {}
+        throw error
+      } finally {
+        logs.close()
+      }
+      if (truncated) {
+        try {
+          await running.kill('SIGKILL')
+        } catch {}
+      }
+      const result = await running.wait({ signal: context.signal })
+      return { exitCode: result.exitCode, stdout, stderr, truncated }
+    },
+  }),
+  setReminder: tool({
+    description:
+      'Set a reminder for yourself after any delay up to six days. When it is due, it arrives as a new user message.',
+    inputSchema: z.object({
+      delaySeconds: z
+        .number()
+        .int()
+        .min(1)
+        .max(maxReminderDelaySeconds)
+        .describe('Seconds from now, from 1 through 518400'),
+      reminder: z.string().min(1).max(500),
+    }),
+    execute: async ({ delaySeconds, reminder }, { toolCallId }) => {
+      const context = handlerContext(demoAgent)
+      await context.session.schedule(
+        `reminder:${toolCallId}`,
+        { delay: `${delaySeconds}s` },
+        ...inputs.message({
+          id: `reminder:${context.event.id}`,
+          role: 'user',
+          parts: [{ type: 'text', text: `Reminder: ${reminder}` }],
+        }),
+      )
+      return { scheduled: true, delaySeconds, reminder }
+    },
+  }),
+}
+
+export const agentScheduler =
+  process.env.VERCEL || process.env.A2_QUEUES
+    ? vercelQueues({ topic: 'a2-agent' })
+    : undefined
+
+export const agentServer = createAgentServer({
+  ...(store ? { store } : {}),
+  ...(agentScheduler ? { scheduler: agentScheduler } : {}),
+  agent: demoAgent,
+  model: 'openai/gpt-5.6-luna',
+  tools,
+  instructions: `You are an incident-response agent for the playground.
+When responding to an incident, inspect checkout-api before taking action. Its
+runbook says to restart when the error rate remains above 10%. If it does,
+immediately call restartService. Do not ask for approval in prose: that tool
+automatically creates the built-in approval. After the operator responds,
+continue and report the result.
+
+When the operator asks for a reminder, always call setReminder and only say it
+was scheduled after the tool succeeds. A user message beginning with
+"Reminder:" is a reminder that is now due: respond to it, and do not schedule
+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' },
+  },
+})