@electric-ax/agents 0.3.0 → 0.4.1

package/dist/index.d.ts

@@ -1,9 +1,9 @@
-import { AgentConfig, AgentTool, AvailableProvider, EntityRegistry, EntityStreamDBWithActions, HandlerContext, RuntimeHandler, WakeEvent } from "@electric-ax/agents-runtime";
+import { AgentConfig, AgentTool, AvailableProvider, DispatchPolicy, EntityRegistry, EntityStreamDBWithActions, HandlerContext, HeadersProvider, PullWakeRunnerConfig, RuntimeHandler, WakeEvent } from "@electric-ax/agents-runtime";
 import { ChangeEvent } from "@durable-streams/state";
 import { braveSearchTool } from "@electric-ax/agents-runtime/tools";
 import { ListedEntry as McpListedEntry, McpConfig, McpServerConfig, McpServerConfig as McpServerConfig$1, Registry, Registry as McpRegistry, RegistrySnapshot, RegistrySubscriber } from "@electric-ax/agents-mcp";
-import { IncomingMessage, ServerResponse } from "node:http";
 import { AgentTool as AgentTool$1, StreamFn } from "@mariozechner/pi-agent-core";
+import { IncomingMessage, ServerResponse } from "node:http";
 
 //#region src/skills/types.d.ts
 interface SkillMeta {
@@ -43,6 +43,10 @@ interface BuiltinAgentHandlerOptions {
   streamFn?: StreamFn;
   publicUrl?: string;
   runtimeName?: string;
+  /** Override for the built-in skills directory; required when embedders bundle this package. */
+  baseSkillsDir?: string;
+  serverHeaders?: HeadersProvider;
+  defaultDispatchPolicyForType?: (typeName: string) => DispatchPolicy | undefined;
   createElectricTools?: (context: {
     entityUrl: string;
     entityType: string;
@@ -85,12 +89,20 @@ declare const registerAgentTypes: typeof registerBuiltinAgentTypes;
 //#region src/server.d.ts
 interface BuiltinAgentsServerOptions {
   agentServerUrl: string;
-  baseUrl?: string;
-  port: number;
-  host?: string;
   workingDirectory?: string;
   mockStreamFn?: StreamFn;
-  webhookPath?: string;
+  /** Pull-wake runner configuration for built-in agents. */
+  pullWake: {
+    runnerId: string;
+    ownerUserId?: string;
+    label?: string;
+    registerRunner?: boolean;
+    headers?: PullWakeRunnerConfig[`headers`];
+    claimHeaders?: PullWakeRunnerConfig[`claimHeaders`];
+    claimTokenHeader?: PullWakeRunnerConfig[`claimTokenHeader`];
+    heartbeatIntervalMs?: PullWakeRunnerConfig[`heartbeatIntervalMs`];
+    leaseMs?: PullWakeRunnerConfig[`leaseMs`];
+  };
   /** Invoked when an `authorizationCode` server needs user consent. */
   openAuthorizeUrl?: (url: string, server: string) => void;
   /**
@@ -115,6 +127,8 @@ interface BuiltinAgentsServerOptions {
    * so the embedder must opt in.
    */
   loadProjectMcpConfig?: boolean;
+  /** Override for the built-in skills directory; required when embedders bundle this package. */
+  baseSkillsDir?: string;
   createElectricTools?: (context: {
     entityUrl: string;
     entityType: string;
@@ -149,24 +163,20 @@ interface BuiltinAgentsServerOptions {
   }) => Array<AgentTool> | Promise<Array<AgentTool>>;
 }
 declare class BuiltinAgentsServer {
-  private server;
   private bootstrap;
-  private _url;
-  private publicBaseUrl;
   private _mcpRegistry;
   private mcpWatcherCloser;
   private mcpToolProviderName;
   private mcpApplyInFlight;
   private mcpStopping;
+  private pullWakeRunner;
   readonly options: BuiltinAgentsServerOptions;
   constructor(options: BuiltinAgentsServerOptions);
   /** Embedded MCP registry. `null` until `start()` has run. */
   get mcpRegistry(): Registry | null;
-  get url(): string;
-  get registeredBaseUrl(): string;
   start(): Promise<string>;
   stop(): Promise<void>;
-  private handleRequest;
+  private registerPullWakeRunner;
 }
 
 //#endregion

package/dist/index.js

@@ -1,6 +1,6 @@
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { completeWithLowCostModel, createEntityRegistry, createRuntimeHandler, db, detectAvailableProviders, readCodexAccessToken, registerToolProvider, unregisterToolProvider } from "@electric-ax/agents-runtime";
+import { appendPathToUrl, completeWithLowCostModel, createEntityRegistry, createPullWakeRunner, createRuntimeHandler, db, detectAvailableProviders, readCodexAccessToken, registerToolProvider, unregisterToolProvider } from "@electric-ax/agents-runtime";
 import fs from "node:fs";
 import pino from "pino";
 import { eq, not, queryOnce } from "@durable-streams/state";
@@ -14,15 +14,18 @@ import { nanoid } from "nanoid";
 import { getModels } from "@mariozechner/pi-ai";
 import { braveSearchTool, braveSearchTool as braveSearchTool$1, createBashTool, createEditTool, createFetchUrlTool, createReadFileTool, createWriteTool, fetchUrlTool } from "@electric-ax/agents-runtime/tools";
 import { bridgeMcpTool, buildPromptTools, buildResourceTools, createRegistry, keychainPersistence, loadConfig, mcp, watchConfig } from "@electric-ax/agents-mcp";
-import { createServer } from "node:http";
 
 //#region src/log.ts
 const LOG_DIR = process.env.ELECTRIC_AGENTS_LOG_DIR ?? path.resolve(process.cwd(), `logs`);
 fs.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) }];
+const IS_ELECTRON_MAIN = Boolean(process.versions.electron);
+const USE_PRETTY_LOGS = LOG_LEVEL !== `silent` && !process.env.VITEST && !IS_ELECTRON_MAIN;
+const streams = [{ stream: pino.destination({
+	dest: LOG_FILE,
+	sync: IS_ELECTRON_MAIN
+}) }];
 if (USE_PRETTY_LOGS) streams.push({ stream: pino.transport({
 	target: `pino-pretty`,
 	options: {
@@ -621,8 +624,8 @@ function createHortonDocsSupport(workingDirectory, opts = {}) {
 		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 (wake.type === `inbox`) {
+			const eventQuestion = findLatestQuestion(events.filter((event) => event.type === `inbox`).map((event) => event.value));
 			if (eventQuestion) return eventQuestion;
 		}
 		const wakeQuestion = payloadToText(wake.payload).trim();
@@ -1423,7 +1426,8 @@ function registerHorton(registry, options) {
 	const { workingDirectory, streamFn, skillsRegistry = null, modelCatalog } = 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)`);
+	else if (process.env.ANTHROPIC_API_KEY) serverLog.warn(`[horton] BRAVE_SEARCH_API_KEY not set — web search will fall back to Anthropic built-in search`);
+	else serverLog.warn(`[horton] BRAVE_SEARCH_API_KEY and ANTHROPIC_API_KEY not set — web search tool will be unavailable`);
 	const docsSupport = createHortonDocsSupport(workingDirectory);
 	const docsSearchTool = docsSupport?.createSearchTool();
 	docsSupport?.ensureReady().catch((error) => {
@@ -1900,7 +1904,7 @@ function truncate(str, max) {
 //#region src/bootstrap.ts
 const DEFAULT_BUILTIN_AGENT_HANDLER_PATH = `/_electric/builtin-agent-handler`;
 async function createBuiltinAgentHandler(options) {
-	const { agentServerUrl, serveEndpoint = `${agentServerUrl}${DEFAULT_BUILTIN_AGENT_HANDLER_PATH}`, workingDirectory, streamFn, createElectricTools, publicUrl, runtimeName } = options;
+	const { agentServerUrl, serveEndpoint, workingDirectory, streamFn, createElectricTools, publicUrl, runtimeName, baseSkillsDir: baseSkillsDirOverride, serverHeaders, defaultDispatchPolicyForType } = options;
 	const modelCatalog = await createBuiltinModelCatalog({ allowMockFallback: Boolean(streamFn) });
 	if (!modelCatalog) {
 		serverLog.warn(`[builtin-agents] no supported model provider API key found — set ANTHROPIC_API_KEY or OPENAI_API_KEY`);
@@ -1908,7 +1912,7 @@ async function createBuiltinAgentHandler(options) {
 	}
 	const cwd = workingDirectory ?? process.cwd();
 	const here = path.dirname(fileURLToPath(import.meta.url));
-	const baseSkillsDir = path.resolve(here, `../skills`);
+	const baseSkillsDir = baseSkillsDirOverride ?? path.resolve(here, `../skills`);
 	let skillsRegistry = null;
 	try {
 		skillsRegistry = await createSkillsRegistry({
@@ -1938,6 +1942,8 @@ async function createBuiltinAgentHandler(options) {
 		serveEndpoint,
 		registry,
 		subscriptionPathForType: (name) => `/${name}/*/main`,
+		defaultDispatchPolicyForType,
+		serverHeaders,
 		idleTimeout: 5e3,
 		createElectricTools,
 		publicUrl,
@@ -1969,15 +1975,13 @@ const registerAgentTypes = registerBuiltinAgentTypes;
 //#endregion
 //#region src/server.ts
 var BuiltinAgentsServer = class {
-	server = null;
 	bootstrap = null;
-	_url = null;
-	publicBaseUrl = null;
 	_mcpRegistry = null;
 	mcpWatcherCloser = null;
 	mcpToolProviderName = null;
 	mcpApplyInFlight = new Set();
 	mcpStopping = false;
+	pullWakeRunner = null;
 	options;
 	constructor(options) {
 		this.options = options;
@@ -1986,171 +1990,167 @@ var BuiltinAgentsServer = class {
 	get mcpRegistry() {
 		return this._mcpRegistry;
 	}
-	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, 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` }));
-					}
-				});
+		if (this.bootstrap || this.pullWakeRunner) throw new Error(`Builtin agents runtime already started`);
+		const pullWake = this.options.pullWake;
+		if (!pullWake?.runnerId) throw new Error(`Builtin agents require a pull-wake runner id`);
+		try {
+			const publicUrl = this.options.mcpOAuthRedirectBase ?? this.options.agentServerUrl;
+			const mcpRegistry = createRegistry({
+				publicUrl,
+				openAuthorizeUrl: this.options.openAuthorizeUrl
 			});
-			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();
-					const publicUrl = this.options.mcpOAuthRedirectBase ?? this.publicBaseUrl;
-					const mcpRegistry = createRegistry({
-						publicUrl,
-						openAuthorizeUrl: this.options.openAuthorizeUrl
-					});
-					this._mcpRegistry = mcpRegistry;
-					const mcpConfigPath = this.options.loadProjectMcpConfig ? path.resolve(this.options.workingDirectory ?? process.cwd(), `mcp.json`) : null;
-					const extras = this.options.extraMcpServers ?? [];
-					const wirePersistence = async (cfg) => {
-						const servers = [];
-						for (const s of cfg.servers) if (s.transport === `http` && s.auth?.mode === `authorizationCode`) {
-							const persist = await keychainPersistence({ server: s.name });
-							servers.push({
-								...s,
-								auth: {
-									...s.auth,
-									...persist
-								}
-							});
-						} else servers.push(s);
-						return {
-							...cfg,
-							servers
-						};
-					};
-					const merge = (jsonCfg) => {
-						const jsonServers = jsonCfg?.servers ?? [];
-						const jsonNames = new Set(jsonServers.map((s) => s.name));
-						const filteredExtras = extras.filter((s) => !jsonNames.has(s.name));
-						return {
-							servers: [...filteredExtras, ...jsonServers],
-							raw: jsonCfg?.raw
-						};
-					};
-					const onConfigError = this.options.onConfigError;
-					const runApply = async (jsonCfg) => {
-						if (this.mcpStopping) return;
-						try {
-							const wired = await wirePersistence(merge(jsonCfg));
-							if (this.mcpStopping) return;
-							await mcpRegistry.applyConfig(wired);
-						} catch (e) {
-							serverLog.error(`[mcp] applyConfig:`, e);
-							try {
-								onConfigError?.(e);
-							} catch (cbErr) {
-								serverLog.error(`[mcp] onConfigError callback failed:`, cbErr);
-							}
-						}
-					};
-					const applyMerged = (jsonCfg) => {
-						const p = runApply(jsonCfg);
-						this.mcpApplyInFlight.add(p);
-						p.finally(() => this.mcpApplyInFlight.delete(p));
-						return p;
-					};
-					if (mcpConfigPath) {
-						try {
-							const cfg = await loadConfig(mcpConfigPath, process.env);
-							applyMerged(cfg);
-						} catch (err) {
-							if (err.code !== `ENOENT`) throw err;
-							if (extras.length === 0) serverLog.info(`[mcp] no ${mcpConfigPath} — starting with no servers`);
-							else serverLog.info(`[mcp] no ${mcpConfigPath} — starting with ${extras.length} server(s) from extras`);
-							applyMerged(null);
-						}
-						try {
-							this.mcpWatcherCloser = await watchConfig(mcpConfigPath, {
-								onChange: (cfg) => void applyMerged(cfg),
-								onError: (e) => serverLog.error(`[mcp] config error:`, e)
-							});
-						} catch (e) {
-							serverLog.error(`[mcp] config watcher failed to start:`, e);
-						}
-					} else {
-						if (extras.length > 0) serverLog.info(`[mcp] starting with ${extras.length} server(s) from extras`);
-						applyMerged(null);
-					}
-					this.mcpToolProviderName = `mcp`;
-					registerToolProvider({
-						name: `mcp`,
-						tools: () => {
-							const tools = [];
-							for (const entry of mcpRegistry.list()) {
-								if (entry.status !== `ready`) continue;
-								const live = mcpRegistry.get(entry.name);
-								if (!live?.transport) continue;
-								for (const t of entry.tools) tools.push(bridgeMcpTool({
-									server: entry.name,
-									tool: t,
-									client: live.transport.client,
-									timeoutMs: live.config.timeoutMs
-								}));
-								const caps = live.transport.client.getServerCapabilities?.();
-								if (caps?.resources) tools.push(...buildResourceTools({
-									server: entry.name,
-									client: live.transport.client,
-									timeoutMs: live.config.timeoutMs
-								}));
-								if (caps?.prompts) tools.push(...buildPromptTools({
-									server: entry.name,
-									client: live.transport.client,
-									timeoutMs: live.config.timeoutMs
-								}));
-							}
-							return tools;
+			this._mcpRegistry = mcpRegistry;
+			const mcpConfigPath = this.options.loadProjectMcpConfig ? path.resolve(this.options.workingDirectory ?? process.cwd(), `mcp.json`) : null;
+			const extras = this.options.extraMcpServers ?? [];
+			const wirePersistence = async (cfg) => {
+				const servers = [];
+				for (const s of cfg.servers) if (s.transport === `http` && s.auth?.mode === `authorizationCode`) {
+					const persist = await keychainPersistence({ server: s.name });
+					servers.push({
+						...s,
+						auth: {
+							...s.auth,
+							...persist
 						}
 					});
-					this.bootstrap = await createBuiltinAgentHandler({
-						agentServerUrl: this.options.agentServerUrl,
-						serveEndpoint,
-						workingDirectory: this.options.workingDirectory,
-						streamFn: this.options.mockStreamFn,
-						createElectricTools: this.options.createElectricTools,
-						publicUrl,
-						runtimeName: `builtin-agents`
+				} else servers.push(s);
+				return {
+					...cfg,
+					servers
+				};
+			};
+			const merge = (jsonCfg) => {
+				const jsonServers = jsonCfg?.servers ?? [];
+				const jsonNames = new Set(jsonServers.map((s) => s.name));
+				const filteredExtras = extras.filter((s) => !jsonNames.has(s.name));
+				return {
+					servers: [...filteredExtras, ...jsonServers],
+					raw: jsonCfg?.raw
+				};
+			};
+			const onConfigError = this.options.onConfigError;
+			const runApply = async (jsonCfg) => {
+				if (this.mcpStopping) return;
+				try {
+					const wired = await wirePersistence(merge(jsonCfg));
+					if (this.mcpStopping) return;
+					await mcpRegistry.applyConfig(wired);
+				} catch (e) {
+					serverLog.error(`[mcp] applyConfig:`, e);
+					try {
+						onConfigError?.(e);
+					} catch (cbErr) {
+						serverLog.error(`[mcp] onConfigError callback failed:`, cbErr);
+					}
+				}
+			};
+			const applyMerged = (jsonCfg) => {
+				const p = runApply(jsonCfg);
+				this.mcpApplyInFlight.add(p);
+				p.finally(() => this.mcpApplyInFlight.delete(p));
+				return p;
+			};
+			if (mcpConfigPath) {
+				try {
+					const cfg = await loadConfig(mcpConfigPath, process.env);
+					applyMerged(cfg);
+				} catch (err) {
+					if (err.code !== `ENOENT`) throw err;
+					if (extras.length === 0) serverLog.info(`[mcp] no ${mcpConfigPath} — starting with no servers`);
+					else serverLog.info(`[mcp] no ${mcpConfigPath} — starting with ${extras.length} server(s) from extras`);
+					applyMerged(null);
+				}
+				try {
+					this.mcpWatcherCloser = await watchConfig(mcpConfigPath, {
+						onChange: (cfg) => void applyMerged(cfg),
+						onError: (e) => serverLog.error(`[mcp] config error:`, e)
 					});
-					if (!this.bootstrap) throw new Error(`ANTHROPIC_API_KEY or OPENAI_API_KEY must be set before starting builtin agents`);
-					await registerBuiltinAgentTypes(this.bootstrap);
-					serverLog.info(`[builtin-agents] webhook handler listening at ${serveEndpoint}`);
-					resolve(this._url);
-				} catch (error) {
-					await this.stop().catch(() => {});
-					reject(error);
+				} catch (e) {
+					serverLog.error(`[mcp] config watcher failed to start:`, e);
+				}
+			} else {
+				if (extras.length > 0) serverLog.info(`[mcp] starting with ${extras.length} server(s) from extras`);
+				applyMerged(null);
+			}
+			this.mcpToolProviderName = `mcp`;
+			registerToolProvider({
+				name: `mcp`,
+				tools: () => {
+					const tools = [];
+					for (const entry of mcpRegistry.list()) {
+						if (entry.status !== `ready`) continue;
+						const live = mcpRegistry.get(entry.name);
+						if (!live?.transport) continue;
+						for (const t of entry.tools) tools.push(bridgeMcpTool({
+							server: entry.name,
+							tool: t,
+							client: live.transport.client,
+							timeoutMs: live.config.timeoutMs
+						}));
+						const caps = live.transport.client.getServerCapabilities?.();
+						if (caps?.resources) tools.push(...buildResourceTools({
+							server: entry.name,
+							client: live.transport.client,
+							timeoutMs: live.config.timeoutMs
+						}));
+						if (caps?.prompts) tools.push(...buildPromptTools({
+							server: entry.name,
+							client: live.transport.client,
+							timeoutMs: live.config.timeoutMs
+						}));
+					}
+					return tools;
 				}
 			});
-		});
+			this.bootstrap = await createBuiltinAgentHandler({
+				agentServerUrl: this.options.agentServerUrl,
+				workingDirectory: this.options.workingDirectory,
+				streamFn: this.options.mockStreamFn,
+				createElectricTools: this.options.createElectricTools,
+				publicUrl,
+				runtimeName: `builtin-agents`,
+				baseSkillsDir: this.options.baseSkillsDir,
+				serverHeaders: pullWake.headers
+			});
+			if (!this.bootstrap) throw new Error(`ANTHROPIC_API_KEY or OPENAI_API_KEY must be set before starting builtin agents`);
+			await registerBuiltinAgentTypes(this.bootstrap);
+			const registeredRunner = pullWake.registerRunner ? await this.registerPullWakeRunner(pullWake) : null;
+			this.pullWakeRunner = createPullWakeRunner({
+				baseUrl: this.options.agentServerUrl,
+				runnerId: pullWake.runnerId,
+				runtime: this.bootstrap.runtime,
+				headers: pullWake.headers,
+				claimHeaders: pullWake.claimHeaders,
+				claimTokenHeader: pullWake.claimTokenHeader,
+				heartbeatIntervalMs: pullWake.heartbeatIntervalMs,
+				leaseMs: pullWake.leaseMs,
+				offset: registeredRunner?.wake_stream_offset,
+				onError: (error) => {
+					serverLog.error(`[builtin-agents] pull-wake runner failed`, error);
+					return true;
+				}
+			});
+			this.pullWakeRunner.start();
+			serverLog.info(`[builtin-agents] pull-wake runner started: ${pullWake.runnerId}`);
+			return `pull-wake:${pullWake.runnerId}`;
+		} catch (error) {
+			await this.stop().catch(() => {});
+			throw error;
+		}
 	}
 	async stop() {
+		if (this.pullWakeRunner) {
+			await this.pullWakeRunner.stop().catch((e) => {
+				serverLog.error(`[builtin-agents] pull-wake runner stop failed`, e);
+			});
+			this.pullWakeRunner = null;
+		}
 		if (this.bootstrap) {
 			this.bootstrap.runtime.abortWakes();
-			await Promise.race([this.bootstrap.runtime.drainWakes().catch(() => {}), new Promise((resolve) => setTimeout(resolve, 5e3))]);
+			await Promise.race([this.bootstrap.runtime.drainWakes().catch((err) => {
+				serverLog.error(`[builtin-agents] drainWakes failed during shutdown:`, err);
+			}), new Promise((resolve) => setTimeout(resolve, 5e3))]);
 			this.bootstrap = null;
 		}
 		this.mcpStopping = true;
@@ -2173,39 +2173,29 @@ var BuiltinAgentsServer = class {
 			});
 			this._mcpRegistry = null;
 		}
-		if (this.server) {
-			const server = this.server;
-			await new Promise((resolve) => {
-				server.close(() => resolve());
-			});
-			this.server = null;
-		}
 		this.mcpStopping = false;
-		this._url = null;
-		this.publicBaseUrl = null;
 	}
-	async handleRequest(req, res) {
-		const method = req.method?.toUpperCase();
-		const pathname = new URL(req.url ?? `/`, `http://localhost`).pathname;
-		const webhookPath = this.options.webhookPath ?? DEFAULT_BUILTIN_AGENT_HANDLER_PATH;
-		if (pathname === `/_electric/health` && method === `GET`) {
-			res.writeHead(200, { "content-type": `application/json` });
-			res.end(JSON.stringify({ status: `ok` }));
-			return;
-		}
-		if (pathname === 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` }));
+	async registerPullWakeRunner(pullWake) {
+		const headers = new Headers(typeof pullWake.headers === `function` ? await pullWake.headers() : pullWake.headers);
+		headers.set(`content-type`, `application/json`);
+		const response = await fetch(appendPathToUrl(this.options.agentServerUrl, `/_electric/runners`), {
+			method: `POST`,
+			headers,
+			body: JSON.stringify({
+				id: pullWake.runnerId,
+				owner_user_id: pullWake.ownerUserId,
+				label: pullWake.label ?? `Built-in agents`,
+				kind: `local`,
+				admin_status: `enabled`
+			})
+		});
+		if (!response.ok) throw new Error(`Failed to register pull-wake runner ${pullWake.runnerId}: ${response.status} ${await response.text()}`);
+		return await response.json();
 	}
 };
 
 //#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();
@@ -2218,13 +2208,6 @@ function readRequiredEnv(env, names, description) {
 	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);
@@ -2233,20 +2216,55 @@ function validateUrl(name, value) {
 		throw new Error(`Invalid ${name}: "${value}"`);
 	}
 }
+function parseAdditionalServerHeaders(env) {
+	const raw = readEnv(env, [`ELECTRIC_AGENTS_SERVER_HEADERS`]);
+	if (!raw) return void 0;
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		throw new Error(`Invalid ELECTRIC_AGENTS_SERVER_HEADERS: expected JSON`);
+	}
+	if (!parsed || typeof parsed !== `object` || Array.isArray(parsed)) throw new Error(`Invalid ELECTRIC_AGENTS_SERVER_HEADERS: expected a JSON object`);
+	const headers = new Headers();
+	for (const [name, value] of Object.entries(parsed)) {
+		if (typeof value !== `string`) throw new Error(`Invalid ELECTRIC_AGENTS_SERVER_HEADERS: header "${name}" must be a string`);
+		headers.set(name, value);
+	}
+	const normalized = Object.fromEntries(headers.entries());
+	return Object.keys(normalized).length > 0 ? normalized : void 0;
+}
+function mergeHeaders(...sources) {
+	const headers = new Headers();
+	for (const source of sources) {
+		if (!source) continue;
+		new Headers(source).forEach((value, key) => headers.set(key, value));
+	}
+	const merged = Object.fromEntries(headers.entries());
+	return Object.keys(merged).length > 0 ? merged : void 0;
+}
+function hasHeader(headers, name) {
+	return headers ? new Headers(headers).has(name) : false;
+}
 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`]);
+	const runnerId = readRequiredEnv(env, [`ELECTRIC_AGENTS_PULL_WAKE_RUNNER_ID`, `PULL_WAKE_RUNNER_ID`], `pull-wake runner id`);
+	const serverHeaders = mergeHeaders(parseAdditionalServerHeaders(env));
 	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
+		workingDirectory: readEnv(env, [`ELECTRIC_AGENTS_WORKING_DIRECTORY`, `WORKING_DIRECTORY`]) ?? cwd,
+		pullWake: {
+			runnerId,
+			registerRunner: readEnv(env, [`ELECTRIC_AGENTS_REGISTER_PULL_WAKE_RUNNER`]) === `true` || readEnv(env, [`ELECTRIC_AGENTS_REGISTER_PULL_WAKE_RUNNER`]) === `1`,
+			headers: serverHeaders,
+			claimHeaders: serverHeaders,
+			claimTokenHeader: hasHeader(serverHeaders, `authorization`) ? `electric-claim-token` : void 0
+		}
 	};
 }
-async function runBuiltinAgentsEntrypoint({ env = process.env, cwd = process.cwd(), createServer: createServer$1 = (options$1) => new BuiltinAgentsServer(options$1) } = {}) {
+async function runBuiltinAgentsEntrypoint({ env = process.env, cwd = process.cwd(), createServer = (options$1) => new BuiltinAgentsServer(options$1) } = {}) {
 	const options = resolveBuiltinAgentsEntrypointOptions(env, cwd);
-	const server = createServer$1(options);
+	const server = createServer(options);
 	const url = await server.start();
 	return {
 		options,

package/docs/index.md

@@ -60,7 +60,7 @@ The function that runs when an entity wakes. Receives a [`HandlerContext`](/docs
 ```ts
 registry.define("support", {
   async handler(ctx, wake) {
-    if (wake.type === "message_received") {
+    if (wake.type === "inbox") {
       ctx.useAgent({
         systemPrompt: "You are a support agent.",
         model: "claude-sonnet-4-5-20250929",
@@ -78,11 +78,11 @@ Events that trigger a handler invocation. Wake sources include incoming messages
 
 ```ts
 async handler(ctx, wake) {
-  // wake.type — "message_received", "wake", etc.
+  // wake.type — "inbox", "wake", etc.
   // wake.source — who triggered the wake
   // wake.payload — message content or wake data
 
-  if (wake.type === "message_received") {
+  if (wake.type === "inbox") {
     const userMessage = wake.payload
     // handle incoming message
   }

package/docs/reference/built-in-collections.md

@@ -23,7 +23,7 @@ Every entity automatically has these 17 collections, populated by the runtime as
 | `toolCalls`        | `tool_call`        | `ToolCall`         | Tool call lifecycle          |
 | `reasoning`        | `reasoning`        | `Reasoning`        | Reasoning block lifecycle    |
 | `errors`           | `error`            | `ErrorEvent`       | Diagnostic errors            |
-| `inbox`            | `message_received` | `MessageReceived`  | Inbound messages             |
+| `inbox`            | `inbox` | `MessageReceived`  | Inbound messages             |
 | `wakes`            | `wake`             | `WakeEntry`        | Wake delivery records        |
 | `entityCreated`    | `entity_created`   | `EntityCreated`    | Entity bootstrap metadata    |
 | `entityStopped`    | `entity_stopped`   | `EntityStopped`    | Entity shutdown signal       |