@electric-ax/agents 0.2.1 → 0.2.2

package/docs/usage/overview.md

@@ -0,0 +1,284 @@
+---
+title: Overview
+titleTemplate: '... - Electric Agents'
+description: >-
+  High level overview of the Electric Agents system and developer APIs.
+outline: [2, 3]
+---
+
+# Usage overview
+
+High level overview of the Electric Agents system and developer APIs.
+
+## 1. Entity definition (`registry.define()`)
+
+Agents are entities that handle events, defined as a:
+
+- `handler(ctx, wake)` with
+- `state` and [built in collections](#_8-built-in-collections)
+
+And schemas:
+
+- `creationSchema` -- validated spawn args
+- `inboxSchemas` -- typed message contracts
+- `outputSchemas` -- what the entity emits (for UI binding)
+
+See [Defining entities](/docs/agents/usage/defining-entities) and [EntityDefinition reference](/docs/agents/reference/entity-definition).
+
+## 2. Handler context (`ctx`)
+
+The context API passed into the handler:
+
+| Property/Method                     | Purpose                                                               |
+| ----------------------------------- | --------------------------------------------------------------------- |
+| `ctx.firstWake`                     | Boolean -- is this the entity's first activation?                     |
+| `ctx.entityUrl`                     | Identity -- `/type/id`                                                |
+| `ctx.entityType`                    | Type name string                                                      |
+| `ctx.args`                          | Readonly spawn arguments                                              |
+| `ctx.tags`                          | Entity tags -- key/value metadata                                     |
+| `ctx.db`                            | Full TanStack DB: `db.actions` for writes, `db.collections` for reads |
+| `ctx.state`                         | Proxy object keyed by collection name                                 |
+| `ctx.events`                        | Change events that triggered this wake                                |
+| `ctx.useAgent()`                    | Set up the LLM agent                                                  |
+| `ctx.useContext()`                  | Declare context sources with token budgets and cache tiers            |
+| `ctx.timelineMessages()`            | Project the entity timeline into LLM messages                         |
+| `ctx.insertContext(id, entry)`      | Insert a durable context entry                                        |
+| `ctx.agent.run()`                   | Execute the agent loop                                                |
+| `ctx.electricTools`                 | Runtime-provided tools to spread into agent config                    |
+| `ctx.spawn(type, id, args, opts)`   | Create child entity                                                   |
+| `ctx.observe(source, opts)`         | Subscribe to a source via `entity()`, `cron()`, `entities()`, `db()`  |
+| `ctx.send(url, payload, opts)`      | Send message to an entity                                             |
+| `ctx.sleep()`                       | Return to idle                                                        |
+| `ctx.mkdb(id, schema)`              | Create cross-entity shared state                                      |
+| `ctx.observe(db(id, schema), opts)` | Join existing shared state                                            |
+| `ctx.setTag(key, value)`            | Set a tag on this entity                                              |
+| `ctx.removeTag(key)`                | Remove a tag from this entity                                         |
+
+See [Writing handlers](/docs/agents/usage/writing-handlers) and [HandlerContext reference](/docs/agents/reference/handler-context).
+
+## 3. Agent configuration
+
+```ts
+ctx.useAgent({
+  systemPrompt: string,
+  model: string | Model<any>, // e.g. 'claude-sonnet-4-5-20250929'
+  provider?: KnownProvider,   // defaults to 'anthropic' for string models
+  tools: AgentTool[],      // [...ctx.electricTools, ...custom]
+  streamFn?: StreamFn,     // optional streaming callback
+  testResponses?: string[] // for testing without LLM
+})
+await ctx.agent.run()      // blocks until agent finishes
+```
+
+See [Configuring the agent](/docs/agents/usage/configuring-the-agent) and [AgentConfig reference](/docs/agents/reference/agent-config).
+
+## 4. Tool definition
+
+**Stateless tools** are pure functions:
+
+```ts
+const myTool: AgentTool = {
+  name: 'calculator',
+  label: 'Calculator',
+  description: 'Evaluate a mathematical expression.',
+  parameters: Type.Object({ expression: Type.String() }), // TypeBox
+  execute: async (_toolCallId, params) => {
+    const { expression } = params as { expression: string }
+    const result = evaluate(expression)
+    return {
+      content: [{ type: 'text', text: String(result) }],
+      details: {},
+    }
+  },
+}
+```
+
+**Stateful tools** are factories receiving `ctx` for state access:
+
+```ts
+function createMemoryTool(ctx: HandlerContext): AgentTool {
+  return {
+    name: 'memory_store',
+    label: 'Memory Store',
+    description: 'Persist a key-value memory row.',
+    parameters: Type.Object({
+      key: Type.String(),
+      value: Type.String(),
+    }),
+    execute: async (_, params) => {
+      const { key, value } = params as { key: string; value: string }
+      ctx.db.actions.memory_insert({ row: { key, value } }) // writes to entity state
+      return { content: [{ type: 'text', text: 'Stored.' }], details: {} }
+    },
+  }
+}
+```
+
+**Handler-scoped tools** are factories receiving `ctx`:
+
+```ts
+function createDispatchTool(ctx: HandlerContext): AgentTool {
+  return {
+    name: 'dispatch',
+    label: 'Dispatch',
+    description: 'Spawn a worker and return its text output.',
+    parameters: Type.Object({
+      id: Type.String(),
+      systemPrompt: Type.String(),
+      task: Type.String(),
+    }),
+    execute: async (_, params) => {
+      const { id, systemPrompt, task } = params as {
+        id: string
+        systemPrompt: string
+        task: string
+      }
+      const child = await ctx.spawn(
+        'worker',
+        id,
+        { systemPrompt, tools: ['read'] },
+        { initialMessage: task, wake: 'runFinished' }
+      )
+      const text = (await child.text()).join('\n\n')
+      return { content: [{ type: 'text', text }], details: {} }
+    },
+  }
+}
+```
+
+See [Defining tools](/docs/agents/usage/defining-tools) and [AgentTool reference](/docs/agents/reference/agent-tool).
+
+## 5. State collections (`ctx.db`)
+
+Custom state is accessed through `ctx.db`:
+
+**Writes** via `ctx.db.actions`:
+
+- `.<name>_insert({ row })` -- add new row
+- `.<name>_update({ key, updater: (draft) => { ... } })` -- Immer-style mutation
+- `.<name>_delete({ key })` -- remove by primary key
+
+**Reads** via `ctx.db.collections`:
+
+- `.<name>?.get(key)` -- read one
+- `.<name>?.toArray` -- read all (getter, not method)
+
+See [Managing state](/docs/agents/usage/managing-state).
+
+## 6. Entity coordination primitives
+
+- **`spawn(type, id, args, opts)`** -> `EntityHandle` -- create child
+  - `opts.initialMessage` -- first message to deliver
+  - `opts.wake` -- `'runFinished'`, `{ on: 'runFinished', includeResponse? }`, or `{ on: 'change', collections?, debounceMs?, timeoutMs? }`
+- **`observe(source, opts)`** -> `EntityHandle | ObservationHandle` -- subscribe via `entity()`, `cron()`, `entities()`, `db()`
+- **`send(url, payload, opts)`** -- fire-and-forget message
+- **`sleep()`** -- go idle
+
+**EntityHandle** returned from spawn/observe:
+
+- `.entityUrl`, `.type`, `.db` (read-only TanStack DB)
+- `.run` -- Promise that resolves when child completes
+- `.text()` -- get all completed text output
+- `.send(msg)` -- send follow-up message
+- `.status()` -- `ChildStatus | undefined` (object with `.status`, `.entity_url`, `.entity_type`)
+
+See [Spawning & coordinating](/docs/agents/usage/spawning-and-coordinating) and [EntityHandle reference](/docs/agents/reference/entity-handle).
+
+## 7. Shared state (cross-entity)
+
+Define a schema map, then create/connect:
+
+```ts
+const schema = {
+  findings: {
+    schema: z.object({ key: z.string(), text: z.string() }),
+    type: 'shared:finding',
+    primaryKey: 'key',
+  },
+}
+// Parent creates:
+ctx.mkdb('research-123', schema)
+// Children connect:
+const shared = await ctx.observe(db('research-123', schema))
+shared.findings.insert({ key: 'f1', text: '...' })
+```
+
+See [Shared state](/docs/agents/usage/shared-state) and [SharedStateHandle reference](/docs/agents/reference/shared-state-handle).
+
+## 8. Built-in collections
+
+Every entity automatically has 17 `ctx.db.collections`:
+
+| Collection         | Purpose                   | Key fields                                                             |
+| ------------------ | ------------------------- | ---------------------------------------------------------------------- |
+| `runs`             | Agent run lifecycle       | `status: started/completed/failed`                                     |
+| `steps`            | LLM call steps            | `step_number, model_id, duration_ms`                                   |
+| `texts`            | Text message blocks       | `status: streaming/completed`                                          |
+| `textDeltas`       | Incremental text chunks   | `text_id, delta`                                                       |
+| `toolCalls`        | Tool invocation lifecycle | `tool_name, status, args, result`                                      |
+| `reasoning`        | Extended thinking blocks  | `status: streaming/completed`                                          |
+| `errors`           | Diagnostic errors         | `error_code, message`                                                  |
+| `inbox`            | Received messages         | `from, payload, message_type`                                          |
+| `wakes`            | Wake event history        | `source, timeout, changes`                                             |
+| `entityCreated`    | Bootstrap metadata        | `entity_type, args, parent_url`                                        |
+| `entityStopped`    | Shutdown signal           | `timestamp, reason`                                                    |
+| `childStatus`      | Child entity status       | `entity_url, status`                                                   |
+| `manifests`        | Wiring declarations       | discriminated union: child/source/shared-state/effect/context/schedule |
+| `replayWatermarks` | Replay offset tracking    | `source_id, offset`                                                    |
+| `tags`             | Entity tags/labels        | `key, value`                                                           |
+| `contextInserted`  | Context additions         | `id, name, attrs, content, timestamp`                                  |
+| `contextRemoved`   | Context removals          | `id, name, timestamp`                                                  |
+
+See [Built-in collections](/docs/agents/reference/built-in-collections).
+
+## 9. CLI (`electric agents`)
+
+Interact with the system using the Electric Agents CLI:
+
+| Command                                         | Purpose                          |
+| ----------------------------------------------- | -------------------------------- |
+| `electric agents types`                         | List registered entity types     |
+| `electric agents types inspect <name>`          | Show type schema                 |
+| `electric agents spawn /type/id --args '{...}'` | Create entity                    |
+| `electric agents send /type/id 'message'`       | Send message                     |
+| `electric agents observe /type/id`              | Stream entity events             |
+| `electric agents inspect /type/id`              | Show entity state                |
+| `electric agents ps [--type --status --parent]` | List entities                    |
+| `electric agents kill /type/id`                 | Delete entity                    |
+| `electric agents start`                         | Start local dev environment      |
+| `electric agents start-builtin`                 | Start built-in Horton runtime    |
+| `electric agents quickstart`                    | Start local server and built-ins |
+| `electric agents stop`                          | Stop local dev environment       |
+
+See [CLI reference](/docs/agents/reference/cli).
+
+## 10. App setup
+
+```ts
+const registry = createEntityRegistry()
+registerMyEntity(registry)
+
+const runtime = createRuntimeHandler({
+  baseUrl: ELECTRIC_AGENTS_URL, // Electric Agents server
+  serveEndpoint: `${URL}/webhook`, // callback URL
+  registry,
+})
+
+// Node HTTP server, forward POST /webhook -> runtime.onEnter(req, res)
+await runtime.registerTypes() // register all types with runtime server
+```
+
+See [App setup](/docs/agents/usage/app-setup) and [RuntimeHandler reference](/docs/agents/reference/runtime-handler).
+
+## 11. App clients and embedded built-ins
+
+Use the client and embedding APIs when you need to work with agents outside an entity handler:
+
+| API                           | Use case                                                          |
+| ----------------------------- | ----------------------------------------------------------------- |
+| `createAgentsClient()`        | Observe entity, membership, or shared-state streams from app code |
+| `useChat()`                   | Render an observed `EntityStreamDB` in React                      |
+| `createRuntimeServerClient()` | Spawn, message, delete, tag, and schedule entities from services  |
+| `BuiltinAgentsServer`         | Host Horton and worker in your own process                        |
+
+See [Clients & React](/docs/agents/usage/clients-and-react), [Programmatic runtime client](/docs/agents/usage/programmatic-runtime-client), and [Embedded built-ins](/docs/agents/usage/embedded-builtins).

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

@@ -0,0 +1,216 @@
+---
+title: Programmatic runtime client
+titleTemplate: '... - Electric Agents'
+description: >-
+  Use createRuntimeServerClient to spawn entities, send messages, register wakes,
+  manage schedules, and connect shared state from application code.
+outline: [2, 3]
+---
+
+# Programmatic runtime client
+
+`createRuntimeServerClient()` is the lower-level HTTP client for the Electric Agents server. Handler code should usually use `ctx.spawn()`, `ctx.send()`, `ctx.observe()`, and `ctx.mkdb()` instead. Use this client from application services, tests, CLIs, and integration code that needs to manage entities from outside a handler.
+
+```ts
+import { createRuntimeServerClient } from '@electric-ax/agents-runtime'
+
+const client = createRuntimeServerClient({
+  baseUrl: 'http://localhost:4437',
+})
+```
+
+## Config
+
+```ts
+interface RuntimeServerClientConfig {
+  baseUrl: string
+  fetch?: typeof globalThis.fetch
+  track?: <T>(promise: Promise<T>) => Promise<T>
+}
+```
+
+| Field     | Description                                                               |
+| --------- | ------------------------------------------------------------------------- |
+| `baseUrl` | Base URL for the Electric Agents server.                                  |
+| `fetch`   | Optional fetch implementation, useful in tests or non-standard runtimes.  |
+| `track`   | Optional wrapper for all requests, useful for telemetry or pending state. |
+
+## Entity Lifecycle
+
+### spawnEntity
+
+```ts
+const info = await client.spawnEntity({
+  type: 'horton',
+  id: 'onboarding',
+  args: { timezone: 'Europe/London' },
+  initialMessage: 'Help me get started.',
+  tags: { project: 'docs' },
+})
+
+console.log(info.entityUrl) // "/horton/onboarding"
+```
+
+`spawnEntity()` is idempotent for an existing `/{type}/{id}` URL: if the server reports a conflict and returns entity details, the client returns that entity info.
+
+```ts
+interface SpawnEntityOptions {
+  type: string
+  id: string
+  args?: Record<string, unknown>
+  parentUrl?: string
+  initialMessage?: unknown
+  tags?: Record<string, string>
+  wake?: {
+    subscriberUrl: string
+    condition:
+      | 'runFinished'
+      | {
+          on: 'change'
+          collections?: string[]
+          ops?: Array<'insert' | 'update' | 'delete'>
+        }
+    debounceMs?: number
+    timeoutMs?: number
+    includeResponse?: boolean
+  }
+}
+```
+
+### getEntityInfo
+
+```ts
+const info = await client.getEntityInfo('/horton/onboarding')
+// { entityUrl, entityType, streamPath }
+```
+
+### deleteEntity
+
+```ts
+await client.deleteEntity('/horton/onboarding')
+```
+
+Deleting an already-missing entity is treated as success.
+
+## Messages
+
+```ts
+await client.sendEntityMessage({
+  targetUrl: '/horton/onboarding',
+  payload: 'What changed since last time?',
+  from: 'support-ui',
+  type: 'user_message',
+})
+```
+
+```ts
+interface SendEntityMessageOptions {
+  targetUrl: string
+  payload: unknown
+  from?: string
+  type?: string
+  afterMs?: number
+}
+```
+
+`afterMs` asks the server to deliver the message later.
+
+## Shared State
+
+```ts
+const streamPath = await client.ensureSharedStateStream('research-123')
+// "/_electric/shared-state/research-123"
+
+const samePath = client.getSharedStateStreamPath('research-123')
+```
+
+Use `ensureSharedStateStream()` when app code needs to create a shared-state stream before entities connect to it.
+
+## Wakes and Sources
+
+### registerWake
+
+`registerWake()` creates a wake subscription from one source stream to a subscriber entity.
+
+```ts
+await client.registerWake({
+  subscriberUrl: '/coordinator/research',
+  sourceUrl: '/worker/analyst/main',
+  condition: 'runFinished',
+  includeResponse: true,
+})
+```
+
+For change wakes:
+
+```ts
+await client.registerWake({
+  subscriberUrl: '/monitor/main',
+  sourceUrl: '/horton/onboarding/main',
+  condition: {
+    on: 'change',
+    collections: ['runs', 'texts'],
+    ops: ['insert', 'update'],
+  },
+  debounceMs: 250,
+})
+```
+
+### registerCronSource
+
+```ts
+const streamUrl = await client.registerCronSource('0 9 * * *', 'Europe/London')
+```
+
+### registerEntitiesSource
+
+```ts
+const source = await client.registerEntitiesSource({ project: 'docs' })
+// { streamUrl, sourceRef }
+```
+
+This is the lower-level operation behind observing `entities({ tags })`.
+
+## Schedules
+
+Schedules are stored on an entity manifest and return the write transaction id.
+
+```ts
+await client.upsertCronSchedule({
+  entityUrl: '/horton/onboarding',
+  id: 'daily-checkin',
+  expression: '0 9 * * *',
+  timezone: 'Europe/London',
+  payload: 'Run the daily check-in.',
+})
+
+await client.upsertFutureSendSchedule({
+  entityUrl: '/horton/onboarding',
+  id: 'follow-up',
+  fireAt: new Date(Date.now() + 60_000).toISOString(),
+  payload: 'Follow up now.',
+})
+
+await client.deleteSchedule({
+  entityUrl: '/horton/onboarding',
+  id: 'follow-up',
+})
+```
+
+## Tags
+
+`setTag()` and `removeTag()` require the entity write token. Handler code should prefer `ctx.setTag()` and `ctx.removeTag()` because the runtime already has the write token.
+
+```ts
+await client.setTag('/horton/onboarding', 'title', 'Onboarding', writeToken)
+await client.removeTag('/horton/onboarding', 'title', writeToken)
+```
+
+## Choosing a Client
+
+| API                            | Use when                                                                     |
+| ------------------------------ | ---------------------------------------------------------------------------- |
+| `ctx.spawn/send/observe`       | You are inside an entity handler.                                            |
+| `createAgentsClient()`         | You need to observe streams and drive UI state.                              |
+| `createRuntimeServerClient()`  | You need to manage entities, messages, wakes, schedules, or tags externally. |
+| `electric-ax/entity-stream-db` | You need the CLI-style entity stream loader with `close()`.                  |

package/docs/usage/shared-state.md

@@ -0,0 +1,169 @@
+---
+title: Shared state
+titleTemplate: '... - Electric Agents'
+description: >-
+  Coordinate across entities with shared state streams, schema definition, and cross-entity reads and writes.
+outline: [2, 3]
+---
+
+# Shared state
+
+Shared state allows multiple entities to read and write the same collections. A parent entity creates a shared state stream, and children connect to it.
+
+## Schema definition
+
+Define a `SharedStateSchemaMap` — a record of collection names to their schemas:
+
+```ts
+const researchSchema = {
+  findings: {
+    schema: z.object({ key: z.string(), domain: z.string(), text: z.string() }),
+    type: 'shared:finding',
+    primaryKey: 'key',
+  },
+}
+```
+
+Each entry requires `type` and `primaryKey`. `schema` is optional but recommended for validation. The `type` is the event type string written to the backing durable stream.
+
+## Creating shared state
+
+The parent entity creates the shared DB stream, typically on `firstWake`:
+
+```ts
+if (ctx.firstWake) {
+  ctx.mkdb('research-123', researchSchema)
+}
+const shared = await ctx.observe(db('research-123', researchSchema))
+```
+
+`mkdb` creates the backing stream. It throws if the DB already exists — creation is always a one-time operation guarded by `firstWake` or your own state checks.
+
+`observe(db(id, schema))` returns a handle for reading and writing. Call it on any wake to get a handle to an existing shared DB.
+
+`observe` accepts an optional `wake` option to re-wake the entity when the shared state changes:
+
+```ts
+const shared = await ctx.observe(db('research-123', researchSchema), {
+  wake: { on: 'change', debounceMs: 500 },
+})
+```
+
+## Connecting from children
+
+Pass the shared DB config to children via spawn args:
+
+```ts
+const child = await ctx.spawn(
+  'worker',
+  'specialist-1',
+  {
+    systemPrompt: '...',
+    sharedDb: { id: 'research-123', schema: researchSchema },
+  },
+  { initialMessage: 'Research topic X', wake: 'runFinished' }
+)
+```
+
+The child entity connects using the args it receives:
+
+```ts
+async handler(ctx) {
+  const args = ctx.args as { sharedDb: { id: string; schema: SharedStateSchemaMap } }
+  const shared = await ctx.observe(db(args.sharedDb.id, args.sharedDb.schema))
+  // Use shared.findings to read and write
+}
+```
+
+## Using the handle
+
+`SharedStateHandle` exposes collection proxies via `StateCollectionProxy` (the same insert/update/delete/get/toArray API):
+
+```ts
+// Insert
+shared.findings.insert({
+  key: 'f1',
+  domain: 'physics',
+  text: 'Finding text...',
+})
+
+// Read
+shared.findings.get('f1')
+shared.findings.toArray
+
+// Update
+shared.findings.update('f1', (draft) => {
+  draft.text = 'Updated'
+})
+
+// Delete
+shared.findings.delete('f1')
+```
+
+## SharedStateHandle type
+
+```ts
+type SharedStateHandle<TSchema extends SharedStateSchemaMap> = {
+  id: string
+} & { [K in keyof TSchema]: StateCollectionProxy }
+```
+
+The `id` property holds the stream identifier. Each key from the schema map becomes a `StateCollectionProxy`.
+
+## Example: debate pattern
+
+The debate pattern uses shared state for pro/con arguments. A moderator creates the stream, spawns workers for each side, and reads all arguments to make a ruling.
+
+```ts
+const debateSchema = {
+  arguments: {
+    schema: z.object({
+      key: z.string(),
+      side: z.enum(['pro', 'con']),
+      text: z.string(),
+      round: z.number(),
+    }),
+    type: 'shared:argument',
+    primaryKey: 'key',
+  },
+}
+
+registry.define('debate', {
+  state: {
+    status: { primaryKey: 'key' },
+  },
+
+  async handler(ctx) {
+    if (ctx.firstWake) {
+      ctx.mkdb(`debate-${ctx.entityUrl}`, debateSchema)
+    }
+    const shared = await ctx.observe(
+      db(`debate-${ctx.entityUrl}`, debateSchema)
+    )
+
+    // Spawn pro and con workers with shared state access
+    const pro = await ctx.spawn(
+      'worker',
+      'debate-pro',
+      {
+        systemPrompt: 'Argue FOR the topic.',
+        sharedDb: { id: `debate-${ctx.entityUrl}`, schema: debateSchema },
+      },
+      { initialMessage: 'The topic is: ...', wake: 'runFinished' }
+    )
+
+    const con = await ctx.spawn(
+      'worker',
+      'debate-con',
+      {
+        systemPrompt: 'Argue AGAINST the topic.',
+        sharedDb: { id: `debate-${ctx.entityUrl}`, schema: debateSchema },
+      },
+      { initialMessage: 'The topic is: ...', wake: 'runFinished' }
+    )
+
+    // Read all arguments written by both workers
+    const allArgs = shared.arguments.toArray
+  },
+})
+```