@electric-ax/agents 0.2.3 → 0.3.0

package/docs/usage/clients-and-react.md

@@ -1,6 +1,6 @@
 ---
 title: Clients & React
-titleTemplate: '... - Electric Agents'
+titleTemplate: "... - Electric Agents"
 description: >-
   Observe Electric Agents entities from app code, build reactive StreamDB handles,
   and render chat timelines with the React useChat hook.
@@ -17,20 +17,24 @@ Use the client APIs when you need to observe agents from application code rather
 
 ```ts
 import {
+  codingSession,
   createAgentsClient,
   entity,
   entities,
-} from '@electric-ax/agents-runtime'
+} from "@electric-ax/agents-runtime"
 
-const client = createAgentsClient({ baseUrl: 'http://localhost:4437' })
+const client = createAgentsClient({ baseUrl: "http://localhost:4437" })
 
 // Observe a single entity stream.
-const entityDb = await client.observe(entity('/horton/onboarding'))
+const entityDb = await client.observe(entity("/horton/onboarding"))
 console.log(entityDb.collections.texts.toArray)
 
 // Observe the entity membership stream for a tag query.
-const membersDb = await client.observe(entities({ tags: { project: 'alpha' } }))
+const membersDb = await client.observe(
+  entities({ tags: { project: "alpha" } })
+)
 console.log(membersDb.collections.members.toArray)
+
 ```
 
 ### Types
@@ -58,17 +62,17 @@ interface AgentsClient {
 
 The same source helpers used by `ctx.observe()` can be used with `AgentsClient`.
 
-| Helper               | Use case                                            |
-| -------------------- | --------------------------------------------------- |
-| `entity(url)`        | Observe one entity by URL.                          |
+| Helper              | Use case                                             |
+| ------------------- | ---------------------------------------------------- |
+| `entity(url)`       | Observe one entity by URL.                           |
 | `entities({ tags })` | Observe the entity membership stream matching tags. |
-| `db(id, schema)`     | Observe a shared-state stream.                      |
-| `cron(expression)`   | Build a cron source for wake subscriptions.         |
+| `db(id, schema)`    | Observe a shared-state stream.                       |
+| `cron(expression)`  | Build a cron source for wake subscriptions.          |
 
 ```ts
-import { db } from '@electric-ax/agents-runtime'
+import { db } from "@electric-ax/agents-runtime"
 
-const shared = await client.observe(db('research-123', researchSchema))
+const shared = await client.observe(db("research-123", researchSchema))
 ```
 
 ## React useChat
@@ -76,12 +80,12 @@ const shared = await client.observe(db('research-123', researchSchema))
 `@electric-ax/agents-runtime/react` exports `useChat()`, a React hook that turns an `EntityStreamDB` into sections suitable for a chat UI.
 
 ```tsx
-import { useEffect, useState } from 'react'
-import { createAgentsClient, entity } from '@electric-ax/agents-runtime'
-import { useChat } from '@electric-ax/agents-runtime/react'
-import type { EntityStreamDB } from '@electric-ax/agents-runtime'
+import { useEffect, useState } from "react"
+import { createAgentsClient, entity } from "@electric-ax/agents-runtime"
+import { useChat } from "@electric-ax/agents-runtime/react"
+import type { EntityStreamDB } from "@electric-ax/agents-runtime"
 
-const client = createAgentsClient({ baseUrl: 'http://localhost:4437' })
+const client = createAgentsClient({ baseUrl: "http://localhost:4437" })
 
 export function AgentConversation({ entityUrl }: { entityUrl: string }) {
   const [db, setDb] = useState<EntityStreamDB | null>(null)
@@ -109,10 +113,10 @@ export function AgentConversation({ entityUrl }: { entityUrl: string }) {
     <ol>
       {chat.sections.map((section, index) => (
         <li key={index}>
-          {section.kind === 'user_message'
+          {section.kind === "user_message"
             ? section.text
             : section.items.map((item) =>
-                item.kind === 'text' ? item.text : item.toolName
+                item.kind === "text" ? item.text : item.toolName
               )}
         </li>
       ))}
@@ -126,7 +130,7 @@ export function AgentConversation({ entityUrl }: { entityUrl: string }) {
 ```ts
 interface UseChatResult {
   sections: EntityTimelineSection[]
-  state: 'pending' | 'queued' | 'working' | 'idle' | 'error'
+  state: "pending" | "queued" | "working" | "idle" | "error"
   runs: IncludesRun[]
   inbox: IncludesInboxMessage[]
   wakes: IncludesWakeMessage[]
@@ -151,34 +155,34 @@ import {
   normalizeEntityTimelineData,
   timelineMessages,
   timelineToMessages,
-} from '@electric-ax/agents-runtime'
+} from "@electric-ax/agents-runtime"
 ```
 
 Use these when you already have an `EntityStreamDB` and want to build your own UI integration.
 
-| Helper                              | Purpose                                                                |
-| ----------------------------------- | ---------------------------------------------------------------------- |
-| `createEntityIncludesQuery(db)`     | Builds the TanStack DB query used by `useChat`.                        |
-| `normalizeEntityTimelineData()`     | Normalizes and sorts nested run, text, tool, wake, and entity data.    |
-| `getEntityState(runs, inbox)`       | Computes `pending`, `queued`, `working`, `idle`, or `error`.           |
-| `buildSections(runs, inbox)`        | Builds chat-friendly user/agent sections.                              |
-| `buildTimelineEntries(runs, inbox)` | Builds keyed timeline entries with response timestamps.                |
-| `materializeTimeline(data)`         | Converts normalized timeline data into prompt-oriented timeline items. |
-| `defaultProjection(item)`           | Projects one timeline item into LLM messages.                          |
-| `timelineMessages(db, opts?)`       | Reads an entity DB and returns timestamped LLM messages.               |
-| `timelineToMessages(db)`            | Convenience wrapper returning plain LLM messages.                      |
+| Helper                         | Purpose                                                       |
+| ------------------------------ | ------------------------------------------------------------- |
+| `createEntityIncludesQuery(db)` | Builds the TanStack DB query used by `useChat`.               |
+| `normalizeEntityTimelineData()` | Normalizes and sorts nested run, text, tool, wake, and entity data. |
+| `getEntityState(runs, inbox)`  | Computes `pending`, `queued`, `working`, `idle`, or `error`.  |
+| `buildSections(runs, inbox)`   | Builds chat-friendly user/agent sections.                     |
+| `buildTimelineEntries(runs, inbox)` | Builds keyed timeline entries with response timestamps.  |
+| `materializeTimeline(data)`    | Converts normalized timeline data into prompt-oriented timeline items. |
+| `defaultProjection(item)`      | Projects one timeline item into LLM messages.                 |
+| `timelineMessages(db, opts?)`  | Reads an entity DB and returns timestamped LLM messages.      |
+| `timelineToMessages(db)`       | Convenience wrapper returning plain LLM messages.             |
 
 ## CLI Entity Stream DB
 
 The `electric-ax/entity-stream-db` subpath exposes a convenience loader used by CLI and UI code:
 
 ```ts
-import { createEntityStreamDB } from 'electric-ax/entity-stream-db'
+import { createEntityStreamDB } from "electric-ax/entity-stream-db"
 
 const { db, close } = await createEntityStreamDB({
-  baseUrl: 'http://localhost:4437',
-  entityUrl: '/horton/onboarding',
-  initialOffset: '0',
+  baseUrl: "http://localhost:4437",
+  entityUrl: "/horton/onboarding",
+  initialOffset: "0",
 })
 
 try {

package/docs/usage/configuring-the-agent.md

@@ -1,6 +1,6 @@
 ---
 title: Configuring the agent
-titleTemplate: '... - Electric Agents'
+titleTemplate: "... - Electric Agents"
 description: >-
   Set up LLM agents with ctx.useAgent(), including model selection, system prompts, tools, and test responses.
 outline: [2, 3]
@@ -19,18 +19,22 @@ interface AgentConfig {
   provider?: KnownProvider
   tools: AgentTool[]
   streamFn?: StreamFn
+  getApiKey?: (provider: string) => Promise<string | undefined> | string | undefined
+  onPayload?: SimpleStreamOptions["onPayload"]
   testResponses?: string[] | TestResponseFn
 }
 ```
 
-| Field           | Required | Description                                                                                                            |
-| --------------- | -------- | ---------------------------------------------------------------------------------------------------------------------- |
-| `systemPrompt`  | Yes      | The system prompt passed to the LLM.                                                                                   |
-| `model`         | Yes      | Model identifier string or resolved model object.                                                                      |
-| `provider`      | No       | Provider to use when `model` is a string. Defaults to `"anthropic"`.                                                   |
+| Field           | Required | Description                                                             |
+| --------------- | -------- | ----------------------------------------------------------------------- |
+| `systemPrompt`  | Yes      | The system prompt passed to the LLM.                                    |
+| `model`         | Yes      | Model identifier string or resolved model object.                       |
+| `provider`      | No       | Provider to use when `model` is a string. Defaults to `"anthropic"`.    |
 | `tools`         | Yes      | Array of tools available to the agent. Spread `ctx.electricTools` when your runtime host provides runtime-level tools. |
-| `streamFn`      | No       | Optional streaming callback passed to the underlying agent.                                                            |
-| `testResponses` | No       | Mock responses for testing without calling the LLM.                                                                    |
+| `streamFn`      | No       | Optional streaming callback passed to the underlying agent.             |
+| `getApiKey`     | No       | Optional API-key resolver passed through to the model layer.            |
+| `onPayload`     | No       | Optional callback for raw streaming payloads from the model layer.      |
+| `testResponses` | No       | Mock responses for testing without calling the LLM.                     |
 
 ## Basic usage
 
@@ -71,16 +75,18 @@ Returns an `AgentRunResult`:
 
 ```ts
 type AgentRunResult = {
+  result?: unknown
   writes: ChangeEvent[]
   toolCalls: Array<{ name: string; args: unknown; result: unknown }>
   usage: { tokens: number; duration: number }
 }
 ```
 
-| Field       | Description                                                                             |
-| ----------- | --------------------------------------------------------------------------------------- |
-| `writes`    | Currently returned as an empty array placeholder.                                       |
-| `toolCalls` | Currently returned as an empty array placeholder.                                       |
+| Field       | Description                                                                 |
+| ----------- | --------------------------------------------------------------------------- |
+| `result`    | Optional final result from the underlying agent adapter.                    |
+| `writes`    | Currently returned as an empty array placeholder.                           |
+| `toolCalls` | Currently returned as an empty array placeholder.                           |
 | `usage`     | Currently returned as `{ tokens: 0, duration: 0 }` until usage aggregation is wired in. |
 
 ## AgentHandle
@@ -100,8 +106,8 @@ You must call `useAgent` before calling `run()`. Calling `ctx.agent.run()` witho
 When `model` is a string, the runtime resolves it through the configured `provider` (default `"anthropic"`). You can also pass a resolved `Model` object directly.
 
 ```ts
-model: 'claude-sonnet-4-5-20250929'
-provider: 'anthropic'
+model: "claude-sonnet-4-5-20250929"
+provider: "anthropic"
 ```
 
 ## Test responses
@@ -112,10 +118,10 @@ For testing handlers without making LLM calls, pass `testResponses`. Two forms a
 
 ```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?', 'Sure, I can do that.'],
+  testResponses: ["Hello! How can I help?", "Sure, I can do that."],
 })
 ```
 
@@ -125,8 +131,8 @@ ctx.useAgent({
 ctx.useAgent({
   // ...
   testResponses: async (message, bridge) => {
-    if (message.includes('calculate')) {
-      return 'The answer is 42.'
+    if (message.includes("calculate")) {
+      return "The answer is 42."
     }
     return undefined // emits no automatic text response
   },

package/docs/usage/context-composition.md

@@ -1,6 +1,6 @@
 ---
 title: Context composition
-titleTemplate: '... - Electric Agents'
+titleTemplate: "... - Electric Agents"
 description: >-
   Control what goes into the agent's context window using ctx.useContext() with token-budgeted sources, cache tiers, and imperative context entries.
 outline: [2, 3]
@@ -25,14 +25,14 @@ ctx.useContext({
   sourceBudget: 18_000,
   sources: {
     docs: {
-      content: () => '# Reference docs\n...',
+      content: () => "# Reference docs\n...",
       max: 6_000,
-      cache: 'stable',
+      cache: "stable",
     },
     conversation: {
       content: () => ctx.timelineMessages(),
       max: 12_000,
-      cache: 'volatile',
+      cache: "volatile",
     },
   },
 })
@@ -82,7 +82,7 @@ const messages = ctx.timelineMessages()
 const messages = ctx.timelineMessages({
   since: 42,
   projection: (item) => {
-    if (item.kind === 'run') return [{ role: 'assistant', content: '...' }]
+    if (item.kind === "run") return [{ role: "assistant", content: "..." }]
     return null // use default projection
   },
 })
@@ -102,7 +102,7 @@ ctx.useContext({
     conversation: {
       content: () => ctx.timelineMessages(),
       max: 15_000,
-      cache: 'volatile',
+      cache: "volatile",
     },
   },
 })
@@ -117,10 +117,10 @@ Use context entries for information the agent discovers during a run that should
 ### insertContext
 
 ```ts
-ctx.insertContext('user-prefs', {
-  name: 'User preferences',
-  content: 'Prefers concise responses. Timezone: PST.',
-  attrs: { priority: 'high' },
+ctx.insertContext("user-prefs", {
+  name: "User preferences",
+  content: "Prefers concise responses. Timezone: PST.",
+  attrs: { priority: "high" },
 })
 ```
 
@@ -129,13 +129,13 @@ Inserting with an existing `id` replaces the previous entry.
 ### removeContext
 
 ```ts
-ctx.removeContext('user-prefs')
+ctx.removeContext("user-prefs")
 ```
 
 ### getContext / listContext
 
 ```ts
-const entry = ctx.getContext('user-prefs')
+const entry = ctx.getContext("user-prefs")
 // { id: "user-prefs", name: "User preferences", content: "...", insertedAt: 1234 }
 
 const all = ctx.listContext()

package/docs/usage/defining-entities.md

@@ -1,6 +1,6 @@
 ---
 title: Defining entities
-titleTemplate: '... - Electric Agents'
+titleTemplate: "... - Electric Agents"
 description: >-
   Register entity types with the EntityRegistry, define custom state collections, typed schemas, and handler functions.
 outline: [2, 3]
@@ -15,16 +15,16 @@ An entity type is registered with an `EntityRegistry`. The registry maps type na
 `createEntityRegistry()` returns an `EntityRegistry`. Register types with `registry.define(name, definition)`.
 
 ```ts
-import { createEntityRegistry } from '@electric-ax/agents-runtime'
+import { createEntityRegistry } from "@electric-ax/agents-runtime"
 
 const registry = createEntityRegistry()
 
-registry.define('assistant', {
-  description: 'A general-purpose AI assistant',
+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',
+      systemPrompt: "You are a helpful assistant.",
+      model: "claude-sonnet-4-5-20250929",
       tools: [...ctx.electricTools],
     })
     await ctx.agent.run()
@@ -50,15 +50,15 @@ interface EntityDefinition {
 }
 ```
 
-| Field            | Purpose                                                                                             |
-| ---------------- | --------------------------------------------------------------------------------------------------- |
-| `description`    | Human-readable description. Shown in the Electric Agents UI and CLI.                                |
+| 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.                                        |
+| `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
 
@@ -81,7 +81,7 @@ interface CollectionDefinition {
 Declared collections become available via `ctx.state` proxies and the lower-level `ctx.db.actions` / `ctx.db.collections` APIs:
 
 ```ts
-import { z } from 'zod'
+import { z } from "zod"
 
 const childSchema = z.object({
   key: z.string(),
@@ -89,22 +89,22 @@ const childSchema = z.object({
   kind: z.string(),
 })
 
-registry.define('coordinator', {
-  description: 'Spawns and tracks child entities',
+registry.define("coordinator", {
+  description: "Spawns and tracks child entities",
   state: {
-    status: { primaryKey: 'key' },
-    children: { schema: childSchema, primaryKey: 'key' },
+    status: { primaryKey: "key" },
+    children: { schema: childSchema, primaryKey: "key" },
   },
 
   async handler(ctx) {
-    if (ctx.firstWake) {
-      ctx.db.actions.status_insert({ row: { key: 'current', value: 'idle' } })
+    if (!ctx.db.collections.status.get("current")) {
+      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',
+      key: "child-1",
+      url: "/worker/child-1",
+      kind: "worker",
     })
 
     // Lower-level APIs:
@@ -126,9 +126,9 @@ For projects with multiple entity types, keep a separate registry file and impor
 
 ```ts
 // entities/registry.ts
-import { createEntityRegistry } from '@electric-ax/agents-runtime'
-import { registerAssistant } from './assistant'
-import { registerWorker } from './worker'
+import { createEntityRegistry } from "@electric-ax/agents-runtime"
+import { registerAssistant } from "./assistant"
+import { registerWorker } from "./worker"
 
 export const registry = createEntityRegistry()
 registerAssistant(registry)
@@ -137,15 +137,15 @@ registerWorker(registry)
 
 ```ts
 // entities/assistant.ts
-import type { EntityRegistry } from '@electric-ax/agents-runtime'
+import type { EntityRegistry } from "@electric-ax/agents-runtime"
 
 export function registerAssistant(registry: EntityRegistry) {
-  registry.define('assistant', {
-    description: 'General-purpose assistant',
+  registry.define("assistant", {
+    description: "General-purpose assistant",
     async handler(ctx) {
       ctx.useAgent({
-        systemPrompt: 'You are a helpful assistant.',
-        model: 'claude-sonnet-4-5-20250929',
+        systemPrompt: "You are a helpful assistant.",
+        model: "claude-sonnet-4-5-20250929",
         tools: [...ctx.electricTools],
       })
       await ctx.agent.run()
@@ -161,12 +161,12 @@ This keeps each entity type isolated and the registry composition explicit.
 `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'
+import { z } from "zod/v4"
 
-registry.define('processor', {
-  description: 'Processes structured tasks',
+registry.define("processor", {
+  description: "Processes structured tasks",
   creationSchema: z.object({
-    priority: z.enum(['low', 'medium', 'high']).default('medium'),
+    priority: z.enum(["low", "medium", "high"]).default("medium"),
   }),
   inboxSchemas: {
     task: z.object({