@electric-ax/agents 0.1.0

package/dist/index.js

@@ -0,0 +1,1673 @@
+import { createEntityRegistry, createRuntimeHandler } from "@electric-ax/agents-runtime";
+import path, { dirname, relative, resolve } from "node:path";
+import fsSync from "node:fs";
+import pino from "pino";
+import Anthropic from "@anthropic-ai/sdk";
+import { createHash } from "node:crypto";
+import fs, { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+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 { createServer } from "node:http";
+
+//#region src/log.ts
+const LOG_DIR = process.env.ELECTRIC_AGENTS_LOG_DIR ?? path.resolve(process.cwd(), `logs`);
+fsSync.mkdirSync(LOG_DIR, { recursive: true });
+const LOG_FILE = path.join(LOG_DIR, `builtin-agents-${Date.now()}.jsonl`);
+const LOG_LEVEL = process.env.ELECTRIC_AGENTS_LOG_LEVEL ?? `info`;
+const USE_PRETTY_LOGS = LOG_LEVEL !== `silent` && !process.env.VITEST;
+const streams = [{ stream: pino.destination(LOG_FILE) }];
+if (USE_PRETTY_LOGS) streams.push({ stream: pino.transport({
+	target: `pino-pretty`,
+	options: {
+		colorize: true,
+		ignore: `pid,hostname,name`,
+		translateTime: `SYS:HH:MM:ss`
+	}
+}) });
+const logger = pino({
+	base: void 0,
+	level: LOG_LEVEL
+}, pino.multistream(streams));
+function formatArgs(args) {
+	const errors = [];
+	const parts = [];
+	for (const value of args) if (value instanceof Error) errors.push(value);
+	else parts.push(typeof value === `string` ? value : JSON.stringify(value));
+	return {
+		err: errors[0],
+		msg: parts.join(` `)
+	};
+}
+const serverLog = {
+	info(...args) {
+		const { msg } = formatArgs(args);
+		logger.info(msg);
+	},
+	warn(...args) {
+		const { err, msg } = formatArgs(args);
+		if (err) logger.warn({ err }, msg);
+		else logger.warn(msg);
+	},
+	error(...args) {
+		const { err, msg } = formatArgs(args);
+		if (err) logger.error({ err }, msg);
+		else logger.error(msg);
+	},
+	event(obj, msg) {
+		logger.info(obj, msg);
+	}
+};
+
+//#endregion
+//#region src/docs/embed.ts
+const EMBEDDING_DIMENSIONS = 128;
+function tokenize(value) {
+	return value.toLowerCase().replace(/[^a-z0-9\s]/g, ` `).split(/\s+/).filter((token) => token.length > 0);
+}
+function hashToken(token) {
+	return createHash(`sha256`).update(token).digest();
+}
+function embedText(value) {
+	const vector = new Float32Array(EMBEDDING_DIMENSIONS);
+	const tokens = tokenize(value);
+	for (const token of tokens) {
+		const hash = hashToken(token);
+		for (let index = 0; index < 4; index++) {
+			const raw = hash.readUInt32BE(index * 4);
+			const dimension = raw % EMBEDDING_DIMENSIONS;
+			const sign = (hash[index + 16] & 1) === 0 ? 1 : -1;
+			vector[dimension] += sign;
+		}
+	}
+	let norm = 0;
+	for (const value$1 of vector) norm += value$1 * value$1;
+	norm = Math.sqrt(norm);
+	if (norm > 0) for (let index = 0; index < vector.length; index++) vector[index] /= norm;
+	return vector;
+}
+function embeddingToSqlInput(embedding) {
+	return Buffer.from(embedding.buffer.slice(0));
+}
+
+//#endregion
+//#region src/docs/knowledge-base.ts
+const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
+const INDEX_VERSION = `1`;
+const DOCS_FINGERPRINT_KEY = `docs_fingerprint`;
+const INDEX_VERSION_KEY = `index_version`;
+const DEFAULT_K = 8;
+function parseFrontmatter(value) {
+	if (!value.startsWith(`---\n`)) return { body: value };
+	const end = value.indexOf(`\n---\n`, 4);
+	if (end === -1) return { body: value };
+	const frontmatter = value.slice(4, end);
+	const titleMatch = frontmatter.match(/^title:\s*(.+)$/m);
+	return {
+		title: titleMatch?.[1]?.trim().replace(/^['"]|['"]$/g, ``),
+		body: value.slice(end + 5)
+	};
+}
+function firstHeading(value) {
+	const match = value.match(/^#\s+(.+)$/m);
+	return match?.[1]?.trim();
+}
+function collectHeadings(value) {
+	const headings = [];
+	for (const line of value.split(`\n`)) {
+		const match = line.match(/^#{1,6}\s+(.+)$/);
+		if (match) headings.push(match[1].trim());
+	}
+	return headings;
+}
+function toDocTitle(relativePath, content) {
+	const parsed = parseFrontmatter(content);
+	return parsed.title ?? firstHeading(parsed.body) ?? relativePath.replace(/\.md$/, ``).split(`/`).at(-1) ?? relativePath;
+}
+function normalizeWhitespace(value) {
+	return value.replace(/\r\n/g, `\n`).replace(/\n{3,}/g, `\n\n`).trim();
+}
+async function collectMarkdownFiles(root) {
+	async function walk(dir) {
+		const entries = await fs.readdir(dir, { withFileTypes: true });
+		const files = [];
+		for (const entry of entries) {
+			const fullPath = path.join(dir, entry.name);
+			if (entry.isDirectory()) {
+				files.push(...await walk(fullPath));
+				continue;
+			}
+			if (entry.isFile() && entry.name.endsWith(`.md`)) files.push(fullPath);
+		}
+		return files;
+	}
+	return walk(root);
+}
+function chunkMarkdown(input) {
+	const parsed = parseFrontmatter(input.content);
+	const title = toDocTitle(input.relativePath, input.content);
+	const lines = parsed.body.split(`\n`);
+	const sections = [];
+	let currentHeading = title;
+	let currentLines = [];
+	function pushSection() {
+		const text = normalizeWhitespace(currentLines.join(`\n`));
+		if (!text) return;
+		sections.push({
+			heading: currentHeading,
+			text
+		});
+	}
+	for (const line of lines) {
+		const headingMatch = line.match(/^(#{1,6})\s+(.+)$/);
+		if (headingMatch) {
+			pushSection();
+			currentHeading = headingMatch[2].trim();
+			currentLines = [line];
+			continue;
+		}
+		currentLines.push(line);
+	}
+	pushSection();
+	const chunks = [];
+	let chunkIndex = 0;
+	for (const section of sections) {
+		const paragraphs = section.text.split(/\n\s*\n/).map((paragraph) => normalizeWhitespace(paragraph)).filter(Boolean);
+		let current = ``;
+		for (const paragraph of paragraphs) {
+			const candidate = current ? `${current}\n\n${paragraph}` : paragraph;
+			if (candidate.length <= 1200) {
+				current = candidate;
+				continue;
+			}
+			if (current) chunks.push({
+				docPath: input.relativePath,
+				title,
+				heading: section.heading,
+				chunkIndex: chunkIndex++,
+				content: current
+			});
+			if (paragraph.length <= 1200) {
+				current = paragraph;
+				continue;
+			}
+			const overlap = 150;
+			let start = 0;
+			while (start < paragraph.length) {
+				const end = Math.min(start + 1200, paragraph.length);
+				const slice = paragraph.slice(start, end).trim();
+				if (slice) chunks.push({
+					docPath: input.relativePath,
+					title,
+					heading: section.heading,
+					chunkIndex: chunkIndex++,
+					content: slice
+				});
+				if (end >= paragraph.length) {
+					current = ``;
+					break;
+				}
+				start = Math.max(end - overlap, start + 1);
+			}
+		}
+		if (current) chunks.push({
+			docPath: input.relativePath,
+			title,
+			heading: section.heading,
+			chunkIndex: chunkIndex++,
+			content: current
+		});
+	}
+	return chunks;
+}
+function createFingerprint(entries) {
+	const hash = createHash(`sha256`);
+	for (const entry of entries) {
+		hash.update(entry.path);
+		hash.update(`\0`);
+		hash.update(entry.content);
+		hash.update(`\0`);
+	}
+	return hash.digest(`hex`);
+}
+function getMeta(db, key) {
+	const row = db.prepare(`select value from index_meta where key = ?`).get(key);
+	return row?.value ?? null;
+}
+function setMeta(db, key, value) {
+	db.prepare(`insert into index_meta(key, value) values(?, ?)
+     on conflict(key) do update set value = excluded.value`).run(key, value);
+}
+function reciprocalRank(rank, k = 60) {
+	return rank === null ? 0 : 1 / (k + rank);
+}
+function sanitizeSnippet(value) {
+	return value.replace(/\s+/g, ` `).trim();
+}
+function vectorQuerySql() {
+	return `
+    select
+      id,
+      doc_path as docPath,
+      title,
+      heading,
+      content
+    from chunks
+    order by vec_distance_cosine(embedding, vec_f32(?)) asc
+    limit ?
+  `;
+}
+function payloadToText(payload) {
+	if (typeof payload === `string`) return payload;
+	if (payload && typeof payload === `object`) {
+		const text = payload.text;
+		if (typeof text === `string`) return text;
+		return JSON.stringify(payload);
+	}
+	return String(payload ?? ``);
+}
+function findLatestQuestion(items) {
+	for (let index = items.length - 1; index >= 0; index--) {
+		const text = payloadToText(items[index]?.payload).trim();
+		if (text.length > 0) return text;
+	}
+	return void 0;
+}
+function resolveDocsRoot(workingDirectory) {
+	const candidates = [
+		process.env.HORTON_DOCS_ROOT,
+		path.resolve(workingDirectory, `electric-agents-docs/docs`),
+		path.resolve(process.cwd(), `electric-agents-docs/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;
+	return null;
+}
+var DocsKnowledgeBase = class {
+	db;
+	docsRoot;
+	dbPath;
+	logPrefix;
+	fallbackDocs = [];
+	fallbackChunks = [];
+	fallbackFingerprint = ``;
+	readyPromise;
+	constructor(options) {
+		this.docsRoot = options.docsRoot;
+		this.dbPath = options.dbPath;
+		this.logPrefix = options.logPrefix ?? `[horton-docs]`;
+		this.db = this.openDatabase();
+		this.createSchema();
+		this.readyPromise = this.ensureIngested();
+	}
+	openDatabase() {
+		fsSync.mkdirSync(path.dirname(this.dbPath), { recursive: true });
+		try {
+			const db = new Database(this.dbPath);
+			load(db);
+			db.pragma(`journal_mode = WAL`);
+			db.pragma(`synchronous = NORMAL`);
+			return db;
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			console.warn(`${this.logPrefix} falling back to in-memory docs index: ${message}`);
+			return null;
+		}
+	}
+	createSchema() {
+		if (!this.db) return;
+		this.db.exec(`
+      create table if not exists index_meta (
+        key text primary key,
+        value text not null
+      );
+
+      create table if not exists docs (
+        path text primary key,
+        title text not null,
+        content text not null
+      );
+
+      create table if not exists chunks (
+        id integer primary key,
+        doc_path text not null,
+        title text not null,
+        heading text not null,
+        chunk_index integer not null,
+        content text not null,
+        embedding blob not null check(vec_length(embedding) = ${EMBEDDING_DIMENSIONS}),
+        foreign key (doc_path) references docs(path) on delete cascade
+      );
+
+      create index if not exists chunks_doc_path_idx on chunks(doc_path);
+
+      create virtual table if not exists chunks_fts using fts5(
+        doc_path,
+        title,
+        heading,
+        content,
+        tokenize = 'porter unicode61'
+      );
+    `);
+	}
+	async ensureReady() {
+		await this.readyPromise;
+	}
+	stats() {
+		if (!this.db) return {
+			docCount: this.fallbackDocs.length,
+			chunkCount: this.fallbackChunks.length,
+			fingerprint: this.fallbackFingerprint
+		};
+		const docCount = Number(this.db.prepare(`select count(*) as count from docs`).get().count);
+		const chunkCount = Number(this.db.prepare(`select count(*) as count from chunks`).get().count);
+		return {
+			docCount,
+			chunkCount,
+			fingerprint: getMeta(this.db, DOCS_FINGERPRINT_KEY) ?? ``
+		};
+	}
+	async ensureIngested() {
+		await fs.mkdir(path.dirname(this.dbPath), { recursive: true });
+		const files = (await collectMarkdownFiles(this.docsRoot)).sort();
+		const docs = await Promise.all(files.map(async (filePath) => ({
+			path: path.relative(this.docsRoot, filePath),
+			content: await fs.readFile(filePath, `utf8`)
+		})));
+		const fingerprint = createFingerprint(docs);
+		if (!this.db) {
+			if (this.fallbackFingerprint === fingerprint && this.fallbackChunks.length > 0) return this.stats();
+			this.fallbackDocs = docs.map((doc) => ({
+				path: doc.path,
+				title: toDocTitle(doc.path, doc.content),
+				content: doc.content
+			}));
+			this.fallbackChunks = [];
+			let nextId = 1;
+			for (const doc of docs) for (const chunk of chunkMarkdown({
+				relativePath: doc.path,
+				content: doc.content
+			})) {
+				const searchableText = `${chunk.title}\n${chunk.heading}\n${chunk.content}`;
+				this.fallbackChunks.push({
+					...chunk,
+					id: nextId++,
+					embedding: embedText(searchableText)
+				});
+			}
+			this.fallbackFingerprint = fingerprint;
+			const stats$1 = this.stats();
+			console.log(`${this.logPrefix} indexed ${stats$1.docCount} docs into ${stats$1.chunkCount} chunks (${stats$1.fingerprint.slice(0, 12)}...)`);
+			return stats$1;
+		}
+		const db = this.db;
+		const currentFingerprint = getMeta(db, DOCS_FINGERPRINT_KEY);
+		const currentVersion = getMeta(db, INDEX_VERSION_KEY);
+		if (currentFingerprint === fingerprint && currentVersion === INDEX_VERSION && this.stats().chunkCount > 0) return this.stats();
+		const insertDoc = db.prepare(`insert into docs(path, title, content) values(?, ?, ?)`);
+		const insertChunk = db.prepare(`insert into chunks(doc_path, title, heading, chunk_index, content, embedding)
+       values(?, ?, ?, ?, ?, vec_f32(?))`);
+		const insertFts = db.prepare(`insert into chunks_fts(rowid, doc_path, title, heading, content)
+       values(?, ?, ?, ?, ?)`);
+		const reset = db.transaction(() => {
+			db.exec(`
+        delete from chunks_fts;
+        delete from chunks;
+        delete from docs;
+      `);
+			for (const doc of docs) {
+				const title = toDocTitle(doc.path, doc.content);
+				insertDoc.run(doc.path, title, doc.content);
+				const chunks = chunkMarkdown({
+					relativePath: doc.path,
+					content: doc.content
+				});
+				for (const chunk of chunks) {
+					const searchableText = `${chunk.title}\n${chunk.heading}\n${chunk.content}`;
+					const embedding = embeddingToSqlInput(embedText(searchableText));
+					const result = insertChunk.run(chunk.docPath, chunk.title, chunk.heading, chunk.chunkIndex, chunk.content, embedding);
+					insertFts.run(Number(result.lastInsertRowid), chunk.docPath, chunk.title, chunk.heading, chunk.content);
+				}
+			}
+			setMeta(db, DOCS_FINGERPRINT_KEY, fingerprint);
+			setMeta(db, INDEX_VERSION_KEY, INDEX_VERSION);
+		});
+		reset();
+		const stats = this.stats();
+		console.log(`${this.logPrefix} indexed ${stats.docCount} docs into ${stats.chunkCount} chunks (${stats.fingerprint.slice(0, 12)}...)`);
+		return stats;
+	}
+	hybridSearch(query, limit = DEFAULT_K) {
+		const cleanedQuery = query.trim();
+		if (!cleanedQuery) return [];
+		if (!this.db) {
+			const queryEmbedding = embedText(cleanedQuery);
+			const vectorMatches$1 = [...this.fallbackChunks].map((chunk) => ({
+				...chunk,
+				vectorScore: dotProduct(queryEmbedding, chunk.embedding)
+			})).sort((left, right) => right.vectorScore - left.vectorScore).slice(0, limit * 3);
+			const tokens$1 = cleanedQuery.toLowerCase().replace(/[^a-z0-9\s]/g, ` `).split(/\s+/).filter((token) => token.length >= 2);
+			const bm25Matches$1 = tokens$1.length > 0 ? [...this.fallbackChunks].map((chunk) => ({
+				...chunk,
+				bm25Score: keywordScore(`${chunk.title}\n${chunk.heading}\n${chunk.content}`, tokens$1)
+			})).filter((chunk) => chunk.bm25Score > 0).sort((left, right) => right.bm25Score - left.bm25Score).slice(0, limit * 3) : [];
+			const merged$1 = new Map();
+			for (const [index, row] of bm25Matches$1.entries()) {
+				const existing = merged$1.get(row.id);
+				merged$1.set(row.id, {
+					id: row.id,
+					docPath: row.docPath,
+					title: row.title,
+					heading: row.heading,
+					content: row.content,
+					hybridScore: reciprocalRank(index + 1) + reciprocalRank(existing?.vectorRank ?? null),
+					bm25Rank: index + 1,
+					vectorRank: existing?.vectorRank ?? null
+				});
+			}
+			for (const [index, row] of vectorMatches$1.entries()) {
+				const existing = merged$1.get(row.id);
+				merged$1.set(row.id, {
+					id: row.id,
+					docPath: row.docPath,
+					title: row.title,
+					heading: row.heading,
+					content: row.content,
+					hybridScore: reciprocalRank(existing?.bm25Rank ?? null) + reciprocalRank(index + 1),
+					bm25Rank: existing?.bm25Rank ?? null,
+					vectorRank: index + 1
+				});
+			}
+			return [...merged$1.values()].sort((left, right) => right.hybridScore - left.hybridScore).slice(0, limit);
+		}
+		const vectorMatches = this.db.prepare(vectorQuerySql()).all(embeddingToSqlInput(embedText(cleanedQuery)), limit * 3);
+		const tokens = cleanedQuery.toLowerCase().replace(/[^a-z0-9\s]/g, ` `).split(/\s+/).filter((token) => token.length >= 2);
+		const ftsQuery = tokens.length > 0 ? tokens.map((token) => `"${token}"`).join(` OR `) : null;
+		const bm25Matches = ftsQuery ? this.db.prepare(`
+            select
+              c.id as id,
+              c.doc_path as docPath,
+              c.title as title,
+              c.heading as heading,
+              c.content as content,
+              bm25(chunks_fts) as bm25Score
+            from chunks_fts
+            join chunks c on c.id = chunks_fts.rowid
+            where chunks_fts match ?
+            order by bm25Score
+            limit ?
+          `).all(ftsQuery, limit * 3) : [];
+		const merged = new Map();
+		for (const [index, row] of bm25Matches.entries()) {
+			const existing = merged.get(row.id);
+			merged.set(row.id, {
+				id: row.id,
+				docPath: row.docPath,
+				title: row.title,
+				heading: row.heading,
+				content: row.content,
+				hybridScore: reciprocalRank(index + 1) + reciprocalRank(existing?.vectorRank ?? null),
+				bm25Rank: index + 1,
+				vectorRank: existing?.vectorRank ?? null
+			});
+		}
+		for (const [index, row] of vectorMatches.entries()) {
+			const existing = merged.get(row.id);
+			merged.set(row.id, {
+				id: row.id,
+				docPath: row.docPath,
+				title: row.title,
+				heading: row.heading,
+				content: row.content,
+				hybridScore: reciprocalRank(existing?.bm25Rank ?? null) + reciprocalRank(index + 1),
+				bm25Rank: existing?.bm25Rank ?? null,
+				vectorRank: index + 1
+			});
+		}
+		return [...merged.values()].sort((left, right) => right.hybridScore - left.hybridScore).slice(0, limit);
+	}
+	outline() {
+		if (!this.db) return this.fallbackDocs.map((doc) => ({
+			path: doc.path,
+			title: doc.title,
+			headings: collectHeadings(parseFrontmatter(doc.content).body)
+		})).sort((left, right) => left.path.localeCompare(right.path));
+		const docs = this.db.prepare(`select path, title, content from docs order by path`).all();
+		return docs.map((doc) => ({
+			path: doc.path,
+			title: doc.title,
+			headings: collectHeadings(parseFrontmatter(doc.content).body)
+		}));
+	}
+	renderCompressedToc(maxHeadingsPerDoc = 4) {
+		const lines = [`<docs_toc>`];
+		for (const doc of this.outline()) {
+			const headings = doc.headings.slice(0, maxHeadingsPerDoc).map((heading) => heading.replace(/"/g, `&quot;`));
+			const attrs = [`path="${path.resolve(this.docsRoot, doc.path).replace(/"/g, `&quot;`)}"`, `title="${doc.title.replace(/"/g, `&quot;`)}"`];
+			if (headings.length > 0) attrs.push(`headings="${headings.join(` | `)}"`);
+			if (doc.headings.length > maxHeadingsPerDoc) attrs.push(`more_headings="${doc.headings.length - maxHeadingsPerDoc}"`);
+			lines.push(`<doc ${attrs.join(` `)} />`);
+		}
+		lines.push(`</docs_toc>`);
+		return lines.join(`\n`);
+	}
+};
+function dotProduct(left, right) {
+	let sum = 0;
+	for (let index = 0; index < left.length; index++) sum += (left[index] ?? 0) * (right[index] ?? 0);
+	return sum;
+}
+function keywordScore(haystack, tokens) {
+	const normalized = haystack.toLowerCase();
+	let score = 0;
+	for (const token of tokens) if (normalized.includes(token)) score += 1;
+	return score;
+}
+function renderSearchResults(query, results, docsRoot) {
+	if (results.length === 0) return `<docs_search query="${query.replace(/"/g, `&quot;`)}"><no_results /></docs_search>`;
+	const lines = [`<docs_search query="${query.replace(/"/g, `&quot;`)}">`];
+	for (const [index, result] of results.entries()) {
+		const renderedPath = docsRoot ? path.resolve(docsRoot, result.docPath) : result.docPath;
+		lines.push(`<chunk rank="${index + 1}" path="${renderedPath.replace(/"/g, `&quot;`)}" title="${result.title.replace(/"/g, `&quot;`)}" heading="${result.heading.replace(/"/g, `&quot;`)}" chunk_id="${result.id}" hybrid_score="${result.hybridScore.toFixed(5)}" bm25_rank="${result.bm25Rank ?? ``}" vector_rank="${result.vectorRank ?? ``}">`, sanitizeSnippet(result.content), `</chunk>`);
+	}
+	lines.push(`</docs_search>`);
+	return lines.join(`\n`);
+}
+function logSearchResults(kind, query, output) {
+	console.log(`[horton-docs] ${kind} search for "${query}"\n${output}\n`);
+}
+function createHortonDocsSupport(workingDirectory, opts = {}) {
+	const docsRoot = opts.docsRoot ?? resolveDocsRoot(workingDirectory);
+	if (!docsRoot) return null;
+	const dbPath = opts.dbPath ?? path.resolve(workingDirectory, `.electric-agents/horton-docs.sqlite`);
+	const kb = new DocsKnowledgeBase({
+		docsRoot,
+		dbPath,
+		logPrefix: `[horton-docs]`
+	});
+	function resolveCurrentQuestion(wake, events, inbox) {
+		if (wake.type === `message_received`) {
+			const eventQuestion = findLatestQuestion(events.filter((event) => event.type === `message_received`).map((event) => event.value));
+			if (eventQuestion) return eventQuestion;
+		}
+		const wakeQuestion = payloadToText(wake.payload).trim();
+		if (wakeQuestion.length > 0) return wakeQuestion;
+		return findLatestQuestion(inbox) ?? ``;
+	}
+	return {
+		async ensureReady() {
+			await kb.ensureReady();
+		},
+		resolveCurrentQuestion,
+		async renderRetrievedDocsSource(wake, events, inbox) {
+			await kb.ensureReady();
+			const question = resolveCurrentQuestion(wake, events, inbox);
+			if (!question) return `<docs_search><no_query /></docs_search>`;
+			const rendered = renderSearchResults(question, kb.hybridSearch(question, 6), kb.docsRoot);
+			logSearchResults(`initial`, question, rendered);
+			return rendered;
+		},
+		async renderCompressedToc() {
+			await kb.ensureReady();
+			return kb.renderCompressedToc();
+		},
+		createSearchTool() {
+			return {
+				name: `search_durable_agents_docs`,
+				label: `Search Durable Agents Docs`,
+				description: `Run a hybrid BM25 plus vector search over the local Durable Agents documentation index.`,
+				parameters: Type.Object({
+					query: Type.String({ description: `The docs question or search query to run.` }),
+					limit: Type.Optional(Type.Number({
+						minimum: 1,
+						maximum: 12,
+						description: `Maximum number of chunks to return.`
+					}))
+				}),
+				execute: async (_toolCallId, params) => {
+					await kb.ensureReady();
+					const query = String(params.query ?? ``).trim();
+					const limit = Number(params.limit ?? 6);
+					const results = kb.hybridSearch(query, Math.min(Math.max(limit, 1), 12));
+					const rendered = renderSearchResults(query, results, kb.docsRoot);
+					logSearchResults(`tool`, query, rendered);
+					return {
+						content: [{
+							type: `text`,
+							text: rendered
+						}],
+						details: {
+							query,
+							resultCount: results.length,
+							results: results.map((result) => ({
+								id: result.id,
+								docPath: result.docPath,
+								heading: result.heading,
+								hybridScore: result.hybridScore
+							}))
+						}
+					};
+				}
+			};
+		}
+	};
+}
+
+//#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 = [
+	`bash`,
+	`read`,
+	`write`,
+	`edit`,
+	`brave_search`,
+	`fetch_url`,
+	`spawn_worker`
+];
+function createSpawnWorkerTool(ctx) {
+	return {
+		name: `spawn_worker`,
+		label: `Spawn Worker`,
+		description: `Dispatch a subagent (worker) to perform an isolated subtask. Provide a system prompt that briefs the worker like a colleague who just walked into the room (file paths, line numbers, what specifically to do, what form of answer you want back) and pick the subset of tools the worker needs.`,
+		parameters: Type.Object({
+			systemPrompt: Type.String({ description: `System prompt for the worker. Be concrete: include file paths, line numbers, and the form of answer you want back.` }),
+			tools: Type.Array(Type.Union(WORKER_TOOL_NAMES.map((n) => Type.Literal(n))), { description: `Subset of tool names to enable for the worker. Must include at least one.` }),
+			initialMessage: Type.String({ description: `First user message sent to the worker. This is what kicks off its run — without it the worker will idle. Describe the concrete task to perform.` })
+		}),
+		execute: async (_toolCallId, params) => {
+			const { systemPrompt, tools, initialMessage } = params;
+			if (!Array.isArray(tools) || tools.length === 0) return {
+				content: [{
+					type: `text`,
+					text: `Error: provide at least one tool for the worker.`
+				}],
+				details: { spawned: false }
+			};
+			if (typeof initialMessage !== `string` || initialMessage.length === 0) return {
+				content: [{
+					type: `text`,
+					text: `Error: initialMessage is required and must be a non-empty string.`
+				}],
+				details: { spawned: false }
+			};
+			const id = nanoid(10);
+			try {
+				const handle = await ctx.spawn(`worker`, id, {
+					systemPrompt,
+					tools
+				}, {
+					initialMessage,
+					wake: {
+						on: `runFinished`,
+						includeResponse: true
+					}
+				});
+				const workerUrl = handle.entityUrl;
+				return {
+					content: [{
+						type: `text`,
+						text: `Worker dispatched at ${workerUrl}. End your turn — when you next wake, the wake message will tell you the worker has finished and include its response.`
+					}],
+					details: {
+						spawned: true,
+						workerUrl
+					}
+				};
+			} catch (err) {
+				serverLog.warn(`[spawn_worker tool] failed to spawn worker ${id}: ${err instanceof Error ? err.message : String(err)}`, err instanceof Error ? err : void 0);
+				return {
+					content: [{
+						type: `text`,
+						text: `Error spawning worker: ${err instanceof Error ? err.message : `Unknown error`}`
+					}],
+					details: { spawned: false }
+				};
+			}
+		}
+	};
+}
+
+//#endregion
+//#region src/tools/write.ts
+function createWriteTool(workingDirectory, readSet) {
+	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.`,
+		parameters: Type.Object({
+			path: Type.String({ description: `File path (relative to working directory)` }),
+			content: Type.String({ description: `Full file contents to write` })
+		}),
+		execute: async (_toolCallId, params) => {
+			const { path: filePath, content } = 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: { bytesWritten: 0 }
+				};
+				await mkdir(dirname(resolved), { recursive: true });
+				await writeFile(resolved, content, `utf-8`);
+				readSet?.add(resolved);
+				const bytesWritten = Buffer.byteLength(content, `utf-8`);
+				return {
+					content: [{
+						type: `text`,
+						text: `Wrote ${bytesWritten} bytes to ${rel}`
+					}],
+					details: { bytesWritten }
+				};
+			} catch (err) {
+				serverLog.warn(`[write tool] failed to write ${filePath}: ${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`}`
+					}],
+					details: { bytesWritten: 0 }
+				};
+			}
+		}
+	};
+}
+
+//#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 {
+				content: [{
+					type: `text`,
+					text: formatted
+				}],
+				details: { resultCount: results.length }
+			};
+		} catch (err) {
+			return {
+				content: [{
+					type: `text`,
+					text: `Search failed: ${err instanceof Error ? err.message : `Unknown error`}`
+				}],
+				details: { resultCount: 0 }
+			};
+		}
+	}
+};
+
+//#endregion
+//#region src/agents/horton.ts
+const TITLE_MODEL = `claude-haiku-4-5-20251001`;
+const HORTON_MODEL = `claude-sonnet-4-5-20250929`;
+let anthropic = null;
+function getClient() {
+	if (!anthropic) anthropic = new Anthropic();
+	return anthropic;
+}
+async function defaultHaikuCall(prompt) {
+	const client = getClient();
+	const res = await client.messages.create({
+		model: TITLE_MODEL,
+		max_tokens: 64,
+		messages: [{
+			role: `user`,
+			content: prompt
+		}]
+	});
+	const block = res.content[0];
+	return block?.type === `text` ? block.text : ``;
+}
+const TITLE_PROMPT = (userMessage) => `Summarize the following user request in 3-5 words for use as a chat session title.
+Respond with only the title, no quotes, no punctuation, no preamble.
+
+User request:
+${userMessage}`;
+const TITLE_STOP_WORDS = new Set([
+	`a`,
+	`an`,
+	`and`,
+	`are`,
+	`can`,
+	`for`,
+	`from`,
+	`help`,
+	`i`,
+	`in`,
+	`into`,
+	`is`,
+	`it`,
+	`look`,
+	`me`,
+	`my`,
+	`need`,
+	`of`,
+	`on`,
+	`or`,
+	`please`,
+	`the`,
+	`this`,
+	`to`,
+	`we`,
+	`with`,
+	`you`
+]);
+const TITLE_IGNORED_WORDS = new Set([
+	`dist`,
+	`js`,
+	`json`,
+	`jsx`,
+	`md`,
+	`package`,
+	`packages`,
+	`src`,
+	`ts`,
+	`tsx`,
+	`yaml`,
+	`yml`
+]);
+function toTitleWord(word) {
+	return word.charAt(0).toUpperCase() + word.slice(1).toLowerCase();
+}
+function buildFallbackTitle(userMessage) {
+	const cleaned = userMessage.replace(/`[^`]*`/g, ` `).replace(/[./\\_-]+/g, ` `).replace(/[^a-zA-Z0-9\s]/g, ` `).replace(/\s+/g, ` `).trim();
+	const rawWords = cleaned.split(/\s+/).filter(Boolean);
+	const seen = new Set();
+	const informativeWords = [];
+	const backupWords = [];
+	for (const rawWord of rawWords) {
+		const word = rawWord.toLowerCase();
+		if (seen.has(word)) continue;
+		seen.add(word);
+		if (!/^[a-z0-9]+$/i.test(word)) continue;
+		if (word.length < 2 || /^\d+$/.test(word)) continue;
+		if (TITLE_IGNORED_WORDS.has(word)) continue;
+		const titled = toTitleWord(word);
+		if (backupWords.length < 5) backupWords.push(titled);
+		if (TITLE_STOP_WORDS.has(word)) continue;
+		informativeWords.push(titled);
+	}
+	const selected = informativeWords.length >= 2 ? informativeWords.slice(0, 5) : backupWords;
+	return selected.join(` `).slice(0, 80).trim() || `Untitled Chat`;
+}
+async function generateTitle(userMessage, llmCall = defaultHaikuCall) {
+	try {
+		const raw = await llmCall(TITLE_PROMPT(userMessage));
+		const title = raw.trim();
+		return title.length > 0 ? title : buildFallbackTitle(userMessage);
+	} catch {
+		return buildFallbackTitle(userMessage);
+	}
+}
+function buildHortonSystemPrompt(workingDirectory, opts = {}) {
+	const docsTools = opts.hasDocsSupport ? `\n- search_durable_agents_docs: hybrid search over the built-in Durable Agents docs index` : ``;
+	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.` : ``;
+	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.
+
+# Tools
+- bash: run shell commands
+- read: read a file
+- write: create or overwrite a file
+- edit: targeted string replacement in an existing file (you must read the file first)
+- brave_search: search the web
+- fetch_url: fetch and convert a URL to markdown
+- spawn_worker: dispatch a subagent for an isolated task
+${docsTools}
+
+# 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}
+
+# Risky actions
+Pause and confirm with the user before:
+- Destructive operations (deleting files, rm -rf, dropping data, force-pushing)
+- Hard-to-reverse operations (git reset --hard, removing dependencies)
+- Actions visible to others (pushing code, opening PRs, sending messages)
+
+# Parallelism
+Run independent tool calls in parallel. Only run sequentially when one call depends on the result of another.
+
+# When to spawn a worker
+Dispatch a worker when:
+- The subtask involves long research that would clutter our conversation.
+- The subtask is independent and can run in parallel with other work.
+- You need an isolated context (e.g., focused coding on one file without pulling its full content into our chat).
+
+When you spawn a worker, write its system prompt the way you'd brief a colleague who just walked in: include file paths, line numbers, what specifically to do, and what form of answer you want back. The system prompt sets the worker's persona and constraints; the required initialMessage is the concrete task you're handing off — that's what kicks the worker off, so without it the worker sits idle.
+
+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.
+
+# 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.
+
+Working directory: ${workingDirectory}
+The current year is ${new Date().getFullYear()}.`;
+}
+function createHortonTools(workingDirectory, ctx, readSet, opts = {}) {
+	return [
+		createBashTool(workingDirectory),
+		createReadFileTool(workingDirectory, readSet),
+		createWriteTool(workingDirectory, readSet),
+		createEditTool(workingDirectory, readSet),
+		braveSearchTool,
+		fetchUrlTool,
+		createSpawnWorkerTool(ctx),
+		...opts.docsSearchTool ? [opts.docsSearchTool] : []
+	];
+}
+function extractFirstUserMessage(events) {
+	for (const event of events) {
+		if (event.type !== `message_received`) continue;
+		const value = event.value;
+		if (!value || value.from === `system`) continue;
+		const payload = value.payload;
+		if (typeof payload === `string`) return payload;
+		if (payload != null) return JSON.stringify(payload);
+	}
+	return null;
+}
+function createAssistantHandler(options) {
+	const { workingDirectory, streamFn, docsSupport, docsSearchTool } = options;
+	return async function assistantHandler(ctx, wake) {
+		const readSet = new Set();
+		const tools = [...ctx.electricTools, ...createHortonTools(workingDirectory, ctx, readSet, { docsSearchTool })];
+		if (docsSupport) ctx.useContext({
+			sourceBudget: 1e5,
+			sources: {
+				docs_toc: {
+					content: () => docsSupport.renderCompressedToc(),
+					max: 3e3,
+					cache: `stable`
+				},
+				retrieved_docs: {
+					content: () => docsSupport.renderRetrievedDocsSource(wake, ctx.events, ctx.db.collections.inbox.toArray),
+					max: 6e3,
+					cache: `volatile`
+				},
+				conversation: {
+					content: () => ctx.timelineMessages(),
+					cache: `volatile`
+				}
+			}
+		});
+		ctx.useAgent({
+			systemPrompt: buildHortonSystemPrompt(workingDirectory, { hasDocsSupport: Boolean(docsSupport) }),
+			model: HORTON_MODEL,
+			tools,
+			...streamFn && { streamFn }
+		});
+		await ctx.agent.run();
+		if (ctx.firstWake && !ctx.tags.title) {
+			const firstUserMessage = extractFirstUserMessage(ctx.events);
+			if (firstUserMessage) {
+				let title = null;
+				try {
+					const result = await generateTitle(firstUserMessage);
+					if (result.length > 0) title = result;
+				} catch (err) {
+					serverLog.warn(`[horton ${ctx.entityUrl}] title generation failed: ${err instanceof Error ? err.message : String(err)}`);
+				}
+				if (title !== null) try {
+					await ctx.setTag(`title`, title);
+				} catch (err) {
+					serverLog.warn(`[horton ${ctx.entityUrl}] setTag failed: ${err instanceof Error ? err.message : String(err)}`);
+				}
+			}
+		}
+	};
+}
+function registerHorton(registry, options) {
+	const { workingDirectory, streamFn } = options;
+	const docsSupport = createHortonDocsSupport(workingDirectory);
+	const docsSearchTool = docsSupport?.createSearchTool();
+	docsSupport?.ensureReady().catch((error) => {
+		serverLog.warn(`[horton-docs] warmup failed: ${error instanceof Error ? error.message : String(error)}`);
+	});
+	const assistantHandler = createAssistantHandler({
+		workingDirectory,
+		streamFn,
+		docsSupport,
+		docsSearchTool
+	});
+	registry.define(`horton`, {
+		description: `Friendly capable assistant — chat, code, research, dispatch`,
+		handler: assistantHandler
+	});
+	const typeNames = [`horton`];
+	if (streamFn) {
+		registry.define(`chat`, {
+			description: `Compatibility alias for the built-in assistant type.`,
+			handler: assistantHandler
+		});
+		typeNames.push(`chat`);
+	}
+	return typeNames;
+}
+
+//#endregion
+//#region src/agents/worker.ts
+function isWorkerToolName(value) {
+	return typeof value === `string` && WORKER_TOOL_NAMES.includes(value);
+}
+function parseWorkerArgs(value) {
+	if (typeof value.systemPrompt !== `string` || value.systemPrompt.length === 0) throw new Error(`[worker] systemPrompt is required`);
+	if (!Array.isArray(value.tools) || value.tools.length === 0) throw new Error(`[worker] tools must be a non-empty array`);
+	const tools = [];
+	for (const t of value.tools) {
+		if (!isWorkerToolName(t)) throw new Error(`[worker] unknown tool name: ${JSON.stringify(t)}. Valid tools: ${WORKER_TOOL_NAMES.join(`, `)}`);
+		if (!tools.includes(t)) tools.push(t);
+	}
+	return {
+		systemPrompt: value.systemPrompt,
+		tools
+	};
+}
+function buildToolsForWorker(tools, workingDirectory, ctx, readSet) {
+	const out = [];
+	for (const name of tools) switch (name) {
+		case `bash`:
+			out.push(createBashTool(workingDirectory));
+			break;
+		case `read`:
+			out.push(createReadFileTool(workingDirectory, readSet));
+			break;
+		case `write`:
+			out.push(createWriteTool(workingDirectory, readSet));
+			break;
+		case `edit`:
+			out.push(createEditTool(workingDirectory, readSet));
+			break;
+		case `brave_search`:
+			out.push(braveSearchTool);
+			break;
+		case `fetch_url`:
+			out.push(fetchUrlTool);
+			break;
+		case `spawn_worker`:
+			out.push(createSpawnWorkerTool(ctx));
+			break;
+	}
+	return out;
+}
+const WORKER_PROMPT_FOOTER = `
+
+# 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.`;
+function registerWorker(registry, options) {
+	const { workingDirectory, streamFn } = options;
+	registry.define(`worker`, {
+		description: `Internal — generic worker spawned by other agents. Configure via spawn args (systemPrompt + tools).`,
+		async handler(ctx) {
+			const args = parseWorkerArgs(ctx.args);
+			const readSet = new Set();
+			const tools = buildToolsForWorker(args.tools, workingDirectory, ctx, readSet);
+			ctx.useAgent({
+				systemPrompt: `${args.systemPrompt}${WORKER_PROMPT_FOOTER}`,
+				model: HORTON_MODEL,
+				tools,
+				...streamFn && { streamFn }
+			});
+			await ctx.agent.run();
+		}
+	});
+}
+
+//#endregion
+//#region src/bootstrap.ts
+const DEFAULT_BUILTIN_AGENT_HANDLER_PATH = `/_electric/builtin-agent-handler`;
+function createBuiltinAgentHandler(options) {
+	const { agentServerUrl, serveEndpoint = `${agentServerUrl}${DEFAULT_BUILTIN_AGENT_HANDLER_PATH}`, workingDirectory, streamFn, createElectricTools } = options;
+	if (!streamFn && !process.env.ANTHROPIC_API_KEY) {
+		serverLog.warn(`[builtin-agents] ANTHROPIC_API_KEY not set — skipping built-in agent registration`);
+		return null;
+	}
+	const cwd = workingDirectory ?? process.cwd();
+	const registry = createEntityRegistry();
+	const typeNames = registerHorton(registry, {
+		workingDirectory: cwd,
+		streamFn
+	});
+	registerWorker(registry, {
+		workingDirectory: cwd,
+		streamFn
+	});
+	typeNames.push(`worker`);
+	const runtime = createRuntimeHandler({
+		baseUrl: agentServerUrl,
+		serveEndpoint,
+		registry,
+		subscriptionPathForType: (name) => `/${name}/*/main`,
+		idleTimeout: 5e3,
+		createElectricTools
+	});
+	return {
+		handler: runtime.onEnter,
+		runtime,
+		registry,
+		typeNames
+	};
+}
+function createAgentHandler(agentServerUrl, workingDirectory, streamFn, createElectricTools, serveEndpoint) {
+	return createBuiltinAgentHandler({
+		agentServerUrl,
+		serveEndpoint,
+		workingDirectory,
+		streamFn,
+		createElectricTools
+	});
+}
+async function registerBuiltinAgentTypes(bootstrap) {
+	await bootstrap.runtime.registerTypes();
+	serverLog.info(`[builtin-agents] ${bootstrap.typeNames.length} built-in agent types ready: ${bootstrap.typeNames.join(`, `)}`);
+}
+const registerAgentTypes = registerBuiltinAgentTypes;
+
+//#endregion
+//#region src/server.ts
+var BuiltinAgentsServer = class {
+	server = null;
+	bootstrap = null;
+	_url = null;
+	publicBaseUrl = null;
+	options;
+	constructor(options) {
+		this.options = options;
+	}
+	get url() {
+		if (!this._url) throw new Error(`Builtin agents server not started`);
+		return this._url;
+	}
+	get registeredBaseUrl() {
+		if (!this.publicBaseUrl) throw new Error(`Builtin agents server not started`);
+		return this.publicBaseUrl;
+	}
+	async start() {
+		if (this.server) throw new Error(`Builtin agents server already started`);
+		return new Promise((resolve$1, reject) => {
+			this.server = createServer((req, res) => {
+				this.handleRequest(req, res).catch((error) => {
+					serverLog.error(`[builtin-agents] unhandled request error`, error);
+					if (!res.headersSent) {
+						res.writeHead(500, { "content-type": `application/json` });
+						res.end(JSON.stringify({ error: `Internal server error` }));
+					}
+				});
+			});
+			this.server.on(`error`, reject);
+			const host = this.options.host ?? `127.0.0.1`;
+			this.server.listen(this.options.port, host, async () => {
+				try {
+					const addr = this.server.address();
+					if (typeof addr === `string`) this._url = addr;
+					else if (addr) {
+						const resolvedHost = host === `0.0.0.0` ? `127.0.0.1` : host;
+						this._url = `http://${resolvedHost}:${addr.port}`;
+					} else throw new Error(`Could not determine builtin agents server address`);
+					this.publicBaseUrl = this.options.baseUrl ?? this._url;
+					const webhookPath = this.options.webhookPath ?? DEFAULT_BUILTIN_AGENT_HANDLER_PATH;
+					const serveEndpoint = new URL(webhookPath, this.publicBaseUrl.endsWith(`/`) ? this.publicBaseUrl : `${this.publicBaseUrl}/`).toString();
+					this.bootstrap = createBuiltinAgentHandler({
+						agentServerUrl: this.options.agentServerUrl,
+						serveEndpoint,
+						workingDirectory: this.options.workingDirectory,
+						streamFn: this.options.mockStreamFn,
+						createElectricTools: this.options.createElectricTools
+					});
+					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);
+				} catch (error) {
+					await this.stop().catch(() => {});
+					reject(error);
+				}
+			});
+		});
+	}
+	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))]);
+			this.bootstrap = null;
+		}
+		if (this.server) {
+			const server = this.server;
+			await new Promise((resolve$1) => {
+				server.close(() => resolve$1());
+			});
+			this.server = null;
+		}
+		this._url = null;
+		this.publicBaseUrl = null;
+	}
+	async handleRequest(req, res) {
+		const method = req.method?.toUpperCase();
+		const path$1 = new URL(req.url ?? `/`, `http://localhost`).pathname;
+		const webhookPath = this.options.webhookPath ?? DEFAULT_BUILTIN_AGENT_HANDLER_PATH;
+		if (path$1 === `/_electric/health` && method === `GET`) {
+			res.writeHead(200, { "content-type": `application/json` });
+			res.end(JSON.stringify({ status: `ok` }));
+			return;
+		}
+		if (path$1 === webhookPath && method === `POST` && this.bootstrap) {
+			await this.bootstrap.handler(req, res);
+			return;
+		}
+		res.writeHead(404, { "content-type": `application/json` });
+		res.end(JSON.stringify({ error: `Not found` }));
+	}
+};
+
+//#endregion
+//#region src/entrypoint-lib.ts
+const DEFAULT_HOST = `127.0.0.1`;
+const DEFAULT_PORT = 4448;
+function readEnv(env, names) {
+	for (const name of names) {
+		const value = env[name]?.trim();
+		if (value) return value;
+	}
+	return void 0;
+}
+function readRequiredEnv(env, names, description) {
+	const value = readEnv(env, names);
+	if (value) return value;
+	throw new Error(`Missing ${description}. Set one of: ${names.map((name) => `"${name}"`).join(`, `)}`);
+}
+function readPort(env) {
+	const raw = readEnv(env, [`ELECTRIC_AGENTS_BUILTIN_PORT`, `PORT`]);
+	if (!raw) return DEFAULT_PORT;
+	const port = Number(raw);
+	if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error(`Invalid builtin agents port "${raw}". Expected an integer between 1 and 65535.`);
+	return port;
+}
+function validateUrl(name, value) {
+	try {
+		new URL(value);
+		return value;
+	} catch {
+		throw new Error(`Invalid ${name}: "${value}"`);
+	}
+}
+function resolveBuiltinAgentsEntrypointOptions(env = process.env, cwd = process.cwd()) {
+	const agentServerUrl = validateUrl(`agent server URL`, readRequiredEnv(env, [`ELECTRIC_AGENTS_SERVER_URL`, `ELECTRIC_AGENTS_BASE_URL`], `agent server base URL`));
+	const baseUrl = readEnv(env, [`ELECTRIC_AGENTS_BUILTIN_BASE_URL`, `BUILTIN_AGENTS_BASE_URL`]);
+	return {
+		agentServerUrl,
+		baseUrl: baseUrl ? validateUrl(`builtin agents base URL`, baseUrl) : void 0,
+		host: readEnv(env, [`ELECTRIC_AGENTS_BUILTIN_HOST`, `HOST`]) ?? DEFAULT_HOST,
+		port: readPort(env),
+		workingDirectory: readEnv(env, [`ELECTRIC_AGENTS_WORKING_DIRECTORY`, `WORKING_DIRECTORY`]) ?? cwd
+	};
+}
+async function runBuiltinAgentsEntrypoint({ env = process.env, cwd = process.cwd(), createServer: createServer$1 = (options$1) => new BuiltinAgentsServer(options$1) } = {}) {
+	const options = resolveBuiltinAgentsEntrypointOptions(env, cwd);
+	const server = createServer$1(options);
+	const url = await server.start();
+	return {
+		options,
+		server,
+		url
+	};
+}
+
+//#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 };