@electric-ax/agents 0.4.19 → 0.6.0

package/docs/usage/attachments.md

@@ -0,0 +1,129 @@
+---
+title: Attachments
+titleTemplate: "... - Electric Agents"
+description: >-
+  Upload, reference, read, and hydrate files and images for Electric Agents entities.
+outline: [2, 3]
+---
+
+# Attachments
+
+Attachments are files associated with an entity. They are uploaded through entity routes, stored in private attachment streams, and referenced by `manifest` rows on the entity stream.
+
+Attachments are useful for image inputs, user-uploaded files, generated artifacts, and tool outputs that should be tracked alongside the entity timeline.
+
+## Upload from clients
+
+Use `createRuntimeServerClient().createAttachment()`:
+
+```ts
+import { createRuntimeServerClient } from "@electric-ax/agents-runtime"
+
+const client = createRuntimeServerClient({
+  baseUrl: "http://localhost:4437",
+  principalKey: "user:sam",
+})
+
+const { attachment } = await client.createAttachment({
+  entityUrl: "/horton/onboarding",
+  attachment: {
+    bytes: imageBytes,
+    mimeType: "image/png",
+    filename: "screenshot.png",
+    subject: { type: "inbox", key: "message-1" },
+    role: "input",
+    meta: { source: "upload" },
+  },
+})
+```
+
+The server writes a manifest entry like:
+
+```ts
+interface ManifestAttachmentEntry {
+  kind: "attachment"
+  id: string
+  streamPath: string
+  status: "pending" | "complete" | "failed"
+  subject: {
+    type: "inbox" | "run" | "text" | "tool_call" | "context"
+    key: string
+  }
+  role: "input" | "output"
+  mimeType: string
+  filename?: string
+  byteLength?: number
+  sha256?: string
+  createdAt: string
+  createdBy?: string
+  error?: string
+  meta?: Record<string, JsonValue>
+}
+```
+
+## Read from clients
+
+Read bytes by entity URL and attachment id:
+
+```ts
+const bytes = await client.readAttachment({
+  entityUrl: "/horton/onboarding",
+  id: attachment.id,
+})
+```
+
+The caller needs read access to the entity.
+
+## Handler API
+
+Handlers access attachments through `ctx.attachments`:
+
+```ts
+async handler(ctx) {
+  const inputs = ctx.attachments.list({ role: "input" })
+  const first = inputs[0]
+  if (!first) return
+
+  const bytes = await ctx.attachments.read(first.id)
+  // Use bytes in a custom tool or external API call.
+}
+```
+
+Available operations:
+
+| Method | Purpose |
+| ------ | ------- |
+| `list(filter?)` | List manifest-backed attachments, optionally by role or subject. |
+| `get(id)` | Return one attachment manifest entry by id. |
+| `read(id)` | Read attachment bytes. |
+| `create(input)` | Create a new attachment associated with this entity. |
+
+## Subjects and roles
+
+The `subject` links an attachment to the timeline object it belongs to:
+
+| Subject type | Typical use |
+| ------------ | ----------- |
+| `inbox`      | User-uploaded input attached to a message |
+| `run`        | Artifact associated with an agent run |
+| `text`       | File linked to generated text |
+| `tool_call`  | Tool input or output artifact |
+| `context`    | Durable context material |
+
+`role` is either `input` or `output`. Input attachments are usually supplied by users or the host app. Output attachments are usually created by handlers or tools.
+
+## Images in agent context
+
+When image attachments are associated with inbox messages, the runtime can hydrate supported image inputs into model messages. The UI should hide image upload controls for models that do not advertise image input support.
+
+To keep context bounded, image hydration uses newest-first byte/count guardrails. Large or older images may remain as attachment descriptors rather than inline model content.
+
+## Failure and rollback
+
+Attachment uploads can fail independently of message sends. UI flows should roll back uploaded attachments if the send that references them fails, or leave an explicit failed manifest row when the failure should be visible to the entity.
+
+## Related APIs
+
+- [`HandlerContext`](../reference/handler-context) documents `ctx.attachments`.
+- [`Built-in collections`](../reference/built-in-collections) documents attachment manifest rows.
+- [`Programmatic runtime client`](./programmatic-runtime-client) documents `createAttachment()` and `readAttachment()`.

package/docs/usage/clients-and-react.md

@@ -17,10 +17,10 @@ Use the client APIs when you need to observe agents from application code rather
 
 ```ts
 import {
-  codingSession,
   createAgentsClient,
   entity,
   entities,
+  pgSync,
 } from "@electric-ax/agents-runtime"
 
 const client = createAgentsClient({ baseUrl: "http://localhost:4437" })
@@ -43,17 +43,27 @@ console.log(membersDb.collections.members.toArray)
 interface AgentsClientConfig {
   baseUrl: string
   fetch?: typeof globalThis.fetch
+  principalKey?: string
 }
 
 interface AgentsClient {
   observe(
     source: ObservationSource
   ): Promise<EntityStreamDB | ObservationStreamDB>
+  signal(options: {
+    entityUrl: string
+    signal: EntitySignal
+    reason?: string
+    payload?: unknown
+  }): Promise<{ txid: number }>
+  kill(entityUrl: string, reason?: string): Promise<{ txid: number }>
 }
 ```
 
 `observe(entity(url))` returns an `EntityStreamDB`. `observe(entities(...))` and `observe(db(...))` return an `ObservationStreamDB`.
 
+Use `principalKey` when observing or signalling against a server that enforces principal-scoped access.
+
 :::: warning
 `client.observe(cron(...))` is not currently supported. Use cron sources from handler wake subscriptions, or schedule tools exposed through `ctx.electricTools`.
 ::::
@@ -67,12 +77,23 @@ The same source helpers used by `ctx.observe()` can be used with `AgentsClient`.
 | `entity(url)`       | Observe one entity by URL.                           |
 | `entities({ tags })` | Observe the entity membership stream matching tags. |
 | `db(id, schema)`    | Observe a shared-state stream.                       |
+| `webhook(endpointKey, opts?)` | Observe a webhook-backed stream.             |
+| `pgSync(options)`   | Observe an Electric Postgres shape stream.           |
 | `cron(expression)`  | Build a cron source for wake subscriptions.          |
 
 ```ts
-import { db } from "@electric-ax/agents-runtime"
+import { db, pgSync } from "@electric-ax/agents-runtime"
 
 const shared = await client.observe(db("research-123", researchSchema))
+
+const todos = await client.observe(
+  pgSync({
+    url: "http://localhost:3000/v1/shape",
+    table: "todos",
+    where: "project_id = $1",
+    params: ["docs"],
+  })
+)
 ```
 
 ## React useChat

package/docs/usage/configuring-the-agent.md

@@ -16,11 +16,18 @@ Call `ctx.useAgent()` in your handler to set up the LLM, then `ctx.agent.run()`
 interface AgentConfig {
   systemPrompt: string
   model: string | Model<any>
-  provider?: KnownProvider
+  provider?: Provider
   tools: AgentTool[]
   streamFn?: StreamFn
   getApiKey?: (provider: string) => Promise<string | undefined> | string | undefined
   onPayload?: SimpleStreamOptions["onPayload"]
+  onStepEnd?: (stats: {
+    input: number
+    uncachedInput: number
+    output: number
+  }) => void
+  modelTimeoutMs?: number
+  modelMaxRetries?: number
   testResponses?: string[] | TestResponseFn
 }
 ```
@@ -29,11 +36,14 @@ interface AgentConfig {
 | --------------- | -------- | ----------------------------------------------------------------------- |
 | `systemPrompt`  | Yes      | The system prompt passed to the LLM.                                    |
 | `model`         | Yes      | Model identifier string or resolved model object.                       |
-| `provider`      | No       | Provider to use when `model` is a string. Defaults to `"anthropic"`.    |
+| `provider`      | No       | pi-ai provider to use when `model` is a string. Defaults to `"anthropic"`. |
 | `tools`         | Yes      | Array of tools available to the agent. Spread `ctx.electricTools` when your runtime host provides runtime-level tools. |
 | `streamFn`      | No       | Optional streaming callback passed to the underlying agent.             |
 | `getApiKey`     | No       | Optional API-key resolver passed through to the model layer.            |
 | `onPayload`     | No       | Optional callback for raw streaming payloads from the model layer.      |
+| `onStepEnd`     | No       | Callback after each model step with provider-reported token counts.     |
+| `modelTimeoutMs` | No      | Timeout for individual model calls, in milliseconds.                    |
+| `modelMaxRetries` | No     | Maximum retry count for model calls.                                    |
 | `testResponses` | No       | Mock responses for testing without calling the LLM.                     |
 
 ## Basic usage
@@ -42,7 +52,7 @@ interface AgentConfig {
 async handler(ctx) {
   ctx.useAgent({
     systemPrompt: 'You are a helpful assistant.',
-    model: 'claude-sonnet-4-5-20250929',
+    model: 'claude-sonnet-4-6',
     tools: [...ctx.electricTools],
   })
   await ctx.agent.run()
@@ -106,7 +116,7 @@ You must call `useAgent` before calling `run()`. Calling `ctx.agent.run()` witho
 When `model` is a string, the runtime resolves it through the configured `provider` (default `"anthropic"`). You can also pass a resolved `Model` object directly.
 
 ```ts
-model: "claude-sonnet-4-5-20250929"
+model: "claude-sonnet-4-6"
 provider: "anthropic"
 ```
 
@@ -119,7 +129,7 @@ For testing handlers without making LLM calls, pass `testResponses`. Two forms a
 ```ts
 ctx.useAgent({
   systemPrompt: "...",
-  model: "claude-sonnet-4-5-20250929",
+  model: "claude-sonnet-4-6",
   tools: [...ctx.electricTools],
   testResponses: ["Hello! How can I help?", "Sure, I can do that."],
 })

package/docs/usage/context-composition.md

@@ -17,6 +17,7 @@ Most entities don't need `useContext` -- the default timeline assembly works wel
 - **Budget token space** across multiple content sources (docs, conversation history, retrieved context)
 - **Mix static and dynamic content** with different caching behavior
 - **Inject external content** (documentation, search results, knowledge bases) alongside conversation history
+- **Hydrate uploaded files or images** through manifest-backed [attachments](./attachments)
 
 ## UseContextConfig
 
@@ -190,7 +191,7 @@ async handler(ctx, wake) {
 
   ctx.useAgent({
     systemPrompt: "You are a helpful assistant.",
-    model: "claude-sonnet-4-5-20250929",
+    model: "claude-sonnet-4-6",
     tools,
   })
   await ctx.agent.run()

package/docs/usage/defining-entities.md

@@ -24,7 +24,7 @@ registry.define("assistant", {
   async handler(ctx) {
     ctx.useAgent({
       systemPrompt: "You are a helpful assistant.",
-      model: "claude-sonnet-4-5-20250929",
+      model: "claude-sonnet-4-6",
       tools: [...ctx.electricTools],
     })
     await ctx.agent.run()
@@ -45,7 +45,8 @@ interface EntityDefinition {
   ) => Record<string, (...args: unknown[]) => void>
   creationSchema?: StandardJSONSchemaV1
   inboxSchemas?: Record<string, StandardJSONSchemaV1>
-  outputSchemas?: Record<string, StandardJSONSchemaV1>
+  stateSchemas?: Record<string, StandardJSONSchemaV1>
+  permissionGrants?: EntityTypePermissionGrantDefinition[]
   handler: (ctx: HandlerContext, wake: WakeEvent) => void | Promise<void>
 }
 ```
@@ -57,9 +58,12 @@ interface EntityDefinition {
 | `actions`        | Factory that returns custom non-CRUD action functions exposed on `ctx.actions`.       |
 | `creationSchema` | JSON Schema for arguments passed when the entity is spawned.                          |
 | `inboxSchemas`   | JSON Schemas for typed inbox message categories.                                      |
-| `outputSchemas`  | JSON Schemas for typed output message categories.                                     |
+| `stateSchemas`   | Additional JSON Schemas registered with the entity type's state schema map.           |
+| `permissionGrants` | Initial permission grants applied when this entity type is registered.              |
 | `handler`        | The function that runs each time the entity wakes. Required.                          |
 
+See [Permissions & principals](./permissions-and-principals) for the access-control model behind `permissionGrants`.
+
 ## Custom state
 
 Declare named collections in the `state` field. Each collection is a `CollectionDefinition`:
@@ -145,7 +149,7 @@ export function registerAssistant(registry: EntityRegistry) {
     async handler(ctx) {
       ctx.useAgent({
         systemPrompt: "You are a helpful assistant.",
-        model: "claude-sonnet-4-5-20250929",
+        model: "claude-sonnet-4-6",
         tools: [...ctx.electricTools],
       })
       await ctx.agent.run()
@@ -158,7 +162,7 @@ This keeps each entity type isolated and the registry composition explicit.
 
 ## Schemas
 
-`creationSchema`, `inboxSchemas`, and `outputSchemas` accept [`StandardJSONSchemaV1`](https://github.com/standard-schema/standard-schema) objects. Any schema library implementing the Standard JSON Schema interface works (e.g. Zod v4). These schemas are used for validation and for generating UI and documentation in the Electric Agents dashboard.
+`creationSchema`, `inboxSchemas`, and `stateSchemas` accept [`StandardJSONSchemaV1`](https://github.com/standard-schema/standard-schema) objects. Any schema library implementing the Standard JSON Schema interface works (e.g. Zod v4). These schemas are used for validation and for generating UI and documentation in the Electric Agents dashboard.
 
 ```ts
 import { z } from "zod/v4"

package/docs/usage/defining-tools.md

@@ -217,7 +217,7 @@ registry.define("assistant", {
 
     ctx.useAgent({
       systemPrompt: "You are a helpful assistant with persistent memory.",
-      model: "claude-sonnet-4-5-20250929",
+      model: "claude-sonnet-4-6",
       tools: [...ctx.electricTools, memoryTool, dispatchTool, calculatorTool],
     })
     await ctx.agent.run()

package/docs/usage/embedded-builtins.md

@@ -13,21 +13,24 @@ The CLI commands `electric agents start-builtin` and `electric agents quickstart
 
 ## BuiltinAgentsServer
 
-`BuiltinAgentsServer` starts an HTTP webhook server, registers `horton` and `worker`, and forwards Electric Agents webhook wakes to the built-in handler.
+`BuiltinAgentsServer` registers `horton` and `worker`, advertises the runtime's sandbox profiles, and starts a pull-wake runner that claims wakes from the Electric Agents server. This is the same model used by the CLI and desktop app.
 
 ```ts
 import { BuiltinAgentsServer } from "@electric-ax/agents"
 
 const server = new BuiltinAgentsServer({
   agentServerUrl: "http://localhost:4437",
-  port: 4448,
   workingDirectory: process.cwd(),
+  loadProjectMcpConfig: true,
+  pullWake: {
+    runnerId: "builtin-agents",
+    ownerPrincipal: "/principal/system%3Abuiltin-agents",
+    registerRunner: true,
+  },
 })
 
-await server.start()
-
-console.log(server.url)
-console.log(server.registeredBaseUrl)
+const runtimeUrl = await server.start()
+console.log(runtimeUrl) // "pull-wake:builtin-agents"
 
 // Later, during shutdown:
 await server.stop()
@@ -42,12 +45,23 @@ type CreateElectricTools = RuntimeRouterConfig["createElectricTools"]
 
 interface BuiltinAgentsServerOptions {
   agentServerUrl: string
-  baseUrl?: string
-  port: number
-  host?: string
   workingDirectory?: string
   mockStreamFn?: StreamFn
-  webhookPath?: string
+  durableStreamsFetchCache?: DurableStreamsFetchCacheOptions | false
+  pullWake: {
+    runnerId: string
+    ownerPrincipal?: string
+    label?: string
+    registerRunner?: boolean
+    headers?: HeadersProvider
+    claimHeaders?: HeadersProvider
+    claimTokenHeader?: ClaimTokenHeader
+    heartbeatIntervalMs?: number
+    eventHeartbeatThrottleMs?: number
+    leaseMs?: number
+  }
+  enabledModelValues?: readonly string[] | null
+  baseSkillsDir?: string
   createElectricTools?: CreateElectricTools
   // MCP integration
   extraMcpServers?: ReadonlyArray<McpServerConfig>
@@ -61,24 +75,49 @@ interface BuiltinAgentsServerOptions {
 | 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.                                                                                                                                                                                                                |
+| `mockStreamFn`         | Optional test stream function. Lets you run without a real model provider.                                                                                                                                                                                                             |
+| `durableStreamsFetchCache` | Optional process-wide HTTP cache tuning for Undici-backed fetch calls. Pass `false` to leave the global dispatcher unchanged.                                                                                                                                                    |
+| `pullWake`             | Pull-wake runner configuration. `runnerId` identifies this runtime to the server. Set `registerRunner: true` when this process should create/update the runner record.                                                                                                                  |
+| `enabledModelValues`   | Optional allowlist of model values exposed by built-in agent creation schemas. Values use the model catalog's `provider:model` form.                                                                                                                                                    |
+| `baseSkillsDir`        | Override for the bundled skills directory, useful when an embedder packages `@electric-ax/agents`.                                                                                                                                                                                      |
+| `createElectricTools`  | Optional factory for tools injected into built-in agent handlers. The default built-in factory includes webhook-source and schedule tools; override or wrap it when adding host-specific tools.                                                                                                                                                                                                              |
 | `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.                   |
+| `loadProjectMcpConfig` | Load `<workingDirectory>/mcp.json` (and watch it). Off by default because stdio MCP servers can spawn local commands, so embedders 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. 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.
+Without `mockStreamFn`, at least one supported provider must be configured before the built-in handler starts: `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `DEEPSEEK_API_KEY`, `MOONSHOT_API_KEY`, or a valid OpenAI Codex CLI auth file for the `openai-codex` provider.
+
+### Pull-wake headers and principals
+
+When the server enforces principals or auth, pass the same headers to runner registration and wake claims:
+
+```ts
+const serverHeaders = {
+  "electric-principal": "service:local-runtime",
+  authorization: `Bearer ${process.env.ELECTRIC_AGENTS_TOKEN}`,
+}
+
+const server = new BuiltinAgentsServer({
+  agentServerUrl: "http://localhost:4437",
+  pullWake: {
+    runnerId: "local-runtime",
+    ownerPrincipal: "/principal/service%3Alocal-runtime",
+    registerRunner: true,
+    headers: serverHeaders,
+    claimHeaders: serverHeaders,
+    claimTokenHeader: "electric-claim-token",
+  },
+})
+```
+
+Use `claimTokenHeader: "electric-claim-token"` when your `authorization` header is reserved for server auth. Otherwise the default claim token transport is the standard `Authorization: Bearer <claim-token>` header.
 
 ## createBuiltinAgentHandler
 
-Use `createBuiltinAgentHandler()` when you already have an HTTP server and only need the request handler and runtime objects.
+Use `createBuiltinAgentHandler()` when you need the lower-level registry/runtime objects. If you pass `serveEndpoint`, `registerTypes()` registers webhook dispatch for the built-in types. If you are using pull-wake, prefer `BuiltinAgentsServer`, which wires runner registration, MCP, sandbox profiles, and wake claiming for you.
 
 ```ts
 import {
@@ -93,7 +132,7 @@ const bootstrap = await createBuiltinAgentHandler({
 })
 
 if (!bootstrap) {
-  throw new Error("ANTHROPIC_API_KEY is required for built-in agents")
+  throw new Error("No supported model provider is configured")
 }
 
 await registerBuiltinAgentTypes(bootstrap)
@@ -111,19 +150,29 @@ interface AgentHandlerResult {
   registry: EntityRegistry
   typeNames: string[]
   skillsRegistry: SkillsRegistry | null
+  shutdownSandboxes: (() => Promise<void>) | null
+  modelCatalog: BuiltinModelCatalog
 }
 ```
 
+Call `shutdownSandboxes()` during process shutdown when it is present. `modelCatalog` is the catalog used by the built-in Horton and Worker definitions; pass it along if you register sibling built-in-style types directly with `registerHorton()` or `registerWorker()`. Most embedders should use `registerBuiltinAgentTypes()` instead.
+
 ## Extra Electric Tools
 
 Both `BuiltinAgentsServer` and `createBuiltinAgentHandler()` accept `createElectricTools`. The factory receives the same context shape as `RuntimeRouterConfig.createElectricTools` and can add host-specific tools to Horton.
 
+If you do not provide a custom factory, the built-in runtime injects webhook-source tools and schedule tools (`list_schedules`, `upsert_cron_schedule`, `upsert_future_send`, and `delete_schedule`). If you replace the factory entirely, include those tools yourself when Horton should keep that behavior.
+
 ```ts
+import { BuiltinAgentsServer } from "@electric-ax/agents"
 import { Type } from "@sinclair/typebox"
 
 const server = new BuiltinAgentsServer({
   agentServerUrl: "http://localhost:4437",
-  port: 4448,
+  pullWake: {
+    runnerId: "builtin-agents",
+    registerRunner: true,
+  },
   createElectricTools: ({ entityUrl, upsertCronSchedule }) => [
     {
       name: "schedule_daily_summary",
@@ -165,15 +214,17 @@ await server.stop()
 
 Environment variables:
 
-| Variable                         | Description                                           |
-| -------------------------------- | ----------------------------------------------------- |
-| `ELECTRIC_AGENTS_SERVER_URL`     | Required coordinator server URL.                      |
-| `ELECTRIC_AGENTS_PRINCIPAL`      | Optional principal key sent as `Electric-Principal`.  |
-| `ELECTRIC_AGENTS_SERVER_HEADERS` | Optional JSON object of additional server headers.    |
-| `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_BASE_URL`                 | Legacy alias for `ELECTRIC_AGENTS_SERVER_URL`.                              |
+| `ELECTRIC_AGENTS_PULL_WAKE_RUNNER_ID`      | Required pull-wake runner id.                                               |
+| `PULL_WAKE_RUNNER_ID`                      | Legacy alias for `ELECTRIC_AGENTS_PULL_WAKE_RUNNER_ID`.                     |
+| `ELECTRIC_AGENTS_REGISTER_PULL_WAKE_RUNNER` | Set to `true` or `1` to register/update the runner record before claiming. |
+| `ELECTRIC_AGENTS_PRINCIPAL`                | Optional principal key sent as `Electric-Principal`.                        |
+| `ELECTRIC_AGENTS_SERVER_HEADERS`           | Optional JSON object of additional server headers.                          |
+| `ELECTRIC_AGENTS_WORKING_DIRECTORY`        | Working directory for file tools.                                           |
+| `WORKING_DIRECTORY`                        | Legacy alias for `ELECTRIC_AGENTS_WORKING_DIRECTORY`.                       |
 
 ## Built-in Agent APIs
 

package/docs/usage/managing-state.md

@@ -42,11 +42,16 @@ interface CollectionDefinition {
   schema?: StandardSchemaV1 // Zod or any Standard Schema validator
   type?: string // Event type in the stream. Defaults to "state:{name}"
   primaryKey?: string // Key field. Defaults to "key"
+  externallyWritable?: boolean // Opt in to HTTP writes for this collection
+  contract?: string // Well-known contract implemented by this collection
+  operations?: Array<"insert" | "update" | "delete"> // External write allowlist
 }
 ```
 
 All fields are optional. A minimal collection like `{ primaryKey: 'key' }` works without a schema — rows are untyped.
 
+Set `externallyWritable: true` only for collections that should accept writes through the entity collection HTTP routes. When enabled, `operations` controls which external write operations are allowed; if omitted, the server permits inserts only.
+
 ## Writing and reading state
 
 Use `ctx.state.<collection>` for normal handler code. Its `insert`, `update`, and `delete` methods route through generated actions; its `get` and `toArray` members read from the underlying TanStack DB collection.

package/docs/usage/mcp-servers.md

@@ -26,8 +26,11 @@ import { BuiltinAgentsServer } from "@electric-ax/agents"
 
 const server = new BuiltinAgentsServer({
   agentServerUrl: "http://localhost:4437",
-  port: 4448,
   workingDirectory: process.cwd(),
+  pullWake: {
+    runnerId: "builtin-agents",
+    registerRunner: true,
+  },
 })
 
 await server.start()
@@ -44,7 +47,7 @@ const result = await server.mcpRegistry?.addServer({
 })
 ```
 
-`addServer` returns a discriminated [`AddServerResult`](#addserverresult) — `{ state: "ready" | "authenticating" | "error", … }`. The state landscape is described in [Server states](#server-states) below; the full lifecycle (hot-reload, reauthorize, timeouts) lives in [Lifecycle](#lifecycle).
+`addServer` returns a discriminated [`AddServerResult`](/docs/agents/reference/mcp-registry#addserverresult) — `{ state: "ready" | "authenticating" | "error", … }`. The state landscape is described in [Server states](#server-states) below; the full lifecycle (hot-reload, reauthorize, timeouts) lives in [Lifecycle](#lifecycle).
 
 The bulk methods are:
 
@@ -95,7 +98,7 @@ For static, project-scoped configuration the runtime can load `mcp.json` from th
 }
 ```
 
-For [`authorizationCode`](#authorization-code-oauth) servers in `mcp.json`, the runtime auto-wires `keychainPersistence` so OAuth tokens survive process restarts via the OS keychain.
+For [`authorizationCode`](#authorizationcode-oauth) servers in `mcp.json`, the runtime auto-wires `keychainPersistence` so OAuth tokens survive process restarts via the OS keychain.
 
 ### Desktop settings layer
 
@@ -117,10 +120,15 @@ Example shape:
 
 ```jsonc
 {
-  "servers": [...],
-  "activeServer": {...},
+  "servers": [
+    {
+      "id": "local",
+      "name": "Local",
+      "url": "http://localhost:4437"
+    }
+  ],
+  "defaultServerId": "local",
   "workingDirectory": "/Users/me/workspace/foo",
-  "apiKeys": {...},
   "mcp": {
     "servers": {
       "linear": {
@@ -137,10 +145,10 @@ Programmatic embedders (other than the desktop) pass the resolved set as an arra
 
 ## Per-agent allowlist
 
-Entity definitions opt into MCP servers explicitly via the `mcp.tools()` helper from `@electric-ax/agents-runtime`:
+Entity definitions opt into MCP servers explicitly via the `mcp.tools()` helper from `@electric-ax/agents-mcp`:
 
 ```ts
-import { mcp } from "@electric-ax/agents-runtime"
+import { mcp } from "@electric-ax/agents-mcp"
 
 registry.define("research-agent", {
   async handler(ctx) {