@electric-ax/agents 0.4.0 → 0.4.2

package/dist/entrypoint.js

@@ -625,8 +625,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();
@@ -885,11 +885,11 @@ function createSpawnWorkerTool(ctx, modelConfig) {
 	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.`,
+		description: `Dispatch a subagent (worker) to perform an isolated subtask. Provide a brief system prompt to give it its role and then a detailed initialMessage which 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.` }),
+			systemPrompt: Type.String({ description: `System prompt for the worker.` }),
 			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.` })
+			initialMessage: Type.String({ description: `First user message sent to the worker. Be concrete: include file paths, line numbers, and the form of answer you want back. This is what kicks off its run — without it the worker will idle. Describe the concrete task to perform and what form of message you want back.` })
 		}),
 		execute: async (_toolCallId, params) => {
 			const { systemPrompt, tools, initialMessage } = params;
@@ -1426,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) => {
@@ -1902,7 +1903,7 @@ function truncate(str, max) {
 //#endregion
 //#region src/bootstrap.ts
 async function createBuiltinAgentHandler(options) {
-	const { agentServerUrl, serveEndpoint, workingDirectory, streamFn, createElectricTools, publicUrl, runtimeName, serverHeaders, defaultDispatchPolicyForType } = 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`);
@@ -1910,7 +1911,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({
@@ -1962,6 +1963,19 @@ async function registerBuiltinAgentTypes(bootstrap) {
 
 //#endregion
 //#region src/server.ts
+const PRINCIPAL_KEY_PREFIXES = new Set([
+	`user`,
+	`agent`,
+	`service`,
+	`system`
+]);
+function normalizeOwnerUserId(ownerUserId) {
+	const trimmed = ownerUserId?.trim();
+	if (!trimmed) return void 0;
+	const colon = trimmed.indexOf(`:`);
+	if (colon > 0 && PRINCIPAL_KEY_PREFIXES.has(trimmed.slice(0, colon))) return trimmed;
+	return `user:${trimmed}`;
+}
 var BuiltinAgentsServer = class {
 	bootstrap = null;
 	_mcpRegistry = null;
@@ -2098,6 +2112,7 @@ var BuiltinAgentsServer = class {
 				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`);
@@ -2165,22 +2180,35 @@ var BuiltinAgentsServer = class {
 	async registerPullWakeRunner(pullWake) {
 		const headers = new Headers(typeof pullWake.headers === `function` ? await pullWake.headers() : pullWake.headers);
 		headers.set(`content-type`, `application/json`);
+		const ownerUserId = normalizeOwnerUserId(pullWake.ownerUserId);
+		const body = {
+			id: pullWake.runnerId,
+			label: pullWake.label ?? `Built-in agents`,
+			kind: `local`,
+			admin_status: `enabled`
+		};
+		if (ownerUserId) body.owner_user_id = ownerUserId;
 		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`
-			})
+			body: JSON.stringify(body)
 		});
 		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/server-headers.ts
+const ELECTRIC_PRINCIPAL_HEADER = `electric-principal`;
+function mergeElectricPrincipalHeader(headers, principal) {
+	const merged = new Headers(headers);
+	const trimmedPrincipal = principal?.trim();
+	if (trimmedPrincipal !== void 0 && trimmedPrincipal.length > 0) merged.set(ELECTRIC_PRINCIPAL_HEADER, trimmedPrincipal);
+	const normalized = Object.fromEntries(merged.entries());
+	return Object.keys(normalized).length > 0 ? normalized : void 0;
+}
+
 //#endregion
 //#region src/entrypoint-lib.ts
 function readEnv(env, names) {
@@ -2203,14 +2231,6 @@ function validateUrl(name, value) {
 		throw new Error(`Invalid ${name}: "${value}"`);
 	}
 }
-function buildAssertedAuthHeaders(env) {
-	const headers = {};
-	const email = readEnv(env, [`ELECTRIC_ASSERTED_AUTH_EMAIL`]);
-	const name = readEnv(env, [`ELECTRIC_ASSERTED_AUTH_NAME`]);
-	if (email) headers[`X-Electric-Asserted-Email`] = email;
-	if (name) headers[`X-Electric-Asserted-Name`] = name;
-	return Object.keys(headers).length > 0 ? headers : void 0;
-}
 function parseAdditionalServerHeaders(env) {
 	const raw = readEnv(env, [`ELECTRIC_AGENTS_SERVER_HEADERS`]);
 	if (!raw) return void 0;
@@ -2244,7 +2264,7 @@ function hasHeader(headers, name) {
 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 runnerId = readRequiredEnv(env, [`ELECTRIC_AGENTS_PULL_WAKE_RUNNER_ID`, `PULL_WAKE_RUNNER_ID`], `pull-wake runner id`);
-	const serverHeaders = mergeHeaders(buildAssertedAuthHeaders(env), parseAdditionalServerHeaders(env));
+	const serverHeaders = mergeHeaders(mergeElectricPrincipalHeader(parseAdditionalServerHeaders(env), readEnv(env, [`ELECTRIC_AGENTS_PRINCIPAL`])));
 	return {
 		agentServerUrl,
 		workingDirectory: readEnv(env, [`ELECTRIC_AGENTS_WORKING_DIRECTORY`, `WORKING_DIRECTORY`]) ?? cwd,

package/dist/index.cjs

@@ -22,6 +22,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 }) : target, mod));
 
 //#endregion
+const require_server_headers = require('./server-headers-65vIhxvJ.cjs');
 const node_path = __toESM(require("node:path"));
 const node_url = __toESM(require("node:url"));
 const __electric_ax_agents_runtime = __toESM(require("@electric-ax/agents-runtime"));
@@ -648,8 +649,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();
@@ -908,11 +909,11 @@ function createSpawnWorkerTool(ctx, modelConfig) {
 	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.`,
+		description: `Dispatch a subagent (worker) to perform an isolated subtask. Provide a brief system prompt to give it its role and then a detailed initialMessage which 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: __sinclair_typebox.Type.Object({
-			systemPrompt: __sinclair_typebox.Type.String({ description: `System prompt for the worker. Be concrete: include file paths, line numbers, and the form of answer you want back.` }),
+			systemPrompt: __sinclair_typebox.Type.String({ description: `System prompt for the worker.` }),
 			tools: __sinclair_typebox.Type.Array(__sinclair_typebox.Type.Union(WORKER_TOOL_NAMES.map((n) => __sinclair_typebox.Type.Literal(n))), { description: `Subset of tool names to enable for the worker. Must include at least one.` }),
-			initialMessage: __sinclair_typebox.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.` })
+			initialMessage: __sinclair_typebox.Type.String({ description: `First user message sent to the worker. Be concrete: include file paths, line numbers, and the form of answer you want back. This is what kicks off its run — without it the worker will idle. Describe the concrete task to perform and what form of message you want back.` })
 		}),
 		execute: async (_toolCallId, params) => {
 			const { systemPrompt, tools, initialMessage } = params;
@@ -1450,7 +1451,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) => {
@@ -1927,7 +1929,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, workingDirectory, streamFn, createElectricTools, publicUrl, runtimeName, serverHeaders, defaultDispatchPolicyForType } = 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`);
@@ -1935,7 +1937,7 @@ async function createBuiltinAgentHandler(options) {
 	}
 	const cwd = workingDirectory ?? process.cwd();
 	const here = node_path.default.dirname((0, node_url.fileURLToPath)(require("url").pathToFileURL(__filename).href));
-	const baseSkillsDir = node_path.default.resolve(here, `../skills`);
+	const baseSkillsDir = baseSkillsDirOverride ?? node_path.default.resolve(here, `../skills`);
 	let skillsRegistry = null;
 	try {
 		skillsRegistry = await createSkillsRegistry({
@@ -1997,6 +1999,19 @@ const registerAgentTypes = registerBuiltinAgentTypes;
 
 //#endregion
 //#region src/server.ts
+const PRINCIPAL_KEY_PREFIXES = new Set([
+	`user`,
+	`agent`,
+	`service`,
+	`system`
+]);
+function normalizeOwnerUserId(ownerUserId) {
+	const trimmed = ownerUserId?.trim();
+	if (!trimmed) return void 0;
+	const colon = trimmed.indexOf(`:`);
+	if (colon > 0 && PRINCIPAL_KEY_PREFIXES.has(trimmed.slice(0, colon))) return trimmed;
+	return `user:${trimmed}`;
+}
 var BuiltinAgentsServer = class {
 	bootstrap = null;
 	_mcpRegistry = null;
@@ -2133,6 +2148,7 @@ var BuiltinAgentsServer = class {
 				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`);
@@ -2200,16 +2216,18 @@ var BuiltinAgentsServer = class {
 	async registerPullWakeRunner(pullWake) {
 		const headers = new Headers(typeof pullWake.headers === `function` ? await pullWake.headers() : pullWake.headers);
 		headers.set(`content-type`, `application/json`);
+		const ownerUserId = normalizeOwnerUserId(pullWake.ownerUserId);
+		const body = {
+			id: pullWake.runnerId,
+			label: pullWake.label ?? `Built-in agents`,
+			kind: `local`,
+			admin_status: `enabled`
+		};
+		if (ownerUserId) body.owner_user_id = ownerUserId;
 		const response = await fetch((0, __electric_ax_agents_runtime.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`
-			})
+			body: JSON.stringify(body)
 		});
 		if (!response.ok) throw new Error(`Failed to register pull-wake runner ${pullWake.runnerId}: ${response.status} ${await response.text()}`);
 		return await response.json();
@@ -2238,14 +2256,6 @@ function validateUrl(name, value) {
 		throw new Error(`Invalid ${name}: "${value}"`);
 	}
 }
-function buildAssertedAuthHeaders(env) {
-	const headers = {};
-	const email = readEnv(env, [`ELECTRIC_ASSERTED_AUTH_EMAIL`]);
-	const name = readEnv(env, [`ELECTRIC_ASSERTED_AUTH_NAME`]);
-	if (email) headers[`X-Electric-Asserted-Email`] = email;
-	if (name) headers[`X-Electric-Asserted-Name`] = name;
-	return Object.keys(headers).length > 0 ? headers : void 0;
-}
 function parseAdditionalServerHeaders(env) {
 	const raw = readEnv(env, [`ELECTRIC_AGENTS_SERVER_HEADERS`]);
 	if (!raw) return void 0;
@@ -2279,7 +2289,7 @@ function hasHeader(headers, name) {
 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 runnerId = readRequiredEnv(env, [`ELECTRIC_AGENTS_PULL_WAKE_RUNNER_ID`, `PULL_WAKE_RUNNER_ID`], `pull-wake runner id`);
-	const serverHeaders = mergeHeaders(buildAssertedAuthHeaders(env), parseAdditionalServerHeaders(env));
+	const serverHeaders = mergeHeaders(require_server_headers.mergeElectricPrincipalHeader(parseAdditionalServerHeaders(env), readEnv(env, [`ELECTRIC_AGENTS_PRINCIPAL`])));
 	return {
 		agentServerUrl,
 		workingDirectory: readEnv(env, [`ELECTRIC_AGENTS_WORKING_DIRECTORY`, `WORKING_DIRECTORY`]) ?? cwd,

package/dist/index.d.cts

@@ -43,6 +43,8 @@ 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: {
@@ -125,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;

package/dist/index.d.ts

@@ -43,6 +43,8 @@ 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: {
@@ -125,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;

package/dist/index.js

@@ -1,3 +1,4 @@
+import { mergeElectricPrincipalHeader } from "./server-headers-KD5yHFYT.js";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { appendPathToUrl, completeWithLowCostModel, createEntityRegistry, createPullWakeRunner, createRuntimeHandler, db, detectAvailableProviders, readCodexAccessToken, registerToolProvider, unregisterToolProvider } from "@electric-ax/agents-runtime";
@@ -624,8 +625,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();
@@ -884,11 +885,11 @@ function createSpawnWorkerTool(ctx, modelConfig) {
 	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.`,
+		description: `Dispatch a subagent (worker) to perform an isolated subtask. Provide a brief system prompt to give it its role and then a detailed initialMessage which 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.` }),
+			systemPrompt: Type.String({ description: `System prompt for the worker.` }),
 			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.` })
+			initialMessage: Type.String({ description: `First user message sent to the worker. Be concrete: include file paths, line numbers, and the form of answer you want back. This is what kicks off its run — without it the worker will idle. Describe the concrete task to perform and what form of message you want back.` })
 		}),
 		execute: async (_toolCallId, params) => {
 			const { systemPrompt, tools, initialMessage } = params;
@@ -1426,7 +1427,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) => {
@@ -1903,7 +1905,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, workingDirectory, streamFn, createElectricTools, publicUrl, runtimeName, serverHeaders, defaultDispatchPolicyForType } = 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`);
@@ -1911,7 +1913,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({
@@ -1973,6 +1975,19 @@ const registerAgentTypes = registerBuiltinAgentTypes;
 
 //#endregion
 //#region src/server.ts
+const PRINCIPAL_KEY_PREFIXES = new Set([
+	`user`,
+	`agent`,
+	`service`,
+	`system`
+]);
+function normalizeOwnerUserId(ownerUserId) {
+	const trimmed = ownerUserId?.trim();
+	if (!trimmed) return void 0;
+	const colon = trimmed.indexOf(`:`);
+	if (colon > 0 && PRINCIPAL_KEY_PREFIXES.has(trimmed.slice(0, colon))) return trimmed;
+	return `user:${trimmed}`;
+}
 var BuiltinAgentsServer = class {
 	bootstrap = null;
 	_mcpRegistry = null;
@@ -2109,6 +2124,7 @@ var BuiltinAgentsServer = class {
 				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`);
@@ -2176,16 +2192,18 @@ var BuiltinAgentsServer = class {
 	async registerPullWakeRunner(pullWake) {
 		const headers = new Headers(typeof pullWake.headers === `function` ? await pullWake.headers() : pullWake.headers);
 		headers.set(`content-type`, `application/json`);
+		const ownerUserId = normalizeOwnerUserId(pullWake.ownerUserId);
+		const body = {
+			id: pullWake.runnerId,
+			label: pullWake.label ?? `Built-in agents`,
+			kind: `local`,
+			admin_status: `enabled`
+		};
+		if (ownerUserId) body.owner_user_id = ownerUserId;
 		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`
-			})
+			body: JSON.stringify(body)
 		});
 		if (!response.ok) throw new Error(`Failed to register pull-wake runner ${pullWake.runnerId}: ${response.status} ${await response.text()}`);
 		return await response.json();
@@ -2214,14 +2232,6 @@ function validateUrl(name, value) {
 		throw new Error(`Invalid ${name}: "${value}"`);
 	}
 }
-function buildAssertedAuthHeaders(env) {
-	const headers = {};
-	const email = readEnv(env, [`ELECTRIC_ASSERTED_AUTH_EMAIL`]);
-	const name = readEnv(env, [`ELECTRIC_ASSERTED_AUTH_NAME`]);
-	if (email) headers[`X-Electric-Asserted-Email`] = email;
-	if (name) headers[`X-Electric-Asserted-Name`] = name;
-	return Object.keys(headers).length > 0 ? headers : void 0;
-}
 function parseAdditionalServerHeaders(env) {
 	const raw = readEnv(env, [`ELECTRIC_AGENTS_SERVER_HEADERS`]);
 	if (!raw) return void 0;
@@ -2255,7 +2265,7 @@ function hasHeader(headers, name) {
 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 runnerId = readRequiredEnv(env, [`ELECTRIC_AGENTS_PULL_WAKE_RUNNER_ID`, `PULL_WAKE_RUNNER_ID`], `pull-wake runner id`);
-	const serverHeaders = mergeHeaders(buildAssertedAuthHeaders(env), parseAdditionalServerHeaders(env));
+	const serverHeaders = mergeHeaders(mergeElectricPrincipalHeader(parseAdditionalServerHeaders(env), readEnv(env, [`ELECTRIC_AGENTS_PRINCIPAL`])));
 	return {
 		agentServerUrl,
 		workingDirectory: readEnv(env, [`ELECTRIC_AGENTS_WORKING_DIRECTORY`, `WORKING_DIRECTORY`]) ?? cwd,

package/dist/server-headers-65vIhxvJ.cjs

@@ -0,0 +1,25 @@
+"use strict";
+
+//#region src/server-headers.ts
+const ELECTRIC_PRINCIPAL_HEADER = `electric-principal`;
+function mergeElectricPrincipalHeader(headers, principal) {
+	const merged = new Headers(headers);
+	const trimmedPrincipal = principal?.trim();
+	if (trimmedPrincipal !== void 0 && trimmedPrincipal.length > 0) merged.set(ELECTRIC_PRINCIPAL_HEADER, trimmedPrincipal);
+	const normalized = Object.fromEntries(merged.entries());
+	return Object.keys(normalized).length > 0 ? normalized : void 0;
+}
+
+//#endregion
+Object.defineProperty(exports, 'ELECTRIC_PRINCIPAL_HEADER', {
+  enumerable: true,
+  get: function () {
+    return ELECTRIC_PRINCIPAL_HEADER;
+  }
+});
+Object.defineProperty(exports, 'mergeElectricPrincipalHeader', {
+  enumerable: true,
+  get: function () {
+    return mergeElectricPrincipalHeader;
+  }
+});

package/dist/server-headers-KD5yHFYT.js

@@ -0,0 +1,12 @@
+//#region src/server-headers.ts
+const ELECTRIC_PRINCIPAL_HEADER = `electric-principal`;
+function mergeElectricPrincipalHeader(headers, principal) {
+	const merged = new Headers(headers);
+	const trimmedPrincipal = principal?.trim();
+	if (trimmedPrincipal !== void 0 && trimmedPrincipal.length > 0) merged.set(ELECTRIC_PRINCIPAL_HEADER, trimmedPrincipal);
+	const normalized = Object.fromEntries(merged.entries());
+	return Object.keys(normalized).length > 0 ? normalized : void 0;
+}
+
+//#endregion
+export { ELECTRIC_PRINCIPAL_HEADER, mergeElectricPrincipalHeader };

package/dist/server-headers.cjs

@@ -0,0 +1,4 @@
+const require_server_headers = require('./server-headers-65vIhxvJ.cjs');
+
+exports.ELECTRIC_PRINCIPAL_HEADER = require_server_headers.ELECTRIC_PRINCIPAL_HEADER
+exports.mergeElectricPrincipalHeader = require_server_headers.mergeElectricPrincipalHeader

package/dist/server-headers.d.cts

@@ -0,0 +1,6 @@
+//#region src/server-headers.d.ts
+declare const ELECTRIC_PRINCIPAL_HEADER = "electric-principal";
+declare function mergeElectricPrincipalHeader(headers: HeadersInit | undefined, principal: string | undefined): Record<string, string> | undefined;
+
+//#endregion
+export { ELECTRIC_PRINCIPAL_HEADER, mergeElectricPrincipalHeader };

package/dist/server-headers.d.ts

@@ -0,0 +1,6 @@
+//#region src/server-headers.d.ts
+declare const ELECTRIC_PRINCIPAL_HEADER = "electric-principal";
+declare function mergeElectricPrincipalHeader(headers: HeadersInit | undefined, principal: string | undefined): Record<string, string> | undefined;
+
+//#endregion
+export { ELECTRIC_PRINCIPAL_HEADER, mergeElectricPrincipalHeader };

package/dist/server-headers.js

@@ -0,0 +1,3 @@
+import { ELECTRIC_PRINCIPAL_HEADER, mergeElectricPrincipalHeader } from "./server-headers-KD5yHFYT.js";
+
+export { ELECTRIC_PRINCIPAL_HEADER, mergeElectricPrincipalHeader };

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       |

package/docs/reference/cli.md

@@ -20,6 +20,8 @@ npm install -g electric-ax
 | -------------------------------- | ----------------------- | -------------------------------------------- |
 | `ELECTRIC_AGENTS_URL`            | `http://localhost:4437` | Server URL for entity commands and built-ins |
 | `ELECTRIC_AGENTS_IDENTITY`       | `user@hostname`         | Sender identity for messages                 |
+| `ELECTRIC_AGENTS_PRINCIPAL`      | -                       | Optional principal key sent as `Electric-Principal` |
+| `ELECTRIC_AGENTS_SERVER_HEADERS` | -                       | Optional JSON object of additional server headers |
 | `ELECTRIC_AGENTS_PORT`           | `4437`                  | Port used by `start` / `quickstart`          |
 | `ELECTRIC_AGENTS_BUILTIN_PORT`   | `4448`                  | Webhook port for `start-builtin`             |
 | `ELECTRIC_AGENTS_COMPOSE_PROJECT` | `electric-agents`       | Docker Compose project name                  |

package/docs/reference/wake-event.md

@@ -30,7 +30,7 @@ type WakeEvent = {
 | Field        | Type      | Description                                                              |
 | ------------ | --------- | ------------------------------------------------------------------------ |
 | `source`     | `string`  | URL or identifier of the stream that triggered the wake.                 |
-| `type`       | `string`  | Wake type. Usually `"message_received"` or `"wake"`; fallback webhook events can use `triggerEvent` or `"message"`. See catalog. |
+| `type`       | `string`  | Wake type. Usually `"inbox"` or `"wake"`; fallback webhook events can use `triggerEvent` or `"message"`. See catalog. |
 | `fromOffset` | `number`  | Start offset of new events in the source stream.                         |
 | `toOffset`   | `number`  | End offset (exclusive) of new events.                                    |
 | `eventCount` | `number`  | Number of new events in this wake.                                       |
@@ -40,9 +40,9 @@ type WakeEvent = {
 
 ## Wake-type catalog
 
-Handlers usually see two values for `wake.type`. Direct inbox messages arrive as `"message_received"`. Most non-message triggers are flattened into `"wake"`, with the specifics carried on `wake.payload`. Low-level webhook fallbacks can surface `triggerEvent` directly, or `"message"` when no trigger event is provided.
+Handlers usually see two values for `wake.type`. Direct inbox messages arrive as `"inbox"`. Most non-message triggers are flattened into `"wake"`, with the specifics carried on `wake.payload`. Low-level webhook fallbacks can surface `triggerEvent` directly, or `"message"` when no trigger event is provided.
 
-### `"message_received"`
+### `"inbox"`
 
 An external message landed in the entity's inbox — from `ctx.send()`, the CLI's `electric agents send`, or any direct `/send` HTTP call.
 
@@ -89,7 +89,7 @@ Inspect the payload to distinguish the sub-kind:
 | Observed change     | `ctx.observe(..., { wake: { on: 'change' } })` or `observe(db(...))`        | `payload.changes` is non-empty                                                            |
 | Shared-state change | `await ctx.observe(db(...), { wake: { on: 'change' } })`                    | `payload.changes` is non-empty, `payload.source` identifies the shared-state stream       |
 | Cron fired          | A cron schedule entry on the entity's manifest                              | `payload.source` identifies the schedule; `payload.changes` is empty                      |
-| Scheduled send      | A `future_send` schedule fires                                              | Arrives as `"message_received"` (not `"wake"`) — the schedule produces a message delivery |
+| Scheduled send      | A `future_send` schedule fires                                              | Arrives as `"inbox"` (not `"wake"`) — the schedule produces a message delivery |
 | Timeout             | `timeoutMs` on a `change` wake config elapsed with no changes               | `payload.timeout === true`, `payload.changes` is empty                                    |
 
 For the narrative on how these are produced, see [Waking entities](../usage/waking-entities).

package/docs/usage/embedded-builtins.md

@@ -168,6 +168,8 @@ Environment variables:
 | Variable                         | Description                                           |
 | -------------------------------- | ----------------------------------------------------- |
 | `ELECTRIC_AGENTS_SERVER_URL`     | Required coordinator server URL.                      |
+| `ELECTRIC_AGENTS_PRINCIPAL`      | Optional principal key sent as `Electric-Principal`.  |
+| `ELECTRIC_AGENTS_SERVER_HEADERS` | Optional JSON object of additional server headers.    |
 | `ELECTRIC_AGENTS_BUILTIN_BASE_URL` | Public webhook base URL for the built-in server.   |
 | `ELECTRIC_AGENTS_BUILTIN_HOST`   | Bind host.                                            |
 | `ELECTRIC_AGENTS_BUILTIN_PORT`   | Built-in server port. Defaults to `4448`.             |

package/docs/usage/spawning-and-coordinating.md

@@ -129,7 +129,7 @@ async handler(ctx) {
 
   const analyst = await ctx.observe(entity("/worker/analyst"))
 
-  if (wake.type === "message_received") {
+  if (wake.type === "inbox") {
     analyst.send(wake.payload)
   }
 }

package/docs/usage/waking-entities.md

@@ -31,13 +31,13 @@ There are five things that can wake an entity:
 
 ### 1. An incoming message
 
-Any external `/send` (via the CLI, HTTP, or another entity's `ctx.send()`) appends a `message_received` event to the entity's stream, which wakes the handler:
+Any external `/send` (via the CLI, HTTP, or another entity's `ctx.send()`) appends a `inbox` event to the entity's stream, which wakes the handler:
 
 ```ts
 ctx.send("/assistant/peer", { text: "hello" })
 ```
 
-The receiving handler sees `wake.type === "message_received"` and finds the payload on `wake.payload`.
+The receiving handler sees `wake.type === "inbox"` and finds the payload on `wake.payload`.
 
 ### 2. A spawned child
 
@@ -97,7 +97,7 @@ The minimum useful pattern is to branch on `wake.type`:
 
 ```ts
 async handler(ctx, wake) {
-  if (wake.type === "message_received") {
+  if (wake.type === "inbox") {
     // external input - reply, dispatch, etc.
     ctx.useAgent({ ... })
     await ctx.agent.run()
@@ -112,8 +112,8 @@ async handler(ctx, wake) {
 
 Two wake types reach handlers directly:
 
-- `"message_received"` — an external message was delivered to this entity's inbox.
-- `"wake"` — a synthesised wake for anything else (child finished, collection change, cron, timeout). The specifics are on `wake.payload`. A future-send schedule delivers a message, so it arrives as `"message_received"`.
+- `"inbox"` — an external message was delivered to this entity's inbox.
+- `"wake"` — a synthesised wake for anything else (child finished, collection change, cron, timeout). The specifics are on `wake.payload`. A future-send schedule delivers a message, so it arrives as `"inbox"`.
 
 For the full payload shape (`changes[]`, `finished_child`, `other_children`, `timeout`), see the [wake-type catalog](../reference/wake-event#wake-type-catalog) in the reference.
 

package/docs/usage/writing-handlers.md

@@ -120,7 +120,7 @@ type WakeEvent = {
 | Field        | Description                                                    |
 | ------------ | -------------------------------------------------------------- |
 | `source`     | The stream or entity that caused the wake.                     |
-| `type`       | The wake type: `"message_received"` for inbox messages or `"wake"` for child completion, observed changes, cron, and timeouts. |
+| `type`       | The wake type: `"inbox"` for inbox messages or `"wake"` for child completion, observed changes, cron, and timeouts. |
 | `fromOffset` | Start offset of the events that triggered this wake.           |
 | `toOffset`   | End offset of the events that triggered this wake.             |
 | `eventCount` | Number of new events since last wake.                          |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@electric-ax/agents",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Built-in Electric Agents runtimes such as Horton and worker",
   "repository": {
     "type": "git",
@@ -25,6 +25,16 @@
         "default": "./dist/index.cjs"
       }
     },
+    "./server-headers": {
+      "import": {
+        "types": "./dist/server-headers.d.ts",
+        "default": "./dist/server-headers.js"
+      },
+      "require": {
+        "types": "./dist/server-headers.d.cts",
+        "default": "./dist/server-headers.cjs"
+      }
+    },
     "./package.json": "./package.json"
   },
   "dependencies": {
@@ -32,14 +42,14 @@
     "@mariozechner/pi-agent-core": "^0.70.2",
     "@mariozechner/pi-ai": "^0.70.2",
     "@sinclair/typebox": "^0.34.48",
-    "better-sqlite3": "^11.10.0",
+    "better-sqlite3": "^12.9.0",
     "nanoid": "^3.3.11",
     "pino": "^10.3.1",
     "pino-pretty": "^13.0.0",
     "sqlite-vec": "^0.1.9",
     "zod": "^4.3.6",
-    "@electric-ax/agents-mcp": "0.2.1",
-    "@electric-ax/agents-runtime": "0.2.0"
+    "@electric-ax/agents-mcp": "0.2.2",
+    "@electric-ax/agents-runtime": "0.2.1"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",