npm - @electric-ax/agents - Versions diffs - 0.2.1 → 0.2.3 - Mend

@electric-ax/agents 0.2.1 → 0.2.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (49) hide show

package/dist/entrypoint.js +5 -3
package/dist/index.cjs +5 -3
package/dist/index.js +5 -3
package/docs/entities/agents/horton.md +89 -0
package/docs/entities/agents/worker.md +102 -0
package/docs/entities/patterns/blackboard.md +111 -0
package/docs/entities/patterns/dispatcher.md +77 -0
package/docs/entities/patterns/manager-worker.md +127 -0
package/docs/entities/patterns/map-reduce.md +81 -0
package/docs/entities/patterns/pipeline.md +101 -0
package/docs/entities/patterns/reactive-observers.md +125 -0
package/docs/examples/mega-draw.md +106 -0
package/docs/examples/playground.md +46 -0
package/docs/index.md +208 -0
package/docs/quickstart.md +201 -0
package/docs/reference/agent-config.md +82 -0
package/docs/reference/agent-tool.md +58 -0
package/docs/reference/built-in-collections.md +334 -0
package/docs/reference/cli.md +238 -0
package/docs/reference/entity-definition.md +57 -0
package/docs/reference/entity-handle.md +63 -0
package/docs/reference/entity-registry.md +73 -0
package/docs/reference/handler-context.md +108 -0
package/docs/reference/runtime-handler.md +136 -0
package/docs/reference/shared-state-handle.md +74 -0
package/docs/reference/state-collection-proxy.md +41 -0
package/docs/reference/wake-event.md +132 -0
package/docs/usage/app-setup.md +165 -0
package/docs/usage/clients-and-react.md +191 -0
package/docs/usage/configuring-the-agent.md +136 -0
package/docs/usage/context-composition.md +204 -0
package/docs/usage/defining-entities.md +181 -0
package/docs/usage/defining-tools.md +229 -0
package/docs/usage/embedded-builtins.md +180 -0
package/docs/usage/managing-state.md +93 -0
package/docs/usage/overview.md +284 -0
package/docs/usage/programmatic-runtime-client.md +216 -0
package/docs/usage/shared-state.md +169 -0
package/docs/usage/spawning-and-coordinating.md +165 -0
package/docs/usage/testing.md +76 -0
package/docs/usage/waking-entities.md +148 -0
package/docs/usage/writing-handlers.md +267 -0
package/package.json +3 -2
package/skills/quickstart/scaffold/package.json +17 -3
package/skills/quickstart/scaffold/tsconfig.json +8 -3
package/skills/quickstart/scaffold/vite.config.ts +21 -0
package/skills/quickstart/scaffold-ui/index.html +12 -0
package/skills/quickstart/scaffold-ui/main.tsx +440 -0
package/skills/quickstart.md +209 -344

package/skills/quickstart/scaffold/package.json CHANGED Viewed

@@ -4,14 +4,28 @@
   "type": "module",
   "scripts": {
     "start": "tsx server.ts",
-    "dev": "tsx --watch server.ts"
+    "dev": "tsx --watch server.ts",
+    "dev:server": "tsx --watch server.ts",
+    "dev:ui": "vite",
+    "dev:all": "npm run dev:server & npm run dev:ui"
   },
   "dependencies": {
     "@electric-ax/agents-runtime": "latest",
-    "@sinclair/typebox": "^0.34.49"
+    "@radix-ui/react-icons": "^1.3.0",
+    "@radix-ui/themes": "^3.3.0",
+    "@sinclair/typebox": "^0.34.49",
+    "@tanstack/db": "^0.6.0",
+    "@tanstack/react-db": "^0.1.78",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "streamdown": "^2.5.0"
   },
   "devDependencies": {
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^5.2.0",
     "tsx": "^4.19.0",
-    "typescript": "^5.7.0"
+    "typescript": "^5.7.0",
+    "vite": "^7.2.4"
   }
 }

package/skills/quickstart/scaffold/tsconfig.json CHANGED Viewed

@@ -3,13 +3,18 @@
     "target": "ES2022",
     "module": "ESNext",
     "moduleResolution": "bundler",
+    "jsx": "react-jsx",
     "strict": true,
     "esModuleInterop": true,
     "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
     "resolveJsonModule": true,
-    "allowImportingTsExtensions": false,
-    "noEmit": true
+    "isolatedModules": true,
+    "noEmit": true,
+    "paths": {
+      "@tanstack/db": ["./node_modules/@tanstack/db"]
+    }
   },
-  "include": ["**/*.ts"],
+  "include": ["**/*.ts", "**/*.tsx"],
   "exclude": ["node_modules"]
 }

package/skills/quickstart/scaffold/vite.config.ts ADDED Viewed

@@ -0,0 +1,21 @@
+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,
+    proxy: { '/api': `http://localhost:3000` },
+  },
+  build: { outDir: `../dist`, emptyOutDir: true },
+})

package/skills/quickstart/scaffold-ui/index.html ADDED Viewed

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Perspectives Analyzer</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="./main.tsx"></script>
+  </body>
+</html>

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

@@ -0,0 +1,440 @@
+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'
+import {
+  Theme,
+  Box,
+  Flex,
+  Heading,
+  Text,
+  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 }> = {
+  analyser: { bg: `var(--blue-3)`, border: `var(--blue-6)` },
+  optimist: { bg: `var(--green-3)`, border: `var(--green-6)` },
+  critic: { bg: `var(--red-3)`, border: `var(--red-6)` },
+}
+function useEntityDb(url: string | null, retryMs = 0) {
+  const [db, setDb] = useState<EntityStreamDB | null>(null)
+  useEffect(() => {
+    if (!url) {
+      setDb(null)
+      return
+    }
+    let cancelled = false
+    let observedDb: EntityStreamDB | null = null
+    let timer: ReturnType<typeof setTimeout> | null = null
+    const connect = () => {
+      const client = createAgentsClient({ baseUrl: AGENTS_URL })
+      client.observe(entity(url)).then(
+        (observed) => {
+          observedDb = observed as EntityStreamDB
+          if (cancelled) {
+            observedDb.close()
+            return
+          }
+          setDb(observedDb)
+        },
+        () => {
+          if (!cancelled && retryMs > 0) {
+            timer = setTimeout(connect, retryMs)
+          }
+        }
+      )
+    }
+    connect()
+    return () => {
+      cancelled = true
+      if (timer) clearTimeout(timer)
+      observedDb?.close()
+    }
+  }, [url, retryMs])
+  return db
+}
+interface AgentMessage {
+  agent: string
+  text: string
+  isStreaming: boolean
+}
+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,
+      }))
+  )
+}
+function MessageBubble({ msg }: { msg: AgentMessage }) {
+  const colors = AGENT_COLORS[msg.agent] ?? {
+    bg: `var(--gray-3)`,
+    border: `var(--gray-6)`,
+  }
+  return (
+    <Card
+      size="1"
+      style={{
+        background: colors.bg,
+        borderLeft: `3px solid ${colors.border}`,
+      }}
+    >
+      <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>
+  )
+}
+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>(() => {
+    const id = getIdFromHash()
+    return id ? urlsFromId(id) : null
+  })
+  const [loading, setLoading] = useState(false)
+  const bottomRef = useRef<HTMLDivElement>(null)
+  const analyserMessages = useAgentMessages(urls?.entityUrl ?? null, `analyser`)
+  const optimistMessages = useAgentMessages(
+    urls?.optimistUrl ?? null,
+    `optimist`,
+    2000
+  )
+  const criticMessages = useAgentMessages(
+    urls?.criticUrl ?? null,
+    `critic`,
+    2000
+  )
+  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
+    if (!el) return
+    const observer = new MutationObserver(() => {
+      window.scrollTo({ top: document.body.scrollHeight, behavior: `smooth` })
+    })
+    observer.observe(el, {
+      childList: true,
+      subtree: true,
+      characterData: true,
+    })
+    return () => observer.disconnect()
+  }, [urls])
+  const handleAnalyze = async () => {
+    if (!question.trim()) return
+    setLoading(true)
+    try {
+      const res = await fetch(`/api/analyze`, {
+        method: `POST`,
+        headers: { 'Content-Type': `application/json` },
+        body: JSON.stringify({ question }),
+      })
+      const data = (await res.json()) as {
+        entityUrl: string
+        optimistUrl: string
+        criticUrl: string
+      }
+      const id = data.entityUrl.split(`/`).pop()!
+      window.location.hash = id
+      setUrls(data)
+    } catch (err) {
+      console.error(`Analyze failed:`, err)
+    } finally {
+      setLoading(false)
+    }
+  }
+  return (
+    <>
+      <style>{`@keyframes blink { 50% { opacity: 0; } }`}</style>
+      <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.
+        </Text>
+        <Flex gap="2" mb="5">
+          <Box flexGrow="1">
+            <TextField.Root
+              size="3"
+              placeholder="Enter a question to analyze..."
+              value={question}
+              onChange={(e) => setQuestion(e.target.value)}
+              onKeyDown={(e) => e.key === `Enter` && handleAnalyze()}
+            />
+          </Box>
+          <Button
+            size="3"
+            onClick={handleAnalyze}
+            disabled={loading || !question.trim()}
+          >
+            {loading ? `Analyzing...` : `Analyze`}
+          </Button>
+        </Flex>
+        <Flex direction="column" gap="3">
+          {urls && analyserIntro.length === 0 && (
+            <Text color="gray" size="2">
+              Waiting for agents to respond...
+            </Text>
+          )}
+          {/* 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(
+  <DarkModeProvider>
+    <ThemedApp />
+  </DarkModeProvider>
+)