@electric-ax/agents 0.2.1 → 0.2.2

package/docs/reference/runtime-handler.md

@@ -0,0 +1,136 @@
+---
+title: RuntimeHandler
+titleTemplate: '... - Electric Agents'
+description: >-
+  API reference for RuntimeHandler: webhook handling, type registration, and deployment configuration.
+outline: [2, 3]
+---
+
+# RuntimeHandler
+
+Factory functions that create the runtime request router and Node HTTP adapter. The router handles webhook wake delivery from the Electric Agents runtime server and registers entity types on startup.
+
+**Source:** `@electric-ax/agents-runtime`
+
+## RuntimeRouter
+
+```ts
+interface RuntimeRouter {
+  handleRequest(request: Request): Promise<Response | null>
+  handleWebhookRequest(request: Request): Promise<Response>
+  dispatchWebhookWake(notification: WebhookNotification): void
+  drainWakes(): Promise<void>
+  waitForSettled(): Promise<void>
+  abortWakes(): void
+  debugState(): RuntimeDebugState
+  readonly typeNames: string[]
+  registerTypes(): Promise<void>
+}
+```
+
+| Method                              | Return Type                 | Description                                                                                                               |
+| ----------------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `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.                                                                |
+| `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).                                                                         |
+| `registerTypes()`                   | `Promise<void>`             | Register all entity types with the Electric Agents runtime server. Uses upsert semantics — safe to call on every startup. |
+
+## RuntimeHandler
+
+Extends `RuntimeRouter` with a Node HTTP adapter.
+
+```ts
+interface RuntimeHandler extends RuntimeRouter {
+  onEnter(req: IncomingMessage, res: ServerResponse): Promise<void>
+}
+```
+
+| Method              | Parameters                               | Description                                                                                           |
+| ------------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `onEnter(req, res)` | Node `IncomingMessage`, `ServerResponse` | Node HTTP adapter. Converts the request to a fetch `Request` and delegates to `handleWebhookRequest`. |
+
+## RuntimeDebugState
+
+```ts
+interface RuntimeDebugState {
+  pendingWakeCount: number
+  pendingWakeLabels: string[]
+  wakeErrorCount: number
+  typeNames: string[]
+}
+```
+
+| Field               | Type       | Description                                             |
+| ------------------- | ---------- | ------------------------------------------------------- |
+| `pendingWakeCount`  | `number`   | Number of in-flight wake handlers.                      |
+| `pendingWakeLabels` | `string[]` | Labels identifying each pending wake (for diagnostics). |
+| `wakeErrorCount`    | `number`   | Number of wake handlers that have errored.              |
+| `typeNames`         | `string[]` | Names of all registered entity types.                   |
+
+## Factory functions
+
+```ts
+function createRuntimeRouter(config: RuntimeRouterConfig): RuntimeRouter
+
+function createRuntimeHandler(config: RuntimeHandlerConfig): RuntimeHandler
+```
+
+Both factory functions accept the same runtime router configuration.
+
+## RuntimeRouterConfig
+
+```ts
+interface RuntimeRouterConfig {
+  baseUrl: string
+  serveEndpoint?: string
+  webhookPath?: string
+  registry?: EntityRegistry
+  subscriptionPathForType?: (typeName: string) => string
+  idleTimeout?: number
+  heartbeatInterval?: number
+  createElectricTools?: (context: {
+    entityUrl: string
+    entityType: string
+    args: Readonly<Record<string, unknown>>
+    db: EntityStreamDBWithActions
+    events: Array<ChangeEvent>
+    upsertCronSchedule(opts: {
+      id: string
+      expression: string
+      timezone?: string
+      payload?: unknown
+      debounceMs?: number
+      timeoutMs?: number
+    }): Promise<{ txid: string }>
+    upsertFutureSendSchedule(opts: {
+      id: string
+      payload: unknown
+      targetUrl?: string
+      fireAt: string
+      from?: string
+      messageType?: string
+    }): Promise<{ txid: string }>
+    deleteSchedule(opts: { id: string }): Promise<{ txid: string }>
+  }) => AgentTool[] | Promise<AgentTool[]>
+  onWakeError?: (error: Error) => boolean | void
+  registrationConcurrency?: number
+}
+```
+
+| 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`, or `"/electric-agents"` | Path matched by `handleRequest()`.                                                                                |
+| `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.                                                               |

package/docs/reference/shared-state-handle.md

@@ -0,0 +1,74 @@
+---
+title: SharedStateHandle
+titleTemplate: '... - Electric Agents'
+description: >-
+  Type reference for SharedStateHandle: collection proxies and SharedStateSchemaMap interface.
+outline: [2, 3]
+---
+
+# SharedStateHandle
+
+Handle for a shared state stream, returned by `ctx.mkdb()` and `await ctx.observe(db(...))`. Provides typed collection proxies keyed by the collection names declared in the schema map.
+
+**Source:** `@electric-ax/agents-runtime`
+
+```ts
+type SharedStateHandle<
+  TSchema extends SharedStateSchemaMap = SharedStateSchemaMap,
+> = {
+  id: string
+} & { [K in keyof TSchema]: StateCollectionProxy }
+```
+
+## Properties
+
+| Property           | Type                                               | Description                                                                                   |
+| ------------------ | -------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `id`               | `string`                                           | The shared state stream identifier.                                                           |
+| `[collectionName]` | [`StateCollectionProxy`](./state-collection-proxy) | One property per collection defined in the schema. Provides insert/update/delete/get/toArray. |
+
+## SharedStateSchemaMap
+
+Defines the collections in a shared state stream.
+
+```ts
+type SharedStateSchemaMap = Record<string, SharedStateCollectionSchema>
+```
+
+## SharedStateCollectionSchema
+
+```ts
+interface SharedStateCollectionSchema {
+  schema?: StandardSchemaV1
+  type: string
+  primaryKey: string
+}
+```
+
+| Field        | Type               | Required | Description                                                      |
+| ------------ | ------------------ | -------- | ---------------------------------------------------------------- |
+| `schema`     | `StandardSchemaV1` | No       | Zod or Standard Schema validator for the row type.               |
+| `type`       | `string`           | Yes      | Event type string used in the durable stream (e.g. `"finding"`). |
+| `primaryKey` | `string`           | Yes      | Primary key field name on the row (must be a string field).      |
+
+## Example
+
+```ts
+import { db } from '@electric-ax/agents-runtime'
+
+const schema = {
+  findings: {
+    schema: z.object({
+      key: z.string(),
+      domain: z.string(),
+      finding: z.string(),
+    }),
+    type: 'finding',
+    primaryKey: 'key',
+  },
+}
+
+ctx.mkdb('research-findings', schema)
+const shared = await ctx.observe(db('research-findings', schema))
+shared.findings.insert({ key: 'f1', domain: 'security', finding: '...' })
+```

package/docs/reference/state-collection-proxy.md

@@ -0,0 +1,41 @@
+---
+title: StateCollectionProxy
+titleTemplate: '... - Electric Agents'
+description: >-
+  API reference for StateCollectionProxy: insert, update, delete, get, and toArray operations.
+outline: [2, 3]
+---
+
+# StateCollectionProxy
+
+Proxy handle for a state collection. Entity-local state exposes these proxies on `ctx.state.<collection>`, and shared state exposes them on a `SharedStateHandle` returned by `ctx.mkdb()` or `await ctx.observe(db(...))`. Mutations are routed through auto-generated CRUD actions. Reads delegate to the underlying TanStack DB collection.
+
+> **Note:** Entity state can also be accessed through the lower-level `ctx.db.actions.<coll>_insert/update/delete` and `ctx.db.collections.<coll>?.get/toArray` APIs. `ctx.state` is the proxy convenience layer over those APIs.
+
+**Source:** `@electric-ax/agents-runtime`
+
+```ts
+interface StateCollectionProxy<T extends object = Record<string, unknown>> {
+  insert(row: T): unknown
+  update(key: string, updater: (draft: T) => void): unknown
+  delete(key: string): unknown
+  get(key: string): T | undefined
+  toArray: T[]
+}
+```
+
+## Members
+
+| Member                 | Parameters                                   | Return Type      | Description                                                             |
+| ---------------------- | -------------------------------------------- | ---------------- | ----------------------------------------------------------------------- |
+| `insert(row)`          | `row: T`                                     | `Transaction`    | Insert a new row into the collection.                                   |
+| `update(key, updater)` | `key: string`, `updater: (draft: T) => void` | `Transaction`    | Update a row by key. The updater receives an Immer-style mutable draft. |
+| `delete(key)`          | `key: string`                                | `Transaction`    | Delete a row by key.                                                    |
+| `get(key)`             | `key: string`                                | `T \| undefined` | Read a single row by key. Returns `undefined` if not found.             |
+| `toArray`              | -                                            | `T[]`            | All rows as an array. This is a getter property, not a method.          |
+
+## Notes
+
+- Mutating methods (`insert`, `update`, `delete`) return a Transaction. These are fire-and-forget -- the write is persisted to the backing durable stream asynchronously.
+- The `update` method uses Immer-style drafts. Mutate the draft directly rather than returning a new object.
+- `toArray` is a property, not a method call. Access it without parentheses: `ctx.state.items.toArray` or `shared.items.toArray`.

package/docs/reference/wake-event.md

@@ -0,0 +1,132 @@
+---
+title: WakeEvent
+titleTemplate: '... - Electric Agents'
+description: >-
+  Type reference for WakeEvent and Wake configuration: runFinished and change-based wake conditions.
+outline: [2, 3]
+---
+
+# WakeEvent
+
+Describes why an entity handler was invoked. Passed as the second argument to the handler function.
+
+**Source:** `@electric-ax/agents-runtime`
+
+```ts
+type WakeEvent = {
+  source: string
+  type: string
+  fromOffset: number
+  toOffset: number
+  eventCount: number
+  payload?: unknown
+  summary?: string
+  fullRef?: string
+}
+```
+
+## Fields
+
+| Field        | Type      | Description                                                                                                                      |
+| ------------ | --------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `source`     | `string`  | URL or identifier of the stream that triggered the wake.                                                                         |
+| `type`       | `string`  | Wake type. Usually `"message_received"` or `"wake"`; fallback webhook events can use `triggerEvent` or `"message"`. See catalog. |
+| `fromOffset` | `number`  | Start offset of new events in the source stream.                                                                                 |
+| `toOffset`   | `number`  | End offset (exclusive) of new events.                                                                                            |
+| `eventCount` | `number`  | Number of new events in this wake.                                                                                               |
+| `payload`    | `unknown` | Optional payload data associated with the wake. Shape depends on `type`.                                                         |
+| `summary`    | `string`  | Optional human-readable summary of the wake reason.                                                                              |
+| `fullRef`    | `string`  | Optional full reference identifier for the wake source.                                                                          |
+
+## Wake-type catalog
+
+Handlers usually see two values for `wake.type`. Direct inbox messages arrive as `"message_received"`. Most non-message triggers are flattened into `"wake"`, with the specifics carried on `wake.payload`. Low-level webhook fallbacks can surface `triggerEvent` directly, or `"message"` when no trigger event is provided.
+
+### `"message_received"`
+
+An external message landed in the entity's inbox — from `ctx.send()`, the CLI's `electric agents send`, or any direct `/send` HTTP call.
+
+| Field          | Shape                                                                             |
+| -------------- | --------------------------------------------------------------------------------- |
+| `wake.source`  | The `from` field of the message (sender identifier), or the entity URL if absent. |
+| `wake.payload` | The message payload (any JSON-serialisable value).                                |
+| `wake.summary` | The `message_type` if the sender set one.                                         |
+
+### `"wake"`
+
+A synthesised wake for any non-message trigger. `wake.payload` is a `WakeMessage`:
+
+```ts
+type WakeMessage = {
+  timestamp: string
+  source: string
+  timeout: boolean
+  changes: Array<{
+    collection: string
+    kind: 'insert' | 'update' | 'delete'
+    key: string
+  }>
+  finished_child?: {
+    url: string
+    type: string
+    run_status: 'completed' | 'failed'
+    response?: string
+    error?: string
+  }
+  other_children?: Array<{
+    url: string
+    type: string
+    status: 'spawning' | 'running' | 'idle' | 'stopped'
+  }>
+}
+```
+
+Inspect the payload to distinguish the sub-kind:
+
+| Sub-kind            | Producer                                                                    | Payload marker                                                                            |
+| ------------------- | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| Child finished      | `ctx.spawn(..., { wake: 'runFinished' })` when the child completes or fails | `payload.finished_child` is set (with `run_status` and optional `response`)               |
+| 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                      |
+| Scheduled send      | A `future_send` schedule fires                                              | Arrives as `"message_received"` (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                                    |
+
+For the narrative on how these are produced, see [Waking entities](../usage/waking-entities).
+
+## Wake
+
+The `Wake` type configures when a parent should be woken in response to a child, observed entity, or shared state change. Used in `ctx.spawn()`, `ctx.observe()`, and `ctx.observe(db(...))` options.
+
+```ts
+type Wake =
+  | 'runFinished'
+  | { on: 'runFinished'; includeResponse?: boolean }
+  | {
+      on: 'change'
+      collections?: string[]
+      ops?: ('insert' | 'update' | 'delete')[]
+      debounceMs?: number
+      timeoutMs?: number
+    }
+```
+
+### `'runFinished'`
+
+Wake the parent when the child's agent run completes (status changes to `completed` or `failed`). By default, the wake event includes the child's concatenated text response in `finished_child.response`.
+
+### `{ on: 'runFinished', includeResponse?: boolean }`
+
+Object form of `runFinished` with options. Set `includeResponse: false` to omit the child's text response from the wake event.
+
+### `{ on: 'change' }`
+
+Wake the parent when changes occur in the observed stream.
+
+| Field         | Type       | Description                                                           |
+| ------------- | ---------- | --------------------------------------------------------------------- |
+| `on`          | `'change'` | Required discriminant.                                                |
+| `collections` | `string[]` | Optional filter. Only wake on changes to these collections.           |
+| `ops`         | `string[]` | Optional operation filter: `"insert"`, `"update"`, and/or `"delete"`. |
+| `debounceMs`  | `number`   | Debounce interval in milliseconds. Batches rapid changes.             |
+| `timeoutMs`   | `number`   | Maximum time to wait before waking, even if no changes occur.         |

package/docs/usage/app-setup.md

@@ -0,0 +1,165 @@
+---
+title: App setup
+titleTemplate: '... - Electric Agents'
+description: >-
+  Connect your app to the Electric Agents runtime with createRuntimeHandler, webhooks, and type registration.
+outline: [2, 3]
+---
+
+# App setup
+
+The runtime handler connects your app's entity definitions to the Electric Agents runtime server via webhooks.
+
+## createRuntimeHandler
+
+Creates a runtime with a Node HTTP adapter:
+
+```ts
+import {
+  createEntityRegistry,
+  createRuntimeHandler,
+} from '@electric-ax/agents-runtime'
+
+const registry = createEntityRegistry()
+// ... register entity types ...
+
+const runtime = createRuntimeHandler({
+  baseUrl: 'http://localhost:4437',
+  serveEndpoint: 'http://localhost:3000/webhook',
+  registry,
+})
+```
+
+## Configuration
+
+```ts
+interface RuntimeRouterConfig {
+  baseUrl: string // Electric Agents server URL
+  serveEndpoint?: string // Webhook callback URL
+  webhookPath?: string // Path to match (default: derived from serveEndpoint)
+  registry?: EntityRegistry
+  subscriptionPathForType?: (typeName: string) => string
+  idleTimeout?: number // ms before closing idle wake (default: 20000)
+  heartbeatInterval?: number // ms between heartbeats (default: 30000)
+  createElectricTools?: (context: {
+    entityUrl: string
+    entityType: string
+    args: Readonly<Record<string, unknown>>
+    db: EntityStreamDBWithActions
+    events: Array<ChangeEvent>
+    upsertCronSchedule(opts: {
+      id: string
+      expression: string
+      timezone?: string
+      payload?: unknown
+      debounceMs?: number
+      timeoutMs?: number
+    }): Promise<{ txid: string }>
+    upsertFutureSendSchedule(opts: {
+      id: string
+      payload: unknown
+      targetUrl?: string
+      fireAt: string
+      from?: string
+      messageType?: string
+    }): Promise<{ txid: string }>
+    deleteSchedule(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)
+}
+```
+
+## 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:
+
+```ts
+import http from 'node:http'
+
+const server = http.createServer(async (req, res) => {
+  if (req.url === '/webhook' && req.method === 'POST') {
+    await runtime.onEnter(req, res)
+    return
+  }
+  res.writeHead(404)
+  res.end()
+})
+
+server.listen(PORT, async () => {
+  await runtime.registerTypes()
+  console.log(`${runtime.typeNames.length} types registered`)
+})
+```
+
+## registerTypes
+
+Registers all entity types with the Electric Agents runtime server and creates webhook subscriptions. Uses upsert semantics — re-registering an existing type updates it rather than erroring.
+
+Must be called after your app starts listening.
+
+```ts
+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.
+
+## RuntimeHandler
+
+```ts
+interface RuntimeHandler {
+  onEnter(req: IncomingMessage, res: ServerResponse): Promise<void>
+  handleRequest(request: Request): Promise<Response | null>
+  handleWebhookRequest(request: Request): Promise<Response>
+  dispatchWebhookWake(notification: WebhookNotification): void
+  drainWakes(): Promise<void>
+  waitForSettled(): Promise<void>
+  abortWakes(): void
+  debugState(): RuntimeDebugState
+  readonly typeNames: string[]
+  registerTypes(): Promise<void>
+}
+
+interface RuntimeDebugState {
+  pendingWakeCount: number
+  pendingWakeLabels: string[]
+  wakeErrorCount: number
+  typeNames: string[]
+}
+```
+
+| Method                 | Description                                                                              |
+| ---------------------- | ---------------------------------------------------------------------------------------- |
+| `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                                 |
+| `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 |
+
+## createRuntimeRouter
+
+Fetch-native alternative with no Node HTTP dependency:
+
+```ts
+import { createRuntimeRouter } from '@electric-ax/agents-runtime'
+
+const router = createRuntimeRouter(config)
+const response = await router.handleRequest(request)
+```
+
+Use this when integrating with non-Node frameworks or edge runtimes.
+
+## Environment variables
+
+| Variable              | Default                 | Purpose                            |
+| --------------------- | ----------------------- | ---------------------------------- |
+| `ELECTRIC_AGENTS_URL` | `http://localhost:4437` | Electric Agents runtime server URL |
+| `PORT`                | `3000`                  | Your app's HTTP port               |
+| `ANTHROPIC_API_KEY`   | —                       | Claude API key                     |