@electric-ax/agents 0.4.19 → 0.6.0

package/docs/usage/writing-handlers.md

@@ -18,56 +18,7 @@ handler(ctx: HandlerContext, wake: WakeEvent) => void | Promise<void>
 
 ## HandlerContext
 
-```ts
-interface HandlerContext<TState extends StateProxy = StateProxy> {
-  firstWake: boolean
-  tags: Readonly<EntityTags>
-  entityUrl: string
-  entityType: string
-  args: Readonly<Record<string, unknown>>
-  db: EntityStreamDBWithActions
-  state: TState
-  events: Array<ChangeEvent>
-  actions: Record<string, (...args: unknown[]) => unknown>
-  electricTools: AgentTool[]
-  useAgent: (config: AgentConfig) => AgentHandle
-  useContext: (config: UseContextConfig) => void
-  timelineMessages: (opts?: TimelineProjectionOpts) => Array<TimestampedMessage>
-  insertContext: (id: string, entry: ContextEntryInput) => void
-  removeContext: (id: string) => void
-  getContext: (id: string) => ContextEntry | undefined
-  listContext: () => Array<ContextEntry>
-  agent: AgentHandle
-  spawn: (
-    type: string,
-    id: string,
-    args?: Record<string, unknown>,
-    opts?: {
-      initialMessage?: unknown
-      wake?: Wake
-      tags?: Record<string, string>
-      observe?: boolean
-    }
-  ) => Promise<EntityHandle>
-  observe: (
-    source: ObservationSource,
-    opts?: { wake?: Wake }
-  ) => Promise<EntityHandle | SharedStateHandle | ObservationHandle>
-  mkdb: <T extends SharedStateSchemaMap>(
-    id: string,
-    schema: T
-  ) => SharedStateHandle<T>
-  send: (
-    entityUrl: string,
-    payload: unknown,
-    opts?: { type?: string; afterMs?: number }
-  ) => void
-  recordRun: () => RunHandle
-  setTag: (key: string, value: string) => Promise<void>
-  removeTag: (key: string) => Promise<void>
-  sleep: () => void
-}
-```
+`HandlerContext` includes identity, state, agent configuration, context composition, coordination, signals, sandboxing, attachments, goals, and lifecycle helpers. The table below summarizes the most common members; see the [HandlerContext reference](../reference/handler-context) for the full interface.
 
 ### Property reference
 
@@ -97,7 +48,7 @@ interface HandlerContext<TState extends StateProxy = StateProxy> {
 | `send`             | Sends a message to another entity's inbox. Supports delayed delivery via `afterMs`.                                                                     |
 | `recordRun`        | Records non-LLM work in the built-in `runs` collection so `runFinished` observers are woken.                                                            |
 | `setTag`           | Sets a tag on this entity.                                                                                                                              |
-| `removeTag`        | Removes a tag from this entity.                                                                                                                         |
+| `deleteTag`        | Deletes a tag from this entity.                                                                                                                         |
 | `sleep`            | Returns the entity to idle without re-waking.                                                                                                           |
 
 ## WakeEvent
@@ -146,7 +97,7 @@ registry.define("assistant", {
 
     ctx.useAgent({
       systemPrompt: "You are a helpful assistant.",
-      model: "claude-sonnet-4-5-20250929",
+      model: "claude-sonnet-4-6",
       tools: [...ctx.electricTools],
     })
     await ctx.agent.run()
@@ -162,11 +113,18 @@ Passed to `ctx.useAgent()`:
 interface AgentConfig {
   systemPrompt: string
   model: string | Model<any>
-  provider?: KnownProvider
+  provider?: Provider
   tools: AgentTool[]
   streamFn?: StreamFn
   getApiKey?: (provider: string) => Promise<string | undefined> | string | undefined
   onPayload?: SimpleStreamOptions["onPayload"]
+  onStepEnd?: (stats: {
+    input: number
+    uncachedInput: number
+    output: number
+  }) => void
+  modelTimeoutMs?: number
+  modelMaxRetries?: number
   testResponses?: string[] | TestResponseFn
 }
 ```
@@ -242,7 +200,7 @@ async handler(ctx) {
   const { systemPrompt } = ctx.args as { systemPrompt: string }
   ctx.useAgent({
     systemPrompt,
-    model: 'claude-sonnet-4-5-20250929',
+    model: 'claude-sonnet-4-6',
     tools: [...ctx.electricTools],
   })
   await ctx.agent.run()
@@ -274,7 +232,7 @@ async handler(ctx) {
 
   ctx.useAgent({
     systemPrompt: 'You are an assistant with lookup capabilities.',
-    model: 'claude-sonnet-4-5-20250929',
+    model: 'claude-sonnet-4-6',
     tools: [...ctx.electricTools, myTool],
   })
   await ctx.agent.run()

package/docs/walkthrough.md

@@ -422,11 +422,15 @@ registry.define("manager", {
   description: "A manager agent that delegates work to assistants",
   async handler(ctx, wake) {
     if (wake.type === 'inbox') {
+      const message =
+        typeof wake.payload === "string"
+          ? wake.payload
+          : (wake.payload as { text?: string })?.text ?? wake.payload
       await ctx.spawn(
         'assistant',
         genId(),
         { systemPrompt: `Reverse the user message.` },
-        { initialMessage: wake.payload.text, wake: { on: 'runFinished', includeResponse: true } }
+        { initialMessage: message, wake: { on: 'runFinished', includeResponse: true } }
       )
     }
 
@@ -445,16 +449,20 @@ This is very similar to our `assistant` type but, as you can see, adds this impe
 
 ```ts
 if (wake.type === 'inbox') {
+  const message =
+    typeof wake.payload === "string"
+      ? wake.payload
+      : (wake.payload as { text?: string })?.text ?? wake.payload
   await ctx.spawn(
     'assistant',
     genId(),
     { systemPrompt: `Reverse the user message.` },
-    { initialMessage: wake.payload.text, wake: { on: 'runFinished', includeResponse: true } }
+    { initialMessage: message, wake: { on: 'runFinished', includeResponse: true } }
   )
 }
 ```
 
-What this does is say "if the notification you're responding to comes from the inbox stream", which means it's a user message, then spawn a sub-agent, specifically an `assistant` with a "Reverse the user message" systemPrompt, passing through the user message from `wake.payload.text`.
+What this does is say "if the notification you're responding to comes from the inbox stream", which means it's a user message, then spawn a sub-agent, specifically an `assistant` with a "Reverse the user message" systemPrompt, passing through the user message from `wake.payload`.
 
 Now if you go back to the web UI on [https://localhost:4438](https://localhost:4438) you can now also create `manager` agents:
 
@@ -828,7 +836,7 @@ const rebut = (arg: string) =>
 
 ### Debate collection
 
-Now let's add the `debate` [collection](https://tanstack.com/db/latest/docs/overview#defining-collections) to the entity definition's [`state`](/docs/agents/usage/shared-state). This allows us to track the progress and status of a debate in the [durable state layer](/streams/).
+Now let's add the `debate` [collection](https://tanstack.com/db/latest/docs/overview#defining-collections) to the entity definition's [`state`](/docs/agents/usage/managing-state). This allows us to track the progress and status of a debate in the [durable state layer](/streams/).
 
 Pull in two more imports from `@electric-ax/agents-runtime`:
 
@@ -1095,7 +1103,7 @@ registry.define(`manager`, {
   // ...,
   async handler(ctx, wake) {
     // When receiving wake notifications ...
-    if ((wake.type = `wake`)) {
+    if (wake.type === `wake`) {
       const finishedChild = wake.payload?.finished_child
 
       // ... from a judge sub-agent ...

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@electric-ax/agents",
-  "version": "0.4.19",
+  "version": "0.6.0",
   "description": "Built-in Electric Agents runtimes such as Horton and worker",
   "repository": {
     "type": "git",
@@ -49,8 +49,8 @@
     "sqlite-vec": "^0.1.9",
     "undici": "^7.24.7",
     "zod": "^4.3.6",
-    "@electric-ax/agents-runtime": "0.4.1",
-    "@electric-ax/agents-mcp": "0.2.3"
+    "@electric-ax/agents-mcp": "0.6.0",
+    "@electric-ax/agents-runtime": "0.6.0"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",