@electric-ax/agents 0.2.3 → 0.3.0

package/docs/usage/defining-tools.md

@@ -1,6 +1,6 @@
 ---
 title: Defining tools
-titleTemplate: '... - Electric Agents'
+titleTemplate: "... - Electric Agents"
 description: >-
   Create stateless, stateful, and handler-scoped tools for the LLM agent loop.
 outline: [2, 3]
@@ -33,7 +33,7 @@ The return type:
 
 ```ts
 interface AgentToolResult<T = any> {
-  content: Array<{ type: 'text'; text: string }>
+  content: Array<{ type: "text"; text: string }>
   details: T
 }
 ```
@@ -43,11 +43,11 @@ interface AgentToolResult<T = any> {
 Defined using [TypeBox](https://github.com/sinclairzx81/typebox) (`@sinclair/typebox`). The schema is used for LLM function calling and argument validation.
 
 ```ts
-import { Type } from '@sinclair/typebox'
+import { Type } from "@sinclair/typebox"
 
 parameters: Type.Object({
-  expression: Type.String({ description: 'Math expression to evaluate' }),
-  precision: Type.Optional(Type.Number({ description: 'Decimal places' })),
+  expression: Type.String({ description: "Math expression to evaluate" }),
+  precision: Type.Optional(Type.Number({ description: "Decimal places" })),
 })
 ```
 
@@ -56,21 +56,21 @@ parameters: Type.Object({
 Pure functions with no side effects beyond what they compute. Define directly as an `AgentTool` object.
 
 ```ts
-import { Type } from '@sinclair/typebox'
-import type { AgentTool } from '@electric-ax/agents-runtime'
+import { Type } from "@sinclair/typebox"
+import type { AgentTool } from "@electric-ax/agents-runtime"
 
 const calculatorTool: AgentTool = {
-  name: 'calculator',
-  label: 'Calculator',
-  description: 'Evaluate mathematical expressions.',
+  name: "calculator",
+  label: "Calculator",
+  description: "Evaluate mathematical expressions.",
   parameters: Type.Object({
-    expression: Type.String({ description: 'The expression to evaluate' }),
+    expression: Type.String({ description: "The expression to evaluate" }),
   }),
   execute: async (_toolCallId, params) => {
     const { expression } = params as { expression: string }
     const result = evaluate(expression)
     return {
-      content: [{ type: 'text', text: String(result) }],
+      content: [{ type: "text", text: String(result) }],
       details: {},
     }
   },
@@ -82,20 +82,20 @@ const calculatorTool: AgentTool = {
 Use a factory function that receives the `HandlerContext`. The state persists across wakes -- it is backed by the entity's durable stream. Reads go through `ctx.db.collections` and writes go through `ctx.db.actions`.
 
 ```ts
-import { Type } from '@sinclair/typebox'
-import type { AgentTool, HandlerContext } from '@electric-ax/agents-runtime'
+import { Type } from "@sinclair/typebox"
+import type { AgentTool, HandlerContext } from "@electric-ax/agents-runtime"
 
 function createMemoryStoreTool(ctx: HandlerContext): AgentTool {
   return {
-    name: 'memory_store',
-    label: 'Memory Store',
-    description: 'Persistent key-value store.',
+    name: "memory_store",
+    label: "Memory Store",
+    description: "Persistent key-value store.",
     parameters: Type.Object({
       operation: Type.Union([
-        Type.Literal('get'),
-        Type.Literal('set'),
-        Type.Literal('delete'),
-        Type.Literal('list'),
+        Type.Literal("get"),
+        Type.Literal("set"),
+        Type.Literal("delete"),
+        Type.Literal("list"),
       ]),
       key: Type.Optional(Type.String()),
       value: Type.Optional(Type.String()),
@@ -106,7 +106,7 @@ function createMemoryStoreTool(ctx: HandlerContext): AgentTool {
         key?: string
         value?: string
       }
-      if (operation === 'set') {
+      if (operation === "set") {
         const existing = ctx.db.collections.kv?.get(key!)
         if (existing) {
           ctx.db.actions.kv_update({
@@ -119,27 +119,27 @@ function createMemoryStoreTool(ctx: HandlerContext): AgentTool {
           ctx.db.actions.kv_insert({ row: { key: key!, value: value! } })
         }
         return {
-          content: [{ type: 'text', text: `Stored "${key}"` }],
+          content: [{ type: "text", text: `Stored "${key}"` }],
           details: {},
         }
       }
-      if (operation === 'get') {
+      if (operation === "get") {
         const entry = ctx.db.collections.kv?.get(key!)
         const text = entry ? entry.value : `No value found for "${key}"`
-        return { content: [{ type: 'text', text }], details: {} }
+        return { content: [{ type: "text", text }], details: {} }
       }
-      if (operation === 'delete') {
+      if (operation === "delete") {
         ctx.db.actions.kv_delete({ key: key! })
         return {
-          content: [{ type: 'text', text: `Deleted "${key}"` }],
+          content: [{ type: "text", text: `Deleted "${key}"` }],
           details: {},
         }
       }
       // list
       const entries = ctx.db.collections.kv?.toArray ?? []
-      const text = entries.map((e) => `${e.key}: ${e.value}`).join('\n')
+      const text = entries.map((e) => `${e.key}: ${e.value}`).join("\n")
       return {
-        content: [{ type: 'text', text: text || '(empty)' }],
+        content: [{ type: "text", text: text || "(empty)" }],
         details: {},
       }
     },
@@ -162,18 +162,18 @@ The entity state API:
 Use a factory that receives the `HandlerContext`. These tools can spawn entities, observe streams, send messages, and use any other `ctx` primitive.
 
 ```ts
-import { Type } from '@sinclair/typebox'
-import type { AgentTool, HandlerContext } from '@electric-ax/agents-runtime'
+import { Type } from "@sinclair/typebox"
+import type { AgentTool, HandlerContext } from "@electric-ax/agents-runtime"
 
 function createDispatchTool(ctx: HandlerContext): AgentTool {
   return {
-    name: 'dispatch',
-    label: 'Dispatch',
-    description: 'Spawn a child agent and wait for its response.',
+    name: "dispatch",
+    label: "Dispatch",
+    description: "Spawn a child agent and wait for its response.",
     parameters: Type.Object({
-      type: Type.String({ description: 'Entity type to spawn' }),
-      systemPrompt: Type.String({ description: 'System prompt for the child' }),
-      task: Type.String({ description: 'Task to send to the child' }),
+      type: Type.String({ description: "Entity type to spawn" }),
+      systemPrompt: Type.String({ description: "System prompt for the child" }),
+      task: Type.String({ description: "Task to send to the child" }),
     }),
     execute: async (_, params) => {
       const { type, systemPrompt, task } = params as {
@@ -187,12 +187,12 @@ function createDispatchTool(ctx: HandlerContext): AgentTool {
         { systemPrompt },
         {
           initialMessage: task,
-          wake: 'runFinished',
+          wake: "runFinished",
         }
       )
-      const text = (await child.text()).join('\n\n')
+      const text = (await child.text()).join("\n\n")
       return {
-        content: [{ type: 'text', text }],
+        content: [{ type: "text", text }],
         details: {},
       }
     },
@@ -207,18 +207,18 @@ function createDispatchTool(ctx: HandlerContext): AgentTool {
 Tools are constructed in the handler and passed to `useAgent`. Include `ctx.electricTools` when your runtime host provides runtime-level tools that the LLM should be able to call:
 
 ```ts
-registry.define('assistant', {
-  description: 'An assistant with memory and delegation',
+registry.define("assistant", {
+  description: "An assistant with memory and delegation",
   state: {
-    kv: { primaryKey: 'key' },
+    kv: { primaryKey: "key" },
   },
   async handler(ctx) {
     const memoryTool = createMemoryStoreTool(ctx)
     const dispatchTool = createDispatchTool(ctx)
 
     ctx.useAgent({
-      systemPrompt: 'You are a helpful assistant with persistent memory.',
-      model: 'claude-sonnet-4-5-20250929',
+      systemPrompt: "You are a helpful assistant with persistent memory.",
+      model: "claude-sonnet-4-5-20250929",
       tools: [...ctx.electricTools, memoryTool, dispatchTool, calculatorTool],
     })
     await ctx.agent.run()

package/docs/usage/embedded-builtins.md

@@ -1,6 +1,6 @@
 ---
 title: Embedded built-ins
-titleTemplate: '... - Electric Agents'
+titleTemplate: "... - Electric Agents"
 description: >-
   Embed the built-in Horton and worker runtime in your own process using
   @electric-ax/agents, BuiltinAgentsServer, or the entrypoint helpers.
@@ -16,10 +16,10 @@ The CLI commands `electric agents start-builtin` and `electric agents quickstart
 `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'
+import { BuiltinAgentsServer } from "@electric-ax/agents"
 
 const server = new BuiltinAgentsServer({
-  agentServerUrl: 'http://localhost:4437',
+  agentServerUrl: "http://localhost:4437",
   port: 4448,
   workingDirectory: process.cwd(),
 })
@@ -36,9 +36,9 @@ await server.stop()
 ### Options
 
 ```ts
-import type { RuntimeRouterConfig } from '@electric-ax/agents-runtime'
+import type { RuntimeRouterConfig } from "@electric-ax/agents-runtime"
 
-type CreateElectricTools = RuntimeRouterConfig['createElectricTools']
+type CreateElectricTools = RuntimeRouterConfig["createElectricTools"]
 
 interface BuiltinAgentsServerOptions {
   agentServerUrl: string
@@ -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 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.      |
+| 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.
 
@@ -73,16 +84,16 @@ Use `createBuiltinAgentHandler()` when you already have an HTTP server and only
 import {
   createBuiltinAgentHandler,
   registerBuiltinAgentTypes,
-} from '@electric-ax/agents'
+} from "@electric-ax/agents"
 
 const bootstrap = await createBuiltinAgentHandler({
-  agentServerUrl: 'http://localhost:4437',
-  serveEndpoint: 'https://example.com/_electric/builtin-agent-handler',
+  agentServerUrl: "http://localhost:4437",
+  serveEndpoint: "https://example.com/_electric/builtin-agent-handler",
   workingDirectory: process.cwd(),
 })
 
 if (!bootstrap) {
-  throw new Error('ANTHROPIC_API_KEY is required for built-in agents')
+  throw new Error("ANTHROPIC_API_KEY is required for built-in agents")
 }
 
 await registerBuiltinAgentTypes(bootstrap)
@@ -108,27 +119,27 @@ interface AgentHandlerResult {
 Both `BuiltinAgentsServer` and `createBuiltinAgentHandler()` accept `createElectricTools`. The factory receives the same context shape as `RuntimeRouterConfig.createElectricTools` and can add host-specific tools to Horton.
 
 ```ts
-import { Type } from '@sinclair/typebox'
+import { Type } from "@sinclair/typebox"
 
 const server = new BuiltinAgentsServer({
-  agentServerUrl: 'http://localhost:4437',
+  agentServerUrl: "http://localhost:4437",
   port: 4448,
   createElectricTools: ({ entityUrl, upsertCronSchedule }) => [
     {
-      name: 'schedule_daily_summary',
-      label: 'Schedule daily summary',
-      description: 'Schedule a daily summary wake for this entity.',
+      name: "schedule_daily_summary",
+      label: "Schedule daily summary",
+      description: "Schedule a daily summary wake for this entity.",
       parameters: Type.Object({
         hour: Type.Number(),
       }),
       execute: async (_id, params) => {
         const { hour } = params as { hour: number }
         await upsertCronSchedule({
-          id: 'daily-summary',
+          id: "daily-summary",
           expression: `0 ${hour} * * *`,
           payload: `Run daily summary for ${entityUrl}`,
         })
-        return { content: [{ type: 'text', text: 'Scheduled.' }], details: {} }
+        return { content: [{ type: "text", text: "Scheduled." }], details: {} }
       },
     },
   ],
@@ -143,7 +154,7 @@ const server = new BuiltinAgentsServer({
 import {
   resolveBuiltinAgentsEntrypointOptions,
   runBuiltinAgentsEntrypoint,
-} from '@electric-ax/agents'
+} from "@electric-ax/agents"
 
 const options = resolveBuiltinAgentsEntrypointOptions(process.env)
 const { server, url } = await runBuiltinAgentsEntrypoint()
@@ -154,27 +165,27 @@ await server.stop()
 
 Environment variables:
 
-| Variable                            | Description                                      |
-| ----------------------------------- | ------------------------------------------------ |
-| `ELECTRIC_AGENTS_SERVER_URL`        | Required coordinator server URL.                 |
-| `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.                |
+| Variable                         | Description                                           |
+| -------------------------------- | ----------------------------------------------------- |
+| `ELECTRIC_AGENTS_SERVER_URL`     | Required coordinator server URL.                      |
+| `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. |
 
 ## Built-in Agent APIs
 
 The built-in agent exports are also available if you want to compose your own runtime:
 
-| Export                      | Purpose                                               |
-| --------------------------- | ----------------------------------------------------- |
-| `registerHorton()`          | Register the `horton` type on an `EntityRegistry`.    |
-| `registerWorker()`          | Register the `worker` type on an `EntityRegistry`.    |
-| `HORTON_MODEL`              | Default model id used by Horton and worker.           |
+| Export                    | Purpose                                             |
+| ------------------------- | --------------------------------------------------- |
+| `registerHorton()`        | Register the `horton` type on an `EntityRegistry`.  |
+| `registerWorker()`        | Register the `worker` 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.  |
-| `createSpawnWorkerTool()`   | Create the `spawn_worker` tool for another agent.     |
-| `WORKER_TOOL_NAMES`         | Valid primitive tool names for workers.               |
-| `createHortonDocsSupport()` | Create Horton's docs knowledge-base support.          |
+| `createHortonTools()`     | Create Horton's base shell/file/search/worker tools. |
+| `createSpawnWorkerTool()` | Create the `spawn_worker` tool for another agent.   |
+| `WORKER_TOOL_NAMES`       | Valid primitive tool names for workers.             |
+| `createHortonDocsSupport()` | Create Horton's docs knowledge-base support.       |
 
 For the behavior of `horton` and `worker`, see [Horton](../entities/agents/horton) and [Worker](../entities/agents/worker).

package/docs/usage/managing-state.md

@@ -1,6 +1,6 @@
 ---
 title: Managing state
-titleTemplate: '... - Electric Agents'
+titleTemplate: "... - Electric Agents"
 description: >-
   Declare and manage persistent entity state using custom collections with typed CRUD operations.
 outline: [2, 3]
@@ -15,16 +15,16 @@ Entities can declare custom persistent collections. The convenience API is `ctx.
 Define collections in the `state` field of the entity definition:
 
 ```ts
-registry.define('my-entity', {
+registry.define("my-entity", {
   state: {
-    status: { primaryKey: 'key' },
+    status: { primaryKey: "key" },
     items: {
       schema: z.object({
         key: z.string(),
         name: z.string(),
         count: z.number(),
       }),
-      primaryKey: 'key',
+      primaryKey: "key",
     },
   },
   async handler(ctx) {
@@ -59,33 +59,33 @@ Write helpers return a Transaction. Reads query the underlying TanStack DB colle
 
 ```ts
 // Convenience API
-ctx.state.items.insert({ key: 'item-1', name: 'Widget', count: 5 })
-const itemViaState = ctx.state.items.get('item-1')
+ctx.state.items.insert({ key: "item-1", name: "Widget", count: 5 })
+const itemViaState = ctx.state.items.get("item-1")
 const allViaState = ctx.state.items.toArray
-ctx.state.items.update('item-1', (draft) => {
+ctx.state.items.update("item-1", (draft) => {
   draft.count += 1
 })
-ctx.state.items.delete('item-1')
+ctx.state.items.delete("item-1")
 
 // Lower-level insert
 ctx.db.actions.items_insert({
-  row: { key: 'item-1', name: 'Widget', count: 5 },
+  row: { key: "item-1", name: "Widget", count: 5 },
 })
 
 // Lower-level read
-const item = ctx.db.collections.items?.get('item-1')
+const item = ctx.db.collections.items?.get("item-1")
 const all = ctx.db.collections.items?.toArray
 
 // Lower-level update (Immer-style draft)
 ctx.db.actions.items_update({
-  key: 'item-1',
+  key: "item-1",
   updater: (draft) => {
     draft.count += 1
   },
 })
 
 // Lower-level delete
-ctx.db.actions.items_delete({ key: 'item-1' })
+ctx.db.actions.items_delete({ key: "item-1" })
 ```
 
 ## Built-in collections