experimental-a2 0.7.0 → 0.8.1

package/examples/playground/DEPLOY.md

@@ -0,0 +1,106 @@
+# Deploying the playground
+
+The event log runs with zero setup in development (SQLite at `.a2/dev.db`,
+no scheduler). The Agent demo also needs AI Gateway and Vercel Sandbox
+credentials. Production needs the deliberate pieces from
+`node_modules/experimental-a2/docs/guides/05-production.mdx`.
+
+## 1. A store
+
+Two options — set one of:
+
+```
+REDIS_URL=rediss://…      # push-native streams (Upstash; recommended here)
+DATABASE_URL=postgres://… # any Postgres (Neon, Supabase, RDS)
+```
+
+`lib/store.ts` prefers Redis when both are set — the chat, document,
+and canvas demos are stream-latency-sensitive, and the Redis backend
+delivers to parked subscribers in single-digit milliseconds (Postgres
+streams poll adaptively, 25–250ms). The canvas demo's presence plane
+(cursors, drag ghosts) also rides the backend's delivery tier: push on
+Redis, poll cadence elsewhere. Upstash is durable by default; use its TCP
+`rediss://` URL, not the REST one. Each feature creates its own server with
+the shared store; storage remains namespaced per contract. Without either variable, a
+production boot fails fast with `STORE_NOT_CONFIGURED` (by design).
+Schemas/keys are created lazily on first use; no migration step.
+
+To verify a provider before leaning on it, run the full conformance
+kit against it (throwaway database; the suite isolates by key prefix
+and sweeps after itself):
+
+```sh
+TEST_REDIS_URL=rediss://… pnpm --filter a2 exec vitest run test/store-redis.conformance.test.ts
+```
+
+`pg` and `ioredis` are optional peer dependencies of `experimental-a2` and direct
+dependencies of this app.
+
+## 2. Vercel Queues scheduler
+
+Queues need no configuration beyond the triggers in `vercel.json`. Orders,
+Chat, Agent, and Recovery each own a scheduler route and queue topic alongside
+their contract and server. Each topic is created on first send, and its trigger
+makes the scheduler route private (no public URL). Schedulers turn on
+automatically when `VERCEL` is set (every deployment).
+
+To exercise the scheduler locally against a linked project:
+
+```sh
+vercel link
+vercel env pull   # OIDC credentials for the @vercel/queue SDK
+A2_QUEUES=1 pnpm dev
+```
+
+## 3. AI Gateway
+
+The Agent demo uses the AI SDK with `openai/gpt-5.6-luna`, while the Chat demo
+uses `openai/gpt-5.4`. Both resolve through Vercel AI Gateway. Vercel
+deployments use their OIDC token automatically. For local generation, link the
+project and pull its environment or set an `AI_GATEWAY_API_KEY`:
+
+```sh
+vercel link
+vercel env pull
+```
+
+New Chat rooms invoke the model only for `@agent` mentions. Participants can
+enable ambient mode for the room to invoke it for every subsequent message.
+
+The Counter, Orders, Canvas, and Documents demos do not call a model.
+
+## 4. Vercel Sandbox
+
+The Agent demo's Bash tool executes commands in a named, persistent Vercel
+Sandbox. Every A2 agent session gets its own sandbox, so files remain available
+to later Bash calls in that conversation. Vercel deployments authenticate with
+OIDC automatically; the `vercel link` and `vercel env pull` commands above
+supply the same credentials during local development.
+
+## 5. WebSockets for the canvas
+
+Deployed, the canvas demo upgrades its route to a WebSocket
+(`experimental_upgradeWebSocket` from `@vercel/functions`, with `ws`
+as the server-side socket — both direct dependencies of this app).
+Vercel WebSockets need Fluid compute, which is the default on new
+projects. Under `next dev` the upgrade never reaches the route (the
+dev server drops the handshake), so the demo's session module picks
+the SSE + POST pair in development — same route, same protocol
+semantics, different wire.
+
+## 6. Deploy
+
+```sh
+vercel deploy
+```
+
+The Recovery lab tests a real function timeout. Its dedicated trigger and
+queue consumer both export `maxDuration = 20`. The pipeline has four 8-second
+handlers, so every handler fits in a fresh invocation but the 32-second chain
+does not. A2 keeps dispatching events. Vercel stops the first invocation while
+the third handler is running, leaving that event without a processed marker.
+The deadline-capped claim expires, its watchdog retries the same event in a
+fresh function, and already completed events do not run again. The dedicated
+`a2-recovery` topic keeps this artificial budget away from the
+playground's other recovery workloads. This example is disabled under
+`next dev`, which supplies neither a Vercel deadline nor queue delivery.

package/examples/playground/README.md

@@ -0,0 +1,19 @@
+# A2 playground
+
+This is a standalone snapshot of the A2 playground included with the
+`experimental-a2` npm package. It uses only public package entry points.
+
+## Run it
+
+```sh
+pnpm install
+pnpm dev
+```
+
+Each directory under `app/` owns its contract, reducer, server, routes, and
+scheduler when one is needed. Start with `app/counter` for the smallest
+example, then read `app/orders`, `app/chat`, or `app/agent` for complete
+handler-driven applications.
+
+The canonical source lives in `apps/playground` in the A2 repository. This
+copy is generated from it when the package is published.

package/examples/playground/activity-feed.test.ts

@@ -0,0 +1,10 @@
+import { describe, expect, it } from 'vitest'
+import { formatActivityTime } from './app/components/activity-feed'
+
+describe('activity feed', () => {
+  it('formats event times identically on the server and client', () => {
+    expect(formatActivityTime(new Date('2026-08-18T01:16:09.123Z'))).toBe(
+      '01:16:09 UTC',
+    )
+  })
+})

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 }))