@electric-ax/agents 0.1.5 → 0.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@electric-ax/agents",
-  "version": "0.1.5",
+  "version": "0.2.2",
   "description": "Built-in Electric Agents runtimes such as Horton and worker",
   "repository": {
     "type": "git",
@@ -29,26 +29,22 @@
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.78.0",
-    "@durable-streams/state": "npm:@electric-ax/durable-streams-state-beta@^0.3.0",
+    "@durable-streams/state": "npm:@electric-ax/durable-streams-state-beta@^0.3.1",
     "@mariozechner/pi-agent-core": "^0.70.2",
     "@mariozechner/pi-ai": "^0.70.2",
-    "@mozilla/readability": "^0.6.0",
     "@sinclair/typebox": "^0.34.48",
+    "agent-session-protocol": "^0.0.2",
     "better-sqlite3": "^11.10.0",
-    "jsdom": "^28.1.0",
     "nanoid": "^3.3.11",
     "pino": "^10.3.1",
     "pino-pretty": "^13.0.0",
     "sqlite-vec": "^0.1.9",
-    "turndown": "^7.2.2",
-    "turndown-plugin-gfm": "^1.0.2",
-    "@electric-ax/agents-runtime": "0.0.4"
+    "zod": "^4.3.6",
+    "@electric-ax/agents-runtime": "0.1.1"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",
-    "@types/jsdom": "^27.0.0",
     "@types/node": "^22.19.15",
-    "@types/turndown": "^5.0.6",
     "@vitest/coverage-v8": "^4.1.0",
     "tsdown": "^0.9.0",
     "typescript": "^5.0.0",
@@ -56,6 +52,7 @@
   },
   "files": [
     "dist",
+    "docs",
     "skills"
   ],
   "sideEffects": false,

package/skills/init.md

@@ -0,0 +1,71 @@
+---
+description: Scaffold a new Electric Agents app project and get oriented in the codebase
+whenToUse: User wants to create a new app, start a project, or scaffold an Electric Agents application
+keywords:
+  - init
+  - scaffold
+  - new project
+  - create app
+  - starter
+  - setup
+user-invocable: true
+argument-hint: '[project-name]'
+arguments:
+  - project_name
+max: 15000
+---
+
+# Init: Create a New Electric Agents App
+
+Help the user scaffold and understand a new Electric Agents project.
+
+## Flow
+
+### 1. Assess experience
+
+Before scaffolding, ask the user:
+
+> "Are you familiar with Electric Agents concepts (entities, handlers, spawning workers)? If not, I can walk you through a hands-on quickstart first — or we can dive straight into setting up your project."
+
+- If they want the quickstart → load the quickstart skill with `use_skill("quickstart")`
+- If they want to dive in → continue to step 2
+
+### 2. Scaffold the project
+
+**Ask the user where they want the project.** Suggest a sensible default (e.g., `./$project_name` relative to the working directory) but let them choose. Do not create files or directories until the user confirms the location.
+
+If `$project_name` is not provided, ask the user what they'd like to name their project.
+
+Run the init command to create the project:
+
+```
+npx electric-ax agents init $project_name
+```
+
+After the command completes, read the generated project structure to orient yourself.
+
+### 3. Orient the user
+
+Walk through what was created. Read the key files and explain:
+
+- **Project structure** — what each directory and file is for
+- **Entity definitions** — where entity types are defined (e.g., `src/server/` or `entities/`)
+- **Server setup** — how the HTTP server and webhook handler work
+- **Frontend** — how the UI connects to the agent backend (if applicable)
+- **Running it** — the commands to start the dev server
+
+Keep explanations concise. The user can ask follow-up questions.
+
+### 4. Customize
+
+Ask the user what they want to build:
+
+> "What kind of app are you thinking of building? I can help you customize the starter — rename entity types, add new ones, adjust the tools, or modify the UI."
+
+Help them make their first changes to the scaffolded project.
+
+## Rules
+
+- Always read generated files before explaining them — don't assume the scaffold output.
+- If the init command doesn't exist or fails, fall back to manual scaffolding: create the project directory, set up package.json, install dependencies, and create a basic server.ts using the pattern from the quickstart skill's scaffold directory.
+- Don't overwhelm with information. Give a high-level overview first, then go deeper when asked.

package/skills/quickstart/scaffold/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "my-electric-agents-app",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "start": "tsx 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",
+    "@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",
+    "vite": "^7.2.4"
+  }
+}

package/skills/{tutorial → quickstart}/scaffold/tsconfig.json

@@ -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

@@ -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

@@ -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

@@ -0,0 +1,235 @@
+import { useState, useEffect, useRef } 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,
+} from '@radix-ui/themes'
+import { Streamdown } from 'streamdown'
+import '@radix-ui/themes/styles.css'
+import 'streamdown/styles.css'
+import type { EntityStreamDB } from '@electric-ax/agents-runtime'
+
+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 App() {
+  const [question, setQuestion] = useState(``)
+  const [urls, setUrls] = useState<{
+    entityUrl: string
+    optimistUrl: string
+    criticUrl: string
+  } | null>(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 allMessages = [
+    ...analyserMessages,
+    ...optimistMessages,
+    ...criticMessages,
+  ]
+
+  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
+      }
+      setUrls(data)
+    } catch (err) {
+      console.error(`Analyze failed:`, err)
+    } finally {
+      setLoading(false)
+    }
+  }
+
+  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>
+        <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 && allMessages.length === 0 && (
+            <Text color="gray" size="2">
+              Waiting for agents to respond...
+            </Text>
+          )}
+          {allMessages.map((msg, i) => (
+            <MessageBubble key={`${msg.agent}-${i}`} msg={msg} />
+          ))}
+          <div ref={bottomRef} />
+        </Flex>
+      </Box>
+    </Theme>
+  )
+}
+
+createRoot(document.getElementById(`root`)!).render(<App />)