@electric-ax/agents 0.2.1 → 0.2.2

package/docs/quickstart.md

@@ -0,0 +1,201 @@
+---
+title: Quickstart
+titleTemplate: '... - Electric Agents'
+description: >-
+  Run the Electric Agents runtime and the built-in Horton assistant with a single CLI command, then connect from the web UI or define your own entities.
+outline: [2, 3]
+---
+
+# Quickstart
+
+One command starts the Electric Agents runtime, the web UI, and a local [Horton](./entities/agents/horton) assistant you can chat with right away. From there, define your own [entities](./usage/defining-entities) in your own app.
+
+```sh
+npx electric-ax agents quickstart
+```
+
+## What you'll need
+
+- **Node.js 18+**.
+- **[Docker](https://docs.docker.com/get-docker/)**. The runtime server, Postgres, and Electric run as containers.
+- **An [Anthropic API key](https://console.anthropic.com/settings/keys)**. Used by the built-in Horton agent.
+- _(Optional)_ A **[Brave Search API key](https://brave.com/search/api/)** if you want Horton to be able to search the web.
+
+## Set your API key
+
+Either export it in your shell:
+
+```sh
+export ANTHROPIC_API_KEY=sk-ant-...
+```
+
+Or persist it in a `.env` file in the directory you run the CLI from (this creates or overwrites `.env` in the current directory):
+
+```sh
+cat <<'EOF' > .env
+ANTHROPIC_API_KEY=sk-ant-...
+# BRAVE_SEARCH_API_KEY=BS...
+EOF
+```
+
+The CLI also accepts `--anthropic-api-key <key>` if you'd rather pass it inline.
+
+## Start the runtime
+
+```sh
+npx electric-ax agents quickstart
+```
+
+This:
+
+1. Starts Postgres, Electric, and the Electric Agents runtime server in Docker (the runtime serves both the API and the web UI on `http://localhost:4437`).
+2. Starts a built-in **Horton** runtime in the foreground that registers the `horton` and `worker` entity types.
+3. Prints onboarding commands you can copy into a second terminal.
+
+Leave this terminal running. Press `Ctrl-C` to stop the built-in Horton runtime — the runtime server containers keep running in the background until you call [`electric agents stop`](#stop-the-dev-environment).
+
+## Chat with Horton
+
+### From the web UI
+
+Open [http://localhost:4437](http://localhost:4437). Spawn a `horton` entity from the dashboard and send it a message — its timeline updates live as the agent thinks, calls tools, and responds.
+
+### From the CLI
+
+In a separate terminal:
+
+```sh
+npx electric-ax agents spawn /horton/onboarding
+npx electric-ax agents send /horton/onboarding 'Walk me through Electric Agents'
+npx electric-ax agents observe /horton/onboarding
+```
+
+- `spawn` creates a new entity instance at the given path.
+- `send` delivers a message to the entity's inbox, waking its handler.
+- `observe` streams the entity's events to your terminal in real time, with reasoning, tool calls, and text deltas rendered inline.
+
+See the [CLI reference](./reference/cli) for the full command surface.
+
+## Define your own entity types
+
+Once you're chatting with Horton, the next step is to define your own entity types in your own app. Your app is just a process that registers entity types with the runtime server and receives webhook callbacks when they wake.
+
+### 1. Install the runtime SDK
+
+```sh
+mkdir my-agents-app && cd my-agents-app
+npm init -y
+npm install @electric-ax/agents-runtime
+npm install --save-dev tsx
+```
+
+### 2. Create a server
+
+Create `server.ts`:
+
+```ts
+import http from 'node:http'
+import {
+  createEntityRegistry,
+  createRuntimeHandler,
+} from '@electric-ax/agents-runtime'
+
+const ELECTRIC_AGENTS_URL =
+  process.env.ELECTRIC_AGENTS_URL ?? 'http://localhost:4437'
+const PORT = Number(process.env.PORT ?? 3000)
+const SERVE_URL = process.env.SERVE_URL ?? `http://localhost:${PORT}`
+
+const registry = createEntityRegistry()
+
+registry.define('assistant', {
+  description: 'A general-purpose AI assistant',
+  async handler(ctx) {
+    ctx.useAgent({
+      systemPrompt: 'You are a helpful assistant.',
+      model: 'claude-sonnet-4-5-20250929',
+      tools: [...ctx.electricTools],
+    })
+    await ctx.agent.run()
+  },
+})
+
+const runtime = createRuntimeHandler({
+  baseUrl: ELECTRIC_AGENTS_URL,
+  serveEndpoint: `${SERVE_URL}/webhook`,
+  registry,
+})
+
+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(`App server ready on port ${PORT}`)
+})
+```
+
+This does four things:
+
+1. **Defines an entity type** called `assistant` with a handler that configures and runs an LLM agent.
+2. **Creates a runtime handler** that connects to the runtime server.
+3. **Starts an HTTP server** to receive webhook callbacks from the runtime.
+4. **Registers entity types** with the runtime server on startup.
+
+See [App setup](./usage/app-setup) for the full `createRuntimeHandler` configuration.
+
+### 3. Run your app
+
+With the runtime server already running (from `electric agents quickstart` or `electric agents start`), start your app:
+
+```sh
+npx tsx server.ts
+```
+
+Your handler calls `ctx.useAgent()` in this process, so make sure `ANTHROPIC_API_KEY` is exported in this shell (or copy your `.env` into `my-agents-app`).
+
+### 4. Interact with your entity
+
+Spawn an instance, send it a message, and observe the timeline:
+
+```sh
+npx electric-ax agents spawn /assistant/my-assistant
+npx electric-ax agents send /assistant/my-assistant 'Hello!'
+npx electric-ax agents observe /assistant/my-assistant
+```
+
+Or open the web UI at `http://localhost:4437` and pick `/assistant/my-assistant` from the entity list.
+
+## Stop the dev environment
+
+`Ctrl-C` in the quickstart terminal stops the built-in Horton runtime. The runtime server containers keep running. To stop them:
+
+```sh
+npx electric-ax agents stop                  # stop containers, keep data
+npx electric-ax agents stop --remove-volumes # stop containers and wipe data
+```
+
+## Run pieces independently
+
+`quickstart` runs `start` then `start-builtin` for you. Run them yourself if you want the runtime server up across multiple sessions, or to run your own agent process instead of the built-ins:
+
+```sh
+npx electric-ax agents start          # runtime server + UI (background, Docker)
+npx electric-ax agents start-builtin  # built-in Horton + worker (foreground)
+```
+
+See the [CLI reference](./reference/cli#start) for the full set of commands.
+
+## Next steps
+
+- [Overview](./) — the mental model behind entities, handlers, and wakes.
+- [Usage overview](./usage/overview) — the full developer surface on one page.
+- [Defining entities](./usage/defining-entities) — entity types, schemas, and configuration.
+- [Writing handlers](./usage/writing-handlers) — handler lifecycle and the `ctx` API.
+- [Configuring the agent](./usage/configuring-the-agent) — `useAgent`, models, tools, and streaming.
+- [Built-in agents](./entities/agents/horton) — Horton and Worker, the agents that ship with the runtime.

package/docs/reference/agent-config.md

@@ -0,0 +1,82 @@
+---
+title: AgentConfig
+titleTemplate: '... - Electric Agents'
+description: >-
+  API reference for AgentConfig: system prompt, model, tools, streaming, and test responses.
+outline: [2, 3]
+---
+
+# AgentConfig
+
+Configuration for the LLM agent loop. Passed to `ctx.useAgent()`.
+
+**Source:** `@electric-ax/agents-runtime`
+
+```ts
+interface AgentConfig {
+  systemPrompt: string
+  model: string | Model<any>
+  provider?: KnownProvider
+  tools: AgentTool[]
+  streamFn?: StreamFn
+  testResponses?: string[] | TestResponseFn
+}
+```
+
+## Fields
+
+| Field           | Type                         | Required | Description                                                                                                                                  |
+| --------------- | ---------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `systemPrompt`  | `string`                     | Yes      | System prompt sent to the LLM on each step.                                                                                                  |
+| `model`         | `string \| Model<any>`       | Yes      | Model identifier (e.g. `"claude-sonnet-4-5-20250929"`) or a resolved model object.                                                           |
+| `provider`      | `KnownProvider`              | No       | Provider to use when `model` is a string. Defaults to `"anthropic"`.                                                                         |
+| `tools`         | `AgentTool[]`                | Yes      | Tools available to the LLM. Spread `ctx.electricTools` when your runtime host provides runtime-level tools. See [`AgentTool`](./agent-tool). |
+| `streamFn`      | `StreamFn`                   | No       | Optional streaming callback passed to the underlying agent.                                                                                  |
+| `testResponses` | `string[] \| TestResponseFn` | No       | Mock LLM responses for testing. When set, no real LLM calls are made.                                                                        |
+
+## TestResponseFn
+
+```ts
+type TestResponseFn = (
+  message: string,
+  bridge: OutboundBridgeHandle
+) => Promise<string | undefined>
+```
+
+A function that receives the current trigger message and an outbound bridge, then returns a mock response string. Returning `undefined` emits no automatic text response.
+
+## AgentHandle
+
+Returned by `ctx.useAgent()`. Also available as `ctx.agent`.
+
+```ts
+interface AgentHandle {
+  run(input?: string): Promise<AgentRunResult>
+}
+```
+
+| Method        | Return Type               | Description                                                                  |
+| ------------- | ------------------------- | ---------------------------------------------------------------------------- |
+| `run(input?)` | `Promise<AgentRunResult>` | Execute the agent loop. Runs until the LLM stops or all tool calls complete. |
+
+**Parameters:**
+
+| Parameter | Type     | Required | Description                                                                      |
+| --------- | -------- | -------- | -------------------------------------------------------------------------------- |
+| `input`   | `string` | No       | Optional user message appended to the conversation before the agent loop starts. |
+
+## AgentRunResult
+
+```ts
+interface AgentRunResult {
+  writes: ChangeEvent[]
+  toolCalls: Array<{ name: string; args: unknown; result: unknown }>
+  usage: { tokens: number; duration: number }
+}
+```
+
+| Field       | Type                                   | Description                                                                             |
+| ----------- | -------------------------------------- | --------------------------------------------------------------------------------------- |
+| `writes`    | `ChangeEvent[]`                        | Currently returned as an empty array placeholder.                                       |
+| `toolCalls` | `Array<{ name, args, result }>`        | Currently returned as an empty array placeholder.                                       |
+| `usage`     | `{ tokens: number; duration: number }` | Currently returned as `{ tokens: 0, duration: 0 }` until usage aggregation is wired in. |

package/docs/reference/agent-tool.md

@@ -0,0 +1,58 @@
+---
+title: AgentTool
+titleTemplate: '... - Electric Agents'
+description: >-
+  Interface reference for AgentTool: name, description, TypeBox parameters schema, and execute function.
+outline: [2, 3]
+---
+
+# AgentTool
+
+Interface for tools the LLM can call during the agent loop. Re-exported from [`@mariozechner/pi-agent-core`](https://github.com/badlogic/pi-mono).
+
+**Source:** `@electric-ax/agents-runtime` (re-export)
+
+```ts
+interface AgentTool<TParameters extends TSchema = TSchema, TDetails = any> {
+  name: string
+  label: string
+  description: string
+  parameters: TParameters
+  execute: (
+    toolCallId: string,
+    params: Static<TParameters>,
+    signal?: AbortSignal,
+    onUpdate?: AgentToolUpdateCallback<TDetails>
+  ) => Promise<AgentToolResult<TDetails>>
+}
+```
+
+## Fields
+
+| Field         | Type                                                                   | Required | Description                                                          |
+| ------------- | ---------------------------------------------------------------------- | -------- | -------------------------------------------------------------------- |
+| `name`        | `string`                                                               | Yes      | Unique tool name used in LLM function calling.                       |
+| `label`       | `string`                                                               | Yes      | Human-readable label for display.                                    |
+| `description` | `string`                                                               | Yes      | Description sent to the LLM to explain when and how to use the tool. |
+| `parameters`  | `TSchema`                                                              | Yes      | TypeBox JSON Schema defining the tool's parameters.                  |
+| `execute`     | `(toolCallId, params, signal?, onUpdate?) => Promise<AgentToolResult>` | Yes      | Function called when the LLM invokes the tool.                       |
+
+Parameters are defined using [TypeBox](https://github.com/sinclairzx81/typebox) (`@sinclair/typebox`). The schema is used for LLM function calling and argument validation.
+
+## AgentToolResult
+
+```ts
+interface AgentToolResult<T = any> {
+  content: (TextContent | ImageContent)[]
+  details: T
+}
+```
+
+| Field     | Type                              | Description                                                              |
+| --------- | --------------------------------- | ------------------------------------------------------------------------ |
+| `content` | `(TextContent \| ImageContent)[]` | Content returned to the LLM. Typically `{ type: 'text', text: string }`. |
+| `details` | `T`                               | Arbitrary metadata. Must be provided (use `{}` if no details).           |
+
+::: warning
+Every tool must return a `details` property. Omitting it causes a type error.
+:::

package/docs/reference/built-in-collections.md

@@ -0,0 +1,334 @@
+---
+title: Built-in collections
+titleTemplate: '... - Electric Agents'
+description: >-
+  Reference for the 17 runtime-managed collections: runs, steps, texts, toolCalls, inbox, errors, and more.
+outline: [2, 3]
+---
+
+# Built-in collections
+
+Every entity automatically has these 17 collections, populated by the runtime as the agent operates. Custom state collections defined in `EntityDefinition.state` are merged with these at creation time.
+
+**Source:** `@electric-ax/agents-runtime` -- `entity-schema.ts`
+
+## Collection summary
+
+| Collection         | Event Type         | Interface          | Description                  |
+| ------------------ | ------------------ | ------------------ | ---------------------------- |
+| `runs`             | `run`              | `Run`              | Agent run lifecycle          |
+| `steps`            | `step`             | `Step`             | LLM call step lifecycle      |
+| `texts`            | `text`             | `Text`             | Text message lifecycle       |
+| `textDeltas`       | `text_delta`       | `TextDelta`        | Incremental text content     |
+| `toolCalls`        | `tool_call`        | `ToolCall`         | Tool call lifecycle          |
+| `reasoning`        | `reasoning`        | `Reasoning`        | Reasoning block lifecycle    |
+| `errors`           | `error`            | `ErrorEvent`       | Diagnostic errors            |
+| `inbox`            | `message_received` | `MessageReceived`  | Inbound messages             |
+| `wakes`            | `wake`             | `WakeEntry`        | Wake delivery records        |
+| `entityCreated`    | `entity_created`   | `EntityCreated`    | Entity bootstrap metadata    |
+| `entityStopped`    | `entity_stopped`   | `EntityStopped`    | Entity shutdown signal       |
+| `childStatus`      | `child_status`     | `ChildStatusEntry` | Child/observed entity status |
+| `tags`             | `tags`             | `TagEntry`         | Entity tags                  |
+| `contextInserted`  | `context_inserted` | `ContextInserted`  | Context additions            |
+| `contextRemoved`   | `context_removed`  | `ContextRemoved`   | Context removals             |
+| `manifests`        | `manifest`         | `Manifest`         | Durable resource manifests   |
+| `replayWatermarks` | `replay_watermark` | `ReplayWatermark`  | Replay progress tracking     |
+
+All collections use `key` as the primary key.
+
+## Type definitions
+
+### Run
+
+```ts
+interface Run {
+  key: string
+  status: 'started' | 'completed' | 'failed'
+  finish_reason?: string
+}
+```
+
+### Step
+
+```ts
+interface Step {
+  key: string
+  run_id?: string
+  step_number: number
+  status: 'started' | 'completed'
+  finish_reason?: string
+  model_provider?: string
+  model_id?: string
+  duration_ms?: number
+}
+```
+
+### Text
+
+```ts
+interface Text {
+  key: string
+  run_id?: string
+  status: 'streaming' | 'completed'
+}
+```
+
+### TextDelta
+
+```ts
+interface TextDelta {
+  key: string
+  text_id: string
+  run_id: string
+  delta: string
+}
+```
+
+### ToolCall
+
+```ts
+interface ToolCall {
+  key: string
+  run_id?: string
+  tool_name: string
+  status: 'started' | 'args_complete' | 'executing' | 'completed' | 'failed'
+  args?: unknown
+  result?: unknown
+  error?: string
+  duration_ms?: number
+}
+```
+
+### Reasoning
+
+```ts
+interface Reasoning {
+  key: string
+  status: 'streaming' | 'completed'
+}
+```
+
+### ErrorEvent
+
+```ts
+interface ErrorEvent {
+  key: string
+  error_code: string
+  message: string
+  run_id?: string
+  step_id?: string
+  tool_call_id?: string
+}
+```
+
+### MessageReceived
+
+```ts
+interface MessageReceived {
+  key: string
+  from: string
+  payload?: unknown
+  timestamp: string
+  message_type?: string
+}
+```
+
+### WakeEntry
+
+```ts
+interface WakeEntry {
+  key: string
+  timestamp: string
+  source: string
+  timeout: boolean
+  changes: WakeChangeEntry[]
+  finished_child?: WakeFinishedChildEntry
+  other_children?: WakeOtherChildEntry[]
+}
+
+interface WakeChangeEntry {
+  collection: string
+  kind: 'insert' | 'update' | 'delete'
+  key: string
+}
+
+interface WakeFinishedChildEntry {
+  url: string
+  type: string
+  run_status: 'completed' | 'failed'
+  response?: string // concatenated text deltas from the finished run
+  error?: string // error message(s) if run_status is "failed"
+}
+
+interface WakeOtherChildEntry {
+  url: string
+  type: string
+  status: 'spawning' | 'running' | 'idle' | 'stopped'
+}
+```
+
+### EntityCreated
+
+```ts
+interface EntityCreated {
+  key: string
+  entity_type: string
+  timestamp: string
+  args: Record<string, JsonValue>
+  parent_url?: string
+}
+```
+
+### EntityStopped
+
+```ts
+interface EntityStopped {
+  key: string
+  timestamp: string
+  reason?: string
+}
+```
+
+### ChildStatusEntry
+
+```ts
+interface ChildStatusEntry {
+  key: string
+  entity_url: string
+  entity_type: string
+  status: 'spawning' | 'running' | 'idle' | 'stopped'
+}
+```
+
+### TagEntry
+
+```ts
+interface TagEntry {
+  key: string
+  value: string
+}
+```
+
+### ContextInserted
+
+```ts
+interface ContextInserted {
+  key: string
+  id: string
+  name: string
+  attrs: Record<string, string | number | boolean>
+  content: string
+  timestamp: string
+}
+```
+
+### ContextRemoved
+
+```ts
+interface ContextRemoved {
+  key: string
+  id: string
+  name: string
+  timestamp: string
+}
+```
+
+### Manifest
+
+Discriminated union by `kind`:
+
+```ts
+type Manifest =
+  | ManifestChildEntry
+  | ManifestSourceEntry
+  | ManifestSharedStateEntry
+  | ManifestEffectEntry
+  | ManifestContextEntry
+  | ManifestCronScheduleEntry
+  | ManifestFutureSendScheduleEntry
+
+interface ManifestChildEntry {
+  key: string
+  kind: 'child'
+  id: string
+  entity_type: string
+  entity_url: string
+  wake?: WakeConfig
+  observed: boolean
+}
+
+interface ManifestSourceEntry {
+  key: string
+  kind: 'source'
+  sourceType: string
+  sourceRef: string
+  wake?: WakeConfig
+  config: Record<string, unknown>
+}
+
+interface ManifestSharedStateEntry {
+  key: string
+  kind: 'shared-state'
+  id: string
+  mode: 'create' | 'connect'
+  collections: Record<string, { type: string; primaryKey: string }>
+  wake?: WakeConfig
+}
+
+interface ManifestEffectEntry {
+  key: string
+  kind: 'effect'
+  id: string
+  function_ref: string
+  config: unknown
+}
+
+interface ManifestContextEntry {
+  key: string
+  kind: 'context'
+  id: string
+  name: string
+  attrs: Record<string, string | number | boolean>
+  content: string
+  insertedAt: number
+}
+
+interface ManifestCronScheduleEntry {
+  key: string
+  kind: 'schedule'
+  id: string
+  scheduleType: 'cron'
+  expression: string
+  timezone?: string
+  payload?: unknown
+  wake?: WakeConfig
+}
+
+interface ManifestFutureSendScheduleEntry {
+  key: string
+  kind: 'schedule'
+  id: string
+  scheduleType: 'future_send'
+  fireAt: string
+  targetUrl: string
+  payload: unknown
+  producerId: string
+  from?: string
+  messageType?: string
+  status?: 'pending' | 'sent' | 'failed'
+  sentAt?: string
+  failedAt?: string
+  lastError?: string
+}
+```
+
+### ReplayWatermark
+
+```ts
+interface ReplayWatermark {
+  key: string
+  source_id: string
+  offset: string
+  updated_at: string
+}
+```