@electric-ax/agents 0.2.3 → 0.2.4

package/docs/usage/testing.md

@@ -1,6 +1,6 @@
 ---
 title: Testing
-titleTemplate: '... - Electric Agents'
+titleTemplate: "... - Electric Agents"
 description: >-
   Test entity handlers with testResponses for LLM mocking, plus unit and integration testing patterns.
 outline: [2, 3]
@@ -14,10 +14,10 @@ Test agent handlers without calling the LLM by providing canned responses:
 
 ```ts
 ctx.useAgent({
-  systemPrompt: '...',
-  model: 'claude-sonnet-4-5-20250929',
+  systemPrompt: "...",
+  model: "claude-sonnet-4-5-20250929",
   tools: [...ctx.electricTools],
-  testResponses: ['Hello! How can I help?'],
+  testResponses: ["Hello! How can I help?"],
 })
 await ctx.agent.run()
 ```
@@ -31,9 +31,9 @@ For dynamic test responses, provide a function instead of an array:
 ```ts
 testResponses: async (message, bridge) => {
   bridge.onTextStart()
-  bridge.onTextDelta('Test response')
+  bridge.onTextDelta("Test response")
   bridge.onTextEnd()
-  return 'Test response'
+  return "Test response"
 }
 ```
 
@@ -46,28 +46,28 @@ The runtime wraps your `TestResponseFn` with `bridge.onRunStart()` / `bridge.onR
 ## Unit testing entity registration
 
 ```ts
-import { createEntityRegistry } from '@electric-ax/agents-runtime'
+import { createEntityRegistry } from "@electric-ax/agents-runtime"
 
 const registry = createEntityRegistry()
 registerAssistant(registry)
 
-test('registers assistant', () => {
-  const entry = registry.get('assistant')
+test("registers assistant", () => {
+  const entry = registry.get("assistant")
   expect(entry).toBeDefined()
-  expect(entry!.definition.handler).toBeTypeOf('function')
+  expect(entry!.definition.handler).toBeTypeOf("function")
 })
 ```
 
 ## Unit testing runtime creation
 
 ```ts
-test('creates runtime with types', () => {
+test("creates runtime with types", () => {
   const runtime = createRuntimeHandler({
-    baseUrl: 'http://localhost:4437',
-    serveEndpoint: 'http://localhost:3000/webhook',
+    baseUrl: "http://localhost:4437",
+    serveEndpoint: "http://localhost:3000/webhook",
     registry,
   })
-  expect(runtime.typeNames).toContain('assistant')
+  expect(runtime.typeNames).toContain("assistant")
 })
 ```
 

package/docs/usage/waking-entities.md

@@ -1,6 +1,6 @@
 ---
 title: Waking entities
-titleTemplate: '... - Electric Agents'
+titleTemplate: "... - Electric Agents"
 description: >-
   How entity handlers get invoked - the triggers that produce wakes, how wake config threads through spawn/observe/observe(db(...)), and how to read a WakeEvent in a handler.
 outline: [2, 3]
@@ -23,7 +23,7 @@ external event  ─►  wake entry (persisted)  ─►  handler invocation  ─
 3. **Handler is invoked.** The runtime picks up the wake, loads the entity's state, and calls your handler with a `WakeEvent` describing what triggered this invocation.
 4. **Handler runs.** You read `ctx.events`, inspect `wake`, configure the agent, emit new events. When the handler returns (or calls `ctx.sleep()`), the entity goes idle until the next wake.
 
-This means handlers are re-entrant: the same handler function is called fresh on every wake. Use `ctx.firstWake` for one-time initialization, and `ctx.db.actions` / `ctx.db.collections` to carry state across wakes.
+This means handlers are re-entrant: the same handler function is called fresh on every wake. Use `ctx.db.actions` / `ctx.db.collections` to carry state across wakes, and make one-time writes idempotent by checking existing state. `ctx.firstWake` is for the initial setup pass while no manifest entries exist.
 
 ## What produces a wake
 
@@ -34,7 +34,7 @@ There are five things that can wake an entity:
 Any external `/send` (via the CLI, HTTP, or another entity's `ctx.send()`) appends a `message_received` event to the entity's stream, which wakes the handler:
 
 ```ts
-ctx.send('/assistant/peer', { text: 'hello' })
+ctx.send("/assistant/peer", { text: "hello" })
 ```
 
 The receiving handler sees `wake.type === "message_received"` and finds the payload on `wake.payload`.
@@ -45,12 +45,12 @@ Pass `wake` when spawning a child to control when the parent wakes:
 
 ```ts
 const child = await ctx.spawn(
-  'worker',
-  'analysis-1',
-  { systemPrompt: 'Analyse this input.', tools: ['read'] },
+  "worker",
+  "analysis-1",
+  { systemPrompt: "Analyse this input.", tools: ["read"] },
   {
-    initialMessage: 'begin',
-    wake: { on: 'runFinished', includeResponse: true },
+    initialMessage: "begin",
+    wake: { on: "runFinished", includeResponse: true },
   }
 )
 ```
@@ -62,10 +62,10 @@ See the full catalog of `Wake` values in [WakeEvent](../reference/wake-event#wak
 `ctx.observe()` subscribes to another entity's stream without spawning it. Pair it with a `wake` option to re-invoke this handler when the observed stream changes:
 
 ```ts
-import { entity } from '@electric-ax/agents-runtime'
+import { entity } from "@electric-ax/agents-runtime"
 
 await ctx.observe(entity(someEntityUrl), {
-  wake: { on: 'change', collections: ['status'], debounceMs: 250 },
+  wake: { on: "change", collections: ["status"], debounceMs: 250 },
 })
 ```
 
@@ -76,8 +76,8 @@ The `entity()` helper wraps a raw URL string into the correct observe target typ
 `observe(db(...))` connects to a shared-state stream and, with `wake`, re-wakes the connecting entity when its collections change:
 
 ```ts
-await ctx.observe(db('board-1', schema), {
-  wake: { on: 'change', collections: ['findings'] },
+await ctx.observe(db("board-1", schema), {
+  wake: { on: "change", collections: ["findings"] },
 })
 ```
 
@@ -123,7 +123,7 @@ Multiple external events that arrive while an entity is busy (or between acks) a
 
 - A wake covers a contiguous range of offsets in the source stream (`wake.fromOffset`..`wake.toOffset`).
 - `wake.eventCount` tells you how many new events this wake represents.
-- Handlers must be safe to re-run with the same input — at-least-once delivery. Use `ctx.firstWake` and idempotent writes to collections rather than side effects on each wake.
+- Handlers must be safe to re-run with the same input — at-least-once delivery. Prefer idempotent writes to collections over side effects on each wake.
 
 If you need to deduplicate explicitly, key your writes by something stable (the child's entity URL, the message's producer/epoch/seq headers, etc.) and let the collection's primary key do the dedup.
 

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]
@@ -57,11 +57,16 @@ interface HandlerContext<TState extends StateProxy = StateProxy> {
     id: string,
     schema: T
   ) => SharedStateHandle<T>
+  useCodingAgent: (
+    sessionId: string,
+    opts: UseCodingAgentOptions
+  ) => Promise<CodingSessionHandle>
   send: (
     entityUrl: string,
     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 +77,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 +86,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).                                      |
@@ -93,7 +98,9 @@ interface HandlerContext<TState extends StateProxy = StateProxy> {
 | `spawn`            | Creates a child entity. See [Spawning and coordinating](./spawning-and-coordinating).                                                                   |
 | `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).                                                                                  |
+| `useCodingAgent`   | Spawns or attaches to a built-in `coder` entity backed by Claude Code or Codex.                                                                          |
 | `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 +122,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 +170,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 +213,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 +291,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.2.4",
   "description": "Built-in Electric Agents runtimes such as Horton and worker",
   "repository": {
     "type": "git",
@@ -53,6 +53,7 @@
   "files": [
     "dist",
     "docs",
+    "scripts",
     "skills"
   ],
   "sideEffects": false,
@@ -60,6 +61,8 @@
   "scripts": {
     "build": "tsdown",
     "dev": "tsdown --watch",
+    "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.