@electric-ax/agents 0.4.18 → 0.6.0

package/docs/usage/sandboxing.md

@@ -0,0 +1,162 @@
+---
+title: Sandboxing
+titleTemplate: "... - Electric Agents"
+description: >-
+  Isolate file, process, and network access for LLM-driven tools with Electric Agents sandbox profiles.
+outline: [2, 3]
+---
+
+# Sandboxing
+
+Electric Agents runs LLM-driven file, shell, and fetch tools through `ctx.sandbox`. The sandbox owns filesystem path resolution, subprocess execution, and network egress for the current wake session.
+
+Sandboxing is configured by the runtime host, advertised to the server as named **sandbox profiles**, and selected when an entity is spawned.
+
+## Runtime profiles
+
+Register sandbox profiles on the runtime:
+
+```ts
+import { createRuntimeHandler } from "@electric-ax/agents-runtime"
+import {
+  remoteSandbox,
+  unrestrictedSandbox,
+} from "@electric-ax/agents-runtime/sandbox"
+
+const runtime = createRuntimeHandler({
+  baseUrl: "http://localhost:4437",
+  registry,
+  sandboxProfiles: [
+    {
+      name: "local",
+      label: "Local",
+      description: "Trusted local development sandbox",
+      factory: ({ args }) =>
+        unrestrictedSandbox({
+          workingDirectory:
+            typeof args.workingDirectory === "string"
+              ? args.workingDirectory
+              : process.cwd(),
+        }),
+    },
+    {
+      name: "e2b",
+      label: "E2B",
+      description: "Remote VM sandbox",
+      remote: true,
+      factory: ({ sandboxKey, persistent, owner }) =>
+        remoteSandbox({
+          provider: "e2b",
+          sandboxKey,
+          persistent,
+          owner,
+          initialNetworkPolicy: { mode: "allow-all" },
+        }),
+    },
+  ],
+})
+```
+
+The runtime sends profile descriptors to the server during type/runtime registration. The factory stays local to the runtime; only names, labels, descriptions, and `remote` metadata cross the wire.
+
+## Built-in profiles
+
+The sandbox package exports:
+
+```ts
+import {
+  chooseDefaultSandbox,
+  unrestrictedSandbox,
+  remoteSandbox,
+} from "@electric-ax/agents-runtime/sandbox"
+import { dockerSandbox } from "@electric-ax/agents-runtime/sandbox/docker"
+```
+
+| Provider | Use case | Notes |
+| -------- | -------- | ----- |
+| `unrestrictedSandbox()` | Trusted local development | Shares the host filesystem and process namespace. It is convenient, not a security boundary. |
+| `dockerSandbox()` | Local isolation for multi-entity hosts | Requires Docker and `dockerode`. Recommended for untrusted or multi-tenant local workloads. |
+| `remoteSandbox({ provider: "e2b" })` | Remote VM isolation | Requires the optional `e2b` package and provider credentials. Mark the profile `remote: true`. |
+| `chooseDefaultSandbox()` | Built-in local default | Chooses the default local profile for built-in Horton and Worker runtimes. |
+
+## Handler access
+
+Handlers and custom tools use `ctx.sandbox`:
+
+```ts
+async handler(ctx) {
+  const result = await ctx.sandbox.exec({
+    command: "ls -la",
+    timeoutMs: 10_000,
+    signal: ctx.signal,
+  })
+
+  const readme = await ctx.sandbox.readFile("README.md")
+  const res = await ctx.sandbox.fetch("https://example.com")
+}
+```
+
+Pass paths straight to the sandbox. Do not pre-resolve paths against the host filesystem; the sandbox may be a container or remote VM with a different root.
+
+The runtime owns sandbox disposal. Handlers should not call `ctx.sandbox.dispose()`.
+
+## Spawn-time selection
+
+Select or inherit a sandbox when spawning:
+
+```ts
+await ctx.spawn(
+  "worker",
+  "analysis",
+  { systemPrompt: "Inspect the workspace", tools: ["read", "bash"] },
+  {
+    initialMessage: "Start with package.json",
+    sandbox: "inherit",
+  }
+)
+```
+
+Object form gives more control:
+
+```ts
+await client.spawnEntity({
+  type: "worker",
+  id: "isolated",
+  sandbox: {
+    profile: "docker",
+    scope: "entity",
+    persistent: true,
+  },
+})
+```
+
+Sandbox selection fields:
+
+| Field | Meaning |
+| ----- | ------- |
+| `profile` | Named runtime profile to use. |
+| `inherit` | Reuse the parent's resolved sandbox selection. |
+| `key` | Explicit shared sandbox identity. |
+| `scope` | `entity` for per-entity identity, or `wake` for per-wake identity. |
+| `persistent` | Preserve sandbox state between wake sessions when supported. |
+| `owner` | Whether this entity owns lifecycle teardown for the sandbox. |
+
+## Network policy
+
+Sandbox network policy supports:
+
+```ts
+type NetworkPolicy =
+  | { mode: "allow-all" }
+  | { mode: "deny-all" }
+  | { mode: "allowlist"; allow: string[] }
+```
+
+`deny-all` is the strongest isolation mode on isolated providers. `allowlist` is provider-dependent: remote providers can enforce it at the VM boundary, while Docker currently uses it for sandbox `fetch()` paths rather than as a complete process-level egress boundary. Use `deny-all` when you need network isolation.
+
+## Security notes
+
+- `unrestrictedSandbox()` is for trusted local code. It can reduce accidental path escapes, but it is not a security boundary.
+- Built-in file tools now rely on the active sandbox for containment and do not forward the host `process.env` into shell commands.
+- Remote and Docker sandboxes isolate more, but credentials and mounted data still need careful scoping.
+- Use a per-entity or explicit sandbox key when a worker needs state to survive across wakes.

package/docs/usage/signals.md

@@ -0,0 +1,138 @@
+---
+title: Signals
+titleTemplate: "... - Electric Agents"
+description: >-
+  Interrupt, pause, resume, terminate, and notify Electric Agents entities with lifecycle signals.
+outline: [2, 3]
+---
+
+# Signals
+
+Signals are lifecycle controls for entities. They let users and hosts interrupt active work, pause or resume entities, kill entities, and deliver custom lifecycle notifications to handlers.
+
+Signal records are written to the entity's `signals` collection and appear in timeline helpers.
+
+## Supported signals
+
+| Signal | Runtime behavior |
+| ------ | ---------------- |
+| `SIGINT` | Abort the active handler invocation through `ctx.signal`. Use for "stop current run". |
+| `SIGSTOP` | Runtime-controlled pause. |
+| `SIGCONT` | Runtime-controlled resume. |
+| `SIGKILL` | Terminal kill/delete signal. |
+| `SIGHUP` | Delivered to `ctx.onSignal()` handlers. |
+| `SIGTERM` | Delivered to `ctx.onSignal()` handlers for graceful shutdown-style behavior. |
+| `SIGUSR` | Delivered to `ctx.onSignal()` handlers for application-defined behavior. |
+
+Runtime-controlled signals are handled by the runtime and are not delivered to `ctx.onSignal()`.
+
+## CLI
+
+Send a signal from the CLI:
+
+```sh
+electric agents signal /horton/onboarding SIGINT --reason "stop current run"
+electric agents signal /horton/onboarding SIGUSR --payload '{"refresh":true}'
+```
+
+`kill` is shorthand for a terminal signal:
+
+```sh
+electric agents kill /horton/onboarding
+```
+
+## Programmatic clients
+
+Use `createAgentsClient()` for UI-style clients:
+
+```ts
+const client = createAgentsClient({
+  baseUrl: "http://localhost:4437",
+  principalKey: "user:sam",
+})
+
+await client.signal({
+  entityUrl: "/horton/onboarding",
+  signal: "SIGINT",
+  reason: "User clicked stop",
+})
+
+await client.kill("/horton/onboarding", "User deleted the session")
+```
+
+Use `createRuntimeServerClient()` when you need the lower-level server client:
+
+```ts
+await runtimeClient.signalEntity({
+  entityUrl: "/worker/analysis",
+  signal: "SIGUSR",
+  payload: { refresh: true },
+})
+```
+
+The caller needs `signal` permission on the entity, or `manage`.
+
+## Handler cancellation
+
+Every handler receives `ctx.signal`, an `AbortSignal` that fires when the current wake should stop early. Pass it to cancellable work:
+
+```ts
+async handler(ctx) {
+  const res = await fetch("https://api.example.com/data", {
+    signal: ctx.signal,
+  })
+
+  await ctx.sandbox.exec({
+    command: "npm test",
+    signal: ctx.signal,
+    timeoutMs: 60_000,
+  })
+}
+```
+
+`SIGINT` aborts this signal. Runtime shutdown can also abort it.
+
+## Handler-delivered signals
+
+Use `ctx.onSignal()` for `SIGHUP`, `SIGTERM`, and `SIGUSR`:
+
+```ts
+async handler(ctx) {
+  ctx.onSignal(async ({ signal, reason, payload }) => {
+    if (signal === "SIGUSR") {
+      ctx.insertContext("refresh-request", {
+        name: "Refresh request",
+        content: JSON.stringify({ reason, payload }),
+        attrs: {},
+      })
+    }
+  })
+
+  await ctx.agent.run()
+}
+```
+
+Handlers should keep signal callbacks short and idempotent. If the signal should trigger substantial work, record state or context and let the normal handler flow pick it up.
+
+## Signal records
+
+Signal rows include the signal name, sender, reason, payload, handling status, outcome, and state transition fields:
+
+```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"]
+}
+```
+
+See [Built-in collections](../reference/built-in-collections#signal) for the full row shape.

package/docs/usage/spawning-and-coordinating.md

@@ -18,15 +18,17 @@ Create a child entity:
 const child = await ctx.spawn(type, id, args?, opts?)
 ```
 
-| Parameter             | Type                      | Description                            |
-| --------------------- | ------------------------- | -------------------------------------- |
-| `type`                | `string`                  | Entity type name (must be registered)  |
-| `id`                  | `string`                  | Unique child ID                        |
-| `args`                | `Record<string, unknown>` | Passed to child handler as `ctx.args`  |
-| `opts.initialMessage` | `unknown`                 | First message delivered to child       |
-| `opts.wake`           | `Wake`                    | When to wake the parent (see below)    |
-| `opts.tags`           | `Record<string, string>`  | Key-value tags applied to the child    |
-| `opts.observe`        | `boolean`                 | Also observe the child (default: true) |
+| Parameter                 | Type                      | Description                            |
+| ------------------------- | ------------------------- | -------------------------------------- |
+| `type`                    | `string`                  | Entity type name (must be registered)  |
+| `id`                      | `string`                  | Unique child ID                        |
+| `args`                    | `Record<string, unknown>` | Passed to child handler as `ctx.args`  |
+| `opts.initialMessage`     | `unknown`                 | First message delivered to child       |
+| `opts.initialMessageType` | `string`                  | Optional inbox message type for `initialMessage` |
+| `opts.wake`               | `Wake`                    | When to wake the parent (see below)    |
+| `opts.tags`               | `Record<string, string>`  | Key-value tags applied to the child    |
+| `opts.observe`            | `boolean`                 | Also observe the child (default: true) |
+| `opts.sandbox`            | `SpawnSandboxOption`      | Sandbox profile or inheritance for the child |
 
 `spawn` is a creation-only operation. Calling it with a `(type, id)` pair that already exists in the entity's manifest throws an error. Use `observe(entity(url))` to get a handle to an existing child.
 
@@ -38,6 +40,23 @@ The `wake` option controls when the parent's handler is re-invoked:
 
 Returns an [`EntityHandle`](#entityhandle).
 
+Use [Sandboxing](./sandboxing) when children need isolated filesystem, process, or network access, or when a worker should inherit its parent's sandbox.
+
+## fork
+
+Forking creates a new entity from another entity's history at its latest completed run. Use it when you want to branch a session and try a different continuation:
+
+```ts
+const fork = await ctx.forkSelf("variant-a", {
+  initialMessage: { text: "Explore the risky option instead." },
+  tags: { branch: "variant-a" },
+})
+```
+
+`ctx.fork(sourceEntityUrl, id, opts?)` forks another entity; `ctx.forkSelf(id, opts?)` forks the current entity. The new fork is a child of the forking entity by default and registers a `runFinished` wake with `includeResponse: true`, so the parent wakes when the fork's next run finishes. Options mirror `spawn` where they apply: `initialMessage`, `wake`, `tags`, and `observe`.
+
+Pass `observe: false` for fire-and-forget branching with no parent relationship or wake subscription.
+
 ## EntityHandle
 
 Returned by `spawn` and `observe`:
@@ -73,7 +92,7 @@ async handler(ctx, wake) {
     )
 
     ctx.state.children.insert({
-      key: "analyst",
+      key: child.entityUrl,
       url: child.entityUrl,
       status: "running",
     })
@@ -130,7 +149,7 @@ The entity remains alive and can be woken again by incoming messages or observed
 After spawning children in `firstWake`, use `observe` on subsequent wakes to get handles:
 
 ```ts
-async handler(ctx) {
+async handler(ctx, wake) {
   if (ctx.firstWake) {
     await ctx.spawn(
       "worker",

package/docs/usage/testing.md

@@ -15,7 +15,7 @@ Test agent handlers without calling the LLM by providing canned responses:
 ```ts
 ctx.useAgent({
   systemPrompt: "...",
-  model: "claude-sonnet-4-5-20250929",
+  model: "claude-sonnet-4-6",
   tools: [...ctx.electricTools],
   testResponses: ["Hello! How can I help?"],
 })

package/docs/usage/waking-entities.md

@@ -8,9 +8,9 @@ outline: [2, 3]
 
 # Waking entities
 
-Entities in Electric Agents are driven by **wakes**. A wake is a single handler invocation triggered by something outside the handler: a new message, a child finishing, a change in an observed stream, or a schedule. Between wakes the entity is idle — no process, no memory, no running handler.
+Entities in Electric Agents are driven by **wakes**. A wake is a single handler invocation triggered by something outside the handler: a new message, a child finishing, a change in an observed stream, a schedule, a webhook source, or a Postgres sync source. Between wakes the entity is idle — no process, no memory, no running handler.
 
-Everything you do to make an entity respond to something — `ctx.spawn(..., { wake })`, `ctx.observe(..., { wake })`, `ctx.send()`, `upsertCronSchedule()` — is ultimately a way to produce a wake.
+Everything you do to make an entity respond to something — `ctx.spawn(..., { wake })`, `ctx.observe(..., { wake })`, `ctx.send()`, the `upsert_cron_schedule` tool, `client.upsertCronSchedule()`, `subscribe_webhook_source`, or `pgSync()` observation — is ultimately a way to produce a wake.
 
 ## The mental model
 
@@ -18,7 +18,7 @@ Everything you do to make an entity respond to something — `ctx.spawn(..., { w
 external event  ─►  wake entry (persisted)  ─►  handler invocation  ─►  WakeEvent passed to handler
 ```
 
-1. **External event.** A message arrives, a child transitions, a watched collection changes, a cron fires.
+1. **External event.** A message arrives, a child transitions, a watched collection changes, a cron fires, or a subscribed webhook source receives matching data.
 2. **Wake entry is persisted** to the entity's stream. This is the durability guarantee — wakes survive process restarts, network blips, and crashes. A wake that was written will eventually be delivered to a handler.
 3. **Handler is invoked.** The runtime picks up the wake, loads the entity's state, and calls your handler with a `WakeEvent` describing what triggered this invocation.
 4. **Handler runs.** You read `ctx.events`, inspect `wake`, configure the agent, emit new events. When the handler returns (or calls `ctx.sleep()`), the entity goes idle until the next wake.
@@ -27,7 +27,7 @@ This means handlers are re-entrant: the same handler function is called fresh on
 
 ## What produces a wake
 
-There are five things that can wake an entity:
+There are seven things that can wake an entity:
 
 ### 1. An incoming message
 
@@ -85,6 +85,32 @@ await ctx.observe(db("board-1", schema), {
 
 Runtime hosts can expose schedule-management tools through `ctx.electricTools`. The current schedule tool set is `list_schedules`, `upsert_cron_schedule`, `upsert_future_send`, and `delete_schedule`. Schedule entries live on the entity's manifest, so they survive restarts and can be updated or cancelled idempotently.
 
+### 6. A webhook source
+
+Runtime hosts can expose webhook-source tools through `ctx.electricTools`. An entity can subscribe to external webhook-backed feeds with `subscribe_webhook_source`; matching future events wake the entity with hydrated event data.
+
+See [Webhook sources](./webhook-sources).
+
+### 7. A Postgres sync source
+
+`pgSync()` observes an Electric Postgres shape stream and wakes the entity when matching row changes arrive:
+
+```ts
+import { pgSync } from "@electric-ax/agents-runtime"
+
+await ctx.observe(
+  pgSync({
+    url: "http://localhost:3000/v1/shape",
+    table: "todos",
+    where: "project_id = $1",
+    params: ["docs"],
+  }),
+  { wake: { on: "change", ops: ["insert", "update"] } }
+)
+```
+
+Built-in Horton also exposes this as the `observe_pg_sync` tool when the runtime host has pg-sync configured, and `unobserve_pg_sync` to remove an existing pg-sync observation.
+
 ## Reading a WakeEvent
 
 Your handler signature is:
@@ -104,7 +130,7 @@ async handler(ctx, wake) {
     return
   }
 
-  // everything else (child finished, change, cron, timeout) arrives as type "wake".
+  // everything else (child finished, change, cron, webhook source, timeout) arrives as type "wake".
   // Inspect wake.payload for the specific sub-kind.
   ctx.sleep()
 }
@@ -113,7 +139,7 @@ async handler(ctx, wake) {
 Two wake types reach handlers directly:
 
 - `"inbox"` — an external message was delivered to this entity's inbox.
-- `"wake"` — a synthesised wake for anything else (child finished, collection change, cron, timeout). The specifics are on `wake.payload`. A future-send schedule delivers a message, so it arrives as `"inbox"`.
+- `"wake"` — a synthesised wake for anything else (child finished, collection change, cron, webhook source, timeout). The specifics are on `wake.payload`. A future-send schedule delivers a message, so it arrives as `"inbox"`.
 
 For the full payload shape (`changes[]`, `finished_child`, `other_children`, `timeout`), see the [wake-type catalog](../reference/wake-event#wake-type-catalog) in the reference.
 
@@ -145,4 +171,6 @@ When the handler finishes (or calls `ctx.sleep()`), the entity returns to idle.
 - [WakeEvent](../reference/wake-event) — full type reference and wake-type catalog.
 - [Spawning & coordinating](./spawning-and-coordinating) — using `wake` with `spawn` and `observe`.
 - [Shared state](./shared-state) — using `wake` with `observe(db(...))`.
+- [Webhook sources](./webhook-sources) — subscribing entities to external webhook feeds.
+- [Signals](./signals) — lifecycle controls that can interrupt or notify active entities.
 - [Writing handlers](./writing-handlers) — `HandlerContext` and `firstWake` patterns.

package/docs/usage/webhook-sources.md

@@ -0,0 +1,171 @@
+---
+title: Webhook sources
+titleTemplate: "... - Electric Agents"
+description: >-
+  Let agents discover and subscribe to external webhook-backed feeds that wake entities with matching event data.
+outline: [2, 3]
+---
+
+# Webhook sources
+
+Webhook sources let agents subscribe to external feeds such as GitHub, Stripe, email, CI, or other webhook integrations. A subscription persists on the entity manifest and wakes the entity when matching external events arrive.
+
+Built-in Horton runtimes expose webhook-source tools through `ctx.electricTools` by default.
+
+## Contracts
+
+A webhook source contract describes what an agent can subscribe to:
+
+```ts
+type WebhookSourceContract = {
+  serviceId?: string
+  webhookKey: string
+  sourceType: "webhook"
+  endpointKey: string
+  status: "active" | "disabled" | "revoked"
+  label: string
+  description?: string
+  agentVisible: boolean
+  buckets: WebhookSourceBucket[]
+  updatedAt?: string
+  revision: number
+}
+```
+
+Buckets describe path templates and parameters:
+
+```ts
+type WebhookSourceBucket = {
+  key: string
+  label: string
+  description?: string
+  pathTemplate: string
+  paramsSchema: Record<string, unknown>
+  eventTypes?: string[]
+  filters?: WebhookSourceFilter[]
+}
+```
+
+Agents should call `list_webhook_sources` first and use the advertised `webhookKey`, `bucketKey`, `paramsSchema`, and optional `filterKey`.
+
+## Built-in tools
+
+The runtime tool factory can add four tools:
+
+| Tool | Purpose |
+| ---- | ------- |
+| `list_webhook_sources` | List external webhook feeds the entity can subscribe to. |
+| `list_webhook_source_subscriptions` | List active subscriptions for this entity. |
+| `subscribe_webhook_source` | Subscribe the entity to a source or bucket. |
+| `unsubscribe_webhook_source` | Remove a subscription by id. |
+
+Horton receives these tools from the built-in runtime. Custom runtimes can provide them with `createWebhookSourceTools()` or by passing `createElectricTools` through `createRuntimeHandler()`. Built-in runtimes also add schedule tools by default; if you replace `createElectricTools`, include both tool sets when you want Horton to keep both capabilities.
+
+```ts
+import { createWebhookSourceTools } from "@electric-ax/agents-runtime/tools"
+
+const runtime = createRuntimeHandler({
+  baseUrl: "http://localhost:4437",
+  registry,
+  createElectricTools: (context) => createWebhookSourceTools(context),
+})
+```
+
+## Subscribing from tools
+
+`subscribe_webhook_source` accepts:
+
+```ts
+type WebhookSourceSubscriptionInput = {
+  id?: string
+  webhookKey: string
+  bucketKey?: string
+  params?: Record<string, unknown>
+  filterKey?: string
+  lifetime?: SubscriptionLifetime
+  reason?: string
+}
+```
+
+If `id` is omitted, the runtime derives a deterministic id from the source, bucket, params, and filter.
+
+Lifetimes:
+
+```ts
+type SubscriptionLifetime =
+  | { kind: "until_entity_stopped" }
+  | { kind: "expires_at"; at: string }
+  | { kind: "manual" }
+```
+
+The default lifetime is `until_entity_stopped`.
+
+## Programmatic subscriptions
+
+Host code can subscribe directly with `createRuntimeServerClient()`:
+
+```ts
+await client.subscribeToWebhookSource({
+  entityUrl: "/horton/onboarding",
+  webhookKey: "github",
+  bucketKey: "repo",
+  params: { repo: "electric-sql/electric" },
+  reason: "Watch repo activity for this session",
+})
+
+await client.unsubscribeFromWebhookSource({
+  entityUrl: "/horton/onboarding",
+  id: "github-main",
+})
+```
+
+Use `listWebhookSources()` to inspect available contracts:
+
+```ts
+const sources = await client.listWebhookSources()
+```
+
+## Wake payloads
+
+When a subscribed source fires, the entity is woken with a hydrated webhook-source payload:
+
+```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[]
+}
+```
+
+Handlers can inspect `wake.payload` or use the normal agent context. Horton includes hydrated webhook-source data in the trigger message so the model can react without doing a second lookup.
+
+## Manifest entries
+
+Subscriptions are stored as `manifest` rows with `kind: "source"` and a stable manifest key:
+
+```ts
+webhook-source:<subscription-id>
+```
+
+This lets the entity list and remove subscriptions across wakes.
+
+## Filters
+
+`filterKey` selects a named filter advertised by the source. Filters are intended to narrow external webhook feeds. In the current version, filters are advisory until server-side webhook filters are enabled, so agents should still handle unexpected events defensively.