docs: refresh agents documentation

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: 'Event sources', link: '/docs/agents/usage/event-sources' },
       { text: 'MCP servers', link: '/docs/agents/usage/mcp-servers' },
       { text: 'Testing', link: '/docs/agents/usage/testing' },
     ],

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

@@ -32,25 +32,25 @@ Horton is configured with `ctx.electricTools` plus the base Horton tool set:
 | `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.                     |
+| `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.             |
 
-`brave_search` requires `BRAVE_SEARCH_API_KEY` in the environment; without it the tool errors at call time.
+`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.
 
 ## 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   |

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

@@ -40,9 +40,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 +58,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 +76,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 +97,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()

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

@@ -63,7 +63,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()
@@ -124,7 +124,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],
 })
 
@@ -206,5 +206,7 @@ console.log(db.collections.texts.toArray)
 - [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 [Event sources](/docs/agents/usage/event-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.

website/docs/agents/quickstart.md

@@ -112,7 +112,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()
@@ -198,4 +198,4 @@ See the [CLI reference](./reference/cli#start) for the full set of commands.
 - [Defining entities](./usage/defining-entities) — entity types, schemas, and configuration.
 - [Writing handlers](./usage/writing-handlers) — handler lifecycle and the `ctx` API.
 - [Configuring the agent](./usage/configuring-the-agent) — `useAgent`, models, tools, and streaming.
-- [Built-in agents](./entities/agents/horton) — Horton, Worker, and Coder, the agents that ship with the runtime.
+- [Built-in agents](./entities/agents/horton) — Horton and Worker, the agents that ship with the runtime.

website/docs/agents/reference/agent-config.md

@@ -32,7 +32,7 @@ interface AgentConfig {
 | Field           | Type                         | Required | Description                                                                                         |
 | --------------- | ---------------------------- | -------- | --------------------------------------------------------------------------------------------------- |
 | `systemPrompt`  | `string`                     | Yes      | System prompt sent to the LLM on each step.                                                         |
-| `model`         | `string \| Model<any>`       | Yes      | Model identifier (e.g. `"claude-sonnet-4-5-20250929"`) or a resolved model object.                  |
+| `model`         | `string \| Model<any>`       | Yes      | Model identifier (e.g. `"claude-sonnet-4-6"`) or a resolved model object.                  |
 | `provider`      | `KnownProvider`              | No       | Provider to use when `model` is a string. Defaults to `"anthropic"`.                                |
 | `tools`         | `AgentTool[]`                | Yes      | Tools available to the LLM. Spread `ctx.electricTools` when your runtime host provides runtime-level tools. See [`AgentTool`](./agent-tool). |
 | `streamFn`      | `StreamFn`                   | No       | Optional streaming callback passed to the underlying agent.                                         |

website/docs/agents/reference/built-in-collections.md

@@ -2,13 +2,13 @@
 title: Built-in collections
 titleTemplate: "... - Electric Agents"
 description: >-
-  Reference for the 17 runtime-managed collections: runs, steps, texts, toolCalls, inbox, errors, and more.
+  Reference for the 18 runtime-managed collections: runs, steps, texts, toolCalls, inbox, signals, errors, and more.
 outline: [2, 3]
 ---
 
 # Built-in collections
 
-Every entity automatically has these 17 collections, populated by the runtime as the agent operates. Custom state collections defined in `EntityDefinition.state` are merged with these at creation time.
+Every entity automatically has these 18 collections, populated by the runtime as the agent operates. Custom state collections defined in `EntityDefinition.state` are merged with these at creation time.
 
 **Source:** `@electric-ax/agents-runtime` -- `entity-schema.ts`
 
@@ -27,14 +27,15 @@ Every entity automatically has these 17 collections, populated by the runtime as
 | `wakes`            | `wake`             | `WakeEntry`        | Wake delivery records        |
 | `entityCreated`    | `entity_created`   | `EntityCreated`    | Entity bootstrap metadata    |
 | `entityStopped`    | `entity_stopped`   | `EntityStopped`    | Entity shutdown signal       |
+| `signals`          | `signal`           | `Signal`           | Lifecycle signal records     |
 | `childStatus`      | `child_status`     | `ChildStatusEntry` | Child/observed entity status |
 | `tags`             | `tags`             | `TagEntry`         | Entity tags                  |
+| `manifests`        | `manifest`         | `Manifest`         | Durable resource manifests   |
 | `contextInserted`  | `context_inserted` | `ContextInserted`  | Context additions            |
 | `contextRemoved`   | `context_removed`  | `ContextRemoved`   | Context removals             |
-| `manifests`        | `manifest`         | `Manifest`         | Durable resource manifests   |
 | `replayWatermarks` | `replay_watermark` | `ReplayWatermark`  | Replay progress tracking     |
 
-All collections use `key` as the primary key.
+All collections use `key` as the primary key. Runtime-managed timeline rows may also include `_timeline_order` for stable timeline sorting.
 
 ## Type definitions
 
@@ -90,6 +91,7 @@ interface TextDelta {
 interface ToolCall {
   key: string
   run_id?: string
+  tool_call_id?: string
   tool_name: string
   status: "started" | "args_complete" | "executing" | "completed" | "failed"
   args?: unknown
@@ -126,10 +128,15 @@ interface ErrorEvent {
 ```ts
 interface MessageReceived {
   key: string
-  from: string
+  from?: string
   payload?: unknown
-  timestamp: string
+  timestamp?: string
   message_type?: string
+  mode?: "immediate" | "queued" | "paused" | "steer"
+  status?: "pending" | "processed" | "cancelled"
+  position?: string
+  processed_at?: string
+  cancelled_at?: string
 }
 ```
 
@@ -150,6 +157,10 @@ interface WakeChangeEntry {
   collection: string
   kind: "insert" | "update" | "delete"
   key: string
+  from?: string
+  payload?: unknown
+  timestamp?: string
+  message_type?: string
 }
 
 interface WakeFinishedChildEntry {
@@ -163,7 +174,7 @@ interface WakeFinishedChildEntry {
 interface WakeOtherChildEntry {
   url: string
   type: string
-  status: "spawning" | "running" | "idle" | "stopped"
+  status: "spawning" | "running" | "idle" | "paused" | "stopping" | "stopped" | "killed"
 }
 ```
 
@@ -189,14 +200,33 @@ interface EntityStopped {
 }
 ```
 
+### Signal
+
+```ts
+interface Signal {
+  key: string
+  signal: "SIGINT" | "SIGHUP" | "SIGTERM" | "SIGKILL" | "SIGSTOP" | "SIGCONT" | "SIGUSR"
+  status: "unhandled" | "handled"
+  sender?: string
+  reason?: string
+  payload?: unknown
+  timestamp: string
+  handled_at?: string
+  handled_by?: string
+  outcome?: "transitioned" | "ignored" | "invalid_for_state" | "delivered" | "aborted" | "shutdown_requested" | "failed"
+  previous_state?: ChildStatusEntry["status"]
+  new_state?: ChildStatusEntry["status"]
+}
+```
+
 ### ChildStatusEntry
 
 ```ts
 interface ChildStatusEntry {
   key: string
   entity_url: string
   entity_type: string
-  status: "spawning" | "running" | "idle" | "stopped"
+  status: "spawning" | "running" | "idle" | "paused" | "stopping" | "stopped" | "killed"
 }
 ```
 
@@ -243,6 +273,7 @@ type Manifest =
   | ManifestSourceEntry
   | ManifestSharedStateEntry
   | ManifestEffectEntry
+  | ManifestAttachmentEntry
   | ManifestContextEntry
   | ManifestCronScheduleEntry
   | ManifestFutureSendScheduleEntry
@@ -283,6 +314,27 @@ interface ManifestEffectEntry {
   config: unknown
 }
 
+interface ManifestAttachmentEntry {
+  key: string
+  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>
+}
+
 interface ManifestContextEntry {
   key: string
   kind: "context"