@electric-ax/agents 0.2.1 → 0.2.2

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

@@ -0,0 +1,191 @@
+---
+title: Clients & React
+titleTemplate: '... - Electric Agents'
+description: >-
+  Observe Electric Agents entities from app code, build reactive StreamDB handles,
+  and render chat timelines with the React useChat hook.
+outline: [2, 3]
+---
+
+# Clients & React
+
+Use the client APIs when you need to observe agents from application code rather than from inside a handler. They load entity or observation streams into TanStack DB-backed collections that can drive UI.
+
+## AgentsClient
+
+`createAgentsClient()` creates a small read client for observation sources.
+
+```ts
+import {
+  createAgentsClient,
+  entity,
+  entities,
+} from '@electric-ax/agents-runtime'
+
+const client = createAgentsClient({ baseUrl: 'http://localhost:4437' })
+
+// Observe a single entity stream.
+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' } }))
+console.log(membersDb.collections.members.toArray)
+```
+
+### Types
+
+```ts
+interface AgentsClientConfig {
+  baseUrl: string
+  fetch?: typeof globalThis.fetch
+}
+
+interface AgentsClient {
+  observe(
+    source: ObservationSource
+  ): Promise<EntityStreamDB | ObservationStreamDB>
+}
+```
+
+`observe(entity(url))` returns an `EntityStreamDB`. `observe(entities(...))` and `observe(db(...))` return an `ObservationStreamDB`.
+
+:::: warning
+`client.observe(cron(...))` is not currently supported. Use cron sources from handler wake subscriptions, or schedule tools exposed through `ctx.electricTools`.
+::::
+
+## Observation Sources
+
+The same source helpers used by `ctx.observe()` can be used with `AgentsClient`.
+
+| 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.         |
+
+```ts
+import { db } from '@electric-ax/agents-runtime'
+
+const shared = await client.observe(db('research-123', researchSchema))
+```
+
+## React useChat
+
+`@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'
+
+const client = createAgentsClient({ baseUrl: 'http://localhost:4437' })
+
+export function AgentConversation({ entityUrl }: { entityUrl: string }) {
+  const [db, setDb] = useState<EntityStreamDB | null>(null)
+
+  useEffect(() => {
+    let cancelled = false
+    let observedDb: EntityStreamDB | null = null
+    client.observe(entity(entityUrl)).then((observed) => {
+      observedDb = observed as EntityStreamDB
+      if (cancelled) {
+        observedDb.close()
+        return
+      }
+      if (!cancelled) setDb(observedDb)
+    })
+    return () => {
+      cancelled = true
+      observedDb?.close()
+    }
+  }, [entityUrl])
+
+  const chat = useChat(db)
+
+  return (
+    <ol>
+      {chat.sections.map((section, index) => (
+        <li key={index}>
+          {section.kind === 'user_message'
+            ? section.text
+            : section.items.map((item) =>
+                item.kind === 'text' ? item.text : item.toolName
+              )}
+        </li>
+      ))}
+    </ol>
+  )
+}
+```
+
+### UseChatResult
+
+```ts
+interface UseChatResult {
+  sections: EntityTimelineSection[]
+  state: 'pending' | 'queued' | 'working' | 'idle' | 'error'
+  runs: IncludesRun[]
+  inbox: IncludesInboxMessage[]
+  wakes: IncludesWakeMessage[]
+  entities: IncludesEntity[]
+}
+```
+
+`sections` are the high-level chat timeline. `runs`, `inbox`, `wakes`, and `entities` expose the normalized underlying data for richer UIs.
+
+## Timeline Helpers
+
+If you are not using React, the runtime also exports pure timeline helpers:
+
+```ts
+import {
+  buildSections,
+  buildTimelineEntries,
+  createEntityIncludesQuery,
+  defaultProjection,
+  getEntityState,
+  materializeTimeline,
+  normalizeEntityTimelineData,
+  timelineMessages,
+  timelineToMessages,
+} 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.                      |
+
+## 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'
+
+const { db, close } = await createEntityStreamDB({
+  baseUrl: 'http://localhost:4437',
+  entityUrl: '/horton/onboarding',
+  initialOffset: '0',
+})
+
+try {
+  console.log(db.collections.runs.toArray)
+} finally {
+  close()
+}
+```
+
+This API fetches entity metadata from the server, opens the entity's main stream, preloads it, and returns an `EntityStreamDB`.

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

@@ -0,0 +1,136 @@
+---
+title: Configuring the agent
+titleTemplate: '... - Electric Agents'
+description: >-
+  Set up LLM agents with ctx.useAgent(), including model selection, system prompts, tools, and test responses.
+outline: [2, 3]
+---
+
+# Configuring the agent
+
+Call `ctx.useAgent()` in your handler to set up the LLM, then `ctx.agent.run()` to execute it.
+
+## AgentConfig
+
+```ts
+interface AgentConfig {
+  systemPrompt: string
+  model: string | Model<any>
+  provider?: KnownProvider
+  tools: AgentTool[]
+  streamFn?: StreamFn
+  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"`.                                                   |
+| `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.                                                                    |
+
+## Basic usage
+
+```ts
+async handler(ctx) {
+  ctx.useAgent({
+    systemPrompt: 'You are a helpful assistant.',
+    model: 'claude-sonnet-4-5-20250929',
+    tools: [...ctx.electricTools],
+  })
+  await ctx.agent.run()
+}
+```
+
+`useAgent` returns an `AgentHandle` and also sets `ctx.agent`. Both references are equivalent.
+
+To control what content fills the agent's context window (token budgets, cache tiers, external sources), use `ctx.useContext()` alongside `useAgent`. See [Context composition](./context-composition).
+
+## ctx.electricTools
+
+`ctx.electricTools` is an array of runtime-provided tools. It may be empty, or it may contain host-provided tools such as schedule management tools. Spread it into the `tools` array when you want the LLM agent to access those runtime-level tools:
+
+```ts
+tools: [...ctx.electricTools, myCustomTool, anotherTool]
+```
+
+Handler-level coordination APIs such as `ctx.spawn`, `ctx.observe`, and `ctx.send` are available on `HandlerContext` regardless of whether you pass `ctx.electricTools` to the LLM.
+
+## ctx.agent.run()
+
+Executes the agent loop. Blocks until the LLM finishes -- all tool calls are resolved and the final text response is emitted.
+
+```ts
+const result = await ctx.agent.run()
+```
+
+Returns an `AgentRunResult`:
+
+```ts
+type AgentRunResult = {
+  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.                                       |
+| `usage`     | Currently returned as `{ tokens: 0, duration: 0 }` until usage aggregation is wired in. |
+
+## AgentHandle
+
+Returned by `useAgent`. Also accessible as `ctx.agent`.
+
+```ts
+interface AgentHandle {
+  run: (input?: string) => Promise<AgentRunResult>
+}
+```
+
+You must call `useAgent` before calling `run()`. Calling `ctx.agent.run()` without prior configuration throws an error.
+
+## Model
+
+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'
+```
+
+## Test responses
+
+For testing handlers without making LLM calls, pass `testResponses`. Two forms are supported:
+
+**Array of strings** -- selected by the number of prior runs, useful for deterministic repeated wakes:
+
+```ts
+ctx.useAgent({
+  systemPrompt: '...',
+  model: 'claude-sonnet-4-5-20250929',
+  tools: [...ctx.electricTools],
+  testResponses: ['Hello! How can I help?', 'Sure, I can do that.'],
+})
+```
+
+**Function** -- called for each turn with the current message and an `OutboundBridgeHandle`:
+
+```ts
+ctx.useAgent({
+  // ...
+  testResponses: async (message, bridge) => {
+    if (message.includes('calculate')) {
+      return 'The answer is 42.'
+    }
+    return undefined // emits no automatic text response
+  },
+})
+```
+
+See [Testing](./testing) for more on writing tests with `testResponses`.

package/docs/usage/context-composition.md

@@ -0,0 +1,204 @@
+---
+title: Context composition
+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]
+---
+
+# Context composition
+
+By default, the runtime assembles the agent's context window from the entity's full timeline (messages, tool calls, text responses). `ctx.useContext()` gives you explicit control over what goes in and how much space each piece gets.
+
+## When to use it
+
+Most entities don't need `useContext` -- the default timeline assembly works well for simple conversational agents. Use `useContext` when you need to:
+
+- **Budget token space** across multiple content sources (docs, conversation history, retrieved context)
+- **Mix static and dynamic content** with different caching behavior
+- **Inject external content** (documentation, search results, knowledge bases) alongside conversation history
+
+## UseContextConfig
+
+```ts
+ctx.useContext({
+  sourceBudget: 18_000,
+  sources: {
+    docs: {
+      content: () => '# Reference docs\n...',
+      max: 6_000,
+      cache: 'stable',
+    },
+    conversation: {
+      content: () => ctx.timelineMessages(),
+      max: 12_000,
+      cache: 'volatile',
+    },
+  },
+})
+```
+
+| Field          | Type                           | Description                                              |
+| -------------- | ------------------------------ | -------------------------------------------------------- |
+| `sourceBudget` | `number`                       | Total token budget across all sources. Required.         |
+| `sources`      | `Record<string, SourceConfig>` | Named content sources. Must contain at least one source. |
+
+### SourceConfig
+
+Each source declares a content function, a max token allocation, and a cache tier:
+
+| Field     | Type                                                   | Description                                                                      |
+| --------- | ------------------------------------------------------ | -------------------------------------------------------------------------------- |
+| `content` | `() => string \| LLMMessage[] \| TimestampedMessage[]` | Function called each agent run to produce the source content. Can be async.      |
+| `max`     | `number`                                               | Maximum tokens this source may consume. Content is truncated if it exceeds this. |
+| `cache`   | `CacheTier`                                            | Caching hint that controls assembly ordering. See [Cache tiers](#cache-tiers).   |
+
+The `content` function can return:
+
+- A **string** -- inserted as a single system message
+- An **`LLMMessage[]`** array -- inserted as-is
+- A **`TimestampedMessage[]`** array -- interleaved by timestamp with other volatile sources
+
+### Cache tiers
+
+Cache tiers control assembly ordering and caching behavior. Sources are assembled from most stable to most volatile:
+
+| Tier              | Position | Use for                                                        |
+| ----------------- | -------- | -------------------------------------------------------------- |
+| `"pinned"`        | First    | Content that never changes (system instructions, schemas)      |
+| `"stable"`        | Second   | Content that changes rarely (docs TOC, reference material)     |
+| `"slow-changing"` | Third    | Content that updates occasionally (summaries, aggregations)    |
+| `"volatile"`      | Last     | Content that changes every wake (conversation, search results) |
+
+Non-volatile sources (`pinned`, `stable`, `slow-changing`) have their `max` values summed and validated against `sourceBudget` at registration time. Volatile sources share the remaining budget.
+
+## timelineMessages
+
+`ctx.timelineMessages()` projects the entity's timeline (inbox messages, agent runs, tool calls) into an ordered array of `TimestampedMessage` objects suitable for passing to an LLM.
+
+```ts
+const messages = ctx.timelineMessages()
+// or with options:
+const messages = ctx.timelineMessages({
+  since: 42,
+  projection: (item) => {
+    if (item.kind === 'run') return [{ role: 'assistant', content: '...' }]
+    return null // use default projection
+  },
+})
+```
+
+| Option       | Type                                           | Description                                                                            |
+| ------------ | ---------------------------------------------- | -------------------------------------------------------------------------------------- |
+| `since`      | `number`                                       | Only include items after this timeline position.                                       |
+| `projection` | `(item: TimelineItem) => LLMMessage[] \| null` | Custom projection function. Return `null` to use the default projection for that item. |
+
+This is typically used as the `content` function of a `volatile` source:
+
+```ts
+ctx.useContext({
+  sourceBudget: 15_000,
+  sources: {
+    conversation: {
+      content: () => ctx.timelineMessages(),
+      max: 15_000,
+      cache: 'volatile',
+    },
+  },
+})
+```
+
+## Context entries
+
+Context entries are durable key-value items stored in the entity's stream. Unlike sources (which are recomputed each wake), context entries persist across wakes and are projected into the context window automatically when `useContext` is active.
+
+Use context entries for information the agent discovers during a run that should remain available in future wakes (e.g. user preferences, extracted facts, accumulated instructions).
+
+### insertContext
+
+```ts
+ctx.insertContext('user-prefs', {
+  name: 'User preferences',
+  content: 'Prefers concise responses. Timezone: PST.',
+  attrs: { priority: 'high' },
+})
+```
+
+Inserting with an existing `id` replaces the previous entry.
+
+### removeContext
+
+```ts
+ctx.removeContext('user-prefs')
+```
+
+### getContext / listContext
+
+```ts
+const entry = ctx.getContext('user-prefs')
+// { id: "user-prefs", name: "User preferences", content: "...", insertedAt: 1234 }
+
+const all = ctx.listContext()
+// Array<ContextEntry>
+```
+
+### ContextEntryInput
+
+| Field     | Type                | Description                         |
+| --------- | ------------------- | ----------------------------------- |
+| `name`    | `string`            | Human-readable label for the entry. |
+| `content` | `string`            | The text content.                   |
+| `attrs`   | `ContextEntryAttrs` | Optional metadata attributes.       |
+
+### ContextEntry
+
+Extends `ContextEntryInput` with:
+
+| Field        | Type     | Description                       |
+| ------------ | -------- | --------------------------------- |
+| `id`         | `string` | The id passed to `insertContext`. |
+| `insertedAt` | `number` | Timeline position when inserted.  |
+
+## Full example
+
+This example from the built-in Horton assistant shows all three source types working together:
+
+```ts
+async handler(ctx, wake) {
+  const tools = [...ctx.electricTools, ...customTools]
+
+  ctx.useContext({
+    sourceBudget: 18_000,
+    sources: {
+      docs_toc: {
+        content: () => renderCompressedToc(),
+        max: 3_000,
+        cache: "stable",
+      },
+      retrieved_docs: {
+        content: () => renderRetrievedDocs(wake, ctx.events),
+        max: 6_000,
+        cache: "volatile",
+      },
+      conversation: {
+        content: () => ctx.timelineMessages(),
+        max: 9_000,
+        cache: "volatile",
+      },
+    },
+  })
+
+  ctx.useAgent({
+    systemPrompt: "You are a helpful assistant.",
+    model: "claude-sonnet-4-5-20250929",
+    tools,
+  })
+  await ctx.agent.run()
+}
+```
+
+The `stable` docs TOC is assembled first and cached across wakes. The two `volatile` sources (retrieved docs and conversation) are recomputed each wake and share the remaining budget.
+
+## Entities without useContext
+
+Entities that don't call `useContext` are unchanged -- the runtime uses its default timeline assembly, building the full conversation history into the context window automatically. There is no need to migrate existing entities.