@electric-ax/agents 0.4.19 → 0.6.0

package/docs/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,
       ],
     })

package/docs/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).` |

package/docs/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()

package/docs/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()

package/docs/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 ?? ""
+    })
+  }
 }
 ```
 

package/docs/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()

package/docs/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()

package/docs/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()

package/docs/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.

package/docs/quickstart.md

@@ -121,7 +121,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()
@@ -202,4 +202,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.

package/docs/reference/agent-config.md

@@ -16,13 +16,20 @@ Configuration for the LLM agent loop. Passed to `ctx.useAgent()`.
 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
 }
 ```
@@ -32,12 +39,15 @@ 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.                  |
-| `provider`      | `KnownProvider`              | No       | Provider to use when `model` is a string. Defaults to `"anthropic"`.                                |
+| `model`         | `string \| Model<any>`       | Yes      | Model identifier (e.g. `"claude-sonnet-4-6"`) or a resolved model object.                  |
+| `provider`      | `Provider`                   | No       | pi-ai 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.                                         |
 | `getApiKey`     | `(provider) => string \| Promise<string> \| undefined` | No | Optional API-key resolver passed through to the model layer. |
 | `onPayload`     | `SimpleStreamOptions["onPayload"]` | No | Optional callback for raw streaming payloads from the model layer. |
+| `onStepEnd`     | `(stats) => void`            | No       | Callback after each model step with provider-reported token counts.                                 |
+| `modelTimeoutMs` | `number`                    | No       | Timeout for individual model calls, in milliseconds.                                                |
+| `modelMaxRetries` | `number`                   | No       | Maximum retry count for model calls.                                                               |
 | `testResponses` | `string[] \| TestResponseFn` | No       | Mock LLM responses for testing. When set, no real LLM calls are made.                               |
 
 ## TestResponseFn

package/docs/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 20 runtime-managed collections: runs, steps, texts, toolCalls, inbox, signals, errors, slashCommands, 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 20 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`
 
@@ -22,19 +22,22 @@ Every entity automatically has these 17 collections, populated by the runtime as
 | `textDeltas`       | `text_delta`       | `TextDelta`        | Incremental text content     |
 | `toolCalls`        | `tool_call`        | `ToolCall`         | Tool call lifecycle          |
 | `reasoning`        | `reasoning`        | `Reasoning`        | Reasoning block lifecycle    |
+| `reasoningDeltas`  | `reasoning_delta`  | `ReasoningDelta`   | Incremental reasoning content |
 | `errors`           | `error`            | `ErrorEvent`       | Diagnostic errors            |
 | `inbox`            | `inbox` | `MessageReceived`  | Inbound messages             |
 | `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                  |
+| `slashCommands`    | `slash_command`    | `SlashCommandEntry` | Composer slash commands      |
+| `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
 
@@ -60,6 +63,8 @@ interface Step {
   model_provider?: string
   model_id?: string
   duration_ms?: number
+  input_tokens?: number
+  output_tokens?: number
 }
 ```
 
@@ -90,6 +95,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
@@ -104,7 +110,21 @@ interface ToolCall {
 ```ts
 interface Reasoning {
   key: string
+  run_id?: string
   status: "streaming" | "completed"
+  encrypted?: string
+  summary_title?: string
+}
+```
+
+### ReasoningDelta
+
+```ts
+interface ReasoningDelta {
+  key: string
+  reasoning_id: string
+  run_id: string
+  delta: string
 }
 ```
 
@@ -126,10 +146,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 +175,10 @@ interface WakeChangeEntry {
   collection: string
   kind: "insert" | "update" | "delete"
   key: string
+  from?: string
+  payload?: unknown
+  timestamp?: string
+  message_type?: string
 }
 
 interface WakeFinishedChildEntry {
@@ -163,7 +192,7 @@ interface WakeFinishedChildEntry {
 interface WakeOtherChildEntry {
   url: string
   type: string
-  status: "spawning" | "running" | "idle" | "stopped"
+  status: "spawning" | "running" | "idle" | "paused" | "stopping" | "stopped" | "killed"
 }
 ```
 
@@ -189,6 +218,25 @@ 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
@@ -196,7 +244,7 @@ interface ChildStatusEntry {
   key: string
   entity_url: string
   entity_type: string
-  status: "spawning" | "running" | "idle" | "stopped"
+  status: "spawning" | "running" | "idle" | "paused" | "stopping" | "stopped" | "killed"
 }
 ```
 
@@ -209,6 +257,39 @@ interface TagEntry {
 }
 ```
 
+### SlashCommandEntry
+
+```ts
+interface SlashCommandEntry {
+  key: string
+  name: string
+  description?: string
+  arguments?: Array<{
+    name: string
+    type: "string" | "number" | "boolean"
+    required?: boolean
+    description?: string
+  }>
+  source: "static" | "dynamic"
+  owner?: string
+  version?: string
+  updated_at: string
+  dynamic_layers?: Array<{
+    name: string
+    description?: string
+    arguments?: Array<{
+      name: string
+      type: "string" | "number" | "boolean"
+      required?: boolean
+      description?: string
+    }>
+    owner?: string
+    version?: string
+    updated_at: string
+  }>
+}
+```
+
 ### ContextInserted
 
 ```ts
@@ -243,9 +324,11 @@ type Manifest =
   | ManifestSourceEntry
   | ManifestSharedStateEntry
   | ManifestEffectEntry
+  | ManifestAttachmentEntry
   | ManifestContextEntry
   | ManifestCronScheduleEntry
   | ManifestFutureSendScheduleEntry
+  | ManifestGoalEntry
 
 interface ManifestChildEntry {
   key: string
@@ -260,7 +343,7 @@ interface ManifestChildEntry {
 interface ManifestSourceEntry {
   key: string
   kind: "source"
-  sourceType: string
+  sourceType: "entity" | "cron" | "entities" | "db" | "webhook" | "pgSync" | string
   sourceRef: string
   wake?: WakeConfig
   config: Record<string, unknown>
@@ -283,6 +366,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"
@@ -320,8 +424,23 @@ interface ManifestFutureSendScheduleEntry {
   failedAt?: string
   lastError?: string
 }
+
+interface ManifestGoalEntry {
+  key: string
+  kind: "goal"
+  id: string
+  objective: string
+  status: "active" | "complete" | "budget_limited"
+  tokenBudget: number | null
+  tokensUsed: number
+  summary?: string
+  createdAt: string
+  updatedAt: string
+}
 ```
 
+`pgSync()` observations are stored as `sourceType: "pgSync"` manifest rows and project matching Postgres shape changes into the observed source's `changes` collection.
+
 ### ReplayWatermark
 
 ```ts

package/docs/reference/cli.md

@@ -23,7 +23,8 @@ npm install -g electric-ax
 | `ELECTRIC_AGENTS_PRINCIPAL`      | -                       | Optional principal key sent as `Electric-Principal` |
 | `ELECTRIC_AGENTS_SERVER_HEADERS` | -                       | Optional JSON object of additional server headers |
 | `ELECTRIC_AGENTS_PORT`           | `4437`                  | Port used by `start` / `quickstart`          |
-| `ELECTRIC_AGENTS_BUILTIN_PORT`   | `4448`                  | Webhook port for `start-builtin`             |
+| `ELECTRIC_AGENTS_PULL_WAKE_RUNNER_ID` | `builtin-{identity}` | Pull-wake runner id for `start-builtin`      |
+| `PULL_WAKE_RUNNER_ID`            | -                       | Legacy alias for `ELECTRIC_AGENTS_PULL_WAKE_RUNNER_ID` |
 | `ELECTRIC_AGENTS_COMPOSE_PROJECT` | `electric-agents`       | Docker Compose project name                  |
 | `ANTHROPIC_API_KEY`              | -                       | Required for `start-builtin` and `quickstart` |
 
@@ -94,6 +95,19 @@ electric agents observe /chat/my-convo --from 0
 | ----------------- | -------------------------------- |
 | `--from <offset>` | Start streaming from this offset |
 
+### <span class="cli-command"><code>view &lt;url&gt; [--from &lt;offset&gt;]</code></span> {#view-url-from-offset}
+
+Print an entity conversation once.
+
+```bash
+electric agents view /chat/my-convo
+electric agents view /chat/my-convo --from 0
+```
+
+| Option            | Description                 |
+| ----------------- | --------------------------- |
+| `--from <offset>` | Start reading from this offset |
+
 ### <span class="cli-command"><code>inspect &lt;url&gt;</code></span> {#inspect-url}
 
 Show entity details. Outputs JSON.
@@ -120,9 +134,23 @@ electric agents ps --parent /manager/my-manager
 
 Output shows `URL`, `STATUS`, `CREATED`, and `LAST ACTIVE` columns with human-readable relative timestamps. Results are sorted by most recently active first.
 
+### <span class="cli-command"><code>signal &lt;url&gt; &lt;signal&gt; [--reason &lt;text&gt;] [--payload &lt;json&gt;]</code></span> {#signal-url-signal}
+
+Send a lifecycle signal to an entity.
+
+```bash
+electric agents signal /chat/my-convo SIGINT --reason "stop current run"
+electric agents signal /chat/my-convo SIGUSR --payload '{"refresh":true}'
+```
+
+| Option             | Description                         |
+| ------------------ | ----------------------------------- |
+| `--reason <text>`  | Human-readable signal reason        |
+| `--payload <json>` | JSON payload to attach to the signal |
+
 ### <span class="cli-command"><code>kill &lt;url&gt;</code></span> {#kill-url}
 
-Delete an entity.
+Send `SIGKILL` to an entity.
 
 ```bash
 electric agents kill /chat/my-convo
@@ -138,7 +166,7 @@ electric agents start
 
 ### <span class="cli-command"><code>start-builtin [--anthropic-api-key &lt;key&gt;]</code></span> {#start-builtin}
 
-Start the built-in Horton runtime and register built-in agent types with the coordinator server.
+Start the built-in Horton and worker runtime, register built-in agent types, and run a pull-wake runner.
 
 ```bash
 electric agents start-builtin --anthropic-api-key sk-ant-...
@@ -216,8 +244,10 @@ import {
 } from "electric-ax"
 
 const env = getElectricCliEnv({
+  ...process.env,
   ELECTRIC_AGENTS_URL: "http://localhost:4437",
   ELECTRIC_AGENTS_IDENTITY: "docs@example.com",
+  ELECTRIC_AGENTS_PRINCIPAL: "user:docs@example.com",
 })
 
 const handlers = createElectricCliHandlers(env, "electric agents")
@@ -234,7 +264,7 @@ await program.parseAsync(["node", "electric", "agents", "types"])
 | Export                            | Purpose                                                                  |
 | --------------------------------- | ------------------------------------------------------------------------ |
 | `DEFAULT_ELECTRIC_AGENTS_URL`     | Default server URL (`"http://localhost:4437"`).                          |
-| `getElectricCliEnv(env?)`         | Reads `ELECTRIC_AGENTS_URL` and `ELECTRIC_AGENTS_IDENTITY`.              |
+| `getElectricCliEnv(env?)`         | Reads `ELECTRIC_AGENTS_URL`, `ELECTRIC_AGENTS_IDENTITY`, `ELECTRIC_AGENTS_PRINCIPAL`, and `ELECTRIC_AGENTS_SERVER_HEADERS`. |
 | `createElectricCliHandlers()`     | Creates the default command handlers.                                    |
 | `createElectricProgram()`         | Creates the Commander program.                                           |
 | `resolveCommandPrefix(argv, env?)` | Resolves help text examples for direct or package-manager invocation.    |