@electric-ax/agents 0.1.4 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@electric-ax/agents",
-  "version": "0.1.4",
+  "version": "0.2.1",
   "description": "Built-in Electric Agents runtimes such as Horton and worker",
   "repository": {
     "type": "git",
@@ -29,33 +29,30 @@
   },
   "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",
     "vitest": "^4.1.0"
   },
   "files": [
-    "dist"
+    "dist",
+    "skills"
   ],
   "sideEffects": false,
   "license": "Apache-2.0",

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/lib/electric-tools.ts

@@ -0,0 +1,80 @@
+import { Type } from '@sinclair/typebox'
+import type { AgentTool } from '@electric-ax/agents-runtime'
+
+type CreateElectricToolsContext = {
+  entityUrl: string
+  entityType: string
+  args: Readonly<Record<string, unknown>>
+  upsertCronSchedule: (opts: {
+    id: string
+    expression: string
+    timezone?: string
+    payload?: unknown
+    debounceMs?: number
+    timeoutMs?: number
+  }) => Promise<{ txid: string }>
+  upsertFutureSendSchedule: (opts: {
+    id: string
+    payload: unknown
+    targetUrl?: string
+    fireAt: string
+    from?: string
+    messageType?: string
+  }) => Promise<{ txid: string }>
+  deleteSchedule: (opts: { id: string }) => Promise<{ txid: string }>
+}
+
+export function createElectricTools(
+  ctx: CreateElectricToolsContext
+): Array<AgentTool> {
+  return [
+    {
+      name: `upsert_cron_schedule`,
+      label: `Upsert Cron`,
+      description: `Create or update a recurring cron wake schedule.`,
+      parameters: Type.Object({
+        id: Type.String({ description: `Stable schedule identifier` }),
+        expression: Type.String({ description: `Cron expression` }),
+        timezone: Type.Optional(Type.String({ description: `IANA timezone` })),
+        payload: Type.Any({ description: `Instruction for the agent` }),
+      }),
+      execute: async (_toolCallId, params) => {
+        const { id, expression, timezone, payload } = params as any
+        const tz = timezone ?? `UTC`
+        const { txid } = await ctx.upsertCronSchedule({
+          id,
+          expression,
+          timezone: tz,
+          payload,
+        })
+        return {
+          content: [
+            { type: `text` as const, text: `Cron "${id}" set. txid=${txid}` },
+          ],
+          details: { txid },
+        }
+      },
+    },
+    {
+      name: `delete_schedule`,
+      label: `Delete Schedule`,
+      description: `Delete a schedule by id.`,
+      parameters: Type.Object({
+        id: Type.String({ description: `Schedule identifier` }),
+      }),
+      execute: async (_toolCallId, params) => {
+        const { id } = params as { id: string }
+        const { txid } = await ctx.deleteSchedule({ id })
+        return {
+          content: [
+            {
+              type: `text` as const,
+              text: `Schedule "${id}" deleted. txid=${txid}`,
+            },
+          ],
+          details: { txid },
+        }
+      },
+    },
+  ]
+}

package/skills/quickstart/scaffold/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "my-electric-agents-app",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "start": "tsx server.ts",
+    "dev": "tsx --watch server.ts"
+  },
+  "dependencies": {
+    "@electric-ax/agents-runtime": "latest",
+    "@sinclair/typebox": "^0.34.49"
+  },
+  "devDependencies": {
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0"
+  }
+}

package/skills/quickstart/scaffold/server.ts

@@ -0,0 +1,51 @@
+import http from 'node:http'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import {
+  createEntityRegistry,
+  createRuntimeHandler,
+} from '@electric-ax/agents-runtime'
+import { createElectricTools } from './lib/electric-tools'
+
+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()
+
+// Register your entity types here:
+// import { registerMyEntity } from "./entities/my-entity"
+// registerMyEntity(registry)
+
+const runtime = createRuntimeHandler({
+  baseUrl: ELECTRIC_AGENTS_URL,
+  serveEndpoint: `${SERVE_URL}/webhook`,
+  registry,
+  createElectricTools,
+})
+
+const server = http.createServer(async (req, res) => {
+  if (req.url === `/webhook` && req.method === `POST`) {
+    await runtime.onEnter(req, res)
+    return
+  }
+  res.writeHead(404)
+  res.end()
+})
+
+server.listen(PORT, async () => {
+  await runtime.registerTypes()
+  console.log(`App server ready on port ${PORT}`)
+})

package/skills/quickstart/scaffold/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "allowImportingTsExtensions": false,
+    "noEmit": true
+  },
+  "include": ["**/*.ts"],
+  "exclude": ["node_modules"]
+}