@electric-ax/agents 0.1.5 → 0.2.2

package/dist/index.js

@@ -1,20 +1,20 @@
-import path, { dirname, relative, resolve } from "node:path";
+import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { createEntityRegistry, createRuntimeHandler, db } from "@electric-ax/agents-runtime";
-import fsSync from "node:fs";
+import { CODING_SESSION_CURSOR_COLLECTION_TYPE, CODING_SESSION_EVENT_COLLECTION_TYPE, CODING_SESSION_META_COLLECTION_TYPE, createEntityRegistry, createRuntimeHandler, db } from "@electric-ax/agents-runtime";
+import fsSync, { promises, watch } from "node:fs";
 import pino from "pino";
+import { spawn } from "node:child_process";
+import { homedir } from "node:os";
+import { z } from "zod";
+import { deserializeCursor, discoverSessions, importLocalSession, loadSession, resolveSession, serializeCursor, tailSession } from "agent-session-protocol";
 import Anthropic from "@anthropic-ai/sdk";
 import { createHash } from "node:crypto";
-import fs, { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import fs from "node:fs/promises";
 import Database from "better-sqlite3";
 import { Type } from "@sinclair/typebox";
 import { load } from "sqlite-vec";
-import { exec } from "node:child_process";
-import { createRequire } from "node:module";
-import { Readability } from "@mozilla/readability";
-import { JSDOM, VirtualConsole } from "jsdom";
-import TurndownService from "turndown";
 import { nanoid } from "nanoid";
+import { braveSearchTool, braveSearchTool as braveSearchTool$1, createBashTool, createEditTool, createReadFileTool, createWriteTool, fetchUrlTool } from "@electric-ax/agents-runtime/tools";
 import { createServer } from "node:http";
 
 //#region src/log.ts
@@ -66,6 +66,516 @@ const serverLog = {
 	}
 };
 
+//#endregion
+//#region src/agents/coding-session.ts
+const defaultCliRunner = { async run(opts) {
+	return new Promise((resolve, reject) => {
+		const isClaude = opts.agent === `claude`;
+		const bin = isClaude ? `claude` : `codex`;
+		const args = isClaude ? opts.sessionId ? [
+			`-r`,
+			opts.sessionId,
+			`--dangerously-skip-permissions`,
+			`-p`
+		] : [`--dangerously-skip-permissions`, `-p`] : opts.sessionId ? [
+			`exec`,
+			`--skip-git-repo-check`,
+			`resume`,
+			opts.sessionId,
+			opts.prompt
+		] : [
+			`exec`,
+			`--skip-git-repo-check`,
+			opts.prompt
+		];
+		const child = spawn(bin, args, {
+			cwd: opts.cwd,
+			stdio: [
+				isClaude ? `pipe` : `ignore`,
+				`pipe`,
+				`pipe`
+			]
+		});
+		const MAX_BUF_CHARS = 4096;
+		let stdout = ``;
+		let stderr = ``;
+		child.stdout?.on(`data`, (d) => {
+			if (stdout.length < MAX_BUF_CHARS) stdout += d.toString().slice(0, MAX_BUF_CHARS - stdout.length);
+		});
+		child.stderr?.on(`data`, (d) => {
+			if (stderr.length < MAX_BUF_CHARS) stderr += d.toString().slice(0, MAX_BUF_CHARS - stderr.length);
+		});
+		child.on(`error`, reject);
+		child.on(`exit`, (code) => {
+			resolve({
+				exitCode: code ?? -1,
+				stdout,
+				stderr
+			});
+		});
+		if (isClaude && child.stdin) {
+			child.stdin.write(opts.prompt);
+			child.stdin.end();
+		}
+	});
+} };
+async function discoverNewestSession(agent, cwd, excludeIds) {
+	const all = await discoverSessions(agent);
+	const candidates = all.filter((s) => !excludeIds.has(s.sessionId) && (!s.cwd || s.cwd === cwd));
+	if (candidates.length === 0) return null;
+	return candidates[0].sessionId;
+}
+/**
+* Compute the candidate directories where Claude Code stores per-cwd
+* session JSONL files. Claude resolves the cwd to its realpath when
+* choosing the directory name (so /tmp/foo on macOS lands under
+* `-private-tmp-foo`), but the entity may have been spawned with the
+* non-realpath form. Return both candidates so the caller can union
+* their contents.
+*/
+async function getClaudeProjectDirs(cwd) {
+	const home = homedir();
+	const make = (c) => path.join(home, `.claude`, `projects`, c.replace(/\//g, `-`));
+	const dirs = [make(cwd)];
+	try {
+		const real = await promises.realpath(cwd);
+		if (real !== cwd) dirs.push(make(real));
+	} catch {}
+	return dirs;
+}
+async function listClaudeJsonlIdsByCwd(cwd) {
+	const ids = new Set();
+	for (const dir of await getClaudeProjectDirs(cwd)) try {
+		const files = await promises.readdir(dir);
+		for (const f of files) if (f.endsWith(`.jsonl`)) ids.add(f.slice(0, -`.jsonl`.length));
+	} catch {}
+	return ids;
+}
+/**
+* Deterministic-path discovery for a freshly created session. After the
+* Claude CLI runs in `-p` mode it writes the new JSONL straight into
+* `~/.claude/projects/<sanitize(cwd)>/<id>.jsonl` *without* leaving a
+* `~/.claude/sessions/<pid>.json` lock file (those are interactive-only),
+* so `discoverSessions` can miss it. Compute the expected dir directly
+* and diff its contents against a pre-run snapshot. Returns the newest
+* fresh sessionId or null. Codex falls back to discoverNewestSession.
+*/
+async function findNewSessionAfterRun(agent, cwd, preDirectIds, preDiscoveredIds) {
+	if (agent === `claude`) {
+		const dirs = await getClaudeProjectDirs(cwd);
+		let best = null;
+		for (const dir of dirs) try {
+			const files = await promises.readdir(dir);
+			for (const f of files) {
+				if (!f.endsWith(`.jsonl`)) continue;
+				const id = f.slice(0, -`.jsonl`.length);
+				if (preDirectIds.has(id)) continue;
+				const st = await promises.stat(path.join(dir, f)).catch(() => null);
+				if (!st) continue;
+				if (!best || st.mtimeMs > best.mtime) best = {
+					id,
+					mtime: st.mtimeMs
+				};
+			}
+		} catch {}
+		if (best) return best.id;
+	}
+	return discoverNewestSession(agent, cwd, preDiscoveredIds);
+}
+const sessionMetaRowSchema = z.object({
+	key: z.literal(`current`),
+	electricSessionId: z.string(),
+	nativeSessionId: z.string().optional(),
+	agent: z.enum([`claude`, `codex`]),
+	cwd: z.string(),
+	status: z.enum([
+		`initializing`,
+		`idle`,
+		`running`,
+		`error`
+	]),
+	error: z.string().optional(),
+	currentPromptInboxKey: z.string().optional()
+});
+const cursorStateRowSchema = z.object({
+	key: z.literal(`current`),
+	cursor: z.string(),
+	lastProcessedInboxKey: z.string().optional()
+});
+const eventRowSchema = z.object({
+	key: z.string(),
+	ts: z.number(),
+	type: z.string(),
+	callId: z.string().optional(),
+	payload: z.looseObject({})
+});
+const creationArgsSchema = z.object({
+	agent: z.enum([`claude`, `codex`]),
+	cwd: z.string().optional(),
+	nativeSessionId: z.string().optional(),
+	importFrom: z.object({
+		agent: z.enum([`claude`, `codex`]),
+		sessionId: z.string()
+	}).optional()
+});
+const promptMessageSchema = z.object({ text: z.string() });
+/**
+* Stable key for an events-collection row, derived from the event's content.
+* Lets us re-insert the same event without producing duplicates — the caller
+* (or the collection's uniqueness guard) uses this to de-dup across retries,
+* replays, and crash recovery. Sorts chronologically by ts, then by type.
+*/
+function eventKey(event) {
+	const tsPart = String(event.ts).padStart(16, `0`);
+	return `${tsPart}_${event.type}_${contentHashHex(event)}`;
+}
+function contentHashHex(event) {
+	const json = JSON.stringify(event);
+	let h = 5381;
+	for (let i = 0; i < json.length; i++) h = (h * 33 ^ json.charCodeAt(i)) >>> 0;
+	return h.toString(16).padStart(8, `0`);
+}
+function buildEventRow(event) {
+	const callId = `callId` in event && typeof event.callId === `string` ? event.callId : void 0;
+	return {
+		key: eventKey(event),
+		ts: event.ts,
+		type: event.type,
+		...callId !== void 0 ? { callId } : {},
+		payload: event
+	};
+}
+function appendIfNew(ctx, event) {
+	const row = buildEventRow(event);
+	if (ctx.events.get(row.key) !== void 0) return;
+	ctx.actions.events_insert({ row });
+}
+/**
+* Mirror every event that lands in the JSONL file while `runWork` is
+* executing (i.e. while the CLI is running). Returns the advanced cursor
+* and the `runWork` result once everything has settled and every append
+* has been persisted to the entity's durable stream.
+*
+* If setup fails (e.g. the session file can't be resolved), `runWork`
+* still runs — but nothing is mirrored and `setupError` is populated so
+* the caller can surface the condition. If `runWork` throws, the error
+* propagates after the watcher has been cleaned up.
+*/
+async function runWithLiveMirror(opts) {
+	let cursor = null;
+	let setupError = void 0;
+	try {
+		const session = await resolveSession(opts.nativeSessionId, opts.agent);
+		if (opts.serializedCursor) cursor = deserializeCursor({
+			...opts.serializedCursor,
+			path: session.path
+		});
+		else {
+			const initial = await loadSession({
+				sessionId: opts.nativeSessionId,
+				agent: opts.agent
+			});
+			for (const ev of initial.events) appendIfNew(opts.ctx, ev);
+			cursor = initial.cursor;
+		}
+	} catch (e) {
+		setupError = e;
+	}
+	if (!cursor) {
+		const result$1 = await opts.runWork();
+		return {
+			cursor: opts.serializedCursor,
+			setupError,
+			result: result$1
+		};
+	}
+	let activeCursor = cursor;
+	let busy = false;
+	let pending = false;
+	let stopped = false;
+	const drainOnce = async () => {
+		if (stopped && busy) return;
+		if (busy) {
+			pending = true;
+			return;
+		}
+		busy = true;
+		try {
+			const res = await tailSession({ cursor: activeCursor });
+			activeCursor = res.cursor;
+			for (const ev of res.newEvents) appendIfNew(opts.ctx, ev);
+		} catch {} finally {
+			busy = false;
+			if (pending && !stopped) {
+				pending = false;
+				drainOnce();
+			}
+		}
+	};
+	const fileWatcher = watch(activeCursor.path, () => {
+		drainOnce();
+	});
+	const pollHandle = setInterval(() => {
+		drainOnce();
+	}, 1500);
+	let result;
+	try {
+		result = await opts.runWork();
+	} finally {
+		stopped = true;
+		clearInterval(pollHandle);
+		fileWatcher.close();
+		while (busy) await new Promise((r) => setTimeout(r, 10));
+		try {
+			const final = await tailSession({ cursor: activeCursor });
+			activeCursor = final.cursor;
+			for (const ev of final.newEvents) appendIfNew(opts.ctx, ev);
+		} catch {}
+	}
+	return {
+		cursor: serializeCursor(activeCursor),
+		setupError,
+		result
+	};
+}
+function registerCodingSession(registry, options = {}) {
+	const runner = options.cliRunner ?? defaultCliRunner;
+	const defaultCwd = options.defaultWorkingDirectory ?? process.cwd();
+	registry.define(`coder`, {
+		description: `Runs a Claude Code / Codex CLI session and mirrors its normalized event stream into a durable store. Prompts arrive via message_received (type: "prompt") and are executed serially.`,
+		creationSchema: creationArgsSchema,
+		inboxSchemas: { prompt: promptMessageSchema },
+		state: {
+			sessionMeta: {
+				schema: sessionMetaRowSchema,
+				type: CODING_SESSION_META_COLLECTION_TYPE,
+				primaryKey: `key`
+			},
+			cursorState: {
+				schema: cursorStateRowSchema,
+				type: CODING_SESSION_CURSOR_COLLECTION_TYPE,
+				primaryKey: `key`
+			},
+			events: {
+				schema: eventRowSchema,
+				type: CODING_SESSION_EVENT_COLLECTION_TYPE,
+				primaryKey: `key`
+			}
+		},
+		async handler(ctx, _wake) {
+			const existingMeta = ctx.db.collections.sessionMeta.get(`current`);
+			if (!existingMeta) {
+				const args = creationArgsSchema.parse(ctx.args);
+				const cwd = args.cwd ?? defaultCwd;
+				const electricSessionId = ctx.entityUrl.split(`/`).pop() ?? ctx.entityUrl;
+				let resolvedNativeId = args.nativeSessionId;
+				if (args.importFrom) {
+					const result = await importLocalSession({
+						source: {
+							sessionId: args.importFrom.sessionId,
+							agent: args.importFrom.agent
+						},
+						target: {
+							agent: args.agent,
+							cwd
+						}
+					});
+					resolvedNativeId = result.sessionId;
+				}
+				const hasNative = resolvedNativeId !== void 0;
+				ctx.db.actions.sessionMeta_insert({ row: {
+					key: `current`,
+					electricSessionId,
+					...hasNative ? { nativeSessionId: resolvedNativeId } : {},
+					agent: args.agent,
+					cwd,
+					status: hasNative ? `idle` : `initializing`
+				} });
+			}
+			if (!ctx.db.collections.cursorState.get(`current`)) ctx.db.actions.cursorState_insert({ row: {
+				key: `current`,
+				cursor: ``
+			} });
+			const metaRow = ctx.db.collections.sessionMeta.get(`current`);
+			const cursorRow = ctx.db.collections.cursorState.get(`current`);
+			if (!metaRow || !cursorRow) throw new Error(`[coding-session] expected sessionMeta and cursorState rows to exist after init`);
+			if (metaRow.nativeSessionId && !cursorRow.cursor) {
+				const mirrorCtx = {
+					events: { get: (k) => ctx.db.collections.events.get(k) },
+					actions: { events_insert: ctx.db.actions.events_insert }
+				};
+				try {
+					const initial = await loadSession({
+						sessionId: metaRow.nativeSessionId,
+						agent: metaRow.agent
+					});
+					for (const ev of initial.events) appendIfNew(mirrorCtx, ev);
+					const serialized = serializeCursor(initial.cursor);
+					ctx.db.actions.cursorState_update({
+						key: `current`,
+						updater: (d) => {
+							d.cursor = JSON.stringify(serialized);
+						}
+					});
+				} catch (e) {
+					const message = e instanceof Error ? e.message : String(e);
+					ctx.db.actions.sessionMeta_update({
+						key: `current`,
+						updater: (d) => {
+							d.error = `initial mirror failed: ${message}`;
+						}
+					});
+				}
+			}
+			const inboxRows = ctx.db.collections.inbox.toArray.slice().sort((a, b) => a.key < b.key ? -1 : a.key > b.key ? 1 : 0);
+			const lastKey = cursorRow.lastProcessedInboxKey ?? ``;
+			const pending = inboxRows.filter((m) => m.key > lastKey);
+			if (pending.length === 0) {
+				if (metaRow.status === `running` || metaRow.status === `error`) ctx.db.actions.sessionMeta_update({
+					key: `current`,
+					updater: (d) => {
+						d.status = `idle`;
+						delete d.currentPromptInboxKey;
+						delete d.error;
+					}
+				});
+				return;
+			}
+			let runningMeta = metaRow;
+			let runningCursor = cursorRow;
+			for (const inboxMsg of pending) {
+				const parsed = promptMessageSchema.safeParse(inboxMsg.payload);
+				if (!parsed.success) {
+					ctx.db.actions.cursorState_update({
+						key: `current`,
+						updater: (d) => {
+							d.lastProcessedInboxKey = inboxMsg.key;
+						}
+					});
+					runningCursor = {
+						...runningCursor,
+						lastProcessedInboxKey: inboxMsg.key
+					};
+					continue;
+				}
+				const prompt = parsed.data.text;
+				const existingTitle = ctx.tags.title;
+				if (typeof existingTitle !== `string` || existingTitle.length === 0) ctx.setTag(`title`, prompt.slice(0, 80));
+				ctx.db.actions.sessionMeta_update({
+					key: `current`,
+					updater: (d) => {
+						d.status = `running`;
+						d.currentPromptInboxKey = inboxMsg.key;
+						delete d.error;
+					}
+				});
+				const recordedRun = ctx.recordRun();
+				const eventKeysBefore = new Set(ctx.db.collections.events.toArray.map((e) => e.key));
+				try {
+					const mirrorCtx = {
+						events: { get: (k) => ctx.db.collections.events.get(k) },
+						actions: { events_insert: ctx.db.actions.events_insert }
+					};
+					let nextCursorJson = runningCursor.cursor;
+					if (!runningMeta.nativeSessionId) {
+						const preDirectIds = runningMeta.agent === `claude` ? await listClaudeJsonlIdsByCwd(runningMeta.cwd) : new Set();
+						const preDiscoveredIds = new Set((await discoverSessions(runningMeta.agent)).map((s) => s.sessionId));
+						const cliResult = await runner.run({
+							agent: runningMeta.agent,
+							cwd: runningMeta.cwd,
+							prompt
+						});
+						if (cliResult.exitCode !== 0) throw new Error(`[coding-session] ${runningMeta.agent} CLI exited ${cliResult.exitCode}. stderr=${cliResult.stderr.slice(0, 800) || `<empty>`} stdout=${cliResult.stdout.slice(0, 800) || `<empty>`}`);
+						const foundId = await findNewSessionAfterRun(runningMeta.agent, runningMeta.cwd, preDirectIds, preDiscoveredIds);
+						if (!foundId) throw new Error(`[coding-session] ${runningMeta.agent} CLI succeeded but no new session file was found`);
+						ctx.db.actions.sessionMeta_update({
+							key: `current`,
+							updater: (d) => {
+								d.nativeSessionId = foundId;
+							}
+						});
+						runningMeta = {
+							...runningMeta,
+							nativeSessionId: foundId
+						};
+						const initial = await loadSession({
+							sessionId: foundId,
+							agent: runningMeta.agent
+						});
+						for (const ev of initial.events) appendIfNew(mirrorCtx, ev);
+						nextCursorJson = JSON.stringify(serializeCursor(initial.cursor));
+					} else {
+						const serializedCursor = runningCursor.cursor ? JSON.parse(runningCursor.cursor) : null;
+						const { cursor: nextSerialized, setupError, result: cliResult } = await runWithLiveMirror({
+							agent: runningMeta.agent,
+							nativeSessionId: runningMeta.nativeSessionId,
+							serializedCursor,
+							ctx: mirrorCtx,
+							runWork: () => runner.run({
+								agent: runningMeta.agent,
+								sessionId: runningMeta.nativeSessionId,
+								cwd: runningMeta.cwd,
+								prompt
+							})
+						});
+						if (setupError) throw setupError instanceof Error ? setupError : new Error(String(setupError));
+						if (cliResult.exitCode !== 0) throw new Error(`[coding-session] ${runningMeta.agent} CLI exited ${cliResult.exitCode}. stderr=${cliResult.stderr.slice(0, 800) || `<empty>`} stdout=${cliResult.stdout.slice(0, 800) || `<empty>`}`);
+						const persistedCursor = nextSerialized ?? serializedCursor;
+						nextCursorJson = persistedCursor ? JSON.stringify(persistedCursor) : ``;
+					}
+					ctx.db.actions.cursorState_update({
+						key: `current`,
+						updater: (d) => {
+							d.cursor = nextCursorJson;
+							d.lastProcessedInboxKey = inboxMsg.key;
+						}
+					});
+					runningCursor = {
+						...runningCursor,
+						cursor: nextCursorJson,
+						lastProcessedInboxKey: inboxMsg.key
+					};
+					for (const row of ctx.db.collections.events.toArray) {
+						if (eventKeysBefore.has(row.key)) continue;
+						if (row.type !== `assistant_message`) continue;
+						const text = row.payload?.text;
+						if (typeof text === `string` && text.length > 0) recordedRun.attachResponse(text);
+					}
+					recordedRun.end({ status: `completed` });
+				} catch (e) {
+					const message = e instanceof Error ? e.message : String(e);
+					recordedRun.end({
+						status: `failed`,
+						finishReason: `error`
+					});
+					ctx.db.actions.sessionMeta_update({
+						key: `current`,
+						updater: (d) => {
+							d.status = `error`;
+							d.error = message;
+						}
+					});
+					ctx.db.actions.cursorState_update({
+						key: `current`,
+						updater: (d) => {
+							d.lastProcessedInboxKey = inboxMsg.key;
+						}
+					});
+					throw e;
+				}
+			}
+			ctx.db.actions.sessionMeta_update({
+				key: `current`,
+				updater: (d) => {
+					d.status = `idle`;
+					delete d.currentPromptInboxKey;
+					delete d.error;
+				}
+			});
+		}
+	});
+}
+
 //#endregion
 //#region src/docs/embed.ts
 const EMBEDDING_DIMENSIONS = 128;
@@ -285,6 +795,8 @@ function resolveDocsRoot(workingDirectory) {
 		process.env.HORTON_DOCS_ROOT,
 		path.resolve(workingDirectory, `electric-agents-docs/docs`),
 		path.resolve(process.cwd(), `electric-agents-docs/docs`),
+		path.resolve(MODULE_DIR, `../docs`),
+		path.resolve(MODULE_DIR, `../../docs`),
 		path.resolve(MODULE_DIR, `../../../../../electric-agents-docs/docs`)
 	].filter((value) => typeof value === `string`);
 	for (const candidate of candidates) if (fsSync.existsSync(candidate)) return candidate;
@@ -838,319 +1350,6 @@ function listRefFiles(dir, prefix = ``) {
 	}
 }
 
-//#endregion
-//#region src/tools/bash.ts
-const TIMEOUT_MS = 3e4;
-const MAX_OUTPUT_CHARS = 5e4;
-function createBashTool(workingDirectory) {
-	return {
-		name: `bash`,
-		label: `Bash`,
-		description: `Execute a shell command and return its output. Commands run in a sandboxed working directory with a 30-second timeout.`,
-		parameters: Type.Object({ command: Type.String({ description: `The shell command to execute` }) }),
-		execute: async (_toolCallId, params) => {
-			const { command } = params;
-			return new Promise((resolve$1) => {
-				const child = exec(command, {
-					cwd: workingDirectory,
-					timeout: TIMEOUT_MS,
-					maxBuffer: 1024 * 1024,
-					env: {
-						...process.env,
-						HOME: workingDirectory
-					}
-				});
-				let stdout = ``;
-				let stderr = ``;
-				child.stdout?.on(`data`, (data) => {
-					stdout += data;
-				});
-				child.stderr?.on(`data`, (data) => {
-					stderr += data;
-				});
-				child.on(`close`, (code, signal) => {
-					const timedOut = signal === `SIGTERM`;
-					let output = stdout;
-					if (stderr) output += output ? `\n\nSTDERR:\n${stderr}` : stderr;
-					if (timedOut) output += `\n\n[Command timed out after ${TIMEOUT_MS / 1e3}s]`;
-					output = output.slice(0, MAX_OUTPUT_CHARS);
-					resolve$1({
-						content: [{
-							type: `text`,
-							text: output || `(no output)`
-						}],
-						details: {
-							exitCode: code ?? 1,
-							timedOut
-						}
-					});
-				});
-				child.on(`error`, (err) => {
-					resolve$1({
-						content: [{
-							type: `text`,
-							text: `Command failed: ${err.message}`
-						}],
-						details: {
-							exitCode: 1,
-							timedOut: false
-						}
-					});
-				});
-			});
-		}
-	};
-}
-
-//#endregion
-//#region src/tools/edit.ts
-const READ_GUARD_MESSAGE = (rel) => `File ${rel} has not been read in this session (sessions are per-wake — re-read after waking from a worker).`;
-function createEditTool(workingDirectory, readSet) {
-	return {
-		name: `edit`,
-		label: `Edit File`,
-		description: `Replace text in a file. The file must have been read with the read tool earlier in this session. By default the old_string must occur exactly once; set replace_all to true to replace every occurrence.`,
-		parameters: Type.Object({
-			path: Type.String({ description: `File path (relative to working directory)` }),
-			old_string: Type.String({ description: `The literal text to find. Must be unique unless replace_all is true.` }),
-			new_string: Type.String({ description: `The replacement text.` }),
-			replace_all: Type.Optional(Type.Boolean({ description: `Replace every occurrence (default false).` }))
-		}),
-		execute: async (_toolCallId, params) => {
-			const { path: filePath, old_string, new_string, replace_all } = params;
-			try {
-				const resolved = resolve(workingDirectory, filePath);
-				const rel = relative(workingDirectory, resolved);
-				if (rel.startsWith(`..`)) return {
-					content: [{
-						type: `text`,
-						text: `Error: Path "${filePath}" is outside the working directory`
-					}],
-					details: { replacements: 0 }
-				};
-				if (!readSet.has(resolved)) return {
-					content: [{
-						type: `text`,
-						text: READ_GUARD_MESSAGE(rel)
-					}],
-					details: { replacements: 0 }
-				};
-				const original = await readFile(resolved, `utf-8`);
-				if (!replace_all) {
-					const first = original.indexOf(old_string);
-					if (first === -1) return {
-						content: [{
-							type: `text`,
-							text: `Error: old_string not found in ${rel}`
-						}],
-						details: { replacements: 0 }
-					};
-					const second = original.indexOf(old_string, first + 1);
-					if (second !== -1) {
-						const matches = original.split(old_string).length - 1;
-						return {
-							content: [{
-								type: `text`,
-								text: `Error: found ${matches} matches for old_string in ${rel}; pass replace_all=true to replace all, or provide a more specific old_string.`
-							}],
-							details: { replacements: 0 }
-						};
-					}
-					const updated = original.slice(0, first) + new_string + original.slice(first + old_string.length);
-					await writeFile(resolved, updated, `utf-8`);
-					return {
-						content: [{
-							type: `text`,
-							text: `Edited ${rel}: 1 replacement`
-						}],
-						details: { replacements: 1 }
-					};
-				}
-				const parts = original.split(old_string);
-				const count = parts.length - 1;
-				if (count === 0) return {
-					content: [{
-						type: `text`,
-						text: `Error: old_string not found in ${rel}`
-					}],
-					details: { replacements: 0 }
-				};
-				await writeFile(resolved, parts.join(new_string), `utf-8`);
-				return {
-					content: [{
-						type: `text`,
-						text: `Edited ${rel}: ${count} occurrences replaced`
-					}],
-					details: { replacements: count }
-				};
-			} catch (err) {
-				serverLog.warn(`[edit tool] failed to edit ${filePath}: ${err instanceof Error ? err.message : String(err)}`, err instanceof Error ? err : void 0);
-				return {
-					content: [{
-						type: `text`,
-						text: `Error editing file: ${err instanceof Error ? err.message : `Unknown error`}`
-					}],
-					details: { replacements: 0 }
-				};
-			}
-		}
-	};
-}
-
-//#endregion
-//#region src/tools/fetch-url.ts
-const MAX_RAW_CHARS = 1e5;
-const require = createRequire(import.meta.url);
-const { gfm } = require(`turndown-plugin-gfm`);
-function htmlToMarkdown(html, url) {
-	const virtualConsole = new VirtualConsole();
-	const dom = new JSDOM(html, {
-		url,
-		virtualConsole
-	});
-	const reader = new Readability(dom.window.document);
-	const article = reader.parse();
-	const turndown = new TurndownService({ headingStyle: `atx` });
-	turndown.use(gfm);
-	return turndown.turndown(article?.content ?? html);
-}
-let anthropic$1 = null;
-function getClient$1() {
-	if (!anthropic$1) anthropic$1 = new Anthropic();
-	return anthropic$1;
-}
-async function extractWithLLM(text, prompt) {
-	const client = getClient$1();
-	const res = await client.messages.create({
-		model: `claude-haiku-4-5-20251001`,
-		max_tokens: 2048,
-		messages: [{
-			role: `user`,
-			content: `${prompt}\n\n<page_content>\n${text.slice(0, MAX_RAW_CHARS)}\n</page_content>`
-		}]
-	});
-	const block = res.content[0];
-	return block?.type === `text` ? block.text : ``;
-}
-const fetchUrlTool = {
-	name: `fetch_url`,
-	label: `Fetch URL`,
-	description: `Fetch a web page and extract its key content using AI. Provide a prompt describing what information you want from the page. Returns a focused extraction rather than raw HTML.`,
-	parameters: Type.Object({
-		url: Type.String({ description: `The URL to fetch` }),
-		prompt: Type.String({ description: `What to extract from the page, e.g. 'Extract the main article content' or 'Find the pricing information'` })
-	}),
-	execute: async (_toolCallId, params) => {
-		const { url, prompt } = params;
-		try {
-			const res = await fetch(url, {
-				headers: {
-					"User-Agent": `Mozilla/5.0 (compatible; DurableStreamsAgent/1.0)`,
-					Accept: `text/html,application/xhtml+xml,text/plain,*/*`
-				},
-				redirect: `follow`,
-				signal: AbortSignal.timeout(1e4)
-			});
-			if (!res.ok) return {
-				content: [{
-					type: `text`,
-					text: `Failed to fetch: ${res.status} ${res.statusText}`
-				}],
-				details: {
-					charCount: 0,
-					usedLLM: false
-				}
-			};
-			const contentType = res.headers.get(`content-type`) ?? ``;
-			const raw = await res.text();
-			const markdown = contentType.includes(`text/html`) ? htmlToMarkdown(raw, url) : raw;
-			const extracted = await extractWithLLM(markdown, prompt);
-			return {
-				content: [{
-					type: `text`,
-					text: extracted
-				}],
-				details: {
-					charCount: extracted.length,
-					usedLLM: true
-				}
-			};
-		} catch (err) {
-			return {
-				content: [{
-					type: `text`,
-					text: `Error fetching URL: ${err instanceof Error ? err.message : `Unknown error`}`
-				}],
-				details: {
-					charCount: 0,
-					usedLLM: false
-				}
-			};
-		}
-	}
-};
-
-//#endregion
-//#region src/tools/read-file.ts
-const MAX_FILE_SIZE = 512 * 1024;
-function createReadFileTool(workingDirectory, readSet) {
-	return {
-		name: `read`,
-		label: `Read File`,
-		description: `Read the contents of a file. Path must be relative to or within the working directory. Binary files and files over 512KB are rejected.`,
-		parameters: Type.Object({ path: Type.String({ description: `File path (relative to working directory)` }) }),
-		execute: async (_toolCallId, params) => {
-			const { path: filePath } = params;
-			try {
-				const resolved = resolve(workingDirectory, filePath);
-				const rel = relative(workingDirectory, resolved);
-				if (rel.startsWith(`..`)) return {
-					content: [{
-						type: `text`,
-						text: `Error: Path "${filePath}" is outside the working directory`
-					}],
-					details: { charCount: 0 }
-				};
-				const fileStat = await stat(resolved);
-				if (fileStat.size > MAX_FILE_SIZE) return {
-					content: [{
-						type: `text`,
-						text: `Error: File is too large (${(fileStat.size / 1024).toFixed(0)}KB > ${MAX_FILE_SIZE / 1024}KB limit)`
-					}],
-					details: { charCount: 0 }
-				};
-				const buffer = await readFile(resolved);
-				const sample = buffer.subarray(0, 8192);
-				if (sample.includes(0)) return {
-					content: [{
-						type: `text`,
-						text: `Error: "${filePath}" appears to be a binary file`
-					}],
-					details: { charCount: 0 }
-				};
-				const text = buffer.toString(`utf-8`);
-				readSet?.add(resolved);
-				return {
-					content: [{
-						type: `text`,
-						text
-					}],
-					details: { charCount: text.length }
-				};
-			} catch (err) {
-				serverLog.warn(`[read tool] failed to read ${filePath}: ${err instanceof Error ? err.message : String(err)}`, err instanceof Error ? err : void 0);
-				return {
-					content: [{
-						type: `text`,
-						text: `Error reading file: ${err instanceof Error ? err.message : `Unknown error`}`
-					}],
-					details: { charCount: 0 }
-				};
-			}
-		}
-	};
-}
-
 //#endregion
 //#region src/tools/spawn-worker.ts
 const WORKER_TOOL_NAMES = [
@@ -1226,114 +1425,117 @@ function createSpawnWorkerTool(ctx) {
 }
 
 //#endregion
-//#region src/tools/write.ts
-function createWriteTool(workingDirectory, readSet) {
+//#region src/tools/spawn-coder.ts
+const CODER_AGENT_NAMES = [`claude`, `codex`];
+function createSpawnCoderTool(ctx) {
 	return {
-		name: `write`,
-		label: `Write File`,
-		description: `Create or overwrite a file. Path must be within the working directory. Parent directories are created as needed.`,
+		name: `spawn_coder`,
+		label: `Spawn Coder`,
+		description: `Spawn a coding-session subagent (a coder) that drives a Claude Code or Codex CLI session in a working directory. Use when the user asks for code changes, file edits, debugging, or any task that benefits from a real coding agent with tool access. The coder is long-lived — its URL stays valid across many turns, so you can keep prompting it via prompt_coder without re-spawning. End your turn after spawning; you'll be woken when the coder finishes its first reply.`,
 		parameters: Type.Object({
-			path: Type.String({ description: `File path (relative to working directory)` }),
-			content: Type.String({ description: `Full file contents to write` })
+			prompt: Type.String({ description: `First user message sent to the coder. This is what kicks off the run — without it the coder will idle. Be concrete: describe the task, mention the files/paths involved, and what form of answer you want back.` }),
+			agent: Type.Optional(Type.Union(CODER_AGENT_NAMES.map((n) => Type.Literal(n)), { description: `Which coding agent to use. Defaults to "claude". Use "codex" only if the user explicitly asks for it.` })),
+			cwd: Type.Optional(Type.String({ description: `Working directory the coder runs in. Defaults to the runtime's cwd (the same directory Horton is running in). Set this when the user wants the coder to operate on a different repo.` }))
 		}),
 		execute: async (_toolCallId, params) => {
-			const { path: filePath, content } = params;
+			const { prompt, agent, cwd } = params;
+			if (typeof prompt !== `string` || prompt.length === 0) return {
+				content: [{
+					type: `text`,
+					text: `Error: prompt is required and must be a non-empty string.`
+				}],
+				details: { spawned: false }
+			};
+			const id = nanoid(10);
+			const spawnArgs = { agent: agent ?? `claude` };
+			if (cwd) spawnArgs.cwd = cwd;
 			try {
-				const resolved = resolve(workingDirectory, filePath);
-				const rel = relative(workingDirectory, resolved);
-				if (rel.startsWith(`..`)) return {
-					content: [{
-						type: `text`,
-						text: `Error: Path "${filePath}" is outside the working directory`
-					}],
-					details: { bytesWritten: 0 }
-				};
-				await mkdir(dirname(resolved), { recursive: true });
-				await writeFile(resolved, content, `utf-8`);
-				readSet?.add(resolved);
-				const bytesWritten = Buffer.byteLength(content, `utf-8`);
+				const handle = await ctx.spawn(`coder`, id, spawnArgs, {
+					initialMessage: { text: prompt },
+					wake: {
+						on: `runFinished`,
+						includeResponse: true
+					}
+				});
+				const coderUrl = handle.entityUrl;
 				return {
 					content: [{
 						type: `text`,
-						text: `Wrote ${bytesWritten} bytes to ${rel}`
+						text: `Coder dispatched at ${coderUrl}. End your turn — when the coder finishes its current reply you'll be woken with the response. To send follow-up prompts to the same coder, call prompt_coder with this URL.`
 					}],
-					details: { bytesWritten }
+					details: {
+						spawned: true,
+						coderUrl
+					}
 				};
 			} catch (err) {
-				serverLog.warn(`[write tool] failed to write ${filePath}: ${err instanceof Error ? err.message : String(err)}`, err instanceof Error ? err : void 0);
+				serverLog.warn(`[spawn_coder tool] failed to spawn coder ${id}: ${err instanceof Error ? err.message : String(err)}`, err instanceof Error ? err : void 0);
 				return {
 					content: [{
 						type: `text`,
-						text: `Error writing file: ${err instanceof Error ? err.message : `Unknown error`}`
+						text: `Error spawning coder: ${err instanceof Error ? err.message : `Unknown error`}`
 					}],
-					details: { bytesWritten: 0 }
+					details: { spawned: false }
 				};
 			}
 		}
 	};
 }
-
-//#endregion
-//#region src/tools/brave-search.ts
-const BRAVE_API_URL = `https://api.search.brave.com/res/v1/web/search`;
-const braveSearchTool = {
-	name: `web_search`,
-	label: `Web Search`,
-	description: `Search the web for current information using Brave Search. Returns titles, URLs, and snippets from top results.`,
-	parameters: Type.Object({ query: Type.String({ description: `The search query` }) }),
-	execute: async (_toolCallId, params) => {
-		const apiKey = process.env.BRAVE_SEARCH_API_KEY;
-		if (!apiKey) return {
-			content: [{
-				type: `text`,
-				text: `Search failed: BRAVE_SEARCH_API_KEY not set`
-			}],
-			details: { resultCount: 0 }
-		};
-		const { query } = params;
-		try {
-			const url = `${BRAVE_API_URL}?q=${encodeURIComponent(query)}&count=5`;
-			const res = await fetch(url, { headers: { "X-Subscription-Token": apiKey } });
-			if (!res.ok) return {
-				content: [{
-					type: `text`,
-					text: `Search failed: ${res.status} ${res.statusText}`
-				}],
-				details: { resultCount: 0 }
-			};
-			const data = await res.json();
-			const results = data.web?.results ?? [];
-			if (results.length === 0) return {
-				content: [{
-					type: `text`,
-					text: `No results found for "${query}"`
-				}],
-				details: { resultCount: 0 }
-			};
-			const formatted = results.map((r, i) => `${i + 1}. **${r.title}**\n   ${r.url}\n   ${r.description}`).join(`\n\n`);
-			return {
+function createPromptCoderTool(ctx) {
+	return {
+		name: `prompt_coder`,
+		label: `Prompt Coder`,
+		description: `Send a follow-up prompt to a coder you previously spawned. The prompt is queued on the coder's inbox and runs as the next CLI turn. End your turn after calling — you'll be woken when the coder's reply lands.`,
+		parameters: Type.Object({
+			coder_url: Type.String({ description: `Entity URL returned by spawn_coder, e.g. "/coder/abc123". Must be the URL of a coder you previously spawned in this conversation.` }),
+			prompt: Type.String({ description: `Follow-up message to send to the coder. Treat this like the next turn in a chat — reference earlier context the coder already saw rather than restating it.` })
+		}),
+		execute: async (_toolCallId, params) => {
+			const { coder_url, prompt } = params;
+			if (typeof coder_url !== `string` || !coder_url.startsWith(`/coder/`)) return {
 				content: [{
 					type: `text`,
-					text: formatted
+					text: `Error: coder_url must be a path like "/coder/<id>".`
 				}],
-				details: { resultCount: results.length }
+				details: { sent: false }
 			};
-		} catch (err) {
-			return {
+			if (typeof prompt !== `string` || prompt.length === 0) return {
 				content: [{
 					type: `text`,
-					text: `Search failed: ${err instanceof Error ? err.message : `Unknown error`}`
+					text: `Error: prompt is required and must be a non-empty string.`
 				}],
-				details: { resultCount: 0 }
+				details: { sent: false }
 			};
+			try {
+				ctx.send(coder_url, { text: prompt });
+				return {
+					content: [{
+						type: `text`,
+						text: `Prompt queued for ${coder_url}. End your turn — you'll be woken when the coder's reply lands.`
+					}],
+					details: {
+						sent: true,
+						coderUrl: coder_url
+					}
+				};
+			} catch (err) {
+				serverLog.warn(`[prompt_coder tool] failed to send to ${coder_url}: ${err instanceof Error ? err.message : String(err)}`, err instanceof Error ? err : void 0);
+				return {
+					content: [{
+						type: `text`,
+						text: `Error sending prompt to coder: ${err instanceof Error ? err.message : `Unknown error`}`
+					}],
+					details: { sent: false }
+				};
+			}
 		}
-	}
-};
+	};
+}
 
 //#endregion
 //#region src/agents/horton.ts
 const TITLE_MODEL = `claude-haiku-4-5-20251001`;
-const HORTON_MODEL = `claude-sonnet-4-5-20250929`;
+const HORTON_MODEL = `claude-sonnet-4-6`;
 let anthropic = null;
 function getClient() {
 	if (!anthropic) anthropic = new Anthropic();
@@ -1436,10 +1638,10 @@ async function generateTitle(userMessage, llmCall = defaultHaikuCall) {
 function buildHortonSystemPrompt(workingDirectory, opts = {}) {
 	const docsTools = opts.hasDocsSupport ? `\n- search_durable_agents_docs: hybrid search over the built-in Durable Agents docs index` : ``;
 	const skillsTools = opts.hasSkills ? `\n- use_skill: load a skill (knowledge, instructions, or a tutorial) into your context to help with the user's request\n- remove_skill: unload a skill from context when you're done with it` : ``;
-	const docsGuidance = opts.hasDocsSupport ? `\n- You have built-in Durable Agents docs context plus a docs search tool. Use that before broad web search when the question is about this repo, Electric Agents, or Durable Agents.\n- The docs TOC and docs search results include concrete file paths under the docs tree. Use the normal read tool with those returned paths.\n- Use repo read/bash tools for non-doc files or when you need to inspect exact implementation code in the workspace.` : ``;
+	const docsGuidance = opts.hasDocsSupport ? `\n- For ANY question about Electric Agents, Durable Agents, or this framework, ALWAYS use search_durable_agents_docs FIRST. Do not use brave_search or fetch_url for Electric Agents topics unless the docs search returns no useful results.\n- The search tool returns chunk content directly — you do not need to read the source files.\n- Use repo read/bash tools only for non-doc files or when you need to inspect exact implementation code in the workspace.` : ``;
 	const skillsGuidance = opts.hasSkills ? `\n# Skills\nYou have access to skills — specialized knowledge and guided workflows you can load on demand. Your context includes a skills catalog listing what's available. When the user's request matches a skill's description or keywords, load it with use_skill.
 
-Some skills are user-invocable — the user can trigger them with a slash command like \`/tutorial\`. When you see a message starting with \`/\` followed by a skill name, load that skill immediately with use_skill. Pass any text after the skill name as args.
+Some skills are user-invocable — the user can trigger them with a slash command like \`/quickstart\`. When you see a message starting with \`/\` followed by a skill name, load that skill immediately with use_skill. Pass any text after the skill name as args.
 
 ## IMPORTANT: How to use a loaded skill
 
@@ -1451,8 +1653,33 @@ When you load a skill, it becomes your primary directive for that interaction. F
 4. **Unload when done.** Use remove_skill to free context space when the skill's workflow is complete.
 
 Do NOT load a skill and then ignore its instructions. The skill is there because it contains a tested, specific workflow. Your job is to execute it faithfully.` : ``;
+	const onboardingGuidance = `\n# Onboarding
+When a user is new or asks how to get started with Electric Agents, **don't assume a single path**. Present the options and let them choose:
+
+- **Learn the concepts first** → Explain what Electric Agents is, answer questions, point to docs.
+  Use search_durable_agents_docs to look up answers. Only load the quickstart skill if the user explicitly asks for a hands-on guided tutorial.
+
+- **Hands-on guided tutorial** → Load the quickstart skill (or tell them to type \`/quickstart\`).
+  This is a step-by-step build that takes them from zero to a running app.
+  Only load it when the user explicitly wants to build something hands-on.
+
+- **Scaffold a new project** → Load the init skill.
+  This sets up project structure and orients them in the codebase.
+
+- **Have a specific question?** → Answer it directly.
+  Use search_durable_agents_docs first, then fall back to fetch_url or general knowledge if needed.
+
+Don't force onboarding. If someone just wants to chat or code, let them. When in doubt, ask what they'd like to do rather than picking a path for them.`;
+	const docsUrlGuidance = opts.docsUrl ? `\n# Electric Agents documentation
+- ${opts.hasDocsSupport ? `If search_durable_agents_docs is available, use it first (faster, hybrid search).` : `Use fetch_url to look up documentation pages.`}
+- The Electric Agents docs site is at ${opts.docsUrl}
+- The docs site covers: Usage (entity definition, handlers, tools, state, spawning, coordination, waking, shared state, client integration, app setup), Reference (handler context, entity definitions, configurations, tools, state proxies, wake events, registries), Entities (Horton, Worker), and Patterns (Manager-Worker, Pipeline, Map-Reduce, Dispatcher, Blackboard, Reactive Observers).
+- For general coding questions unrelated to Electric Agents, use brave_search or your own knowledge.` : ``;
 	return `You are Horton, a friendly and capable assistant. You can chat, research the web, read and edit code, run shell commands, and dispatch subagents (workers) for isolated subtasks. Be warm and engaging in conversation; be precise and concrete when working with code.
 
+# Greetings
+When a user opens with a greeting ("hi", "hello", "hey", etc.) or a broad statement like "I want to learn about Electric Agents", respond warmly and introduce yourself. Briefly explain what you can help with and ask what they'd like to do — don't jump straight into a skill or workflow. Let the user tell you what they need before you start loading skills or running tools.
+
 # Tools
 - bash: run shell commands
 - read: read a file
@@ -1461,13 +1688,15 @@ Do NOT load a skill and then ignore its instructions. The skill is there because
 - brave_search: search the web
 - fetch_url: fetch and convert a URL to markdown
 - spawn_worker: dispatch a subagent for an isolated task
+- spawn_coder: spawn a long-lived coding agent (Claude Code or Codex CLI) for code changes, file edits, debugging
+- prompt_coder: send a follow-up prompt to a coder you previously spawned
 ${docsTools}${skillsTools}
 
 # Working with files
 - Prefer edit over write when modifying existing files.
 - You must read a file before you can edit it.
 - Use absolute paths or paths relative to the current working directory.
-${docsGuidance}${skillsGuidance}
+${docsGuidance}${skillsGuidance}${onboardingGuidance}${docsUrlGuidance}
 
 # Risky actions
 Pause and confirm with the user before:
@@ -1488,6 +1717,13 @@ When you spawn a worker, write its system prompt the way you'd brief a colleague
 
 After spawning, end your turn (optionally with a brief "I've dispatched a worker for X; I'll respond when it finishes"). When the worker finishes, you'll receive a message describing which worker completed and what it returned. Multiple workers may finish at different times — check the message for the worker URL to know which one you're hearing about.
 
+# When to spawn a coder
+Spawn a coder when the user asks for code changes, file edits, debugging, or any task that benefits from a real coding agent with full tool access (bash, file edits, etc.). A coder runs Claude Code or Codex CLI under the hood.
+
+Unlike a worker, a coder is **long-lived**: its URL stays valid across many turns. Spawn once with spawn_coder, then keep prompting it via prompt_coder for follow-ups — don't spawn a new coder for each turn. Treat the coder URL like a chat handle.
+
+After calling spawn_coder or prompt_coder, end your turn. When the coder's reply lands, you'll be woken with the response in the wake message — relay it (or a summary) back to the user, and call prompt_coder again if there's a follow-up.
+
 # Reporting
 Report outcomes faithfully. If a command failed, say so with the relevant output. If you didn't run a verification step, say that rather than implying you did. Don't hedge confirmed results with unnecessary disclaimers.
 
@@ -1500,9 +1736,11 @@ function createHortonTools(workingDirectory, ctx, readSet, opts = {}) {
 		createReadFileTool(workingDirectory, readSet),
 		createWriteTool(workingDirectory, readSet),
 		createEditTool(workingDirectory, readSet),
-		braveSearchTool,
+		braveSearchTool$1,
 		fetchUrlTool,
 		createSpawnWorkerTool(ctx),
+		createSpawnCoderTool(ctx),
+		createPromptCoderTool(ctx),
 		...opts.docsSearchTool ? [opts.docsSearchTool] : []
 	];
 }
@@ -1518,7 +1756,7 @@ function extractFirstUserMessage(events) {
 	return null;
 }
 function createAssistantHandler(options) {
-	const { workingDirectory, streamFn, docsSupport, docsSearchTool, skillsRegistry } = options;
+	const { workingDirectory, streamFn, docsSupport, docsSearchTool, skillsRegistry, docsUrl } = options;
 	const hasSkills = Boolean(skillsRegistry && skillsRegistry.catalog.size > 0);
 	return async function assistantHandler(ctx, wake) {
 		const readSet = new Set();
@@ -1568,7 +1806,8 @@ function createAssistantHandler(options) {
 		ctx.useAgent({
 			systemPrompt: buildHortonSystemPrompt(workingDirectory, {
 				hasDocsSupport: Boolean(docsSupport),
-				hasSkills
+				hasSkills,
+				docsUrl
 			}),
 			model: HORTON_MODEL,
 			tools,
@@ -1596,6 +1835,9 @@ function createAssistantHandler(options) {
 }
 function registerHorton(registry, options) {
 	const { workingDirectory, streamFn, skillsRegistry = null } = options;
+	const docsUrl = options.docsUrl ?? process.env.HORTON_DOCS_URL;
+	if (process.env.BRAVE_SEARCH_API_KEY) serverLog.info(`[horton] Web search: using Brave Search API`);
+	else serverLog.warn(`[horton] BRAVE_SEARCH_API_KEY not set — web search will fall back to Anthropic built-in search (uses your ANTHROPIC_API_KEY)`);
 	const docsSupport = createHortonDocsSupport(workingDirectory);
 	const docsSearchTool = docsSupport?.createSearchTool();
 	docsSupport?.ensureReady().catch((error) => {
@@ -1606,7 +1848,8 @@ function registerHorton(registry, options) {
 		streamFn,
 		docsSupport,
 		docsSearchTool,
-		skillsRegistry
+		skillsRegistry,
+		docsUrl
 	});
 	registry.define(`horton`, {
 		description: `Friendly capable assistant — chat, code, research, dispatch`,
@@ -1672,7 +1915,7 @@ function buildToolsForWorker(tools, workingDirectory, ctx, readSet) {
 			out.push(createEditTool(workingDirectory, readSet));
 			break;
 		case `brave_search`:
-			out.push(braveSearchTool);
+			out.push(braveSearchTool$1);
 			break;
 		case `fetch_url`:
 			out.push(fetchUrlTool);
@@ -2092,6 +2335,8 @@ async function createBuiltinAgentHandler(options) {
 		streamFn
 	});
 	typeNames.push(`worker`);
+	registerCodingSession(registry, { defaultWorkingDirectory: cwd });
+	typeNames.push(`coder`);
 	const runtime = createRuntimeHandler({
 		baseUrl: agentServerUrl,
 		serveEndpoint,
@@ -2144,7 +2389,7 @@ var BuiltinAgentsServer = class {
 	}
 	async start() {
 		if (this.server) throw new Error(`Builtin agents server already started`);
-		return new Promise((resolve$1, reject) => {
+		return new Promise((resolve, reject) => {
 			this.server = createServer((req, res) => {
 				this.handleRequest(req, res).catch((error) => {
 					serverLog.error(`[builtin-agents] unhandled request error`, error);
@@ -2177,7 +2422,7 @@ var BuiltinAgentsServer = class {
 					if (!this.bootstrap) throw new Error(`ANTHROPIC_API_KEY must be set before starting builtin agents`);
 					await registerBuiltinAgentTypes(this.bootstrap);
 					serverLog.info(`[builtin-agents] webhook handler listening at ${serveEndpoint}`);
-					resolve$1(this._url);
+					resolve(this._url);
 				} catch (error) {
 					await this.stop().catch(() => {});
 					reject(error);
@@ -2188,13 +2433,13 @@ var BuiltinAgentsServer = class {
 	async stop() {
 		if (this.bootstrap) {
 			this.bootstrap.runtime.abortWakes();
-			await Promise.race([this.bootstrap.runtime.drainWakes().catch(() => {}), new Promise((resolve$1) => setTimeout(resolve$1, 5e3))]);
+			await Promise.race([this.bootstrap.runtime.drainWakes().catch(() => {}), new Promise((resolve) => setTimeout(resolve, 5e3))]);
 			this.bootstrap = null;
 		}
 		if (this.server) {
 			const server = this.server;
-			await new Promise((resolve$1) => {
-				server.close(() => resolve$1());
+			await new Promise((resolve) => {
+				server.close(() => resolve());
 			});
 			this.server = null;
 		}
@@ -2273,4 +2518,4 @@ async function runBuiltinAgentsEntrypoint({ env = process.env, cwd = process.cwd
 }
 
 //#endregion
-export { BuiltinAgentsServer, DEFAULT_BUILTIN_AGENT_HANDLER_PATH, HORTON_MODEL, WORKER_TOOL_NAMES, buildHortonSystemPrompt, createAgentHandler, createBuiltinAgentHandler, createHortonDocsSupport, createHortonTools, createSpawnWorkerTool, generateTitle, registerAgentTypes, registerBuiltinAgentTypes, registerHorton, registerWorker, resolveBuiltinAgentsEntrypointOptions, runBuiltinAgentsEntrypoint };
+export { BuiltinAgentsServer, DEFAULT_BUILTIN_AGENT_HANDLER_PATH, HORTON_MODEL, WORKER_TOOL_NAMES, braveSearchTool, buildHortonSystemPrompt, createAgentHandler, createBuiltinAgentHandler, createHortonDocsSupport, createHortonTools, createSpawnWorkerTool, generateTitle, registerAgentTypes, registerBuiltinAgentTypes, registerCodingSession, registerHorton, registerWorker, resolveBuiltinAgentsEntrypointOptions, runBuiltinAgentsEntrypoint };