@electric-ax/agents 0.1.5 → 0.2.2

package/docs/entities/agents/horton.md

@@ -0,0 +1,89 @@
+---
+title: Horton agent
+titleTemplate: '... - Electric Agents'
+description: >-
+  The built-in Horton assistant - chat, research, code, and dispatch subagents in one entity type.
+outline: [2, 3]
+---
+
+# Horton agent
+
+The built-in assistant registered by the Electric Agents dev server. Horton can chat conversationally, search the web, read and edit files, run shell commands, and dispatch subagents (workers) for isolated subtasks.
+
+**Source:** [`packages/agents/src/agents/horton.ts`](https://github.com/electric-sql/electric/blob/main/packages/agents/src/agents/horton.ts)
+
+## Try it
+
+With the dev server running (`npx electric-ax agents quickstart`):
+
+```sh
+npx electric-ax agents spawn /horton/my-horton
+npx electric-ax agents send /horton/my-horton 'What's in this directory?'
+npx electric-ax agents observe /horton/my-horton
+```
+
+## Tools
+
+Horton is configured with `ctx.electricTools` plus the base Horton tool set:
+
+| Tool           | Purpose                                                  |
+| -------------- | -------------------------------------------------------- |
+| `bash`         | Run shell commands in the working directory.             |
+| `read`         | Read a file. Tracked in a per-wake `readSet`.            |
+| `write`        | Create or overwrite a file.                              |
+| `edit`         | Targeted string replacement (file must be `read` first). |
+| `brave_search` | Web search via the Brave Search API.                     |
+| `fetch_url`    | Fetch a URL and return it as markdown.                   |
+| `spawn_worker` | Dispatch a subagent for an isolated subtask.             |
+
+`brave_search` requires `BRAVE_SEARCH_API_KEY` in the environment; without it the tool errors at call time.
+
+When docs support or skills are available, Horton also adds the docs search tool and skill tools during bootstrap.
+
+## Title generation
+
+After the first agent run completes, Horton calls `generateTitle()` (Haiku) to summarise the user's first message into a 3-5 word session title and stores it via `ctx.setTag('title', title)`. Failures are logged and ignored — the entity continues without a title.
+
+## Details
+
+| Property          | Value                                                                             |
+| ----------------- | --------------------------------------------------------------------------------- |
+| Type name         | `horton`                                                                          |
+| Model             | `HORTON_MODEL` (`claude-sonnet-4-5-20250929`)                                     |
+| Title model       | `claude-haiku-4-5-20251001`                                                       |
+| Tools             | `ctx.electricTools` + base Horton tool set, plus docs/skill tools when configured |
+| Working directory | Passed at bootstrap (defaults to `process.cwd()`)                                 |
+| Title generation  | Yes, after the first run if no title tag exists                                   |
+
+## Extending Horton
+
+The system prompt and tool factory are exported so you can build your own variants:
+
+```ts
+import {
+  HORTON_MODEL,
+  buildHortonSystemPrompt,
+  createHortonTools,
+} from '@electric-ax/agents'
+
+registry.define('my-assistant', {
+  description: 'Horton with an extra custom tool',
+  async handler(ctx) {
+    const readSet = new Set<string>()
+    ctx.useAgent({
+      systemPrompt: buildHortonSystemPrompt(process.cwd()),
+      model: HORTON_MODEL,
+      tools: [
+        ...ctx.electricTools,
+        ...createHortonTools(process.cwd(), ctx, readSet),
+        myCustomTool,
+      ],
+    })
+    await ctx.agent.run()
+  },
+})
+```
+
+## Related
+
+- [Worker](./worker) — the subagent type Horton dispatches via `spawn_worker`.

package/docs/entities/agents/worker.md

@@ -0,0 +1,102 @@
+---
+title: Worker
+titleTemplate: '... - Electric Agents'
+description: >-
+  Generic sandboxed subagent type. Spawned by Horton (or any agent) via the spawn_worker tool with a system prompt and a chosen tool subset.
+outline: [2, 3]
+---
+
+# Worker
+
+A generic, sandboxed subagent type. Workers are spawned by other agents (typically [Horton](./horton)) via the `spawn_worker` tool — the spawner provides a system prompt and picks the subset of tools the worker should have access to.
+
+**Source:** [`packages/agents/src/agents/worker.ts`](https://github.com/electric-sql/electric/blob/main/packages/agents/src/agents/worker.ts)
+
+## Spawn args
+
+```ts
+interface WorkerArgs {
+  systemPrompt: string
+  tools?: Array<WorkerToolName>
+  sharedDb?: { id: string; schema: SharedStateSchemaMap }
+  sharedDbToolMode?: 'full' | 'write-only'
+}
+```
+
+| Field              | Required | Description                                                                                   |
+| ------------------ | -------- | --------------------------------------------------------------------------------------------- |
+| `systemPrompt`     | Yes      | The worker's system prompt. Brief it like a colleague: file paths, line numbers, deliverable. |
+| `tools`            | No       | Subset of valid tool names (see below). Unknown names throw at parse time.                    |
+| `sharedDb`         | No       | Shared state stream id and schema to connect to.                                              |
+| `sharedDbToolMode` | No       | Shared state tool mode: `"full"` (default) or `"write-only"`.                                 |
+
+`registerWorker(registry, { workingDirectory, streamFn? })` is called by the dev server during bootstrap; you don't usually call it yourself.
+
+## Valid tool names
+
+```ts
+type WorkerToolName =
+  | 'bash'
+  | 'read'
+  | 'write'
+  | 'edit'
+  | 'brave_search'
+  | 'fetch_url'
+  | 'spawn_worker'
+```
+
+These are the same primitives Horton uses. Pick the smallest subset the worker needs — tools are the worker's permission set.
+
+The worker must receive at least one tool or a `sharedDb` config. If `sharedDb` is provided, the worker gets generated shared-state tools in addition to any selected primitives.
+
+## Spawning a worker
+
+The canonical way to spawn a worker is the `spawn_worker` tool, which Horton calls from inside its agent loop:
+
+```ts
+spawn_worker({
+  systemPrompt:
+    'You are a focused researcher. Find the three most-cited papers on X and return their titles, authors, and DOIs as a markdown table.',
+  tools: ['brave_search', 'fetch_url'],
+  initialMessage: 'Begin research now.',
+})
+```
+
+| Field            | Required | Notes                                                                         |
+| ---------------- | -------- | ----------------------------------------------------------------------------- |
+| `systemPrompt`   | Yes      | Sets persona and constraints.                                                 |
+| `tools`          | Yes      | Subset of `WorkerToolName`. Must contain at least one entry.                  |
+| `initialMessage` | Yes      | First user message. **Without this the worker idles** — nothing kicks it off. |
+
+The spawn uses `wake: { on: 'runFinished', includeResponse: true }`, so the spawner wakes when the worker finishes its run and receives the worker's response in the wake message.
+
+## What the handler does
+
+1. Parses `ctx.args` into `WorkerArgs`. Throws if `systemPrompt` is empty, if `tools` contains an unknown name, or if neither `tools` nor `sharedDb` is provided.
+2. Builds the requested tool instances against the worker's `workingDirectory` (and a fresh per-wake `readSet` for the read-first-then-edit guard).
+3. If `sharedDb` is present, connects with `ctx.observe(db(id, schema))` and exposes generated `read_*`, `write_*`, `update_*`, and `delete_*` tools (`write_*` only in `"write-only"` mode).
+4. Configures the agent with `HORTON_MODEL` (`claude-sonnet-4-5-20250929`), the provided system prompt (with a brief reporting-back footer appended), and the assembled tool list.
+5. Runs the agent until the LLM stops.
+
+::: warning Least-privilege sandbox
+Workers deliberately do **not** receive `ctx.electricTools`. The spawner already picked the worker's tool subset; granting entity-runtime primitives (cron, schedule, send-to-arbitrary-entity) would let a worker escape that scope. If a worker needs those primitives, it must spawn its own subagent or report back to the spawner.
+:::
+
+## Reporting footer
+
+The runtime appends this to every worker's system prompt:
+
+```text
+# Reporting back
+When you finish, respond with a concise report covering what was done and any key findings. The caller will relay this to the user, so it only needs the essentials.
+```
+
+## Details
+
+| Property          | Value                                                                                                                     |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| Type name         | `worker`                                                                                                                  |
+| Model             | `HORTON_MODEL` (`claude-sonnet-4-5-20250929`)                                                                             |
+| Tools             | Subset of 7 primitives plus optional shared-state tools. **No `ctx.electricTools`.**                                      |
+| Working directory | Provided to `registerWorker` at bootstrap                                                                                 |
+| Description       | `Internal — generic worker spawned by other agents. Configure via spawn args (systemPrompt + tools + optional sharedDb).` |

package/docs/entities/patterns/blackboard.md

@@ -0,0 +1,111 @@
+---
+title: Blackboard (shared state)
+titleTemplate: '... - Electric Agents'
+description: >-
+  Multi-agent coordination using shared state as a common data structure for reads and writes.
+outline: [2, 3]
+---
+
+# Blackboard (shared state)
+
+Pattern: multiple agents coordinate through a shared data structure. A parent creates shared state, spawns workers that connect to it, and workers read/write shared collections via auto-generated CRUD tools.
+
+**Source:** [`packages/agents-runtime/skills/designing-entities/references/patterns/blackboard.md`](https://github.com/electric-sql/electric/blob/main/packages/agents-runtime/skills/designing-entities/references/patterns/blackboard.md)
+
+## Debate example
+
+The canonical blackboard example: a moderator runs a structured debate between pro and con workers via shared state.
+
+### Schema
+
+```ts
+const debateSchema = {
+  arguments: {
+    schema: z.object({
+      key: z.string(),
+      side: z.enum(['pro', 'con']),
+      text: z.string(),
+      round: z.number(),
+    }),
+    type: 'shared:argument',
+    primaryKey: 'key',
+  },
+}
+```
+
+### Registration
+
+```ts
+import { db } from '@electric-ax/agents-runtime'
+
+export function registerDebate(registry: EntityRegistry) {
+  registry.define(`debate`, {
+    description: `Debate moderator that creates shared state, spawns pro and con workers, and writes a final ruling based on arguments written to shared state`,
+    state: {
+      status: { primaryKey: `key` },
+    },
+
+    async handler(ctx) {
+      if (ctx.firstWake) {
+        ctx.db.actions.status_insert({ row: { key: `current`, value: `idle` } })
+        ctx.mkdb(`debate-${ctx.entityUrl}`, debateSchema)
+      }
+      const shared = await ctx.observe(
+        db(`debate-${ctx.entityUrl}`, debateSchema)
+      )
+
+      // ... create tools that reference `shared` ...
+
+      ctx.useAgent({
+        systemPrompt: DEBATE_SYSTEM_PROMPT,
+        model: `claude-sonnet-4-5-20250929`,
+        tools: [...ctx.electricTools, startTool, checkTool, endTool],
+      })
+      await ctx.agent.run()
+    },
+  })
+}
+```
+
+### How it works
+
+1. On first wake, the moderator creates shared state with `ctx.mkdb()`.
+2. The moderator connects to the shared state with `ctx.observe(db(...))`.
+3. The `start_debate` tool spawns pro and con workers, each connected to the same shared state:
+
+```ts
+const proWorker = await ctx.spawn(
+  `worker`,
+  `debate-pro-${Date.now()}-${spawnCounter}`,
+  {
+    systemPrompt: PRO_WORKER_PROMPT,
+    sharedDb: { id: `debate-${ctx.entityUrl}`, schema: debateSchema },
+  },
+  { initialMessage: proInitialMessage, wake: `runFinished` }
+)
+```
+
+4. Workers write arguments to the shared `arguments` collection using auto-generated `write_arguments` tools (see [Worker](../agents/worker.md)).
+5. The `check_debate` tool reads the shared state to see current arguments:
+
+```ts
+const args = shared.arguments.toArray
+```
+
+6. The `end_debate` tool reads all arguments and transitions to `done`.
+
+### State transitions
+
+```ts
+type DebateStatus = 'idle' | 'debating' | 'ruling' | 'done'
+```
+
+## Other blackboard variants
+
+The same structure applies to other blackboard workflows:
+
+- **Wiki** -- specialist workers collaboratively build a knowledge base. Each writes articles to a shared `articles` collection.
+- **Peer review** -- workers submit reviews with scores and feedback to a shared `reviews` collection. A coordinator summarizes the reviews.
+- **Trading floor** -- trader agents submit buy/sell orders to a shared `orders` collection and transition through market sessions.
+
+All follow the same structure: parent creates shared state, spawns workers with `sharedDb` in their args, workers use generated CRUD tools to coordinate.

package/docs/entities/patterns/dispatcher.md

@@ -0,0 +1,77 @@
+---
+title: Dispatcher
+titleTemplate: '... - Electric Agents'
+description: >-
+  Message routing pattern that classifies incoming messages and dispatches to specialist agents.
+outline: [2, 3]
+---
+
+# Dispatcher
+
+Pattern: classify incoming messages and route to the appropriate agent type.
+
+**Source:** [`packages/agents-runtime/skills/designing-entities/references/patterns/dispatcher.md`](https://github.com/electric-sql/electric/blob/main/packages/agents-runtime/skills/designing-entities/references/patterns/dispatcher.md)
+
+## Registration
+
+```ts
+export function registerDispatcher(registry: EntityRegistry) {
+  registry.define(`dispatcher`, {
+    description: `Router agent that classifies incoming messages and dispatches to the appropriate specialist agent type`,
+
+    async handler(ctx) {
+      const dispatchTool = createDispatchTool(ctx)
+
+      ctx.useAgent({
+        systemPrompt: DISPATCHER_SYSTEM_PROMPT,
+        model: `claude-sonnet-4-5-20250929`,
+        tools: [...ctx.electricTools, dispatchTool],
+      })
+      await ctx.agent.run()
+    },
+  })
+}
+```
+
+::: info No local state
+The dispatcher entity defines no `state` collections. It is stateless -- it relies entirely on the wake mechanism to receive child completion events and forwards specialist output to the user.
+:::
+
+## How it works
+
+The dispatcher exposes a `dispatch` tool. When the LLM classifies an incoming message, it calls the tool with:
+
+- `type` -- the entity type to spawn (e.g. `"horton"`, `"worker"`, or an app-defined type)
+- `systemPrompt` -- a focused prompt crafted for the task
+- `task` -- the original message to forward
+
+The tool then:
+
+1. Spawns the requested entity type with `wake: 'runFinished'`.
+2. Returns immediately with a status message. The dispatcher is re-invoked when the specialist finishes.
+
+## Dispatch tool
+
+```ts
+await ctx.spawn(
+  type,
+  id,
+  type === `worker` ? { systemPrompt, tools: [`read`] } : { systemPrompt },
+  {
+    initialMessage: task,
+    wake: `runFinished`,
+  }
+)
+
+return {
+  content: [
+    {
+      type: `text` as const,
+      text: `Dispatched to "${type}" specialist (${id}). You will be woken when it finishes.`,
+    },
+  ],
+  details: { id, type },
+}
+```
+
+When dispatching to the built-in `worker`, include its required tool subset in the spawn args.

package/docs/entities/patterns/manager-worker.md

@@ -0,0 +1,127 @@
+---
+title: Manager-Worker
+titleTemplate: '... - Electric Agents'
+description: >-
+  Coordination pattern where a parent spawns specialist children, waits for completion, and synthesizes results.
+outline: [2, 3]
+---
+
+# Manager-Worker
+
+Pattern: a parent agent spawns multiple specialist children, waits for all to complete, and synthesizes results.
+
+**Source:** [`packages/agents-runtime/skills/designing-entities/references/patterns/manager-worker.md`](https://github.com/electric-sql/electric/blob/main/packages/agents-runtime/skills/designing-entities/references/patterns/manager-worker.md)
+
+## Registration
+
+```ts
+export function registerManagerWorker(registry: EntityRegistry) {
+  registry.define(`manager-worker`, {
+    description: `Manager agent that spawns optimist, pessimist, and pragmatist workers to analyze any question from multiple perspectives`,
+    state: {
+      children: { schema: managerChildSchema, primaryKey: `key` },
+    },
+
+    async handler(ctx) {
+      const analyzeTool = createAnalyzeWithPerspectivesTool(ctx)
+
+      ctx.useAgent({
+        systemPrompt: MANAGER_SYSTEM_PROMPT,
+        model: `claude-sonnet-4-5-20250929`,
+        tools: [...ctx.electricTools, analyzeTool],
+      })
+      await ctx.agent.run()
+    },
+  })
+}
+```
+
+## How it works
+
+The manager defines a handler-scoped tool called `analyze_with_perspectives`. When the LLM calls this tool, it:
+
+1. Spawns 3 worker children -- optimist, pessimist, pragmatist -- each with a different system prompt.
+2. Sends the same question to all three as `initialMessage`.
+3. Uses `wake: 'runFinished'` to wait for each child to complete.
+4. Collects results with `Promise.all` and `handle.text()`.
+5. Returns the combined perspectives to the LLM for synthesis.
+
+On subsequent calls, the tool reuses existing children via `ctx.observe()` and `child.send()` instead of spawning new ones.
+
+## Spawn-or-reuse pattern
+
+The core of the tool -- first-call spawns, subsequent calls reuse:
+
+```ts
+for (const perspective of PERSPECTIVES) {
+  const existing = children.get(perspective.id)
+  const childId = `${parentId}-${perspective.id}`
+
+  if (!existing?.url) {
+    // First time: spawn a new worker
+    const child = await ctx.spawn(
+      `worker`,
+      childId,
+      { systemPrompt: perspective.systemPrompt, tools: [`read`] },
+      { initialMessage: question, wake: `runFinished` }
+    )
+    children.insert({
+      key: perspective.id,
+      url: child.entityUrl,
+      kind: perspective.id,
+      question,
+    })
+    handles.push({ id: perspective.id, handle: child })
+    continue
+  }
+
+  // Subsequent calls: observe existing child and send new question
+  const child = await ctx.observe(entity(existing.url))
+  child.send(question)
+  children.update(perspective.id, (draft) => {
+    draft.question = question
+  })
+  handles.push({ id: perspective.id, handle: child })
+}
+```
+
+## Collecting results
+
+The `readLatestCompletedText` helper awaits the child's current run, reads all text outputs, and returns the last one:
+
+```ts
+async function readLatestCompletedText(
+  handle: EntityHandle,
+  fallback: string
+): Promise<string> {
+  await handle.run
+  const runs = await handle.text()
+  const latest = runs[runs.length - 1]?.trim()
+  return latest || fallback
+}
+
+const results = await Promise.all(
+  handles.map(async ({ id, handle }) => ({
+    id,
+    text: await readLatestCompletedText(
+      handle,
+      `(no completed output from ${id})`
+    ),
+  }))
+)
+```
+
+## State
+
+The `children` collection tracks spawned workers:
+
+```ts
+const managerChildSchema = z.object({
+  key: z.string(),
+  url: z.string(),
+  kind: z.string(),
+  question: z.string(),
+})
+```
+
+This allows the manager to find and reuse children across handler invocations.

package/docs/entities/patterns/map-reduce.md

@@ -0,0 +1,81 @@
+---
+title: Map-Reduce
+titleTemplate: '... - Electric Agents'
+description: >-
+  Parallel processing pattern that splits work into chunks, processes simultaneously, and reduces results.
+outline: [2, 3]
+---
+
+# Map-Reduce
+
+Pattern: split input into chunks, process all in parallel, collect results.
+
+**Source:** [`packages/agents-runtime/skills/designing-entities/references/patterns/map-reduce.md`](https://github.com/electric-sql/electric/blob/main/packages/agents-runtime/skills/designing-entities/references/patterns/map-reduce.md)
+
+## Registration
+
+```ts
+export function registerMapReduce(registry: EntityRegistry) {
+  registry.define(`map-reduce`, {
+    description: `Map-reduce orchestrator that splits input into chunks, processes them in parallel with worker agents, then synthesizes results`,
+    state: {
+      children: { primaryKey: `key` },
+    },
+
+    async handler(ctx) {
+      ctx.useAgent({
+        systemPrompt: MAP_REDUCE_SYSTEM_PROMPT,
+        model: `claude-sonnet-4-5-20250929`,
+        tools: [...ctx.electricTools, createMapChunksTool(ctx)],
+      })
+      await ctx.agent.run()
+    },
+  })
+}
+```
+
+## How it works
+
+The agent exposes a `map_chunks` tool. When called:
+
+1. **Map phase** -- spawns one worker per chunk simultaneously. All workers run in parallel.
+2. Returns immediately. The entity is re-invoked as each worker finishes.
+3. The LLM synthesizes results once all workers have reported in via wake events.
+
+## Core
+
+```ts
+// Map phase - spawn all workers in parallel
+for (let i = 0; i < chunks.length; i++) {
+  spawnCounter++
+  const id = `chunk-${i}-${Date.now()}-${spawnCounter}`
+  const child = await ctx.spawn(
+    `worker`,
+    id,
+    { systemPrompt: task, tools: [`read`] },
+    {
+      initialMessage: chunks[i],
+      wake: `runFinished`,
+    }
+  )
+  ctx.db.actions.children_insert({
+    row: { key: id, url: child.entityUrl, chunk: i },
+  })
+}
+
+return {
+  content: [
+    {
+      type: `text` as const,
+      text: `Spawned ${chunks.length} parallel workers. You will be woken as each finishes with its output in finished_child.response.`,
+    },
+  ],
+  details: { chunkCount: chunks.length },
+}
+```
+
+## State collections
+
+| Collection | Purpose                                        |
+| ---------- | ---------------------------------------------- |
+| `children` | Spawned chunk workers (key, URL, chunk index). |

package/docs/entities/patterns/pipeline.md

@@ -0,0 +1,101 @@
+---
+title: Pipeline
+titleTemplate: '... - Electric Agents'
+description: >-
+  Sequential processing pattern where each stage's output feeds into the next via state transitions.
+outline: [2, 3]
+---
+
+# Pipeline
+
+Pattern: sequential stages where each stage's output feeds into the next.
+
+**Source:** [`packages/agents-runtime/skills/designing-entities/references/patterns/pipeline.md`](https://github.com/electric-sql/electric/blob/main/packages/agents-runtime/skills/designing-entities/references/patterns/pipeline.md)
+
+## Registration
+
+```ts
+export function registerPipeline(registry: EntityRegistry) {
+  registry.define(`pipeline`, {
+    description: `Pipeline orchestrator that chains sequential worker stages, feeding each stage output into the next`,
+    state: {
+      children: { primaryKey: `key` },
+    },
+
+    async handler(ctx) {
+      ctx.useAgent({
+        systemPrompt: PIPELINE_SYSTEM_PROMPT,
+        model: `claude-sonnet-4-5-20250929`,
+        tools: [...ctx.electricTools, createRunStageTool(ctx)],
+      })
+      await ctx.agent.run()
+    },
+  })
+}
+```
+
+## How it works
+
+The pipeline agent exposes a `run_stage` tool. The LLM drives the pipeline one stage at a time:
+
+1. The LLM calls `run_stage` with an instruction and input for the current stage.
+2. The tool spawns a worker with the instruction as its system prompt and the input as `initialMessage`, using `wake: 'runFinished'`.
+3. The tool returns immediately. The pipeline entity is re-invoked when the worker finishes.
+4. On each re-invocation, the wake event contains `finished_child.response` with the stage's output. The LLM then calls `run_stage` again with the next stage's instruction and the previous output as input.
+5. This repeats until all stages are complete.
+
+## Stage tool
+
+```ts
+function createRunStageTool(ctx: HandlerContext): AgentTool {
+  let stageCount = 0
+
+  return {
+    name: `run_stage`,
+    label: `Run Stage`,
+    description: `Spawns a worker for one pipeline stage.`,
+    parameters: Type.Object({
+      instruction: Type.String({
+        description: `The instruction for this stage.`,
+      }),
+      input: Type.String({ description: `The input for this stage.` }),
+    }),
+    execute: async (_toolCallId, params) => {
+      const { instruction, input } = params as {
+        instruction: string
+        input: string
+      }
+
+      stageCount++
+      const parentId = entityIdFromUrl(ctx.entityUrl)
+      const id = `${parentId}-stage-${stageCount}`
+
+      const child = await ctx.spawn(
+        `worker`,
+        id,
+        { systemPrompt: instruction, tools: [`read`] },
+        { initialMessage: input, wake: `runFinished` }
+      )
+      ctx.db.actions.children_insert({
+        row: { key: id, url: child.entityUrl, stage: stageCount },
+      })
+
+      return {
+        content: [
+          {
+            type: `text` as const,
+            text: `Stage ${stageCount} spawned. You will be woken when it finishes.`,
+          },
+        ],
+        details: { stage: stageCount },
+      }
+    },
+  }
+}
+```
+
+## State collections
+
+| Collection | Purpose                                             |
+| ---------- | --------------------------------------------------- |
+| `children` | Spawned worker references (key, URL, stage number). |