@electric-ax/agents 0.2.3 → 0.3.0

package/docs/reference/built-in-collections.md

@@ -1,6 +1,6 @@
 ---
 title: Built-in collections
-titleTemplate: '... - Electric Agents'
+titleTemplate: "... - Electric Agents"
 description: >-
   Reference for the 17 runtime-managed collections: runs, steps, texts, toolCalls, inbox, errors, and more.
 outline: [2, 3]
@@ -43,7 +43,7 @@ All collections use `key` as the primary key.
 ```ts
 interface Run {
   key: string
-  status: 'started' | 'completed' | 'failed'
+  status: "started" | "completed" | "failed"
   finish_reason?: string
 }
 ```
@@ -55,7 +55,7 @@ interface Step {
   key: string
   run_id?: string
   step_number: number
-  status: 'started' | 'completed'
+  status: "started" | "completed"
   finish_reason?: string
   model_provider?: string
   model_id?: string
@@ -69,7 +69,7 @@ interface Step {
 interface Text {
   key: string
   run_id?: string
-  status: 'streaming' | 'completed'
+  status: "streaming" | "completed"
 }
 ```
 
@@ -91,7 +91,7 @@ interface ToolCall {
   key: string
   run_id?: string
   tool_name: string
-  status: 'started' | 'args_complete' | 'executing' | 'completed' | 'failed'
+  status: "started" | "args_complete" | "executing" | "completed" | "failed"
   args?: unknown
   result?: unknown
   error?: string
@@ -104,7 +104,7 @@ interface ToolCall {
 ```ts
 interface Reasoning {
   key: string
-  status: 'streaming' | 'completed'
+  status: "streaming" | "completed"
 }
 ```
 
@@ -148,14 +148,14 @@ interface WakeEntry {
 
 interface WakeChangeEntry {
   collection: string
-  kind: 'insert' | 'update' | 'delete'
+  kind: "insert" | "update" | "delete"
   key: string
 }
 
 interface WakeFinishedChildEntry {
   url: string
   type: string
-  run_status: 'completed' | 'failed'
+  run_status: "completed" | "failed"
   response?: string // concatenated text deltas from the finished run
   error?: string // error message(s) if run_status is "failed"
 }
@@ -163,7 +163,7 @@ interface WakeFinishedChildEntry {
 interface WakeOtherChildEntry {
   url: string
   type: string
-  status: 'spawning' | 'running' | 'idle' | 'stopped'
+  status: "spawning" | "running" | "idle" | "stopped"
 }
 ```
 
@@ -196,7 +196,7 @@ interface ChildStatusEntry {
   key: string
   entity_url: string
   entity_type: string
-  status: 'spawning' | 'running' | 'idle' | 'stopped'
+  status: "spawning" | "running" | "idle" | "stopped"
 }
 ```
 
@@ -249,7 +249,7 @@ type Manifest =
 
 interface ManifestChildEntry {
   key: string
-  kind: 'child'
+  kind: "child"
   id: string
   entity_type: string
   entity_url: string
@@ -259,7 +259,7 @@ interface ManifestChildEntry {
 
 interface ManifestSourceEntry {
   key: string
-  kind: 'source'
+  kind: "source"
   sourceType: string
   sourceRef: string
   wake?: WakeConfig
@@ -268,16 +268,16 @@ interface ManifestSourceEntry {
 
 interface ManifestSharedStateEntry {
   key: string
-  kind: 'shared-state'
+  kind: "shared-state"
   id: string
-  mode: 'create' | 'connect'
+  mode: "create" | "connect"
   collections: Record<string, { type: string; primaryKey: string }>
   wake?: WakeConfig
 }
 
 interface ManifestEffectEntry {
   key: string
-  kind: 'effect'
+  kind: "effect"
   id: string
   function_ref: string
   config: unknown
@@ -285,7 +285,7 @@ interface ManifestEffectEntry {
 
 interface ManifestContextEntry {
   key: string
-  kind: 'context'
+  kind: "context"
   id: string
   name: string
   attrs: Record<string, string | number | boolean>
@@ -295,9 +295,9 @@ interface ManifestContextEntry {
 
 interface ManifestCronScheduleEntry {
   key: string
-  kind: 'schedule'
+  kind: "schedule"
   id: string
-  scheduleType: 'cron'
+  scheduleType: "cron"
   expression: string
   timezone?: string
   payload?: unknown
@@ -306,16 +306,16 @@ interface ManifestCronScheduleEntry {
 
 interface ManifestFutureSendScheduleEntry {
   key: string
-  kind: 'schedule'
+  kind: "schedule"
   id: string
-  scheduleType: 'future_send'
+  scheduleType: "future_send"
   fireAt: string
   targetUrl: string
   payload: unknown
   producerId: string
   from?: string
   messageType?: string
-  status?: 'pending' | 'sent' | 'failed'
+  status?: "pending" | "sent" | "failed"
   sentAt?: string
   failedAt?: string
   lastError?: string

package/docs/reference/cli.md

@@ -1,6 +1,6 @@
 ---
 title: CLI
-titleTemplate: '... - Electric Agents'
+titleTemplate: "... - Electric Agents"
 description: >-
   Command reference for the Electric Agents CLI: spawn, send, observe, inspect, list, and manage entities.
 outline: [2, 3]
@@ -16,14 +16,14 @@ npm install -g electric-ax
 
 ## Environment variables
 
-| Variable                          | Default                 | Purpose                                       |
-| --------------------------------- | ----------------------- | --------------------------------------------- |
-| `ELECTRIC_AGENTS_URL`             | `http://localhost:4437` | Server URL for entity commands and built-ins  |
-| `ELECTRIC_AGENTS_IDENTITY`        | `user@hostname`         | Sender identity for messages                  |
-| `ELECTRIC_AGENTS_PORT`            | `4437`                  | Port used by `start` / `quickstart`           |
-| `ELECTRIC_AGENTS_BUILTIN_PORT`    | `4448`                  | Webhook port for `start-builtin`              |
-| `ELECTRIC_AGENTS_COMPOSE_PROJECT` | `electric-agents`       | Docker Compose project name                   |
-| `ANTHROPIC_API_KEY`               | -                       | Required for `start-builtin` and `quickstart` |
+| Variable                         | Default                 | Purpose                                      |
+| -------------------------------- | ----------------------- | -------------------------------------------- |
+| `ELECTRIC_AGENTS_URL`            | `http://localhost:4437` | Server URL for entity commands and built-ins |
+| `ELECTRIC_AGENTS_IDENTITY`       | `user@hostname`         | Sender identity for messages                 |
+| `ELECTRIC_AGENTS_PORT`           | `4437`                  | Port used by `start` / `quickstart`          |
+| `ELECTRIC_AGENTS_BUILTIN_PORT`   | `4448`                  | Webhook port for `start-builtin`             |
+| `ELECTRIC_AGENTS_COMPOSE_PROJECT` | `electric-agents`       | Docker Compose project name                  |
+| `ANTHROPIC_API_KEY`              | -                       | Required for `start-builtin` and `quickstart` |
 
 ## Commands
 
@@ -142,9 +142,9 @@ Start the built-in Horton runtime and register built-in agent types with the coo
 electric agents start-builtin --anthropic-api-key sk-ant-...
 ```
 
-| Option                      | Description                                      |
-| --------------------------- | ------------------------------------------------ |
-| `--anthropic-api-key <key>` | Anthropic API key for the built-in Horton server |
+| Option                         | Description                                    |
+| ------------------------------ | ---------------------------------------------- |
+| `--anthropic-api-key <key>`    | Anthropic API key for the built-in Horton server |
 
 ### <span class="cli-command"><code>quickstart [--anthropic-api-key &lt;key&gt;]</code></span> {#quickstart}
 
@@ -154,9 +154,9 @@ Start the coordinator server, print onboarding commands, and run the built-in ag
 electric agents quickstart --anthropic-api-key sk-ant-...
 ```
 
-| Option                      | Description                                      |
-| --------------------------- | ------------------------------------------------ |
-| `--anthropic-api-key <key>` | Anthropic API key for the built-in Horton server |
+| Option                         | Description                                    |
+| ------------------------------ | ---------------------------------------------- |
+| `--anthropic-api-key <key>`    | Anthropic API key for the built-in Horton server |
 
 ### <span class="cli-command"><code>stop [--remove-volumes]</code></span> {#stop}
 
@@ -171,6 +171,15 @@ electric agents stop --remove-volumes
 | ------------------ | ------------------------------ |
 | `--remove-volumes` | Remove Docker volumes as well. |
 
+### <span class="cli-command"><code>init [project-name]</code></span> {#init-project-name}
+
+Scaffold a new Electric Agents project from the bundled starter template.
+
+```bash
+electric agents init
+electric agents init my-agents-app
+```
+
 ### <span class="cli-command"><code>completion [action]</code></span> {#completion-action}
 
 Set up shell completions. Without arguments, prints setup instructions.
@@ -202,32 +211,32 @@ import {
   createElectricProgram,
   getElectricCliEnv,
   run,
-} from 'electric-ax'
+} from "electric-ax"
 
 const env = getElectricCliEnv({
-  ELECTRIC_AGENTS_URL: 'http://localhost:4437',
-  ELECTRIC_AGENTS_IDENTITY: 'docs@example.com',
+  ELECTRIC_AGENTS_URL: "http://localhost:4437",
+  ELECTRIC_AGENTS_IDENTITY: "docs@example.com",
 })
 
-const handlers = createElectricCliHandlers(env, 'electric agents')
+const handlers = createElectricCliHandlers(env, "electric agents")
 const program = createElectricProgram({
   env,
   handlers,
-  commandName: 'electric',
-  commandPrefix: 'electric agents',
+  commandName: "electric",
+  commandPrefix: "electric agents",
 })
 
-await program.parseAsync(['node', 'electric', 'agents', 'types'])
+await program.parseAsync(["node", "electric", "agents", "types"])
 ```
 
-| Export                             | Purpose                                                               |
-| ---------------------------------- | --------------------------------------------------------------------- |
-| `DEFAULT_ELECTRIC_AGENTS_URL`      | Default server URL (`"http://localhost:4437"`).                       |
-| `getElectricCliEnv(env?)`          | Reads `ELECTRIC_AGENTS_URL` and `ELECTRIC_AGENTS_IDENTITY`.           |
-| `createElectricCliHandlers()`      | Creates the default command handlers.                                 |
-| `createElectricProgram()`          | Creates the Commander program.                                        |
-| `resolveCommandPrefix(argv, env?)` | Resolves help text examples for direct or package-manager invocation. |
-| `run(argv?)`                       | Runs the CLI entrypoint.                                              |
+| Export                            | Purpose                                                                  |
+| --------------------------------- | ------------------------------------------------------------------------ |
+| `DEFAULT_ELECTRIC_AGENTS_URL`     | Default server URL (`"http://localhost:4437"`).                          |
+| `getElectricCliEnv(env?)`         | Reads `ELECTRIC_AGENTS_URL` and `ELECTRIC_AGENTS_IDENTITY`.              |
+| `createElectricCliHandlers()`     | Creates the default command handlers.                                    |
+| `createElectricProgram()`         | Creates the Commander program.                                           |
+| `resolveCommandPrefix(argv, env?)` | Resolves help text examples for direct or package-manager invocation.    |
+| `run(argv?)`                      | Runs the CLI entrypoint.                                                 |
 
 The installed binaries are `electric` and `electric-ax`. The package also includes `electric-dev` for development workflows.
 

package/docs/reference/entity-definition.md

@@ -1,6 +1,6 @@
 ---
 title: EntityDefinition
-titleTemplate: '... - Electric Agents'
+titleTemplate: "... - Electric Agents"
 description: >-
   Type reference for EntityDefinition: description, state, schemas, and handler function signature.
 outline: [2, 3]
@@ -28,15 +28,15 @@ interface EntityDefinition {
 
 ## Fields
 
-| Field            | Type                                                 | Required | Description                                                                                                                     |
-| ---------------- | ---------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------- |
-| `description`    | `string`                                             | No       | Human-readable description of the entity type. Used in type registration.                                                       |
-| `state`          | `Record<string, CollectionDefinition>`               | No       | Custom state collections exposed via `ctx.db.actions` (writes) and `ctx.db.collections` (reads).                                |
+| Field            | Type                                                 | Required | Description                                                                                                        |
+| ---------------- | ---------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------ |
+| `description`    | `string`                                             | No       | Human-readable description of the entity type. Used in type registration.                                          |
+| `state`          | `Record<string, CollectionDefinition>`               | No       | Custom state collections exposed via `ctx.db.actions` (writes) and `ctx.db.collections` (reads).                   |
 | `actions`        | `(collections) => Record<string, (...args) => void>` | No       | Factory for custom non-CRUD actions. Receives TanStack DB collections, returns named action functions exposed on `ctx.actions`. |
-| `creationSchema` | `StandardJSONSchemaV1`                               | No       | JSON Schema for spawn arguments validation.                                                                                     |
-| `inboxSchemas`   | `Record<string, StandardJSONSchemaV1>`               | No       | JSON Schemas for inbound message types, keyed by message type.                                                                  |
-| `outputSchemas`  | `Record<string, StandardJSONSchemaV1>`               | No       | JSON Schemas for output event types. Defaults are provided by the runtime.                                                      |
-| `handler`        | `(ctx, wake) => void \| Promise<void>`               | Yes      | The function invoked on each wake. Receives [`HandlerContext`](./handler-context) and [`WakeEvent`](./wake-event).              |
+| `creationSchema` | `StandardJSONSchemaV1`                               | No       | JSON Schema for spawn arguments validation.                                                                        |
+| `inboxSchemas`   | `Record<string, StandardJSONSchemaV1>`               | No       | JSON Schemas for inbound message types, keyed by message type.                                                     |
+| `outputSchemas`  | `Record<string, StandardJSONSchemaV1>`               | No       | JSON Schemas for output event types. Defaults are provided by the runtime.                                         |
+| `handler`        | `(ctx, wake) => void \| Promise<void>`               | Yes      | The function invoked on each wake. Receives [`HandlerContext`](./handler-context) and [`WakeEvent`](./wake-event). |
 
 ## CollectionDefinition
 

package/docs/reference/entity-handle.md

@@ -1,6 +1,6 @@
 ---
 title: EntityHandle
-titleTemplate: '... - Electric Agents'
+titleTemplate: "... - Electric Agents"
 description: >-
   API reference for EntityHandle returned by spawn and observe: streams, status, text retrieval, and messaging.
 outline: [2, 3]
@@ -49,7 +49,7 @@ interface ChildStatusEntry {
   key: string
   entity_url: string
   entity_type: string
-  status: 'spawning' | 'running' | 'idle' | 'stopped'
+  status: "spawning" | "running" | "idle" | "stopped"
 }
 ```
 

package/docs/reference/entity-registry.md

@@ -1,6 +1,6 @@
 ---
 title: EntityRegistry
-titleTemplate: '... - Electric Agents'
+titleTemplate: "... - Electric Agents"
 description: >-
   API reference for EntityRegistry: define, get, list, and clear entity type registrations.
 outline: [2, 3]

package/docs/reference/handler-context.md

@@ -1,6 +1,6 @@
 ---
 title: HandlerContext
-titleTemplate: '... - Electric Agents'
+titleTemplate: "... - Electric Agents"
 description: >-
   API reference for HandlerContext: state, coordination, agent configuration, and execution control.
 outline: [2, 3]
@@ -44,11 +44,11 @@ interface HandlerContext<TState extends StateProxy = StateProxy> {
     }
   ): Promise<EntityHandle>
   observe(
-    source: ObservationSource & { sourceType: 'entity' },
+    source: ObservationSource & { sourceType: "entity" },
     opts?: { wake?: Wake }
   ): Promise<EntityHandle>
   observe(
-    source: ObservationSource & { sourceType: 'db' },
+    source: ObservationSource & { sourceType: "db" },
     opts?: { wake?: Wake }
   ): Promise<SharedStateHandle & ObservationHandle>
   observe(
@@ -64,6 +64,7 @@ interface HandlerContext<TState extends StateProxy = StateProxy> {
     payload: unknown,
     opts?: { type?: string; afterMs?: number }
   ): void
+  recordRun(): RunHandle
   setTag(key: string, value: string): Promise<void>
   removeTag(key: string): Promise<void>
   sleep(): void
@@ -74,27 +75,27 @@ interface HandlerContext<TState extends StateProxy = StateProxy> {
 
 ## Properties
 
-| Property        | Type                                              | Description                                                                                                                                   |
-| --------------- | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
-| `firstWake`     | `boolean`                                         | `true` on the entity's first-ever handler invocation.                                                                                         |
-| `tags`          | `Readonly<EntityTags>`                            | Entity tags — key/value metadata associated with this entity.                                                                                 |
-| `entityUrl`     | `string`                                          | URL path of this entity (e.g. `"/chat/my-convo"`).                                                                                            |
-| `entityType`    | `string`                                          | Registered type name (e.g. `"chat"`).                                                                                                         |
-| `args`          | `Readonly<Record<string, unknown>>`               | Spawn arguments passed when the entity was created.                                                                                           |
-| `db`            | `EntityStreamDBWithActions`                       | The entity's TanStack DB instance with registered actions.                                                                                    |
-| `state`         | `TState`                                          | Proxy object keyed by collection name. Each property is a [`StateCollectionProxy`](./state-collection-proxy).                                 |
-| `events`        | `Array<ChangeEvent>`                              | Change events that triggered this wake.                                                                                                       |
-| `actions`       | `Record<string, (...args: unknown[]) => unknown>` | Custom non-CRUD actions from the entity definition's `actions` factory. Auto-generated CRUD actions live on `ctx.db.actions` and `ctx.state`. |
-| `electricTools` | `AgentTool[]`                                     | Host-provided runtime-level tools to spread into agent config when needed. May be empty.                                                      |
+| Property     | Type                                              | Description                                                                                                   |
+| ------------ | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `firstWake`  | `boolean`                                         | `true` during the initial setup pass while the entity has no persisted manifest entries. Use state checks for one-time plain state initialization. |
+| `tags`       | `Readonly<EntityTags>`                            | Entity tags — key/value metadata associated with this entity.                                                 |
+| `entityUrl`  | `string`                                          | URL path of this entity (e.g. `"/chat/my-convo"`).                                                            |
+| `entityType` | `string`                                          | Registered type name (e.g. `"chat"`).                                                                         |
+| `args`       | `Readonly<Record<string, unknown>>`               | Spawn arguments passed when the entity was created.                                                           |
+| `db`         | `EntityStreamDBWithActions`                       | The entity's TanStack DB instance with registered actions.                                                    |
+| `state`      | `TState`                                          | Proxy object keyed by collection name. Each property is a [`StateCollectionProxy`](./state-collection-proxy). |
+| `events`     | `Array<ChangeEvent>`                              | Change events that triggered this wake.                                                                       |
+| `actions`    | `Record<string, (...args: unknown[]) => unknown>` | Custom non-CRUD actions from the entity definition's `actions` factory. Auto-generated CRUD actions live on `ctx.db.actions` and `ctx.state`. |
+| `electricTools` | `AgentTool[]`                                     | Host-provided runtime-level tools to spread into agent config when needed. May be empty.                     |
 
 ## Methods
 
 | Method                            | Return Type                                                       | Description                                                                                                                                                                                                                                |
 | --------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `useAgent(config)`                | `AgentHandle`                                                     | Configure the LLM agent. Must be called before `agent.run()`. See [`AgentConfig`](./agent-config).                                                                                                                                         |
-| `useContext(config)`              | `void`                                                            | Declare context sources with token budgets and cache tiers for the agent's context window. See [Context composition](/docs/agents/usage/context-composition).                                                                              |
-| `timelineMessages(opts?)`         | `Array<TimestampedMessage>`                                       | Project the entity timeline into an ordered array of LLM messages. Typically used as the `content` function of a volatile source. See [Context composition](/docs/agents/usage/context-composition#timelinemessages).                      |
-| `insertContext(id, entry)`        | `void`                                                            | Insert a durable context entry. Persists across wakes. Inserting with an existing `id` replaces the previous entry. See [Context entries](/docs/agents/usage/context-composition#context-entries).                                         |
+| `useContext(config)`              | `void`                                                            | Declare context sources with token budgets and cache tiers for the agent's context window. See [Context composition](/docs/agents/usage/context-composition).                                                                                     |
+| `timelineMessages(opts?)`         | `Array<TimestampedMessage>`                                       | Project the entity timeline into an ordered array of LLM messages. Typically used as the `content` function of a volatile source. See [Context composition](/docs/agents/usage/context-composition#timelinemessages).                             |
+| `insertContext(id, entry)`        | `void`                                                            | Insert a durable context entry. Persists across wakes. Inserting with an existing `id` replaces the previous entry. See [Context entries](/docs/agents/usage/context-composition#context-entries).                                                |
 | `removeContext(id)`               | `void`                                                            | Remove a context entry by id.                                                                                                                                                                                                              |
 | `getContext(id)`                  | `ContextEntry \| undefined`                                       | Get a context entry by id, or `undefined` if not found.                                                                                                                                                                                    |
 | `listContext()`                   | `Array<ContextEntry>`                                             | List all context entries.                                                                                                                                                                                                                  |
@@ -103,6 +104,21 @@ interface HandlerContext<TState extends StateProxy = StateProxy> {
 | `observe(source, opts?)`          | `Promise<EntityHandle \| SharedStateHandle \| ObservationHandle>` | Observe a source. Return type depends on source type: `EntityHandle` for entities, `SharedStateHandle & ObservationHandle` for db, `ObservationHandle` otherwise. Use `entity()`, `cron()`, `entities()`, `db()` helpers to build sources. |
 | `mkdb(id, schema)`                | `SharedStateHandle<T>`                                            | Create a new shared state stream. See [`SharedStateHandle`](./shared-state-handle).                                                                                                                                                        |
 | `send(entityUrl, payload, opts?)` | `void`                                                            | Send a message to another entity. `opts` accepts `type` and `afterMs` (delay in milliseconds).                                                                                                                                             |
+| `recordRun()`                     | `RunHandle`                                                       | Record a non-LLM run in the built-in `runs` collection, so observers using `wake: "runFinished"` are notified when external work completes.                                                                                               |
 | `setTag(key, value)`              | `Promise<void>`                                                   | Set a tag on this entity.                                                                                                                                                                                                                  |
 | `removeTag(key)`                  | `Promise<void>`                                                   | Remove a tag from this entity.                                                                                                                                                                                                             |
 | `sleep()`                         | `void`                                                            | End the handler without running an agent. The entity remains idle until the next wake.                                                                                                                                                     |
+
+## RunHandle
+
+`recordRun()` is for handlers that perform work outside `ctx.agent.run()` but still want to expose run lifecycle events.
+
+```ts
+interface RunHandle {
+  readonly key: string
+  end(opts: { status: "completed" | "failed"; finishReason?: string }): void
+  attachResponse(text: string): void
+}
+```
+
+`attachResponse()` appends text deltas linked to the run, which can be included in `runFinished` wake payloads.

package/docs/reference/mcp-registry.md

@@ -0,0 +1,189 @@
+---
+title: McpRegistry
+titleTemplate: "... - Electric Agents"
+description: >-
+  API reference for the MCP Registry — addServer, applyConfig,
+  subscribe, reauthorize, and the lifecycle of an MCP server entry
+  inside the runtime.
+outline: [2, 3]
+---
+
+# McpRegistry
+
+The MCP registry owns the live set of [Model Context Protocol](https://modelcontextprotocol.io) servers a runtime is connected to. It manages stdio subprocesses and HTTP clients, drives the OAuth state machine, and emits push-based snapshots so embedders can render UI without polling.
+
+**Source:** `@electric-ax/agents-mcp` (re-exported as `McpRegistry` from `@electric-ax/agents`)
+
+`BuiltinAgentsServer.mcpRegistry` exposes the instance that the embedded runtime owns; the [usage guide](/docs/agents/usage/mcp-servers) walks through registering servers from agent-host code.
+
+```ts
+interface Registry {
+  addServer(cfg: McpServerConfig): Promise<AddServerResult>
+  applyConfig(cfg: McpConfig): Promise<AddServerResult[]>
+  removeServer(name: string): Promise<void>
+  list(): ReadonlyArray<ListedEntry>
+  get(name: string): Entry | undefined
+  finishAuth(server: string, code: string, state?: string): Promise<AddServerResult>
+  reauthorize(name: string): Promise<void>
+  disable(name: string): Promise<void>
+  enable(name: string): Promise<AddServerResult>
+  subscribe(handler: RegistrySubscriber): () => void
+}
+```
+
+## Methods
+
+| Method                      | Description                                                                                                              |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `addServer(cfg)`            | Register or reconfigure a single server. Idempotent on unchanged `(name, url, transport, authMode, scopes, command, args)`. |
+| `applyConfig(cfg)`          | Replace the full set of registered servers. Adds new ones, reconfigures changed ones, and removes anything not in `cfg`. |
+| `removeServer(name)`        | Tear down a single server: close the transport, drop tokens from the in-memory cache, remove the entry.                  |
+| `list()`                    | Returns the current snapshot as a plain array — same shape as the `servers` field of [`RegistrySnapshot`](#registrysnapshot). |
+| `get(name)`                 | Internal lookup of a single entry, with the live `transport` handle and the resolved `provider`. Used by IPC handlers.    |
+| `finishAuth(name, code, state?)` | Complete the OAuth authorization-code flow for an `authenticating` server. Called by the embedder after intercepting the redirect URI. |
+| `reauthorize(name)`         | Force a fresh OAuth flow without removing the entry. Closes the transport, drops cached tokens (hooks remain registered), and rebuilds in place. |
+| `disable(name)`             | Pause a server. Closes the transport but keeps the entry; tokens stay in the cache.                                       |
+| `enable(name)`              | Re-add a previously-disabled server using its last-known config.                                                          |
+| `subscribe(handler)`        | Push-based view of registry state. The handler fires synchronously with a sentinel snapshot, then on every mutation. Returns an unsubscribe function. |
+
+## `addServer` vs `applyConfig`
+
+Both feed the same internal pipeline; pick by what you have:
+
+- **`addServer(cfg)`** — register one server. Use when you're adding an entry in response to a user action, a per-session tool, or a one-off integration.
+- **`applyConfig({ servers })`** — replace the full set. Anything in the registry that isn't in `cfg.servers` is removed; existing entries with unchanged config are left alone (no transport churn). This is what the file-based loaders for `mcp.json` and the desktop `settings.json` compile down to.
+
+Idempotency is the load-bearing property: editors save spuriously, file watchers fire double events on macOS, and most apps re-apply the same baseline on every restart. Calling `applyConfig` with the same shape twice does nothing the second time, so it's safe to wire to noisy upstreams.
+
+## `AddServerResult`
+
+`addServer` and `finishAuth` return a discriminated union so the caller can react without inspecting the registry afterwards:
+
+```ts
+type AddServerResult =
+  | { state: "ready"; id: string; toolCount: number }
+  | { state: "authenticating"; id: string; authUrl: string }
+  | { state: "error"; id: string; error: McpToolError }
+```
+
+| State            | Meaning                                                                                                                            |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `ready`          | Connected and tools listed; calls available at the next agent wake.                                                                |
+| `authenticating` | OAuth required. `authUrl` is the URL to send the user to. The desktop's `openAuthorizeUrl` hook opens it in a sandboxed BrowserWindow automatically. |
+| `error`          | Connect, transport, or auth-config failure. `error.kind` and `error.message` describe what went wrong.                              |
+
+`applyConfig` returns one `AddServerResult` per server in the supplied config (in the same order).
+
+## Lifecycle of an entry
+
+Every entry transitions through one of five statuses, surfaced on the snapshot. The states that matter to UI:
+
+| Status           | Meaning                                                                                          |
+| ---------------- | ------------------------------------------------------------------------------------------------ |
+| `connecting`     | Transport is being built (DCR, HTTPS discovery) or reconnecting.                                 |
+| `authenticating` | OAuth flow needed; `authUrl` is set, browser window is open.                                      |
+| `ready`          | Transport connected; tools listed and callable.                                                   |
+| `error`          | Transport or auth-config failure. The entry stays in `list()` so the UI can surface the failure. |
+| `disabled`       | Operator paused the server via `disable(name)`. Recoverable through `enable(name)`.              |
+
+Transitions are atomic with respect to subscribers: every state change fires a single snapshot in which the entry shows its new status. `reauthorize` mutates entries in place — the row never disappears from `list()`, even mid-rebuild, so renderers don't see a flicker.
+
+## `subscribe(handler)` and `RegistrySnapshot`
+
+```ts
+type RegistrySubscriber = (snapshot: RegistrySnapshot) => void
+
+interface RegistrySnapshot {
+  seq: number
+  servers: ReadonlyArray<ListedEntry>
+}
+```
+
+Subscribing is the primary way to drive a UI off the registry. The first invocation is synchronous and carries `seq: 0` as a sentinel — embedders treat it as the bootstrap snapshot, not part of the event stream. After that, every mutation increments `seq` (1, 2, 3, …) and broadcasts the full snapshot. A late subscriber still sees `seq: 0` on its first delivery; emitted events continue from the registry's current counter.
+
+Handlers must not throw. The registry catches exceptions per subscriber so a misbehaving consumer can't break the others, but the catch is a safety net, not a feature — log and swallow inside your handler.
+
+```ts
+const off = registry.subscribe((snap) => {
+  if (snap.seq === 0) {
+    // bootstrap — render the initial list
+  } else {
+    // diff against the previous snapshot, or just re-render
+  }
+})
+// ...
+off()
+```
+
+## `ListedEntry`
+
+The shape of each `servers[]` entry inside a snapshot:
+
+```ts
+interface ListedEntry {
+  name: string
+  status: McpServerStatus
+  toolCount: number
+  transport?: "http" | "stdio"
+  authMode?: "none" | "apiKey" | "clientCredentials" | "authorizationCode"
+  authUrl?: string
+  error?: McpToolError
+  tools: Array<{ name: string; description?: string; inputSchema: unknown }>
+  capabilities?: unknown
+}
+```
+
+| Field          | Type                                              | Description                                                                                  |
+| -------------- | ------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| `name`         | `string`                                          | The server's stable identifier.                                                              |
+| `status`       | `McpServerStatus`                                 | Current lifecycle state — see the table above.                                               |
+| `toolCount`    | `number`                                          | Number of tools the server advertises. `0` until `status === "ready"`.                       |
+| `transport`    | `"http" \| "stdio"`                               | The transport variant in use.                                                                |
+| `authMode`     | `string`                                          | `none` / `apiKey` / `clientCredentials` / `authorizationCode`. UI badges + "show Authorize" check use this. |
+| `authUrl`      | `string`                                          | Set while `status === "authenticating"`. The URL to open for OAuth consent.                  |
+| `error`        | [`McpToolError`](#mcptoolerror)                   | Set while `status === "error"`.                                                              |
+| `tools`        | `Array<{ name; description?; inputSchema }>`      | Tool metadata as advertised by the server. Each becomes `mcp__<server>__<tool>` for the LLM. |
+| `capabilities` | `unknown`                                         | Server-declared MCP capabilities object (resources, prompts, etc.).                          |
+
+## `McpToolError`
+
+```ts
+interface McpToolError {
+  kind: McpToolErrorKind
+  message: string
+  details?: unknown
+}
+
+type McpToolErrorKind =
+  | "auth_unavailable"
+  | "transport_error"
+  | "timeout"
+  | "server_error"
+  | "tool_not_found"
+```
+
+The same shape surfaces on entry-level `error` (when `addServer` fails to connect) and on individual tool calls. See the [usage guide's failure modes table](/docs/agents/usage/mcp-servers#failure-modes).
+
+## `RegistryOpts`
+
+`BuiltinAgentsServer` constructs the registry on your behalf. You only see this shape if you instantiate `agents-mcp` directly (e.g. from a custom embedder):
+
+```ts
+interface RegistryOpts {
+  publicUrl?: string
+  openAuthorizeUrl?: (url: string, server: string) => void
+}
+
+function createRegistry(opts: RegistryOpts): Registry
+```
+
+| Field              | Description                                                                                                                          |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `publicUrl`        | Base URL used to construct the OAuth `redirect_uri` (full URI is `<publicUrl>/oauth/callback/<server-name>`). MUST be stable across restarts — DCR registers it with the auth server and persists it in the keychain, so a value that drifts forces re-authorization on every launch. Embedders that listen on an ephemeral port should pass a fixed loopback literal (the desktop uses `http://127.0.0.1:53117`); nothing actually listens at the URL — the embedder's BrowserWindow intercepts the redirect by prefix. |
+| `openAuthorizeUrl` | Hook invoked when an `authorizationCode` server first needs 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. |
+
+## See also
+
+- [MCP servers usage guide](/docs/agents/usage/mcp-servers) — the practical walkthrough of registering servers, OAuth, persistence, and the per-agent allowlist.
+- [`McpServerConfig`](/docs/agents/reference/mcp-server-config) — schema for the `cfg` argument to `addServer` / `applyConfig`.
+- [`BuiltinAgentsServer`](/docs/agents/usage/embedded-builtins) — host options that affect MCP, including `extraMcpServers` and `openAuthorizeUrl`.