@electric-ax/agents 0.4.12 → 0.4.14

package/docs/index.md

@@ -4,6 +4,9 @@ titleTemplate: "... - Electric Agents"
 description: >-
   The durable runtime for long-lived agents — entities, handlers, wakes, agent loops, and coordination, built on Electric Streams, TanStack DB, and pi.
 outline: [2, 3]
+next:
+  text: 'Quickstart'
+  link: '/docs/agents/quickstart'
 ---
 
 <script setup>
@@ -12,7 +15,16 @@ import EntityOverviewDiagram from '../../src/components/agents-home/EntityOvervi
 
 # Electric Agents
 
-Electric Agents is **the durable runtime for long-lived agents**. It's a runtime and communication fabric for spawning and scaling collaborative agents on serverless compute, using your existing web and AI&nbsp;frameworks.
+Electric Agents is **the durable runtime for long-lived agents**.
+
+It's a runtime and communication fabric for spawning and scaling collaborative agents <span class="no-wrap-sm">[on serverless compute](/blog/2026/06/04/serverless-agents)</span> using your existing web systems.
+
+> [!Warning] ✨&nbsp; Start using Electric Agents now
+> See the [Quickstart](/docs/agents/quickstart) to fire the system up and try the built-in agents.
+>
+> Dive into the [Walkthrough](/docs/agents/walkthrough) for a step-by-step guide to building a multi-agent system.
+
+## System overview
 
 Each agent is an **entity** — an addressable, schema-typed unit of state at `/{type}/{id}`. An entity's session and state live on a durable [Electric&nbsp;Stream](/streams/) of events.
 
@@ -22,7 +34,7 @@ Every step — runs, tool calls, text deltas, state changes — is appended to t
 
 <EntityOverviewDiagram />
 
-Start with the [Quickstart](/docs/agents/quickstart) to run the built-in `horton` and `worker` entities and connect your own app in a few minutes. The [Usage overview](/docs/agents/usage/overview) summarises the full developer surface in a single page.
+See the [Usage overview](/docs/agents/usage/overview) for a summary of the developer surface in a single page.
 
 ## How it works
 
@@ -38,7 +50,7 @@ The runtime SDK is a layer over three foundations:
 
 **Outside the handler.** Any app or other entity can call [`createAgentsClient().observe(entity('/type/id'))`](/docs/agents/usage/clients-and-react) to load an entity's stream into a local DB and react to changes in real time, with the same schemas and types as the handler.
 
-## Entities
+### Entities
 
 Use entities to model anything long-lived and addressable — an agent session, a chat thread, a research job, a coordinator, a worker. You register a **type** with [`registry.define()`](/docs/agents/reference/entity-registry) and spawn **instances** at `/{type}/{id}`. Each instance has its own state, handler, and event stream. See [Defining entities](/docs/agents/usage/defining-entities).
 
@@ -53,7 +65,7 @@ registry.define("assistant", {
 })
 ```
 
-## Handlers
+### Handlers
 
 The function that runs when an entity wakes. Receives a [`HandlerContext`](/docs/agents/reference/handler-context) (`ctx`) and a [`WakeEvent`](/docs/agents/reference/wake-event) (`wake`). The handler decides how to respond: configure an agent, update state, spawn children, or any combination. See [Writing handlers](/docs/agents/usage/writing-handlers).
 
@@ -72,9 +84,9 @@ registry.define("support", {
 })
 ```
 
-## Wakes
+### Waking and notifications
 
-Events that trigger a handler invocation. Wake sources include incoming messages, child completion, state changes, and timers (scheduled sends, cron, timeouts). The [`WakeEvent`](/docs/agents/reference/wake-event) tells the handler why it was woken. See [Waking entities](/docs/agents/usage/waking-entities).
+Events that trigger a handler invocation. Wake sources include incoming messages, child completion, state changes, and timers (scheduled sends, cron, timeouts). The [`WakeEvent`](/docs/agents/reference/wake-event) tells the handler why it was woken.
 
 ```ts
 async handler(ctx, wake) {
@@ -89,35 +101,9 @@ async handler(ctx, wake) {
 }
 ```
 
-## State
+See [Waking entities](/docs/agents/usage/waking-entities) for more information.
 
-Custom persistent collections on the entity. Defined as part of the [entity definition](/docs/agents/reference/entity-definition) and accessed through `ctx.db` alongside the [built-in collections](#built-in-collections). State is local to the entity, typed, and survives restarts. Use it for things that belong to the entity but aren't part of the agent's event stream — an order's items, a research job's findings, a chat session's TODOs. See [Managing state](/docs/agents/usage/managing-state).
-
-```ts
-registry.define("tracker", {
-  state: {
-    items: {
-      schema: z.object({
-        key: z.string(),
-        name: z.string(),
-        done: z.boolean(),
-      }),
-      primaryKey: "key",
-    },
-  },
-  async handler(ctx) {
-    // read
-    const item = ctx.db.collections.items.get("item-1")
-
-    // write
-    ctx.db.actions.items_insert({
-      row: { key: "item-2", name: "New", done: false },
-    })
-  },
-})
-```
-
-## Agent loop
+### The agent loop
 
 The core pattern is [`ctx.useAgent()`](/docs/agents/reference/agent-config) followed by `ctx.agent.run()`. This runs the LLM in a loop — it generates text, calls tools, and continues until it has nothing left to do. All activity is automatically persisted to the entity's stream. See [Configuring the agent](/docs/agents/usage/configuring-the-agent).
 
@@ -131,7 +117,7 @@ ctx.useAgent({
 await ctx.agent.run()
 ```
 
-## Tools
+### Tools
 
 Functions the LLM can call during the agent loop. Each tool has a name, description, parameters (defined with [TypeBox](https://github.com/sinclairzx81/typebox) or any [Standard Schema](https://standardschema.dev) validator), and an execute function. Tools run in the handler's context and have access to the entity's state and coordination primitives. See [Defining tools](/docs/agents/usage/defining-tools) and the [`AgentTool` reference](/docs/agents/reference/agent-tool).
 
@@ -156,7 +142,7 @@ const searchKbTool: AgentTool = {
 }
 ```
 
-## Coordination
+### Coordination
 
 Entities interact through structured primitives. An entity can `spawn` children, `observe` other entities, `send` messages, and [share state](/docs/agents/usage/shared-state). These operations are all durable — they survive restarts and are tracked in the event stream. See [Spawning and coordinating](/docs/agents/usage/spawning-and-coordinating).
 
@@ -170,7 +156,7 @@ async handler(ctx) {
       systemPrompt: "Analyse the report",
       tools: ["read"],
     },
-    { initialMessage: "Find the top three issues", wake: "runFinished" }
+    { initialMessage: "Find the top three issues", wake: { on: "runFinished", includeResponse: true } }
   )
 
   // send a message to another entity
@@ -183,7 +169,7 @@ async handler(ctx) {
 }
 ```
 
-## Built-in collections
+### Built-in collections
 
 Every entity automatically has collections for runs, steps, texts, tool calls, errors, inbox, and more. These are populated by the runtime as the agent operates and give you live observability into every step of the agent loop — useful for chat UIs, debugging tools, dashboards, and analytics. Query them from the handler or observe them externally. See the [Built-in collections reference](/docs/agents/reference/built-in-collections).
 
@@ -198,9 +184,45 @@ const db = await client.observe(entity("/support/ticket-42"))
 console.log(db.collections.texts.toArray)
 ```
 
+
+### Custom collections
+
+Define custom persistent collections on the entity.
+
+Defined as part of the [entity definition](/docs/agents/reference/entity-definition) and accessed through `ctx.db` alongside the [built-in collections](#built-in-collections).
+
+```ts
+registry.define("tracker", {
+  state: {
+    items: {
+      schema: z.object({
+        key: z.string(),
+        name: z.string(),
+        done: z.boolean(),
+      }),
+      primaryKey: "key",
+    },
+  },
+  async handler(ctx) {
+    // read
+    const item = ctx.db.collections.items.get("item-1")
+
+    // write
+    ctx.db.actions.items_insert({
+      row: { key: "item-2", name: "New", done: false },
+    })
+  },
+})
+```
+
+State is local to the entity, typed, and survives restarts. Use it for things that belong to the entity but aren't part of the agent's event stream — an order's items, a research job's findings, a chat session's TODOs.
+
+See [Managing state](/docs/agents/usage/managing-state) for more information.
+
 ## Next steps
 
-- [Quickstart](/docs/agents/quickstart) — run the built-in `horton` and `worker` entities and connect your own app.
+- [Quickstart](/docs/agents/quickstart) — run the built-in `horton` and `worker` entities and connect your own app
+- [Walkthrough](./walkthrough) — go from a web or mobile app to a <span class="no-wrap">multi-agent</span> system
 - [Usage overview](/docs/agents/usage/overview) — the full developer surface on one page.
 - [Defining entities](/docs/agents/usage/defining-entities) — entity types, schemas, and configuration.
 - [Writing handlers](/docs/agents/usage/writing-handlers) — handler lifecycle and the `ctx` API.

package/docs/quickstart.md

@@ -4,16 +4,24 @@ titleTemplate: "... - Electric Agents"
 description: >-
   Run the Electric Agents runtime and the built-in Horton assistant with a single CLI command, then connect from the web UI or define your own entities.
 outline: [2, 3]
+prev:
+  text: 'Overview'
+  link: '/docs/agents/'
+next:
+  text: 'Walkthrough'
+  link: '/docs/agents/walkthrough'
 ---
 
 # Quickstart
 
-One command starts the Electric Agents runtime, the web UI, and a local [Horton](./entities/agents/horton) assistant you can chat with right away. From there, define your own [entities](./usage/defining-entities) in your own app.
+Get started with the Electric Agents runtime, the web UI, and a local [Horton](./entities/agents/horton) assistant you can chat with right away:
 
 ```sh
 npx electric-ax agents quickstart
 ```
 
+Or see the [Walkthrough guide](./walkthrough) for a step-by-step guide to defining your own entities and building a multi-agent system from scratch.
+
 ## What you'll need
 
 - **Node.js 18+**.
@@ -76,11 +84,14 @@ npx electric-ax agents observe /horton/onboarding
 
 See the [CLI reference](./reference/cli) for the full command surface.
 
-## Define your own entity types
+## Define your own entities
+
+Define your own entity types and register them with the runtime server.
 
-Once you're chatting with Horton, the next step is to define your own entity types in your own app. Your app is just a process that registers entity types with the runtime server and receives webhook callbacks when they wake.
+> [!Tip] See the Walkthrough guide
+> See the [Walkthrough](./walkthrough) for a step-by-step guide on how to go from a web or mobile app to a <span class="no-wrap">multi-agent</span> system with Electric Agents.
 
-### 1. Install the runtime SDK
+Install the runtime SDK:
 
 ```sh
 mkdir my-agents-app && cd my-agents-app
@@ -89,8 +100,6 @@ npm install @electric-ax/agents-runtime
 npm install --save-dev tsx
 ```
 
-### 2. Create a server
-
 Create `server.ts`:
 
 ```ts
@@ -140,28 +149,20 @@ server.listen(PORT, async () => {
 })
 ```
 
-This does four things:
-
-1. **Defines an entity type** called `assistant` with a handler that configures and runs an LLM agent.
-2. **Creates a runtime handler** that connects to the runtime server.
-3. **Starts an HTTP server** to receive webhook callbacks from the runtime.
-4. **Registers entity types** with the runtime server on startup.
-
-See [App setup](./usage/app-setup) for the full `createRuntimeHandler` configuration.
+This:
 
-### 3. Run your app
+1. **defines an entity type** called `assistant`
+2. **creates a runtime handler** that connects to the runtime server
+3. **starts an HTTP server** to receive webhook callbacks from the runtime
+4. **registers entity types** with the runtime server on startup
 
-With the runtime server already running (from `electric agents quickstart` or `electric agents start`), start your app:
+Make sure `ANTHROPIC_API_KEY` is exported in this shell (or copy your `.env` into `my-agents-app`). Then, with the runtime server already running (from `electric agents quickstart` or `electric agents start`), start your app:
 
 ```sh
 npx tsx server.ts
 ```
 
-Your handler calls `ctx.useAgent()` in this process, so make sure `ANTHROPIC_API_KEY` is exported in this shell (or copy your `.env` into `my-agents-app`).
-
-### 4. Interact with your entity
-
-Spawn an instance, send it a message, and observe the timeline:
+You can now interact with your custom entity through the [CLI](/docs/agents/reference/cli). For example, to spawn an instance, send it a message, and observe the timeline:
 
 ```sh
 npx electric-ax agents spawn /assistant/my-assistant
@@ -169,7 +170,9 @@ npx electric-ax agents send /assistant/my-assistant 'Hello!'
 npx electric-ax agents observe /assistant/my-assistant
 ```
 
-Or open the web UI at `http://localhost:4437` and pick `/assistant/my-assistant` from the entity list.
+Or open the web UI at [localhost:4437](http://localhost:4437) and create a new session, choosing your assistant type from the entity list.
+
+See the [Walkthrough](./walkthrough) guide and [App setup](./usage/app-setup) docs for more details.
 
 ## Stop the dev environment
 
@@ -193,6 +196,7 @@ See the [CLI reference](./reference/cli#start) for the full set of commands.
 
 ## Next steps
 
+- [Walkthrough](./walkthrough) — go from a web or mobile app to a <span class="no-wrap">multi-agent</span> system
 - [Overview](./) — the mental model behind entities, handlers, and wakes.
 - [Usage overview](./usage/overview) — the full developer surface on one page.
 - [Defining entities](./usage/defining-entities) — entity types, schemas, and configuration.

package/docs/reference/entity-handle.md

@@ -2,13 +2,13 @@
 title: EntityHandle
 titleTemplate: "... - Electric Agents"
 description: >-
-  API reference for EntityHandle returned by spawn and observe: streams, status, text retrieval, and messaging.
+  API reference for EntityHandle returned by spawn and observe: streams, status, and messaging.
 outline: [2, 3]
 ---
 
 # EntityHandle
 
-Handle returned by `ctx.spawn()` and `ctx.observe()`. Provides access to a child or observed entity's stream and status.
+Handle returned by `ctx.spawn()` and `ctx.observe(entity(...))`. It identifies a child or observed entity and exposes its materialized stream.
 
 **Source:** `@electric-ax/agents-runtime`
 
@@ -18,25 +18,60 @@ interface EntityHandle {
   type?: string
   db: EntityStreamDB
   events: ChangeEvent[]
-  run: Promise<void>
-  text(): Promise<string[]>
-  send(msg: unknown): void
+  send(msg: unknown): Promise<SendResult>
   status(): ChildStatus | undefined
 }
 ```
 
 ## Members
 
-| Member      | Type                       | Description                                                                         |
-| ----------- | -------------------------- | ----------------------------------------------------------------------------------- |
-| `entityUrl` | `string`                   | URL path of the entity (e.g. `"/chat/my-child"`).                                   |
-| `type`      | `string \| undefined`      | Entity type name, if known.                                                         |
-| `db`        | `EntityStreamDB`           | The entity's TanStack DB instance for querying its collections.                     |
-| `events`    | `ChangeEvent[]`            | All change events received from this entity's stream.                               |
-| `run`       | `Promise<void>`            | Promise that resolves when the entity's current run completes. Useful with `await`. |
-| `text()`    | `Promise<string[]>`        | Returns all text outputs from the entity's stream.                                  |
-| `send(msg)` | `void`                     | Send a message to this entity.                                                      |
-| `status()`  | `ChildStatus \| undefined` | Current status of the entity, or `undefined` if unknown.                            |
+| Member      | Type                       | Description                                                     |
+| ----------- | -------------------------- | --------------------------------------------------------------- |
+| `entityUrl` | `string`                   | URL path of the entity, e.g. `"/worker/child-1"`.              |
+| `type`      | `string \| undefined`      | Entity type name, if known.                                     |
+| `db`        | `EntityStreamDB`           | The entity's TanStack DB instance for querying its collections. |
+| `events`    | `ChangeEvent[]`            | Change events received from this entity's stream this wake.     |
+| `send(msg)` | `Promise<SendResult>`      | Send a follow-up message to this entity.                        |
+| `status()`  | `ChildStatus \| undefined` | Current child status, or `undefined` if unknown.                |
+
+## Coordinating with completion
+
+`EntityHandle` does **not** provide a same-wake “wait for output” API. To continue after a child finishes, spawn or observe it with a wake condition and return from the current handler:
+
+```ts
+const child = await ctx.spawn(
+  "worker",
+  "analyst-1",
+  { systemPrompt: "Analyze this input", tools: ["read"] },
+  {
+    initialMessage: "...",
+    wake: { on: "runFinished", includeResponse: true },
+  }
+)
+
+ctx.state.children.insert({
+  key: "analyst-1",
+  url: child.entityUrl,
+  status: "running",
+})
+return
+```
+
+On the later wake, inspect the finished child payload and continue orchestration:
+
+```ts
+if (wake.payload?.finished_child) {
+  const finished = wake.payload.finished_child
+  const response = finished.response ?? ""
+
+  ctx.state.children.update(finished.url, (draft) => {
+    draft.status = finished.run_status
+    draft.response = response
+  })
+}
+```
+
+For structured or large outputs, have the child write to shared state and use the `runFinished` wake as the signal that it is safe to read/reduce that state.
 
 ## ChildStatus
 
@@ -49,15 +84,6 @@ interface ChildStatusEntry {
   key: string
   entity_url: string
   entity_type: string
-  status: "spawning" | "running" | "idle" | "stopped"
+  status: "spawning" | "running" | "idle" | "paused" | "stopping" | "stopped" | "killed"
 }
 ```
-
-Status values:
-
-| Status     | Description                                                 |
-| ---------- | ----------------------------------------------------------- |
-| `spawning` | Entity creation is in progress.                             |
-| `running`  | Handler is currently executing.                             |
-| `idle`     | Handler has completed; entity is waiting for the next wake. |
-| `stopped`  | Entity has been stopped or deleted.                         |

package/docs/reference/handler-context.md

@@ -104,7 +104,7 @@ interface HandlerContext<TState extends StateProxy = StateProxy> {
 | `observe(source, opts?)`          | `Promise<EntityHandle \| SharedStateHandle \| ObservationHandle>` | Observe a source. Return type depends on source type: `EntityHandle` for entities, `SharedStateHandle & ObservationHandle` for db, `ObservationHandle` otherwise. Use `entity()`, `cron()`, `entities()`, `db()` helpers to build sources. |
 | `mkdb(id, schema)`                | `SharedStateHandle<T>`                                            | Create a new shared state stream. See [`SharedStateHandle`](./shared-state-handle).                                                                                                                                                        |
 | `send(entityUrl, payload, opts?)` | `void`                                                            | Send a message to another entity. `opts` accepts `type` and `afterMs` (delay in milliseconds).                                                                                                                                             |
-| `recordRun()`                     | `RunHandle`                                                       | Record a non-LLM run in the built-in `runs` collection, so observers using `wake: "runFinished"` are notified when external work completes.                                                                                               |
+| `recordRun()`                     | `RunHandle`                                                       | Record a non-LLM run in the built-in `runs` collection, so observers using `wake: { on: "runFinished", includeResponse: true }` are notified when external work completes.                                                                                               |
 | `setTag(key, value)`              | `Promise<void>`                                                   | Set a tag on this entity.                                                                                                                                                                                                                  |
 | `removeTag(key)`                  | `Promise<void>`                                                   | Remove a tag from this entity.                                                                                                                                                                                                             |
 | `sleep()`                         | `void`                                                            | End the handler without running an agent. The entity remains idle until the next wake.                                                                                                                                                     |

package/docs/reference/wake-event.md

@@ -85,7 +85,7 @@ Inspect the payload to distinguish the sub-kind:
 
 | Sub-kind            | Producer                                                                    | Payload marker                                                                            |
 | ------------------- | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
-| Child finished      | `ctx.spawn(..., { wake: 'runFinished' })` when the child completes or fails | `payload.finished_child` is set (with `run_status` and optional `response`)               |
+| Child finished      | `ctx.spawn(..., { wake: { on: 'runFinished', includeResponse: true } })` when the child completes or fails | `payload.finished_child` is set (with `run_status` and optional `response`)               |
 | Observed change     | `ctx.observe(..., { wake: { on: 'change' } })` or `observe(db(...))`        | `payload.changes` is non-empty                                                            |
 | Shared-state change | `await ctx.observe(db(...), { wake: { on: 'change' } })`                    | `payload.changes` is non-empty, `payload.source` identifies the shared-state stream       |
 | Cron fired          | A cron schedule entry on the entity's manifest                              | `payload.source` identifies the schedule; `payload.changes` is empty                      |

package/docs/usage/defining-tools.md

@@ -187,20 +187,19 @@ function createDispatchTool(ctx: HandlerContext): AgentTool {
         { systemPrompt },
         {
           initialMessage: task,
-          wake: "runFinished",
+          wake: { on: "runFinished", includeResponse: true },
         }
       )
-      const text = (await child.text()).join("\n\n")
       return {
-        content: [{ type: "text", text }],
-        details: {},
+        content: [{ type: "text", text: `Started ${child.entityUrl}; I will continue when it finishes.` }],
+        details: { childUrl: child.entityUrl },
       }
     },
   }
 }
 ```
 
-`ctx.spawn` returns an `EntityHandle`. Passing `wake: 'runFinished'` means the parent will be woken when the child's agent run completes. `child.text()` returns all text outputs from the child's stream.
+`ctx.spawn` returns an `EntityHandle`. Passing `wake: { on: 'runFinished', includeResponse: true }` means the parent will be woken later when the child's agent run completes, with the child's text response included in the wake payload. Tools should start child work and return; continuation happens in the later handler wake.
 
 ## Wiring tools together
 

package/docs/usage/overview.md

@@ -4,6 +4,9 @@ titleTemplate: "... - Electric Agents"
 description: >-
   High level overview of the Electric Agents system and developer APIs.
 outline: [2, 3]
+prev:
+  text: 'Walkthrough'
+  link: '/docs/agents/walkthrough'
 ---
 
 # Usage overview
@@ -140,10 +143,12 @@ function createDispatchTool(ctx: HandlerContext): AgentTool {
         "worker",
         id,
         { systemPrompt, tools: ["read"] },
-        { initialMessage: task, wake: "runFinished" }
+        { initialMessage: task, wake: { on: "runFinished", includeResponse: true } }
       )
-      const text = (await child.text()).join("\n\n")
-      return { content: [{ type: "text", text }], details: {} }
+      return {
+        content: [{ type: "text", text: `Started ${child.entityUrl}; I will continue when it finishes.` }],
+        details: { childUrl: child.entityUrl },
+      }
     },
   }
 }
@@ -180,9 +185,8 @@ See [Managing state](/docs/agents/usage/managing-state).
 
 **EntityHandle** returned from spawn/observe:
 
-- `.entityUrl`, `.type`, `.db` (read-only TanStack DB)
-- `.run` -- Promise that resolves when child completes
-- `.text()` -- get all completed text output
+- `.entityUrl`, `.type` -- identify the entity
+- `.db` / `.events` -- inspect the observed entity stream
 - `.send(msg)` -- send follow-up message
 - `.status()` -- `ChildStatus | undefined` (object with `.status`, `.entity_url`, `.entity_type`)
 

package/docs/usage/shared-state.md

@@ -61,7 +61,7 @@ const child = await ctx.spawn(
     systemPrompt: "...",
     sharedDb: { id: "research-123", schema: researchSchema },
   },
-  { initialMessage: "Research topic X", wake: "runFinished" }
+  { initialMessage: "Research topic X", wake: { on: "runFinished", includeResponse: true } }
 )
 ```
 
@@ -149,7 +149,7 @@ registry.define("debate", {
         systemPrompt: "Argue FOR the topic.",
         sharedDb: { id: `debate-${ctx.entityUrl}`, schema: debateSchema },
       },
-      { initialMessage: "The topic is: ...", wake: "runFinished" }
+      { initialMessage: "The topic is: ...", wake: { on: "runFinished", includeResponse: true } }
     )
 
     const con = await ctx.spawn(
@@ -159,7 +159,7 @@ registry.define("debate", {
         systemPrompt: "Argue AGAINST the topic.",
         sharedDb: { id: `debate-${ctx.entityUrl}`, schema: debateSchema },
       },
-      { initialMessage: "The topic is: ...", wake: "runFinished" }
+      { initialMessage: "The topic is: ...", wake: { on: "runFinished", includeResponse: true } }
     )
 
     // Read all arguments written by both workers

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

@@ -46,36 +46,52 @@ Returned by `spawn` and `observe`:
 interface EntityHandle {
   entityUrl: string
   type?: string
-  db: EntityStreamDB // Read-only TanStack DB
+  db: EntityStreamDB // TanStack DB for the observed entity stream
   events: ChangeEvent[]
-  run: Promise<void> // Resolves when child's run completes
-  text(): Promise<string[]> // Get completed text outputs
-  send(msg: unknown): void // Send follow-up message
+  send(msg: unknown): Promise<SendResult> // Send follow-up message
   status(): ChildStatus | undefined
 }
 ```
 
 `status()` returns a `ChildStatus` object (or `undefined` if no status is known yet) with `.status`, `.entity_url`, `.entity_type`, and `.key`.
 
-## Waiting for children
+## Continuing after children finish
 
-Wait for a single child:
+Do not wait for child output inside the same wake. Instead, spawn or observe the child with a wake condition, persist enough metadata to correlate the child, and return.
 
 ```ts
-await child.run
-const output = (await child.text()).join("\n\n")
-```
+async handler(ctx, wake) {
+  if (ctx.firstWake) {
+    const child = await ctx.spawn(
+      "worker",
+      "analyst",
+      { systemPrompt: "Analyze this input", tools: ["read"] },
+      {
+        initialMessage: "Initial task.",
+        wake: { on: "runFinished", includeResponse: true },
+      }
+    )
 
-Wait for multiple children in parallel:
+    ctx.state.children.insert({
+      key: "analyst",
+      url: child.entityUrl,
+      status: "running",
+    })
+    return
+  }
 
-```ts
-const results = await Promise.all(
-  children.map(async ({ handle }) => ({
-    text: (await handle.text()).join("\n\n"),
-  }))
-)
+  const finished = wake.payload?.finished_child
+  if (finished) {
+    ctx.state.children.update(finished.url, (draft) => {
+      draft.status = finished.run_status
+      draft.response = finished.response ?? ""
+    })
+  }
+}
 ```
 
+Use `includeResponse: true` for simple text handoff. For structured or large outputs, have children write to shared state and use the `runFinished` wake as the continuation signal.
+
 ## observe
 
 Subscribe to an existing entity without spawning it:
@@ -122,7 +138,7 @@ async handler(ctx) {
       { systemPrompt: "...", tools: ["read"] },
       {
         initialMessage: "Initial task.",
-        wake: "runFinished",
+        wake: { on: "runFinished", includeResponse: true },
       }
     )
   }
@@ -157,7 +173,7 @@ await ctx.spawn(
   { systemPrompt: "Summarise this data.", tools: ["read"] },
   {
     initialMessage: JSON.stringify(data),
-    wake: "runFinished",
+    wake: { on: "runFinished", includeResponse: true },
   }
 )
 ```

package/docs/usage/writing-handlers.md

@@ -210,7 +210,7 @@ async handler(ctx, wake) {
 
 ## recordRun
 
-Call `ctx.recordRun()` when a handler does work without `ctx.agent.run()` but still needs to publish run lifecycle events. This is how non-LLM entities can wake parents observing them with `wake: "runFinished"`.
+Call `ctx.recordRun()` when a handler does work without `ctx.agent.run()` but still needs to publish run lifecycle events. This is how non-LLM entities can wake parents observing them with `wake: { on: "runFinished", includeResponse: true }`.
 
 ```ts
 async handler(ctx) {