@electric-ax/agents 0.2.1 → 0.2.2

package/docs/reference/cli.md

@@ -0,0 +1,238 @@
+---
+title: CLI
+titleTemplate: '... - Electric Agents'
+description: >-
+  Command reference for the Electric Agents CLI: spawn, send, observe, inspect, list, and manage entities.
+outline: [2, 3]
+---
+
+# CLI reference
+
+The Electric Agents CLI manages entity types and entities. Install it from `electric-ax`, then use the `electric agents` command. You can also run one-off commands with `npx electric-ax agents ...`.
+
+```bash
+npm install -g electric-ax
+```
+
+## Environment variables
+
+| Variable                          | Default                 | Purpose                                       |
+| --------------------------------- | ----------------------- | --------------------------------------------- |
+| `ELECTRIC_AGENTS_URL`             | `http://localhost:4437` | Server URL for entity commands and built-ins  |
+| `ELECTRIC_AGENTS_IDENTITY`        | `user@hostname`         | Sender identity for messages                  |
+| `ELECTRIC_AGENTS_PORT`            | `4437`                  | Port used by `start` / `quickstart`           |
+| `ELECTRIC_AGENTS_BUILTIN_PORT`    | `4448`                  | Webhook port for `start-builtin`              |
+| `ELECTRIC_AGENTS_COMPOSE_PROJECT` | `electric-agents`       | Docker Compose project name                   |
+| `ANTHROPIC_API_KEY`               | -                       | Required for `start-builtin` and `quickstart` |
+
+## Commands
+
+### <span class="cli-command"><code>types</code></span> {#types}
+
+List registered entity types.
+
+```bash
+electric agents types
+```
+
+### <span class="cli-command"><code>types inspect &lt;name&gt;</code></span> {#types-inspect-name}
+
+Show entity type details. Outputs JSON.
+
+```bash
+electric agents types inspect chat
+```
+
+### <span class="cli-command"><code>types delete &lt;name&gt;</code></span> {#types-delete-name}
+
+Delete an entity type registration.
+
+```bash
+electric agents types delete chat
+```
+
+### <span class="cli-command"><code>spawn &lt;url-path&gt; [--args &lt;json&gt;]</code></span> {#spawn-url-path-args-json}
+
+Spawn an entity. URL path format: `/<type>/<id>`.
+
+```bash
+electric agents spawn /chat/my-convo
+electric agents spawn /chat/my-convo --args '{"topic": "AI safety"}'
+```
+
+| Option          | Description                    |
+| --------------- | ------------------------------ |
+| `--args <json>` | Spawn arguments as JSON object |
+
+### <span class="cli-command"><code>send &lt;url&gt; &lt;message...&gt; [--type &lt;msg-type&gt;] [--json]</code></span> {#send-url-message-type-json}
+
+Send a message to an entity. By default, wraps the message string as `{ text: "..." }`. Use `--json` to send raw JSON.
+
+```bash
+electric agents send /chat/my-convo 'Hello!'
+electric agents send /chat/my-convo '{"custom": "payload"}' --json
+electric agents send /chat/my-convo 'alert' --type warning
+```
+
+| Option              | Description                                                      |
+| ------------------- | ---------------------------------------------------------------- |
+| `--type <msg-type>` | Set the message type field                                       |
+| `--json`            | Parse message argument as JSON instead of wrapping as `{ text }` |
+
+### <span class="cli-command"><code>observe &lt;url&gt; [--from &lt;offset&gt;]</code></span> {#observe-url-from-offset}
+
+Stream entity events in real-time. Requires an interactive terminal.
+
+```bash
+electric agents observe /chat/my-convo
+electric agents observe /chat/my-convo --from 0
+```
+
+| Option            | Description                      |
+| ----------------- | -------------------------------- |
+| `--from <offset>` | Start streaming from this offset |
+
+### <span class="cli-command"><code>inspect &lt;url&gt;</code></span> {#inspect-url}
+
+Show entity details. Outputs JSON.
+
+```bash
+electric agents inspect /chat/my-convo
+```
+
+### <span class="cli-command"><code>ps [--type &lt;type&gt;] [--status &lt;status&gt;] [--parent &lt;url&gt;]</code></span> {#ps-type-status-parent}
+
+List entities with optional filters.
+
+```bash
+electric agents ps
+electric agents ps --type chat --status running
+electric agents ps --parent /manager/my-manager
+```
+
+| Option              | Description                 |
+| ------------------- | --------------------------- |
+| `--type <type>`     | Filter by entity type       |
+| `--status <status>` | Filter by status            |
+| `--parent <url>`    | Filter by parent entity URL |
+
+Output shows `URL`, `STATUS`, `CREATED`, and `LAST ACTIVE` columns with human-readable relative timestamps. Results are sorted by most recently active first.
+
+### <span class="cli-command"><code>kill &lt;url&gt;</code></span> {#kill-url}
+
+Delete an entity.
+
+```bash
+electric agents kill /chat/my-convo
+```
+
+### <span class="cli-command"><code>start</code></span> {#start}
+
+Start the local Electric Agents coordinator server, Postgres, Electric, and UI using Docker Compose.
+
+```bash
+electric agents start
+```
+
+### <span class="cli-command"><code>start-builtin [--anthropic-api-key &lt;key&gt;]</code></span> {#start-builtin}
+
+Start the built-in Horton runtime and register built-in agent types with the coordinator server.
+
+```bash
+electric agents start-builtin --anthropic-api-key sk-ant-...
+```
+
+| Option                      | Description                                      |
+| --------------------------- | ------------------------------------------------ |
+| `--anthropic-api-key <key>` | Anthropic API key for the built-in Horton server |
+
+### <span class="cli-command"><code>quickstart [--anthropic-api-key &lt;key&gt;]</code></span> {#quickstart}
+
+Start the coordinator server, print onboarding commands, and run the built-in agents runtime.
+
+```bash
+electric agents quickstart --anthropic-api-key sk-ant-...
+```
+
+| Option                      | Description                                      |
+| --------------------------- | ------------------------------------------------ |
+| `--anthropic-api-key <key>` | Anthropic API key for the built-in Horton server |
+
+### <span class="cli-command"><code>stop [--remove-volumes]</code></span> {#stop}
+
+Stop the local Electric Agents dev environment.
+
+```bash
+electric agents stop
+electric agents stop --remove-volumes
+```
+
+| Option             | Description                    |
+| ------------------ | ------------------------------ |
+| `--remove-volumes` | Remove Docker volumes as well. |
+
+### <span class="cli-command"><code>completion [action]</code></span> {#completion-action}
+
+Set up shell completions. Without arguments, prints setup instructions.
+
+```bash
+electric agents completion            # Show setup instructions
+electric agents completion install    # Auto-install into your shell init file
+```
+
+**Manual setup** (add to your shell init file):
+
+```bash
+# Bash (~/.bashrc) or Zsh (~/.zshrc)
+eval "$(electric --completion)"
+
+# Fish (~/.config/fish/config.fish)
+electric --completion-fish | source
+```
+
+Completions provide tab-completion for commands, flags, entity types, and entity URLs.
+
+## Programmatic CLI
+
+The `electric-ax` package also exports the Commander program and handler factory used by the binary. Use these APIs for tests, custom wrappers, or embedding the command tree in another tool.
+
+```ts
+import {
+  createElectricCliHandlers,
+  createElectricProgram,
+  getElectricCliEnv,
+  run,
+} from 'electric-ax'
+
+const env = getElectricCliEnv({
+  ELECTRIC_AGENTS_URL: 'http://localhost:4437',
+  ELECTRIC_AGENTS_IDENTITY: 'docs@example.com',
+})
+
+const handlers = createElectricCliHandlers(env, 'electric agents')
+const program = createElectricProgram({
+  env,
+  handlers,
+  commandName: 'electric',
+  commandPrefix: 'electric agents',
+})
+
+await program.parseAsync(['node', 'electric', 'agents', 'types'])
+```
+
+| Export                             | Purpose                                                               |
+| ---------------------------------- | --------------------------------------------------------------------- |
+| `DEFAULT_ELECTRIC_AGENTS_URL`      | Default server URL (`"http://localhost:4437"`).                       |
+| `getElectricCliEnv(env?)`          | Reads `ELECTRIC_AGENTS_URL` and `ELECTRIC_AGENTS_IDENTITY`.           |
+| `createElectricCliHandlers()`      | Creates the default command handlers.                                 |
+| `createElectricProgram()`          | Creates the Commander program.                                        |
+| `resolveCommandPrefix(argv, env?)` | Resolves help text examples for direct or package-manager invocation. |
+| `run(argv?)`                       | Runs the CLI entrypoint.                                              |
+
+The installed binaries are `electric` and `electric-ax`. The package also includes `electric-dev` for development workflows.
+
+<style scoped>
+.cli-command code::before {
+  content: "electric agents ";
+}
+</style>

package/docs/reference/entity-definition.md

@@ -0,0 +1,57 @@
+---
+title: EntityDefinition
+titleTemplate: '... - Electric Agents'
+description: >-
+  Type reference for EntityDefinition: description, state, schemas, and handler function signature.
+outline: [2, 3]
+---
+
+# EntityDefinition
+
+Defines an entity type's schema, state, and handler. Passed to `registry.define()` or `defineEntity()`.
+
+**Source:** `@electric-ax/agents-runtime`
+
+```ts
+interface EntityDefinition {
+  description?: string
+  state?: Record<string, CollectionDefinition>
+  actions?: (
+    collections: Record<string, unknown>
+  ) => Record<string, (...args: unknown[]) => void>
+  creationSchema?: StandardJSONSchemaV1
+  inboxSchemas?: Record<string, StandardJSONSchemaV1>
+  outputSchemas?: Record<string, StandardJSONSchemaV1>
+  handler(ctx: HandlerContext, wake: WakeEvent): void | Promise<void>
+}
+```
+
+## Fields
+
+| Field            | Type                                                 | Required | Description                                                                                                                     |
+| ---------------- | ---------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `description`    | `string`                                             | No       | Human-readable description of the entity type. Used in type registration.                                                       |
+| `state`          | `Record<string, CollectionDefinition>`               | No       | Custom state collections exposed via `ctx.db.actions` (writes) and `ctx.db.collections` (reads).                                |
+| `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.                                                      |
+| `handler`        | `(ctx, wake) => void \| Promise<void>`               | Yes      | The function invoked on each wake. Receives [`HandlerContext`](./handler-context) and [`WakeEvent`](./wake-event).              |
+
+## CollectionDefinition
+
+Defines a custom state collection.
+
+```ts
+interface CollectionDefinition {
+  schema?: StandardSchemaV1
+  type?: string
+  primaryKey?: string
+}
+```
+
+| 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.                 |

package/docs/reference/entity-handle.md

@@ -0,0 +1,63 @@
+---
+title: EntityHandle
+titleTemplate: '... - Electric Agents'
+description: >-
+  API reference for EntityHandle returned by spawn and observe: streams, status, text retrieval, and messaging.
+outline: [2, 3]
+---
+
+# EntityHandle
+
+Handle returned by `ctx.spawn()` and `ctx.observe()`. Provides access to a child or observed entity's stream and status.
+
+**Source:** `@electric-ax/agents-runtime`
+
+```ts
+interface EntityHandle {
+  entityUrl: string
+  type?: string
+  db: EntityStreamDB
+  events: ChangeEvent[]
+  run: Promise<void>
+  text(): Promise<string[]>
+  send(msg: unknown): void
+  status(): ChildStatus | undefined
+}
+```
+
+## Members
+
+| Member      | Type                       | Description                                                                         |
+| ----------- | -------------------------- | ----------------------------------------------------------------------------------- |
+| `entityUrl` | `string`                   | URL path of the entity (e.g. `"/chat/my-child"`).                                   |
+| `type`      | `string \| undefined`      | Entity type name, if known.                                                         |
+| `db`        | `EntityStreamDB`           | The entity's TanStack DB instance for querying its collections.                     |
+| `events`    | `ChangeEvent[]`            | All change events received from this entity's stream.                               |
+| `run`       | `Promise<void>`            | Promise that resolves when the entity's current run completes. Useful with `await`. |
+| `text()`    | `Promise<string[]>`        | Returns all text outputs from the entity's stream.                                  |
+| `send(msg)` | `void`                     | Send a message to this entity.                                                      |
+| `status()`  | `ChildStatus \| undefined` | Current status of the entity, or `undefined` if unknown.                            |
+
+## ChildStatus
+
+```ts
+type ChildStatus = ChildStatusEntry
+```
+
+```ts
+interface ChildStatusEntry {
+  key: string
+  entity_url: string
+  entity_type: string
+  status: 'spawning' | 'running' | 'idle' | 'stopped'
+}
+```
+
+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. |
+| `stopped`  | Entity has been stopped or deleted.                         |

package/docs/reference/entity-registry.md

@@ -0,0 +1,73 @@
+---
+title: EntityRegistry
+titleTemplate: '... - Electric Agents'
+description: >-
+  API reference for EntityRegistry: define, get, list, and clear entity type registrations.
+outline: [2, 3]
+---
+
+# EntityRegistry
+
+Manages entity type registrations. Create an isolated registry with `createEntityRegistry()`, or use the module-level convenience functions for a shared default registry.
+
+**Source:** `@electric-ax/agents-runtime`
+
+```ts
+class EntityRegistry {
+  define(name: string, definition: EntityDefinition): void
+  get(name: string): EntityTypeEntry | undefined
+  list(): EntityTypeEntry[]
+  clear(): void
+}
+
+function createEntityRegistry(): EntityRegistry
+```
+
+## Methods
+
+| Method                     | Parameters                                     | Return Type                    | Description                                                      |
+| -------------------------- | ---------------------------------------------- | ------------------------------ | ---------------------------------------------------------------- |
+| `define(name, definition)` | `name: string`, `definition: EntityDefinition` | `void`                         | Register an entity type. Throws if `name` is already registered. |
+| `get(name)`                | `name: string`                                 | `EntityTypeEntry \| undefined` | Look up a registered type by name.                               |
+| `list()`                   | -                                              | `EntityTypeEntry[]`            | Return all registered types.                                     |
+| `clear()`                  | -                                              | `void`                         | Remove all registrations.                                        |
+
+## EntityTypeEntry
+
+```ts
+interface EntityTypeEntry {
+  name: string
+  definition: EntityDefinition
+}
+```
+
+| Field        | Type                                      | Description                 |
+| ------------ | ----------------------------------------- | --------------------------- |
+| `name`       | `string`                                  | The registered type name.   |
+| `definition` | [`EntityDefinition`](./entity-definition) | The full entity definition. |
+
+## Module-level functions
+
+These operate on a shared default registry. Use them when you do not need isolated registries.
+
+```ts
+function defineEntity(name: string, definition: EntityDefinition): void
+
+function getEntityType(name: string): EntityTypeEntry | undefined
+
+function listEntityTypes(): EntityTypeEntry[]
+
+function clearRegistry(): void
+
+function resolveDefine(
+  registry?: EntityRegistry
+): (name: string, definition: EntityDefinition) => void
+```
+
+| Function                         | Description                                                                                                                             |
+| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `defineEntity(name, definition)` | Register a type on the default registry.                                                                                                |
+| `getEntityType(name)`            | Look up a type on the default registry.                                                                                                 |
+| `listEntityTypes()`              | List all types on the default registry.                                                                                                 |
+| `clearRegistry()`                | Clear the default registry.                                                                                                             |
+| `resolveDefine(registry?)`       | Returns `registry.define` if a registry is provided, otherwise `defineEntity`. Convenience for code that optionally accepts a registry. |

package/docs/reference/handler-context.md

@@ -0,0 +1,108 @@
+---
+title: HandlerContext
+titleTemplate: '... - Electric Agents'
+description: >-
+  API reference for HandlerContext: state, coordination, agent configuration, and execution control.
+outline: [2, 3]
+---
+
+# HandlerContext
+
+The handler context is passed as the first argument to every entity handler. It provides access to state, coordination primitives, and agent configuration.
+
+**Source:** `@electric-ax/agents-runtime`
+
+```ts
+interface HandlerContext<TState extends StateProxy = StateProxy> {
+  firstWake: boolean
+  tags: Readonly<EntityTags>
+  entityUrl: string
+  entityType: string
+  args: Readonly<Record<string, unknown>>
+  db: EntityStreamDBWithActions
+  state: TState
+  events: Array<ChangeEvent>
+  actions: Record<string, (...args: unknown[]) => unknown>
+  electricTools: AgentTool[]
+  useAgent(config: AgentConfig): AgentHandle
+  useContext(config: UseContextConfig): void
+  timelineMessages(opts?: TimelineProjectionOpts): Array<TimestampedMessage>
+  insertContext(id: string, entry: ContextEntryInput): void
+  removeContext(id: string): void
+  getContext(id: string): ContextEntry | undefined
+  listContext(): Array<ContextEntry>
+  agent: AgentHandle
+  spawn(
+    type: string,
+    id: string,
+    args?: Record<string, unknown>,
+    opts?: {
+      initialMessage?: unknown
+      wake?: Wake
+      tags?: Record<string, string>
+      observe?: boolean
+    }
+  ): Promise<EntityHandle>
+  observe(
+    source: ObservationSource & { sourceType: 'entity' },
+    opts?: { wake?: Wake }
+  ): Promise<EntityHandle>
+  observe(
+    source: ObservationSource & { sourceType: 'db' },
+    opts?: { wake?: Wake }
+  ): Promise<SharedStateHandle & ObservationHandle>
+  observe(
+    source: ObservationSource,
+    opts?: { wake?: Wake }
+  ): Promise<ObservationHandle>
+  mkdb<T extends SharedStateSchemaMap>(
+    id: string,
+    schema: T
+  ): SharedStateHandle<T>
+  send(
+    entityUrl: string,
+    payload: unknown,
+    opts?: { type?: string; afterMs?: number }
+  ): void
+  setTag(key: string, value: string): Promise<void>
+  removeTag(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()`.
+
+## Properties
+
+| Property        | Type                                              | Description                                                                                                                                   |
+| --------------- | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `firstWake`     | `boolean`                                         | `true` on the entity's first-ever handler invocation.                                                                                         |
+| `tags`          | `Readonly<EntityTags>`                            | Entity tags — key/value metadata associated with this entity.                                                                                 |
+| `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.                                                                                           |
+| `db`            | `EntityStreamDBWithActions`                       | The entity's TanStack DB instance with registered actions.                                                                                    |
+| `state`         | `TState`                                          | Proxy object keyed by collection name. Each property is a [`StateCollectionProxy`](./state-collection-proxy).                                 |
+| `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.                                                      |
+
+## Methods
+
+| Method                            | Return Type                                                       | Description                                                                                                                                                                                                                                |
+| --------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `useAgent(config)`                | `AgentHandle`                                                     | Configure the LLM agent. Must be called before `agent.run()`. See [`AgentConfig`](./agent-config).                                                                                                                                         |
+| `useContext(config)`              | `void`                                                            | Declare context sources with token budgets and cache tiers for the agent's context window. See [Context composition](/docs/agents/usage/context-composition).                                                                              |
+| `timelineMessages(opts?)`         | `Array<TimestampedMessage>`                                       | Project the entity timeline into an ordered array of LLM messages. Typically used as the `content` function of a volatile source. See [Context composition](/docs/agents/usage/context-composition#timelinemessages).                      |
+| `insertContext(id, entry)`        | `void`                                                            | Insert a durable context entry. Persists across wakes. Inserting with an existing `id` replaces the previous entry. See [Context entries](/docs/agents/usage/context-composition#context-entries).                                         |
+| `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.                                                                                                                                                                                                                  |
+| `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).                                                                                                               |
+| `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. |
+| `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).                                                                                                                                             |
+| `setTag(key, value)`              | `Promise<void>`                                                   | Set a tag on this entity.                                                                                                                                                                                                                  |
+| `removeTag(key)`                  | `Promise<void>`                                                   | Remove a tag from this entity.                                                                                                                                                                                                             |
+| `sleep()`                         | `void`                                                            | End the handler without running an agent. The entity remains idle until the next wake.                                                                                                                                                     |