@electric-ax/agents 0.2.1 → 0.2.2

package/docs/usage/defining-entities.md

@@ -0,0 +1,181 @@
+---
+title: Defining entities
+titleTemplate: '... - Electric Agents'
+description: >-
+  Register entity types with the EntityRegistry, define custom state collections, typed schemas, and handler functions.
+outline: [2, 3]
+---
+
+# Defining entities
+
+An entity type is registered with an `EntityRegistry`. The registry maps type names to `EntityDefinition` objects that declare the entity's state, schemas, and handler.
+
+## Registry
+
+`createEntityRegistry()` returns an `EntityRegistry`. Register types with `registry.define(name, definition)`.
+
+```ts
+import { createEntityRegistry } from '@electric-ax/agents-runtime'
+
+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()
+  },
+})
+```
+
+Calling `registry.define()` with a name that is already registered throws an error.
+
+## EntityDefinition
+
+```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>
+}
+```
+
+| Field            | Purpose                                                                                             |
+| ---------------- | --------------------------------------------------------------------------------------------------- |
+| `description`    | Human-readable description. Shown in the Electric Agents UI and CLI.                                |
+| `state`          | Custom persistent collections accessed via `ctx.state`, `ctx.db.actions`, and `ctx.db.collections`. |
+| `actions`        | Factory that returns custom non-CRUD action functions exposed on `ctx.actions`.                     |
+| `creationSchema` | JSON Schema for arguments passed when the entity is spawned.                                        |
+| `inboxSchemas`   | JSON Schemas for typed inbox message categories.                                                    |
+| `outputSchemas`  | JSON Schemas for typed output message categories.                                                   |
+| `handler`        | The function that runs each time the entity wakes. Required.                                        |
+
+## Custom state
+
+Declare named collections in the `state` field. Each collection is a `CollectionDefinition`:
+
+```ts
+interface CollectionDefinition {
+  schema?: StandardSchemaV1
+  type?: string
+  primaryKey?: string
+}
+```
+
+| Field        | Default          | Purpose                                                                 |
+| ------------ | ---------------- | ----------------------------------------------------------------------- |
+| `schema`     | none             | Optional Standard Schema validator (e.g. Zod). Validates rows on write. |
+| `type`       | `"state:{name}"` | Event type string used in the durable stream.                           |
+| `primaryKey` | `"key"`          | The field used as the primary key for the collection.                   |
+
+Declared collections become available via `ctx.state` proxies and the lower-level `ctx.db.actions` / `ctx.db.collections` APIs:
+
+```ts
+import { z } from 'zod'
+
+const childSchema = z.object({
+  key: z.string(),
+  url: z.string(),
+  kind: z.string(),
+})
+
+registry.define('coordinator', {
+  description: 'Spawns and tracks child entities',
+  state: {
+    status: { primaryKey: 'key' },
+    children: { schema: childSchema, primaryKey: 'key' },
+  },
+
+  async handler(ctx) {
+    if (ctx.firstWake) {
+      ctx.db.actions.status_insert({ row: { key: 'current', value: 'idle' } })
+    }
+    // Convenience proxy:
+    ctx.state.children.insert({
+      key: 'child-1',
+      url: '/worker/child-1',
+      kind: 'worker',
+    })
+
+    // Lower-level APIs:
+    // Writes: ctx.db.actions.children_insert(), .children_update(), .children_delete()
+    // Reads: ctx.db.collections.children?.get(key), .children?.toArray
+  },
+})
+```
+
+For entity state, `ctx.state.<name>.insert/update/delete/get/toArray` is the convenience API. Lower-level writes use `ctx.db.actions.<name>_insert/update/delete`, and reads use `ctx.db.collections.<name>?.get(key)` and `ctx.db.collections.<name>?.toArray`.
+
+::: info
+`StateCollectionProxy` is used for both entity-local `ctx.state` and shared state handles. See [StateCollectionProxy](../reference/state-collection-proxy) for details.
+:::
+
+## Registry pattern
+
+For projects with multiple entity types, keep a separate registry file and import register functions:
+
+```ts
+// entities/registry.ts
+import { createEntityRegistry } from '@electric-ax/agents-runtime'
+import { registerAssistant } from './assistant'
+import { registerWorker } from './worker'
+
+export const registry = createEntityRegistry()
+registerAssistant(registry)
+registerWorker(registry)
+```
+
+```ts
+// entities/assistant.ts
+import type { EntityRegistry } from '@electric-ax/agents-runtime'
+
+export function registerAssistant(registry: EntityRegistry) {
+  registry.define('assistant', {
+    description: 'General-purpose 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()
+    },
+  })
+}
+```
+
+This keeps each entity type isolated and the registry composition explicit.
+
+## Schemas
+
+`creationSchema`, `inboxSchemas`, and `outputSchemas` accept [`StandardJSONSchemaV1`](https://github.com/standard-schema/standard-schema) objects. Any schema library implementing the Standard JSON Schema interface works (e.g. Zod v4). These schemas are used for validation and for generating UI and documentation in the Electric Agents dashboard.
+
+```ts
+import { z } from 'zod/v4'
+
+registry.define('processor', {
+  description: 'Processes structured tasks',
+  creationSchema: z.object({
+    priority: z.enum(['low', 'medium', 'high']).default('medium'),
+  }),
+  inboxSchemas: {
+    task: z.object({
+      title: z.string(),
+      body: z.string().optional(),
+    }),
+  },
+  async handler(ctx) {
+    // ctx.args.priority is available from creationSchema
+  },
+})
+```

package/docs/usage/defining-tools.md

@@ -0,0 +1,229 @@
+---
+title: Defining tools
+titleTemplate: '... - Electric Agents'
+description: >-
+  Create stateless, stateful, and handler-scoped tools for the LLM agent loop.
+outline: [2, 3]
+---
+
+# Defining tools
+
+Tools are functions the LLM can call during the agent loop. Each tool has a name, description, typed parameters, and an execute function.
+
+## AgentTool interface
+
+Re-exported from [`@mariozechner/pi-agent-core`](https://github.com/badlogic/pi-mono):
+
+```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>>
+}
+```
+
+The return type:
+
+```ts
+interface AgentToolResult<T = any> {
+  content: Array<{ type: 'text'; text: string }>
+  details: T
+}
+```
+
+## Parameters
+
+Defined using [TypeBox](https://github.com/sinclairzx81/typebox) (`@sinclair/typebox`). The schema is used for LLM function calling and argument validation.
+
+```ts
+import { Type } from '@sinclair/typebox'
+
+parameters: Type.Object({
+  expression: Type.String({ description: 'Math expression to evaluate' }),
+  precision: Type.Optional(Type.Number({ description: 'Decimal places' })),
+})
+```
+
+## Stateless tools
+
+Pure functions with no side effects beyond what they compute. Define directly as an `AgentTool` object.
+
+```ts
+import { Type } from '@sinclair/typebox'
+import type { AgentTool } from '@electric-ax/agents-runtime'
+
+const calculatorTool: AgentTool = {
+  name: 'calculator',
+  label: 'Calculator',
+  description: 'Evaluate mathematical expressions.',
+  parameters: Type.Object({
+    expression: Type.String({ description: 'The expression to evaluate' }),
+  }),
+  execute: async (_toolCallId, params) => {
+    const { expression } = params as { expression: string }
+    const result = evaluate(expression)
+    return {
+      content: [{ type: 'text', text: String(result) }],
+      details: {},
+    }
+  },
+}
+```
+
+## Stateful tools
+
+Use a factory function that receives the `HandlerContext`. The state persists across wakes -- it is backed by the entity's durable stream. Reads go through `ctx.db.collections` and writes go through `ctx.db.actions`.
+
+```ts
+import { Type } from '@sinclair/typebox'
+import type { AgentTool, HandlerContext } from '@electric-ax/agents-runtime'
+
+function createMemoryStoreTool(ctx: HandlerContext): AgentTool {
+  return {
+    name: 'memory_store',
+    label: 'Memory Store',
+    description: 'Persistent key-value store.',
+    parameters: Type.Object({
+      operation: Type.Union([
+        Type.Literal('get'),
+        Type.Literal('set'),
+        Type.Literal('delete'),
+        Type.Literal('list'),
+      ]),
+      key: Type.Optional(Type.String()),
+      value: Type.Optional(Type.String()),
+    }),
+    execute: async (_, params) => {
+      const { operation, key, value } = params as {
+        operation: string
+        key?: string
+        value?: string
+      }
+      if (operation === 'set') {
+        const existing = ctx.db.collections.kv?.get(key!)
+        if (existing) {
+          ctx.db.actions.kv_update({
+            key: key!,
+            updater: (draft) => {
+              draft.value = value!
+            },
+          })
+        } else {
+          ctx.db.actions.kv_insert({ row: { key: key!, value: value! } })
+        }
+        return {
+          content: [{ type: 'text', text: `Stored "${key}"` }],
+          details: {},
+        }
+      }
+      if (operation === 'get') {
+        const entry = ctx.db.collections.kv?.get(key!)
+        const text = entry ? entry.value : `No value found for "${key}"`
+        return { content: [{ type: 'text', text }], details: {} }
+      }
+      if (operation === 'delete') {
+        ctx.db.actions.kv_delete({ key: key! })
+        return {
+          content: [{ type: 'text', text: `Deleted "${key}"` }],
+          details: {},
+        }
+      }
+      // list
+      const entries = ctx.db.collections.kv?.toArray ?? []
+      const text = entries.map((e) => `${e.key}: ${e.value}`).join('\n')
+      return {
+        content: [{ type: 'text', text: text || '(empty)' }],
+        details: {},
+      }
+    },
+  }
+}
+```
+
+The entity state API:
+
+| Operation | Write (via `ctx.db.actions`)                                       | Read (via `ctx.db.collections`)       |
+| --------- | ------------------------------------------------------------------ | ------------------------------------- |
+| Insert    | `ctx.db.actions.<coll>_insert({ row: {...} })`                     | -                                     |
+| Update    | `ctx.db.actions.<coll>_update({ key, updater: (draft) => {...} })` | -                                     |
+| Delete    | `ctx.db.actions.<coll>_delete({ key })`                            | -                                     |
+| Get       | -                                                                  | `ctx.db.collections.<coll>?.get(key)` |
+| List      | -                                                                  | `ctx.db.collections.<coll>?.toArray`  |
+
+## Handler-scoped tools
+
+Use a factory that receives the `HandlerContext`. These tools can spawn entities, observe streams, send messages, and use any other `ctx` primitive.
+
+```ts
+import { Type } from '@sinclair/typebox'
+import type { AgentTool, HandlerContext } from '@electric-ax/agents-runtime'
+
+function createDispatchTool(ctx: HandlerContext): AgentTool {
+  return {
+    name: 'dispatch',
+    label: 'Dispatch',
+    description: 'Spawn a child agent and wait for its response.',
+    parameters: Type.Object({
+      type: Type.String({ description: 'Entity type to spawn' }),
+      systemPrompt: Type.String({ description: 'System prompt for the child' }),
+      task: Type.String({ description: 'Task to send to the child' }),
+    }),
+    execute: async (_, params) => {
+      const { type, systemPrompt, task } = params as {
+        type: string
+        systemPrompt: string
+        task: string
+      }
+      const child = await ctx.spawn(
+        type,
+        `dispatch-${Date.now()}`,
+        { systemPrompt },
+        {
+          initialMessage: task,
+          wake: 'runFinished',
+        }
+      )
+      const text = (await child.text()).join('\n\n')
+      return {
+        content: [{ type: 'text', text }],
+        details: {},
+      }
+    },
+  }
+}
+```
+
+`ctx.spawn` returns an `EntityHandle`. Passing `wake: 'runFinished'` means the parent will be woken when the child's agent run completes. `child.text()` returns all text outputs from the child's stream.
+
+## Wiring tools together
+
+Tools are constructed in the handler and passed to `useAgent`. Include `ctx.electricTools` when your runtime host provides runtime-level tools that the LLM should be able to call:
+
+```ts
+registry.define('assistant', {
+  description: 'An assistant with memory and delegation',
+  state: {
+    kv: { primaryKey: 'key' },
+  },
+  async handler(ctx) {
+    const memoryTool = createMemoryStoreTool(ctx)
+    const dispatchTool = createDispatchTool(ctx)
+
+    ctx.useAgent({
+      systemPrompt: 'You are a helpful assistant with persistent memory.',
+      model: 'claude-sonnet-4-5-20250929',
+      tools: [...ctx.electricTools, memoryTool, dispatchTool, calculatorTool],
+    })
+    await ctx.agent.run()
+  },
+})
+```
+
+When you include `ctx.electricTools`, spread them before your custom tools so host-provided primitives keep their expected order.

package/docs/usage/embedded-builtins.md

@@ -0,0 +1,180 @@
+---
+title: Embedded built-ins
+titleTemplate: '... - Electric Agents'
+description: >-
+  Embed the built-in Horton and worker runtime in your own process using
+  @electric-ax/agents, BuiltinAgentsServer, or the entrypoint helpers.
+outline: [2, 3]
+---
+
+# Embedded built-ins
+
+The CLI commands `electric agents start-builtin` and `electric agents quickstart` run the built-in Horton and worker runtime for you. If you need to host those built-ins inside your own process, use the exported APIs from `@electric-ax/agents`.
+
+## BuiltinAgentsServer
+
+`BuiltinAgentsServer` starts an HTTP webhook server, registers `horton` and `worker`, and forwards Electric Agents webhook wakes to the built-in handler.
+
+```ts
+import { BuiltinAgentsServer } from '@electric-ax/agents'
+
+const server = new BuiltinAgentsServer({
+  agentServerUrl: 'http://localhost:4437',
+  port: 4448,
+  workingDirectory: process.cwd(),
+})
+
+await server.start()
+
+console.log(server.url)
+console.log(server.registeredBaseUrl)
+
+// Later, during shutdown:
+await server.stop()
+```
+
+### Options
+
+```ts
+import type { RuntimeRouterConfig } from '@electric-ax/agents-runtime'
+
+type CreateElectricTools = RuntimeRouterConfig['createElectricTools']
+
+interface BuiltinAgentsServerOptions {
+  agentServerUrl: string
+  baseUrl?: string
+  port: number
+  host?: string
+  workingDirectory?: string
+  mockStreamFn?: StreamFn
+  webhookPath?: string
+  createElectricTools?: CreateElectricTools
+}
+```
+
+| Field                 | Description                                                                  |
+| --------------------- | ---------------------------------------------------------------------------- |
+| `agentServerUrl`      | Electric Agents coordinator server URL.                                      |
+| `baseUrl`             | Public base URL used when registering the webhook. Defaults to local URL.    |
+| `port`                | Local webhook server port.                                                   |
+| `host`                | Bind host. Defaults to `127.0.0.1`.                                          |
+| `workingDirectory`    | Directory used by Horton and worker file tools. Defaults to `process.cwd()`. |
+| `mockStreamFn`        | Optional test stream function. Lets you run without `ANTHROPIC_API_KEY`.     |
+| `webhookPath`         | Webhook path. Defaults to `/_electric/builtin-agent-handler`.                |
+| `createElectricTools` | Optional factory for extra tools injected into built-in agent handlers.      |
+
+Without `mockStreamFn`, `ANTHROPIC_API_KEY` must be present before the built-in handler starts.
+
+## createBuiltinAgentHandler
+
+Use `createBuiltinAgentHandler()` when you already have an HTTP server and only need the request handler and runtime objects.
+
+```ts
+import {
+  createBuiltinAgentHandler,
+  registerBuiltinAgentTypes,
+} from '@electric-ax/agents'
+
+const bootstrap = await createBuiltinAgentHandler({
+  agentServerUrl: 'http://localhost:4437',
+  serveEndpoint: 'https://example.com/_electric/builtin-agent-handler',
+  workingDirectory: process.cwd(),
+})
+
+if (!bootstrap) {
+  throw new Error('ANTHROPIC_API_KEY is required for built-in agents')
+}
+
+await registerBuiltinAgentTypes(bootstrap)
+
+// In your HTTP server:
+await bootstrap.handler(req, res)
+```
+
+### Result
+
+```ts
+interface AgentHandlerResult {
+  handler(req: IncomingMessage, res: ServerResponse): Promise<void>
+  runtime: RuntimeHandler
+  registry: EntityRegistry
+  typeNames: string[]
+  skillsRegistry: SkillsRegistry | null
+}
+```
+
+## Extra Electric Tools
+
+Both `BuiltinAgentsServer` and `createBuiltinAgentHandler()` accept `createElectricTools`. The factory receives the same context shape as `RuntimeRouterConfig.createElectricTools` and can add host-specific tools to Horton.
+
+```ts
+import { Type } from '@sinclair/typebox'
+
+const server = new BuiltinAgentsServer({
+  agentServerUrl: 'http://localhost:4437',
+  port: 4448,
+  createElectricTools: ({ entityUrl, upsertCronSchedule }) => [
+    {
+      name: 'schedule_daily_summary',
+      label: 'Schedule daily summary',
+      description: 'Schedule a daily summary wake for this entity.',
+      parameters: Type.Object({
+        hour: Type.Number(),
+      }),
+      execute: async (_id, params) => {
+        const { hour } = params as { hour: number }
+        await upsertCronSchedule({
+          id: 'daily-summary',
+          expression: `0 ${hour} * * *`,
+          payload: `Run daily summary for ${entityUrl}`,
+        })
+        return { content: [{ type: 'text', text: 'Scheduled.' }], details: {} }
+      },
+    },
+  ],
+})
+```
+
+## Entrypoint Helpers
+
+`runBuiltinAgentsEntrypoint()` reads environment variables, creates a `BuiltinAgentsServer`, and starts it. This is what the `electric-agents` package binary uses.
+
+```ts
+import {
+  resolveBuiltinAgentsEntrypointOptions,
+  runBuiltinAgentsEntrypoint,
+} from '@electric-ax/agents'
+
+const options = resolveBuiltinAgentsEntrypointOptions(process.env)
+const { server, url } = await runBuiltinAgentsEntrypoint()
+
+console.log(options.agentServerUrl, url)
+await server.stop()
+```
+
+Environment variables:
+
+| Variable                            | Description                                      |
+| ----------------------------------- | ------------------------------------------------ |
+| `ELECTRIC_AGENTS_SERVER_URL`        | Required coordinator server URL.                 |
+| `ELECTRIC_AGENTS_BUILTIN_BASE_URL`  | Public webhook base URL for the built-in server. |
+| `ELECTRIC_AGENTS_BUILTIN_HOST`      | Bind host.                                       |
+| `ELECTRIC_AGENTS_BUILTIN_PORT`      | Built-in server port. Defaults to `4448`.        |
+| `ELECTRIC_AGENTS_WORKING_DIRECTORY` | Working directory for file tools.                |
+
+## Built-in Agent APIs
+
+The built-in agent exports are also available if you want to compose your own runtime:
+
+| Export                      | Purpose                                               |
+| --------------------------- | ----------------------------------------------------- |
+| `registerHorton()`          | Register the `horton` type on an `EntityRegistry`.    |
+| `registerWorker()`          | Register the `worker` type on an `EntityRegistry`.    |
+| `HORTON_MODEL`              | Default model id used by Horton and worker.           |
+| `buildHortonSystemPrompt()` | Build Horton's system prompt for a working directory. |
+| `createHortonTools()`       | Create Horton's base shell/file/search/worker tools.  |
+| `createSpawnWorkerTool()`   | Create the `spawn_worker` tool for another agent.     |
+| `WORKER_TOOL_NAMES`         | Valid primitive tool names for workers.               |
+| `createHortonDocsSupport()` | Create Horton's docs knowledge-base support.          |
+
+For the behavior of `horton` and `worker`, see [Horton](../entities/agents/horton) and [Worker](../entities/agents/worker).

package/docs/usage/managing-state.md

@@ -0,0 +1,93 @@
+---
+title: Managing state
+titleTemplate: '... - Electric Agents'
+description: >-
+  Declare and manage persistent entity state using custom collections with typed CRUD operations.
+outline: [2, 3]
+---
+
+# Managing state
+
+Entities can declare custom persistent collections. The convenience API is `ctx.state.<name>.insert/update/delete/get/toArray`; the lower-level APIs are `ctx.db.actions.<name>_insert/update/delete` for writes and `ctx.db.collections.<name>` for reads. State is backed by the entity's durable stream. Values survive process restarts and are available on every handler invocation.
+
+## Declaring state
+
+Define collections in the `state` field of the entity definition:
+
+```ts
+registry.define('my-entity', {
+  state: {
+    status: { primaryKey: 'key' },
+    items: {
+      schema: z.object({
+        key: z.string(),
+        name: z.string(),
+        count: z.number(),
+      }),
+      primaryKey: 'key',
+    },
+  },
+  async handler(ctx) {
+    /* ... */
+  },
+})
+```
+
+Each key in `state` becomes a collection exposed on `ctx.state`, `ctx.db.actions`, and `ctx.db.collections`.
+
+## CollectionDefinition
+
+```ts
+interface CollectionDefinition {
+  schema?: StandardSchemaV1 // Zod or any Standard Schema validator
+  type?: string // Event type in the stream. Defaults to "state:{name}"
+  primaryKey?: string // Key field. Defaults to "key"
+}
+```
+
+All fields are optional. A minimal collection like `{ primaryKey: 'key' }` works without a schema — rows are untyped.
+
+## Writing and reading state
+
+Use `ctx.state.<collection>` for normal handler code. Its `insert`, `update`, and `delete` methods route through generated actions; its `get` and `toArray` members read from the underlying TanStack DB collection.
+
+The lower-level `ctx.db.actions` object exposes action methods named `<collection>_insert`, `<collection>_update`, and `<collection>_delete`. Reads go through `ctx.db.collections`, which exposes TanStack DB collection objects with `.get(key)` and `.toArray`.
+
+Write helpers return a Transaction. Reads query the underlying TanStack DB collection.
+
+## CRUD operations
+
+```ts
+// Convenience API
+ctx.state.items.insert({ key: 'item-1', name: 'Widget', count: 5 })
+const itemViaState = ctx.state.items.get('item-1')
+const allViaState = ctx.state.items.toArray
+ctx.state.items.update('item-1', (draft) => {
+  draft.count += 1
+})
+ctx.state.items.delete('item-1')
+
+// Lower-level insert
+ctx.db.actions.items_insert({
+  row: { key: 'item-1', name: 'Widget', count: 5 },
+})
+
+// Lower-level read
+const item = ctx.db.collections.items?.get('item-1')
+const all = ctx.db.collections.items?.toArray
+
+// Lower-level update (Immer-style draft)
+ctx.db.actions.items_update({
+  key: 'item-1',
+  updater: (draft) => {
+    draft.count += 1
+  },
+})
+
+// Lower-level delete
+ctx.db.actions.items_delete({ key: 'item-1' })
+```
+
+## Built-in collections
+
+Every entity also has `ctx.db.collections` with runtime-managed collections: `runs`, `steps`, `texts`, `toolCalls`, `errors`, `inbox`, and more. These are read-only from the handler's perspective — the runtime writes to them as the agent operates. See [Built-in collections](../reference/built-in-collections) for details.