@electric-ax/agents 0.4.12 → 0.4.13

package/dist/index.d.ts

@@ -36,12 +36,26 @@ declare function createAgentHandler(agentServerUrl: string, workingDirectory?: s
 declare function registerBuiltinAgentTypes(bootstrap: AgentHandlerResult): Promise<void>;
 declare const registerAgentTypes: typeof registerBuiltinAgentTypes;
 
+//#endregion
+//#region src/durable-streams-cache.d.ts
+type DurableStreamsFetchCacheOptions = false | {
+  store?: `memory` | `sqlite`;
+  sqliteLocation?: string;
+  maxCount?: number;
+};
+
 //#endregion
 //#region src/server.d.ts
 interface BuiltinAgentsServerOptions {
   agentServerUrl: string;
   workingDirectory?: string;
   mockStreamFn?: StreamFn;
+  /**
+   * Configure the process-wide HTTP cache used by Undici-backed fetch calls.
+   * Defaults to a 100 MiB in-memory cache. Pass `false` to leave the global
+   * dispatcher unchanged.
+   */
+  durableStreamsFetchCache?: DurableStreamsFetchCacheOptions;
   /** Pull-wake runner configuration for built-in agents. */
   pullWake: {
     runnerId: string;
@@ -92,11 +106,24 @@ declare class BuiltinAgentsServer {
   private mcpToolProviderName;
   private mcpApplyInFlight;
   private mcpStopping;
+  private mcpExtras;
+  private mcpLastJsonConfig;
   private pullWakeRunner;
   readonly options: BuiltinAgentsServerOptions;
   constructor(options: BuiltinAgentsServerOptions);
   /** Embedded MCP registry. `null` until `start()` has run. */
   get mcpRegistry(): Registry | null;
+  /**
+   * Replace the in-memory `extras` list and re-apply the merged config
+   * against the last-known workspace `mcp.json` state. Workspace
+   * `mcp.json` still wins on name collision. No-op once `stop()` has
+   * latched `mcpStopping`.
+   */
+  setExtraMcpServers(extras: ReadonlyArray<McpServerConfig$1>): Promise<void>;
+  private wirePersistence;
+  private mergeMcp;
+  private runApply;
+  private applyMerged;
   start(): Promise<string>;
   stop(): Promise<void>;
   private registerPullWakeRunner;

package/dist/index.js

@@ -1,7 +1,7 @@
 import { mergeElectricPrincipalHeader } from "./server-headers-KD5yHFYT.js";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { MOONSHOT_API_BASE_URL, MOONSHOT_PROVIDER, appendPathToUrl, completeWithLowCostModel, createEntityRegistry, createPullWakeRunner, createRuntimeHandler, createSkillTools, createSkillsRegistry, db, detectAvailableProviders, getMoonshotApiKey, getMoonshotModels, readCodexAccessToken, registerToolProvider, unregisterToolProvider } from "@electric-ax/agents-runtime";
+import { MOONSHOT_API_BASE_URL, MOONSHOT_PROVIDER, appendPathToUrl, completeWithLowCostModel, createEntityRegistry, createPullWakeRunner, createRuntimeHandler, createSkillTools, createSkillsRegistry, db, detectAvailableProviders, getMoonshotApiKey, getMoonshotModel, getMoonshotModels, readCodexAccessToken, registerToolProvider, unregisterToolProvider } from "@electric-ax/agents-runtime";
 import { braveSearchTool, braveSearchTool as braveSearchTool$1, createBashTool, createEditTool, createEventSourceTools, createFetchUrlTool, createReadFileTool, createSendTool, createWriteTool } from "@electric-ax/agents-runtime/tools";
 import { chooseDefaultSandbox, isE2BAvailable, remoteSandbox } from "@electric-ax/agents-runtime/sandbox";
 import fsSync from "node:fs";
@@ -15,6 +15,7 @@ import { load } from "sqlite-vec";
 import { nanoid } from "nanoid";
 import { getModels } from "@mariozechner/pi-ai";
 import { bridgeMcpTool, buildPromptTools, buildResourceTools, createRegistry, keychainPersistence, loadConfig, mcp, watchConfig } from "@electric-ax/agents-mcp";
+import { Agent, cacheStores, interceptors, setGlobalDispatcher } from "undici";
 
 //#region src/log.ts
 const LOG_LEVEL = process.env.ELECTRIC_AGENTS_LOG_LEVEL ?? `info`;
@@ -865,6 +866,15 @@ async function fetchAvailableModelIds(provider) {
 function knownModelsForProvider(provider) {
 	return provider === MOONSHOT_PROVIDER ? getMoonshotModels() : getModels(provider);
 }
+function resolveBuiltinModelContextWindow(modelConfig) {
+	const modelId = String(modelConfig.model);
+	if (modelConfig.provider === MOONSHOT_PROVIDER) return getMoonshotModel(modelId)?.contextWindow ?? null;
+	if (!modelConfig.provider) return null;
+	return knownModelsForProvider(modelConfig.provider).find((model) => model.id === modelId)?.contextWindow ?? null;
+}
+function resolveBuiltinModelSourceBudget(modelConfig) {
+	return resolveBuiltinModelContextWindow(modelConfig) ?? 1e5;
+}
 function choiceForKnownModel(provider, model) {
 	return {
 		provider,
@@ -1239,6 +1249,7 @@ function createAssistantHandler(options) {
 	return async function assistantHandler(ctx, wake) {
 		const readSet = new Set();
 		const modelConfig = resolveBuiltinModelConfig(modelCatalog, ctx.args);
+		const sourceBudget = resolveBuiltinModelSourceBudget(modelConfig);
 		const sandboxCwd = ctx.sandbox.workingDirectory;
 		const agentsMd = await readAgentsMd(ctx.sandbox);
 		const tools = [
@@ -1272,7 +1283,7 @@ function createAssistantHandler(options) {
 			}
 		})() : Promise.resolve();
 		if (docsSupport) ctx.useContext({
-			sourceBudget: 1e5,
+			sourceBudget,
 			sources: {
 				docs_toc: {
 					content: () => docsSupport.renderCompressedToc(),
@@ -1301,7 +1312,7 @@ function createAssistantHandler(options) {
 			}
 		});
 		else if (skillsRegistry && skillsRegistry.catalog.size > 0) ctx.useContext({
-			sourceBudget: 1e5,
+			sourceBudget,
 			sources: {
 				skills_catalog: {
 					content: () => skillsRegistry.renderCatalog(2e3),
@@ -1320,7 +1331,7 @@ function createAssistantHandler(options) {
 			}
 		});
 		else if (agentsMd) ctx.useContext({
-			sourceBudget: 1e5,
+			sourceBudget,
 			sources: {
 				conversation: {
 					content: () => ctx.timelineMessages(),
@@ -1377,6 +1388,15 @@ function registerHorton(registry, options) {
 	registry.define(`horton`, {
 		description: `Friendly capable assistant — chat, code, research, dispatch`,
 		creationSchema: hortonCreationSchema,
+		permissionGrants: [{
+			subject_kind: `principal_kind`,
+			subject_value: `user`,
+			permission: `spawn`
+		}, {
+			subject_kind: `principal_kind`,
+			subject_value: `user`,
+			permission: `manage`
+		}],
 		handler: assistantHandler
 	});
 	return [`horton`];
@@ -1418,7 +1438,7 @@ function parseWorkerArgs(value) {
 	if (typeof value.reasoningEffort === `string` && REASONING_EFFORT_VALUES.includes(value.reasoningEffort)) args.reasoningEffort = value.reasoningEffort;
 	return args;
 }
-function buildToolsForWorker(tools, sandbox, ctx, readSet) {
+function buildToolsForWorker(tools, sandbox, ctx, readSet, opts) {
 	const out = [];
 	for (const name of tools) switch (name) {
 		case `bash`:
@@ -1437,7 +1457,10 @@ function buildToolsForWorker(tools, sandbox, ctx, readSet) {
 			out.push(braveSearchTool$1);
 			break;
 		case `fetch_url`:
-			out.push(createFetchUrlTool(sandbox));
+			out.push(createFetchUrlTool(sandbox, {
+				catalog: opts.modelCatalog,
+				modelConfig: opts.modelConfig
+			}));
 			break;
 		case `spawn_worker`:
 			out.push(createSpawnWorkerTool(ctx));
@@ -1548,11 +1571,23 @@ function registerWorker(registry, options) {
 	const { streamFn, modelCatalog } = options;
 	registry.define(`worker`, {
 		description: `Internal — generic worker spawned by other agents. Configure via spawn args (systemPrompt + tools + optional sharedDb).`,
+		permissionGrants: [{
+			subject_kind: `principal_kind`,
+			subject_value: `user`,
+			permission: `spawn`
+		}, {
+			subject_kind: `principal_kind`,
+			subject_value: `user`,
+			permission: `manage`
+		}],
 		async handler(ctx) {
 			const args = parseWorkerArgs(ctx.args);
 			const readSet = new Set();
-			const builtinTools = buildToolsForWorker(args.tools, ctx.sandbox, ctx, readSet);
 			const modelConfig = resolveBuiltinModelConfig(modelCatalog, args);
+			const builtinTools = buildToolsForWorker(args.tools, ctx.sandbox, ctx, readSet, {
+				modelCatalog,
+				modelConfig
+			});
 			const sharedStateTools = [];
 			if (args.sharedDb) {
 				const shared = await ctx.observe(db(args.sharedDb.id, args.sharedDb.schema));
@@ -1746,6 +1781,18 @@ function resolveCwd(args, fallback) {
 	return readWorkingDirectoryArg(args) ?? fallback;
 }
 
+//#endregion
+//#region src/durable-streams-cache.ts
+const MEMORY_CACHE_SIZE_BYTES = 100 * 1024 * 1024;
+function installDurableStreamsFetchCache(options = {}) {
+	if (options === false) return;
+	const store = options.store === `sqlite` || options.sqliteLocation ? new cacheStores.SqliteCacheStore({
+		location: options.sqliteLocation,
+		maxCount: options.maxCount
+	}) : new cacheStores.MemoryCacheStore({ maxSize: MEMORY_CACHE_SIZE_BYTES });
+	setGlobalDispatcher(new Agent().compose(interceptors.cache({ store })));
+}
+
 //#endregion
 //#region src/server.ts
 var BuiltinAgentsServer = class {
@@ -1755,6 +1802,8 @@ var BuiltinAgentsServer = class {
 	mcpToolProviderName = null;
 	mcpApplyInFlight = new Set();
 	mcpStopping = false;
+	mcpExtras = [];
+	mcpLastJsonConfig = null;
 	pullWakeRunner = null;
 	options;
 	constructor(options) {
@@ -1764,8 +1813,70 @@ var BuiltinAgentsServer = class {
 	get mcpRegistry() {
 		return this._mcpRegistry;
 	}
+	/**
+	* Replace the in-memory `extras` list and re-apply the merged config
+	* against the last-known workspace `mcp.json` state. Workspace
+	* `mcp.json` still wins on name collision. No-op once `stop()` has
+	* latched `mcpStopping`.
+	*/
+	async setExtraMcpServers(extras) {
+		if (!this._mcpRegistry || this.mcpStopping) return;
+		this.mcpExtras = extras;
+		await this.applyMerged(this.mcpLastJsonConfig);
+	}
+	async wirePersistence(cfg) {
+		const servers = [];
+		for (const s of cfg.servers) if (s.transport === `http` && s.auth?.mode === `authorizationCode`) {
+			const persist = await keychainPersistence({ server: s.name });
+			servers.push({
+				...s,
+				auth: {
+					...s.auth,
+					...persist
+				}
+			});
+		} else servers.push(s);
+		return {
+			...cfg,
+			servers
+		};
+	}
+	mergeMcp(jsonCfg) {
+		const jsonServers = jsonCfg?.servers ?? [];
+		const jsonNames = new Set(jsonServers.map((s) => s.name));
+		const filteredExtras = this.mcpExtras.filter((s) => !jsonNames.has(s.name));
+		return {
+			servers: [...filteredExtras, ...jsonServers],
+			raw: jsonCfg?.raw
+		};
+	}
+	async runApply(jsonCfg) {
+		if (this.mcpStopping) return;
+		const registry = this._mcpRegistry;
+		if (!registry) return;
+		try {
+			const wired = await this.wirePersistence(this.mergeMcp(jsonCfg));
+			if (this.mcpStopping) return;
+			await registry.applyConfig(wired);
+		} catch (e) {
+			serverLog.error(`[mcp] applyConfig:`, e);
+			try {
+				this.options.onConfigError?.(e);
+			} catch (cbErr) {
+				serverLog.error(`[mcp] onConfigError callback failed:`, cbErr);
+			}
+		}
+	}
+	applyMerged(jsonCfg) {
+		this.mcpLastJsonConfig = jsonCfg;
+		const p = this.runApply(jsonCfg);
+		this.mcpApplyInFlight.add(p);
+		p.finally(() => this.mcpApplyInFlight.delete(p));
+		return p;
+	}
 	async start() {
 		if (this.bootstrap || this.pullWakeRunner) throw new Error(`Builtin agents runtime already started`);
+		installDurableStreamsFetchCache(this.options.durableStreamsFetchCache);
 		const pullWake = this.options.pullWake;
 		if (!pullWake?.runnerId) throw new Error(`Builtin agents require a pull-wake runner id`);
 		try {
@@ -1776,76 +1887,28 @@ var BuiltinAgentsServer = class {
 			});
 			this._mcpRegistry = mcpRegistry;
 			const mcpConfigPath = this.options.loadProjectMcpConfig ? path.resolve(this.options.workingDirectory ?? process.cwd(), `mcp.json`) : null;
-			const extras = this.options.extraMcpServers ?? [];
-			const wirePersistence = async (cfg) => {
-				const servers = [];
-				for (const s of cfg.servers) if (s.transport === `http` && s.auth?.mode === `authorizationCode`) {
-					const persist = await keychainPersistence({ server: s.name });
-					servers.push({
-						...s,
-						auth: {
-							...s.auth,
-							...persist
-						}
-					});
-				} else servers.push(s);
-				return {
-					...cfg,
-					servers
-				};
-			};
-			const merge = (jsonCfg) => {
-				const jsonServers = jsonCfg?.servers ?? [];
-				const jsonNames = new Set(jsonServers.map((s) => s.name));
-				const filteredExtras = extras.filter((s) => !jsonNames.has(s.name));
-				return {
-					servers: [...filteredExtras, ...jsonServers],
-					raw: jsonCfg?.raw
-				};
-			};
-			const onConfigError = this.options.onConfigError;
-			const runApply = async (jsonCfg) => {
-				if (this.mcpStopping) return;
-				try {
-					const wired = await wirePersistence(merge(jsonCfg));
-					if (this.mcpStopping) return;
-					await mcpRegistry.applyConfig(wired);
-				} catch (e) {
-					serverLog.error(`[mcp] applyConfig:`, e);
-					try {
-						onConfigError?.(e);
-					} catch (cbErr) {
-						serverLog.error(`[mcp] onConfigError callback failed:`, cbErr);
-					}
-				}
-			};
-			const applyMerged = (jsonCfg) => {
-				const p = runApply(jsonCfg);
-				this.mcpApplyInFlight.add(p);
-				p.finally(() => this.mcpApplyInFlight.delete(p));
-				return p;
-			};
+			this.mcpExtras = this.options.extraMcpServers ?? [];
 			if (mcpConfigPath) {
 				try {
 					const cfg = await loadConfig(mcpConfigPath, process.env);
-					applyMerged(cfg);
+					this.applyMerged(cfg);
 				} catch (err) {
 					if (err.code !== `ENOENT`) throw err;
-					if (extras.length === 0) serverLog.info(`[mcp] no ${mcpConfigPath} — starting with no servers`);
-					else serverLog.info(`[mcp] no ${mcpConfigPath} — starting with ${extras.length} server(s) from extras`);
-					applyMerged(null);
+					if (this.mcpExtras.length === 0) serverLog.info(`[mcp] no ${mcpConfigPath} — starting with no servers`);
+					else serverLog.info(`[mcp] no ${mcpConfigPath} — starting with ${this.mcpExtras.length} server(s) from extras`);
+					this.applyMerged(null);
 				}
 				try {
 					this.mcpWatcherCloser = await watchConfig(mcpConfigPath, {
-						onChange: (cfg) => void applyMerged(cfg),
+						onChange: (cfg) => void this.applyMerged(cfg),
 						onError: (e) => serverLog.error(`[mcp] config error:`, e)
 					});
 				} catch (e) {
 					serverLog.error(`[mcp] config watcher failed to start:`, e);
 				}
 			} else {
-				if (extras.length > 0) serverLog.info(`[mcp] starting with ${extras.length} server(s) from extras`);
-				applyMerged(null);
+				if (this.mcpExtras.length > 0) serverLog.info(`[mcp] starting with ${this.mcpExtras.length} server(s) from extras`);
+				this.applyMerged(null);
 			}
 			this.mcpToolProviderName = `mcp`;
 			registerToolProvider({

package/docs/entities/patterns/blackboard.md

@@ -81,7 +81,7 @@ const proWorker = await ctx.spawn(
     systemPrompt: PRO_WORKER_PROMPT,
     sharedDb: { id: `debate-${ctx.entityUrl}`, schema: debateSchema },
   },
-  { initialMessage: proInitialMessage, wake: `runFinished` }
+  { initialMessage: proInitialMessage, wake: { on: `runFinished`, includeResponse: true } }
 )
 ```
 

package/docs/entities/patterns/dispatcher.md

@@ -47,7 +47,7 @@ The dispatcher exposes a `dispatch` tool. When the LLM classifies an incoming me
 
 The tool then:
 
-1. Spawns the requested entity type with `wake: 'runFinished'`.
+1. Spawns the requested entity type with `wake: { on: 'runFinished', includeResponse: true }`.
 2. Returns immediately with a status message. The dispatcher is re-invoked when the specialist finishes.
 
 ## Dispatch tool
@@ -59,7 +59,7 @@ await ctx.spawn(
   type === `worker` ? { systemPrompt, tools: [`read`] } : { systemPrompt },
   {
     initialMessage: task,
-    wake: `runFinished`,
+    wake: { on: `runFinished`, includeResponse: true },
   }
 )
 
@@ -67,7 +67,7 @@ return {
   content: [
     {
       type: `text` as const,
-      text: `Dispatched to "${type}" specialist (${id}). You will be woken when it finishes.`,
+      text: `Dispatched to "${type}" specialist (${id}). The dispatcher will continue when it finishes.`,
     },
   ],
   details: { id, type },

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

@@ -42,9 +42,9 @@ The manager defines a handler-scoped tool called `analyze_with_perspectives`. Wh
 
 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.
+3. Uses `wake: { on: 'runFinished', includeResponse: true }` so the manager is re-invoked as each child completes.
+4. Collects results from `runFinished` wake payloads or shared state after workers finish.
+5. Runs a synthesis step after all child-completion wakes have been recorded.
 
 On subsequent calls, the tool reuses existing children via `ctx.observe()` and `child.send()` instead of spawning new ones.
 
@@ -63,7 +63,7 @@ for (const perspective of PERSPECTIVES) {
       `worker`,
       childId,
       { systemPrompt: perspective.systemPrompt, tools: [`read`] },
-      { initialMessage: question, wake: `runFinished` }
+      { initialMessage: question, wake: { on: `runFinished`, includeResponse: true } }
     )
     children.insert({
       key: perspective.id,
@@ -87,28 +87,16 @@ for (const perspective of PERSPECTIVES) {
 
 ## Collecting results
 
-The `readLatestCompletedText` helper awaits the child's current run, reads all text outputs, and returns the last one:
+Do not wait for worker output inside the same wake. Spawn workers with `wake: { on: "runFinished", includeResponse: true }`, record each worker URL in manager state, and return. On each later child-completion wake, store `wake.payload.finished_child.response` (or read structured output from shared state). Once all workers have reported, run the reduce/synthesis step.
 
 ```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 finished = wake.payload?.finished_child
+if (finished) {
+  ctx.state.workers.update(finished.url, (draft) => {
+    draft.status = finished.run_status
+    draft.output = finished.response ?? ""
+  })
 }
-
-const results = await Promise.all(
-  handles.map(async ({ id, handle }) => ({
-    id,
-    text: await readLatestCompletedText(
-      handle,
-      `(no completed output from ${id})`
-    ),
-  }))
-)
 ```
 
 ## State

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

@@ -55,7 +55,7 @@ for (let i = 0; i < chunks.length; i++) {
     { systemPrompt: task, tools: [`read`] },
     {
       initialMessage: chunks[i],
-      wake: `runFinished`,
+      wake: { on: `runFinished`, includeResponse: true },
     }
   )
   ctx.db.actions.children_insert({

package/docs/entities/patterns/pipeline.md

@@ -39,7 +39,7 @@ export function registerPipeline(registry: EntityRegistry) {
 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'`.
+2. The tool spawns a worker with the instruction as its system prompt and the input as `initialMessage`, using `wake: { on: 'runFinished', includeResponse: true }`.
 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.
@@ -74,7 +74,7 @@ function createRunStageTool(ctx: HandlerContext): AgentTool {
         `worker`,
         id,
         { systemPrompt: instruction, tools: [`read`] },
-        { initialMessage: input, wake: `runFinished` }
+        { initialMessage: input, wake: { on: `runFinished`, includeResponse: true } }
       )
       ctx.db.actions.children_insert({
         row: { key: id, url: child.entityUrl, stage: stageCount },
@@ -84,7 +84,7 @@ function createRunStageTool(ctx: HandlerContext): AgentTool {
         content: [
           {
             type: `text` as const,
-            text: `Stage ${stageCount} spawned. You will be woken when it finishes.`,
+            text: `Stage ${stageCount} spawned. The pipeline will continue when it finishes.`,
           },
         ],
         details: { stage: stageCount },

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.