@electric-ax/agents 0.3.0 → 0.4.1

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.
Files changed (12) hide show
  1. package/dist/entrypoint.js +225 -209
  2. package/dist/index.cjs +223 -205
  3. package/dist/index.d.cts +21 -11
  4. package/dist/index.d.ts +22 -12
  5. package/dist/index.js +224 -206
  6. package/docs/index.md +3 -3
  7. package/docs/reference/built-in-collections.md +1 -1
  8. package/docs/reference/wake-event.md +4 -4
  9. package/docs/usage/spawning-and-coordinating.md +1 -1
  10. package/docs/usage/waking-entities.md +5 -5
  11. package/docs/usage/writing-handlers.md +1 -1
  12. package/package.json +5 -5
package/docs/reference/wake-event.md CHANGED
@@ -30,7 +30,7 @@ type WakeEvent = {
30
30
  | Field | Type | Description |
31
31
  | ------------ | --------- | ------------------------------------------------------------------------ |
32
32
  | `source` | `string` | URL or identifier of the stream that triggered the wake. |
33
- | `type` | `string` | Wake type. Usually `"message_received"` or `"wake"`; fallback webhook events can use `triggerEvent` or `"message"`. See catalog. |
33
+ | `type` | `string` | Wake type. Usually `"inbox"` or `"wake"`; fallback webhook events can use `triggerEvent` or `"message"`. See catalog. |
34
34
  | `fromOffset` | `number` | Start offset of new events in the source stream. |
35
35
  | `toOffset` | `number` | End offset (exclusive) of new events. |
36
36
  | `eventCount` | `number` | Number of new events in this wake. |
@@ -40,9 +40,9 @@ type WakeEvent = {
40
40
 
41
41
  ## Wake-type catalog
42
42
 
43
- Handlers usually see two values for `wake.type`. Direct inbox messages arrive as `"message_received"`. Most non-message triggers are flattened into `"wake"`, with the specifics carried on `wake.payload`. Low-level webhook fallbacks can surface `triggerEvent` directly, or `"message"` when no trigger event is provided.
43
+ Handlers usually see two values for `wake.type`. Direct inbox messages arrive as `"inbox"`. Most non-message triggers are flattened into `"wake"`, with the specifics carried on `wake.payload`. Low-level webhook fallbacks can surface `triggerEvent` directly, or `"message"` when no trigger event is provided.
44
44
 
45
- ### `"message_received"`
45
+ ### `"inbox"`
46
46
 
47
47
  An external message landed in the entity's inbox — from `ctx.send()`, the CLI's `electric agents send`, or any direct `/send` HTTP call.
48
48
 
@@ -89,7 +89,7 @@ Inspect the payload to distinguish the sub-kind:
89
89
  | Observed change | `ctx.observe(..., { wake: { on: 'change' } })` or `observe(db(...))` | `payload.changes` is non-empty |
90
90
  | Shared-state change | `await ctx.observe(db(...), { wake: { on: 'change' } })` | `payload.changes` is non-empty, `payload.source` identifies the shared-state stream |
91
91
  | Cron fired | A cron schedule entry on the entity's manifest | `payload.source` identifies the schedule; `payload.changes` is empty |
92
- | Scheduled send | A `future_send` schedule fires | Arrives as `"message_received"` (not `"wake"`) — the schedule produces a message delivery |
92
+ | Scheduled send | A `future_send` schedule fires | Arrives as `"inbox"` (not `"wake"`) — the schedule produces a message delivery |
93
93
  | Timeout | `timeoutMs` on a `change` wake config elapsed with no changes | `payload.timeout === true`, `payload.changes` is empty |
94
94
 
95
95
  For the narrative on how these are produced, see [Waking entities](../usage/waking-entities).
package/docs/usage/spawning-and-coordinating.md CHANGED
@@ -129,7 +129,7 @@ async handler(ctx) {
129
129
 
130
130
  const analyst = await ctx.observe(entity("/worker/analyst"))
131
131
 
132
- if (wake.type === "message_received") {
132
+ if (wake.type === "inbox") {
133
133
  analyst.send(wake.payload)
134
134
  }
135
135
  }
package/docs/usage/waking-entities.md CHANGED
@@ -31,13 +31,13 @@ There are five things that can wake an entity:
31
31
 
32
32
  ### 1. An incoming message
33
33
 
34
- Any external `/send` (via the CLI, HTTP, or another entity's `ctx.send()`) appends a `message_received` event to the entity's stream, which wakes the handler:
34
+ Any external `/send` (via the CLI, HTTP, or another entity's `ctx.send()`) appends a `inbox` event to the entity's stream, which wakes the handler:
35
35
 
36
36
  ```ts
37
37
  ctx.send("/assistant/peer", { text: "hello" })
38
38
  ```
39
39
 
40
- The receiving handler sees `wake.type === "message_received"` and finds the payload on `wake.payload`.
40
+ The receiving handler sees `wake.type === "inbox"` and finds the payload on `wake.payload`.
41
41
 
42
42
  ### 2. A spawned child
43
43
 
@@ -97,7 +97,7 @@ The minimum useful pattern is to branch on `wake.type`:
97
97
 
98
98
  ```ts
99
99
  async handler(ctx, wake) {
100
- if (wake.type === "message_received") {
100
+ if (wake.type === "inbox") {
101
101
  // external input - reply, dispatch, etc.
102
102
  ctx.useAgent({ ... })
103
103
  await ctx.agent.run()
@@ -112,8 +112,8 @@ async handler(ctx, wake) {
112
112
 
113
113
  Two wake types reach handlers directly:
114
114
 
115
- - `"message_received"` — an external message was delivered to this entity's inbox.
116
- - `"wake"` — a synthesised wake for anything else (child finished, collection change, cron, timeout). The specifics are on `wake.payload`. A future-send schedule delivers a message, so it arrives as `"message_received"`.
115
+ - `"inbox"` — an external message was delivered to this entity's inbox.
116
+ - `"wake"` — a synthesised wake for anything else (child finished, collection change, cron, timeout). The specifics are on `wake.payload`. A future-send schedule delivers a message, so it arrives as `"inbox"`.
117
117
 
118
118
  For the full payload shape (`changes[]`, `finished_child`, `other_children`, `timeout`), see the [wake-type catalog](../reference/wake-event#wake-type-catalog) in the reference.
119
119
 
package/docs/usage/writing-handlers.md CHANGED
@@ -120,7 +120,7 @@ type WakeEvent = {
120
120
  | Field | Description |
121
121
  | ------------ | -------------------------------------------------------------- |
122
122
  | `source` | The stream or entity that caused the wake. |
123
- | `type` | The wake type: `"message_received"` for inbox messages or `"wake"` for child completion, observed changes, cron, and timeouts. |
123
+ | `type` | The wake type: `"inbox"` for inbox messages or `"wake"` for child completion, observed changes, cron, and timeouts. |
124
124
  | `fromOffset` | Start offset of the events that triggered this wake. |
125
125
  | `toOffset` | End offset of the events that triggered this wake. |
126
126
  | `eventCount` | Number of new events since last wake. |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@electric-ax/agents",
3
- "version": "0.3.0",
3
+ "version": "0.4.1",
4
4
  "description": "Built-in Electric Agents runtimes such as Horton and worker",
5
5
  "repository": {
6
6
  "type": "git",
@@ -28,18 +28,18 @@
28
28
  "./package.json": "./package.json"
29
29
  },
30
30
  "dependencies": {
31
- "@durable-streams/state": "npm:@electric-ax/durable-streams-state-beta@^0.3.1",
31
+ "@durable-streams/state": "https://pkg.pr.new/durable-streams/durable-streams/@durable-streams/state@350",
32
32
  "@mariozechner/pi-agent-core": "^0.70.2",
33
33
  "@mariozechner/pi-ai": "^0.70.2",
34
34
  "@sinclair/typebox": "^0.34.48",
35
- "better-sqlite3": "^11.10.0",
35
+ "better-sqlite3": "^12.9.0",
36
36
  "nanoid": "^3.3.11",
37
37
  "pino": "^10.3.1",
38
38
  "pino-pretty": "^13.0.0",
39
39
  "sqlite-vec": "^0.1.9",
40
40
  "zod": "^4.3.6",
41
- "@electric-ax/agents-mcp": "0.2.0",
42
- "@electric-ax/agents-runtime": "0.1.3"
41
+ "@electric-ax/agents-mcp": "0.2.2",
42
+ "@electric-ax/agents-runtime": "0.2.1"
43
43
  },
44
44
  "devDependencies": {
45
45
  "@types/better-sqlite3": "^7.6.13",