@electric-ax/agents 0.2.3 → 0.3.0

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

@@ -1,6 +1,6 @@
 ---
 title: Programmatic runtime client
-titleTemplate: '... - Electric Agents'
+titleTemplate: "... - Electric Agents"
 description: >-
   Use createRuntimeServerClient to spawn entities, send messages, register wakes,
   manage schedules, and connect shared state from application code.
@@ -12,10 +12,10 @@ outline: [2, 3]
 `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'
+import { createRuntimeServerClient } from "@electric-ax/agents-runtime"
 
 const client = createRuntimeServerClient({
-  baseUrl: 'http://localhost:4437',
+  baseUrl: "http://localhost:4437",
 })
 ```
 
@@ -41,11 +41,11 @@ interface RuntimeServerClientConfig {
 
 ```ts
 const info = await client.spawnEntity({
-  type: 'horton',
-  id: 'onboarding',
-  args: { timezone: 'Europe/London' },
-  initialMessage: 'Help me get started.',
-  tags: { project: 'docs' },
+  type: "horton",
+  id: "onboarding",
+  args: { timezone: "Europe/London" },
+  initialMessage: "Help me get started.",
+  tags: { project: "docs" },
 })
 
 console.log(info.entityUrl) // "/horton/onboarding"
@@ -64,11 +64,11 @@ interface SpawnEntityOptions {
   wake?: {
     subscriberUrl: string
     condition:
-      | 'runFinished'
+      | "runFinished"
       | {
-          on: 'change'
+          on: "change"
           collections?: string[]
-          ops?: Array<'insert' | 'update' | 'delete'>
+          ops?: Array<"insert" | "update" | "delete">
         }
     debounceMs?: number
     timeoutMs?: number
@@ -80,14 +80,14 @@ interface SpawnEntityOptions {
 ### getEntityInfo
 
 ```ts
-const info = await client.getEntityInfo('/horton/onboarding')
+const info = await client.getEntityInfo("/horton/onboarding")
 // { entityUrl, entityType, streamPath }
 ```
 
 ### deleteEntity
 
 ```ts
-await client.deleteEntity('/horton/onboarding')
+await client.deleteEntity("/horton/onboarding")
 ```
 
 Deleting an already-missing entity is treated as success.
@@ -96,10 +96,10 @@ Deleting an already-missing entity is treated as success.
 
 ```ts
 await client.sendEntityMessage({
-  targetUrl: '/horton/onboarding',
-  payload: 'What changed since last time?',
-  from: 'support-ui',
-  type: 'user_message',
+  targetUrl: "/horton/onboarding",
+  payload: "What changed since last time?",
+  from: "support-ui",
+  type: "user_message",
 })
 ```
 
@@ -118,10 +118,10 @@ interface SendEntityMessageOptions {
 ## Shared State
 
 ```ts
-const streamPath = await client.ensureSharedStateStream('research-123')
+const streamPath = await client.ensureSharedStateStream("research-123")
 // "/_electric/shared-state/research-123"
 
-const samePath = client.getSharedStateStreamPath('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.
@@ -134,9 +134,9 @@ Use `ensureSharedStateStream()` when app code needs to create a shared-state str
 
 ```ts
 await client.registerWake({
-  subscriberUrl: '/coordinator/research',
-  sourceUrl: '/worker/analyst/main',
-  condition: 'runFinished',
+  subscriberUrl: "/coordinator/research",
+  sourceUrl: "/worker/analyst/main",
+  condition: "runFinished",
   includeResponse: true,
 })
 ```
@@ -145,12 +145,12 @@ For change wakes:
 
 ```ts
 await client.registerWake({
-  subscriberUrl: '/monitor/main',
-  sourceUrl: '/horton/onboarding/main',
+  subscriberUrl: "/monitor/main",
+  sourceUrl: "/horton/onboarding/main",
   condition: {
-    on: 'change',
-    collections: ['runs', 'texts'],
-    ops: ['insert', 'update'],
+    on: "change",
+    collections: ["runs", "texts"],
+    ops: ["insert", "update"],
   },
   debounceMs: 250,
 })
@@ -159,13 +159,16 @@ await client.registerWake({
 ### registerCronSource
 
 ```ts
-const streamUrl = await client.registerCronSource('0 9 * * *', 'Europe/London')
+const streamUrl = await client.registerCronSource(
+  "0 9 * * *",
+  "Europe/London"
+)
 ```
 
 ### registerEntitiesSource
 
 ```ts
-const source = await client.registerEntitiesSource({ project: 'docs' })
+const source = await client.registerEntitiesSource({ project: "docs" })
 // { streamUrl, sourceRef }
 ```
 
@@ -177,40 +180,40 @@ 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.',
+  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',
+  entityUrl: "/horton/onboarding",
+  id: "follow-up",
   fireAt: new Date(Date.now() + 60_000).toISOString(),
-  payload: 'Follow up now.',
+  payload: "Follow up now.",
 })
 
 await client.deleteSchedule({
-  entityUrl: '/horton/onboarding',
-  id: 'follow-up',
+  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.
+`setTag()` and `removeTag()` are primarily for handler/runtime-owned flows that already hold the current claim-scoped write token. External clients should prefer `send()` and write only to an entity's inbox rather than writing entity state directly.
 
 ```ts
-await client.setTag('/horton/onboarding', 'title', 'Onboarding', writeToken)
-await client.removeTag('/horton/onboarding', 'title', writeToken)
+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()`.                  |
+| 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

@@ -1,6 +1,6 @@
 ---
 title: Shared state
-titleTemplate: '... - Electric Agents'
+titleTemplate: "... - Electric Agents"
 description: >-
   Coordinate across entities with shared state streams, schema definition, and cross-entity reads and writes.
 outline: [2, 3]
@@ -18,8 +18,8 @@ Define a `SharedStateSchemaMap` — a record of collection names to their schema
 const researchSchema = {
   findings: {
     schema: z.object({ key: z.string(), domain: z.string(), text: z.string() }),
-    type: 'shared:finding',
-    primaryKey: 'key',
+    type: "shared:finding",
+    primaryKey: "key",
   },
 }
 ```
@@ -32,9 +32,9 @@ The parent entity creates the shared DB stream, typically on `firstWake`:
 
 ```ts
 if (ctx.firstWake) {
-  ctx.mkdb('research-123', researchSchema)
+  ctx.mkdb("research-123", researchSchema)
 }
-const shared = await ctx.observe(db('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.
@@ -44,8 +44,8 @@ const shared = await ctx.observe(db('research-123', researchSchema))
 `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 },
+const shared = await ctx.observe(db("research-123", researchSchema), {
+  wake: { on: "change", debounceMs: 500 },
 })
 ```
 
@@ -55,13 +55,13 @@ Pass the shared DB config to children via spawn args:
 
 ```ts
 const child = await ctx.spawn(
-  'worker',
-  'specialist-1',
+  "worker",
+  "specialist-1",
   {
-    systemPrompt: '...',
-    sharedDb: { id: 'research-123', schema: researchSchema },
+    systemPrompt: "...",
+    sharedDb: { id: "research-123", schema: researchSchema },
   },
-  { initialMessage: 'Research topic X', wake: 'runFinished' }
+  { initialMessage: "Research topic X", wake: "runFinished" }
 )
 ```
 
@@ -82,22 +82,22 @@ async handler(ctx) {
 ```ts
 // Insert
 shared.findings.insert({
-  key: 'f1',
-  domain: 'physics',
-  text: 'Finding text...',
+  key: "f1",
+  domain: "physics",
+  text: "Finding text...",
 })
 
 // Read
-shared.findings.get('f1')
+shared.findings.get("f1")
 shared.findings.toArray
 
 // Update
-shared.findings.update('f1', (draft) => {
-  draft.text = 'Updated'
+shared.findings.update("f1", (draft) => {
+  draft.text = "Updated"
 })
 
 // Delete
-shared.findings.delete('f1')
+shared.findings.delete("f1")
 ```
 
 ## SharedStateHandle type
@@ -119,18 +119,18 @@ const debateSchema = {
   arguments: {
     schema: z.object({
       key: z.string(),
-      side: z.enum(['pro', 'con']),
+      side: z.enum(["pro", "con"]),
       text: z.string(),
       round: z.number(),
     }),
-    type: 'shared:argument',
-    primaryKey: 'key',
+    type: "shared:argument",
+    primaryKey: "key",
   },
 }
 
-registry.define('debate', {
+registry.define("debate", {
   state: {
-    status: { primaryKey: 'key' },
+    status: { primaryKey: "key" },
   },
 
   async handler(ctx) {
@@ -143,23 +143,23 @@ registry.define('debate', {
 
     // Spawn pro and con workers with shared state access
     const pro = await ctx.spawn(
-      'worker',
-      'debate-pro',
+      "worker",
+      "debate-pro",
       {
-        systemPrompt: 'Argue FOR the topic.',
+        systemPrompt: "Argue FOR the topic.",
         sharedDb: { id: `debate-${ctx.entityUrl}`, schema: debateSchema },
       },
-      { initialMessage: 'The topic is: ...', wake: 'runFinished' }
+      { initialMessage: "The topic is: ...", wake: "runFinished" }
     )
 
     const con = await ctx.spawn(
-      'worker',
-      'debate-con',
+      "worker",
+      "debate-con",
       {
-        systemPrompt: 'Argue AGAINST the topic.',
+        systemPrompt: "Argue AGAINST the topic.",
         sharedDb: { id: `debate-${ctx.entityUrl}`, schema: debateSchema },
       },
-      { initialMessage: 'The topic is: ...', wake: 'runFinished' }
+      { initialMessage: "The topic is: ...", wake: "runFinished" }
     )
 
     // Read all arguments written by both workers

package/docs/usage/spawning-and-coordinating.md

@@ -1,6 +1,6 @@
 ---
 title: Spawning & coordinating
-titleTemplate: '... - Electric Agents'
+titleTemplate: "... - Electric Agents"
 description: >-
   Spawn child entities, observe existing ones, send messages, and use EntityHandle for coordination.
 outline: [2, 3]
@@ -63,7 +63,7 @@ Wait for a single child:
 
 ```ts
 await child.run
-const output = (await child.text()).join('\n\n')
+const output = (await child.text()).join("\n\n")
 ```
 
 Wait for multiple children in parallel:
@@ -71,7 +71,7 @@ Wait for multiple children in parallel:
 ```ts
 const results = await Promise.all(
   children.map(async ({ handle }) => ({
-    text: (await handle.text()).join('\n\n'),
+    text: (await handle.text()).join("\n\n"),
   }))
 )
 ```
@@ -82,7 +82,7 @@ Subscribe to an existing entity without spawning it:
 
 ```ts
 const handle = await ctx.observe(entity(entityUrl), {
-  wake: { on: 'change', collections: ['runs', 'childStatus'] },
+  wake: { on: "change", collections: ["runs", "childStatus"] },
 })
 ```
 
@@ -93,8 +93,8 @@ Returns an `EntityHandle`. Use `wake` to re-invoke the parent handler when the o
 Fire-and-forget message to another entity:
 
 ```ts
-ctx.send('/assistant/target-id', { text: 'Hello' })
-ctx.send('/assistant/target-id', payload, { type: 'custom_type' })
+ctx.send("/assistant/target-id", { text: "Hello" })
+ctx.send("/assistant/target-id", payload, { type: "custom_type" })
 ```
 
 Messages appear in the target entity's `inbox` collection.
@@ -152,12 +152,12 @@ const data = await response.json()
 
 // Pass data, not credentials, to the worker
 await ctx.spawn(
-  'worker',
+  "worker",
   id,
-  { systemPrompt: 'Summarise this data.', tools: ['read'] },
+  { systemPrompt: "Summarise this data.", tools: ["read"] },
   {
     initialMessage: JSON.stringify(data),
-    wake: 'runFinished',
+    wake: "runFinished",
   }
 )
 ```

package/docs/usage/testing.md

@@ -1,6 +1,6 @@
 ---
 title: Testing
-titleTemplate: '... - Electric Agents'
+titleTemplate: "... - Electric Agents"
 description: >-
   Test entity handlers with testResponses for LLM mocking, plus unit and integration testing patterns.
 outline: [2, 3]
@@ -14,10 +14,10 @@ Test agent handlers without calling the LLM by providing canned responses:
 
 ```ts
 ctx.useAgent({
-  systemPrompt: '...',
-  model: 'claude-sonnet-4-5-20250929',
+  systemPrompt: "...",
+  model: "claude-sonnet-4-5-20250929",
   tools: [...ctx.electricTools],
-  testResponses: ['Hello! How can I help?'],
+  testResponses: ["Hello! How can I help?"],
 })
 await ctx.agent.run()
 ```
@@ -31,9 +31,9 @@ For dynamic test responses, provide a function instead of an array:
 ```ts
 testResponses: async (message, bridge) => {
   bridge.onTextStart()
-  bridge.onTextDelta('Test response')
+  bridge.onTextDelta("Test response")
   bridge.onTextEnd()
-  return 'Test response'
+  return "Test response"
 }
 ```
 
@@ -46,28 +46,28 @@ The runtime wraps your `TestResponseFn` with `bridge.onRunStart()` / `bridge.onR
 ## Unit testing entity registration
 
 ```ts
-import { createEntityRegistry } from '@electric-ax/agents-runtime'
+import { createEntityRegistry } from "@electric-ax/agents-runtime"
 
 const registry = createEntityRegistry()
 registerAssistant(registry)
 
-test('registers assistant', () => {
-  const entry = registry.get('assistant')
+test("registers assistant", () => {
+  const entry = registry.get("assistant")
   expect(entry).toBeDefined()
-  expect(entry!.definition.handler).toBeTypeOf('function')
+  expect(entry!.definition.handler).toBeTypeOf("function")
 })
 ```
 
 ## Unit testing runtime creation
 
 ```ts
-test('creates runtime with types', () => {
+test("creates runtime with types", () => {
   const runtime = createRuntimeHandler({
-    baseUrl: 'http://localhost:4437',
-    serveEndpoint: 'http://localhost:3000/webhook',
+    baseUrl: "http://localhost:4437",
+    serveEndpoint: "http://localhost:3000/webhook",
     registry,
   })
-  expect(runtime.typeNames).toContain('assistant')
+  expect(runtime.typeNames).toContain("assistant")
 })
 ```
 

package/docs/usage/waking-entities.md

@@ -1,6 +1,6 @@
 ---
 title: Waking entities
-titleTemplate: '... - Electric Agents'
+titleTemplate: "... - Electric Agents"
 description: >-
   How entity handlers get invoked - the triggers that produce wakes, how wake config threads through spawn/observe/observe(db(...)), and how to read a WakeEvent in a handler.
 outline: [2, 3]
@@ -23,7 +23,7 @@ external event  ─►  wake entry (persisted)  ─►  handler invocation  ─
 3. **Handler is invoked.** The runtime picks up the wake, loads the entity's state, and calls your handler with a `WakeEvent` describing what triggered this invocation.
 4. **Handler runs.** You read `ctx.events`, inspect `wake`, configure the agent, emit new events. When the handler returns (or calls `ctx.sleep()`), the entity goes idle until the next wake.
 
-This means handlers are re-entrant: the same handler function is called fresh on every wake. Use `ctx.firstWake` for one-time initialization, and `ctx.db.actions` / `ctx.db.collections` to carry state across wakes.
+This means handlers are re-entrant: the same handler function is called fresh on every wake. Use `ctx.db.actions` / `ctx.db.collections` to carry state across wakes, and make one-time writes idempotent by checking existing state. `ctx.firstWake` is for the initial setup pass while no manifest entries exist.
 
 ## What produces a wake
 
@@ -34,7 +34,7 @@ There are five things that can wake an entity:
 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:
 
 ```ts
-ctx.send('/assistant/peer', { text: 'hello' })
+ctx.send("/assistant/peer", { text: "hello" })
 ```
 
 The receiving handler sees `wake.type === "message_received"` and finds the payload on `wake.payload`.
@@ -45,12 +45,12 @@ Pass `wake` when spawning a child to control when the parent wakes:
 
 ```ts
 const child = await ctx.spawn(
-  'worker',
-  'analysis-1',
-  { systemPrompt: 'Analyse this input.', tools: ['read'] },
+  "worker",
+  "analysis-1",
+  { systemPrompt: "Analyse this input.", tools: ["read"] },
   {
-    initialMessage: 'begin',
-    wake: { on: 'runFinished', includeResponse: true },
+    initialMessage: "begin",
+    wake: { on: "runFinished", includeResponse: true },
   }
 )
 ```
@@ -62,10 +62,10 @@ See the full catalog of `Wake` values in [WakeEvent](../reference/wake-event#wak
 `ctx.observe()` subscribes to another entity's stream without spawning it. Pair it with a `wake` option to re-invoke this handler when the observed stream changes:
 
 ```ts
-import { entity } from '@electric-ax/agents-runtime'
+import { entity } from "@electric-ax/agents-runtime"
 
 await ctx.observe(entity(someEntityUrl), {
-  wake: { on: 'change', collections: ['status'], debounceMs: 250 },
+  wake: { on: "change", collections: ["status"], debounceMs: 250 },
 })
 ```
 
@@ -76,8 +76,8 @@ The `entity()` helper wraps a raw URL string into the correct observe target typ
 `observe(db(...))` connects to a shared-state stream and, with `wake`, re-wakes the connecting entity when its collections change:
 
 ```ts
-await ctx.observe(db('board-1', schema), {
-  wake: { on: 'change', collections: ['findings'] },
+await ctx.observe(db("board-1", schema), {
+  wake: { on: "change", collections: ["findings"] },
 })
 ```
 
@@ -123,7 +123,7 @@ Multiple external events that arrive while an entity is busy (or between acks) a
 
 - A wake covers a contiguous range of offsets in the source stream (`wake.fromOffset`..`wake.toOffset`).
 - `wake.eventCount` tells you how many new events this wake represents.
-- Handlers must be safe to re-run with the same input — at-least-once delivery. Use `ctx.firstWake` and idempotent writes to collections rather than side effects on each wake.
+- Handlers must be safe to re-run with the same input — at-least-once delivery. Prefer idempotent writes to collections over side effects on each wake.
 
 If you need to deduplicate explicitly, key your writes by something stable (the child's entity URL, the message's producer/epoch/seq headers, etc.) and let the collection's primary key do the dedup.