experimental-a2 0.8.0 → 0.8.1

package/AGENTS.md

@@ -0,0 +1,11 @@
+# Using A2 from this package
+
+When answering questions or editing applications that use A2:
+
+1. Read `docs/` for the supported API and guarantees.
+2. Read `examples/playground/` for complete application structure.
+3. Read `src/` only when implementation details are relevant.
+
+Do not infer application patterns from `dist/`. The playground uses public
+package entry points and shows where contracts, reducers, servers, route
+handlers, clients, authorization, WebSocket capabilities, and schedulers live.

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.8.1
+
+### Patch Changes
+
+- 3bff761: Include a standalone snapshot of the complete Next.js playground in the npm
+  package, with package and documentation indexes that direct coding agents to
+  the supported docs and example structure.
+
 ## 0.8.0
 
 ### Minor Changes

package/README.md

@@ -0,0 +1,29 @@
+# experimental-a2
+
+Durable sync and reactions for things with a lifecycle. Each session has an
+event log, derived state, handlers, timers, and a live client.
+
+## Read the package
+
+The npm package includes more than compiled output:
+
+- `docs/` defines the supported API.
+- `examples/playground/` contains complete, standalone Next.js examples.
+- `src/` contains the TypeScript implementation.
+
+Coding agents should read `docs/` and `examples/playground/` before inferring
+usage from `dist/` or internal implementation details. Every playground feature
+owns its contract, reducer, server, route handlers, and scheduler when needed.
+The package and copied playground both include `AGENTS.md` discovery files.
+
+## Copy the playground
+
+```sh
+cp -R node_modules/experimental-a2/examples/playground ./a2-playground
+cd a2-playground
+pnpm install
+pnpm dev
+```
+
+The copied application has a standalone `package.json`. Its A2 dependency is
+pinned to the package version that shipped the snapshot.

package/docs/guides/07-examples.mdx

@@ -0,0 +1,56 @@
+---
+title: Complete examples
+description: Read or copy the complete Next.js playground that ships inside the experimental-a2 package.
+---
+
+## Shipped with the package
+
+Every `experimental-a2` installation includes a complete Next.js playground at
+`node_modules/experimental-a2/examples/playground`.
+
+The playground is not a collection of isolated snippets. Each feature owns its
+contract, reducer, server, route handlers, client session, and scheduler when it
+needs one. It uses only public package entry points.
+
+Copy it into a new directory to run or modify it:
+
+```sh
+cp -R node_modules/experimental-a2/examples/playground ./a2-playground
+cd a2-playground
+pnpm install
+pnpm dev
+```
+
+The copied `package.json` is standalone. Its A2 dependency is pinned to the
+version that supplied the example.
+
+The snapshot also includes an `AGENTS.md` file. Coding agents that support
+repository instructions discover the example's structure as soon as they work
+inside the copied directory.
+
+## Find the right example
+
+- `app/counter` is the smallest complete contract, reducer, server, and React
+  client.
+- `app/orders` adds handlers and a feature-owned scheduler.
+- `app/chat` shows request-scoped authorization and durable AI generation.
+- `app/agent` shows tools, approvals, reminders, and sandboxed commands.
+- `app/canvas` adds optimistic state, presence, and WebSocket upgrades.
+- `app/documents` combines A2 events with a collaborative document protocol.
+- `app/recovery` demonstrates queue recovery across function invocations.
+
+## Guidance for coding agents
+
+When A2 is installed locally, read these package directories in this order:
+
+1. `node_modules/experimental-a2/docs` for the supported API and guarantees.
+2. `node_modules/experimental-a2/examples/playground` for complete application
+   structure.
+3. `node_modules/experimental-a2/src` only when implementation details are
+   relevant.
+
+Do not infer application patterns from `dist`. The playground is the reference
+for how the public pieces fit together in a real Next.js application.
+
+The npm snapshot is generated from `apps/playground` in the A2 repository when
+the package is published, so the runnable app remains the canonical source.

package/docs/index.mdx

@@ -250,6 +250,16 @@ See [A2 and your database](/guides/application-data).
 
 </details>
 
+<details>
+<summary>Does the package include complete examples?</summary>
+
+Yes. Every installation includes a standalone Next.js playground at
+`node_modules/experimental-a2/examples/playground`. It contains complete
+contracts, reducers, servers, route handlers, clients, and schedulers using only
+public package entry points. See [Complete examples](/guides/examples).
+
+</details>
+
 ## Where to next
 
 <CardGroup cols={2}>
@@ -271,4 +281,7 @@ See [A2 and your database](/guides/application-data).
   <Card title="A2 and your database" href="/guides/application-data" icon="database">
     Decide what belongs in a session and what belongs in ordinary tables.
   </Card>
+  <Card title="Complete examples" href="/guides/examples" icon="code">
+    Read or copy the standalone Next.js playground included with the package.
+  </Card>
 </CardGroup>

package/examples/README.md

@@ -0,0 +1,15 @@
+# A2 examples
+
+The complete Next.js playground is included at `examples/playground` in the
+published `experimental-a2` package. It uses only public package entry points
+and can be copied into a new directory as a standalone application.
+
+For coding agents, inspect these paths before inventing an integration:
+
+- `docs/` defines the supported API.
+- `examples/playground/` shows complete applications using that API.
+- `src/` is the library implementation, not the recommended application
+  structure.
+
+The playground snapshot is generated from the repository's `apps/playground`
+directory when the package is packed.

package/examples/playground/AGENTS.md

@@ -0,0 +1,11 @@
+# A2 playground
+
+This is a standalone reference application for `experimental-a2`.
+
+- Read `node_modules/experimental-a2/docs` for the supported API.
+- Treat each directory under `app/` as a self-contained feature.
+- Keep its contract and reducer in `model.ts`.
+- Keep handlers and scheduler configuration in `server.ts`.
+- Expose A2 through the feature's `events/route.ts` using `server.fetch`.
+- Add a feature-owned `scheduler/route.ts` only when handlers or timers need it.
+- Use only public `experimental-a2` package entry points.

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