@electric-ax/agents 0.2.2 → 0.2.4

package/skills/quickstart/scaffold-ui/main.tsx

@@ -1,4 +1,12 @@
-import { useState, useEffect, useRef } from 'react'
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react'
 import { createRoot } from 'react-dom/client'
 import { createAgentsClient, entity } from '@electric-ax/agents-runtime'
 import { useChat } from '@electric-ax/agents-runtime/react'
@@ -11,12 +19,132 @@ import {
   TextField,
   Button,
   Card,
+  IconButton,
 } from '@radix-ui/themes'
+import { SunIcon, MoonIcon, DesktopIcon } from '@radix-ui/react-icons'
 import { Streamdown } from 'streamdown'
 import '@radix-ui/themes/styles.css'
 import 'streamdown/styles.css'
 import type { EntityStreamDB } from '@electric-ax/agents-runtime'
 
+// ---------------------------------------------------------------------------
+// Dark-mode hook (inlined – single-file scaffold)
+// ---------------------------------------------------------------------------
+
+const DARK_MODE_STORAGE_KEY = `electric-perspectives.dark-mode`
+
+type ThemePreference = `light` | `dark` | `system`
+
+type DarkModeContextValue = {
+  darkMode: boolean
+  preference: ThemePreference
+  cyclePreference: () => void
+}
+
+const DarkModeContext = createContext<DarkModeContextValue | null>(null)
+
+function readInitialPreference(): ThemePreference {
+  if (typeof window === `undefined`) return `system`
+  const stored = window.localStorage.getItem(DARK_MODE_STORAGE_KEY)
+  if (stored === `true` || stored === `dark`) return `dark`
+  if (stored === `false` || stored === `light`) return `light`
+  return `system`
+}
+
+function systemPrefersDark(): boolean {
+  if (typeof window === `undefined`) return false
+  return window.matchMedia?.(`(prefers-color-scheme: dark)`).matches ?? false
+}
+
+const cycleOrder: Record<ThemePreference, ThemePreference> = {
+  light: `dark`,
+  dark: `system`,
+  system: `light`,
+}
+
+function DarkModeProvider({
+  children,
+}: {
+  children: React.ReactNode
+}): React.ReactElement {
+  const [preference, setPreference] = useState<ThemePreference>(
+    readInitialPreference
+  )
+  const [systemDark, setSystemDark] = useState<boolean>(systemPrefersDark)
+
+  useEffect(() => {
+    if (typeof window === `undefined`) return
+    const mql = window.matchMedia(`(prefers-color-scheme: dark)`)
+    const onChange = (e: MediaQueryListEvent): void => setSystemDark(e.matches)
+    mql.addEventListener(`change`, onChange)
+    return () => mql.removeEventListener(`change`, onChange)
+  }, [])
+
+  const darkMode = preference === `system` ? systemDark : preference === `dark`
+
+  useEffect(() => {
+    document.documentElement.classList.toggle(`dark`, darkMode)
+  }, [darkMode])
+
+  const cyclePreference = useCallback(() => {
+    setPreference((current) => {
+      const next = cycleOrder[current]
+      window.localStorage.setItem(DARK_MODE_STORAGE_KEY, next)
+      return next
+    })
+  }, [])
+
+  const value = useMemo(
+    () => ({ darkMode, preference, cyclePreference }),
+    [darkMode, preference, cyclePreference]
+  )
+
+  return (
+    <DarkModeContext.Provider value={value}>
+      {children}
+    </DarkModeContext.Provider>
+  )
+}
+
+function useDarkModeContext(): DarkModeContextValue {
+  const value = useContext(DarkModeContext)
+  if (!value) {
+    throw new Error(`useDarkModeContext must be used inside DarkModeProvider`)
+  }
+  return value
+}
+
+// ---------------------------------------------------------------------------
+// Theme toggle button
+// ---------------------------------------------------------------------------
+
+function themeButtonIcon(preference: ThemePreference) {
+  if (preference === `light`) return <SunIcon />
+  if (preference === `dark`) return <MoonIcon />
+  return <DesktopIcon />
+}
+
+function themeButtonAriaLabel(preference: ThemePreference): string {
+  if (preference === `light`) return `Switch to dark mode`
+  if (preference === `dark`) return `Switch to system theme`
+  return `Switch to light mode`
+}
+
+function ThemeToggle() {
+  const { preference, cyclePreference } = useDarkModeContext()
+  return (
+    <IconButton
+      variant="ghost"
+      size="2"
+      color="gray"
+      onClick={cyclePreference}
+      aria-label={themeButtonAriaLabel(preference)}
+    >
+      {themeButtonIcon(preference)}
+    </IconButton>
+  )
+}
+
 const AGENTS_URL = `http://localhost:4437`
 
 const AGENT_COLORS: Record<string, { bg: string; border: string }> = {
@@ -121,13 +249,29 @@ function MessageBubble({ msg }: { msg: AgentMessage }) {
   )
 }
 
+function urlsFromId(id: string) {
+  return {
+    entityUrl: `/perspectives/${id}`,
+    optimistUrl: `/worker/${id}-optimist`,
+    criticUrl: `/worker/${id}-critic`,
+  }
+}
+
+function getIdFromHash(): string | null {
+  const hash = window.location.hash.slice(1)
+  return hash || null
+}
+
 function App() {
   const [question, setQuestion] = useState(``)
   const [urls, setUrls] = useState<{
     entityUrl: string
     optimistUrl: string
     criticUrl: string
-  } | null>(null)
+  } | null>(() => {
+    const id = getIdFromHash()
+    return id ? urlsFromId(id) : null
+  })
   const [loading, setLoading] = useState(false)
   const bottomRef = useRef<HTMLDivElement>(null)
 
@@ -143,11 +287,15 @@ function App() {
     2000
   )
 
-  const allMessages = [
-    ...analyserMessages,
-    ...optimistMessages,
-    ...criticMessages,
-  ]
+  const hasOptimist = optimistMessages.length > 0
+  const hasCritic = criticMessages.length > 0
+  const hasWorkerMessages = hasOptimist || hasCritic
+  const hasBothWorkers = hasOptimist && hasCritic
+  // First analyser message is the intro; the rest is synthesis after workers
+  const analyserIntro = analyserMessages.slice(0, 1)
+  const analyserSynthesis = hasWorkerMessages
+    ? analyserMessages.slice(1).filter((m) => m.text.trim() !== `waiting`)
+    : []
 
   useEffect(() => {
     const el = bottomRef.current?.parentElement
@@ -177,6 +325,8 @@ function App() {
         optimistUrl: string
         criticUrl: string
       }
+      const id = data.entityUrl.split(`/`).pop()!
+      window.location.hash = id
       setUrls(data)
     } catch (err) {
       console.error(`Analyze failed:`, err)
@@ -186,12 +336,13 @@ function App() {
   }
 
   return (
-    <Theme appearance="light" accentColor="blue" radius="medium">
+    <>
       <style>{`@keyframes blink { 50% { opacity: 0; } }`}</style>
-      <Box maxWidth="700px" mx="auto" p="5">
-        <Heading size="6" mb="1">
-          Perspectives Analyzer
-        </Heading>
+      <Box maxWidth="900px" mx="auto" p="5">
+        <Flex justify="between" align="center" mb="1">
+          <Heading size="6">Perspectives Analyzer</Heading>
+          <ThemeToggle />
+        </Flex>
         <Text size="2" color="gray" mb="5" as="p">
           Ask a question and get two perspectives — an optimist and a critic —
           then a balanced analysis.
@@ -217,19 +368,73 @@ function App() {
         </Flex>
 
         <Flex direction="column" gap="3">
-          {urls && allMessages.length === 0 && (
+          {urls && analyserIntro.length === 0 && (
             <Text color="gray" size="2">
               Waiting for agents to respond...
             </Text>
           )}
-          {allMessages.map((msg, i) => (
-            <MessageBubble key={`${msg.agent}-${i}`} msg={msg} />
+
+          {/* Analyser intro — full width */}
+          {analyserIntro.map((msg, i) => (
+            <MessageBubble
+              key={`analyser-intro-${i}`}
+              msg={hasWorkerMessages ? { ...msg, isStreaming: false } : msg}
+            />
           ))}
+
+          {/* Workers — single column until both respond, then side-by-side */}
+          {hasWorkerMessages && !hasBothWorkers && (
+            <Flex direction="column" gap="3">
+              {optimistMessages.map((msg, i) => (
+                <MessageBubble key={`optimist-${i}`} msg={msg} />
+              ))}
+              {criticMessages.map((msg, i) => (
+                <MessageBubble key={`critic-${i}`} msg={msg} />
+              ))}
+            </Flex>
+          )}
+          {hasBothWorkers && (
+            <Flex gap="3">
+              <Flex direction="column" gap="3" style={{ flex: 1, minWidth: 0 }}>
+                {optimistMessages.map((msg, i) => (
+                  <MessageBubble key={`optimist-${i}`} msg={msg} />
+                ))}
+              </Flex>
+              <Flex direction="column" gap="3" style={{ flex: 1, minWidth: 0 }}>
+                {criticMessages.map((msg, i) => (
+                  <MessageBubble key={`critic-${i}`} msg={msg} />
+                ))}
+              </Flex>
+            </Flex>
+          )}
+
+          {/* Analyser synthesis — full width */}
+          {analyserSynthesis.map((msg, i) => (
+            <MessageBubble key={`analyser-synth-${i}`} msg={msg} />
+          ))}
+
           <div ref={bottomRef} />
         </Flex>
       </Box>
+    </>
+  )
+}
+
+function ThemedApp() {
+  const { darkMode } = useDarkModeContext()
+  return (
+    <Theme
+      appearance={darkMode ? `dark` : `light`}
+      accentColor="blue"
+      radius="medium"
+    >
+      <App />
     </Theme>
   )
 }
 
-createRoot(document.getElementById(`root`)!).render(<App />)
+createRoot(document.getElementById(`root`)!).render(
+  <DarkModeProvider>
+    <ThemedApp />
+  </DarkModeProvider>
+)

package/skills/quickstart.md

@@ -152,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
 
@@ -214,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
 
@@ -283,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)],
       })
@@ -293,7 +293,7 @@ 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`
+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`
 
 ## Step 4: Server routes
 
@@ -303,104 +303,60 @@ Next, we'll turn this into a real app. The server.ts you've been running is a pl
 
 `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.
 
-Update `server.ts` — add the runtime server client and an `/api/analyze` route:
+Update `server.ts` — add the runtime server client import and an `/api/analyze` route:
+
+Add `createRuntimeServerClient` to your imports from `@electric-ax/agents-runtime`, then create a client instance:
 
 ```typescript
-import http from 'node:http'
-import path from 'node:path'
-import { fileURLToPath } from 'node:url'
 import {
   createEntityRegistry,
   createRuntimeHandler,
-  createRuntimeServerClient,
+  createRuntimeServerClient, // ← add this
 } from '@electric-ax/agents-runtime'
-import { createElectricTools } from './lib/electric-tools'
-import { registerPerspectives } from './entities/perspectives'
-
-try {
-  const here = path.dirname(fileURLToPath(import.meta.url))
-  process.loadEnvFile(path.resolve(here, '.env'))
-} catch {}
-
-if (!process.env.ANTHROPIC_API_KEY) {
-  console.warn(
-    '[app] ANTHROPIC_API_KEY is not set — agent.run() will throw on the first wake.'
-  )
-}
-
-const ELECTRIC_AGENTS_URL =
-  process.env.ELECTRIC_AGENTS_URL ?? 'http://localhost:4437'
-const PORT = Number(process.env.PORT ?? 3000)
-const SERVE_URL = process.env.SERVE_URL ?? `http://localhost:${PORT}`
 
-const registry = createEntityRegistry()
-registerPerspectives(registry)
-
-const runtime = createRuntimeHandler({
-  baseUrl: ELECTRIC_AGENTS_URL,
-  serveEndpoint: `${SERVE_URL}/webhook`,
-  registry,
-  createElectricTools,
-})
+// ... existing setup ...
 
 const client = createRuntimeServerClient({ baseUrl: ELECTRIC_AGENTS_URL })
+```
 
-async function readJson(req: http.IncomingMessage): Promise<unknown> {
-  const chunks: Array<Buffer> = []
-  for await (const chunk of req) chunks.push(chunk as Buffer)
-  return JSON.parse(Buffer.concat(chunks).toString('utf8'))
-}
+Then add this route handler inside `http.createServer`, after the existing `/webhook` handler:
 
-const server = http.createServer(async (req, res) => {
-  if (req.url === '/webhook' && req.method === 'POST') {
-    await runtime.onEnter(req, res)
-    return
-  }
+```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
+    }
 
-  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)}`
 
-      const id = `analysis-${crypto.randomUUID().slice(0, 8)}`
+    await client.spawnEntity({
+      type: 'perspectives',
+      id,
+      initialMessage: body.question,
+    })
 
-      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`,
       })
-
-      res.writeHead(200, { 'content-type': 'application/json' })
-      res.end(
-        JSON.stringify({
-          entityUrl: `/perspectives/${id}`,
-          optimistUrl: `/worker/${id}-optimist`,
-          criticUrl: `/worker/${id}-critic`,
-        })
-      )
-    } catch (err) {
-      res.writeHead(500, { 'content-type': 'application/json' })
-      res.end(
-        JSON.stringify({
-          error: err instanceof Error ? err.message : String(err),
-        })
-      )
-    }
-    return
+    )
+  } catch (err) {
+    res.writeHead(500, { 'content-type': 'application/json' })
+    res.end(
+      JSON.stringify({
+        error: err instanceof Error ? err.message : String(err),
+      })
+    )
   }
-
-  res.writeHead(404)
-  res.end()
-})
-
-server.listen(PORT, async () => {
-  await runtime.registerTypes()
-  console.log(`App server ready on port ${PORT}`)
-})
+  return
+}
 ```
 
 Test with curl:
@@ -414,7 +370,7 @@ curl -X POST http://localhost:3000/api/analyze \
 Then observe the spawned entity:
 
 ```bash
-pnpm electric-agents observe /perspectives/analysis-<id>
+npx electric-ax agents observe /perspectives/analysis-<id>
 ```
 
 **Key concepts:**
@@ -536,7 +492,7 @@ Blue for the analyser, green for the optimist, red for the critic. `Streamdown`
 
 ### Wiring it together
 
-The `App` component subscribes to all three entities and renders messages inline:
+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:
 
 ```tsx
 const analyserMessages = useAgentMessages(urls?.entityUrl ?? null, 'analyser')
@@ -547,14 +503,13 @@ const optimistMessages = useAgentMessages(
 )
 const criticMessages = useAgentMessages(urls?.criticUrl ?? null, 'critic', 2000)
 
-const allMessages = [
-  ...analyserMessages,
-  ...optimistMessages,
-  ...criticMessages,
-]
+const hasWorkerMessages =
+  optimistMessages.length > 0 || criticMessages.length > 0
+const analyserIntro = analyserMessages.slice(0, 1)
+const analyserSynthesis = hasWorkerMessages ? analyserMessages.slice(1) : []
 ```
 
-Workers get `retryMs=2000` because they're spawned asynchronously — the manager calls `analyze_question`, which spawns them, but they may not exist yet when the UI first tries to connect.
+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`.
 

package/docs/examples/mega-draw.md

@@ -1,106 +0,0 @@
----
-title: Mega Draw
-titleTemplate: '... - Electric Agents'
-description: >-
-  Multi-agent collaborative drawing example with coordinator-worker patterns and 100 tile agents.
-outline: [2, 3]
----
-
-# Mega Draw
-
-A collaborative multi-agent drawing app where 100 AI agents each own a tile of a shared 1000x1000 pixel canvas and work together to produce a drawing from a single text prompt. Located at `examples/mega-draw/` in the repository.
-
-## What it demonstrates
-
-- **Coordinator + worker pattern** at scale (1 coordinator spawning 100 tile agents)
-- **Custom drawing tools** --- `fill_rect`, `draw_line`, `draw_circle`, `fill_gradient`, `set_pixels`
-- **Shared canvas** --- in-memory pixel buffer flushed to PNG, served via a live viewer
-- **Follow-up instructions** --- send a new prompt and only affected tiles get re-instructed
-- **Two-pass workflow** --- coordinator does a quick first pass for backgrounds, then a detail pass
-
-## Architecture
-
-```
-User
-  │
-  │  spawn /coordinator/my-drawing
-  │  send "Draw a sunset over mountains"
-  ▼
-┌────────────────────────────────┐
-│       Coordinator Agent        │
-│  - Receives prompt             │
-│  - Plans composition + palette │
-│  - Spawns 100 tile agents      │
-│  - Can re-instruct tiles       │
-└──────────┬─────────────────────┘
-           │ spawn tile-agent (10×10 grid)
-           ▼
-┌────────┐ ┌────────┐
-│Tile 0,0│ │Tile 1,0│  ...  (10 columns)
-└────────┘ └────────┘
-┌────────┐ ┌────────┐
-│Tile 0,1│ │Tile 1,1│  ...
-└────────┘ └────────┘
-   ...        ...       (10 rows = 100 tiles)
-```
-
-Each tile agent:
-
-- Owns a 100x100 pixel region
-- Can **see** 50px beyond its borders (200x200 viewport) for edge coordination
-- Can only **draw** within its own tile
-- Receives drawing instructions from the coordinator
-
-## Key files
-
-### `src/server.ts`
-
-Entry point. Creates the registry, runtime handler, and two HTTP servers (one for the Electric Agents webhook, one for the canvas viewer).
-
-```ts
-const registry = createEntityRegistry()
-registerCoordinator(registry, WEB_PORT)
-registerTileAgent(registry)
-
-const runtime = createRuntimeHandler({
-  baseUrl: ELECTRIC_AGENTS_URL,
-  serveEndpoint: `${SERVE_URL}/webhook`,
-  registry,
-})
-```
-
-### `src/coordinator.ts`
-
-The coordinator entity. Defines two custom tools:
-
-- `set_drawing_plan` --- sets the composition description and color palette
-- `instruct_tile` --- spawns or re-instructs a tile agent with drawing directions
-
-### `src/tile-agent.ts`
-
-The tile agent entity. Each instance gets drawing tools scoped to its tile:
-
-- `read_viewport` --- see current pixel state (own tile + neighbors)
-- `fill_rect`, `draw_line`, `draw_circle`, `fill_gradient`, `set_pixels`
-
-All coordinates are tile-relative (0--99) and automatically clipped to tile bounds.
-
-## Running it
-
-```bash
-cd examples/mega-draw
-pnpm install
-cp ../../.env.template .env  # Set ANTHROPIC_API_KEY
-pnpm dev
-```
-
-Requires a running Electric Agents runtime server at `http://localhost:4437`.
-
-Then in another terminal:
-
-```bash
-npx electric-ax agents spawn /coordinator/my-drawing
-npx electric-ax agents send /coordinator/my-drawing 'Draw a sunset over mountains'
-```
-
-View the canvas live at `http://localhost:3000/my-drawing` --- it auto-refreshes as tiles draw.