@electric-ax/agents 0.2.2 → 0.2.4

package/dist/entrypoint.js

@@ -48,6 +48,10 @@ function formatArgs(args) {
 	};
 }
 const serverLog = {
+	debug(...args) {
+		const { msg } = formatArgs(args);
+		logger.debug(msg);
+	},
 	info(...args) {
 		const { msg } = formatArgs(args);
 		logger.info(msg);
@@ -792,15 +796,38 @@ function findLatestQuestion(items) {
 	return void 0;
 }
 function resolveDocsRoot(workingDirectory) {
+	const envDocsRoot = process.env.HORTON_DOCS_ROOT;
 	const candidates = [
-		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;
+		envDocsRoot ? {
+			path: envDocsRoot,
+			requireIndex: false
+		} : null,
+		{
+			path: path.resolve(workingDirectory, `electric-agents-docs/docs`),
+			requireIndex: false
+		},
+		{
+			path: path.resolve(process.cwd(), `electric-agents-docs/docs`),
+			requireIndex: false
+		},
+		{
+			path: path.resolve(MODULE_DIR, `../docs`),
+			requireIndex: true
+		},
+		{
+			path: path.resolve(MODULE_DIR, `../../docs`),
+			requireIndex: true
+		},
+		{
+			path: path.resolve(MODULE_DIR, `../../../../website/docs/agents`),
+			requireIndex: true
+		},
+		{
+			path: path.resolve(MODULE_DIR, `../../../../../electric-agents-docs/docs`),
+			requireIndex: false
+		}
+	].filter((value) => Boolean(value));
+	for (const candidate of candidates) if (fs.existsSync(candidate.path) && (!candidate.requireIndex || fs.existsSync(path.join(candidate.path, `index.md`)))) return candidate.path;
 	return null;
 }
 var DocsKnowledgeBase = class {
@@ -830,7 +857,7 @@ var DocsKnowledgeBase = class {
 			return db$1;
 		} catch (error) {
 			const message = error instanceof Error ? error.message : String(error);
-			console.warn(`${this.logPrefix} falling back to in-memory docs index: ${message}`);
+			serverLog.debug(`${this.logPrefix} falling back to in-memory docs index: ${message}`);
 			return null;
 		}
 	}
@@ -917,7 +944,7 @@ var DocsKnowledgeBase = class {
 			}
 			this.fallbackFingerprint = fingerprint;
 			const stats$1 = this.stats();
-			console.log(`${this.logPrefix} indexed ${stats$1.docCount} docs into ${stats$1.chunkCount} chunks (${stats$1.fingerprint.slice(0, 12)}...)`);
+			serverLog.debug(`${this.logPrefix} indexed ${stats$1.docCount} docs into ${stats$1.chunkCount} chunks (${stats$1.fingerprint.slice(0, 12)}...)`);
 			return stats$1;
 		}
 		const db$1 = this.db;
@@ -954,7 +981,7 @@ var DocsKnowledgeBase = class {
 		});
 		reset();
 		const stats = this.stats();
-		console.log(`${this.logPrefix} indexed ${stats.docCount} docs into ${stats.chunkCount} chunks (${stats.fingerprint.slice(0, 12)}...)`);
+		serverLog.debug(`${this.logPrefix} indexed ${stats.docCount} docs into ${stats.chunkCount} chunks (${stats.fingerprint.slice(0, 12)}...)`);
 		return stats;
 	}
 	hybridSearch(query, limit = DEFAULT_K) {
@@ -1094,7 +1121,7 @@ function renderSearchResults(query, results, docsRoot) {
 	return lines.join(`\n`);
 }
 function logSearchResults(kind, query, output) {
-	console.log(`[horton-docs] ${kind} search for "${query}"\n${output}\n`);
+	serverLog.debug(`[horton-docs] ${kind} search for "${query}"\n${output}\n`);
 }
 function createHortonDocsSupport(workingDirectory, opts = {}) {
 	const docsRoot = opts.docsRoot ?? resolveDocsRoot(workingDirectory);
@@ -2267,6 +2294,7 @@ async function saveCache(cachePath, catalog, cacheDir) {
 	const obj = {};
 	for (const [name, meta] of catalog) obj[name] = meta;
 	fs.mkdirSync(cacheDir, { recursive: true });
+	await fs$1.writeFile(path.join(cacheDir, `.gitignore`), `*\n`, `utf-8`);
 	await fs$1.writeFile(cachePath, JSON.stringify(obj, null, 2), `utf-8`);
 }
 function sha256(content) {

package/dist/index.cjs

@@ -71,6 +71,10 @@ function formatArgs(args) {
 	};
 }
 const serverLog = {
+	debug(...args) {
+		const { msg } = formatArgs(args);
+		logger.debug(msg);
+	},
 	info(...args) {
 		const { msg } = formatArgs(args);
 		logger.info(msg);
@@ -815,15 +819,38 @@ function findLatestQuestion(items) {
 	return void 0;
 }
 function resolveDocsRoot(workingDirectory) {
+	const envDocsRoot = process.env.HORTON_DOCS_ROOT;
 	const candidates = [
-		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;
+		envDocsRoot ? {
+			path: envDocsRoot,
+			requireIndex: false
+		} : null,
+		{
+			path: node_path.default.resolve(workingDirectory, `electric-agents-docs/docs`),
+			requireIndex: false
+		},
+		{
+			path: node_path.default.resolve(process.cwd(), `electric-agents-docs/docs`),
+			requireIndex: false
+		},
+		{
+			path: node_path.default.resolve(MODULE_DIR, `../docs`),
+			requireIndex: true
+		},
+		{
+			path: node_path.default.resolve(MODULE_DIR, `../../docs`),
+			requireIndex: true
+		},
+		{
+			path: node_path.default.resolve(MODULE_DIR, `../../../../website/docs/agents`),
+			requireIndex: true
+		},
+		{
+			path: node_path.default.resolve(MODULE_DIR, `../../../../../electric-agents-docs/docs`),
+			requireIndex: false
+		}
+	].filter((value) => Boolean(value));
+	for (const candidate of candidates) if (node_fs.default.existsSync(candidate.path) && (!candidate.requireIndex || node_fs.default.existsSync(node_path.default.join(candidate.path, `index.md`)))) return candidate.path;
 	return null;
 }
 var DocsKnowledgeBase = class {
@@ -853,7 +880,7 @@ var DocsKnowledgeBase = class {
 			return db$1;
 		} catch (error) {
 			const message = error instanceof Error ? error.message : String(error);
-			console.warn(`${this.logPrefix} falling back to in-memory docs index: ${message}`);
+			serverLog.debug(`${this.logPrefix} falling back to in-memory docs index: ${message}`);
 			return null;
 		}
 	}
@@ -940,7 +967,7 @@ var DocsKnowledgeBase = class {
 			}
 			this.fallbackFingerprint = fingerprint;
 			const stats$1 = this.stats();
-			console.log(`${this.logPrefix} indexed ${stats$1.docCount} docs into ${stats$1.chunkCount} chunks (${stats$1.fingerprint.slice(0, 12)}...)`);
+			serverLog.debug(`${this.logPrefix} indexed ${stats$1.docCount} docs into ${stats$1.chunkCount} chunks (${stats$1.fingerprint.slice(0, 12)}...)`);
 			return stats$1;
 		}
 		const db$1 = this.db;
@@ -977,7 +1004,7 @@ var DocsKnowledgeBase = class {
 		});
 		reset();
 		const stats = this.stats();
-		console.log(`${this.logPrefix} indexed ${stats.docCount} docs into ${stats.chunkCount} chunks (${stats.fingerprint.slice(0, 12)}...)`);
+		serverLog.debug(`${this.logPrefix} indexed ${stats.docCount} docs into ${stats.chunkCount} chunks (${stats.fingerprint.slice(0, 12)}...)`);
 		return stats;
 	}
 	hybridSearch(query, limit = DEFAULT_K) {
@@ -1117,7 +1144,7 @@ function renderSearchResults(query, results, docsRoot) {
 	return lines.join(`\n`);
 }
 function logSearchResults(kind, query, output) {
-	console.log(`[horton-docs] ${kind} search for "${query}"\n${output}\n`);
+	serverLog.debug(`[horton-docs] ${kind} search for "${query}"\n${output}\n`);
 }
 function createHortonDocsSupport(workingDirectory, opts = {}) {
 	const docsRoot = opts.docsRoot ?? resolveDocsRoot(workingDirectory);
@@ -2290,6 +2317,7 @@ async function saveCache(cachePath, catalog, cacheDir) {
 	const obj = {};
 	for (const [name, meta] of catalog) obj[name] = meta;
 	node_fs.default.mkdirSync(cacheDir, { recursive: true });
+	await node_fs_promises.default.writeFile(node_path.default.join(cacheDir, `.gitignore`), `*\n`, `utf-8`);
 	await node_fs_promises.default.writeFile(cachePath, JSON.stringify(obj, null, 2), `utf-8`);
 }
 function sha256(content) {

package/dist/index.js

@@ -47,6 +47,10 @@ function formatArgs(args) {
 	};
 }
 const serverLog = {
+	debug(...args) {
+		const { msg } = formatArgs(args);
+		logger.debug(msg);
+	},
 	info(...args) {
 		const { msg } = formatArgs(args);
 		logger.info(msg);
@@ -791,15 +795,38 @@ function findLatestQuestion(items) {
 	return void 0;
 }
 function resolveDocsRoot(workingDirectory) {
+	const envDocsRoot = process.env.HORTON_DOCS_ROOT;
 	const candidates = [
-		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;
+		envDocsRoot ? {
+			path: envDocsRoot,
+			requireIndex: false
+		} : null,
+		{
+			path: path.resolve(workingDirectory, `electric-agents-docs/docs`),
+			requireIndex: false
+		},
+		{
+			path: path.resolve(process.cwd(), `electric-agents-docs/docs`),
+			requireIndex: false
+		},
+		{
+			path: path.resolve(MODULE_DIR, `../docs`),
+			requireIndex: true
+		},
+		{
+			path: path.resolve(MODULE_DIR, `../../docs`),
+			requireIndex: true
+		},
+		{
+			path: path.resolve(MODULE_DIR, `../../../../website/docs/agents`),
+			requireIndex: true
+		},
+		{
+			path: path.resolve(MODULE_DIR, `../../../../../electric-agents-docs/docs`),
+			requireIndex: false
+		}
+	].filter((value) => Boolean(value));
+	for (const candidate of candidates) if (fsSync.existsSync(candidate.path) && (!candidate.requireIndex || fsSync.existsSync(path.join(candidate.path, `index.md`)))) return candidate.path;
 	return null;
 }
 var DocsKnowledgeBase = class {
@@ -829,7 +856,7 @@ var DocsKnowledgeBase = class {
 			return db$1;
 		} catch (error) {
 			const message = error instanceof Error ? error.message : String(error);
-			console.warn(`${this.logPrefix} falling back to in-memory docs index: ${message}`);
+			serverLog.debug(`${this.logPrefix} falling back to in-memory docs index: ${message}`);
 			return null;
 		}
 	}
@@ -916,7 +943,7 @@ var DocsKnowledgeBase = class {
 			}
 			this.fallbackFingerprint = fingerprint;
 			const stats$1 = this.stats();
-			console.log(`${this.logPrefix} indexed ${stats$1.docCount} docs into ${stats$1.chunkCount} chunks (${stats$1.fingerprint.slice(0, 12)}...)`);
+			serverLog.debug(`${this.logPrefix} indexed ${stats$1.docCount} docs into ${stats$1.chunkCount} chunks (${stats$1.fingerprint.slice(0, 12)}...)`);
 			return stats$1;
 		}
 		const db$1 = this.db;
@@ -953,7 +980,7 @@ var DocsKnowledgeBase = class {
 		});
 		reset();
 		const stats = this.stats();
-		console.log(`${this.logPrefix} indexed ${stats.docCount} docs into ${stats.chunkCount} chunks (${stats.fingerprint.slice(0, 12)}...)`);
+		serverLog.debug(`${this.logPrefix} indexed ${stats.docCount} docs into ${stats.chunkCount} chunks (${stats.fingerprint.slice(0, 12)}...)`);
 		return stats;
 	}
 	hybridSearch(query, limit = DEFAULT_K) {
@@ -1093,7 +1120,7 @@ function renderSearchResults(query, results, docsRoot) {
 	return lines.join(`\n`);
 }
 function logSearchResults(kind, query, output) {
-	console.log(`[horton-docs] ${kind} search for "${query}"\n${output}\n`);
+	serverLog.debug(`[horton-docs] ${kind} search for "${query}"\n${output}\n`);
 }
 function createHortonDocsSupport(workingDirectory, opts = {}) {
 	const docsRoot = opts.docsRoot ?? resolveDocsRoot(workingDirectory);
@@ -2266,6 +2293,7 @@ async function saveCache(cachePath, catalog, cacheDir) {
 	const obj = {};
 	for (const [name, meta] of catalog) obj[name] = meta;
 	fsSync.mkdirSync(cacheDir, { recursive: true });
+	await fs.writeFile(path.join(cacheDir, `.gitignore`), `*\n`, `utf-8`);
 	await fs.writeFile(cachePath, JSON.stringify(obj, null, 2), `utf-8`);
 }
 function sha256(content) {

package/docs/entities/agents/coder.md

@@ -0,0 +1,99 @@
+---
+title: Coder
+titleTemplate: "... - Electric Agents"
+description: >-
+  Built-in coding-session entity backed by Claude Code or Codex CLI.
+outline: [2, 3]
+---
+
+# Coder
+
+`coder` is the built-in coding-session entity. It runs a Claude Code or Codex CLI session in a working directory, mirrors the normalized session event stream into entity state, and can be prompted repeatedly across many turns.
+
+**Source:** [`packages/agents/src/agents/coding-session.ts`](https://github.com/electric-sql/electric/blob/main/packages/agents/src/agents/coding-session.ts)
+
+## Spawn args
+
+```ts
+interface CoderArgs {
+  agent: "claude" | "codex"
+  cwd?: string
+  nativeSessionId?: string
+  importFrom?: { agent: "claude" | "codex"; sessionId: string }
+}
+```
+
+| Field             | Required | Description |
+| ----------------- | -------- | ----------- |
+| `agent`           | Yes      | CLI backend to run: `"claude"` or `"codex"`. |
+| `cwd`             | No       | Working directory for the CLI. Defaults to the built-in runtime working directory. |
+| `nativeSessionId` | No       | Attach to an existing local Claude/Codex session. |
+| `importFrom`      | No       | Import an existing local session into a new session for the selected backend. |
+
+The built-in runtime registers `coder` during bootstrap. Handler code can also call `registerCodingSession(registry, { defaultWorkingDirectory, cliRunner? })` from `@electric-ax/agents`.
+
+## Prompt messages
+
+The preferred inbox message type is `prompt` with a payload shaped like:
+
+```ts
+interface PromptMessage {
+  text: string
+}
+```
+
+Generic messages with the same `{ text }` payload are also processed, so the dashboard and CLI can send prompts without a custom message type.
+
+## State collections
+
+`coder` adds three custom state collections:
+
+| Collection      | Event type              | Description |
+| --------------- | ----------------------- | ----------- |
+| `sessionMeta`   | `coding_session_meta`   | Current session metadata: selected backend, cwd, status, native session id, and errors. |
+| `cursorState`   | `coding_session_cursor` | Serialized tail cursor and the last processed inbox key. |
+| `events`        | `coding_session_event`  | Normalized `agent-session-protocol` events mirrored from the CLI session. |
+
+## Handler behavior
+
+1. Initializes session metadata and cursor state if needed.
+2. Mirrors existing local session history when attaching or importing.
+3. Processes pending prompt messages in inbox order.
+4. Calls `ctx.recordRun()` around each CLI invocation so parents observing with `wake: "runFinished"` are notified.
+5. Mirrors new CLI events into the `events` collection and appends assistant text as the run response.
+6. Updates `sessionMeta.status` to `idle` or `error`.
+
+## Handler API
+
+Inside another entity handler, use `ctx.useCodingAgent()` to spawn or attach to a coder:
+
+```ts
+const coder = await ctx.useCodingAgent("feature-work", {
+  agent: "claude",
+  cwd: process.cwd(),
+})
+
+coder.send("Implement the requested feature and run the tests.")
+await coder.run
+```
+
+`useCodingAgent()` returns a `CodingSessionHandle` with `entityUrl`, `status()`, `meta()`, `send(prompt)`, `run`, `events`, and `messages`.
+
+## Horton tools
+
+Horton usually interacts with coders through:
+
+| Tool           | Purpose |
+| -------------- | ------- |
+| `spawn_coder`  | Creates a new long-lived `coder`, sends the first prompt, and wakes Horton when the reply lands. |
+| `prompt_coder` | Sends a follow-up prompt to an existing coder URL. |
+
+## Details
+
+| Property          | Value |
+| ----------------- | ----- |
+| Type name         | `coder` |
+| Backends          | Claude Code and Codex CLI |
+| State             | `sessionMeta`, `cursorState`, `events` |
+| Wake support      | Uses `ctx.recordRun()` so `runFinished` observers work |
+| Working directory | From spawn args or `registerCodingSession` default |

package/docs/entities/agents/horton.md

@@ -1,6 +1,6 @@
 ---
 title: Horton agent
-titleTemplate: '... - Electric Agents'
+titleTemplate: "... - Electric Agents"
 description: >-
   The built-in Horton assistant - chat, research, code, and dispatch subagents in one entity type.
 outline: [2, 3]
@@ -8,7 +8,7 @@ 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.
+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, dispatch workers for isolated subtasks, and spawn long-lived coders for code changes.
 
 **Source:** [`packages/agents/src/agents/horton.ts`](https://github.com/electric-sql/electric/blob/main/packages/agents/src/agents/horton.ts)
 
@@ -35,6 +35,8 @@ Horton is configured with `ctx.electricTools` plus the base Horton tool set:
 | `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.             |
+| `spawn_coder`  | Spawn a long-lived `coder` entity backed by Claude Code or Codex. |
+| `prompt_coder` | Send a follow-up prompt to an existing coder.            |
 
 `brave_search` requires `BRAVE_SEARCH_API_KEY` in the environment; without it the tool errors at call time.
 
@@ -46,14 +48,14 @@ After the first agent run completes, Horton calls `generateTitle()` (Haiku) to s
 
 ## 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                                   |
+| 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, coder tools, 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
 
@@ -64,10 +66,10 @@ import {
   HORTON_MODEL,
   buildHortonSystemPrompt,
   createHortonTools,
-} from '@electric-ax/agents'
+} from "@electric-ax/agents"
 
-registry.define('my-assistant', {
-  description: 'Horton with an extra custom tool',
+registry.define("my-assistant", {
+  description: "Horton with an extra custom tool",
   async handler(ctx) {
     const readSet = new Set<string>()
     ctx.useAgent({
@@ -87,3 +89,4 @@ registry.define('my-assistant', {
 ## Related
 
 - [Worker](./worker) — the subagent type Horton dispatches via `spawn_worker`.
+- [Coder](./coder) — the coding-session entity Horton dispatches via `spawn_coder`.

package/docs/entities/agents/worker.md

@@ -1,6 +1,6 @@
 ---
 title: Worker
-titleTemplate: '... - Electric Agents'
+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]
@@ -19,7 +19,7 @@ interface WorkerArgs {
   systemPrompt: string
   tools?: Array<WorkerToolName>
   sharedDb?: { id: string; schema: SharedStateSchemaMap }
-  sharedDbToolMode?: 'full' | 'write-only'
+  sharedDbToolMode?: "full" | "write-only"
 }
 ```
 
@@ -36,13 +36,13 @@ interface WorkerArgs {
 
 ```ts
 type WorkerToolName =
-  | 'bash'
-  | 'read'
-  | 'write'
-  | 'edit'
-  | 'brave_search'
-  | 'fetch_url'
-  | 'spawn_worker'
+  | "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.
@@ -56,9 +56,9 @@ The canonical way to spawn a worker is the `spawn_worker` tool, which Horton cal
 ```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.',
+    "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.",
 })
 ```
 
@@ -93,10 +93,10 @@ When you finish, respond with a concise report covering what was done and any ke
 
 ## 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                                                                                 |
+| 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

@@ -1,6 +1,6 @@
 ---
 title: Blackboard (shared state)
-titleTemplate: '... - Electric Agents'
+titleTemplate: "... - Electric Agents"
 description: >-
   Multi-agent coordination using shared state as a common data structure for reads and writes.
 outline: [2, 3]
@@ -23,12 +23,12 @@ const debateSchema = {
   arguments: {
     schema: z.object({
       key: z.string(),
-      side: z.enum(['pro', 'con']),
+      side: z.enum(["pro", "con"]),
       text: z.string(),
       round: z.number(),
     }),
-    type: 'shared:argument',
-    primaryKey: 'key',
+    type: "shared:argument",
+    primaryKey: "key",
   },
 }
 ```
@@ -36,7 +36,7 @@ const debateSchema = {
 ### Registration
 
 ```ts
-import { db } from '@electric-ax/agents-runtime'
+import { db } from "@electric-ax/agents-runtime"
 
 export function registerDebate(registry: EntityRegistry) {
   registry.define(`debate`, {
@@ -97,7 +97,7 @@ const args = shared.arguments.toArray
 ### State transitions
 
 ```ts
-type DebateStatus = 'idle' | 'debating' | 'ruling' | 'done'
+type DebateStatus = "idle" | "debating" | "ruling" | "done"
 ```
 
 ## Other blackboard variants

package/docs/entities/patterns/dispatcher.md

@@ -1,6 +1,6 @@
 ---
 title: Dispatcher
-titleTemplate: '... - Electric Agents'
+titleTemplate: "... - Electric Agents"
 description: >-
   Message routing pattern that classifies incoming messages and dispatches to specialist agents.
 outline: [2, 3]

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

@@ -1,6 +1,6 @@
 ---
 title: Manager-Worker
-titleTemplate: '... - Electric Agents'
+titleTemplate: "... - Electric Agents"
 description: >-
   Coordination pattern where a parent spawns specialist children, waits for completion, and synthesizes results.
 outline: [2, 3]

package/docs/entities/patterns/map-reduce.md

@@ -1,6 +1,6 @@
 ---
 title: Map-Reduce
-titleTemplate: '... - Electric Agents'
+titleTemplate: "... - Electric Agents"
 description: >-
   Parallel processing pattern that splits work into chunks, processes simultaneously, and reduces results.
 outline: [2, 3]

package/docs/entities/patterns/pipeline.md

@@ -1,6 +1,6 @@
 ---
 title: Pipeline
-titleTemplate: '... - Electric Agents'
+titleTemplate: "... - Electric Agents"
 description: >-
   Sequential processing pattern where each stage's output feeds into the next via state transitions.
 outline: [2, 3]

package/docs/entities/patterns/reactive-observers.md

@@ -1,6 +1,6 @@
 ---
 title: Reactive observers
-titleTemplate: '... - Electric Agents'
+titleTemplate: "... - Electric Agents"
 description: >-
   Pattern for entities that watch others and react to changes using ctx.observe() with wake conditions.
 outline: [2, 3]
@@ -66,7 +66,7 @@ The monitor wraps the base observe tool to also transition its own state to `obs
 The `observe_entity` tool lets the LLM decide what to watch:
 
 ```ts
-import { entity } from '@electric-ax/agents-runtime'
+import { entity } from "@electric-ax/agents-runtime"
 
 export function createObserveTool(ctx: HandlerContext): AgentTool {
   return {