@electric-ax/agents 0.4.1 → 0.4.3

package/dist/entrypoint.js

@@ -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;
@@ -1943,7 +1943,7 @@ async function createBuiltinAgentHandler(options) {
 		subscriptionPathForType: (name) => `/${name}/*/main`,
 		defaultDispatchPolicyForType,
 		serverHeaders,
-		idleTimeout: 5e3,
+		idleTimeout: 5 * 6e4,
 		createElectricTools,
 		publicUrl,
 		name: runtimeName ?? `builtin-agents`
@@ -2113,11 +2113,11 @@ var BuiltinAgentsServer = class {
 				claimHeaders: pullWake.claimHeaders,
 				claimTokenHeader: pullWake.claimTokenHeader,
 				heartbeatIntervalMs: pullWake.heartbeatIntervalMs,
+				eventHeartbeatThrottleMs: pullWake.eventHeartbeatThrottleMs,
 				leaseMs: pullWake.leaseMs,
 				offset: registeredRunner?.wake_stream_offset,
 				onError: (error) => {
 					serverLog.error(`[builtin-agents] pull-wake runner failed`, error);
-					return true;
 				}
 			});
 			this.pullWakeRunner.start();
@@ -2172,7 +2172,7 @@ var BuiltinAgentsServer = class {
 			headers,
 			body: JSON.stringify({
 				id: pullWake.runnerId,
-				owner_user_id: pullWake.ownerUserId,
+				owner_principal: pullWake.ownerPrincipal,
 				label: pullWake.label ?? `Built-in agents`,
 				kind: `local`,
 				admin_status: `enabled`
@@ -2183,6 +2183,17 @@ var BuiltinAgentsServer = class {
 	}
 };
 
+//#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) {
@@ -2238,7 +2249,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(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"));
@@ -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;
@@ -1968,7 +1969,7 @@ async function createBuiltinAgentHandler(options) {
 		subscriptionPathForType: (name) => `/${name}/*/main`,
 		defaultDispatchPolicyForType,
 		serverHeaders,
-		idleTimeout: 5e3,
+		idleTimeout: 5 * 6e4,
 		createElectricTools,
 		publicUrl,
 		name: runtimeName ?? `builtin-agents`
@@ -2148,11 +2149,11 @@ var BuiltinAgentsServer = class {
 				claimHeaders: pullWake.claimHeaders,
 				claimTokenHeader: pullWake.claimTokenHeader,
 				heartbeatIntervalMs: pullWake.heartbeatIntervalMs,
+				eventHeartbeatThrottleMs: pullWake.eventHeartbeatThrottleMs,
 				leaseMs: pullWake.leaseMs,
 				offset: registeredRunner?.wake_stream_offset,
 				onError: (error) => {
 					serverLog.error(`[builtin-agents] pull-wake runner failed`, error);
-					return true;
 				}
 			});
 			this.pullWakeRunner.start();
@@ -2207,7 +2208,7 @@ var BuiltinAgentsServer = class {
 			headers,
 			body: JSON.stringify({
 				id: pullWake.runnerId,
-				owner_user_id: pullWake.ownerUserId,
+				owner_principal: pullWake.ownerPrincipal,
 				label: pullWake.label ?? `Built-in agents`,
 				kind: `local`,
 				admin_status: `enabled`
@@ -2273,7 +2274,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(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

@@ -94,13 +94,14 @@ interface BuiltinAgentsServerOptions {
   /** Pull-wake runner configuration for built-in agents. */
   pullWake: {
     runnerId: string;
-    ownerUserId?: string;
+    ownerPrincipal?: string;
     label?: string;
     registerRunner?: boolean;
     headers?: PullWakeRunnerConfig[`headers`];
     claimHeaders?: PullWakeRunnerConfig[`claimHeaders`];
     claimTokenHeader?: PullWakeRunnerConfig[`claimTokenHeader`];
     heartbeatIntervalMs?: PullWakeRunnerConfig[`heartbeatIntervalMs`];
+    eventHeartbeatThrottleMs?: PullWakeRunnerConfig[`eventHeartbeatThrottleMs`];
     leaseMs?: PullWakeRunnerConfig[`leaseMs`];
   };
   /** Invoked when an `authorizationCode` server needs user consent. */

package/dist/index.d.ts

@@ -94,13 +94,14 @@ interface BuiltinAgentsServerOptions {
   /** Pull-wake runner configuration for built-in agents. */
   pullWake: {
     runnerId: string;
-    ownerUserId?: string;
+    ownerPrincipal?: string;
     label?: string;
     registerRunner?: boolean;
     headers?: PullWakeRunnerConfig[`headers`];
     claimHeaders?: PullWakeRunnerConfig[`claimHeaders`];
     claimTokenHeader?: PullWakeRunnerConfig[`claimTokenHeader`];
     heartbeatIntervalMs?: PullWakeRunnerConfig[`heartbeatIntervalMs`];
+    eventHeartbeatThrottleMs?: PullWakeRunnerConfig[`eventHeartbeatThrottleMs`];
     leaseMs?: PullWakeRunnerConfig[`leaseMs`];
   };
   /** Invoked when an `authorizationCode` server needs user consent. */

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";
@@ -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;
@@ -1944,7 +1945,7 @@ async function createBuiltinAgentHandler(options) {
 		subscriptionPathForType: (name) => `/${name}/*/main`,
 		defaultDispatchPolicyForType,
 		serverHeaders,
-		idleTimeout: 5e3,
+		idleTimeout: 5 * 6e4,
 		createElectricTools,
 		publicUrl,
 		name: runtimeName ?? `builtin-agents`
@@ -2124,11 +2125,11 @@ var BuiltinAgentsServer = class {
 				claimHeaders: pullWake.claimHeaders,
 				claimTokenHeader: pullWake.claimTokenHeader,
 				heartbeatIntervalMs: pullWake.heartbeatIntervalMs,
+				eventHeartbeatThrottleMs: pullWake.eventHeartbeatThrottleMs,
 				leaseMs: pullWake.leaseMs,
 				offset: registeredRunner?.wake_stream_offset,
 				onError: (error) => {
 					serverLog.error(`[builtin-agents] pull-wake runner failed`, error);
-					return true;
 				}
 			});
 			this.pullWakeRunner.start();
@@ -2183,7 +2184,7 @@ var BuiltinAgentsServer = class {
 			headers,
 			body: JSON.stringify({
 				id: pullWake.runnerId,
-				owner_user_id: pullWake.ownerUserId,
+				owner_principal: pullWake.ownerPrincipal,
 				label: pullWake.label ?? `Built-in agents`,
 				kind: `local`,
 				admin_status: `enabled`
@@ -2249,7 +2250,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(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/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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@electric-ax/agents",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "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": {
@@ -39,7 +49,7 @@
     "sqlite-vec": "^0.1.9",
     "zod": "^4.3.6",
     "@electric-ax/agents-mcp": "0.2.2",
-    "@electric-ax/agents-runtime": "0.2.1"
+    "@electric-ax/agents-runtime": "0.2.2"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",