@electric-ax/agents 0.2.1 → 0.2.3

package/skills/quickstart.md

@@ -76,35 +76,47 @@ Once the directory is confirmed, read `server.ts` in that directory:
 
 - **Has `registerPerspectives`**: resume from where they left off (read `entities/perspectives.ts` to determine the step)
 - **Has `server.ts` but no perspectives**: go to Step 1
-- **No `server.ts`**: scaffold the project — spawn a worker (`tools: ["bash"]`, systemPrompt: `"Set up an Electric Agents app project."`, initialMessage: `"mkdir -p TARGET/lib TARGET/entities && cp SKILL_DIR/scaffold/* TARGET/ && cp SKILL_DIR/scaffold/lib/* TARGET/lib/ && cd TARGET && pnpm install && pnpm dev &"` — replace SKILL_DIR and TARGET). Then proceed to Step 1 while the worker runs. Wait for the worker to finish before writing files.
+- **No `server.ts`**: scaffold the project — spawn a worker (`tools: ["bash"]`, systemPrompt: `"Set up an Electric Agents app project."`, initialMessage: `"cp -r SKILL_DIR/scaffold/. TARGET/ && cd TARGET && npm install && npm run dev &"` — replace SKILL_DIR and TARGET). While the worker runs, proceed to Step 1 (explain concepts + show code). Wait for the worker to finish AND for user confirmation before writing any files.
+
+When the scaffold finishes, explain to the user:
+
+- The scaffold created a basic Electric Agents app with a `server.ts` that registers entity types, connects to the agent server, and listens for webhook callbacks on port 3000.
+- `npm run dev` started the server in the background with `tsx --watch`, so any file changes will auto-reload.
+- The `entities/` directory is where we'll add our agent code — it's empty for now.
+- The server is already connected to the Electric Agents coordinator (on port 4437) and ready to handle entities once we define them.
+- `server.ts` is a plain Node.js HTTP server — you can add your own routes, middleware, or serve a frontend from it. We'll do exactly that in later steps.
 
 ## Steps
 
-**Step 1 — Welcome + first entity.** In one message: introduce Electric Agents using the Core Concepts above, preview the perspectives analyzer, and show the Step 1 code. Ask to write.
+IMPORTANT: Never write files until the user explicitly confirms. "Ask to write" means show the code, then wait for the user to say yes. Do not write files automatically after scaffolding completes or after showing code.
 
-**Step 2 — After confirmation:** write `entities/perspectives.ts` with Step 1 code. Give CLI commands. Explain spawning briefly, show Step 2 code (adds one worker). Ask to write.
+**Step 1 — Welcome + first entity.** In one message: introduce Electric Agents using the Core Concepts above, preview the perspectives analyzer, and show the Step 1 code. Ask the user if they want you to write it. Do NOT write until they confirm.
 
-**Step 3 — After confirmation:** write the updated file. Give CLI commands. Explain coordination, show Step 3 code (adds critic + state). Ask to write.
+**Step 2 — After confirmation:** write `entities/perspectives.ts` with Step 1 code. Also update `server.ts` to import and register the entity (replace the placeholder comments with `import { registerPerspectives } from './entities/perspectives'` and `registerPerspectives(registry)`). Give CLI commands. Explain spawning briefly, show Step 2 code (adds one worker). Ask to write.
 
-**Step 4 — After confirmation:** write the updated file. Give CLI commands.
+**Step 3 — After confirmation:** write the updated file. Give CLI commands. Explain coordination, show Step 3 code (adds critic + state). Ask to write. After confirmation, write the file and encourage the user to try the CLI commands.
 
-**Step 5 — Wire up.** Read `server.ts`, show the import change, ask to write, update it.
+**Checkpoint.** After Step 3 is confirmed and working, congratulate the user: they have a working multi-agent system with a manager that spawns workers and synthesizes results. Recap what they've built so far (entity, spawning, state coordination). Then present options for what to do next:
 
-**Step 6 — After confirmation:** explain shared state as cross-entity coordination. Show Step 6 code (chatroom schema + chat-agent entity with `ctx.mkdb` and `ctx.observe`). Write files, give CLI commands to test. Ask to continue.
+- **Continue building** — add an HTTP API route and a React frontend to this app so users can interact with the analyzer from the browser.
+- **Start a new app** — use the `agents-chat-starter` template for a full multi-agent chat app with rooms, agent spawning, and a Slack-style UI. Load the init skill or tell them to type `/init`.
+- **Explore the docs** — read about other coordination patterns (blackboard, pipeline, map-reduce), dive into the API reference, or learn about shared state, context assembly, and other advanced features. Use `search_durable_agents_docs` to look things up.
 
-**Step 7 — After confirmation:** explain context assembly. Show the `ctx.useContext()` addition. Update the entity file. Test with two agents in the same room. Ask to continue.
+Wait for the user to choose. Only proceed to Step 4 if they want to continue building.
 
-**Step 8 — After confirmation:** explain live frontend queries. Show Step 8 code (React + TanStack DB `useLiveQuery`). Create UI files, add deps, give commands to run. Show how updates appear in real time.
+**Step 4 — API route.** Show the updated server.ts with a `POST /api/analyze` route using `createRuntimeServerClient`. Explain what's new in the code. Ask to write — do NOT write until they confirm. After writing, give curl test commands.
 
-**Step 9 — Recap.**
+**Step 5 — After confirmation:** scaffold the UI. Spawn a worker (`tools: ["bash"]`, systemPrompt: `"Copy UI scaffold files into the project."`, initialMessage: `"cp -r SKILL_DIR/scaffold-ui/. TARGET/ui/"` — replace SKILL_DIR and TARGET). While the worker copies, explain the frontend architecture: `createAgentsClient` connects to the agent server, `entity(url)` subscribes to an entity's stream, `useChat` reactively assembles text from deltas, and Radix Themes provides the UI components. Walk through the key parts of `ui/main.tsx` — the `useEntityDb` hook (with retry for workers that are spawned asynchronously), `useAgentMessages`, `MessageBubble` (color-coded by agent: blue for analyser, green for optimist, red for critic), and the `App` component's flow (POST to `/api/analyze` → subscribe to all three entity streams → messages appear inline as chat bubbles). After the worker finishes, tell the user to run `npm run dev:all` to start both the server and UI, then open `http://localhost:5175`.
+
+**Step 6 — Recap.**
 
 ## Rules
 
-- Use the exact code below. Write files with your write tool.
+- Show only the key changes in each step, not the full file. Explain what's new and why, then use the write/edit tool to apply the changes. The code below is a reference — do not dump the entire file on the user.
 - `server.ts` is at the working directory root. Entity files go in `entities/`.
-- Worker spawn args MUST include `tools` array (e.g. `tools: ["bash", "read"]`).
-- Prefer showing what changed between steps rather than repeating the entire file.
+- Worker spawn args MUST include `tools` array (at least one tool, e.g. `tools: ["bash"]`).
 - Use `edit` tool for small changes (like updating server.ts). Use `write` for full entity file updates.
+- If the user asks a question about Electric Agents concepts, APIs, or patterns between steps, use the `search_durable_agents_docs` tool to look up the answer in the built-in documentation before guessing or searching the web.
 
 ---
 
@@ -140,7 +152,7 @@ import { registerPerspectives } from './entities/perspectives'
 registerPerspectives(registry)
 ```
 
-Test: `pnpm electric-agents spawn /perspectives/test-1 && pnpm electric-agents send /perspectives/test-1 "Is remote work better than office work?" && pnpm electric-agents observe /perspectives/test-1`
+Test: `npx electric-ax agents spawn /perspectives/test-1 && npx electric-ax agents send /perspectives/test-1 "Is remote work better than office work?" && npx electric-ax agents observe /perspectives/test-1`
 
 ## Step 2: One worker
 
@@ -202,7 +214,7 @@ export function registerPerspectives(registry: EntityRegistry) {
 }
 ```
 
-Test: `pnpm electric-agents spawn /perspectives/test-2 && pnpm electric-agents send /perspectives/test-2 "Is remote work better than office work?" && pnpm electric-agents observe /perspectives/test-2`
+Test: `npx electric-ax agents spawn /perspectives/test-2 && npx electric-ax agents send /perspectives/test-2 "Is remote work better than office work?" && npx electric-ax agents observe /perspectives/test-2`
 
 ## Step 3: Two workers + state
 
@@ -219,12 +231,12 @@ const PERSPECTIVES = [
   {
     id: 'optimist',
     systemPrompt:
-      'You are an optimist analyst. Provide an enthusiastic, positive analysis focusing on opportunities and benefits.',
+      'You are an optimist analyst. Provide an enthusiastic, positive analysis focusing on opportunities and benefits. Answer directly — do not comment on tools or capabilities.',
   },
   {
     id: 'critic',
     systemPrompt:
-      'You are a critical analyst. Provide a sharp analysis focusing on risks, downsides, and challenges.',
+      'You are a critical analyst. Provide a sharp analysis focusing on risks, downsides, and challenges. Answer directly — do not comment on tools or capabilities.',
   },
 ]
 
@@ -244,7 +256,7 @@ function createAnalyzeTool(ctx: HandlerContext) {
         await ctx.spawn(
           'worker',
           childId,
-          { systemPrompt: p.systemPrompt, tools: ['bash', 'read'] },
+          { systemPrompt: p.systemPrompt, tools: ['bash'] },
           { initialMessage: question, wake: 'runFinished' }
         )
         ctx.db.actions.children_insert({
@@ -271,7 +283,7 @@ export function registerPerspectives(registry: EntityRegistry) {
     state: { children: { primaryKey: 'key' } },
     async handler(ctx) {
       ctx.useAgent({
-        systemPrompt: `You are a balanced analyst.\n\n1. Call analyze_question with the question.\n2. End your turn. You'll be woken as each worker finishes.\n3. Each wake includes finished_child.response and other_children.\n4. Once both are done, synthesize a balanced response.`,
+        systemPrompt: `You are a balanced analyst.\n\n1. Call analyze_question with the question.\n2. Tell the user you are spawning an optimist and a critic to analyze their question and that you will synthesize their perspectives once they finish.\n3. End your turn immediately — say nothing else.\n\nYou will be woken once per worker that finishes. Each wake includes finished_child and other_children (with status "running" or "finished").\n\nCRITICAL: When woken, check other_children. If ANY child still has status "running", you MUST respond with ONLY the exact text "waiting" and nothing else — no commentary, no status updates, no emoji. Just the single word "waiting".\n\nOnly when ALL children show status "finished" should you synthesize a balanced response using both perspectives.`,
         model: 'claude-sonnet-4-6',
         tools: [...ctx.electricTools, createAnalyzeTool(ctx)],
       })
@@ -281,392 +293,245 @@ export function registerPerspectives(registry: EntityRegistry) {
 }
 ```
 
-Test: `pnpm electric-agents spawn /perspectives/test-3 && pnpm electric-agents send /perspectives/test-3 "Is remote work better than office work?" && pnpm electric-agents observe /perspectives/test-3`
-
-## Step 6: Shared state — a chatroom
+Test: `npx electric-ax agents spawn /perspectives/test-3 && npx electric-ax agents send /perspectives/test-3 "Is remote work better than office work?" && npx electric-ax agents observe /perspectives/test-3`
 
-In the perspectives analyzer, workers reported back to a parent via `runFinished`. But what if agents need to coordinate in real time — reading and writing to the same data? That's **shared state**.
+## Step 4: Server routes
 
-Shared state is a durable stream that multiple entities can observe. One entity creates it with `ctx.mkdb()`, others connect with `ctx.observe(db(...))`. Both sides read and write the same collections.
+You now have a working multi-agent system: a manager entity that spawns optimist and critic workers, coordinates their responses, and synthesizes the analysis. Everything works from the CLI.
 
-Let's build a chatroom: a shared message log that agents post to using a `send_message` tool.
+Next, we'll turn this into a real app. The server.ts you've been running is a plain Node.js HTTP server — we can add routes to it, serve a frontend, and let users interact with the analyzer from a browser. First step: an API route.
 
-`entities/chatroom-schema.ts`:
+`createRuntimeServerClient()` gives you a programmatic client for spawning entities and sending messages from your server code — the same operations you've been doing with the CLI.
 
-```typescript
-import { z } from 'zod'
-
-export const messageSchema = z.object({
-  key: z.string().min(1),
-  role: z.enum(['user', 'agent']),
-  sender: z.string().min(1),
-  senderName: z.string().min(1),
-  text: z.string().min(1),
-  timestamp: z.number(),
-})
-
-export const chatroomSchema = {
-  messages: {
-    schema: messageSchema,
-    type: 'shared:message',
-    primaryKey: 'key',
-  },
-} as const
-```
+Update `server.ts` — add the runtime server client import and an `/api/analyze` route:
 
-`entities/chat-agent.ts`:
+Add `createRuntimeServerClient` to your imports from `@electric-ax/agents-runtime`, then create a client instance:
 
 ```typescript
-import { db } from '@electric-ax/agents-runtime'
-import { z } from 'zod'
-import { Type } from '@sinclair/typebox'
-import { chatroomSchema } from './chatroom-schema'
-import type {
-  EntityRegistry,
-  SharedStateHandle,
-  AgentTool,
+import {
+  createEntityRegistry,
+  createRuntimeHandler,
+  createRuntimeServerClient, // ← add this
 } from '@electric-ax/agents-runtime'
 
-type ChatroomState = SharedStateHandle<typeof chatroomSchema>
-
-const chatAgentArgs = z.object({ chatroomId: z.string().min(1) })
-
-function createSendMessageTool(
-  messages: ChatroomState['messages'],
-  senderName: string
-): AgentTool {
-  return {
-    name: 'send_message',
-    description: 'Post a message to the chatroom.',
-    parameters: Type.Object({
-      text: Type.String({ description: 'The message text' }),
-    }),
-    execute: async (_id, params) => {
-      const { text } = params as { text: string }
-      ;(messages as any).insert({
-        key: crypto.randomUUID(),
-        role: 'agent',
-        sender: senderName,
-        senderName,
-        text,
-        timestamp: Date.now(),
-      })
-      return {
-        content: [{ type: 'text' as const, text: 'Message sent.' }],
-        details: {},
-      }
-    },
-  }
-}
-
-function createWebSearchTool(): AgentTool {
-  return {
-    name: 'web_search',
-    description: 'Search the web for current information.',
-    parameters: Type.Object({
-      query: Type.String({ description: 'The search query' }),
-    }),
-    execute: async (_id, params) => {
-      const apiKey = process.env.BRAVE_SEARCH_API_KEY
-      if (!apiKey) {
-        return {
-          content: [
-            {
-              type: 'text' as const,
-              text: 'Web search unavailable: BRAVE_SEARCH_API_KEY not set.',
-            },
-          ],
-          details: {},
-        }
-      }
-      const { query } = params as { query: string }
-      const res = await fetch(
-        `https://api.search.brave.com/res/v1/web/search?q=${encodeURIComponent(query)}&count=5`,
-        { headers: { 'X-Subscription-Token': apiKey } }
-      )
-      if (!res.ok) {
-        return {
-          content: [
-            { type: 'text' as const, text: `Search failed: ${res.status}` },
-          ],
-          details: {},
-        }
-      }
-      const data = (await res.json()) as {
-        web?: {
-          results?: Array<{ title: string; url: string; description: string }>
-        }
-      }
-      const results = data.web?.results ?? []
-      const formatted = results
-        .map(
-          (r, i) => `${i + 1}. **${r.title}**\n   ${r.url}\n   ${r.description}`
-        )
-        .join('\n\n')
-      return {
-        content: [
-          { type: 'text' as const, text: formatted || 'No results found.' },
-        ],
-        details: { resultCount: results.length },
-      }
-    },
-  }
-}
-
-export function registerChatAgent(registry: EntityRegistry) {
-  registry.define('chat-agent', {
-    description: 'Chat agent that reads and writes to a shared chatroom',
-    creationSchema: chatAgentArgs,
-    async handler(ctx) {
-      const args = chatAgentArgs.parse(ctx.args)
-
-      // First wake: create the shared state
-      if (ctx.firstWake) {
-        ctx.mkdb(args.chatroomId, chatroomSchema)
-      }
+// ... existing setup ...
 
-      // Observe shared state — wake when messages change
-      const chatroom = (await ctx.observe(db(args.chatroomId, chatroomSchema), {
-        wake: { on: 'change', collections: ['shared:message'] },
-      })) as unknown as ChatroomState
+const client = createRuntimeServerClient({ baseUrl: ELECTRIC_AGENTS_URL })
+```
 
-      // On first wake, just register the wake — don't call the LLM
-      if (ctx.firstWake) return
+Then add this route handler inside `http.createServer`, after the existing `/webhook` handler:
 
-      ctx.useAgent({
-        systemPrompt:
-          'You are a helpful chat agent. Use web_search to find information and send_message to reply.',
-        model: 'claude-sonnet-4-6',
-        tools: [
-          createSendMessageTool(chatroom.messages, ctx.entityUrl),
-          createWebSearchTool(),
-        ],
+```typescript
+if (req.url === '/api/analyze' && req.method === 'POST') {
+  try {
+    const body = (await readJson(req)) as { question?: string }
+    if (!body.question) {
+      res.writeHead(400, { 'content-type': 'application/json' })
+      res.end(JSON.stringify({ error: 'Missing "question" field' }))
+      return
+    }
+
+    const id = `analysis-${crypto.randomUUID().slice(0, 8)}`
+
+    await client.spawnEntity({
+      type: 'perspectives',
+      id,
+      initialMessage: body.question,
+    })
+
+    res.writeHead(200, { 'content-type': 'application/json' })
+    res.end(
+      JSON.stringify({
+        entityUrl: `/perspectives/${id}`,
+        optimistUrl: `/worker/${id}-optimist`,
+        criticUrl: `/worker/${id}-critic`,
       })
-      await ctx.agent.run()
-    },
-  })
+    )
+  } catch (err) {
+    res.writeHead(500, { 'content-type': 'application/json' })
+    res.end(
+      JSON.stringify({
+        error: err instanceof Error ? err.message : String(err),
+      })
+    )
+  }
+  return
 }
 ```
 
-Add to `server.ts`:
+Test with curl:
 
-```typescript
-import { registerChatAgent } from './entities/chat-agent'
-registerChatAgent(registry)
+```bash
+curl -X POST http://localhost:3000/api/analyze \
+  -H "Content-Type: application/json" \
+  -d '{"question":"Is remote work better than office work?"}'
 ```
 
-Test:
+Then observe the spawned entity:
 
 ```bash
-pnpm electric-agents spawn /chat-agent/agent-1 '{"chatroomId":"room-1"}' \
-  && pnpm electric-agents send /chat-agent/agent-1 "Hello! What can you help me with?" \
-  && pnpm electric-agents observe /chat-agent/agent-1
+npx electric-ax agents observe /perspectives/analysis-<id>
 ```
 
 **Key concepts:**
 
-- `ctx.mkdb(id, schema)` — creates a shared state stream (only on first wake)
-- `ctx.observe(db(id, schema), { wake })` — connects to shared state and wakes on changes
-- `wake: { on: 'change', collections: ['shared:message'] }` — wake when specific event types appear
-- The observe + wake must run on first wake (before early return) so the wake registers
-- Custom tools (`send_message`, `web_search`) — agents interact with the world through tools you define
+- `createRuntimeServerClient({ baseUrl })` — programmatic client for the agent server
+- `client.spawnEntity({ type, id, initialMessage })` — spawns an entity and sends a message in one call
+- Entity URLs are addressable — child worker URLs are deterministic (`<id>-optimist`, `<id>-critic`)
 
-## Step 7: Context assembly — agents that remember
+## Step 5: Frontend — live results
 
-When an agent wakes, it only sees the current message in its inbox. But in a chatroom, it needs the full conversation history to respond intelligently. And if a new agent joins mid-conversation, it should catch up.
+The UI files are pre-built in the scaffold. Copy them into the project, then read and explain them.
 
-`ctx.useContext()` injects external data into the agent's context before the LLM call. You configure sources with a token budget and cache strategy:
+The scaffold includes:
 
-Update the handler in `entities/chat-agent.ts` — add `useContext` between `observe` and `useAgent`:
+- `ui/index.html` — HTML shell
+- `ui/main.tsx` — React app with Radix Themes, `createAgentsClient`, `useChat` hook
+- `vite.config.ts` — Vite dev server with proxy to the app server
 
-```typescript
-      // Read conversation history from shared state
-      const allMessages = (chatroom.messages as any).toArray as Array<{
-        senderName: string
-        text: string
-      }>
-      const history = allMessages
-        .map((m) => `[${m.senderName}]: ${m.text}`)
-        .join('\n')
-
-      // Inject as volatile context (changes every wake)
-      ctx.useContext({
-        sourceBudget: 50_000,
-        sources: {
-          conversation: {
-            cache: 'volatile',
-            content: async () =>
-              history ? `Conversation so far:\n${history}` : '',
-          },
-        },
-      })
+The `vite.config.ts` was already included in the initial scaffold. The `ui/` files are copied from `SKILL_DIR/scaffold-ui/`.
 
-      ctx.useAgent({
-```
-
-Test — spawn two agents in the same room to see them share context:
-
-```bash
-pnpm electric-agents spawn /chat-agent/agent-2 '{"chatroomId":"room-1"}' \
-  && pnpm electric-agents send /chat-agent/agent-2 "What has been discussed so far?" \
-  && pnpm electric-agents observe /chat-agent/agent-2
-```
-
-Agent 2 sees agent 1's messages because both observe the same shared state.
+After copying, read `ui/main.tsx` with the user and walk through the key parts with code snippets:
 
-**Key concepts:**
-
-- `ctx.useContext()` — injects data into the LLM context (separate from the system prompt)
-- `sourceBudget` — limits total tokens so long conversations don't overflow
-- `cache: 'volatile'` — content changes every wake (vs `'stable'` for static docs, `'pinned'` for always-include)
-- The content function is `async` — you can fetch from any source
-
-## Step 8: Frontend — live queries
+### Connecting to an entity stream
 
-The agents are chatting, but we can't see it. Let's build a frontend that subscribes to the shared state and updates in real time — no polling.
+The `useEntityDb` hook subscribes to a single entity's durable stream. This is the bridge between the agent server and React:
 
-The frontend uses `createAgentsClient` to connect to the agents server, then `useLiveQuery` from TanStack DB for reactive queries on durable stream collections.
-
-`ui/index.html`:
+```tsx
+function useEntityDb(url: string | null, retryMs = 0) {
+  const [db, setDb] = useState<EntityStreamDB | null>(null)
 
-```html
-<!DOCTYPE html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Chat</title>
-  </head>
-  <body>
-    <div id="root"></div>
-    <script type="module" src="./main.tsx"></script>
-  </body>
-</html>
+  useEffect(() => {
+    if (!url) {
+      setDb(null)
+      return
+    }
+    let cancelled = false
+    const connect = () => {
+      const client = createAgentsClient({ baseUrl: AGENTS_URL })
+      client.observe(entity(url)).then(
+        (observed) => {
+          if (!cancelled) setDb(observed as EntityStreamDB)
+        },
+        () => {
+          if (!cancelled && retryMs > 0) setTimeout(connect, retryMs)
+        }
+      )
+    }
+    connect()
+    return () => {
+      cancelled = true
+    }
+  }, [url, retryMs])
+
+  return db
+}
 ```
 
-`ui/main.tsx`:
-
-```tsx
-import { useState, useEffect, useRef } from 'react'
-import { createRoot } from 'react-dom/client'
-import { createAgentsClient, db } from '@electric-ax/agents-runtime'
-import { useLiveQuery } from '@tanstack/react-db'
-import type { Collection } from '@tanstack/db'
-import { chatroomSchema } from '../entities/chatroom-schema'
+`createAgentsClient` connects to the agent server. `entity(url)` tells it which entity to observe. The connection is via SSE — updates arrive in real time, no polling. `retryMs` handles workers that don't exist yet (the manager spawns them asynchronously).
 
-const AGENTS_URL = 'http://localhost:4437'
-const ROOM_ID = 'room-1'
+### Extracting messages with useChat
 
-function Chat() {
-  const [collection, setCollection] = useState<Collection<any> | null>(null)
-  const [error, setError] = useState<string | null>(null)
-  const bottomRef = useRef<HTMLDivElement>(null)
+The `useAgentMessages` hook takes an entity stream and extracts text messages using `useChat`:
 
-  useEffect(() => {
-    const client = createAgentsClient({ baseUrl: AGENTS_URL })
-    client
-      .observe(db(ROOM_ID, chatroomSchema))
-      .then((sdb: any) => setCollection(sdb.collections.messages))
-      .catch((e: Error) => setError(e.message))
-  }, [])
-
-  const { data: messages = [] } = useLiveQuery(
-    collection
-      ? (q) =>
-          q
-            .from({ m: collection })
-            .orderBy(({ m }) => (m as any).timestamp, 'asc')
-            .select(({ m }) => m)
-      : () => null,
-    [collection]
+```tsx
+function useAgentMessages(
+  url: string | null,
+  agent: string,
+  retryMs = 0
+): AgentMessage[] {
+  const db = useEntityDb(url, retryMs)
+  const chat = useChat(db)
+
+  return chat.runs.flatMap((r, ri) =>
+    r.texts
+      .filter((t) => t.text.trim().length > 0)
+      .map((t, ti) => ({
+        agent,
+        text: t.text,
+        isStreaming:
+          chat.state === 'working' &&
+          ri === chat.runs.length - 1 &&
+          ti === r.texts.length - 1,
+      }))
   )
+}
+```
 
-  useEffect(() => {
-    bottomRef.current?.scrollIntoView({ behavior: 'smooth' })
-  }, [messages.length])
+`useChat(db)` is the key hook — it reactively assembles text from the entity's `textDeltas` collection (token-by-token streaming) into complete text blocks. `chat.runs` contains each agent run with its `texts`. `chat.state` tells you if the agent is `'working'` (still generating) or `'idle'` (done).
+
+### Rendering messages
 
-  if (error) return <div>Error: {error}</div>
-  if (!collection) return <div>Connecting...</div>
+Each message is a color-coded card with markdown rendering via `Streamdown`:
 
+```tsx
+function MessageBubble({ msg }: { msg: AgentMessage }) {
+  const colors = AGENT_COLORS[msg.agent]
   return (
-    <div
-      style={{ maxWidth: 600, margin: '2rem auto', fontFamily: 'system-ui' }}
+    <Card
+      size="1"
+      style={{
+        background: colors.bg,
+        borderLeft: `3px solid ${colors.border}`,
+      }}
     >
-      <h1>Chatroom: {ROOM_ID}</h1>
-      <div
-        style={{
-          border: '1px solid #ddd',
-          borderRadius: 8,
-          padding: 16,
-          minHeight: 300,
-        }}
-      >
-        {messages.map((m: any) => (
-          <div key={m.key} style={{ marginBottom: 8 }}>
-            <strong>{m.senderName}:</strong> {m.text}
-          </div>
-        ))}
-        <div ref={bottomRef} />
-      </div>
-    </div>
+      <Text size="1" weight="bold" style={{ textTransform: 'capitalize' }}>
+        {msg.agent}
+      </Text>
+      <Box mt="1" style={{ fontSize: 'var(--font-size-2)' }}>
+        <Streamdown isAnimating={msg.isStreaming} controls={false}>
+          {msg.text}
+        </Streamdown>
+      </Box>
+    </Card>
   )
 }
-
-createRoot(document.getElementById('root')!).render(<Chat />)
 ```
 
-Add dependencies: `pnpm add @tanstack/db @tanstack/react-db react react-dom` and dev dependencies: `pnpm add -D @types/react @types/react-dom @vitejs/plugin-react vite`
-
-Add a Vite config (`vite.config.ts`):
-
-```typescript
-import path from 'node:path'
-import { defineConfig } from 'vite'
-import react from '@vitejs/plugin-react'
-
-export default defineConfig({
-  root: 'ui',
-  plugins: [react()],
-  resolve: {
-    alias: {
-      '@tanstack/db': path.resolve(
-        import.meta.dirname,
-        'node_modules/@tanstack/db'
-      ),
-    },
-  },
-  server: { port: 5175 },
-  build: { outDir: '../dist', emptyOutDir: true },
-})
-```
+Blue for the analyser, green for the optimist, red for the critic. `Streamdown` renders markdown and shows a streaming cursor while `isAnimating` is true.
 
-Run: `npx vite` (in a new terminal). Open `http://localhost:5175`.
+### Wiring it together
 
-Then send a message to an agent in the room:
+The `App` component subscribes to all three entities and renders them in sections — the analyser's intro at full width, then the optimist and critic side-by-side in two columns, then the analyser's synthesis at full width:
 
-```bash
-pnpm electric-agents send /chat-agent/agent-1 "What's the weather like today?"
+```tsx
+const analyserMessages = useAgentMessages(urls?.entityUrl ?? null, 'analyser')
+const optimistMessages = useAgentMessages(
+  urls?.optimistUrl ?? null,
+  'optimist',
+  2000
+)
+const criticMessages = useAgentMessages(urls?.criticUrl ?? null, 'critic', 2000)
+
+const hasWorkerMessages =
+  optimistMessages.length > 0 || criticMessages.length > 0
+const analyserIntro = analyserMessages.slice(0, 1)
+const analyserSynthesis = hasWorkerMessages ? analyserMessages.slice(1) : []
 ```
 
-Watch the frontend update in real time as the agent responds.
+The layout transitions naturally: first the analyser's intro appears full-width, then two columns open up as workers start streaming, and finally the synthesis appears full-width below. Workers get `retryMs=2000` because they're spawned asynchronously.
+
+After explaining, tell the user to restart with `npm run dev:all` (starts both server and Vite). Open `http://localhost:5175`.
 
 **Key concepts:**
 
-- `createAgentsClient({ baseUrl })` — connects the frontend to the agents server
-- `client.observe(db(roomId, schema))` — subscribes to a shared state stream (SSE)
-- `useLiveQuery` — reactive query that re-renders when the collection changes
-- `.select(({ m }) => m)` — flattens the query result (removes the alias wrapper)
-- No polling — the durable stream pushes updates to the browser via SSE
+- `createAgentsClient({ baseUrl })` — connects the frontend to the agent server
+- `client.observe(entity(url))` — subscribes to an entity's durable stream via SSE
+- `useChat(db)` — reactive hook that assembles text from `textDeltas`, tracks agent state
+- `chat.state` — `'working'` means the agent is actively generating text
+- `Streamdown` — renders markdown with streaming cursor support
+- No polling — the durable stream pushes updates to the browser
 
 ## What you learned
 
-| Step | Concept                 | API                                                             |
-| ---- | ----------------------- | --------------------------------------------------------------- |
-| 1    | Entity types & handlers | `registry.define()`, `ctx.useAgent()`, `ctx.agent.run()`        |
-| 2    | Spawning children       | `ctx.spawn()`, `wake: 'runFinished'`                            |
-| 3    | State collections       | `state: { children: { primaryKey: 'key' } }`                    |
-| 6    | Shared state            | `ctx.mkdb()`, `ctx.observe(db(...))`, cross-entity coordination |
-| 7    | Context assembly        | `ctx.useContext()`, `sourceBudget`, cache tiers                 |
-| 8    | Live frontend           | `createAgentsClient`, `useLiveQuery`, `.select()`               |
+| Step | Concept                 | API                                                         |
+| ---- | ----------------------- | ----------------------------------------------------------- |
+| 1    | Entity types & handlers | `registry.define()`, `ctx.useAgent()`, `ctx.agent.run()`    |
+| 2    | Spawning children       | `ctx.spawn()`, `wake: 'runFinished'`                        |
+| 3    | State collections       | `state: { children: { primaryKey: 'key' } }`                |
+| 4    | Server routes           | `createRuntimeServerClient()`, `client.spawnEntity()`       |
+| 5    | Live frontend           | `createAgentsClient`, `entity()`, `useChat`, streaming text |
 
 For a complete multi-agent chat app with rooms, agent spawning, and a Slack-style UI, see the [agents-chat-starter](https://github.com/electric-sql/electric/tree/main/examples/agents-chat-starter) example.
+
+Want to keep going? Just ask me anything — I can search the Electric Agents docs for coordination patterns (pipeline, map-reduce, blackboard), API reference, shared state, context assembly, and more.