@electric-ax/agents 0.2.3 → 0.3.0

package/docs/reference/mcp-server-config.md

@@ -0,0 +1,226 @@
+---
+title: McpServerConfig
+titleTemplate: "... - Electric Agents"
+description: >-
+  Schema reference for MCP server entries — transports, auth modes, and
+  persistence callbacks accepted by Registry.addServer, applyConfig, and
+  the mcp.json / settings.json layers.
+outline: [2, 3]
+---
+
+# McpServerConfig
+
+Shape of a server entry in the MCP registry. Identical between declarative (`mcp.json`, desktop `settings.json`) and programmatic (`Registry.addServer`) creation paths.
+
+**Source:** `@electric-ax/agents` (re-exported from `@electric-ax/agents-mcp`)
+
+```ts
+type McpServerConfig = McpHttpServerConfig | McpStdioServerConfig
+```
+
+The variant is selected by the `transport` field.
+
+## McpHttpServerConfig
+
+Streamable HTTP transport per the current MCP spec.
+
+```ts
+interface McpHttpServerConfig {
+  name: string
+  transport: "http"
+  url: string
+  auth: McpAuthConfig
+  timeoutMs?: number
+}
+```
+
+| Field       | Type            | Required | Description                                                                  |
+| ----------- | --------------- | -------- | ---------------------------------------------------------------------------- |
+| `name`      | `string`        | Yes      | Stable identifier. Used as the keychain account, the IPC verb argument, and the `mcp__<name>__<tool>` tool prefix. |
+| `transport` | `"http"`        | Yes      | Discriminator selecting the HTTP variant.                                    |
+| `url`       | `string`        | Yes      | The MCP server's HTTPS endpoint. Streamable transport with SSE inside.       |
+| `auth`      | `McpAuthConfig` | Yes      | One of the auth modes below. Use `{ mode: "none" }` for unauthenticated servers. |
+| `timeoutMs` | `number`        | No       | Per-call timeout override. Default `30000` (30 seconds).                     |
+
+## McpStdioServerConfig
+
+Locally-spawned subprocess speaking the MCP stdio protocol.
+
+```ts
+interface McpStdioServerConfig {
+  name: string
+  transport: "stdio"
+  command: string
+  args?: string[]
+  env?: Record<string, string>
+  auth?: McpAuthConfig
+  timeoutMs?: number
+}
+```
+
+| Field       | Type                     | Required | Description                                                              |
+| ----------- | ------------------------ | -------- | ------------------------------------------------------------------------ |
+| `name`      | `string`                 | Yes      | Stable identifier (see HTTP variant).                                    |
+| `transport` | `"stdio"`                | Yes      | Discriminator selecting the stdio variant.                               |
+| `command`   | `string`                 | Yes      | Executable name or absolute path. Resolved against `PATH`.               |
+| `args`      | `string[]`               | No       | CLI arguments. `${workspaceRoot}` is the only built-in expansion.        |
+| `env`       | `Record<string, string>` | No       | Environment variables for the subprocess. Inherits the parent's `PATH`.  |
+| `auth`      | `McpAuthConfig`          | No       | Typically `{ mode: "none" }`. Defaults to `none` when omitted.           |
+| `timeoutMs` | `number`                 | No       | Per-call timeout override. Default `30000`.                              |
+
+The subprocess is spawned lazily on the first tool call, kept alive across calls, and restarted on crash. One process per server, multiplexed via JSON-RPC `id`.
+
+## McpAuthConfig
+
+Discriminated union covering the four supported credential modes.
+
+```ts
+type McpAuthConfig =
+  | { mode: "none" }
+  | ApiKeyAuth
+  | ClientCredentialsAuth
+  | AuthorizationCodeAuth
+```
+
+### `none`
+
+```ts
+{ mode: "none" }
+```
+
+No authentication. Required for stdio servers that don't need credentials; rare for HTTP servers.
+
+### `apiKey`
+
+```ts
+interface ApiKeyAuth {
+  mode: "apiKey"
+  key: string
+  headerName?: string  // default "Authorization"
+  valuePrefix?: string // e.g. "Bearer "
+}
+```
+
+| Field         | Type     | Required | Description                                                                  |
+| ------------- | -------- | -------- | ---------------------------------------------------------------------------- |
+| `key`         | `string` | Yes      | Raw secret. Inline at the call site (e.g. `process.env.X_API_KEY`).          |
+| `headerName`  | `string` | No       | HTTP header name. Defaults to `Authorization`.                               |
+| `valuePrefix` | `string` | No       | Prepended to the key. Use `"Bearer "` for bearer tokens; empty for raw keys. |
+
+### `clientCredentials`
+
+OAuth 2.1 client-credentials grant. Unattended; no user interaction.
+
+```ts
+interface ClientCredentialsAuth {
+  mode: "clientCredentials"
+  tokenUrl: string
+  clientId: string
+  clientSecret: string
+  scopes?: string[]
+  audience?: string
+  resource?: string
+}
+```
+
+| Field          | Type       | Required | Description                                                                 |
+| -------------- | ---------- | -------- | --------------------------------------------------------------------------- |
+| `tokenUrl`     | `string`   | Yes      | OAuth token endpoint.                                                       |
+| `clientId`     | `string`   | Yes      | Inline at the call site (e.g. `process.env.X_CLIENT_ID`).                   |
+| `clientSecret` | `string`   | Yes      | Inline at the call site (e.g. `process.env.X_CLIENT_SECRET`).               |
+| `scopes`       | `string[]` | No       | Requested OAuth scopes.                                                     |
+| `audience`     | `string`   | No       | Auth0/OIDC `audience` claim, when the auth server requires it.              |
+| `resource`     | `string`   | No       | RFC 8707 resource indicator.                                                |
+
+The runtime exchanges the credentials for a short-lived access token, retries the exchange on 401, and never surfaces user-facing errors during steady state.
+
+### `authorizationCode`
+
+OAuth 2.1 authorization-code grant with PKCE. Requires a one-time browser flow per user.
+
+```ts
+interface AuthorizationCodeAuth {
+  mode: "authorizationCode"
+  scopes?: string[]
+  resource?: string
+  redirectUri?: string
+  client?: OAuthClientInfo
+  tokens?: OAuthTokens
+  onTokensChanged?: (tokens: OAuthTokens) => void | Promise<void>
+  onClientRegistered?: (client: OAuthClientInfo) => void | Promise<void>
+  oauthProviderRef?: string
+}
+```
+
+| Field                | Type                                          | Required | Description                                                                                                                              |
+| -------------------- | --------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `scopes`             | `string[]`                                    | No       | Requested OAuth scopes.                                                                                                                  |
+| `resource`           | `string`                                      | No       | RFC 8707 resource indicator.                                                                                                             |
+| `redirectUri`        | `string`                                      | No       | Override the default `${publicUrl}/oauth/callback/<server>` sentinel. Most embedders don't need this.                                    |
+| `client`             | `OAuthClientInfo`                             | No       | Pre-registered OAuth client (`client_id`, optional `client_secret`). When present, RFC 7591 Dynamic Client Registration is skipped.       |
+| `tokens`             | `OAuthTokens`                                 | No       | Pre-existing tokens to seed the in-process cache. The OAuth flow is skipped on boot; refresh-token rotation still happens transparently. |
+| `onTokensChanged`    | `(tokens) => void \| Promise<void>`           | No       | Fires after initial auth and on every refresh. Wire to a persistence layer if tokens should survive process restarts.                    |
+| `onClientRegistered` | `(client) => void \| Promise<void>`           | No       | Fires once after RFC 7591 DCR completes. Pair with `client` on the next boot to skip DCR.                                                |
+| `oauthProviderRef`   | `string`                                      | No       | Reference into a per-process map of pre-built `OAuthClientProvider` instances. Escape hatch for mTLS, OIDC quirks, etc.                  |
+
+### `OAuthTokens`
+
+```ts
+interface OAuthTokens {
+  accessToken: string
+  refreshToken?: string
+  expiresAt?: number  // Unix seconds
+}
+```
+
+### `OAuthClientInfo`
+
+```ts
+interface OAuthClientInfo {
+  clientId: string
+  clientSecret?: string
+  // RFC 7591 metadata (issued_at, expires_at, redirect_uris, …)
+  // — preserved verbatim from the DCR response.
+  [key: string]: unknown
+}
+```
+
+## Validation
+
+`mcp.json` and programmatic configs are validated when first applied:
+
+- `transport` must be `"http"` or `"stdio"`.
+- `auth.mode` must be one of `none` / `apiKey` / `clientCredentials` / `authorizationCode`.
+- `mcp.json` rejects forbidden reference keys (`clientIdRef`, `clientSecretRef`, `valueRef`, …) — secrets must be passed inline at the call site, not declared as references.
+- Inline `${VAR}` placeholders in `mcp.json` are expanded against `process.env` before validation.
+
+Invalid entries surface as `error`-state entries in `Registry.list()` with a structured `McpToolError`. The rest of the registry continues to operate.
+
+## Persistence helpers
+
+Two opt-in helpers from `@electric-ax/agents-mcp` produce auth-config slices that satisfy the persistence callback contract:
+
+```ts
+import { keychainPersistence, filePersistence } from "@electric-ax/agents-mcp"
+
+const tokens = await keychainPersistence({ server: "honeycomb" })
+// → { tokens?, client?, onTokensChanged, onClientRegistered }
+
+await registry.addServer({
+  name: "honeycomb",
+  transport: "http",
+  url: "https://mcp.honeycomb.io/mcp",
+  auth: { mode: "authorizationCode", scopes: ["mcp:read"], ...tokens },
+})
+```
+
+| Helper                              | Backing store                                                         | Notes                                                                |
+| ----------------------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| `keychainPersistence({ server })`   | macOS `security`, Linux `secret-tool`. Throws on Windows.             | Service `electric-agents`, accounts `tokens:<server>` / `client:<server>`. |
+| `filePersistence({ path, server })` | Mode-`0600` JSON file. Refuses to read files with looser permissions. | Use for CI / containers without an OS keychain.                      |
+
+## See also
+
+- [MCP servers usage guide](/docs/agents/usage/mcp-servers) — programmatic, file-based, and desktop-settings paths end-to-end.
+- [`McpRegistry`](/docs/agents/reference/mcp-registry) — the API that consumes this config (`addServer` / `applyConfig` / lifecycle).
+- [`BuiltinAgentsServer`](/docs/agents/usage/embedded-builtins) — host options that affect MCP, including `extraMcpServers` and `openAuthorizeUrl`.

package/docs/reference/runtime-handler.md

@@ -1,6 +1,6 @@
 ---
 title: RuntimeHandler
-titleTemplate: '... - Electric Agents'
+titleTemplate: "... - Electric Agents"
 description: >-
   API reference for RuntimeHandler: webhook handling, type registration, and deployment configuration.
 outline: [2, 3]
@@ -28,16 +28,16 @@ interface RuntimeRouter {
 }
 ```
 
-| Method                              | Return Type                 | Description                                                                                                               |
-| ----------------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
-| `handleRequest(request)`            | `Promise<Response \| null>` | Route a fetch `Request`. Returns `null` if the request path does not match `webhookPath`.                                 |
-| `handleWebhookRequest(request)`     | `Promise<Response>`         | Handle a webhook request directly, without route matching.                                                                |
-| `dispatchWebhookWake(notification)` | `void`                      | Dispatch an already-parsed webhook notification. Runs the wake handler in the background.                                 |
-| `drainWakes()`                      | `Promise<void>`             | Wait for all in-flight wake handlers to settle. Throws if any wake errored.                                               |
-| `waitForSettled()`                  | `Promise<void>`             | Wait for all in-flight wake handlers to settle.                                                                           |
-| `abortWakes()`                      | `void`                      | Abort in-flight wakes so host shutdown can complete quickly.                                                              |
-| `debugState()`                      | `RuntimeDebugState`         | Return a runtime-local snapshot for tests and shutdown diagnostics.                                                       |
-| `typeNames`                         | `string[]`                  | Names of all registered entity types (read-only).                                                                         |
+| Method                              | Return Type                 | Description                                                                                             |
+| ----------------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `handleRequest(request)`            | `Promise<Response \| null>` | Route a fetch `Request`. Returns `null` if the request path does not match `webhookPath`.               |
+| `handleWebhookRequest(request)`     | `Promise<Response>`         | Handle a webhook request directly, without route matching.                                              |
+| `dispatchWebhookWake(notification)` | `void`                      | Dispatch an already-parsed webhook notification. Runs the wake handler in the background.               |
+| `drainWakes()`                      | `Promise<void>`             | Wait for all in-flight wake handlers to settle. Throws if any wake errored.                             |
+| `waitForSettled()`                  | `Promise<void>`             | Wait for all in-flight wake handlers to settle.                                                         |
+| `abortWakes()`                      | `void`                      | Abort in-flight wakes so host shutdown can complete quickly.                                            |
+| `debugState()`                      | `RuntimeDebugState`         | Return a runtime-local snapshot for tests and shutdown diagnostics.                                     |
+| `typeNames`                         | `string[]`                  | Names of all registered entity types (read-only).                                                       |
 | `registerTypes()`                   | `Promise<void>`             | Register all entity types with the Electric Agents runtime server. Uses upsert semantics — safe to call on every startup. |
 
 ## RuntimeHandler
@@ -89,6 +89,7 @@ interface RuntimeRouterConfig {
   baseUrl: string
   serveEndpoint?: string
   webhookPath?: string
+  handlerUrl?: string
   registry?: EntityRegistry
   subscriptionPathForType?: (typeName: string) => string
   idleTimeout?: number
@@ -122,15 +123,16 @@ interface RuntimeRouterConfig {
 }
 ```
 
-| Field                     | Type                                       | Default                                                | Description                                                                                                       |
-| ------------------------- | ------------------------------------------ | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
-| `baseUrl`                 | `string`                                   | -                                                      | Base URL of the Electric Agents runtime server (e.g. `"http://localhost:4437"`). Required.                        |
-| `serveEndpoint`           | `string`                                   | -                                                      | Full webhook callback URL exposed by your app. Used for type registration.                                        |
-| `webhookPath`             | `string`                                   | pathname from `serveEndpoint`, or `"/electric-agents"` | Path matched by `handleRequest()`.                                                                                |
-| `registry`                | `EntityRegistry`                           | default registry                                       | Entity registry for this handler. Falls back to the module-level default registry.                                |
-| `subscriptionPathForType` | `(typeName: string) => string`             | -                                                      | Override the webhook subscription path used per entity type registration.                                         |
-| `idleTimeout`             | `number`                                   | `20000`                                                | Idle timeout in milliseconds before closing a wake.                                                               |
-| `heartbeatInterval`       | `number`                                   | `30000`                                                | Heartbeat interval in milliseconds.                                                                               |
-| `createElectricTools`     | `(context) => AgentTool[] \| Promise<...>` | -                                                      | Optional tool factory invoked for each wake context before handler execution. Provides extra tools to the agent.  |
-| `onWakeError`             | `(error: Error) => boolean \| void`        | -                                                      | Observer for background wake failures. Return `true` to mark the error as handled so it is not rethrown on drain. |
-| `registrationConcurrency` | `number`                                   | `8`                                                    | Max number of concurrent entity-type registrations.                                                               |
+| Field                     | Type                                                          | Default                                      | Description                                                                                                       |
+| ------------------------- | ------------------------------------------------------------- | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `baseUrl`                 | `string`                                                      | -                                            | Base URL of the Electric Agents runtime server (e.g. `"http://localhost:4437"`). Required.                                          |
+| `serveEndpoint`           | `string`                                                      | -                                            | Full webhook callback URL exposed by your app. Used for type registration.                                        |
+| `webhookPath`             | `string`                                                      | pathname from `serveEndpoint` / `handlerUrl`, or `"/electric-agents"` | Path matched by `handleRequest()`.                                                                                |
+| `handlerUrl`              | `string`                                                      | -                                            | Backward-compatible alias for `serveEndpoint`; prefer `serveEndpoint` in new code.                                |
+| `registry`                | `EntityRegistry`                                              | default registry                             | Entity registry for this handler. Falls back to the module-level default registry.                                |
+| `subscriptionPathForType` | `(typeName: string) => string`                                | -                                            | Override the webhook subscription path used per entity type registration.                                         |
+| `idleTimeout`             | `number`                                                      | `20000`                                      | Idle timeout in milliseconds before closing a wake.                                                               |
+| `heartbeatInterval`       | `number`                                                      | `30000`                                      | Heartbeat interval in milliseconds.                                                                               |
+| `createElectricTools`     | `(context) => AgentTool[] \| Promise<...>`                    | -                                            | Optional tool factory invoked for each wake context before handler execution. Provides extra tools to the agent.  |
+| `onWakeError`             | `(error: Error) => boolean \| void`                           | -                                            | Observer for background wake failures. Return `true` to mark the error as handled so it is not rethrown on drain. |
+| `registrationConcurrency` | `number`                                                      | `8`                                          | Max number of concurrent entity-type registrations.                                                               |

package/docs/reference/shared-state-handle.md

@@ -1,6 +1,6 @@
 ---
 title: SharedStateHandle
-titleTemplate: '... - Electric Agents'
+titleTemplate: "... - Electric Agents"
 description: >-
   Type reference for SharedStateHandle: collection proxies and SharedStateSchemaMap interface.
 outline: [2, 3]
@@ -54,7 +54,7 @@ interface SharedStateCollectionSchema {
 ## Example
 
 ```ts
-import { db } from '@electric-ax/agents-runtime'
+import { db } from "@electric-ax/agents-runtime"
 
 const schema = {
   findings: {
@@ -63,12 +63,12 @@ const schema = {
       domain: z.string(),
       finding: z.string(),
     }),
-    type: 'finding',
-    primaryKey: 'key',
+    type: "finding",
+    primaryKey: "key",
   },
 }
 
-ctx.mkdb('research-findings', schema)
-const shared = await ctx.observe(db('research-findings', schema))
-shared.findings.insert({ key: 'f1', domain: 'security', finding: '...' })
+ctx.mkdb("research-findings", schema)
+const shared = await ctx.observe(db("research-findings", schema))
+shared.findings.insert({ key: "f1", domain: "security", finding: "..." })
 ```

package/docs/reference/state-collection-proxy.md

@@ -1,6 +1,6 @@
 ---
 title: StateCollectionProxy
-titleTemplate: '... - Electric Agents'
+titleTemplate: "... - Electric Agents"
 description: >-
   API reference for StateCollectionProxy: insert, update, delete, get, and toArray operations.
 outline: [2, 3]

package/docs/reference/wake-event.md

@@ -1,6 +1,6 @@
 ---
 title: WakeEvent
-titleTemplate: '... - Electric Agents'
+titleTemplate: "... - Electric Agents"
 description: >-
   Type reference for WakeEvent and Wake configuration: runFinished and change-based wake conditions.
 outline: [2, 3]
@@ -27,16 +27,16 @@ type WakeEvent = {
 
 ## Fields
 
-| Field        | Type      | Description                                                                                                                      |
-| ------------ | --------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| `source`     | `string`  | URL or identifier of the stream that triggered the wake.                                                                         |
+| Field        | Type      | Description                                                              |
+| ------------ | --------- | ------------------------------------------------------------------------ |
+| `source`     | `string`  | URL or identifier of the stream that triggered the wake.                 |
 | `type`       | `string`  | Wake type. Usually `"message_received"` or `"wake"`; fallback webhook events can use `triggerEvent` or `"message"`. See catalog. |
-| `fromOffset` | `number`  | Start offset of new events in the source stream.                                                                                 |
-| `toOffset`   | `number`  | End offset (exclusive) of new events.                                                                                            |
-| `eventCount` | `number`  | Number of new events in this wake.                                                                                               |
-| `payload`    | `unknown` | Optional payload data associated with the wake. Shape depends on `type`.                                                         |
-| `summary`    | `string`  | Optional human-readable summary of the wake reason.                                                                              |
-| `fullRef`    | `string`  | Optional full reference identifier for the wake source.                                                                          |
+| `fromOffset` | `number`  | Start offset of new events in the source stream.                         |
+| `toOffset`   | `number`  | End offset (exclusive) of new events.                                    |
+| `eventCount` | `number`  | Number of new events in this wake.                                       |
+| `payload`    | `unknown` | Optional payload data associated with the wake. Shape depends on `type`. |
+| `summary`    | `string`  | Optional human-readable summary of the wake reason.                      |
+| `fullRef`    | `string`  | Optional full reference identifier for the wake source.                  |
 
 ## Wake-type catalog
 
@@ -63,20 +63,20 @@ type WakeMessage = {
   timeout: boolean
   changes: Array<{
     collection: string
-    kind: 'insert' | 'update' | 'delete'
+    kind: "insert" | "update" | "delete"
     key: string
   }>
   finished_child?: {
     url: string
     type: string
-    run_status: 'completed' | 'failed'
+    run_status: "completed" | "failed"
     response?: string
     error?: string
   }
   other_children?: Array<{
     url: string
     type: string
-    status: 'spawning' | 'running' | 'idle' | 'stopped'
+    status: "spawning" | "running" | "idle" | "stopped"
   }>
 }
 ```
@@ -100,12 +100,12 @@ The `Wake` type configures when a parent should be woken in response to a child,
 
 ```ts
 type Wake =
-  | 'runFinished'
-  | { on: 'runFinished'; includeResponse?: boolean }
+  | "runFinished"
+  | { on: "runFinished"; includeResponse?: boolean }
   | {
-      on: 'change'
+      on: "change"
       collections?: string[]
-      ops?: ('insert' | 'update' | 'delete')[]
+      ops?: ("insert" | "update" | "delete")[]
       debounceMs?: number
       timeoutMs?: number
     }
@@ -123,10 +123,10 @@ Object form of `runFinished` with options. Set `includeResponse: false` to omit
 
 Wake the parent when changes occur in the observed stream.
 
-| Field         | Type       | Description                                                           |
-| ------------- | ---------- | --------------------------------------------------------------------- |
-| `on`          | `'change'` | Required discriminant.                                                |
-| `collections` | `string[]` | Optional filter. Only wake on changes to these collections.           |
+| Field         | Type       | Description                                                   |
+| ------------- | ---------- | ------------------------------------------------------------- |
+| `on`          | `'change'` | Required discriminant.                                        |
+| `collections` | `string[]` | Optional filter. Only wake on changes to these collections.   |
 | `ops`         | `string[]` | Optional operation filter: `"insert"`, `"update"`, and/or `"delete"`. |
-| `debounceMs`  | `number`   | Debounce interval in milliseconds. Batches rapid changes.             |
-| `timeoutMs`   | `number`   | Maximum time to wait before waking, even if no changes occur.         |
+| `debounceMs`  | `number`   | Debounce interval in milliseconds. Batches rapid changes.     |
+| `timeoutMs`   | `number`   | Maximum time to wait before waking, even if no changes occur. |

package/docs/usage/app-setup.md

@@ -1,6 +1,6 @@
 ---
 title: App setup
-titleTemplate: '... - Electric Agents'
+titleTemplate: "... - Electric Agents"
 description: >-
   Connect your app to the Electric Agents runtime with createRuntimeHandler, webhooks, and type registration.
 outline: [2, 3]
@@ -18,14 +18,14 @@ Creates a runtime with a Node HTTP adapter:
 import {
   createEntityRegistry,
   createRuntimeHandler,
-} from '@electric-ax/agents-runtime'
+} from "@electric-ax/agents-runtime"
 
 const registry = createEntityRegistry()
 // ... register entity types ...
 
 const runtime = createRuntimeHandler({
-  baseUrl: 'http://localhost:4437',
-  serveEndpoint: 'http://localhost:3000/webhook',
+  baseUrl: "http://localhost:4437",
+  serveEndpoint: "http://localhost:3000/webhook",
   registry,
 })
 ```
@@ -37,6 +37,7 @@ interface RuntimeRouterConfig {
   baseUrl: string // Electric Agents server URL
   serveEndpoint?: string // Webhook callback URL
   webhookPath?: string // Path to match (default: derived from serveEndpoint)
+  handlerUrl?: string // legacy alias for serveEndpoint
   registry?: EntityRegistry
   subscriptionPathForType?: (typeName: string) => string
   idleTimeout?: number // ms before closing idle wake (default: 20000)
@@ -75,10 +76,10 @@ interface RuntimeRouterConfig {
 Your app needs an HTTP server to receive webhook callbacks from the Electric Agents runtime server. Forward webhook POSTs to the runtime handler:
 
 ```ts
-import http from 'node:http'
+import http from "node:http"
 
 const server = http.createServer(async (req, res) => {
-  if (req.url === '/webhook' && req.method === 'POST') {
+  if (req.url === "/webhook" && req.method === "POST") {
     await runtime.onEnter(req, res)
     return
   }
@@ -131,24 +132,24 @@ interface RuntimeDebugState {
 }
 ```
 
-| Method                 | Description                                                                              |
-| ---------------------- | ---------------------------------------------------------------------------------------- |
-| `onEnter`              | Node HTTP adapter — reads the request body and delegates to `handleWebhookRequest`       |
-| `handleRequest`        | Fetch-native router — returns `null` if the path does not match `webhookPath`            |
-| `handleWebhookRequest` | Processes a webhook POST directly, without path matching                                 |
-| `dispatchWebhookWake`  | Dispatches a pre-parsed notification (fire-and-forget)                                   |
-| `drainWakes`           | Waits for all in-flight wake handlers to settle; throws on errors                        |
-| `waitForSettled`       | Waits for all in-flight wakes; throws on errors                                          |
-| `abortWakes`           | Cancels all in-flight wake handlers immediately                                          |
-| `debugState`           | Returns a snapshot of internal runtime state for diagnostics                             |
-| `registerTypes`        | Registers entity types and webhook subscriptions with the Electric Agents runtime server |
+| Method                 | Description                                                                        |
+| ---------------------- | ---------------------------------------------------------------------------------- |
+| `onEnter`              | Node HTTP adapter — reads the request body and delegates to `handleWebhookRequest` |
+| `handleRequest`        | Fetch-native router — returns `null` if the path does not match `webhookPath`      |
+| `handleWebhookRequest` | Processes a webhook POST directly, without path matching                           |
+| `dispatchWebhookWake`  | Dispatches a pre-parsed notification (fire-and-forget)                             |
+| `drainWakes`           | Waits for all in-flight wake handlers to settle; throws on errors                  |
+| `waitForSettled`       | Waits for all in-flight wakes; throws on errors                                    |
+| `abortWakes`           | Cancels all in-flight wake handlers immediately                                    |
+| `debugState`           | Returns a snapshot of internal runtime state for diagnostics                       |
+| `registerTypes`        | Registers entity types and webhook subscriptions with the Electric Agents runtime server     |
 
 ## createRuntimeRouter
 
 Fetch-native alternative with no Node HTTP dependency:
 
 ```ts
-import { createRuntimeRouter } from '@electric-ax/agents-runtime'
+import { createRuntimeRouter } from "@electric-ax/agents-runtime"
 
 const router = createRuntimeRouter(config)
 const response = await router.handleRequest(request)
@@ -158,8 +159,8 @@ Use this when integrating with non-Node frameworks or edge runtimes.
 
 ## Environment variables
 
-| Variable              | Default                 | Purpose                            |
-| --------------------- | ----------------------- | ---------------------------------- |
-| `ELECTRIC_AGENTS_URL` | `http://localhost:4437` | Electric Agents runtime server URL |
-| `PORT`                | `3000`                  | Your app's HTTP port               |
-| `ANTHROPIC_API_KEY`   | —                       | Claude API key                     |
+| Variable            | Default                 | Purpose                  |
+| ------------------- | ----------------------- | ------------------------ |
+| `ELECTRIC_AGENTS_URL`         | `http://localhost:4437` | Electric Agents runtime server URL |
+| `PORT`              | `3000`                  | Your app's HTTP port     |
+| `ANTHROPIC_API_KEY` | —                       | Claude API key           |