docs: refresh agents documentation (#4491)

## Preview

https://deploy-preview-4491--electric-next.netlify.app/docs/agents/

## Summary
- Refresh agents docs against the current runtime, server, CLI, client,
and built-in agent APIs.
- Add dedicated usage pages for permissions, sandboxing, attachments,
signals, and event sources.
- Update sidebar/navigation plus stale references for Horton, Worker,
collections, pull-wake built-ins, MCP, runtime clients, and model
examples.

## Test plan
- `nvm use 22 && pnpm --dir website exec vitepress build .`
- Stale-term grep for removed agents docs patterns: old Coder
references, old model IDs, `brave_search`, `removeTag`, stale
`send()`/status snippets, and old attachment subject shape.
- Cursor lints for edited agents docs and VitePress config.

## Notes
- `pnpm --dir website run typecheck` was attempted earlier and still
fails on pre-existing site-wide Vue type resolution issues unrelated to
these docs changes.
- VitePress build exits successfully, while printing existing site
warnings from PGlite bundling and an SSR `requestAnimationFrame` warning
in a blog component.

Made with [Cursor](https://cursor.com)

---------

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: samwillis

website/.vitepress/config.mts

@@ -260,6 +260,10 @@ const agentsDocsSidebar = [
         text: 'Managing state',
         link: '/docs/agents/usage/managing-state',
       },
+      {
+        text: 'Permissions & principals',
+        link: '/docs/agents/usage/permissions-and-principals',
+      },
       {
         text: 'Spawning & coordinating',
         link: '/docs/agents/usage/spawning-and-coordinating',
@@ -268,6 +272,9 @@ const agentsDocsSidebar = [
         text: 'Waking entities',
         link: '/docs/agents/usage/waking-entities',
       },
+      { text: 'Signals', link: '/docs/agents/usage/signals' },
+      { text: 'Sandboxing', link: '/docs/agents/usage/sandboxing' },
+      { text: 'Attachments', link: '/docs/agents/usage/attachments' },
       { text: 'Shared state', link: '/docs/agents/usage/shared-state' },
       {
         text: 'Clients & React',
@@ -282,6 +289,7 @@ const agentsDocsSidebar = [
         text: 'Embedded built-ins',
         link: '/docs/agents/usage/embedded-builtins',
       },
+      { text: 'Webhook sources', link: '/docs/agents/usage/webhook-sources' },
       { text: 'MCP servers', link: '/docs/agents/usage/mcp-servers' },
       { text: 'Testing', link: '/docs/agents/usage/testing' },
     ],

website/docs/agents/entities/agents/horton.md

@@ -26,31 +26,36 @@ npx electric-ax agents observe /horton/my-horton
 
 Horton is configured with `ctx.electricTools` plus the base Horton tool set:
 
-| Tool           | Purpose                                                  |
-| -------------- | -------------------------------------------------------- |
-| `bash`         | Run shell commands in the working directory.             |
-| `read`         | Read a file. Tracked in a per-wake `readSet`.            |
-| `write`        | Create or overwrite a file.                              |
-| `edit`         | Targeted string replacement (file must be `read` first). |
-| `brave_search` | Web search via the Brave Search API.                     |
-| `fetch_url`    | Fetch a URL and return it as markdown.                   |
-| `spawn_worker` | Dispatch a subagent for an isolated subtask.             |
-
-`brave_search` requires `BRAVE_SEARCH_API_KEY` in the environment; without it the tool errors at call time.
-
-When docs support or skills are available, Horton also adds the docs search tool and skill tools during bootstrap.
+| Tool              | Purpose                                                  |
+| ----------------- | -------------------------------------------------------- |
+| `bash`            | Run shell commands in the working directory.             |
+| `read`            | Read a file. Tracked in a per-wake `readSet`.            |
+| `write`           | Create or overwrite a file.                              |
+| `edit`            | Targeted string replacement (file must be `read` first). |
+| `web_search`      | Web search via the configured search provider.           |
+| `fetch_url`       | Fetch a URL and return it as markdown.                   |
+| `spawn_worker`    | Dispatch a subagent for an isolated subtask.             |
+| `fork`            | Branch a session at its latest completed response.       |
+| `observe_pg_sync` | Observe an Electric Postgres shape and wake on changes.  |
+| `unobserve_pg_sync` | Remove an existing pg-sync observation.                |
+| `send`            | Send a message to another entity.                        |
+| `set_title`       | Rename the current chat session title.                   |
+
+`web_search` uses the search provider configured by the built-in runtime; Brave search requires `BRAVE_SEARCH_API_KEY`.
+
+When docs support or skills are available, Horton also adds the docs search tool and skill tools during bootstrap. Built-in runtimes also provide `ctx.electricTools`, including schedule tools and webhook-source tools when configured.
 
 ## Title generation
 
-After the first agent run completes, Horton calls `generateTitle()` (Haiku) to summarise the user's first message into a 3-5 word session title and stores it via `ctx.setTag('title', title)`. Failures are logged and ignored — the entity continues without a title.
+After the first agent run completes, Horton calls `generateTitle()` using the configured low-cost model to summarise the user's first message into a 3-5 word session title and stores it via `ctx.setTag('title', title)`. Failures are logged and ignored — the entity continues without a title.
 
 ## Details
 
 | Property          | Value                                             |
 | ----------------- | ------------------------------------------------- |
 | Type name         | `horton`                                          |
-| Model             | `HORTON_MODEL` (`claude-sonnet-4-5-20250929`)     |
-| Title model       | `claude-haiku-4-5-20251001`                       |
+| Model             | `HORTON_MODEL` (`claude-sonnet-4-6` by default)   |
+| Title model       | Configured low-cost model                         |
 | Tools             | `ctx.electricTools` + base Horton tool set, plus docs/skill tools when configured |
 | Working directory | Passed at bootstrap (defaults to `process.cwd()`) |
 | Title generation  | Yes, after the first run if no title tag exists   |
@@ -75,7 +80,7 @@ registry.define("my-assistant", {
       model: HORTON_MODEL,
       tools: [
         ...ctx.electricTools,
-        ...createHortonTools(process.cwd(), ctx, readSet),
+        ...createHortonTools(ctx.sandbox, ctx, readSet),
         myCustomTool,
       ],
     })

website/docs/agents/entities/agents/worker.md

@@ -20,6 +20,9 @@ interface WorkerArgs {
   tools?: Array<WorkerToolName>
   sharedDb?: { id: string; schema: SharedStateSchemaMap }
   sharedDbToolMode?: "full" | "write-only"
+  model?: string
+  provider?: string
+  reasoningEffort?: string
 }
 ```
 
@@ -29,8 +32,11 @@ interface WorkerArgs {
 | `tools`            | No       | Subset of valid tool names (see below). Unknown names throw at parse time.                    |
 | `sharedDb`         | No       | Shared state stream id and schema to connect to.                                              |
 | `sharedDbToolMode` | No       | Shared state tool mode: `"full"` (default) or `"write-only"`.                                 |
+| `model`            | No       | Model id override. Usually inherited from `spawn_worker` / Horton model config.               |
+| `provider`         | No       | Model provider override paired with `model`.                                                  |
+| `reasoningEffort`  | No       | Reasoning effort override for compatible reasoning models.                                    |
 
-`registerWorker(registry, { workingDirectory, streamFn? })` is called by the dev server during bootstrap; you don't usually call it yourself.
+`registerWorker(registry, { workingDirectory, modelCatalog, streamFn? })` is called by the dev server during bootstrap; you don't usually call it yourself. The bootstrap path supplies the required `modelCatalog`.
 
 ## Valid tool names
 
@@ -40,9 +46,10 @@ type WorkerToolName =
   | "read"
   | "write"
   | "edit"
-  | "brave_search"
+  | "web_search"
   | "fetch_url"
   | "spawn_worker"
+  | "send"
 ```
 
 These are the same primitives Horton uses. Pick the smallest subset the worker needs — tools are the worker's permission set.
@@ -57,7 +64,7 @@ The canonical way to spawn a worker is the `spawn_worker` tool, which Horton cal
 spawn_worker({
   systemPrompt:
     "You are a focused researcher. Find the three most-cited papers on X and return their titles, authors, and DOIs as a markdown table.",
-  tools: ["brave_search", "fetch_url"],
+  tools: ["web_search", "fetch_url"],
   initialMessage: "Begin research now.",
 })
 ```
@@ -75,7 +82,7 @@ The spawn uses `wake: { on: 'runFinished', includeResponse: true }`, so the spaw
 1. Parses `ctx.args` into `WorkerArgs`. Throws if `systemPrompt` is empty, if `tools` contains an unknown name, or if neither `tools` nor `sharedDb` is provided.
 2. Builds the requested tool instances against the worker's `workingDirectory` (and a fresh per-wake `readSet` for the read-first-then-edit guard).
 3. If `sharedDb` is present, connects with `ctx.observe(db(id, schema))` and exposes generated `read_*`, `write_*`, `update_*`, and `delete_*` tools (`write_*` only in `"write-only"` mode).
-4. Configures the agent with `HORTON_MODEL` (`claude-sonnet-4-5-20250929`), the provided system prompt (with a brief reporting-back footer appended), and the assembled tool list.
+4. Configures the agent with `HORTON_MODEL` (`claude-sonnet-4-6` by default), the provided system prompt (with a brief reporting-back footer appended), and the assembled tool list.
 5. Runs the agent until the LLM stops.
 
 ::: warning Least-privilege sandbox
@@ -96,7 +103,7 @@ When you finish, respond with a concise report covering what was done and any ke
 | Property          | Value                                                                 |
 | ----------------- | --------------------------------------------------------------------- |
 | Type name         | `worker`                                                              |
-| Model             | `HORTON_MODEL` (`claude-sonnet-4-5-20250929`)                         |
-| Tools             | Subset of 7 primitives plus optional shared-state tools. **No `ctx.electricTools`.** |
+| Model             | `HORTON_MODEL` (`claude-sonnet-4-6` by default)                       |
+| Tools             | Subset of 8 primitives plus optional shared-state tools. **No `ctx.electricTools`.** |
 | Working directory | Provided to `registerWorker` at bootstrap                             |
 | Description       | `Internal — generic worker spawned by other agents. Configure via spawn args (systemPrompt + tools + optional sharedDb).` |

website/docs/agents/entities/patterns/blackboard.md

@@ -58,7 +58,7 @@ export function registerDebate(registry: EntityRegistry) {
 
       ctx.useAgent({
         systemPrompt: DEBATE_SYSTEM_PROMPT,
-        model: `claude-sonnet-4-5-20250929`,
+        model: `claude-sonnet-4-6`,
         tools: [...ctx.electricTools, startTool, checkTool, endTool],
       })
       await ctx.agent.run()

website/docs/agents/entities/patterns/dispatcher.md

@@ -24,7 +24,7 @@ export function registerDispatcher(registry: EntityRegistry) {
 
       ctx.useAgent({
         systemPrompt: DISPATCHER_SYSTEM_PROMPT,
-        model: `claude-sonnet-4-5-20250929`,
+        model: `claude-sonnet-4-6`,
         tools: [...ctx.electricTools, dispatchTool],
       })
       await ctx.agent.run()

website/docs/agents/entities/patterns/manager-worker.md

@@ -27,7 +27,7 @@ export function registerManagerWorker(registry: EntityRegistry) {
 
       ctx.useAgent({
         systemPrompt: MANAGER_SYSTEM_PROMPT,
-        model: `claude-sonnet-4-5-20250929`,
+        model: `claude-sonnet-4-6`,
         tools: [...ctx.electricTools, analyzeTool],
       })
       await ctx.agent.run()
@@ -92,10 +92,15 @@ Do not wait for worker output inside the same wake. Spawn workers with `wake: {
 ```ts
 const finished = wake.payload?.finished_child
 if (finished) {
-  ctx.state.workers.update(finished.url, (draft) => {
-    draft.status = finished.run_status
-    draft.output = finished.response ?? ""
-  })
+  const child = ctx.state.children.toArray.find(
+    (entry) => entry.url === finished.url
+  )
+  if (child) {
+    ctx.state.children.update(child.key, (draft) => {
+      draft.status = finished.run_status
+      draft.output = finished.response ?? ""
+    })
+  }
 }
 ```
 

website/docs/agents/entities/patterns/map-reduce.md

@@ -25,7 +25,7 @@ export function registerMapReduce(registry: EntityRegistry) {
     async handler(ctx) {
       ctx.useAgent({
         systemPrompt: MAP_REDUCE_SYSTEM_PROMPT,
-        model: `claude-sonnet-4-5-20250929`,
+        model: `claude-sonnet-4-6`,
         tools: [...ctx.electricTools, createMapChunksTool(ctx)],
       })
       await ctx.agent.run()

website/docs/agents/entities/patterns/pipeline.md

@@ -25,7 +25,7 @@ export function registerPipeline(registry: EntityRegistry) {
     async handler(ctx) {
       ctx.useAgent({
         systemPrompt: PIPELINE_SYSTEM_PROMPT,
-        model: `claude-sonnet-4-5-20250929`,
+        model: `claude-sonnet-4-6`,
         tools: [...ctx.electricTools, createRunStageTool(ctx)],
       })
       await ctx.agent.run()

website/docs/agents/entities/patterns/reactive-observers.md

@@ -50,7 +50,7 @@ export function registerMonitor(registry: EntityRegistry) {
 
       ctx.useAgent({
         systemPrompt: MONITOR_SYSTEM_PROMPT,
-        model: `claude-sonnet-4-5-20250929`,
+        model: `claude-sonnet-4-6`,
         tools: [...ctx.electricTools, observeTool],
       })
       await ctx.agent.run()

website/docs/agents/index.md

@@ -44,7 +44,7 @@ The runtime SDK is a layer over three foundations:
 - **[TanStack DB](https://tanstack.com/db)** — typed local reads and writes via collections.
 - **Mario Zechner's [pi](https://github.com/badlogic/pi-mono) toolkit** — `pi-ai` (unified multi-provider LLM API) and `pi-agent-core` (agent runtime) for the LLM agent loop.
 
-**One stream per entity.** The runtime projects that stream into a typed local DB of collections — an `EntityStreamDB`. Inside a handler, that DB is `ctx.db`: writes go through `ctx.db.actions` (which append events to the stream), reads come from `ctx.db.collections`. The runtime ships [built-in collections](#built-in-collections) for runs, tool calls, text deltas, errors, inbox, and more, and you add your own typed [state](#state) collections per entity type.
+**One stream per entity.** The runtime projects that stream into a typed local DB of collections — an `EntityStreamDB`. Inside a handler, that DB is `ctx.db`: writes go through `ctx.db.actions` (which append events to the stream), reads come from `ctx.db.collections`. The runtime ships [built-in collections](#built-in-collections) for runs, tool calls, text deltas, errors, inbox, and more, and you add your own typed [state](/docs/agents/usage/managing-state) collections per entity type.
 
 **Inside a handler.** When a handler calls `ctx.useAgent()`, the runtime configures the agent on its behalf and routes every step — model call, text delta, tool invocation, error — through the same projection, so the agent loop becomes durable events on the entity's stream.
 
@@ -75,7 +75,7 @@ registry.define("support", {
     if (wake.type === "inbox") {
       ctx.useAgent({
         systemPrompt: "You are a support agent.",
-        model: "claude-sonnet-4-5-20250929",
+        model: "claude-sonnet-4-6",
         tools: [...ctx.electricTools, searchKbTool],
       })
       await ctx.agent.run()
@@ -110,7 +110,7 @@ The core pattern is [`ctx.useAgent()`](/docs/agents/reference/agent-config) foll
 ```ts
 ctx.useAgent({
   systemPrompt: "You are a helpful assistant.",
-  model: "claude-sonnet-4-5-20250929",
+  model: "claude-sonnet-4-6",
   tools: [...ctx.electricTools, myCustomTool],
 })
 
@@ -228,5 +228,7 @@ See [Managing state](/docs/agents/usage/managing-state) for more information.
 - [Writing handlers](/docs/agents/usage/writing-handlers) — handler lifecycle and the `ctx` API.
 - [Configuring the agent](/docs/agents/usage/configuring-the-agent) — `useAgent`, models, tools, and streaming.
 - [Spawning & coordinating](/docs/agents/usage/spawning-and-coordinating) — multi-entity topologies and shared state.
-- [Built-in agents](/docs/agents/entities/agents/horton) — Horton, Worker, and Coder, the agents that ship with the runtime.
+- [Permissions & principals](/docs/agents/usage/permissions-and-principals) — entity access control and principal-scoped clients.
+- [Sandboxing](/docs/agents/usage/sandboxing), [Attachments](/docs/agents/usage/attachments), [Signals](/docs/agents/usage/signals), and [Webhook sources](/docs/agents/usage/webhook-sources) — newer runtime capabilities for hosted agents.
+- [Built-in agents](/docs/agents/entities/agents/horton) — Horton and Worker, the agents that ship with the runtime.
 - [Examples](/docs/agents/examples/playground) — pattern walkthroughs and demo apps.