@electric-ax/agents 0.2.4 → 0.3.0

package/docs/usage/embedded-builtins.md

@@ -2,18 +2,18 @@
 title: Embedded built-ins
 titleTemplate: "... - Electric Agents"
 description: >-
-  Embed the built-in Horton, worker, and coder runtime in your own process using
+  Embed the built-in Horton and worker runtime in your own process using
   @electric-ax/agents, BuiltinAgentsServer, or the entrypoint helpers.
 outline: [2, 3]
 ---
 
 # Embedded built-ins
 
-The CLI commands `electric agents start-builtin` and `electric agents quickstart` run the built-in Horton, worker, and coder runtime for you. If you need to host those built-ins inside your own process, use the exported APIs from `@electric-ax/agents`.
+The CLI commands `electric agents start-builtin` and `electric agents quickstart` run the built-in Horton and worker runtime for you. If you need to host those built-ins inside your own process, use the exported APIs from `@electric-ax/agents`.
 
 ## BuiltinAgentsServer
 
-`BuiltinAgentsServer` starts an HTTP webhook server, registers `horton`, `worker`, and `coder`, and forwards Electric Agents webhook wakes to the built-in handler.
+`BuiltinAgentsServer` starts an HTTP webhook server, registers `horton` and `worker`, and forwards Electric Agents webhook wakes to the built-in handler.
 
 ```ts
 import { BuiltinAgentsServer } from "@electric-ax/agents"
@@ -49,19 +49,30 @@ interface BuiltinAgentsServerOptions {
   mockStreamFn?: StreamFn
   webhookPath?: string
   createElectricTools?: CreateElectricTools
+  // MCP integration
+  extraMcpServers?: ReadonlyArray<McpServerConfig>
+  loadProjectMcpConfig?: boolean
+  mcpOAuthRedirectBase?: string
+  openAuthorizeUrl?: (url: string, server: string) => void
+  onConfigError?: (error: unknown) => void
 }
 ```
 
-| Field                 | Description                                                                 |
-| --------------------- | --------------------------------------------------------------------------- |
-| `agentServerUrl`      | Electric Agents coordinator server URL.                                     |
-| `baseUrl`             | Public base URL used when registering the webhook. Defaults to local URL.   |
-| `port`                | Local webhook server port.                                                  |
-| `host`                | Bind host. Defaults to `127.0.0.1`.                                         |
-| `workingDirectory`    | Directory used by Horton, worker file tools, and the default coder cwd. Defaults to `process.cwd()`. |
-| `mockStreamFn`        | Optional test stream function. Lets you run without `ANTHROPIC_API_KEY`.    |
-| `webhookPath`         | Webhook path. Defaults to `/_electric/builtin-agent-handler`.               |
-| `createElectricTools` | Optional factory for extra tools injected into built-in agent handlers.     |
+| Field                  | Description                                                                                                                                                                                                                                                                            |
+| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `agentServerUrl`       | Electric Agents coordinator server URL.                                                                                                                                                                                                                                                |
+| `baseUrl`              | Public base URL used when registering the webhook. Defaults to local URL.                                                                                                                                                                                                              |
+| `port`                 | Local webhook server port.                                                                                                                                                                                                                                                             |
+| `host`                 | Bind host. Defaults to `127.0.0.1`.                                                                                                                                                                                                                                                    |
+| `workingDirectory`     | Directory used by Horton and worker file tools. Defaults to `process.cwd()`.                                                                                                                                                                                                           |
+| `mockStreamFn`         | Optional test stream function. Lets you run without `ANTHROPIC_API_KEY`.                                                                                                                                                                                                               |
+| `webhookPath`          | Webhook path. Defaults to `/_electric/builtin-agent-handler`.                                                                                                                                                                                                                          |
+| `createElectricTools`  | Optional factory for extra tools injected into built-in agent handlers.                                                                                                                                                                                                                |
+| `extraMcpServers`      | MCP servers contributed by the embedder. On name conflict with `mcp.json`, `mcp.json` wins. `authorizationCode` servers are auto-wired with `keychainPersistence`.                                                                                                                     |
+| `loadProjectMcpConfig` | Load `<workingDirectory>/mcp.json` (and watch it). Off by default — stdio MCP servers can spawn local commands, so the embedder must opt in. The Electron desktop and `electric-ax` CLI opt in.                                                                                        |
+| `mcpOAuthRedirectBase` | Base for OAuth redirect URIs (full URI is `<base>/oauth/callback/<server-name>`). MUST be stable across restarts so DCR client info stays valid; required when listening on `port: 0`. The runtime never listens at this URI — the embedder intercepts the redirect.                   |
+| `openAuthorizeUrl`     | Hook invoked when an `authorizationCode` MCP server first needs user consent. Receives the SDK-generated authorize URL. The desktop opens it in a sandboxed `BrowserWindow`; headless embedders can read the URL from the `authenticating` envelope of `addServer` and surface it themselves. |
+| `onConfigError`        | Invoked when applying an MCP config (initial boot or watcher reload) fails. Errors are always logged; this hook is for surfacing them programmatically.                                                                                                                                |
 
 Without `mockStreamFn`, `ANTHROPIC_API_KEY` must be present before the built-in handler starts.
 
@@ -160,7 +171,7 @@ Environment variables:
 | `ELECTRIC_AGENTS_BUILTIN_BASE_URL` | Public webhook base URL for the built-in server.   |
 | `ELECTRIC_AGENTS_BUILTIN_HOST`   | Bind host.                                            |
 | `ELECTRIC_AGENTS_BUILTIN_PORT`   | Built-in server port. Defaults to `4448`.             |
-| `ELECTRIC_AGENTS_WORKING_DIRECTORY` | Working directory for file tools and default coder sessions. |
+| `ELECTRIC_AGENTS_WORKING_DIRECTORY` | Working directory for file tools. |
 
 ## Built-in Agent APIs
 
@@ -170,7 +181,6 @@ The built-in agent exports are also available if you want to compose your own ru
 | ------------------------- | --------------------------------------------------- |
 | `registerHorton()`        | Register the `horton` type on an `EntityRegistry`.  |
 | `registerWorker()`        | Register the `worker` type on an `EntityRegistry`.  |
-| `registerCodingSession()` | Register the `coder` type on an `EntityRegistry`.   |
 | `HORTON_MODEL`            | Default model id used by Horton and worker.         |
 | `buildHortonSystemPrompt()` | Build Horton's system prompt for a working directory. |
 | `createHortonTools()`     | Create Horton's base shell/file/search/worker tools. |
@@ -178,4 +188,4 @@ The built-in agent exports are also available if you want to compose your own ru
 | `WORKER_TOOL_NAMES`       | Valid primitive tool names for workers.             |
 | `createHortonDocsSupport()` | Create Horton's docs knowledge-base support.       |
 
-For the behavior of `horton`, `worker`, and `coder`, see [Horton](../entities/agents/horton), [Worker](../entities/agents/worker), and [Coder](../entities/agents/coder).
+For the behavior of `horton` and `worker`, see [Horton](../entities/agents/horton) and [Worker](../entities/agents/worker).

package/docs/usage/mcp-servers.md

@@ -0,0 +1,354 @@
+---
+title: MCP servers
+titleTemplate: "... - Electric Agents"
+description: >-
+  Connect agents to external tools, resources, and prompts via the
+  Model Context Protocol. Register servers programmatically through the
+  Registry API, declaratively in mcp.json, or globally in the desktop
+  app's settings.
+outline: [2, 3]
+---
+
+# MCP servers
+
+The runtime ships an embedded **MCP registry** that connects agents to external [Model Context Protocol](https://modelcontextprotocol.io) servers — both locally-spawned `stdio` servers and remote `Streamable HTTP` servers. Tools, resources, and prompts exposed by those servers become available to every entity at the next wake without per-agent wiring.
+
+## Registering servers
+
+`Registry` is the primary API. Agent authors call into it directly when they're defining or hosting agents in code. `mcp.json` and the desktop app's `settings.json` are file-based convenience layers that the runtime turns into the same `Registry.applyConfig()` calls under the hood.
+
+### Programmatic — `Registry.addServer()` / `applyConfig()`
+
+`BuiltinAgentsServer` exposes the registry through `mcpRegistry`. Add servers from code anywhere it's the right shape — at boot from your own config source, in response to user actions, or per-session for tools an agent should only see during a specific task:
+
+```ts
+import { BuiltinAgentsServer } from "@electric-ax/agents"
+
+const server = new BuiltinAgentsServer({
+  agentServerUrl: "http://localhost:4437",
+  port: 4448,
+  workingDirectory: process.cwd(),
+})
+
+await server.start()
+
+const result = await server.mcpRegistry?.addServer({
+  name: "stripe",
+  transport: "http",
+  url: "https://mcp.stripe.com/mcp",
+  auth: {
+    mode: "apiKey",
+    headerName: "Authorization",
+    key: process.env.STRIPE_MCP_KEY!,
+  },
+})
+```
+
+`addServer` returns a discriminated [`AddServerResult`](#addserverresult) — `{ state: "ready" | "authenticating" | "error", … }`. The state landscape is described in [Server states](#server-states) below; the full lifecycle (hot-reload, reauthorize, timeouts) lives in [Lifecycle](#lifecycle).
+
+The bulk methods are:
+
+- `applyConfig(cfg)` — replace the full set of servers. Idempotent on unchanged entries; removes anything not in the supplied config. This is what file-based config layers compile down to.
+- `subscribe(handler)` — push-based view of the live state, including `ready` / `authenticating` / `error` transitions. Useful when an embedder renders its own UI on top of the registry.
+- `reauthorize(name)`, `disable(name)`, `enable(name)`, `removeServer(name)` — single-server lifecycle.
+
+Static secrets (`apiKey.key`, `clientCredentials.clientId` / `clientSecret`) are passed inline at the call site — typically read from `process.env`. The runtime never reads environment variables on the embedder's behalf. See [`McpServerConfig`](/docs/agents/reference/mcp-server-config) for the full schema.
+
+### File-based — `mcp.json`
+
+For static, project-scoped configuration the runtime can load `mcp.json` from the configured `workingDirectory`, watch it for changes, and hot-reload adds, removes, and reconfigurations through `applyConfig` — exactly as if you'd called the API yourself. In-flight tool calls finish on the old config; new calls pick up the new one.
+
+`mcp.json` loading is opt-in: stdio MCP servers spawn local commands, so picking a working directory must not auto-execute config from it. The Electron desktop and the `electric-ax` CLI opt in by default. Library embedders that construct `BuiltinAgentsServer` directly enable it with `loadProjectMcpConfig: true` (which loads `<workingDirectory>/mcp.json` and watches it).
+
+`mcp.json` carries structural shape only — no secrets:
+
+```jsonc
+{
+  "servers": {
+    "honeycomb": {
+      "transport": "http",
+      "url": "https://mcp.honeycomb.io/mcp",
+      "auth": {
+        "mode": "authorizationCode",
+        "scopes": ["mcp:read", "mcp:write"]
+      }
+    },
+    "internal-api": {
+      "transport": "http",
+      "url": "https://api.example.com/mcp",
+      "auth": {
+        "mode": "apiKey",
+        "headerName": "X-Api-Key"
+      }
+    },
+    "git-local": {
+      "transport": "stdio",
+      "command": "npx",
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-git",
+        "--repository",
+        "${workspaceRoot}"
+      ]
+    }
+  }
+}
+```
+
+For [`authorizationCode`](#authorization-code-oauth) servers in `mcp.json`, the runtime auto-wires `keychainPersistence` so OAuth tokens survive process restarts via the OS keychain.
+
+### Desktop settings layer
+
+The Electron desktop app exposes a second file-based layer: a global `mcp.servers` block in its `settings.json`, applied to every workspace. The shape mirrors `mcp.json` — keyed by server name — so entries can be copy-pasted between the two files. It composes with the workspace `mcp.json` instead of replacing it:
+
+- Servers from both files load together when their names don't collide.
+- On a name collision, the workspace `mcp.json` wins (project scope overrides global).
+- `keychainPersistence` is auto-wired for OAuth servers from either source.
+
+The `settings.json` lives at:
+
+| OS      | Path                                                    |
+| ------- | ------------------------------------------------------- |
+| macOS   | `~/Library/Application Support/Electric Agents/`        |
+| Linux   | `~/.config/Electric Agents/`                            |
+| Windows | `%APPDATA%\Electric Agents\`                            |
+
+Example shape:
+
+```jsonc
+{
+  "servers": [...],
+  "activeServer": {...},
+  "workingDirectory": "/Users/me/workspace/foo",
+  "apiKeys": {...},
+  "mcp": {
+    "servers": {
+      "linear": {
+        "transport": "http",
+        "url": "https://mcp.linear.app/sse",
+        "auth": { "mode": "authorizationCode", "scopes": ["mcp:read"] }
+      }
+    }
+  }
+}
+```
+
+Programmatic embedders (other than the desktop) pass the resolved set as an array via `BuiltinAgentsServer({ extraMcpServers })` — that's the in-memory shape `settings.json` is rewritten into when the desktop loads it.
+
+## Per-agent allowlist
+
+Entity definitions opt into MCP servers explicitly via the `mcp.tools()` helper from `@electric-ax/agents-runtime`:
+
+```ts
+import { mcp } from "@electric-ax/agents-runtime"
+
+registry.define("research-agent", {
+  async handler(ctx) {
+    ctx.useAgent({
+      systemPrompt: "...",
+      tools: [
+        ...ctx.electricTools,
+        ...mcp.tools(["sentry", "github"]), // explicit list
+        // or: ...mcp.tools()                 // every registered server
+      ],
+    })
+    await ctx.agent.run()
+  },
+})
+```
+
+The resolved tool set is recorded in the agent's manifest at compose time. Tools are exposed to the model with always-prefixed names matching Anthropic's tool-name regex (`^[a-zA-Z0-9_-]{1,128}$`):
+
+- Tools: `mcp__sentry__search`, `mcp__github__create_issue`, …
+- Resources: `mcp__<server>__list_resources`, `mcp__<server>__read_resource`
+- Prompts: `mcp__<server>__list_prompts`, `mcp__<server>__get_prompt`
+
+Built-in entities `horton` and `worker` opt in to all registered servers via `mcp.tools()`.
+
+## Auth modes
+
+Each server declares one auth mode. The runtime keeps a valid token in hand on every call: silent refresh when possible, or a structured `auth_unavailable` error to the agent's model when not.
+
+### `apiKey`
+
+```ts
+auth: {
+  mode: "apiKey",
+  key: process.env.X_API_KEY!,
+  headerName: "X-Api-Key",  // default "Authorization"
+  valuePrefix: "Bearer ",   // optional
+}
+```
+
+The header is sent on every request. Rotate by editing the config; the registry's idempotency check picks up the change and rebuilds the transport on the next reload.
+
+### `clientCredentials`
+
+```ts
+auth: {
+  mode: "clientCredentials",
+  tokenUrl: "https://auth.example.com/oauth/token",
+  clientId: process.env.X_CLIENT_ID!,
+  clientSecret: process.env.X_CLIENT_SECRET!,
+  scopes: ["mcp:read"],
+}
+```
+
+The runtime exchanges the client credentials for short-lived access tokens silently. No user interaction.
+
+### `authorizationCode` (OAuth)
+
+```ts
+auth: {
+  mode: "authorizationCode",
+  scopes: ["mcp:read"],
+  // optional — pre-registered OAuth client (skips DCR)
+  client: { clientId: "...", clientSecret: "..." },
+  // optional — pre-existing tokens (skips OAuth flow on boot)
+  tokens: { accessToken: "...", refreshToken: "...", expiresAt: 1736e9 },
+  // fires on initial auth + every refresh — wire to your persistence
+  onTokensChanged: async (t) => { /* persist */ },
+  // fires once after RFC 7591 DCR completes
+  onClientRegistered: async (c) => { /* persist */ },
+}
+```
+
+The MCP SDK handles PKCE, RFC 7591 Dynamic Client Registration, RFC 9728 Protected Resource Metadata discovery, and 401-retry transparently. The first time a server is used:
+
+1. The runtime captures an authorize URL and surfaces it through the `openAuthorizeUrl(url, server)` hook on `BuiltinAgentsServer`.
+2. The Electron desktop opens the URL in a sandboxed `BrowserWindow` and intercepts the `redirect_uri` navigation client-side — the redirect URL is never actually fetched, so no HTTP listener is needed.
+3. The runtime exchanges the captured `code` + `state` for tokens and fires `onTokensChanged`.
+
+Subsequent restarts re-seed from persisted tokens; refresh-token rotation happens silently on every call.
+
+The redirect URI registered with the auth server during DCR is `<mcpOAuthRedirectBase>/oauth/callback/<server-name>`. Embedders that listen on an ephemeral port (the desktop runs on `port: 0`) MUST pass a stable `mcpOAuthRedirectBase` to `BuiltinAgentsServer` — otherwise the cached DCR client info goes stale on every restart and users have to re-authorize every launch. The desktop sets it to a fixed loopback literal (`http://127.0.0.1:53117`) per RFC 8252 §7.3; nothing actually listens at the port. Headless embedders that use port 0 with persisted credentials need to do the same.
+
+#### Persistence helpers
+
+`@electric-ax/agents-mcp` ships two opt-in helpers that produce the auth-config slice:
+
+```ts
+import { keychainPersistence, filePersistence } from "@electric-ax/agents-mcp"
+
+const honeycomb = await keychainPersistence({ server: "honeycomb" })
+
+await mcpRegistry.addServer({
+  name: "honeycomb",
+  transport: "http",
+  url: "https://mcp.honeycomb.io/mcp",
+  auth: {
+    mode: "authorizationCode",
+    scopes: ["mcp:read"],
+    ...honeycomb,
+  },
+})
+```
+
+| Helper                             | Backing store                                                    | When to use                                              |
+| ---------------------------------- | ---------------------------------------------------------------- | -------------------------------------------------------- |
+| `keychainPersistence({ server })`  | OS keychain (macOS `security`, Linux `secret-tool`)              | Local dev / desktop apps; tokens encrypted by the OS     |
+| `filePersistence({ path, server })` | Mode-`0600` JSON file                                           | CI / containers without an OS keychain                   |
+
+For Vault, SSM, or a custom secret system, write your own `onTokensChanged` and `onClientRegistered` directly. The contract is two callbacks and two optional values.
+
+## Server states
+
+Every server entry the registry tracks is in exactly one of five states. The state is the `status` field on `ListedEntry` (returned by `Registry.list()` and emitted on every snapshot through `subscribe`), and it's the discriminator on the `AddServerResult` envelope returned from `addServer` / `applyConfig` / `finishAuth` / `enable`.
+
+| State            | Meaning                                                                                                                            | Side data                                       |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
+| `connecting`     | Transport is being built (RFC 9728 discovery, RFC 7591 DCR, stdio spawn, HTTP handshake) or rebuilt after `reauthorize` / `enable`. | —                                               |
+| `authenticating` | An `authorizationCode` server needs the user. The SDK has produced an authorize URL; the embedder's `openAuthorizeUrl` hook fired. | `authUrl: string`                               |
+| `ready`          | Connected. Tools listed. Calls succeed and stream through the bridge.                                                              | `toolCount: number`, `tools: [...]`             |
+| `error`          | Transport, auth-config, or `addServer` validation failure. The entry stays in `list()` so the UI can surface the failure.          | `error: { kind, message, details? }`            |
+| `disabled`       | Operator paused the server via `Registry.disable(name)`. Transport closed; tokens stay in the cache.                                | —                                               |
+
+Transitions are driven by registry methods. The high-level shape:
+
+```
+                    ┌──────────────┐    success     ┌──────────┐
+   addServer ──────▶│  connecting  │───────────────▶│  ready   │
+   applyConfig      └──────┬───────┘                └────┬─────┘
+   enable                  │                             │
+                           │ no tokens / 401             │
+                           ▼                             │
+                    ┌──────────────┐  finishAuth         │
+                    │authenticating│───────────────────▶─┘
+                    └──────┬───────┘  (retries connect)
+                           │
+                           │ unrecoverable
+                           ▼
+                    ┌──────────────┐
+                    │    error     │
+                    └──────────────┘
+
+   reauthorize:  any non-disabled  ──▶ connecting ──▶ authenticating
+   disable:      any               ──▶ disabled
+   enable:       disabled          ──▶ connecting ──▶ ready (or authenticating, or error)
+   removeServer: any               ──▶ (entry gone)
+```
+
+A few specifics worth knowing:
+
+- **`error` is sticky.** It doesn't auto-recover. Reach `ready` again by calling `addServer` with the same config (idempotency picks up changes), `reauthorize(name)`, or — for transient transport issues — re-running through `applyConfig`. The entry stays in the snapshot the whole time.
+- **`reauthorize` always lands in `connecting` first**, then typically `authenticating` because tokens are intentionally cleared. The mutation is in-place — subscribers never see the entry disappear, so renderers don't flicker.
+- **`disable` is recoverable.** It closes the transport but keeps tokens, hooks, and the entry. `enable` rebuilds the transport from the same config; if tokens are still valid, the next state is `ready` without an OAuth round-trip.
+- **`removeServer` is destructive.** It clears tokens from the in-memory cache (persisted tokens via `onTokensChanged` stay where the operator put them) and removes the entry. There is no UI affordance for it on the desktop — Disable is the recoverable equivalent.
+
+For the full per-method API (including `subscribe`, `RegistrySnapshot`, and `RegistryOpts`), see the [`McpRegistry` reference](/docs/agents/reference/mcp-registry).
+
+## Lifecycle
+
+### Hot-reload
+
+Editing `mcp.json` (or calling `applyConfig` programmatically) takes effect immediately:
+
+- **New server.** Tools available at the next tool-selection step in any active wake; manifests of agents using `mcp.tools()` update at the next compose.
+- **Removed server.** In-flight tool calls complete or fail cleanly; no new calls dispatch; stdio subprocesses terminate after in-flight calls drain.
+- **Reconfigured server.** Takes effect on the next tool call to that server. In-flight calls finish on the old config.
+
+`addServer` and `applyConfig` are idempotent on unchanged config — they compare by `(name, url, transport, authMode, scopes, timeoutMs, command, args)` and short-circuit when nothing changed. Spurious file-system events from macOS reload watchers won't tear down healthy connections.
+
+### Re-authorize
+
+Calling `Registry.reauthorize(name)` forces a fresh OAuth flow without removing the entry from the registry. The transport is closed, tokens are dropped from the in-memory cache (hooks remain registered), and the SDK produces a new authorize URL that fires through the `openAuthorizeUrl` hook. The entry stays in every snapshot throughout, so subscribers don't see it disappear and reappear.
+
+The desktop's **Authorize** button routes through this method. It's enabled when the server is in `authenticating` (initial sign-in) or `error` (recover from a stale-token state). Once the server is `ready` the same button label switches to **Re-authorize** and forces a fresh OAuth flow — useful when refresh-token rotation has stopped working and you want to re-bootstrap without removing the server.
+
+### Per-call timeouts
+
+Every MCP tool call has a timeout (default 30 seconds, overridable per server via `timeoutMs`). When exceeded, the bridge cancels the call (JSON-RPC cancellation for stdio servers; HTTP request abort for HTTP servers) and resolves it with a `timeout` error result. The agent's model decides what to do — retry, fall back, abort.
+
+The timeout is a hygiene feature, not a long-running-call solution. Tool calls in v1 are synchronous within the wake.
+
+## Connected Services UI (desktop)
+
+The Electron desktop ships a **Settings → MCP Servers** page that mirrors `Registry.subscribe` over Electron IPC. Each row shows:
+
+- **Name and transport** (stdio / http).
+- **Auth mode** (apiKey / clientCredentials / authorizationCode).
+- **Status** — `connecting`, `authenticating`, `ready`, `error`, or `disabled`.
+- **Tool count + expandable tool list.**
+- **Per-row actions:** Authorize (only when a server is in `authenticating`), Reconnect, Disable / Enable.
+
+The page is the operator's primary mechanism for noticing and fixing broken credentials, and the developer's primary surface for kicking off initial OAuth flows. There is no Disconnect action: removal of an entry happens via editing the config file. Disable pauses without losing state and is recoverable from the UI.
+
+## Failure modes
+
+The runtime returns a structured error to the agent's model on any tool-call failure it can't transparently recover from:
+
+| Kind                | Meaning                                                                                |
+| ------------------- | -------------------------------------------------------------------------------------- |
+| `auth_unavailable`  | Silent refresh failed and no credential is usable; operator must reauthorize.          |
+| `transport_error`   | Server unreachable, connection dropped, malformed response.                            |
+| `timeout`           | Call exceeded its per-call timeout.                                                    |
+| `server_error`      | The MCP server returned a structured error.                                            |
+| `tool_not_found`    | Capability mismatch (e.g. server's tool list changed since compose).                   |
+
+Agents handle these like any other tool error: retry, fall back, give up gracefully, or escalate to the user. The runtime doesn't block tool calls indefinitely waiting for out-of-band recovery.
+
+## Reference
+
+- [`McpRegistry`](/docs/agents/reference/mcp-registry) — full API: `addServer`, `applyConfig`, `subscribe`, `reauthorize`, the lifecycle, snapshot envelope, and `RegistryOpts` for custom embedders.
+- [`McpServerConfig`](/docs/agents/reference/mcp-server-config) — schema for the `cfg` argument to `addServer` / `applyConfig`.
+- [`BuiltinAgentsServer` options](/docs/agents/usage/embedded-builtins) — the `extraMcpServers` and `openAuthorizeUrl` options used to wire embedder-specific MCP behavior.

package/docs/usage/overview.md

@@ -51,7 +51,6 @@ The context API passed into the handler:
 | `ctx.sleep()`                       | Return to idle                                                        |
 | `ctx.mkdb(id, schema)`              | Create cross-entity shared state                                      |
 | `ctx.observe(db(id, schema), opts)` | Join existing shared state                                            |
-| `ctx.useCodingAgent(sessionId, opts)` | Spawn or attach to a built-in `coder` session                       |
 | `ctx.recordRun()`                   | Record non-LLM work as a run for `runFinished` observers              |
 | `ctx.setTag(key, value)`            | Set a tag on this entity                                              |
 | `ctx.removeTag(key)`                | Remove a tag from this entity                                         |
@@ -176,7 +175,6 @@ See [Managing state](/docs/agents/usage/managing-state).
   - `opts.wake` -- `'runFinished'`, `{ on: 'runFinished', includeResponse? }`, or `{ on: 'change', collections?, debounceMs?, timeoutMs? }`
 - **`observe(source, opts)`** -> `EntityHandle | ObservationHandle` -- subscribe via `entity()`, `cron()`, `entities()`, `db()`
 - **`send(url, payload, opts)`** -- fire-and-forget message
-- **`useCodingAgent(sessionId, opts)`** -> `CodingSessionHandle` -- spawn or attach to a built-in Claude Code/Codex session
 - **`recordRun()`** -> `RunHandle` -- publish run lifecycle for external work
 - **`sleep()`** -- go idle
 
@@ -286,6 +284,6 @@ Use the client and embedding APIs when you need to work with agents outside an e
 | `createAgentsClient()`            | Observe entity, membership, or shared-state streams from app code |
 | `useChat()`                       | Render an observed `EntityStreamDB` in React  |
 | `createRuntimeServerClient()`     | Spawn, message, delete, tag, and schedule entities from services |
-| `BuiltinAgentsServer`             | Host Horton, worker, and coder in your own process |
+| `BuiltinAgentsServer`             | Host Horton and worker in your own process |
 
 See [Clients & React](/docs/agents/usage/clients-and-react), [Programmatic runtime client](/docs/agents/usage/programmatic-runtime-client), and [Embedded built-ins](/docs/agents/usage/embedded-builtins).

package/docs/usage/programmatic-runtime-client.md

@@ -202,7 +202,7 @@ await client.deleteSchedule({
 
 ## Tags
 
-`setTag()` and `removeTag()` require the entity write token. Handler code should prefer `ctx.setTag()` and `ctx.removeTag()` because the runtime already has the write token.
+`setTag()` and `removeTag()` are primarily for handler/runtime-owned flows that already hold the current claim-scoped write token. External clients should prefer `send()` and write only to an entity's inbox rather than writing entity state directly.
 
 ```ts
 await client.setTag("/horton/onboarding", "title", "Onboarding", writeToken)

package/docs/usage/writing-handlers.md

@@ -57,10 +57,6 @@ interface HandlerContext<TState extends StateProxy = StateProxy> {
     id: string,
     schema: T
   ) => SharedStateHandle<T>
-  useCodingAgent: (
-    sessionId: string,
-    opts: UseCodingAgentOptions
-  ) => Promise<CodingSessionHandle>
   send: (
     entityUrl: string,
     payload: unknown,
@@ -98,7 +94,6 @@ 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.                                                                                                                              |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@electric-ax/agents",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "description": "Built-in Electric Agents runtimes such as Horton and worker",
   "repository": {
     "type": "git",
@@ -28,25 +28,26 @@
     "./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"
   },
@@ -61,6 +62,7 @@
   "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",

package/docs/entities/agents/coder.md

@@ -1,99 +0,0 @@
----
-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 |