@electric-ax/agents 0.2.3 → 0.3.0

package/docs/usage/writing-handlers.md

@@ -1,6 +1,6 @@
 ---
 title: Writing handlers
-titleTemplate: '... - Electric Agents'
+titleTemplate: "... - Electric Agents"
 description: >-
   Implement entity handlers using HandlerContext and WakeEvent, with patterns for first wake, messaging, and tool use.
 outline: [2, 3]
@@ -62,6 +62,7 @@ interface HandlerContext<TState extends StateProxy = StateProxy> {
     payload: unknown,
     opts?: { type?: string; afterMs?: number }
   ) => void
+  recordRun: () => RunHandle
   setTag: (key: string, value: string) => Promise<void>
   removeTag: (key: string) => Promise<void>
   sleep: () => void
@@ -72,7 +73,7 @@ interface HandlerContext<TState extends StateProxy = StateProxy> {
 
 | Property           | Description                                                                                                                                             |
 | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `firstWake`        | `true` on the entity's first activation ever. Use for initialization.                                                                                   |
+| `firstWake`        | `true` during the initial setup pass while the entity has no persisted manifest entries. Use state checks for one-time plain state initialization.       |
 | `tags`             | Entity tags -- key/value metadata associated with this entity.                                                                                          |
 | `entityUrl`        | The entity's URL path, e.g. `"/assistant/my-chat"`.                                                                                                     |
 | `entityType`       | The registered type name, e.g. `"assistant"`.                                                                                                           |
@@ -81,7 +82,7 @@ interface HandlerContext<TState extends StateProxy = StateProxy> {
 | `state`            | Proxy object keyed by collection name. Each property is a [`StateCollectionProxy`](../reference/state-collection-proxy).                                |
 | `events`           | Change events that triggered this wake.                                                                                                                 |
 | `actions`          | Custom non-CRUD action functions from the entity definition's `actions` factory.                                                                        |
-| `electricTools`    | Host-provided runtime-level tools to pass to `useAgent` when needed. May be empty.                                                                      |
+| `electricTools`       | Host-provided runtime-level tools to pass to `useAgent` when needed. May be empty.                                                                      |
 | `useAgent`         | Configures the LLM agent. Returns an `AgentHandle`. See [Configuring the agent](./configuring-the-agent).                                               |
 | `useContext`       | Declares context sources with token budgets and cache tiers. See [Context composition](./context-composition).                                          |
 | `timelineMessages` | Projects the entity timeline into LLM messages. See [Context composition](./context-composition#timelinemessages).                                      |
@@ -94,6 +95,7 @@ interface HandlerContext<TState extends StateProxy = StateProxy> {
 | `observe`          | Connects to another entity's stream or shared db. See [Reactive observers](../entities/patterns/reactive-observers) and [Shared state](./shared-state). |
 | `mkdb`             | Creates a new shared state stream. See [Shared state](./shared-state).                                                                                  |
 | `send`             | Sends a message to another entity's inbox. Supports delayed delivery via `afterMs`.                                                                     |
+| `recordRun`        | Records non-LLM work in the built-in `runs` collection so `runFinished` observers are woken.                                                            |
 | `setTag`           | Sets a tag on this entity.                                                                                                                              |
 | `removeTag`        | Removes a tag from this entity.                                                                                                                         |
 | `sleep`            | Returns the entity to idle without re-waking.                                                                                                           |
@@ -115,36 +117,36 @@ type WakeEvent = {
 }
 ```
 
-| Field        | Description                                                                                                                    |
-| ------------ | ------------------------------------------------------------------------------------------------------------------------------ |
-| `source`     | The stream or entity that caused the wake.                                                                                     |
+| Field        | Description                                                    |
+| ------------ | -------------------------------------------------------------- |
+| `source`     | The stream or entity that caused the wake.                     |
 | `type`       | The wake type: `"message_received"` for inbox messages or `"wake"` for child completion, observed changes, cron, and timeouts. |
-| `fromOffset` | Start offset of the events that triggered this wake.                                                                           |
-| `toOffset`   | End offset of the events that triggered this wake.                                                                             |
-| `eventCount` | Number of new events since last wake.                                                                                          |
-| `payload`    | Optional payload from the trigger event.                                                                                       |
-| `summary`    | Optional human-readable summary.                                                                                               |
-| `fullRef`    | Optional full reference string for the trigger.                                                                                |
+| `fromOffset` | Start offset of the events that triggered this wake.           |
+| `toOffset`   | End offset of the events that triggered this wake.             |
+| `eventCount` | Number of new events since last wake.                          |
+| `payload`    | Optional payload from the trigger event.                       |
+| `summary`    | Optional human-readable summary.                               |
+| `fullRef`    | Optional full reference string for the trigger.                |
 
 ## Typical handler pattern
 
-Most handlers follow the same structure: initialize state on first wake, configure the agent, run the agent.
+Most LLM handlers follow the same structure: initialize missing state idempotently, configure the agent, run the agent.
 
 ```ts
-registry.define('assistant', {
-  description: 'A general-purpose assistant',
+registry.define("assistant", {
+  description: "A general-purpose assistant",
   state: {
-    status: { primaryKey: 'key' },
+    status: { primaryKey: "key" },
   },
 
   async handler(ctx) {
-    if (ctx.firstWake) {
-      ctx.db.actions.status_insert({ row: { key: 'current', value: 'idle' } })
+    if (!ctx.db.collections.status.get("current")) {
+      ctx.db.actions.status_insert({ row: { key: "current", value: "idle" } })
     }
 
     ctx.useAgent({
-      systemPrompt: 'You are a helpful assistant.',
-      model: 'claude-sonnet-4-5-20250929',
+      systemPrompt: "You are a helpful assistant.",
+      model: "claude-sonnet-4-5-20250929",
       tools: [...ctx.electricTools],
     })
     await ctx.agent.run()
@@ -163,25 +165,31 @@ interface AgentConfig {
   provider?: KnownProvider
   tools: AgentTool[]
   streamFn?: StreamFn
+  getApiKey?: (provider: string) => Promise<string | undefined> | string | undefined
+  onPayload?: SimpleStreamOptions["onPayload"]
   testResponses?: string[] | TestResponseFn
 }
 ```
 
-## firstWake
+## firstWake and initialization
 
-`ctx.firstWake` is `true` only on the entity's very first activation. Use it for one-time initialization:
+`ctx.firstWake` is `true` during the initial setup pass while the entity has no persisted manifest entries. It is useful for setup that creates manifest-backed resources such as `ctx.spawn()`, `ctx.observe()`, `ctx.mkdb()`, context entries, or schedules.
+
+For plain state rows, prefer checking the collection itself so initialization stays idempotent even for entities that do not create manifest entries:
 
 ```ts
 async handler(ctx) {
-  if (ctx.firstWake) {
+  if (!ctx.db.collections.status.get("current")) {
     ctx.db.actions.status_insert({ row: { key: 'current', value: 'idle' } })
+  }
+  if (!ctx.db.collections.counters.get("runs")) {
     ctx.db.actions.counters_insert({ row: { key: 'runs', value: 0 } })
   }
   // ...
 }
 ```
 
-On subsequent wakes (new messages, child completion, etc.), `firstWake` is `false`.
+After an entity persists manifest entries, subsequent wakes set `firstWake` to `false`.
 
 ## sleep
 
@@ -200,6 +208,24 @@ async handler(ctx, wake) {
 }
 ```
 
+## recordRun
+
+Call `ctx.recordRun()` when a handler does work without `ctx.agent.run()` but still needs to publish run lifecycle events. This is how non-LLM entities can wake parents observing them with `wake: "runFinished"`.
+
+```ts
+async handler(ctx) {
+  const run = ctx.recordRun()
+  try {
+    const result = await runExternalJob()
+    run.attachResponse(result.summary)
+    run.end({ status: "completed" })
+  } catch (error) {
+    run.end({ status: "failed", finishReason: "error" })
+    throw error
+  }
+}
+```
+
 ## Using spawn args
 
 Arguments passed at spawn time are available as `ctx.args`. This is how you parameterize entity behavior:
@@ -260,8 +286,8 @@ async handler(ctx) {
 Use `ctx.send()` to deliver a message to another entity's inbox:
 
 ```ts
-ctx.send('/worker/task-1', { action: 'process', data: payload })
-ctx.send('/worker/task-1', payload, { type: 'custom_type' })
+ctx.send("/worker/task-1", { action: "process", data: payload })
+ctx.send("/worker/task-1", payload, { type: "custom_type" })
 ```
 
 The target entity will be woken to process the message.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@electric-ax/agents",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "Built-in Electric Agents runtimes such as Horton and worker",
   "repository": {
     "type": "git",
@@ -28,31 +28,33 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@anthropic-ai/sdk": "^0.78.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",
     "@sinclair/typebox": "^0.34.48",
-    "agent-session-protocol": "^0.0.2",
     "better-sqlite3": "^11.10.0",
     "nanoid": "^3.3.11",
     "pino": "^10.3.1",
     "pino-pretty": "^13.0.0",
     "sqlite-vec": "^0.1.9",
     "zod": "^4.3.6",
-    "@electric-ax/agents-runtime": "0.1.2"
+    "@electric-ax/agents-mcp": "0.2.0",
+    "@electric-ax/agents-runtime": "0.1.3"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^22.19.15",
     "@vitest/coverage-v8": "^4.1.0",
+    "cross-env": "^10.1.0",
     "tsdown": "^0.9.0",
+    "tsx": "^4.19.0",
     "typescript": "^5.0.0",
     "vitest": "^4.1.0"
   },
   "files": [
     "dist",
     "docs",
+    "scripts",
     "skills"
   ],
   "sideEffects": false,
@@ -60,6 +62,9 @@
   "scripts": {
     "build": "tsdown",
     "dev": "tsdown --watch",
+    "start": "cross-env ELECTRIC_AGENTS_SERVER_URL=http://localhost:4437 tsx --watch src/entrypoint.ts",
+    "docs:sync": "node scripts/sync-docs.mjs",
+    "docs:clean": "node scripts/sync-docs.mjs --clean",
     "test": "vitest run",
     "coverage": "pnpm exec vitest --coverage",
     "typecheck": "tsc --noEmit",

package/scripts/sync-docs.mjs

@@ -0,0 +1,42 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const packageRoot = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  `..`
+)
+const repoRoot = path.resolve(packageRoot, `../..`)
+const source = path.join(repoRoot, `website/docs/agents`)
+const target = path.join(packageRoot, `docs`)
+
+async function pathExists(value) {
+  try {
+    await fs.access(value)
+    return true
+  } catch {
+    return false
+  }
+}
+
+async function clean() {
+  await fs.rm(target, { recursive: true, force: true })
+}
+
+if (process.argv.includes(`--clean`)) {
+  if (await pathExists(path.join(source, `index.md`))) {
+    await clean()
+  }
+} else {
+  if (!(await pathExists(path.join(source, `index.md`)))) {
+    if (await pathExists(path.join(target, `index.md`))) {
+      console.log(`Agents docs source not found; preserving ${target}`)
+      process.exit(0)
+    }
+    throw new Error(`Agents docs source not found at ${source}`)
+  }
+
+  await clean()
+  await fs.cp(source, target, { recursive: true })
+  console.log(`Synced agents docs from ${source} to ${target}`)
+}

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.