@electric-ax/agents 0.4.19 → 0.6.0

package/docs/usage/overview.md

@@ -18,13 +18,13 @@ High level overview of the Electric Agents system and developer APIs.
 Agents are entities that handle events, defined as a:
 
 - `handler(ctx, wake)` with
-- `state` and [built in collections](#_8-built-in-collections)
+- `state` and [built in collections](#_9-built-in-collections)
 
 And schemas:
 
 - `creationSchema` -- validated spawn args
 - `inboxSchemas` -- typed message contracts
-- `outputSchemas` -- what the entity emits (for UI binding)
+- `stateSchemas` -- additional registered state schemas
 
 See [Defining entities](/docs/agents/usage/defining-entities) and [EntityDefinition reference](/docs/agents/reference/entity-definition).
 
@@ -35,10 +35,13 @@ The context API passed into the handler:
 | Property/Method                     | Purpose                                                               |
 | ----------------------------------- | --------------------------------------------------------------------- |
 | `ctx.firstWake`                     | Boolean -- initial setup pass while no manifest entries exist         |
+| `ctx.wake`                          | Current wake, also passed as the second handler argument              |
+| `ctx.slashCommands`                 | Read/register structured composer slash commands                      |
 | `ctx.entityUrl`                     | Identity -- `/type/id`                                                |
 | `ctx.entityType`                    | Type name string                                                      |
 | `ctx.args`                          | Readonly spawn arguments                                              |
 | `ctx.tags`                          | Entity tags -- key/value metadata                                     |
+| `ctx.principal`                     | Principal that caused the current wake, when supplied by the server   |
 | `ctx.db`                            | Full TanStack DB: `db.actions` for writes, `db.collections` for reads |
 | `ctx.state`                         | Proxy object keyed by collection name                                 |
 | `ctx.events`                        | Change events that triggered this wake                                |
@@ -49,14 +52,17 @@ The context API passed into the handler:
 | `ctx.agent.run()`                   | Execute the agent loop                                                |
 | `ctx.electricTools`                    | Runtime-provided tools to spread into agent config                    |
 | `ctx.spawn(type, id, args, opts)`   | Create child entity                                                   |
-| `ctx.observe(source, opts)`         | Subscribe to a source via `entity()`, `cron()`, `entities()`, `db()`  |
+| `ctx.fork(url, id, opts)` / `ctx.forkSelf(id, opts)` | Branch an entity at its latest completed run                         |
+| `ctx.observe(source, opts)`         | Subscribe to a source via `entity()`, `cron()`, `entities()`, `db()`, `webhook()`, or `pgSync()` |
 | `ctx.send(url, payload, opts)`      | Send message to an entity                                             |
 | `ctx.sleep()`                       | Return to idle                                                        |
 | `ctx.mkdb(id, schema)`              | Create cross-entity shared state                                      |
 | `ctx.observe(db(id, schema), opts)` | Join existing shared state                                            |
 | `ctx.recordRun()`                   | Record non-LLM work as a run for `runFinished` observers              |
+| `ctx.replyText(text)`               | Emit a synthetic assistant text reply without invoking the LLM         |
+| `ctx.setGoal(input)` / `ctx.getGoal()` | Manage the active goal for long-running agents                     |
 | `ctx.setTag(key, value)`            | Set a tag on this entity                                              |
-| `ctx.removeTag(key)`                | Remove a tag from this entity                                         |
+| `ctx.deleteTag(key)`                | Delete a tag from this entity                                         |
 
 See [Writing handlers](/docs/agents/usage/writing-handlers) and [HandlerContext reference](/docs/agents/reference/handler-context).
 
@@ -65,12 +71,14 @@ See [Writing handlers](/docs/agents/usage/writing-handlers) and [HandlerContext
 ```ts
 ctx.useAgent({
   systemPrompt: string,
-  model: string | Model<any>, // e.g. 'claude-sonnet-4-5-20250929'
-  provider?: KnownProvider,   // defaults to 'anthropic' for string models
+  model: string | Model<any>, // e.g. 'claude-sonnet-4-6'
+  provider?: Provider,        // defaults to 'anthropic' for string models
   tools: AgentTool[],      // [...ctx.electricTools, ...custom]
   streamFn?: StreamFn,     // optional streaming callback
   getApiKey?: (provider: string) => string | Promise<string> | undefined,
   onPayload?: SimpleStreamOptions["onPayload"],
+  modelTimeoutMs?: number,
+  modelMaxRetries?: number,
   testResponses?: string[] | TestResponseFn // for testing without LLM
 })
 await ctx.agent.run()      // blocks until agent finishes
@@ -177,8 +185,10 @@ See [Managing state](/docs/agents/usage/managing-state).
 
 - **`spawn(type, id, args, opts)`** -> `EntityHandle` -- create child
   - `opts.initialMessage` -- first message to deliver
+  - `opts.initialMessageType` -- optional inbox message type for the initial message
   - `opts.wake` -- `'runFinished'`, `{ on: 'runFinished', includeResponse? }`, or `{ on: 'change', collections?, debounceMs?, timeoutMs? }`
-- **`observe(source, opts)`** -> `EntityHandle | ObservationHandle` -- subscribe via `entity()`, `cron()`, `entities()`, `db()`
+- **`fork(sourceEntityUrl, id, opts)` / `forkSelf(id, opts)`** -> `EntityHandle` -- branch an entity at its latest completed run
+- **`observe(source, opts)`** -> `EntityHandle | ObservationHandle` -- subscribe via `entity()`, `cron()`, `entities()`, `db()`, `webhook()`, or `pgSync()`
 - **`send(url, payload, opts)`** -- fire-and-forget message
 - **`recordRun()`** -> `RunHandle` -- publish run lifecycle for external work
 - **`sleep()`** -- go idle
@@ -192,7 +202,17 @@ See [Managing state](/docs/agents/usage/managing-state).
 
 See [Spawning & coordinating](/docs/agents/usage/spawning-and-coordinating) and [EntityHandle reference](/docs/agents/reference/entity-handle).
 
-## 7. Shared state (cross-entity)
+## 7. Runtime capabilities
+
+Use the dedicated guides for runtime features that cut across handlers, clients, and hosted built-ins:
+
+- [Permissions & principals](/docs/agents/usage/permissions-and-principals) — principal-scoped access to types and entities.
+- [Sandboxing](/docs/agents/usage/sandboxing) — filesystem, process, and network isolation for LLM-driven tools.
+- [Attachments](/docs/agents/usage/attachments) — upload, read, and hydrate files and images.
+- [Signals](/docs/agents/usage/signals) — interrupt, pause, resume, kill, and notify entities.
+- [Webhook sources](/docs/agents/usage/webhook-sources) — subscribe entities to external webhook-backed feeds.
+
+## 8. Shared state (cross-entity)
 
 Define a schema map, then create/connect:
 
@@ -213,9 +233,9 @@ shared.findings.insert({ key: "f1", text: "..." })
 
 See [Shared state](/docs/agents/usage/shared-state) and [SharedStateHandle reference](/docs/agents/reference/shared-state-handle).
 
-## 8. Built-in collections
+## 9. Built-in collections
 
-Every entity automatically has 17 `ctx.db.collections`:
+Every entity automatically has 20 `ctx.db.collections`:
 
 | Collection         | Purpose                   | Key fields                                                             |
 | ------------------ | ------------------------- | ---------------------------------------------------------------------- |
@@ -225,13 +245,16 @@ Every entity automatically has 17 `ctx.db.collections`:
 | `textDeltas`       | Incremental text chunks   | `text_id, delta`                                                       |
 | `toolCalls`        | Tool invocation lifecycle | `tool_name, status, args, result`                                      |
 | `reasoning`        | Extended thinking blocks  | `status: streaming/completed`                                          |
+| `reasoningDeltas`  | Incremental reasoning chunks | `reasoning_id, delta`                                               |
 | `errors`           | Diagnostic errors         | `error_code, message`                                                  |
 | `inbox`            | Received messages         | `from, payload, message_type`                                          |
 | `wakes`            | Wake event history        | `source, timeout, changes`                                             |
 | `entityCreated`    | Bootstrap metadata        | `entity_type, args, parent_url`                                        |
 | `entityStopped`    | Shutdown signal           | `timestamp, reason`                                                    |
+| `signals`          | Lifecycle signal records  | `signal, status, outcome`                                              |
 | `childStatus`      | Child entity status       | `entity_url, status`                                                   |
-| `manifests`        | Wiring declarations       | discriminated union: child/source/shared-state/effect/context/schedule |
+| `slashCommands`    | Composer slash commands   | `name, description, args`                                              |
+| `manifests`        | Wiring declarations       | discriminated union: child/source/shared-state/effect/attachment/context/schedule |
 | `replayWatermarks` | Replay offset tracking    | `source_id, offset`                                                    |
 | `tags`             | Entity tags/labels        | `key, value`                                                           |
 | `contextInserted`  | Context additions         | `id, name, attrs, content, timestamp`                                  |
@@ -239,7 +262,7 @@ Every entity automatically has 17 `ctx.db.collections`:
 
 See [Built-in collections](/docs/agents/reference/built-in-collections).
 
-## 9. CLI (`electric agents`)
+## 10. CLI (`electric agents`)
 
 Interact with the system using the Electric Agents CLI:
 
@@ -250,6 +273,8 @@ Interact with the system using the Electric Agents CLI:
 | `electric agents spawn /type/id --args '{...}'` | Create entity                |
 | `electric agents send /type/id 'message'`     | Send message                 |
 | `electric agents observe /type/id`            | Stream entity events         |
+| `electric agents view /type/id`               | Print entity conversation once |
+| `electric agents signal /type/id SIGINT`      | Send a lifecycle signal      |
 | `electric agents inspect /type/id`            | Show entity state            |
 | `electric agents ps [--type --status --parent]` | List entities                |
 | `electric agents kill /type/id`               | Delete entity                |
@@ -261,7 +286,7 @@ Interact with the system using the Electric Agents CLI:
 
 See [CLI reference](/docs/agents/reference/cli).
 
-## 10. App setup
+## 11. App setup
 
 ```ts
 const registry = createEntityRegistry()
@@ -279,7 +304,7 @@ await runtime.registerTypes() // register all types with runtime server
 
 See [App setup](/docs/agents/usage/app-setup) and [RuntimeHandler reference](/docs/agents/reference/runtime-handler).
 
-## 11. App clients and embedded built-ins
+## 12. App clients and embedded built-ins
 
 Use the client and embedding APIs when you need to work with agents outside an entity handler:
 

package/docs/usage/permissions-and-principals.md

@@ -0,0 +1,160 @@
+---
+title: Permissions & principals
+titleTemplate: "... - Electric Agents"
+description: >-
+  Control who can spawn, read, write, signal, fork, schedule, and manage Electric Agents entities using principals and grants.
+outline: [2, 3]
+---
+
+# Permissions & principals
+
+Electric Agents servers authorize requests using a **principal** and permission grants. A principal identifies the caller; grants decide what that caller can do to entity types and entity instances.
+
+## Principals
+
+Pass a principal key as the `Electric-Principal` header. The key shape is:
+
+```text
+<kind>:<id>
+```
+
+Supported principal kinds are `user`, `agent`, `service`, and `system`. The server turns a key such as `user:sam` into the canonical principal URL `/principal/user%3Asam`.
+
+From clients, use `principalKey`:
+
+```ts
+import { createRuntimeServerClient } from "@electric-ax/agents-runtime"
+
+const client = createRuntimeServerClient({
+  baseUrl: "http://localhost:4437",
+  principalKey: "user:sam",
+})
+```
+
+The CLI can pass the same value through the environment:
+
+```sh
+ELECTRIC_AGENTS_PRINCIPAL=user:sam electric agents ps
+```
+
+Servers may also accept additional auth headers through `ELECTRIC_AGENTS_SERVER_HEADERS` or `serverHeaders`, depending on the host.
+
+## Entity type permissions
+
+Entity type grants control who can spawn or manage entities of a type. Type-level permissions are:
+
+| Permission | Allows |
+| ---------- | ------ |
+| `spawn`    | Spawn entities of this type |
+| `manage`   | Manage the entity type and acts as the broader type-level permission |
+
+Declare initial type grants in an entity definition:
+
+```ts
+registry.define("worker", {
+  description: "Internal worker",
+  permissionGrants: [
+    {
+      subject_kind: "principal_kind",
+      subject_value: "user",
+      permission: "spawn",
+    },
+  ],
+  async handler(ctx) {
+    // ...
+  },
+})
+```
+
+`subject_kind` can be `principal` for one principal URL/key or `principal_kind` for every principal of a kind.
+
+Built-in Horton and Worker registrations grant all `user` principals both `spawn` and `manage` on those entity types. This makes local and hosted user principals able to create built-in sessions and see the type metadata needed by creation UIs. Custom entity types should choose their own `permissionGrants`.
+
+## Entity permissions
+
+Entity grants control access to existing entities. Entity-level permissions are:
+
+| Permission | Allows |
+| ---------- | ------ |
+| `read`     | Read entity metadata and streams |
+| `write`    | Send messages and write entity-owned resources |
+| `delete`   | Delete or kill the entity |
+| `signal`   | Send lifecycle signals |
+| `fork`     | Fork from entity history |
+| `schedule` | Create, update, or delete schedules |
+| `spawn`    | Spawn children from this entity |
+| `manage`   | Manage grants and acts as the broader entity-level permission |
+
+Server spawn routes can include initial entity grants:
+
+```ts
+await fetch("http://localhost:4437/_electric/entities/assistant/support-ticket-42", {
+  method: "PUT",
+  headers: {
+    "content-type": "application/json",
+    "electric-principal": "user:sam",
+  },
+  body: JSON.stringify({
+    grants: [
+      {
+        subject_kind: "principal",
+        subject_value: "/principal/user%3Asam",
+        permission: "read",
+      },
+    ],
+  }),
+})
+```
+
+When spawning from a parent, broad delegation requires `manage` on the parent. This applies to grants such as `manage`, principal-kind grants, descendant propagation, and `copy_to_children`.
+
+## Sharing roles
+
+The server stores granular grants, but the UI presents common sharing roles:
+
+| Role     | Grants |
+| -------- | ------ |
+| `view`   | `read`, `fork` |
+| `chat`   | `read`, `write`, `signal`, `fork`, `schedule`, `spawn` |
+| `manage` | `manage`, `delete` |
+
+These are presets for entity grants. They do not change the underlying permission model, and deployments can still grant individual permissions directly.
+
+The server also exposes principal and effective-permission data through Electric shapes for sharing UIs. Point authorization still uses server-side permission checks; Electric visibility is derived from materialized effective permissions.
+
+## Grant propagation
+
+Entity grants may include propagation options:
+
+```ts
+{
+  subject_kind: "principal",
+  subject_value: "/principal/user%3Asam",
+  permission: "read",
+  propagation: "descendants",
+  copy_to_children: true,
+}
+```
+
+- `propagation: "self"` applies to the entity itself.
+- `propagation: "descendants"` applies through descendant entities.
+- `copy_to_children: true` copies the grant when children are spawned.
+- `expires_at` can set a grant expiry timestamp.
+
+## Claim-scoped write tokens
+
+Some low-level writes are protected by claim-scoped write tokens. Handler APIs such as `ctx.setTag()` and `ctx.deleteTag()` already have the active claim context. External clients should usually send messages instead of directly mutating entity-owned state.
+
+If a host reserves the `Authorization` header for server auth, configure write token transport with `writeTokenHeader` or `claimTokenHeader`:
+
+```ts
+const client = createRuntimeServerClient({
+  baseUrl: "http://localhost:4437",
+  headers: { authorization: `Bearer ${serverToken}` },
+  writeTokenHeader: "electric-claim-token",
+})
+```
+
+## Development fallback
+
+Local development servers can use a development principal fallback. Production deployments should authenticate requests and provide an explicit `Electric-Principal` header for every request.

package/docs/usage/programmatic-runtime-client.md

@@ -25,15 +25,21 @@ const client = createRuntimeServerClient({
 interface RuntimeServerClientConfig {
   baseUrl: string
   fetch?: typeof globalThis.fetch
+  headers?: HeadersProvider
+  writeTokenHeader?: ClaimTokenHeader
   track?: <T>(promise: Promise<T>) => Promise<T>
+  principalKey?: string
 }
 ```
 
-| Field     | Description                                                               |
-| --------- | ------------------------------------------------------------------------- |
-| `baseUrl` | Base URL for the Electric Agents server.                                  |
-| `fetch`   | Optional fetch implementation, useful in tests or non-standard runtimes.  |
-| `track`   | Optional wrapper for all requests, useful for telemetry or pending state. |
+| Field              | Description                                                                 |
+| ------------------ | --------------------------------------------------------------------------- |
+| `baseUrl`          | Base URL for the Electric Agents server.                                    |
+| `fetch`            | Optional fetch implementation, useful in tests or non-standard runtimes.    |
+| `headers`          | Static or async headers added to requests, useful for auth or tenant scope. |
+| `writeTokenHeader` | Header transport for claim-scoped write tokens: `authorization`, `electric-claim-token`, or `both`. |
+| `track`            | Optional wrapper for all requests, useful for telemetry or pending state.   |
+| `principalKey`     | Principal key sent as `Electric-Principal` on requests.                     |
 
 ## Entity Lifecycle
 
@@ -46,6 +52,7 @@ const info = await client.spawnEntity({
   args: { timezone: "Europe/London" },
   initialMessage: "Help me get started.",
   tags: { project: "docs" },
+  sandbox: { profile: "local", scope: "entity" },
 })
 
 console.log(info.entityUrl) // "/horton/onboarding"
@@ -60,7 +67,17 @@ interface SpawnEntityOptions {
   args?: Record<string, unknown>
   parentUrl?: string
   initialMessage?: unknown
+  initialMessageType?: string
   tags?: Record<string, string>
+  sandbox?: {
+    profile?: string
+    key?: string
+    scope?: "entity" | "wake"
+    persistent?: boolean
+    owner?: boolean
+    inherit?: boolean
+  }
+  dispatch_policy?: DispatchPolicy
   wake?: {
     subscriberUrl: string
     condition:
@@ -73,14 +90,50 @@ interface SpawnEntityOptions {
     debounceMs?: number
     timeoutMs?: number
     includeResponse?: boolean
+    manifestKey?: string
+  }
+}
+```
+
+### forkEntity
+
+`forkEntity()` wraps `POST /_electric/entities/<type>/<id>/fork` and creates a new entity from a source entity's latest completed run:
+
+```ts
+const fork = await client.forkEntity({
+  sourceEntityUrl: "/horton/onboarding",
+  instanceId: "onboarding-variant",
+  initialMessage: { text: "Try a different approach." },
+  tags: { branch: "variant" },
+})
+
+console.log(fork.entityUrl)
+```
+
+```ts
+interface ForkEntityOptions {
+  sourceEntityUrl: string
+  instanceId?: string
+  parent?: string
+  wake?: {
+    subscriberUrl: string
+    condition: RegisterWakeOptions["condition"]
+    debounceMs?: number
+    timeoutMs?: number
+    includeResponse?: boolean
+    manifestKey?: string
   }
+  initialMessage?: unknown
+  tags?: Record<string, string>
 }
 ```
 
-### getEntityInfo
+`initialMessage` is sent after the fork has been created and dispatch subscriptions are linked, so a partial failure can leave an idle fork. Handler code should prefer `ctx.fork()` or `ctx.forkSelf()`.
+
+### getEntity
 
 ```ts
-const info = await client.getEntityInfo("/horton/onboarding")
+const info = await client.getEntity("/horton/onboarding")
 // { entityUrl, entityType, streamPath }
 ```
 
@@ -98,8 +151,8 @@ Deleting an already-missing entity is treated as success.
 await client.sendEntityMessage({
   targetUrl: "/horton/onboarding",
   payload: "What changed since last time?",
-  from: "support-ui",
   type: "user_message",
+  mode: "queued",
 })
 ```
 
@@ -107,13 +160,57 @@ await client.sendEntityMessage({
 interface SendEntityMessageOptions {
   targetUrl: string
   payload: unknown
-  from?: string
   type?: string
   afterMs?: number
+  mode?: "immediate" | "queued" | "paused" | "steer"
+  position?: string
+  fromPrincipal?: string
+  fromAgent?: string
+  writeToken?: string
 }
 ```
 
-`afterMs` asks the server to deliver the message later.
+`afterMs` asks the server to deliver the message later. `mode` controls how the server queues or applies the message. `fromPrincipal`, `fromAgent`, and `writeToken` are advanced fields for claim-scoped runtime writes.
+
+## Signals
+
+Send lifecycle signals to an entity:
+
+```ts
+await client.signalEntity({
+  entityUrl: "/horton/onboarding",
+  signal: "SIGINT",
+  reason: "User stopped the current run",
+})
+```
+
+`deleteEntity()` sends `SIGKILL` and treats an already-missing entity as success:
+
+```ts
+await client.deleteEntity("/horton/onboarding")
+```
+
+## Attachments
+
+Attachments are uploaded through entity routes, stored in private attachment streams, and referenced by manifest entries:
+
+```ts
+const { attachment } = await client.createAttachment({
+  entityUrl: "/horton/onboarding",
+  attachment: {
+    bytes: imageBytes,
+    mimeType: "image/png",
+    filename: "diagram.png",
+    subject: { type: "inbox", key: "message-1" },
+    role: "input",
+  },
+})
+
+const bytes = await client.readAttachment({
+  entityUrl: "/horton/onboarding",
+  id: attachment.id,
+})
+```
 
 ## Shared State
 
@@ -156,24 +253,69 @@ await client.registerWake({
 })
 ```
 
-### registerCronSource
+### ensureCronStream
 
 ```ts
-const streamUrl = await client.registerCronSource(
+const streamUrl = await client.ensureCronStream(
   "0 9 * * *",
   "Europe/London"
 )
 ```
 
-### registerEntitiesSource
+### ensureEntitiesMembershipStream
 
 ```ts
-const source = await client.registerEntitiesSource({ project: "docs" })
+const source = await client.ensureEntitiesMembershipStream({ project: "docs" })
 // { streamUrl, sourceRef }
 ```
 
 This is the lower-level operation behind observing `entities({ tags })`.
 
+### registerPgSyncSource
+
+```ts
+const source = await client.registerPgSyncSource({
+  url: "http://localhost:3000/v1/shape",
+  table: "todos",
+  where: "project_id = $1",
+  params: ["docs"],
+})
+// { streamUrl, sourceRef }
+```
+
+This is the lower-level operation behind observing `pgSync({ url, table, where, params })` sources. The server turns the Postgres shape into an Electric Agents observation stream.
+
+Remove an entity's pg-sync observation by source reference:
+
+```ts
+await client.removePgSyncObservation({
+  entityUrl: "/horton/onboarding",
+  sourceRef: source.sourceRef,
+})
+```
+
+### Webhook sources
+
+Webhook-source APIs expose webhook-backed feeds that agents can subscribe to:
+
+```ts
+const sources = await client.listWebhookSources()
+
+await client.subscribeToWebhookSource({
+  entityUrl: "/horton/onboarding",
+  id: "github-main",
+  webhookKey: "github",
+  bucketKey: "repo",
+  params: { repo: "electric-sql/electric" },
+  lifetime: { kind: "until_entity_stopped" },
+})
+
+await client.unsubscribeFromWebhookSource({
+  entityUrl: "/horton/onboarding",
+  id: "github-main",
+})
+```
+
 ## Schedules
 
 Schedules are stored on an entity manifest and return the write transaction id.
@@ -202,11 +344,11 @@ await client.deleteSchedule({
 
 ## Tags
 
-`setTag()` and `removeTag()` are primarily for handler/runtime-owned flows that already hold the current claim-scoped write token. External clients should prefer `send()` and write only to an entity's inbox rather than writing entity state directly.
+`setTag()` and `deleteTag()` are primarily for handler/runtime-owned flows that already hold the current claim-scoped write token. External clients should prefer `sendEntityMessage()` and write only to an entity's inbox rather than writing entity state directly.
 
 ```ts
 await client.setTag("/horton/onboarding", "title", "Onboarding", writeToken)
-await client.removeTag("/horton/onboarding", "title", writeToken)
+await client.deleteTag("/horton/onboarding", "title", writeToken)
 ```
 
 ## Choosing a Client