@electric-ax/agents 0.2.2 → 0.2.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/entrypoint.js +40 -12
- package/dist/index.cjs +40 -12
- package/dist/index.js +40 -12
- package/docs/entities/agents/coder.md +99 -0
- package/docs/entities/agents/horton.md +16 -13
- package/docs/entities/agents/worker.md +18 -18
- package/docs/entities/patterns/blackboard.md +6 -6
- package/docs/entities/patterns/dispatcher.md +1 -1
- package/docs/entities/patterns/manager-worker.md +1 -1
- package/docs/entities/patterns/map-reduce.md +1 -1
- package/docs/entities/patterns/pipeline.md +1 -1
- package/docs/entities/patterns/reactive-observers.md +2 -2
- package/docs/examples/playground.md +42 -26
- package/docs/index.md +23 -23
- package/docs/quickstart.md +13 -13
- package/docs/reference/agent-config.md +20 -12
- package/docs/reference/agent-tool.md +1 -1
- package/docs/reference/built-in-collections.md +21 -21
- package/docs/reference/cli.md +39 -30
- package/docs/reference/entity-definition.md +9 -9
- package/docs/reference/entity-handle.md +2 -2
- package/docs/reference/entity-registry.md +1 -1
- package/docs/reference/handler-context.md +69 -18
- package/docs/reference/runtime-handler.md +25 -23
- package/docs/reference/shared-state-handle.md +7 -7
- package/docs/reference/state-collection-proxy.md +1 -1
- package/docs/reference/wake-event.md +23 -23
- package/docs/usage/app-setup.md +24 -23
- package/docs/usage/clients-and-react.md +44 -36
- package/docs/usage/configuring-the-agent.md +25 -19
- package/docs/usage/context-composition.md +12 -12
- package/docs/usage/defining-entities.md +36 -36
- package/docs/usage/defining-tools.md +45 -45
- package/docs/usage/embedded-builtins.md +48 -47
- package/docs/usage/managing-state.md +12 -12
- package/docs/usage/overview.md +52 -45
- package/docs/usage/programmatic-runtime-client.md +50 -47
- package/docs/usage/shared-state.md +32 -32
- package/docs/usage/spawning-and-coordinating.md +9 -9
- package/docs/usage/testing.md +14 -14
- package/docs/usage/waking-entities.md +13 -13
- package/docs/usage/writing-handlers.md +57 -26
- package/package.json +5 -2
- package/scripts/sync-docs.mjs +42 -0
- package/skills/quickstart/scaffold/package.json +1 -0
- package/skills/quickstart/scaffold-ui/index.html +1 -1
- package/skills/quickstart/scaffold-ui/main.tsx +221 -16
- package/skills/quickstart.md +49 -94
- package/docs/examples/mega-draw.md +0 -106
package/docs/reference/cli.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: CLI
|
|
3
|
-
titleTemplate:
|
|
3
|
+
titleTemplate: "... - Electric Agents"
|
|
4
4
|
description: >-
|
|
5
5
|
Command reference for the Electric Agents CLI: spawn, send, observe, inspect, list, and manage entities.
|
|
6
6
|
outline: [2, 3]
|
|
@@ -16,14 +16,14 @@ npm install -g electric-ax
|
|
|
16
16
|
|
|
17
17
|
## Environment variables
|
|
18
18
|
|
|
19
|
-
| Variable
|
|
20
|
-
|
|
|
21
|
-
| `ELECTRIC_AGENTS_URL`
|
|
22
|
-
| `ELECTRIC_AGENTS_IDENTITY`
|
|
23
|
-
| `ELECTRIC_AGENTS_PORT`
|
|
24
|
-
| `ELECTRIC_AGENTS_BUILTIN_PORT`
|
|
25
|
-
| `ELECTRIC_AGENTS_COMPOSE_PROJECT` | `electric-agents` | Docker Compose project name
|
|
26
|
-
| `ANTHROPIC_API_KEY`
|
|
19
|
+
| Variable | Default | Purpose |
|
|
20
|
+
| -------------------------------- | ----------------------- | -------------------------------------------- |
|
|
21
|
+
| `ELECTRIC_AGENTS_URL` | `http://localhost:4437` | Server URL for entity commands and built-ins |
|
|
22
|
+
| `ELECTRIC_AGENTS_IDENTITY` | `user@hostname` | Sender identity for messages |
|
|
23
|
+
| `ELECTRIC_AGENTS_PORT` | `4437` | Port used by `start` / `quickstart` |
|
|
24
|
+
| `ELECTRIC_AGENTS_BUILTIN_PORT` | `4448` | Webhook port for `start-builtin` |
|
|
25
|
+
| `ELECTRIC_AGENTS_COMPOSE_PROJECT` | `electric-agents` | Docker Compose project name |
|
|
26
|
+
| `ANTHROPIC_API_KEY` | - | Required for `start-builtin` and `quickstart` |
|
|
27
27
|
|
|
28
28
|
## Commands
|
|
29
29
|
|
|
@@ -142,9 +142,9 @@ Start the built-in Horton runtime and register built-in agent types with the coo
|
|
|
142
142
|
electric agents start-builtin --anthropic-api-key sk-ant-...
|
|
143
143
|
```
|
|
144
144
|
|
|
145
|
-
| Option
|
|
146
|
-
|
|
|
147
|
-
| `--anthropic-api-key <key>`
|
|
145
|
+
| Option | Description |
|
|
146
|
+
| ------------------------------ | ---------------------------------------------- |
|
|
147
|
+
| `--anthropic-api-key <key>` | Anthropic API key for the built-in Horton server |
|
|
148
148
|
|
|
149
149
|
### <span class="cli-command"><code>quickstart [--anthropic-api-key <key>]</code></span> {#quickstart}
|
|
150
150
|
|
|
@@ -154,9 +154,9 @@ Start the coordinator server, print onboarding commands, and run the built-in ag
|
|
|
154
154
|
electric agents quickstart --anthropic-api-key sk-ant-...
|
|
155
155
|
```
|
|
156
156
|
|
|
157
|
-
| Option
|
|
158
|
-
|
|
|
159
|
-
| `--anthropic-api-key <key>`
|
|
157
|
+
| Option | Description |
|
|
158
|
+
| ------------------------------ | ---------------------------------------------- |
|
|
159
|
+
| `--anthropic-api-key <key>` | Anthropic API key for the built-in Horton server |
|
|
160
160
|
|
|
161
161
|
### <span class="cli-command"><code>stop [--remove-volumes]</code></span> {#stop}
|
|
162
162
|
|
|
@@ -171,6 +171,15 @@ electric agents stop --remove-volumes
|
|
|
171
171
|
| ------------------ | ------------------------------ |
|
|
172
172
|
| `--remove-volumes` | Remove Docker volumes as well. |
|
|
173
173
|
|
|
174
|
+
### <span class="cli-command"><code>init [project-name]</code></span> {#init-project-name}
|
|
175
|
+
|
|
176
|
+
Scaffold a new Electric Agents project from the bundled starter template.
|
|
177
|
+
|
|
178
|
+
```bash
|
|
179
|
+
electric agents init
|
|
180
|
+
electric agents init my-agents-app
|
|
181
|
+
```
|
|
182
|
+
|
|
174
183
|
### <span class="cli-command"><code>completion [action]</code></span> {#completion-action}
|
|
175
184
|
|
|
176
185
|
Set up shell completions. Without arguments, prints setup instructions.
|
|
@@ -202,32 +211,32 @@ import {
|
|
|
202
211
|
createElectricProgram,
|
|
203
212
|
getElectricCliEnv,
|
|
204
213
|
run,
|
|
205
|
-
} from
|
|
214
|
+
} from "electric-ax"
|
|
206
215
|
|
|
207
216
|
const env = getElectricCliEnv({
|
|
208
|
-
ELECTRIC_AGENTS_URL:
|
|
209
|
-
ELECTRIC_AGENTS_IDENTITY:
|
|
217
|
+
ELECTRIC_AGENTS_URL: "http://localhost:4437",
|
|
218
|
+
ELECTRIC_AGENTS_IDENTITY: "docs@example.com",
|
|
210
219
|
})
|
|
211
220
|
|
|
212
|
-
const handlers = createElectricCliHandlers(env,
|
|
221
|
+
const handlers = createElectricCliHandlers(env, "electric agents")
|
|
213
222
|
const program = createElectricProgram({
|
|
214
223
|
env,
|
|
215
224
|
handlers,
|
|
216
|
-
commandName:
|
|
217
|
-
commandPrefix:
|
|
225
|
+
commandName: "electric",
|
|
226
|
+
commandPrefix: "electric agents",
|
|
218
227
|
})
|
|
219
228
|
|
|
220
|
-
await program.parseAsync([
|
|
229
|
+
await program.parseAsync(["node", "electric", "agents", "types"])
|
|
221
230
|
```
|
|
222
231
|
|
|
223
|
-
| Export
|
|
224
|
-
|
|
|
225
|
-
| `DEFAULT_ELECTRIC_AGENTS_URL`
|
|
226
|
-
| `getElectricCliEnv(env?)`
|
|
227
|
-
| `createElectricCliHandlers()`
|
|
228
|
-
| `createElectricProgram()`
|
|
229
|
-
| `resolveCommandPrefix(argv, env?)` | Resolves help text examples for direct or package-manager invocation.
|
|
230
|
-
| `run(argv?)`
|
|
232
|
+
| Export | Purpose |
|
|
233
|
+
| --------------------------------- | ------------------------------------------------------------------------ |
|
|
234
|
+
| `DEFAULT_ELECTRIC_AGENTS_URL` | Default server URL (`"http://localhost:4437"`). |
|
|
235
|
+
| `getElectricCliEnv(env?)` | Reads `ELECTRIC_AGENTS_URL` and `ELECTRIC_AGENTS_IDENTITY`. |
|
|
236
|
+
| `createElectricCliHandlers()` | Creates the default command handlers. |
|
|
237
|
+
| `createElectricProgram()` | Creates the Commander program. |
|
|
238
|
+
| `resolveCommandPrefix(argv, env?)` | Resolves help text examples for direct or package-manager invocation. |
|
|
239
|
+
| `run(argv?)` | Runs the CLI entrypoint. |
|
|
231
240
|
|
|
232
241
|
The installed binaries are `electric` and `electric-ax`. The package also includes `electric-dev` for development workflows.
|
|
233
242
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: EntityDefinition
|
|
3
|
-
titleTemplate:
|
|
3
|
+
titleTemplate: "... - Electric Agents"
|
|
4
4
|
description: >-
|
|
5
5
|
Type reference for EntityDefinition: description, state, schemas, and handler function signature.
|
|
6
6
|
outline: [2, 3]
|
|
@@ -28,15 +28,15 @@ interface EntityDefinition {
|
|
|
28
28
|
|
|
29
29
|
## Fields
|
|
30
30
|
|
|
31
|
-
| Field | Type | Required | Description
|
|
32
|
-
| ---------------- | ---------------------------------------------------- | -------- |
|
|
33
|
-
| `description` | `string` | No | Human-readable description of the entity type. Used in type registration.
|
|
34
|
-
| `state` | `Record<string, CollectionDefinition>` | No | Custom state collections exposed via `ctx.db.actions` (writes) and `ctx.db.collections` (reads).
|
|
31
|
+
| Field | Type | Required | Description |
|
|
32
|
+
| ---------------- | ---------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------ |
|
|
33
|
+
| `description` | `string` | No | Human-readable description of the entity type. Used in type registration. |
|
|
34
|
+
| `state` | `Record<string, CollectionDefinition>` | No | Custom state collections exposed via `ctx.db.actions` (writes) and `ctx.db.collections` (reads). |
|
|
35
35
|
| `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`. |
|
|
36
|
-
| `creationSchema` | `StandardJSONSchemaV1` | No | JSON Schema for spawn arguments validation.
|
|
37
|
-
| `inboxSchemas` | `Record<string, StandardJSONSchemaV1>` | No | JSON Schemas for inbound message types, keyed by message type.
|
|
38
|
-
| `outputSchemas` | `Record<string, StandardJSONSchemaV1>` | No | JSON Schemas for output event types. Defaults are provided by the runtime.
|
|
39
|
-
| `handler` | `(ctx, wake) => void \| Promise<void>` | Yes | The function invoked on each wake. Receives [`HandlerContext`](./handler-context) and [`WakeEvent`](./wake-event).
|
|
36
|
+
| `creationSchema` | `StandardJSONSchemaV1` | No | JSON Schema for spawn arguments validation. |
|
|
37
|
+
| `inboxSchemas` | `Record<string, StandardJSONSchemaV1>` | No | JSON Schemas for inbound message types, keyed by message type. |
|
|
38
|
+
| `outputSchemas` | `Record<string, StandardJSONSchemaV1>` | No | JSON Schemas for output event types. Defaults are provided by the runtime. |
|
|
39
|
+
| `handler` | `(ctx, wake) => void \| Promise<void>` | Yes | The function invoked on each wake. Receives [`HandlerContext`](./handler-context) and [`WakeEvent`](./wake-event). |
|
|
40
40
|
|
|
41
41
|
## CollectionDefinition
|
|
42
42
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: EntityHandle
|
|
3
|
-
titleTemplate:
|
|
3
|
+
titleTemplate: "... - Electric Agents"
|
|
4
4
|
description: >-
|
|
5
5
|
API reference for EntityHandle returned by spawn and observe: streams, status, text retrieval, and messaging.
|
|
6
6
|
outline: [2, 3]
|
|
@@ -49,7 +49,7 @@ interface ChildStatusEntry {
|
|
|
49
49
|
key: string
|
|
50
50
|
entity_url: string
|
|
51
51
|
entity_type: string
|
|
52
|
-
status:
|
|
52
|
+
status: "spawning" | "running" | "idle" | "stopped"
|
|
53
53
|
}
|
|
54
54
|
```
|
|
55
55
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: HandlerContext
|
|
3
|
-
titleTemplate:
|
|
3
|
+
titleTemplate: "... - Electric Agents"
|
|
4
4
|
description: >-
|
|
5
5
|
API reference for HandlerContext: state, coordination, agent configuration, and execution control.
|
|
6
6
|
outline: [2, 3]
|
|
@@ -44,11 +44,11 @@ interface HandlerContext<TState extends StateProxy = StateProxy> {
|
|
|
44
44
|
}
|
|
45
45
|
): Promise<EntityHandle>
|
|
46
46
|
observe(
|
|
47
|
-
source: ObservationSource & { sourceType:
|
|
47
|
+
source: ObservationSource & { sourceType: "entity" },
|
|
48
48
|
opts?: { wake?: Wake }
|
|
49
49
|
): Promise<EntityHandle>
|
|
50
50
|
observe(
|
|
51
|
-
source: ObservationSource & { sourceType:
|
|
51
|
+
source: ObservationSource & { sourceType: "db" },
|
|
52
52
|
opts?: { wake?: Wake }
|
|
53
53
|
): Promise<SharedStateHandle & ObservationHandle>
|
|
54
54
|
observe(
|
|
@@ -59,11 +59,16 @@ interface HandlerContext<TState extends StateProxy = StateProxy> {
|
|
|
59
59
|
id: string,
|
|
60
60
|
schema: T
|
|
61
61
|
): SharedStateHandle<T>
|
|
62
|
+
useCodingAgent(
|
|
63
|
+
sessionId: string,
|
|
64
|
+
opts: UseCodingAgentOptions
|
|
65
|
+
): Promise<CodingSessionHandle>
|
|
62
66
|
send(
|
|
63
67
|
entityUrl: string,
|
|
64
68
|
payload: unknown,
|
|
65
69
|
opts?: { type?: string; afterMs?: number }
|
|
66
70
|
): void
|
|
71
|
+
recordRun(): RunHandle
|
|
67
72
|
setTag(key: string, value: string): Promise<void>
|
|
68
73
|
removeTag(key: string): Promise<void>
|
|
69
74
|
sleep(): void
|
|
@@ -74,27 +79,27 @@ interface HandlerContext<TState extends StateProxy = StateProxy> {
|
|
|
74
79
|
|
|
75
80
|
## Properties
|
|
76
81
|
|
|
77
|
-
| Property
|
|
78
|
-
|
|
|
79
|
-
| `firstWake`
|
|
80
|
-
| `tags`
|
|
81
|
-
| `entityUrl`
|
|
82
|
-
| `entityType`
|
|
83
|
-
| `args`
|
|
84
|
-
| `db`
|
|
85
|
-
| `state`
|
|
86
|
-
| `events`
|
|
87
|
-
| `actions`
|
|
88
|
-
| `electricTools` | `AgentTool[]` | Host-provided runtime-level tools to spread into agent config when needed. May be empty.
|
|
82
|
+
| Property | Type | Description |
|
|
83
|
+
| ------------ | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
|
|
84
|
+
| `firstWake` | `boolean` | `true` during the initial setup pass while the entity has no persisted manifest entries. Use state checks for one-time plain state initialization. |
|
|
85
|
+
| `tags` | `Readonly<EntityTags>` | Entity tags — key/value metadata associated with this entity. |
|
|
86
|
+
| `entityUrl` | `string` | URL path of this entity (e.g. `"/chat/my-convo"`). |
|
|
87
|
+
| `entityType` | `string` | Registered type name (e.g. `"chat"`). |
|
|
88
|
+
| `args` | `Readonly<Record<string, unknown>>` | Spawn arguments passed when the entity was created. |
|
|
89
|
+
| `db` | `EntityStreamDBWithActions` | The entity's TanStack DB instance with registered actions. |
|
|
90
|
+
| `state` | `TState` | Proxy object keyed by collection name. Each property is a [`StateCollectionProxy`](./state-collection-proxy). |
|
|
91
|
+
| `events` | `Array<ChangeEvent>` | Change events that triggered this wake. |
|
|
92
|
+
| `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`. |
|
|
93
|
+
| `electricTools` | `AgentTool[]` | Host-provided runtime-level tools to spread into agent config when needed. May be empty. |
|
|
89
94
|
|
|
90
95
|
## Methods
|
|
91
96
|
|
|
92
97
|
| Method | Return Type | Description |
|
|
93
98
|
| --------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
94
99
|
| `useAgent(config)` | `AgentHandle` | Configure the LLM agent. Must be called before `agent.run()`. See [`AgentConfig`](./agent-config). |
|
|
95
|
-
| `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).
|
|
96
|
-
| `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).
|
|
97
|
-
| `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).
|
|
100
|
+
| `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). |
|
|
101
|
+
| `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). |
|
|
102
|
+
| `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). |
|
|
98
103
|
| `removeContext(id)` | `void` | Remove a context entry by id. |
|
|
99
104
|
| `getContext(id)` | `ContextEntry \| undefined` | Get a context entry by id, or `undefined` if not found. |
|
|
100
105
|
| `listContext()` | `Array<ContextEntry>` | List all context entries. |
|
|
@@ -102,7 +107,53 @@ interface HandlerContext<TState extends StateProxy = StateProxy> {
|
|
|
102
107
|
| `spawn(type, id, args?, opts?)` | `Promise<EntityHandle>` | Spawn a child entity. `opts` accepts `tags`, `observe`, `initialMessage`, and `wake`. See [`EntityHandle`](./entity-handle). |
|
|
103
108
|
| `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. |
|
|
104
109
|
| `mkdb(id, schema)` | `SharedStateHandle<T>` | Create a new shared state stream. See [`SharedStateHandle`](./shared-state-handle). |
|
|
110
|
+
| `useCodingAgent(sessionId, opts)` | `Promise<CodingSessionHandle>` | Spawn or attach to the built-in `coder` entity for a Claude Code or Codex CLI session. Requires the `coder` type to be registered. |
|
|
105
111
|
| `send(entityUrl, payload, opts?)` | `void` | Send a message to another entity. `opts` accepts `type` and `afterMs` (delay in milliseconds). |
|
|
112
|
+
| `recordRun()` | `RunHandle` | Record a non-LLM run in the built-in `runs` collection, so observers using `wake: "runFinished"` are notified when external work completes. |
|
|
106
113
|
| `setTag(key, value)` | `Promise<void>` | Set a tag on this entity. |
|
|
107
114
|
| `removeTag(key)` | `Promise<void>` | Remove a tag from this entity. |
|
|
108
115
|
| `sleep()` | `void` | End the handler without running an agent. The entity remains idle until the next wake. |
|
|
116
|
+
|
|
117
|
+
## Coding sessions
|
|
118
|
+
|
|
119
|
+
`useCodingAgent()` is a convenience wrapper around the built-in `coder` entity type.
|
|
120
|
+
|
|
121
|
+
```ts
|
|
122
|
+
type CodingAgentType = "claude" | "codex"
|
|
123
|
+
|
|
124
|
+
interface UseCodingAgentOptions {
|
|
125
|
+
agent: CodingAgentType
|
|
126
|
+
nativeSessionId?: string
|
|
127
|
+
importFrom?: { agent: CodingAgentType; sessionId: string }
|
|
128
|
+
cwd?: string
|
|
129
|
+
wake?: Wake
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
interface CodingSessionHandle {
|
|
133
|
+
readonly entityUrl: string
|
|
134
|
+
readonly sessionId: string
|
|
135
|
+
readonly agent: CodingAgentType
|
|
136
|
+
meta(): CodingSessionMeta | undefined
|
|
137
|
+
status(): "initializing" | "idle" | "running" | "error" | undefined
|
|
138
|
+
run: Promise<void>
|
|
139
|
+
send(prompt: string): void
|
|
140
|
+
readonly events: ReadonlyArray<CodingSessionEventRow>
|
|
141
|
+
readonly messages: ReadonlyArray<CodingSessionEventRow>
|
|
142
|
+
}
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
By default, `useCodingAgent()` observes the coder with `wake: "runFinished"`, so the caller wakes when a prompt finishes. Pass a change wake if you need per-event updates.
|
|
146
|
+
|
|
147
|
+
## RunHandle
|
|
148
|
+
|
|
149
|
+
`recordRun()` is for handlers that perform work outside `ctx.agent.run()` but still want to expose run lifecycle events.
|
|
150
|
+
|
|
151
|
+
```ts
|
|
152
|
+
interface RunHandle {
|
|
153
|
+
readonly key: string
|
|
154
|
+
end(opts: { status: "completed" | "failed"; finishReason?: string }): void
|
|
155
|
+
attachResponse(text: string): void
|
|
156
|
+
}
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
`attachResponse()` appends text deltas linked to the run, which can be included in `runFinished` wake payloads.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: RuntimeHandler
|
|
3
|
-
titleTemplate:
|
|
3
|
+
titleTemplate: "... - Electric Agents"
|
|
4
4
|
description: >-
|
|
5
5
|
API reference for RuntimeHandler: webhook handling, type registration, and deployment configuration.
|
|
6
6
|
outline: [2, 3]
|
|
@@ -28,16 +28,16 @@ interface RuntimeRouter {
|
|
|
28
28
|
}
|
|
29
29
|
```
|
|
30
30
|
|
|
31
|
-
| Method | Return Type | Description
|
|
32
|
-
| ----------------------------------- | --------------------------- |
|
|
33
|
-
| `handleRequest(request)` | `Promise<Response \| null>` | Route a fetch `Request`. Returns `null` if the request path does not match `webhookPath`.
|
|
34
|
-
| `handleWebhookRequest(request)` | `Promise<Response>` | Handle a webhook request directly, without route matching.
|
|
35
|
-
| `dispatchWebhookWake(notification)` | `void` | Dispatch an already-parsed webhook notification. Runs the wake handler in the background.
|
|
36
|
-
| `drainWakes()` | `Promise<void>` | Wait for all in-flight wake handlers to settle. Throws if any wake errored.
|
|
37
|
-
| `waitForSettled()` | `Promise<void>` | Wait for all in-flight wake handlers to settle.
|
|
38
|
-
| `abortWakes()` | `void` | Abort in-flight wakes so host shutdown can complete quickly.
|
|
39
|
-
| `debugState()` | `RuntimeDebugState` | Return a runtime-local snapshot for tests and shutdown diagnostics.
|
|
40
|
-
| `typeNames` | `string[]` | Names of all registered entity types (read-only).
|
|
31
|
+
| Method | Return Type | Description |
|
|
32
|
+
| ----------------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------- |
|
|
33
|
+
| `handleRequest(request)` | `Promise<Response \| null>` | Route a fetch `Request`. Returns `null` if the request path does not match `webhookPath`. |
|
|
34
|
+
| `handleWebhookRequest(request)` | `Promise<Response>` | Handle a webhook request directly, without route matching. |
|
|
35
|
+
| `dispatchWebhookWake(notification)` | `void` | Dispatch an already-parsed webhook notification. Runs the wake handler in the background. |
|
|
36
|
+
| `drainWakes()` | `Promise<void>` | Wait for all in-flight wake handlers to settle. Throws if any wake errored. |
|
|
37
|
+
| `waitForSettled()` | `Promise<void>` | Wait for all in-flight wake handlers to settle. |
|
|
38
|
+
| `abortWakes()` | `void` | Abort in-flight wakes so host shutdown can complete quickly. |
|
|
39
|
+
| `debugState()` | `RuntimeDebugState` | Return a runtime-local snapshot for tests and shutdown diagnostics. |
|
|
40
|
+
| `typeNames` | `string[]` | Names of all registered entity types (read-only). |
|
|
41
41
|
| `registerTypes()` | `Promise<void>` | Register all entity types with the Electric Agents runtime server. Uses upsert semantics — safe to call on every startup. |
|
|
42
42
|
|
|
43
43
|
## RuntimeHandler
|
|
@@ -89,6 +89,7 @@ interface RuntimeRouterConfig {
|
|
|
89
89
|
baseUrl: string
|
|
90
90
|
serveEndpoint?: string
|
|
91
91
|
webhookPath?: string
|
|
92
|
+
handlerUrl?: string
|
|
92
93
|
registry?: EntityRegistry
|
|
93
94
|
subscriptionPathForType?: (typeName: string) => string
|
|
94
95
|
idleTimeout?: number
|
|
@@ -122,15 +123,16 @@ interface RuntimeRouterConfig {
|
|
|
122
123
|
}
|
|
123
124
|
```
|
|
124
125
|
|
|
125
|
-
| Field | Type
|
|
126
|
-
| ------------------------- |
|
|
127
|
-
| `baseUrl` | `string`
|
|
128
|
-
| `serveEndpoint` | `string`
|
|
129
|
-
| `webhookPath` | `string`
|
|
130
|
-
| `
|
|
131
|
-
| `
|
|
132
|
-
| `
|
|
133
|
-
| `
|
|
134
|
-
| `
|
|
135
|
-
| `
|
|
136
|
-
| `
|
|
126
|
+
| Field | Type | Default | Description |
|
|
127
|
+
| ------------------------- | ------------------------------------------------------------- | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
|
|
128
|
+
| `baseUrl` | `string` | - | Base URL of the Electric Agents runtime server (e.g. `"http://localhost:4437"`). Required. |
|
|
129
|
+
| `serveEndpoint` | `string` | - | Full webhook callback URL exposed by your app. Used for type registration. |
|
|
130
|
+
| `webhookPath` | `string` | pathname from `serveEndpoint` / `handlerUrl`, or `"/electric-agents"` | Path matched by `handleRequest()`. |
|
|
131
|
+
| `handlerUrl` | `string` | - | Backward-compatible alias for `serveEndpoint`; prefer `serveEndpoint` in new code. |
|
|
132
|
+
| `registry` | `EntityRegistry` | default registry | Entity registry for this handler. Falls back to the module-level default registry. |
|
|
133
|
+
| `subscriptionPathForType` | `(typeName: string) => string` | - | Override the webhook subscription path used per entity type registration. |
|
|
134
|
+
| `idleTimeout` | `number` | `20000` | Idle timeout in milliseconds before closing a wake. |
|
|
135
|
+
| `heartbeatInterval` | `number` | `30000` | Heartbeat interval in milliseconds. |
|
|
136
|
+
| `createElectricTools` | `(context) => AgentTool[] \| Promise<...>` | - | Optional tool factory invoked for each wake context before handler execution. Provides extra tools to the agent. |
|
|
137
|
+
| `onWakeError` | `(error: Error) => boolean \| void` | - | Observer for background wake failures. Return `true` to mark the error as handled so it is not rethrown on drain. |
|
|
138
|
+
| `registrationConcurrency` | `number` | `8` | Max number of concurrent entity-type registrations. |
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: SharedStateHandle
|
|
3
|
-
titleTemplate:
|
|
3
|
+
titleTemplate: "... - Electric Agents"
|
|
4
4
|
description: >-
|
|
5
5
|
Type reference for SharedStateHandle: collection proxies and SharedStateSchemaMap interface.
|
|
6
6
|
outline: [2, 3]
|
|
@@ -54,7 +54,7 @@ interface SharedStateCollectionSchema {
|
|
|
54
54
|
## Example
|
|
55
55
|
|
|
56
56
|
```ts
|
|
57
|
-
import { db } from
|
|
57
|
+
import { db } from "@electric-ax/agents-runtime"
|
|
58
58
|
|
|
59
59
|
const schema = {
|
|
60
60
|
findings: {
|
|
@@ -63,12 +63,12 @@ const schema = {
|
|
|
63
63
|
domain: z.string(),
|
|
64
64
|
finding: z.string(),
|
|
65
65
|
}),
|
|
66
|
-
type:
|
|
67
|
-
primaryKey:
|
|
66
|
+
type: "finding",
|
|
67
|
+
primaryKey: "key",
|
|
68
68
|
},
|
|
69
69
|
}
|
|
70
70
|
|
|
71
|
-
ctx.mkdb(
|
|
72
|
-
const shared = await ctx.observe(db(
|
|
73
|
-
shared.findings.insert({ key:
|
|
71
|
+
ctx.mkdb("research-findings", schema)
|
|
72
|
+
const shared = await ctx.observe(db("research-findings", schema))
|
|
73
|
+
shared.findings.insert({ key: "f1", domain: "security", finding: "..." })
|
|
74
74
|
```
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: WakeEvent
|
|
3
|
-
titleTemplate:
|
|
3
|
+
titleTemplate: "... - Electric Agents"
|
|
4
4
|
description: >-
|
|
5
5
|
Type reference for WakeEvent and Wake configuration: runFinished and change-based wake conditions.
|
|
6
6
|
outline: [2, 3]
|
|
@@ -27,16 +27,16 @@ type WakeEvent = {
|
|
|
27
27
|
|
|
28
28
|
## Fields
|
|
29
29
|
|
|
30
|
-
| Field | Type | Description
|
|
31
|
-
| ------------ | --------- |
|
|
32
|
-
| `source` | `string` | URL or identifier of the stream that triggered the wake.
|
|
30
|
+
| Field | Type | Description |
|
|
31
|
+
| ------------ | --------- | ------------------------------------------------------------------------ |
|
|
32
|
+
| `source` | `string` | URL or identifier of the stream that triggered the wake. |
|
|
33
33
|
| `type` | `string` | Wake type. Usually `"message_received"` or `"wake"`; fallback webhook events can use `triggerEvent` or `"message"`. See catalog. |
|
|
34
|
-
| `fromOffset` | `number` | Start offset of new events in the source stream.
|
|
35
|
-
| `toOffset` | `number` | End offset (exclusive) of new events.
|
|
36
|
-
| `eventCount` | `number` | Number of new events in this wake.
|
|
37
|
-
| `payload` | `unknown` | Optional payload data associated with the wake. Shape depends on `type`.
|
|
38
|
-
| `summary` | `string` | Optional human-readable summary of the wake reason.
|
|
39
|
-
| `fullRef` | `string` | Optional full reference identifier for the wake source.
|
|
34
|
+
| `fromOffset` | `number` | Start offset of new events in the source stream. |
|
|
35
|
+
| `toOffset` | `number` | End offset (exclusive) of new events. |
|
|
36
|
+
| `eventCount` | `number` | Number of new events in this wake. |
|
|
37
|
+
| `payload` | `unknown` | Optional payload data associated with the wake. Shape depends on `type`. |
|
|
38
|
+
| `summary` | `string` | Optional human-readable summary of the wake reason. |
|
|
39
|
+
| `fullRef` | `string` | Optional full reference identifier for the wake source. |
|
|
40
40
|
|
|
41
41
|
## Wake-type catalog
|
|
42
42
|
|
|
@@ -63,20 +63,20 @@ type WakeMessage = {
|
|
|
63
63
|
timeout: boolean
|
|
64
64
|
changes: Array<{
|
|
65
65
|
collection: string
|
|
66
|
-
kind:
|
|
66
|
+
kind: "insert" | "update" | "delete"
|
|
67
67
|
key: string
|
|
68
68
|
}>
|
|
69
69
|
finished_child?: {
|
|
70
70
|
url: string
|
|
71
71
|
type: string
|
|
72
|
-
run_status:
|
|
72
|
+
run_status: "completed" | "failed"
|
|
73
73
|
response?: string
|
|
74
74
|
error?: string
|
|
75
75
|
}
|
|
76
76
|
other_children?: Array<{
|
|
77
77
|
url: string
|
|
78
78
|
type: string
|
|
79
|
-
status:
|
|
79
|
+
status: "spawning" | "running" | "idle" | "stopped"
|
|
80
80
|
}>
|
|
81
81
|
}
|
|
82
82
|
```
|
|
@@ -100,12 +100,12 @@ The `Wake` type configures when a parent should be woken in response to a child,
|
|
|
100
100
|
|
|
101
101
|
```ts
|
|
102
102
|
type Wake =
|
|
103
|
-
|
|
|
104
|
-
| { on:
|
|
103
|
+
| "runFinished"
|
|
104
|
+
| { on: "runFinished"; includeResponse?: boolean }
|
|
105
105
|
| {
|
|
106
|
-
on:
|
|
106
|
+
on: "change"
|
|
107
107
|
collections?: string[]
|
|
108
|
-
ops?: (
|
|
108
|
+
ops?: ("insert" | "update" | "delete")[]
|
|
109
109
|
debounceMs?: number
|
|
110
110
|
timeoutMs?: number
|
|
111
111
|
}
|
|
@@ -123,10 +123,10 @@ Object form of `runFinished` with options. Set `includeResponse: false` to omit
|
|
|
123
123
|
|
|
124
124
|
Wake the parent when changes occur in the observed stream.
|
|
125
125
|
|
|
126
|
-
| Field | Type | Description
|
|
127
|
-
| ------------- | ---------- |
|
|
128
|
-
| `on` | `'change'` | Required discriminant.
|
|
129
|
-
| `collections` | `string[]` | Optional filter. Only wake on changes to these collections.
|
|
126
|
+
| Field | Type | Description |
|
|
127
|
+
| ------------- | ---------- | ------------------------------------------------------------- |
|
|
128
|
+
| `on` | `'change'` | Required discriminant. |
|
|
129
|
+
| `collections` | `string[]` | Optional filter. Only wake on changes to these collections. |
|
|
130
130
|
| `ops` | `string[]` | Optional operation filter: `"insert"`, `"update"`, and/or `"delete"`. |
|
|
131
|
-
| `debounceMs` | `number` | Debounce interval in milliseconds. Batches rapid changes.
|
|
132
|
-
| `timeoutMs` | `number` | Maximum time to wait before waking, even if no changes occur.
|
|
131
|
+
| `debounceMs` | `number` | Debounce interval in milliseconds. Batches rapid changes. |
|
|
132
|
+
| `timeoutMs` | `number` | Maximum time to wait before waking, even if no changes occur. |
|