@electric-ax/agents 0.4.18 → 0.6.0

package/docs/reference/entity-definition.md

@@ -21,7 +21,9 @@ interface EntityDefinition {
   ) => Record<string, (...args: unknown[]) => void>
   creationSchema?: StandardJSONSchemaV1
   inboxSchemas?: Record<string, StandardJSONSchemaV1>
-  outputSchemas?: Record<string, StandardJSONSchemaV1>
+  stateSchemas?: Record<string, StandardJSONSchemaV1>
+  permissionGrants?: EntityTypePermissionGrantDefinition[]
+  slashCommands?: SlashCommandDefinition[]
   handler(ctx: HandlerContext, wake: WakeEvent): void | Promise<void>
 }
 ```
@@ -35,7 +37,9 @@ interface EntityDefinition {
 | `actions`        | `(collections) => Record<string, (...args) => void>` | No       | Factory for custom non-CRUD actions. Receives TanStack DB collections, returns named action functions exposed on `ctx.actions`. |
 | `creationSchema` | `StandardJSONSchemaV1`                               | No       | JSON Schema for spawn arguments validation.                                                                        |
 | `inboxSchemas`   | `Record<string, StandardJSONSchemaV1>`               | No       | JSON Schemas for inbound message types, keyed by message type.                                                     |
-| `outputSchemas`  | `Record<string, StandardJSONSchemaV1>`               | No       | JSON Schemas for output event types. Defaults are provided by the runtime.                                         |
+| `stateSchemas`   | `Record<string, StandardJSONSchemaV1>`               | No       | Additional JSON Schemas included in the registered entity type's state schema map.                                 |
+| `permissionGrants` | `EntityTypePermissionGrantDefinition[]`            | No       | Initial permission grants applied when this entity type is registered.                                             |
+| `slashCommands`  | `SlashCommandDefinition[]`                           | No       | Static slash commands exposed to structured composers and available through `ctx.slashCommands`.                   |
 | `handler`        | `(ctx, wake) => void \| Promise<void>`               | Yes      | The function invoked on each wake. Receives [`HandlerContext`](./handler-context) and [`WakeEvent`](./wake-event). |
 
 ## CollectionDefinition
@@ -47,11 +51,39 @@ interface CollectionDefinition {
   schema?: StandardSchemaV1
   type?: string
   primaryKey?: string
+  externallyWritable?: boolean
+  contract?: string
+  operations?: Array<"insert" | "update" | "delete">
 }
 ```
 
-| Field        | Type               | Default          | Description                                        |
-| ------------ | ------------------ | ---------------- | -------------------------------------------------- |
-| `schema`     | `StandardSchemaV1` | -                | Zod or Standard Schema validator for the row type. |
-| `type`       | `string`           | `"state:{name}"` | Event type string used in the durable stream.      |
-| `primaryKey` | `string`           | `"key"`          | Primary key field name on the row.                 |
+| Field                | Type                                      | Default          | Description                                        |
+| -------------------- | ----------------------------------------- | ---------------- | -------------------------------------------------- |
+| `schema`             | `StandardSchemaV1`                        | -                | Zod or Standard Schema validator for the row type. |
+| `type`               | `string`                                  | `"state:{name}"` | Event type string used in the durable stream.      |
+| `primaryKey`         | `string`                                  | `"key"`          | Primary key field name on the row.                 |
+| `externallyWritable` | `boolean`                                 | `false`          | Opt in to HTTP writes for this collection.         |
+| `contract`           | `string`                                  | -                | Well-known contract implemented by the collection. |
+| `operations`         | `Array<"insert" \| "update" \| "delete">` | `["insert"]` for external writes | Allowlist of external write operations when `externallyWritable` is enabled. |
+
+## Permission grants
+
+`permissionGrants` lets an entity type declare the initial access grants that the server stores for entities of that type.
+
+```ts
+registry.define("worker", {
+  description: "Internal worker agent",
+  permissionGrants: [
+    {
+      subject_kind: "principal_kind",
+      subject_value: "user",
+      permission: "spawn",
+    },
+  ],
+  async handler(ctx, wake) {
+    // ...
+  },
+})
+```
+
+The server currently recognizes `read`, `write`, `delete`, `signal`, `fork`, `schedule`, `spawn`, and `manage` permissions. Grants can target a specific principal or a principal kind, and may include propagation options depending on the server route that creates them.

package/docs/reference/entity-handle.md

@@ -14,6 +14,9 @@ Handle returned by `ctx.spawn()` and `ctx.observe(entity(...))`. It identifies a
 
 ```ts
 interface EntityHandle {
+  sourceType: string
+  sourceRef: string
+  streamUrl?: string
   entityUrl: string
   type?: string
   db: EntityStreamDB
@@ -27,6 +30,9 @@ interface EntityHandle {
 
 | Member      | Type                       | Description                                                     |
 | ----------- | -------------------------- | --------------------------------------------------------------- |
+| `sourceType` | `string`                  | Observation source type inherited from `ObservationHandle`.     |
+| `sourceRef` | `string`                   | Stable source reference inherited from `ObservationHandle`.     |
+| `streamUrl` | `string \| undefined`      | Source stream URL when available.                               |
 | `entityUrl` | `string`                   | URL path of the entity, e.g. `"/worker/child-1"`.              |
 | `type`      | `string \| undefined`      | Entity type name, if known.                                     |
 | `db`        | `EntityStreamDB`           | The entity's TanStack DB instance for querying its collections. |
@@ -50,7 +56,7 @@ const child = await ctx.spawn(
 )
 
 ctx.state.children.insert({
-  key: "analyst-1",
+  key: child.entityUrl,
   url: child.entityUrl,
   status: "running",
 })
@@ -87,3 +93,15 @@ interface ChildStatusEntry {
   status: "spawning" | "running" | "idle" | "paused" | "stopping" | "stopped" | "killed"
 }
 ```
+
+Status values:
+
+| Status     | Description                                                 |
+| ---------- | ----------------------------------------------------------- |
+| `spawning` | Entity creation is in progress.                             |
+| `running`  | Handler is currently executing.                             |
+| `idle`     | Handler has completed; entity is waiting for the next wake. |
+| `paused`   | Entity is paused.                                           |
+| `stopping` | Entity is stopping and rejects normal writes.                |
+| `stopped`  | Entity has been stopped or deleted.                         |
+| `killed`   | Entity was killed by a terminal lifecycle signal.            |

package/docs/reference/handler-context.md

@@ -15,7 +15,10 @@ The handler context is passed as the first argument to every entity handler. It
 ```ts
 interface HandlerContext<TState extends StateProxy = StateProxy> {
   firstWake: boolean
+  wake: HandlerWake
+  slashCommands: SlashCommandHelpers
   tags: Readonly<EntityTags>
+  principal?: RuntimePrincipal
   entityUrl: string
   entityType: string
   args: Readonly<Record<string, unknown>>
@@ -24,6 +27,8 @@ interface HandlerContext<TState extends StateProxy = StateProxy> {
   events: Array<ChangeEvent>
   actions: Record<string, (...args: unknown[]) => unknown>
   electricTools: AgentTool[]
+  signal: AbortSignal
+  sandbox: Sandbox
   useAgent(config: AgentConfig): AgentHandle
   useContext(config: UseContextConfig): void
   timelineMessages(opts?: TimelineProjectionOpts): Array<TimestampedMessage>
@@ -31,6 +36,14 @@ interface HandlerContext<TState extends StateProxy = StateProxy> {
   removeContext(id: string): void
   getContext(id: string): ContextEntry | undefined
   listContext(): Array<ContextEntry>
+  setGoal(input: GoalInput): GoalEntry
+  clearGoal(): boolean
+  getGoal(): GoalEntry | undefined
+  markGoalComplete(summary?: string): GoalEntry | undefined
+  updateGoalUsage(
+    tokensUsed: number,
+    opts?: { status?: GoalEntry["status"] }
+  ): GoalEntry | undefined
   agent: AgentHandle
   spawn(
     type: string,
@@ -38,11 +51,19 @@ interface HandlerContext<TState extends StateProxy = StateProxy> {
     args?: Record<string, unknown>,
     opts?: {
       initialMessage?: unknown
+      initialMessageType?: string
       wake?: Wake
       tags?: Record<string, string>
       observe?: boolean
+      sandbox?: SpawnSandboxOption
     }
   ): Promise<EntityHandle>
+  fork(
+    sourceEntityUrl: string,
+    id: string,
+    opts?: ForkOptions
+  ): Promise<EntityHandle>
+  forkSelf(id: string, opts?: ForkOptions): Promise<EntityHandle>
   observe(
     source: ObservationSource & { sourceType: "entity" },
     opts?: { wake?: Wake }
@@ -55,6 +76,7 @@ interface HandlerContext<TState extends StateProxy = StateProxy> {
     source: ObservationSource,
     opts?: { wake?: Wake }
   ): Promise<ObservationHandle>
+  unobserve(sourceRef: string): Promise<void>
   mkdb<T extends SharedStateSchemaMap>(
     id: string,
     schema: T
@@ -63,22 +85,34 @@ interface HandlerContext<TState extends StateProxy = StateProxy> {
     entityUrl: string,
     payload: unknown,
     opts?: { type?: string; afterMs?: number }
+  ): Promise<SendResult>
+  attachments: AttachmentsApi
+  onSignal(
+    handler: (signal: {
+      signal: EntitySignal
+      reason?: string
+      payload?: unknown
+    }) => void | Promise<void>
   ): void
   recordRun(): RunHandle
+  replyText(text: string): void
   setTag(key: string, value: string): Promise<void>
-  removeTag(key: string): Promise<void>
+  deleteTag(key: string): Promise<void>
   sleep(): void
 }
 ```
 
-> **Tip:** Use the helper functions `entity()`, `cron()`, `entities()`, and `db()` from `@electric-ax/agents-runtime` to construct `ObservationSource` values for `observe()`.
+> **Tip:** Use the helper functions `entity()`, `cron()`, `entities()`, `db()`, `webhook()`, and `pgSync()` from `@electric-ax/agents-runtime` to construct `ObservationSource` values for `observe()`.
 
 ## Properties
 
 | Property     | Type                                              | Description                                                                                                   |
 | ------------ | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
 | `firstWake`  | `boolean`                                         | `true` during the initial setup pass while the entity has no persisted manifest entries. Use state checks for one-time plain state initialization. |
+| `wake`       | `HandlerWake`                                     | Current wake projected into the handler context. Equivalent to the second handler argument.                    |
+| `slashCommands` | `SlashCommandHelpers`                         | Read and manage slash-command definitions exposed to structured composer inputs.                              |
 | `tags`       | `Readonly<EntityTags>`                            | Entity tags — key/value metadata associated with this entity.                                                 |
+| `principal`  | `RuntimePrincipal \| undefined`                   | Principal that caused the current wake, when the server supplied one.                                         |
 | `entityUrl`  | `string`                                          | URL path of this entity (e.g. `"/chat/my-convo"`).                                                            |
 | `entityType` | `string`                                          | Registered type name (e.g. `"chat"`).                                                                         |
 | `args`       | `Readonly<Record<string, unknown>>`               | Spawn arguments passed when the entity was created.                                                           |
@@ -87,6 +121,30 @@ interface HandlerContext<TState extends StateProxy = StateProxy> {
 | `events`     | `Array<ChangeEvent>`                              | Change events that triggered this wake.                                                                       |
 | `actions`    | `Record<string, (...args: unknown[]) => unknown>` | Custom non-CRUD actions from the entity definition's `actions` factory. Auto-generated CRUD actions live on `ctx.db.actions` and `ctx.state`. |
 | `electricTools` | `AgentTool[]`                                     | Host-provided runtime-level tools to spread into agent config when needed. May be empty.                     |
+| `signal`     | `AbortSignal`                                     | Aborts when the current wake should stop early, such as during shutdown or `SIGINT`. Pass it to cancellable work. |
+| `sandbox`    | `Sandbox`                                         | Active sandbox for this wake session. Runtime-provided tools use this for filesystem, process, and network access. |
+| `attachments` | `AttachmentsApi`                                 | Read and create manifest-backed attachments for this entity.                                                  |
+
+## HandlerWake
+
+`ctx.wake` is a normalized convenience view of the raw `WakeEvent` passed as the handler's second argument:
+
+```ts
+type HandlerWake =
+  | {
+      type: "inbox"
+      source: string
+      message: { type: string; payload: unknown; from?: string }
+      raw: WakeEvent
+    }
+  | {
+      type: "other"
+      wakeType: string
+      source: string
+      payload?: unknown
+      raw: WakeEvent
+    }
+```
 
 ## Methods
 
@@ -99,16 +157,83 @@ interface HandlerContext<TState extends StateProxy = StateProxy> {
 | `removeContext(id)`               | `void`                                                            | Remove a context entry by id.                                                                                                                                                                                                              |
 | `getContext(id)`                  | `ContextEntry \| undefined`                                       | Get a context entry by id, or `undefined` if not found.                                                                                                                                                                                    |
 | `listContext()`                   | `Array<ContextEntry>`                                             | List all context entries.                                                                                                                                                                                                                  |
+| `setGoal(input)`                  | `GoalEntry`                                                       | Set or replace the active goal for this entity.                                                                                                                        |
+| `clearGoal()`                     | `boolean`                                                         | Clear the active goal. Returns whether a goal was removed.                                                                                                             |
+| `getGoal()`                       | `GoalEntry \| undefined`                                          | Read the active goal, if one exists.                                                                                                                                    |
+| `markGoalComplete(summary?)`      | `GoalEntry \| undefined`                                          | Mark the active goal complete, optionally recording a summary.                                                                                                        |
+| `updateGoalUsage(tokens, opts?)`  | `GoalEntry \| undefined`                                          | Add token usage to the active goal and optionally update its status.                                                                                                  |
 | `agent.run(input?)`               | `Promise<AgentRunResult>`                                         | Run the configured agent loop. Optional `input` string is appended as a user message before the loop starts.                                                                                                                               |
-| `spawn(type, id, args?, opts?)`   | `Promise<EntityHandle>`                                           | Spawn a child entity. `opts` accepts `tags`, `observe`, `initialMessage`, and `wake`. See [`EntityHandle`](./entity-handle).                                                                                                               |
+| `spawn(type, id, args?, opts?)`   | `Promise<EntityHandle>`                                           | Spawn a child entity. `opts` accepts `tags`, `observe`, `initialMessage`, `initialMessageType`, `wake`, and `sandbox`. See [`EntityHandle`](./entity-handle).                                                                                                    |
+| `fork(sourceUrl, id, opts?)`      | `Promise<EntityHandle>`                                           | Fork another entity at its latest completed run. By default the fork becomes this entity's child and wakes this entity when the fork's next run finishes.                                                                                   |
+| `forkSelf(id, opts?)`             | `Promise<EntityHandle>`                                           | Convenience wrapper for `ctx.fork(ctx.entityUrl, id, opts)`.                                                                                                                                                                               |
 | `observe(source, opts?)`          | `Promise<EntityHandle \| SharedStateHandle \| ObservationHandle>` | Observe a source. Return type depends on source type: `EntityHandle` for entities, `SharedStateHandle & ObservationHandle` for db, `ObservationHandle` otherwise. Use `entity()`, `cron()`, `entities()`, `db()` helpers to build sources. |
+| `unobserve(sourceRef)`            | `Promise<void>`                                                   | Stop this entity from observing a pg-sync source by source reference.                                                                                                                            |
 | `mkdb(id, schema)`                | `SharedStateHandle<T>`                                            | Create a new shared state stream. See [`SharedStateHandle`](./shared-state-handle).                                                                                                                                                        |
-| `send(entityUrl, payload, opts?)` | `void`                                                            | Send a message to another entity. `opts` accepts `type` and `afterMs` (delay in milliseconds).                                                                                                                                             |
+| `send(entityUrl, payload, opts?)` | `Promise<SendResult>`                                             | Send a message to another entity. `opts` accepts `type` and `afterMs` (delay in milliseconds).                                                                                                                                             |
+| `onSignal(handler)`               | `void`                                                            | Register a handler for lifecycle signals delivered during this wake. Runtime-controlled signals such as `SIGINT`, `SIGSTOP`, `SIGCONT`, and `SIGKILL` are handled by the runtime.                                                         |
 | `recordRun()`                     | `RunHandle`                                                       | Record a non-LLM run in the built-in `runs` collection, so observers using `wake: { on: "runFinished", includeResponse: true }` are notified when external work completes.                                                                                               |
+| `replyText(text)`                 | `void`                                                            | Write a synthetic assistant text reply without invoking the LLM. Emits the same run/text rows used by chat UIs.                                                                                               |
 | `setTag(key, value)`              | `Promise<void>`                                                   | Set a tag on this entity.                                                                                                                                                                                                                  |
-| `removeTag(key)`                  | `Promise<void>`                                                   | Remove a tag from this entity.                                                                                                                                                                                                             |
+| `deleteTag(key)`                  | `Promise<void>`                                                   | Delete a tag from this entity.                                                                                                                                                                                                             |
 | `sleep()`                         | `void`                                                            | End the handler without running an agent. The entity remains idle until the next wake.                                                                                                                                                     |
 
+## Sandbox
+
+`ctx.sandbox` is selected from the entity's sandbox profile at wake-session start. The runtime owns disposal; handlers should not call `sandbox.dispose()` directly. Use it when writing custom tools that need filesystem, subprocess, or network access so the behavior follows the active sandbox profile.
+
+Spawned children can inherit or select a sandbox:
+
+```ts
+await ctx.spawn("worker", "analysis", args, {
+  sandbox: "inherit",
+  initialMessage: "Review the current workspace.",
+})
+```
+
+## Forking
+
+`ctx.fork(sourceEntityUrl, id, opts?)` creates a child fork of another entity at that source entity's latest completed run. `ctx.forkSelf(id, opts?)` forks the current entity. Options mirror spawn where the semantics map:
+
+```ts
+const fork = await ctx.forkSelf("variant-a", {
+  initialMessage: { text: "Try a different approach." },
+  tags: { branch: "variant-a" },
+})
+```
+
+By default the fork is observed as this entity's child with a `runFinished` wake that includes the fork response. Pass `observe: false` for a fire-and-forget fork with no parent manifest entry, wake subscription, or reply path.
+
+## Attachments
+
+`ctx.attachments` exposes manifest-backed attachments associated with the entity. It is used by the runtime to hydrate image and file context and can also be used by custom handlers or tools that need to inspect uploaded files.
+
+## Slash Commands
+
+`ctx.slashCommands` exposes structured composer commands registered on the entity. Static commands come from the entity type; handlers can add or replace dynamic commands for UI composers that send `composer_input` messages:
+
+```ts
+ctx.slashCommands.register({
+  name: "summarize",
+  description: "Summarize the current session",
+})
+```
+
+Use `ctx.wake` or the handler's `wake` argument to inspect incoming composer payloads.
+
+## Lifecycle Signals
+
+Use `ctx.signal` for cancellable work and `ctx.onSignal()` for handler-delivered lifecycle signals:
+
+```ts
+ctx.onSignal(async ({ signal, reason }) => {
+  if (signal === "SIGTERM") {
+    await cleanup(reason)
+  }
+})
+```
+
+`SIGINT` aborts the active handler invocation through `ctx.signal`. `SIGSTOP`, `SIGCONT`, and `SIGKILL` are runtime-controlled.
+
 ## RunHandle
 
 `recordRun()` is for handlers that perform work outside `ctx.agent.run()` but still want to expose run lifecycle events.

package/docs/reference/runtime-handler.md

@@ -18,12 +18,22 @@ Factory functions that create the runtime request router and Node HTTP adapter.
 interface RuntimeRouter {
   handleRequest(request: Request): Promise<Response | null>
   handleWebhookRequest(request: Request): Promise<Response>
+  dispatchWake(
+    notification: WakeNotification,
+    options?: Pick<ProcessWakeConfig, "claimHeaders" | "claimTokenHeader">
+  ): void
   dispatchWebhookWake(notification: WebhookNotification): void
   drainWakes(): Promise<void>
   waitForSettled(): Promise<void>
   abortWakes(): void
   debugState(): RuntimeDebugState
   readonly typeNames: string[]
+  readonly sandboxProfileDescriptors: Array<{
+    name: string
+    label: string
+    description?: string
+    remote?: boolean
+  }>
   registerTypes(): Promise<void>
 }
 ```
@@ -32,12 +42,14 @@ interface RuntimeRouter {
 | ----------------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------- |
 | `handleRequest(request)`            | `Promise<Response \| null>` | Route a fetch `Request`. Returns `null` if the request path does not match `webhookPath`.               |
 | `handleWebhookRequest(request)`     | `Promise<Response>`         | Handle a webhook request directly, without route matching.                                              |
+| `dispatchWake(notification, opts?)` | `void`                      | Dispatch an already-parsed wake notification from any transport.                                        |
 | `dispatchWebhookWake(notification)` | `void`                      | Dispatch an already-parsed webhook notification. Runs the wake handler in the background.               |
 | `drainWakes()`                      | `Promise<void>`             | Wait for all in-flight wake handlers to settle. Throws if any wake errored.                             |
 | `waitForSettled()`                  | `Promise<void>`             | Wait for all in-flight wake handlers to settle.                                                         |
 | `abortWakes()`                      | `void`                      | Abort in-flight wakes so host shutdown can complete quickly.                                            |
 | `debugState()`                      | `RuntimeDebugState`         | Return a runtime-local snapshot for tests and shutdown diagnostics.                                     |
 | `typeNames`                         | `string[]`                  | Names of all registered entity types (read-only).                                                       |
+| `sandboxProfileDescriptors`         | `Array<{ name, label, description?, remote? }>` | Wire-shape descriptors for sandbox profiles advertised by this runtime (read-only). |
 | `registerTypes()`                   | `Promise<void>`             | Register all entity types with the Electric Agents runtime server. Uses upsert semantics — safe to call on every startup. |
 
 ## RuntimeHandler
@@ -92,6 +104,9 @@ interface RuntimeRouterConfig {
   handlerUrl?: string
   registry?: EntityRegistry
   subscriptionPathForType?: (typeName: string) => string
+  defaultDispatchPolicyForType?: (typeName: string) => DispatchPolicy | undefined
+  serverHeaders?: HeadersProvider
+  webhookSignature?: false | Partial<WebhookSignatureVerifierConfig>
   idleTimeout?: number
   heartbeatInterval?: number
   createElectricTools?: (context: {
@@ -113,26 +128,39 @@ interface RuntimeRouterConfig {
       payload: unknown
       targetUrl?: string
       fireAt: string
-      from?: string
       messageType?: string
     }): Promise<{ txid: string }>
     deleteSchedule(opts: { id: string }): Promise<{ txid: string }>
+    listWebhookSources(): Promise<Array<WebhookSourceContract>>
+    subscribeToWebhookSource(
+      opts: WebhookSourceSubscriptionInput
+    ): Promise<{ txid: string; subscription: WebhookSourceSubscription }>
+    unsubscribeFromWebhookSource(opts: { id: string }): Promise<{ txid: string }>
   }) => AgentTool[] | Promise<AgentTool[]>
   onWakeError?: (error: Error) => boolean | void
   registrationConcurrency?: number
+  sandboxProfiles?: ReadonlyArray<SandboxProfile>
+  publicUrl?: string
+  name?: string
 }
 ```
 
-| Field                     | Type                                                          | Default                                      | Description                                                                                                       |
-| ------------------------- | ------------------------------------------------------------- | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
-| `baseUrl`                 | `string`                                                      | -                                            | Base URL of the Electric Agents runtime server (e.g. `"http://localhost:4437"`). Required.                                          |
-| `serveEndpoint`           | `string`                                                      | -                                            | Full webhook callback URL exposed by your app. Used for type registration.                                        |
-| `webhookPath`             | `string`                                                      | pathname from `serveEndpoint` / `handlerUrl`, or `"/electric-agents"` | Path matched by `handleRequest()`.                                                                                |
-| `handlerUrl`              | `string`                                                      | -                                            | Backward-compatible alias for `serveEndpoint`; prefer `serveEndpoint` in new code.                                |
-| `registry`                | `EntityRegistry`                                              | default registry                             | Entity registry for this handler. Falls back to the module-level default registry.                                |
-| `subscriptionPathForType` | `(typeName: string) => string`                                | -                                            | Override the webhook subscription path used per entity type registration.                                         |
-| `idleTimeout`             | `number`                                                      | `20000`                                      | Idle timeout in milliseconds before closing a wake.                                                               |
-| `heartbeatInterval`       | `number`                                                      | `30000`                                      | Heartbeat interval in milliseconds.                                                                               |
-| `createElectricTools`     | `(context) => AgentTool[] \| Promise<...>`                    | -                                            | Optional tool factory invoked for each wake context before handler execution. Provides extra tools to the agent.  |
-| `onWakeError`             | `(error: Error) => boolean \| void`                           | -                                            | Observer for background wake failures. Return `true` to mark the error as handled so it is not rethrown on drain. |
-| `registrationConcurrency` | `number`                                                      | `8`                                          | Max number of concurrent entity-type registrations.                                                               |
+| Field                          | Type                                        | Default                                                     | Description                                                                                                       |
+| ------------------------------ | ------------------------------------------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `baseUrl`                      | `string`                                    | -                                                           | Base URL of the Electric Agents runtime server (e.g. `"http://localhost:4437"`). Required.                       |
+| `serveEndpoint`                | `string`                                    | -                                                           | Full webhook callback URL exposed by your app. Used for type registration.                                        |
+| `webhookPath`                  | `string`                                    | pathname from `serveEndpoint` / `handlerUrl`, or `"/electric-agents"` | Path matched by `handleRequest()`.                                                                                |
+| `handlerUrl`                   | `string`                                    | -                                                           | Backward-compatible alias for `serveEndpoint`; prefer `serveEndpoint` in new code.                                |
+| `registry`                     | `EntityRegistry`                            | default registry                                            | Entity registry for this handler. Falls back to the module-level default registry.                                |
+| `subscriptionPathForType`      | `(typeName: string) => string`              | -                                                           | Override the webhook subscription path used per entity type registration.                                         |
+| `defaultDispatchPolicyForType` | `(typeName: string) => DispatchPolicy \| undefined` | -                                                   | Override the default dispatch policy registered per entity type.                                                  |
+| `serverHeaders`                | `HeadersProvider`                           | -                                                           | Headers sent on control-plane requests to the agents server, including type registration and wake claims.         |
+| `webhookSignature`             | `false \| Partial<WebhookSignatureVerifierConfig>` | enabled against `${baseUrl}/__ds/jwks.json`         | Webhook signature verification config. Set to `false` only for trusted in-process tests.                          |
+| `idleTimeout`                  | `number`                                    | `20000`                                                     | Idle timeout in milliseconds before closing a wake.                                                               |
+| `heartbeatInterval`            | `number`                                    | `10000`                                                     | Heartbeat interval in milliseconds.                                                                               |
+| `createElectricTools`          | `(context) => AgentTool[] \| Promise<...>`  | -                                                           | Optional tool factory invoked for each wake context before handler execution. Provides extra tools to the agent.  |
+| `onWakeError`                  | `(error: Error) => boolean \| void`         | -                                                           | Observer for background wake failures. Return `true` to mark the error as handled so it is not rethrown on drain. |
+| `registrationConcurrency`      | `number`                                    | `8`                                                         | Max number of concurrent entity-type registrations.                                                               |
+| `sandboxProfiles`              | `ReadonlyArray<SandboxProfile>`             | -                                                           | Named sandbox profiles advertised by this runtime. Spawn requests can select one by profile name.                 |
+| `publicUrl`                    | `string`                                    | -                                                           | Public URL surfaced by server runtime metadata APIs when available.                                               |
+| `name`                         | `string`                                    | `"default"`                                                 | Human-readable runtime name used for runtime metadata de-duplication.                                             |

package/docs/reference/wake-event.md

@@ -76,7 +76,7 @@ type WakeMessage = {
   other_children?: Array<{
     url: string
     type: string
-    status: "spawning" | "running" | "idle" | "stopped"
+    status: "spawning" | "running" | "idle" | "paused" | "stopping" | "stopped" | "killed"
   }>
 }
 ```
@@ -89,9 +89,37 @@ Inspect the payload to distinguish the sub-kind:
 | Observed change     | `ctx.observe(..., { wake: { on: 'change' } })` or `observe(db(...))`        | `payload.changes` is non-empty                                                            |
 | Shared-state change | `await ctx.observe(db(...), { wake: { on: 'change' } })`                    | `payload.changes` is non-empty, `payload.source` identifies the shared-state stream       |
 | Cron fired          | A cron schedule entry on the entity's manifest                              | `payload.source` identifies the schedule; `payload.changes` is empty                      |
+| Webhook source      | `subscribe_webhook_source` tool or `client.subscribeToWebhookSource()`      | `payload.type === "webhook_source_wake"` and `payload.events` contains matching webhook events |
 | Scheduled send      | A `future_send` schedule fires                                              | Arrives as `"inbox"` (not `"wake"`) — the schedule produces a message delivery |
 | Timeout             | `timeoutMs` on a `change` wake config elapsed with no changes               | `payload.timeout === true`, `payload.changes` is empty                                    |
 
+Webhook-source wakes use the hydrated payload from `HydratedWebhookSourceWake`:
+
+```ts
+type HydratedWebhookSourceWake = {
+  type: "webhook_source_wake"
+  source: string
+  sourceType: "webhook"
+  endpointKey: string
+  webhookKey: string
+  subscription: {
+    id: string
+    bucketKey?: string
+    params: Record<string, unknown>
+    filterKey?: string
+    reason?: string
+  }
+  bucket: string | null
+  changes: Array<{
+    collection: string
+    kind: "insert" | "update" | "delete"
+    key: string
+  }>
+  events: WebhookEventRow[]
+  missingEventKeys?: string[]
+}
+```
+
 For the narrative on how these are produced, see [Waking entities](../usage/waking-entities).
 
 ## Wake

package/docs/usage/app-setup.md

@@ -40,8 +40,11 @@ interface RuntimeRouterConfig {
   handlerUrl?: string // legacy alias for serveEndpoint
   registry?: EntityRegistry
   subscriptionPathForType?: (typeName: string) => string
+  defaultDispatchPolicyForType?: (typeName: string) => DispatchPolicy | undefined
+  serverHeaders?: HeadersProvider
+  webhookSignature?: false | Partial<WebhookSignatureVerifierConfig>
   idleTimeout?: number // ms before closing idle wake (default: 20000)
-  heartbeatInterval?: number // ms between heartbeats (default: 30000)
+  heartbeatInterval?: number // ms between heartbeats (default: 10000)
   createElectricTools?: (context: {
     entityUrl: string
     entityType: string
@@ -61,16 +64,35 @@ interface RuntimeRouterConfig {
       payload: unknown
       targetUrl?: string
       fireAt: string
-      from?: string
       messageType?: string
     }): Promise<{ txid: string }>
     deleteSchedule(opts: { id: string }): Promise<{ txid: string }>
+    listWebhookSources(): Promise<Array<WebhookSourceContract>>
+    subscribeToWebhookSource(
+      opts: WebhookSourceSubscriptionInput
+    ): Promise<{ txid: string; subscription: WebhookSourceSubscription }>
+    unsubscribeFromWebhookSource(opts: { id: string }): Promise<{ txid: string }>
   }) => AgentTool[] | Promise<AgentTool[]> // factory for extra agent tools
   onWakeError?: (error: Error) => boolean | void // return true to mark handled
   registrationConcurrency?: number // max concurrent type registrations (default: 8)
+  sandboxProfiles?: ReadonlyArray<SandboxProfile>
+  publicUrl?: string
+  name?: string
 }
 ```
 
+Key fields:
+
+| Field                          | Description                                                                                                      |
+| ------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
+| `serveEndpoint`                | Public webhook callback URL. When present, type registration includes webhook dispatch unless a default dispatch policy overrides it. |
+| `serverHeaders`                | Headers sent on control-plane requests to the agents server, including type registration and wake claims.        |
+| `webhookSignature`             | Webhook signature verification config. Enabled by default against `${baseUrl}/__ds/jwks.json`; set to `false` only for trusted in-process tests. |
+| `defaultDispatchPolicyForType` | Override the default dispatch policy registered per entity type. Use this for pull-wake runner targets.          |
+| `sandboxProfiles`              | Named sandbox profiles advertised by this runtime. Spawn requests can select one by profile name.                |
+| `publicUrl`                    | Public URL for this runtime, surfaced by server runtime metadata APIs when available.                            |
+| `name`                         | Human-readable runtime name. Defaults to `"default"`.                                                           |
+
 ## HTTP server
 
 Your app needs an HTTP server to receive webhook callbacks from the Electric Agents runtime server. Forward webhook POSTs to the runtime handler:
@@ -103,10 +125,7 @@ Must be called after your app starts listening.
 await runtime.registerTypes()
 ```
 
-This makes two requests per entity type:
-
-1. `POST /_electric/entity-types` — registers the type definition and schemas.
-2. `PUT /{type}/**?subscription={type}-handler` — creates a webhook subscription for the type.
+This sends `POST /_electric/entity-types` for each entity type. The request includes the type definition, state schemas, permission grants, optional `serve_endpoint`, and optional default dispatch policy. When `serveEndpoint` is set and no custom default dispatch policy is provided, registration uses webhook dispatch to that endpoint.
 
 ## RuntimeHandler
 
@@ -115,12 +134,22 @@ interface RuntimeHandler {
   onEnter(req: IncomingMessage, res: ServerResponse): Promise<void>
   handleRequest(request: Request): Promise<Response | null>
   handleWebhookRequest(request: Request): Promise<Response>
+  dispatchWake(
+    notification: WakeNotification,
+    options?: Pick<ProcessWakeConfig, "claimHeaders" | "claimTokenHeader">
+  ): void
   dispatchWebhookWake(notification: WebhookNotification): void
   drainWakes(): Promise<void>
   waitForSettled(): Promise<void>
   abortWakes(): void
   debugState(): RuntimeDebugState
   readonly typeNames: string[]
+  readonly sandboxProfileDescriptors: Array<{
+    name: string
+    label: string
+    description?: string
+    remote?: boolean
+  }>
   registerTypes(): Promise<void>
 }
 
@@ -137,12 +166,14 @@ interface RuntimeDebugState {
 | `onEnter`              | Node HTTP adapter — reads the request body and delegates to `handleWebhookRequest` |
 | `handleRequest`        | Fetch-native router — returns `null` if the path does not match `webhookPath`      |
 | `handleWebhookRequest` | Processes a webhook POST directly, without path matching                           |
+| `dispatchWake`         | Dispatches a pre-parsed wake notification from any transport                       |
 | `dispatchWebhookWake`  | Dispatches a pre-parsed notification (fire-and-forget)                             |
 | `drainWakes`           | Waits for all in-flight wake handlers to settle; throws on errors                  |
 | `waitForSettled`       | Waits for all in-flight wakes; throws on errors                                    |
 | `abortWakes`           | Cancels all in-flight wake handlers immediately                                    |
 | `debugState`           | Returns a snapshot of internal runtime state for diagnostics                       |
-| `registerTypes`        | Registers entity types and webhook subscriptions with the Electric Agents runtime server     |
+| `sandboxProfileDescriptors` | Sandbox profile descriptors advertised by this runtime                     |
+| `registerTypes`        | Registers entity types, schemas, permission grants, and default dispatch policy with the Electric Agents runtime server |
 
 ## createRuntimeRouter