@electric-ax/agents 0.2.1 → 0.2.2

package/dist/entrypoint.js

@@ -796,6 +796,8 @@ function resolveDocsRoot(workingDirectory) {
 		process.env.HORTON_DOCS_ROOT,
 		path.resolve(workingDirectory, `electric-agents-docs/docs`),
 		path.resolve(process.cwd(), `electric-agents-docs/docs`),
+		path.resolve(MODULE_DIR, `../docs`),
+		path.resolve(MODULE_DIR, `../../docs`),
 		path.resolve(MODULE_DIR, `../../../../../electric-agents-docs/docs`)
 	].filter((value) => typeof value === `string`);
 	for (const candidate of candidates) if (fs.existsSync(candidate)) return candidate;
@@ -1637,7 +1639,7 @@ async function generateTitle(userMessage, llmCall = defaultHaikuCall) {
 function buildHortonSystemPrompt(workingDirectory, opts = {}) {
 	const docsTools = opts.hasDocsSupport ? `\n- search_durable_agents_docs: hybrid search over the built-in Durable Agents docs index` : ``;
 	const skillsTools = opts.hasSkills ? `\n- use_skill: load a skill (knowledge, instructions, or a tutorial) into your context to help with the user's request\n- remove_skill: unload a skill from context when you're done with it` : ``;
-	const docsGuidance = opts.hasDocsSupport ? `\n- You have built-in Durable Agents docs context plus a docs search tool. Use that before broad web search when the question is about this repo, Electric Agents, or Durable Agents.\n- The docs TOC and docs search results include concrete file paths under the docs tree. Use the normal read tool with those returned paths.\n- Use repo read/bash tools for non-doc files or when you need to inspect exact implementation code in the workspace.` : ``;
+	const docsGuidance = opts.hasDocsSupport ? `\n- For ANY question about Electric Agents, Durable Agents, or this framework, ALWAYS use search_durable_agents_docs FIRST. Do not use brave_search or fetch_url for Electric Agents topics unless the docs search returns no useful results.\n- The search tool returns chunk content directly — you do not need to read the source files.\n- Use repo read/bash tools only for non-doc files or when you need to inspect exact implementation code in the workspace.` : ``;
 	const skillsGuidance = opts.hasSkills ? `\n# Skills\nYou have access to skills — specialized knowledge and guided workflows you can load on demand. Your context includes a skills catalog listing what's available. When the user's request matches a skill's description or keywords, load it with use_skill.
 
 Some skills are user-invocable — the user can trigger them with a slash command like \`/quickstart\`. When you see a message starting with \`/\` followed by a skill name, load that skill immediately with use_skill. Pass any text after the skill name as args.
@@ -1656,7 +1658,7 @@ Do NOT load a skill and then ignore its instructions. The skill is there because
 When a user is new or asks how to get started with Electric Agents, **don't assume a single path**. Present the options and let them choose:
 
 - **Learn the concepts first** → Explain what Electric Agents is, answer questions, point to docs.
-  Use your docs tools or fetch_url. Only load the quickstart skill if the user explicitly asks for a hands-on guided tutorial.
+  Use search_durable_agents_docs to look up answers. Only load the quickstart skill if the user explicitly asks for a hands-on guided tutorial.
 
 - **Hands-on guided tutorial** → Load the quickstart skill (or tell them to type \`/quickstart\`).
   This is a step-by-step build that takes them from zero to a running app.
@@ -1666,7 +1668,7 @@ When a user is new or asks how to get started with Electric Agents, **don't assu
   This sets up project structure and orients them in the codebase.
 
 - **Have a specific question?** → Answer it directly.
-  Use your docs tools, fetch_url, or general coding knowledge.
+  Use search_durable_agents_docs first, then fall back to fetch_url or general knowledge if needed.
 
 Don't force onboarding. If someone just wants to chat or code, let them. When in doubt, ask what they'd like to do rather than picking a path for them.`;
 	const docsUrlGuidance = opts.docsUrl ? `\n# Electric Agents documentation

package/dist/index.cjs

@@ -819,6 +819,8 @@ function resolveDocsRoot(workingDirectory) {
 		process.env.HORTON_DOCS_ROOT,
 		node_path.default.resolve(workingDirectory, `electric-agents-docs/docs`),
 		node_path.default.resolve(process.cwd(), `electric-agents-docs/docs`),
+		node_path.default.resolve(MODULE_DIR, `../docs`),
+		node_path.default.resolve(MODULE_DIR, `../../docs`),
 		node_path.default.resolve(MODULE_DIR, `../../../../../electric-agents-docs/docs`)
 	].filter((value) => typeof value === `string`);
 	for (const candidate of candidates) if (node_fs.default.existsSync(candidate)) return candidate;
@@ -1660,7 +1662,7 @@ async function generateTitle(userMessage, llmCall = defaultHaikuCall) {
 function buildHortonSystemPrompt(workingDirectory, opts = {}) {
 	const docsTools = opts.hasDocsSupport ? `\n- search_durable_agents_docs: hybrid search over the built-in Durable Agents docs index` : ``;
 	const skillsTools = opts.hasSkills ? `\n- use_skill: load a skill (knowledge, instructions, or a tutorial) into your context to help with the user's request\n- remove_skill: unload a skill from context when you're done with it` : ``;
-	const docsGuidance = opts.hasDocsSupport ? `\n- You have built-in Durable Agents docs context plus a docs search tool. Use that before broad web search when the question is about this repo, Electric Agents, or Durable Agents.\n- The docs TOC and docs search results include concrete file paths under the docs tree. Use the normal read tool with those returned paths.\n- Use repo read/bash tools for non-doc files or when you need to inspect exact implementation code in the workspace.` : ``;
+	const docsGuidance = opts.hasDocsSupport ? `\n- For ANY question about Electric Agents, Durable Agents, or this framework, ALWAYS use search_durable_agents_docs FIRST. Do not use brave_search or fetch_url for Electric Agents topics unless the docs search returns no useful results.\n- The search tool returns chunk content directly — you do not need to read the source files.\n- Use repo read/bash tools only for non-doc files or when you need to inspect exact implementation code in the workspace.` : ``;
 	const skillsGuidance = opts.hasSkills ? `\n# Skills\nYou have access to skills — specialized knowledge and guided workflows you can load on demand. Your context includes a skills catalog listing what's available. When the user's request matches a skill's description or keywords, load it with use_skill.
 
 Some skills are user-invocable — the user can trigger them with a slash command like \`/quickstart\`. When you see a message starting with \`/\` followed by a skill name, load that skill immediately with use_skill. Pass any text after the skill name as args.
@@ -1679,7 +1681,7 @@ Do NOT load a skill and then ignore its instructions. The skill is there because
 When a user is new or asks how to get started with Electric Agents, **don't assume a single path**. Present the options and let them choose:
 
 - **Learn the concepts first** → Explain what Electric Agents is, answer questions, point to docs.
-  Use your docs tools or fetch_url. Only load the quickstart skill if the user explicitly asks for a hands-on guided tutorial.
+  Use search_durable_agents_docs to look up answers. Only load the quickstart skill if the user explicitly asks for a hands-on guided tutorial.
 
 - **Hands-on guided tutorial** → Load the quickstart skill (or tell them to type \`/quickstart\`).
   This is a step-by-step build that takes them from zero to a running app.
@@ -1689,7 +1691,7 @@ When a user is new or asks how to get started with Electric Agents, **don't assu
   This sets up project structure and orients them in the codebase.
 
 - **Have a specific question?** → Answer it directly.
-  Use your docs tools, fetch_url, or general coding knowledge.
+  Use search_durable_agents_docs first, then fall back to fetch_url or general knowledge if needed.
 
 Don't force onboarding. If someone just wants to chat or code, let them. When in doubt, ask what they'd like to do rather than picking a path for them.`;
 	const docsUrlGuidance = opts.docsUrl ? `\n# Electric Agents documentation

package/dist/index.js

@@ -795,6 +795,8 @@ function resolveDocsRoot(workingDirectory) {
 		process.env.HORTON_DOCS_ROOT,
 		path.resolve(workingDirectory, `electric-agents-docs/docs`),
 		path.resolve(process.cwd(), `electric-agents-docs/docs`),
+		path.resolve(MODULE_DIR, `../docs`),
+		path.resolve(MODULE_DIR, `../../docs`),
 		path.resolve(MODULE_DIR, `../../../../../electric-agents-docs/docs`)
 	].filter((value) => typeof value === `string`);
 	for (const candidate of candidates) if (fsSync.existsSync(candidate)) return candidate;
@@ -1636,7 +1638,7 @@ async function generateTitle(userMessage, llmCall = defaultHaikuCall) {
 function buildHortonSystemPrompt(workingDirectory, opts = {}) {
 	const docsTools = opts.hasDocsSupport ? `\n- search_durable_agents_docs: hybrid search over the built-in Durable Agents docs index` : ``;
 	const skillsTools = opts.hasSkills ? `\n- use_skill: load a skill (knowledge, instructions, or a tutorial) into your context to help with the user's request\n- remove_skill: unload a skill from context when you're done with it` : ``;
-	const docsGuidance = opts.hasDocsSupport ? `\n- You have built-in Durable Agents docs context plus a docs search tool. Use that before broad web search when the question is about this repo, Electric Agents, or Durable Agents.\n- The docs TOC and docs search results include concrete file paths under the docs tree. Use the normal read tool with those returned paths.\n- Use repo read/bash tools for non-doc files or when you need to inspect exact implementation code in the workspace.` : ``;
+	const docsGuidance = opts.hasDocsSupport ? `\n- For ANY question about Electric Agents, Durable Agents, or this framework, ALWAYS use search_durable_agents_docs FIRST. Do not use brave_search or fetch_url for Electric Agents topics unless the docs search returns no useful results.\n- The search tool returns chunk content directly — you do not need to read the source files.\n- Use repo read/bash tools only for non-doc files or when you need to inspect exact implementation code in the workspace.` : ``;
 	const skillsGuidance = opts.hasSkills ? `\n# Skills\nYou have access to skills — specialized knowledge and guided workflows you can load on demand. Your context includes a skills catalog listing what's available. When the user's request matches a skill's description or keywords, load it with use_skill.
 
 Some skills are user-invocable — the user can trigger them with a slash command like \`/quickstart\`. When you see a message starting with \`/\` followed by a skill name, load that skill immediately with use_skill. Pass any text after the skill name as args.
@@ -1655,7 +1657,7 @@ Do NOT load a skill and then ignore its instructions. The skill is there because
 When a user is new or asks how to get started with Electric Agents, **don't assume a single path**. Present the options and let them choose:
 
 - **Learn the concepts first** → Explain what Electric Agents is, answer questions, point to docs.
-  Use your docs tools or fetch_url. Only load the quickstart skill if the user explicitly asks for a hands-on guided tutorial.
+  Use search_durable_agents_docs to look up answers. Only load the quickstart skill if the user explicitly asks for a hands-on guided tutorial.
 
 - **Hands-on guided tutorial** → Load the quickstart skill (or tell them to type \`/quickstart\`).
   This is a step-by-step build that takes them from zero to a running app.
@@ -1665,7 +1667,7 @@ When a user is new or asks how to get started with Electric Agents, **don't assu
   This sets up project structure and orients them in the codebase.
 
 - **Have a specific question?** → Answer it directly.
-  Use your docs tools, fetch_url, or general coding knowledge.
+  Use search_durable_agents_docs first, then fall back to fetch_url or general knowledge if needed.
 
 Don't force onboarding. If someone just wants to chat or code, let them. When in doubt, ask what they'd like to do rather than picking a path for them.`;
 	const docsUrlGuidance = opts.docsUrl ? `\n# Electric Agents documentation

package/docs/entities/agents/horton.md

@@ -0,0 +1,89 @@
+---
+title: Horton agent
+titleTemplate: '... - Electric Agents'
+description: >-
+  The built-in Horton assistant - chat, research, code, and dispatch subagents in one entity type.
+outline: [2, 3]
+---
+
+# Horton agent
+
+The built-in assistant registered by the Electric Agents dev server. Horton can chat conversationally, search the web, read and edit files, run shell commands, and dispatch subagents (workers) for isolated subtasks.
+
+**Source:** [`packages/agents/src/agents/horton.ts`](https://github.com/electric-sql/electric/blob/main/packages/agents/src/agents/horton.ts)
+
+## Try it
+
+With the dev server running (`npx electric-ax agents quickstart`):
+
+```sh
+npx electric-ax agents spawn /horton/my-horton
+npx electric-ax agents send /horton/my-horton 'What's in this directory?'
+npx electric-ax agents observe /horton/my-horton
+```
+
+## Tools
+
+Horton is configured with `ctx.electricTools` plus the base Horton tool set:
+
+| Tool           | Purpose                                                  |
+| -------------- | -------------------------------------------------------- |
+| `bash`         | Run shell commands in the working directory.             |
+| `read`         | Read a file. Tracked in a per-wake `readSet`.            |
+| `write`        | Create or overwrite a file.                              |
+| `edit`         | Targeted string replacement (file must be `read` first). |
+| `brave_search` | Web search via the Brave Search API.                     |
+| `fetch_url`    | Fetch a URL and return it as markdown.                   |
+| `spawn_worker` | Dispatch a subagent for an isolated subtask.             |
+
+`brave_search` requires `BRAVE_SEARCH_API_KEY` in the environment; without it the tool errors at call time.
+
+When docs support or skills are available, Horton also adds the docs search tool and skill tools during bootstrap.
+
+## Title generation
+
+After the first agent run completes, Horton calls `generateTitle()` (Haiku) to summarise the user's first message into a 3-5 word session title and stores it via `ctx.setTag('title', title)`. Failures are logged and ignored — the entity continues without a title.
+
+## Details
+
+| Property          | Value                                                                             |
+| ----------------- | --------------------------------------------------------------------------------- |
+| Type name         | `horton`                                                                          |
+| Model             | `HORTON_MODEL` (`claude-sonnet-4-5-20250929`)                                     |
+| Title model       | `claude-haiku-4-5-20251001`                                                       |
+| Tools             | `ctx.electricTools` + base Horton tool set, plus docs/skill tools when configured |
+| Working directory | Passed at bootstrap (defaults to `process.cwd()`)                                 |
+| Title generation  | Yes, after the first run if no title tag exists                                   |
+
+## Extending Horton
+
+The system prompt and tool factory are exported so you can build your own variants:
+
+```ts
+import {
+  HORTON_MODEL,
+  buildHortonSystemPrompt,
+  createHortonTools,
+} from '@electric-ax/agents'
+
+registry.define('my-assistant', {
+  description: 'Horton with an extra custom tool',
+  async handler(ctx) {
+    const readSet = new Set<string>()
+    ctx.useAgent({
+      systemPrompt: buildHortonSystemPrompt(process.cwd()),
+      model: HORTON_MODEL,
+      tools: [
+        ...ctx.electricTools,
+        ...createHortonTools(process.cwd(), ctx, readSet),
+        myCustomTool,
+      ],
+    })
+    await ctx.agent.run()
+  },
+})
+```
+
+## Related
+
+- [Worker](./worker) — the subagent type Horton dispatches via `spawn_worker`.

package/docs/entities/agents/worker.md

@@ -0,0 +1,102 @@
+---
+title: Worker
+titleTemplate: '... - Electric Agents'
+description: >-
+  Generic sandboxed subagent type. Spawned by Horton (or any agent) via the spawn_worker tool with a system prompt and a chosen tool subset.
+outline: [2, 3]
+---
+
+# Worker
+
+A generic, sandboxed subagent type. Workers are spawned by other agents (typically [Horton](./horton)) via the `spawn_worker` tool — the spawner provides a system prompt and picks the subset of tools the worker should have access to.
+
+**Source:** [`packages/agents/src/agents/worker.ts`](https://github.com/electric-sql/electric/blob/main/packages/agents/src/agents/worker.ts)
+
+## Spawn args
+
+```ts
+interface WorkerArgs {
+  systemPrompt: string
+  tools?: Array<WorkerToolName>
+  sharedDb?: { id: string; schema: SharedStateSchemaMap }
+  sharedDbToolMode?: 'full' | 'write-only'
+}
+```
+
+| Field              | Required | Description                                                                                   |
+| ------------------ | -------- | --------------------------------------------------------------------------------------------- |
+| `systemPrompt`     | Yes      | The worker's system prompt. Brief it like a colleague: file paths, line numbers, deliverable. |
+| `tools`            | No       | Subset of valid tool names (see below). Unknown names throw at parse time.                    |
+| `sharedDb`         | No       | Shared state stream id and schema to connect to.                                              |
+| `sharedDbToolMode` | No       | Shared state tool mode: `"full"` (default) or `"write-only"`.                                 |
+
+`registerWorker(registry, { workingDirectory, streamFn? })` is called by the dev server during bootstrap; you don't usually call it yourself.
+
+## Valid tool names
+
+```ts
+type WorkerToolName =
+  | 'bash'
+  | 'read'
+  | 'write'
+  | 'edit'
+  | 'brave_search'
+  | 'fetch_url'
+  | 'spawn_worker'
+```
+
+These are the same primitives Horton uses. Pick the smallest subset the worker needs — tools are the worker's permission set.
+
+The worker must receive at least one tool or a `sharedDb` config. If `sharedDb` is provided, the worker gets generated shared-state tools in addition to any selected primitives.
+
+## Spawning a worker
+
+The canonical way to spawn a worker is the `spawn_worker` tool, which Horton calls from inside its agent loop:
+
+```ts
+spawn_worker({
+  systemPrompt:
+    'You are a focused researcher. Find the three most-cited papers on X and return their titles, authors, and DOIs as a markdown table.',
+  tools: ['brave_search', 'fetch_url'],
+  initialMessage: 'Begin research now.',
+})
+```
+
+| Field            | Required | Notes                                                                         |
+| ---------------- | -------- | ----------------------------------------------------------------------------- |
+| `systemPrompt`   | Yes      | Sets persona and constraints.                                                 |
+| `tools`          | Yes      | Subset of `WorkerToolName`. Must contain at least one entry.                  |
+| `initialMessage` | Yes      | First user message. **Without this the worker idles** — nothing kicks it off. |
+
+The spawn uses `wake: { on: 'runFinished', includeResponse: true }`, so the spawner wakes when the worker finishes its run and receives the worker's response in the wake message.
+
+## What the handler does
+
+1. Parses `ctx.args` into `WorkerArgs`. Throws if `systemPrompt` is empty, if `tools` contains an unknown name, or if neither `tools` nor `sharedDb` is provided.
+2. Builds the requested tool instances against the worker's `workingDirectory` (and a fresh per-wake `readSet` for the read-first-then-edit guard).
+3. If `sharedDb` is present, connects with `ctx.observe(db(id, schema))` and exposes generated `read_*`, `write_*`, `update_*`, and `delete_*` tools (`write_*` only in `"write-only"` mode).
+4. Configures the agent with `HORTON_MODEL` (`claude-sonnet-4-5-20250929`), the provided system prompt (with a brief reporting-back footer appended), and the assembled tool list.
+5. Runs the agent until the LLM stops.
+
+::: warning Least-privilege sandbox
+Workers deliberately do **not** receive `ctx.electricTools`. The spawner already picked the worker's tool subset; granting entity-runtime primitives (cron, schedule, send-to-arbitrary-entity) would let a worker escape that scope. If a worker needs those primitives, it must spawn its own subagent or report back to the spawner.
+:::
+
+## Reporting footer
+
+The runtime appends this to every worker's system prompt:
+
+```text
+# Reporting back
+When you finish, respond with a concise report covering what was done and any key findings. The caller will relay this to the user, so it only needs the essentials.
+```
+
+## Details
+
+| Property          | Value                                                                                                                     |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| Type name         | `worker`                                                                                                                  |
+| Model             | `HORTON_MODEL` (`claude-sonnet-4-5-20250929`)                                                                             |
+| Tools             | Subset of 7 primitives plus optional shared-state tools. **No `ctx.electricTools`.**                                      |
+| Working directory | Provided to `registerWorker` at bootstrap                                                                                 |
+| Description       | `Internal — generic worker spawned by other agents. Configure via spawn args (systemPrompt + tools + optional sharedDb).` |

package/docs/entities/patterns/blackboard.md

@@ -0,0 +1,111 @@
+---
+title: Blackboard (shared state)
+titleTemplate: '... - Electric Agents'
+description: >-
+  Multi-agent coordination using shared state as a common data structure for reads and writes.
+outline: [2, 3]
+---
+
+# Blackboard (shared state)
+
+Pattern: multiple agents coordinate through a shared data structure. A parent creates shared state, spawns workers that connect to it, and workers read/write shared collections via auto-generated CRUD tools.
+
+**Source:** [`packages/agents-runtime/skills/designing-entities/references/patterns/blackboard.md`](https://github.com/electric-sql/electric/blob/main/packages/agents-runtime/skills/designing-entities/references/patterns/blackboard.md)
+
+## Debate example
+
+The canonical blackboard example: a moderator runs a structured debate between pro and con workers via shared state.
+
+### Schema
+
+```ts
+const debateSchema = {
+  arguments: {
+    schema: z.object({
+      key: z.string(),
+      side: z.enum(['pro', 'con']),
+      text: z.string(),
+      round: z.number(),
+    }),
+    type: 'shared:argument',
+    primaryKey: 'key',
+  },
+}
+```
+
+### Registration
+
+```ts
+import { db } from '@electric-ax/agents-runtime'
+
+export function registerDebate(registry: EntityRegistry) {
+  registry.define(`debate`, {
+    description: `Debate moderator that creates shared state, spawns pro and con workers, and writes a final ruling based on arguments written to shared state`,
+    state: {
+      status: { primaryKey: `key` },
+    },
+
+    async handler(ctx) {
+      if (ctx.firstWake) {
+        ctx.db.actions.status_insert({ row: { key: `current`, value: `idle` } })
+        ctx.mkdb(`debate-${ctx.entityUrl}`, debateSchema)
+      }
+      const shared = await ctx.observe(
+        db(`debate-${ctx.entityUrl}`, debateSchema)
+      )
+
+      // ... create tools that reference `shared` ...
+
+      ctx.useAgent({
+        systemPrompt: DEBATE_SYSTEM_PROMPT,
+        model: `claude-sonnet-4-5-20250929`,
+        tools: [...ctx.electricTools, startTool, checkTool, endTool],
+      })
+      await ctx.agent.run()
+    },
+  })
+}
+```
+
+### How it works
+
+1. On first wake, the moderator creates shared state with `ctx.mkdb()`.
+2. The moderator connects to the shared state with `ctx.observe(db(...))`.
+3. The `start_debate` tool spawns pro and con workers, each connected to the same shared state:
+
+```ts
+const proWorker = await ctx.spawn(
+  `worker`,
+  `debate-pro-${Date.now()}-${spawnCounter}`,
+  {
+    systemPrompt: PRO_WORKER_PROMPT,
+    sharedDb: { id: `debate-${ctx.entityUrl}`, schema: debateSchema },
+  },
+  { initialMessage: proInitialMessage, wake: `runFinished` }
+)
+```
+
+4. Workers write arguments to the shared `arguments` collection using auto-generated `write_arguments` tools (see [Worker](../agents/worker.md)).
+5. The `check_debate` tool reads the shared state to see current arguments:
+
+```ts
+const args = shared.arguments.toArray
+```
+
+6. The `end_debate` tool reads all arguments and transitions to `done`.
+
+### State transitions
+
+```ts
+type DebateStatus = 'idle' | 'debating' | 'ruling' | 'done'
+```
+
+## Other blackboard variants
+
+The same structure applies to other blackboard workflows:
+
+- **Wiki** -- specialist workers collaboratively build a knowledge base. Each writes articles to a shared `articles` collection.
+- **Peer review** -- workers submit reviews with scores and feedback to a shared `reviews` collection. A coordinator summarizes the reviews.
+- **Trading floor** -- trader agents submit buy/sell orders to a shared `orders` collection and transition through market sessions.
+
+All follow the same structure: parent creates shared state, spawns workers with `sharedDb` in their args, workers use generated CRUD tools to coordinate.

package/docs/entities/patterns/dispatcher.md

@@ -0,0 +1,77 @@
+---
+title: Dispatcher
+titleTemplate: '... - Electric Agents'
+description: >-
+  Message routing pattern that classifies incoming messages and dispatches to specialist agents.
+outline: [2, 3]
+---
+
+# Dispatcher
+
+Pattern: classify incoming messages and route to the appropriate agent type.
+
+**Source:** [`packages/agents-runtime/skills/designing-entities/references/patterns/dispatcher.md`](https://github.com/electric-sql/electric/blob/main/packages/agents-runtime/skills/designing-entities/references/patterns/dispatcher.md)
+
+## Registration
+
+```ts
+export function registerDispatcher(registry: EntityRegistry) {
+  registry.define(`dispatcher`, {
+    description: `Router agent that classifies incoming messages and dispatches to the appropriate specialist agent type`,
+
+    async handler(ctx) {
+      const dispatchTool = createDispatchTool(ctx)
+
+      ctx.useAgent({
+        systemPrompt: DISPATCHER_SYSTEM_PROMPT,
+        model: `claude-sonnet-4-5-20250929`,
+        tools: [...ctx.electricTools, dispatchTool],
+      })
+      await ctx.agent.run()
+    },
+  })
+}
+```
+
+::: info No local state
+The dispatcher entity defines no `state` collections. It is stateless -- it relies entirely on the wake mechanism to receive child completion events and forwards specialist output to the user.
+:::
+
+## How it works
+
+The dispatcher exposes a `dispatch` tool. When the LLM classifies an incoming message, it calls the tool with:
+
+- `type` -- the entity type to spawn (e.g. `"horton"`, `"worker"`, or an app-defined type)
+- `systemPrompt` -- a focused prompt crafted for the task
+- `task` -- the original message to forward
+
+The tool then:
+
+1. Spawns the requested entity type with `wake: 'runFinished'`.
+2. Returns immediately with a status message. The dispatcher is re-invoked when the specialist finishes.
+
+## Dispatch tool
+
+```ts
+await ctx.spawn(
+  type,
+  id,
+  type === `worker` ? { systemPrompt, tools: [`read`] } : { systemPrompt },
+  {
+    initialMessage: task,
+    wake: `runFinished`,
+  }
+)
+
+return {
+  content: [
+    {
+      type: `text` as const,
+      text: `Dispatched to "${type}" specialist (${id}). You will be woken when it finishes.`,
+    },
+  ],
+  details: { id, type },
+}
+```
+
+When dispatching to the built-in `worker`, include its required tool subset in the spawn args.

package/docs/entities/patterns/manager-worker.md

@@ -0,0 +1,127 @@
+---
+title: Manager-Worker
+titleTemplate: '... - Electric Agents'
+description: >-
+  Coordination pattern where a parent spawns specialist children, waits for completion, and synthesizes results.
+outline: [2, 3]
+---
+
+# Manager-Worker
+
+Pattern: a parent agent spawns multiple specialist children, waits for all to complete, and synthesizes results.
+
+**Source:** [`packages/agents-runtime/skills/designing-entities/references/patterns/manager-worker.md`](https://github.com/electric-sql/electric/blob/main/packages/agents-runtime/skills/designing-entities/references/patterns/manager-worker.md)
+
+## Registration
+
+```ts
+export function registerManagerWorker(registry: EntityRegistry) {
+  registry.define(`manager-worker`, {
+    description: `Manager agent that spawns optimist, pessimist, and pragmatist workers to analyze any question from multiple perspectives`,
+    state: {
+      children: { schema: managerChildSchema, primaryKey: `key` },
+    },
+
+    async handler(ctx) {
+      const analyzeTool = createAnalyzeWithPerspectivesTool(ctx)
+
+      ctx.useAgent({
+        systemPrompt: MANAGER_SYSTEM_PROMPT,
+        model: `claude-sonnet-4-5-20250929`,
+        tools: [...ctx.electricTools, analyzeTool],
+      })
+      await ctx.agent.run()
+    },
+  })
+}
+```
+
+## How it works
+
+The manager defines a handler-scoped tool called `analyze_with_perspectives`. When the LLM calls this tool, it:
+
+1. Spawns 3 worker children -- optimist, pessimist, pragmatist -- each with a different system prompt.
+2. Sends the same question to all three as `initialMessage`.
+3. Uses `wake: 'runFinished'` to wait for each child to complete.
+4. Collects results with `Promise.all` and `handle.text()`.
+5. Returns the combined perspectives to the LLM for synthesis.
+
+On subsequent calls, the tool reuses existing children via `ctx.observe()` and `child.send()` instead of spawning new ones.
+
+## Spawn-or-reuse pattern
+
+The core of the tool -- first-call spawns, subsequent calls reuse:
+
+```ts
+for (const perspective of PERSPECTIVES) {
+  const existing = children.get(perspective.id)
+  const childId = `${parentId}-${perspective.id}`
+
+  if (!existing?.url) {
+    // First time: spawn a new worker
+    const child = await ctx.spawn(
+      `worker`,
+      childId,
+      { systemPrompt: perspective.systemPrompt, tools: [`read`] },
+      { initialMessage: question, wake: `runFinished` }
+    )
+    children.insert({
+      key: perspective.id,
+      url: child.entityUrl,
+      kind: perspective.id,
+      question,
+    })
+    handles.push({ id: perspective.id, handle: child })
+    continue
+  }
+
+  // Subsequent calls: observe existing child and send new question
+  const child = await ctx.observe(entity(existing.url))
+  child.send(question)
+  children.update(perspective.id, (draft) => {
+    draft.question = question
+  })
+  handles.push({ id: perspective.id, handle: child })
+}
+```
+
+## Collecting results
+
+The `readLatestCompletedText` helper awaits the child's current run, reads all text outputs, and returns the last one:
+
+```ts
+async function readLatestCompletedText(
+  handle: EntityHandle,
+  fallback: string
+): Promise<string> {
+  await handle.run
+  const runs = await handle.text()
+  const latest = runs[runs.length - 1]?.trim()
+  return latest || fallback
+}
+
+const results = await Promise.all(
+  handles.map(async ({ id, handle }) => ({
+    id,
+    text: await readLatestCompletedText(
+      handle,
+      `(no completed output from ${id})`
+    ),
+  }))
+)
+```
+
+## State
+
+The `children` collection tracks spawned workers:
+
+```ts
+const managerChildSchema = z.object({
+  key: z.string(),
+  url: z.string(),
+  kind: z.string(),
+  question: z.string(),
+})
+```
+
+This allows the manager to find and reuse children across handler invocations.