electric-ax 0.2.1 → 0.2.3

package/dist/completions.d.cts

@@ -1,4 +1,4 @@
-import { ElectricCliEnv } from "./index-cwCTPq6Y.cjs";
+import { ElectricCliEnv } from "./index-OgX1QS9Q.cjs";
 
 //#region src/completions.d.ts
 declare function fetchEntityTypeNames(env: ElectricCliEnv): Promise<Array<string>>;

package/dist/completions.d.ts

@@ -1,4 +1,4 @@
-import { ElectricCliEnv } from "./index-BSHO_Rei.js";
+import { ElectricCliEnv } from "./index-CwRI9tWl.js";
 
 //#region src/completions.d.ts
 declare function fetchEntityTypeNames(env: ElectricCliEnv): Promise<Array<string>>;

package/dist/{index-BSHO_Rei.d.ts → index-CwRI9tWl.d.ts}

@@ -34,7 +34,7 @@ declare function getStartedEnvironmentMessage(started: StartedDevEnvironment): s
 declare function getStoppedEnvironmentMessage(stopped: StoppedDevEnvironment): string;
 declare function getStartedBuiltinAgentsMessage(started: StartedBuiltinAgentsEnvironment): string;
 declare function resolvePullWakeRunnerId(env?: NodeJS.ProcessEnv, fileEnv?: Record<string, string>): string;
-declare function resolvePullWakeOwnerId(env?: NodeJS.ProcessEnv, fileEnv?: Record<string, string>): string;
+declare function resolvePullWakeOwnerPrincipal(env?: NodeJS.ProcessEnv, fileEnv?: Record<string, string>): string;
 declare function resolveComposeProjectName(_cwd?: string, env?: NodeJS.ProcessEnv): string;
 declare function waitForElectricAgentsServer(baseUrl: string, options?: WaitForServerOptions): Promise<void>;
 declare function startElectricAgentsDevEnvironment(_options?: StartCommandOptions, env?: NodeJS.ProcessEnv, cwd?: string): Promise<StartedDevEnvironment>;
@@ -125,4 +125,4 @@ declare function createElectricProgram({
 declare function run(argv?: Array<string>): Promise<void>;
 
 //#endregion
-export { DEFAULT_ELECTRIC_AGENTS_URL, ElectricCliEnv, ElectricCliHandlers, ObserveCommandOptions, PsCommandOptions, SendCommandOptions, SpawnCommandOptions, StartBuiltinCommandOptions, StartCommandOptions, StartedBuiltinAgentsEnvironment, StartedDevEnvironment, StopCommandOptions, StoppedDevEnvironment, createElectricCliHandlers, createElectricProgram, formatQuickstartBackendStartedMessage, getElectricCliEnv, getStartedBuiltinAgentsMessage, getStartedEnvironmentMessage, getStoppedEnvironmentMessage, readDotEnvFile, resolveAnthropicApiKey, resolveCommandPrefix, resolveComposeProjectName, resolveElectricAgentsPort, resolvePullWakeOwnerId, resolvePullWakeRunnerId, run, startBuiltinAgentsServer, startElectricAgentsDevEnvironment, stopElectricAgentsDevEnvironment, waitForElectricAgentsServer };
+export { DEFAULT_ELECTRIC_AGENTS_URL, ElectricCliEnv, ElectricCliHandlers, ObserveCommandOptions, PsCommandOptions, SendCommandOptions, SpawnCommandOptions, StartBuiltinCommandOptions, StartCommandOptions, StartedBuiltinAgentsEnvironment, StartedDevEnvironment, StopCommandOptions, StoppedDevEnvironment, createElectricCliHandlers, createElectricProgram, formatQuickstartBackendStartedMessage, getElectricCliEnv, getStartedBuiltinAgentsMessage, getStartedEnvironmentMessage, getStoppedEnvironmentMessage, readDotEnvFile, resolveAnthropicApiKey, resolveCommandPrefix, resolveComposeProjectName, resolveElectricAgentsPort, resolvePullWakeOwnerPrincipal, resolvePullWakeRunnerId, run, startBuiltinAgentsServer, startElectricAgentsDevEnvironment, stopElectricAgentsDevEnvironment, waitForElectricAgentsServer };

package/dist/{index-cwCTPq6Y.d.cts → index-OgX1QS9Q.d.cts}

@@ -34,7 +34,7 @@ declare function getStartedEnvironmentMessage(started: StartedDevEnvironment): s
 declare function getStoppedEnvironmentMessage(stopped: StoppedDevEnvironment): string;
 declare function getStartedBuiltinAgentsMessage(started: StartedBuiltinAgentsEnvironment): string;
 declare function resolvePullWakeRunnerId(env?: NodeJS.ProcessEnv, fileEnv?: Record<string, string>): string;
-declare function resolvePullWakeOwnerId(env?: NodeJS.ProcessEnv, fileEnv?: Record<string, string>): string;
+declare function resolvePullWakeOwnerPrincipal(env?: NodeJS.ProcessEnv, fileEnv?: Record<string, string>): string;
 declare function resolveComposeProjectName(_cwd?: string, env?: NodeJS.ProcessEnv): string;
 declare function waitForElectricAgentsServer(baseUrl: string, options?: WaitForServerOptions): Promise<void>;
 declare function startElectricAgentsDevEnvironment(_options?: StartCommandOptions, env?: NodeJS.ProcessEnv, cwd?: string): Promise<StartedDevEnvironment>;
@@ -125,4 +125,4 @@ declare function createElectricProgram({
 declare function run(argv?: Array<string>): Promise<void>;
 
 //#endregion
-export { DEFAULT_ELECTRIC_AGENTS_URL, ElectricCliEnv, ElectricCliHandlers, ObserveCommandOptions, PsCommandOptions, SendCommandOptions, SpawnCommandOptions, StartBuiltinCommandOptions, StartCommandOptions, StartedBuiltinAgentsEnvironment, StartedDevEnvironment, StopCommandOptions, StoppedDevEnvironment, createElectricCliHandlers, createElectricProgram, formatQuickstartBackendStartedMessage, getElectricCliEnv, getStartedBuiltinAgentsMessage, getStartedEnvironmentMessage, getStoppedEnvironmentMessage, readDotEnvFile, resolveAnthropicApiKey, resolveCommandPrefix, resolveComposeProjectName, resolveElectricAgentsPort, resolvePullWakeOwnerId, resolvePullWakeRunnerId, run, startBuiltinAgentsServer, startElectricAgentsDevEnvironment, stopElectricAgentsDevEnvironment, waitForElectricAgentsServer };
+export { DEFAULT_ELECTRIC_AGENTS_URL, ElectricCliEnv, ElectricCliHandlers, ObserveCommandOptions, PsCommandOptions, SendCommandOptions, SpawnCommandOptions, StartBuiltinCommandOptions, StartCommandOptions, StartedBuiltinAgentsEnvironment, StartedDevEnvironment, StopCommandOptions, StoppedDevEnvironment, createElectricCliHandlers, createElectricProgram, formatQuickstartBackendStartedMessage, getElectricCliEnv, getStartedBuiltinAgentsMessage, getStartedEnvironmentMessage, getStoppedEnvironmentMessage, readDotEnvFile, resolveAnthropicApiKey, resolveCommandPrefix, resolveComposeProjectName, resolveElectricAgentsPort, resolvePullWakeOwnerPrincipal, resolvePullWakeRunnerId, run, startBuiltinAgentsServer, startElectricAgentsDevEnvironment, stopElectricAgentsDevEnvironment, waitForElectricAgentsServer };

package/dist/index.cjs

@@ -11,6 +11,7 @@ const node_path = require_chunk.__toESM(require("node:path"));
 const node_url = require_chunk.__toESM(require("node:url"));
 const commander = require_chunk.__toESM(require("commander"));
 const node_readline_promises = require_chunk.__toESM(require("node:readline/promises"));
+const __electric_ax_agents_server_headers = require_chunk.__toESM(require("@electric-ax/agents/server-headers"));
 
 //#region src/prompt-api-key.ts
 const FRIENDLY_INTRO = `\n${[
@@ -162,17 +163,20 @@ function parseElectricAgentsHeaders(raw) {
 }
 function getElectricCliEnv(env = process.env) {
 	const explicitIdentity = env.ELECTRIC_AGENTS_IDENTITY?.trim();
+	const headers = parseElectricAgentsHeaders(env.ELECTRIC_AGENTS_SERVER_HEADERS);
 	return {
 		electricAgentsUrl: env.ELECTRIC_AGENTS_URL || DEFAULT_ELECTRIC_AGENTS_URL,
 		electricAgentsIdentity: explicitIdentity || getDefaultElectricAgentsIdentity(),
-		electricAgentsHeaders: parseElectricAgentsHeaders(env.ELECTRIC_AGENTS_SERVER_HEADERS)
+		electricAgentsHeaders: (0, __electric_ax_agents_server_headers.mergeElectricPrincipalHeader)(headers, env.ELECTRIC_AGENTS_PRINCIPAL)
 	};
 }
 function getErrorMessage(error) {
-	return error instanceof Error ? error.message : String(error);
+	if (error instanceof Error) return error.message || error.name || `Unknown error`;
+	const message = String(error);
+	return message || `Unknown error`;
 }
 function fail(message) {
-	throw new CliError(message);
+	throw new CliError(message || `Unknown error`);
 }
 function relativeTime(epochMs) {
 	const seconds = Math.floor((Date.now() - epochMs) / 1e3);
@@ -310,17 +314,36 @@ async function parseJsonResponse(res) {
 		return JSON.parse(text);
 	} catch (error) {
 		if (!(error instanceof SyntaxError)) throw error;
-		return { error: { message: text || res.statusText } };
+		return { error: { message: text || fallbackResponseMessage(res) } };
 	}
 }
+function fallbackResponseMessage(res) {
+	const status = res.status ? `HTTP ${res.status}` : `HTTP error`;
+	return res.statusText ? `${status}: ${res.statusText}` : status;
+}
+function stringMessage(value) {
+	if (typeof value !== `string`) return void 0;
+	const trimmed = value.trim();
+	if (trimmed.length === 0) return void 0;
+	return trimmed;
+}
+function errorMessageFromValue(value) {
+	const direct = stringMessage(value);
+	if (direct) return direct;
+	if (!value || typeof value !== `object` || Array.isArray(value)) return void 0;
+	const record = value;
+	return errorMessageFromValue(record.message) ?? errorMessageFromValue(record.error) ?? errorMessageFromValue(record.reason) ?? errorMessageFromValue(record.detail);
+}
+function responseErrorMessage(data, res) {
+	return errorMessageFromValue(data) ?? fallbackResponseMessage(res);
+}
 function failFromResponse(data, res) {
-	const err = data.error;
-	fail(String(err?.message ?? res.statusText));
+	fail(responseErrorMessage(data, res));
 }
 async function fetchEntityTypes(env) {
 	const res = await electricAgentsFetch(env, `/_electric/entity-types`);
-	const data = await res.json();
-	if (!res.ok) fail(typeof data === `object` && data !== null ? String(data.error?.message ?? res.statusText) : res.statusText);
+	const data = await parseJsonResponse(res);
+	if (!res.ok) failFromResponse(data, res);
 	if (!Array.isArray(data)) fail(`Unexpected response from server when listing entity types`);
 	return data;
 }
@@ -345,8 +368,8 @@ async function fetchEntities(env, options = {}) {
 	if (options.parent) searchParams.set(`parent`, options.parent);
 	const suffix = searchParams.size > 0 ? `?${searchParams.toString()}` : ``;
 	const res = await electricAgentsFetch(env, `/_electric/entities${suffix}`);
-	const data = await res.json();
-	if (!res.ok) fail(typeof data === `object` && data !== null ? String(data.error?.message ?? res.statusText) : res.statusText);
+	const data = await parseJsonResponse(res);
+	if (!res.ok) failFromResponse(data, res);
 	if (!Array.isArray(data)) fail(`Unexpected response from server when listing entities`);
 	return data;
 }
@@ -525,6 +548,8 @@ function getHelpText(commandName) {
 Environment:
   ELECTRIC_AGENTS_URL        Base URL of the server (default: ${DEFAULT_ELECTRIC_AGENTS_URL})
   ELECTRIC_AGENTS_IDENTITY   Sender identity for messages (default: ${getDefaultElectricAgentsIdentity()})
+  ELECTRIC_AGENTS_PRINCIPAL  Optional principal key sent as the Electric-Principal header
+  ELECTRIC_AGENTS_SERVER_HEADERS  Optional JSON object of additional server headers
   ANTHROPIC_API_KEY          Required for '${agentsCommand} start-builtin' and '${agentsCommand} quickstart'
 
 Examples:

package/dist/index.d.cts

@@ -1,3 +1,3 @@
 #!/usr/bin/env node
-import { DEFAULT_ELECTRIC_AGENTS_URL, ElectricCliEnv, ElectricCliHandlers, ObserveCommandOptions, PsCommandOptions, SendCommandOptions, SpawnCommandOptions, StartBuiltinCommandOptions, StartCommandOptions, StartedBuiltinAgentsEnvironment, StartedDevEnvironment, StopCommandOptions, StoppedDevEnvironment, createElectricCliHandlers, createElectricProgram, formatQuickstartBackendStartedMessage, getElectricCliEnv, resolveCommandPrefix, run } from "./index-cwCTPq6Y.cjs";
+import { DEFAULT_ELECTRIC_AGENTS_URL, ElectricCliEnv, ElectricCliHandlers, ObserveCommandOptions, PsCommandOptions, SendCommandOptions, SpawnCommandOptions, StartBuiltinCommandOptions, StartCommandOptions, StartedBuiltinAgentsEnvironment, StartedDevEnvironment, StopCommandOptions, StoppedDevEnvironment, createElectricCliHandlers, createElectricProgram, formatQuickstartBackendStartedMessage, getElectricCliEnv, resolveCommandPrefix, run } from "./index-OgX1QS9Q.cjs";
 export { DEFAULT_ELECTRIC_AGENTS_URL, ElectricCliEnv, ElectricCliHandlers, ObserveCommandOptions, PsCommandOptions, SendCommandOptions, SpawnCommandOptions, StartBuiltinCommandOptions, StartCommandOptions, StartedBuiltinAgentsEnvironment, StartedDevEnvironment, StopCommandOptions, StoppedDevEnvironment, createElectricCliHandlers, createElectricProgram, formatQuickstartBackendStartedMessage, getElectricCliEnv, resolveCommandPrefix, run };

package/dist/index.d.ts

@@ -1,3 +1,3 @@
 #!/usr/bin/env node
-import { DEFAULT_ELECTRIC_AGENTS_URL, ElectricCliEnv, ElectricCliHandlers, ObserveCommandOptions, PsCommandOptions, SendCommandOptions, SpawnCommandOptions, StartBuiltinCommandOptions, StartCommandOptions, StartedBuiltinAgentsEnvironment, StartedDevEnvironment, StopCommandOptions, StoppedDevEnvironment, createElectricCliHandlers, createElectricProgram, formatQuickstartBackendStartedMessage, getElectricCliEnv, resolveCommandPrefix, run } from "./index-BSHO_Rei.js";
+import { DEFAULT_ELECTRIC_AGENTS_URL, ElectricCliEnv, ElectricCliHandlers, ObserveCommandOptions, PsCommandOptions, SendCommandOptions, SpawnCommandOptions, StartBuiltinCommandOptions, StartCommandOptions, StartedBuiltinAgentsEnvironment, StartedDevEnvironment, StopCommandOptions, StoppedDevEnvironment, createElectricCliHandlers, createElectricProgram, formatQuickstartBackendStartedMessage, getElectricCliEnv, resolveCommandPrefix, run } from "./index-CwRI9tWl.js";
 export { DEFAULT_ELECTRIC_AGENTS_URL, ElectricCliEnv, ElectricCliHandlers, ObserveCommandOptions, PsCommandOptions, SendCommandOptions, SpawnCommandOptions, StartBuiltinCommandOptions, StartCommandOptions, StartedBuiltinAgentsEnvironment, StartedDevEnvironment, StopCommandOptions, StoppedDevEnvironment, createElectricCliHandlers, createElectricProgram, formatQuickstartBackendStartedMessage, getElectricCliEnv, resolveCommandPrefix, run };

package/dist/index.js

@@ -9,6 +9,7 @@ import { basename, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Command } from "commander";
 import { createInterface } from "node:readline/promises";
+import { mergeElectricPrincipalHeader } from "@electric-ax/agents/server-headers";
 
 //#region src/prompt-api-key.ts
 const FRIENDLY_INTRO = `\n${[
@@ -160,17 +161,20 @@ function parseElectricAgentsHeaders(raw) {
 }
 function getElectricCliEnv(env = process.env) {
 	const explicitIdentity = env.ELECTRIC_AGENTS_IDENTITY?.trim();
+	const headers = parseElectricAgentsHeaders(env.ELECTRIC_AGENTS_SERVER_HEADERS);
 	return {
 		electricAgentsUrl: env.ELECTRIC_AGENTS_URL || DEFAULT_ELECTRIC_AGENTS_URL,
 		electricAgentsIdentity: explicitIdentity || getDefaultElectricAgentsIdentity(),
-		electricAgentsHeaders: parseElectricAgentsHeaders(env.ELECTRIC_AGENTS_SERVER_HEADERS)
+		electricAgentsHeaders: mergeElectricPrincipalHeader(headers, env.ELECTRIC_AGENTS_PRINCIPAL)
 	};
 }
 function getErrorMessage(error) {
-	return error instanceof Error ? error.message : String(error);
+	if (error instanceof Error) return error.message || error.name || `Unknown error`;
+	const message = String(error);
+	return message || `Unknown error`;
 }
 function fail(message) {
-	throw new CliError(message);
+	throw new CliError(message || `Unknown error`);
 }
 function relativeTime(epochMs) {
 	const seconds = Math.floor((Date.now() - epochMs) / 1e3);
@@ -308,17 +312,36 @@ async function parseJsonResponse(res) {
 		return JSON.parse(text);
 	} catch (error) {
 		if (!(error instanceof SyntaxError)) throw error;
-		return { error: { message: text || res.statusText } };
+		return { error: { message: text || fallbackResponseMessage(res) } };
 	}
 }
+function fallbackResponseMessage(res) {
+	const status = res.status ? `HTTP ${res.status}` : `HTTP error`;
+	return res.statusText ? `${status}: ${res.statusText}` : status;
+}
+function stringMessage(value) {
+	if (typeof value !== `string`) return void 0;
+	const trimmed = value.trim();
+	if (trimmed.length === 0) return void 0;
+	return trimmed;
+}
+function errorMessageFromValue(value) {
+	const direct = stringMessage(value);
+	if (direct) return direct;
+	if (!value || typeof value !== `object` || Array.isArray(value)) return void 0;
+	const record = value;
+	return errorMessageFromValue(record.message) ?? errorMessageFromValue(record.error) ?? errorMessageFromValue(record.reason) ?? errorMessageFromValue(record.detail);
+}
+function responseErrorMessage(data, res) {
+	return errorMessageFromValue(data) ?? fallbackResponseMessage(res);
+}
 function failFromResponse(data, res) {
-	const err = data.error;
-	fail(String(err?.message ?? res.statusText));
+	fail(responseErrorMessage(data, res));
 }
 async function fetchEntityTypes(env) {
 	const res = await electricAgentsFetch(env, `/_electric/entity-types`);
-	const data = await res.json();
-	if (!res.ok) fail(typeof data === `object` && data !== null ? String(data.error?.message ?? res.statusText) : res.statusText);
+	const data = await parseJsonResponse(res);
+	if (!res.ok) failFromResponse(data, res);
 	if (!Array.isArray(data)) fail(`Unexpected response from server when listing entity types`);
 	return data;
 }
@@ -343,8 +366,8 @@ async function fetchEntities(env, options = {}) {
 	if (options.parent) searchParams.set(`parent`, options.parent);
 	const suffix = searchParams.size > 0 ? `?${searchParams.toString()}` : ``;
 	const res = await electricAgentsFetch(env, `/_electric/entities${suffix}`);
-	const data = await res.json();
-	if (!res.ok) fail(typeof data === `object` && data !== null ? String(data.error?.message ?? res.statusText) : res.statusText);
+	const data = await parseJsonResponse(res);
+	if (!res.ok) failFromResponse(data, res);
 	if (!Array.isArray(data)) fail(`Unexpected response from server when listing entities`);
 	return data;
 }
@@ -523,6 +546,8 @@ function getHelpText(commandName) {
 Environment:
   ELECTRIC_AGENTS_URL        Base URL of the server (default: ${DEFAULT_ELECTRIC_AGENTS_URL})
   ELECTRIC_AGENTS_IDENTITY   Sender identity for messages (default: ${getDefaultElectricAgentsIdentity()})
+  ELECTRIC_AGENTS_PRINCIPAL  Optional principal key sent as the Electric-Principal header
+  ELECTRIC_AGENTS_SERVER_HEADERS  Optional JSON object of additional server headers
   ANTHROPIC_API_KEY          Required for '${agentsCommand} start-builtin' and '${agentsCommand} quickstart'
 
 Examples:

package/dist/start.cjs

@@ -3,6 +3,7 @@ const require_chunk = require('./chunk-BCwAaXi7.cjs');
 const require_env = require('./env-CFKgT8o2.cjs');
 const __electric_ax_agents_runtime = require_chunk.__toESM(require("@electric-ax/agents-runtime"));
 const node_url = require_chunk.__toESM(require("node:url"));
+const __electric_ax_agents_server_headers = require_chunk.__toESM(require("@electric-ax/agents/server-headers"));
 const node_child_process = require_chunk.__toESM(require("node:child_process"));
 const __electric_ax_agents = require_chunk.__toESM(require("@electric-ax/agents"));
 
@@ -22,7 +23,8 @@ const ELECTRIC_AGENTS_SERVER_IMAGE_TAG = `latest`;
 const DEFAULT_ELECTRIC_AGENTS_PORT = 4437;
 const DEFAULT_COMPOSE_PROJECT_NAME = `electric-agents`;
 const DEFAULT_PULL_WAKE_RUNNER_ID = `builtin-agents`;
-const DEFAULT_PULL_WAKE_OWNER_ID = `builtin-agents`;
+const DEFAULT_PULL_WAKE_OWNER_PRINCIPAL = `/principal/system%3Abuiltin-agents`;
+const PRINCIPAL_URL_PREFIX = `/principal/`;
 const DOCKER_COMPOSE_FILE = (0, node_url.fileURLToPath)(new URL(`../docker-compose.full.yml`, require("url").pathToFileURL(__filename).href));
 function resolveElectricAgentsPort(env = process.env, fileEnv = require_env.readDotEnvFile()) {
 	const raw = env.ELECTRIC_AGENTS_PORT?.trim() || fileEnv.ELECTRIC_AGENTS_PORT?.trim();
@@ -65,11 +67,18 @@ function runnerIdFromIdentity(identity) {
 	const slug = identity.toLowerCase().replace(/[^a-z0-9._-]+/g, `-`).replace(/^-+|-+$/g, ``);
 	return slug ? `builtin-${slug}` : DEFAULT_PULL_WAKE_RUNNER_ID;
 }
+function principalUrlFromConfig(value) {
+	return value.startsWith(PRINCIPAL_URL_PREFIX) ? value : `${PRINCIPAL_URL_PREFIX}${encodeURIComponent(value)}`;
+}
 function resolvePullWakeRunnerId(env = process.env, fileEnv = require_env.readDotEnvFile()) {
 	return readConfigValue(env, fileEnv, [`ELECTRIC_AGENTS_PULL_WAKE_RUNNER_ID`, `PULL_WAKE_RUNNER_ID`]) ?? runnerIdFromIdentity(readConfigValue(env, fileEnv, [`ELECTRIC_AGENTS_IDENTITY`]));
 }
-function resolvePullWakeOwnerId(env = process.env, fileEnv = require_env.readDotEnvFile()) {
-	return readConfigValue(env, fileEnv, [`ELECTRIC_AGENTS_IDENTITY`]) ?? DEFAULT_PULL_WAKE_OWNER_ID;
+function resolvePullWakeOwnerPrincipal(env = process.env, fileEnv = require_env.readDotEnvFile()) {
+	const principal = readConfigValue(env, fileEnv, [`ELECTRIC_AGENTS_PRINCIPAL`]);
+	if (principal) return principalUrlFromConfig(principal);
+	const identity = readConfigValue(env, fileEnv, [`ELECTRIC_AGENTS_IDENTITY`]);
+	if (identity) return principalUrlFromConfig(identity);
+	return DEFAULT_PULL_WAKE_OWNER_PRINCIPAL;
 }
 function parseAdditionalServerHeaders(env, fileEnv) {
 	const raw = readConfigValue(env, fileEnv, [`ELECTRIC_AGENTS_SERVER_HEADERS`]);
@@ -89,6 +98,9 @@ function parseAdditionalServerHeaders(env, fileEnv) {
 	const normalized = Object.fromEntries(headers.entries());
 	return Object.keys(normalized).length > 0 ? normalized : void 0;
 }
+function resolveServerHeaders(env, fileEnv) {
+	return (0, __electric_ax_agents_server_headers.mergeElectricPrincipalHeader)(parseAdditionalServerHeaders(env, fileEnv), readConfigValue(env, fileEnv, [`ELECTRIC_AGENTS_PRINCIPAL`]));
+}
 function mergeHeaders(...sources) {
 	const headers = new Headers();
 	for (const source of sources) {
@@ -226,8 +238,8 @@ async function startBuiltinAgentsServer(options, params = {}) {
 	const fileEnv = require_env.readDotEnvFile(cwd);
 	const anthropicApiKey = require_env.resolveAnthropicApiKey(options, env, fileEnv);
 	const runnerId = resolvePullWakeRunnerId(env, fileEnv);
-	const ownerUserId = resolvePullWakeOwnerId(env, fileEnv);
-	const serverHeaders = mergeHeaders(parseAdditionalServerHeaders(env, fileEnv));
+	const ownerPrincipal = resolvePullWakeOwnerPrincipal(env, fileEnv);
+	const serverHeaders = mergeHeaders(resolveServerHeaders(env, fileEnv));
 	const agentServerUrl = params.agentServerUrl ?? env.ELECTRIC_AGENTS_URL?.trim() ?? `http://localhost:${resolveElectricAgentsPort(env, fileEnv)}`;
 	process.env.ANTHROPIC_API_KEY = anthropicApiKey;
 	await waitForElectricAgentsServer(agentServerUrl, { headers: serverHeaders });
@@ -237,7 +249,7 @@ async function startBuiltinAgentsServer(options, params = {}) {
 		loadProjectMcpConfig: true,
 		pullWake: {
 			runnerId,
-			ownerUserId,
+			ownerPrincipal,
 			registerRunner: true,
 			headers: serverHeaders,
 			claimHeaders: serverHeaders,
@@ -263,7 +275,7 @@ exports.readDotEnvFile = require_env.readDotEnvFile
 exports.resolveAnthropicApiKey = require_env.resolveAnthropicApiKey
 exports.resolveComposeProjectName = resolveComposeProjectName
 exports.resolveElectricAgentsPort = resolveElectricAgentsPort
-exports.resolvePullWakeOwnerId = resolvePullWakeOwnerId
+exports.resolvePullWakeOwnerPrincipal = resolvePullWakeOwnerPrincipal
 exports.resolvePullWakeRunnerId = resolvePullWakeRunnerId
 exports.startBuiltinAgentsServer = startBuiltinAgentsServer
 exports.startElectricAgentsDevEnvironment = startElectricAgentsDevEnvironment

package/dist/start.d.cts

@@ -1,2 +1,2 @@
-import { StartedBuiltinAgentsEnvironment, StartedDevEnvironment, StoppedDevEnvironment, getStartedBuiltinAgentsMessage, getStartedEnvironmentMessage, getStoppedEnvironmentMessage, readDotEnvFile, resolveAnthropicApiKey, resolveComposeProjectName, resolveElectricAgentsPort, resolvePullWakeOwnerId, resolvePullWakeRunnerId, startBuiltinAgentsServer, startElectricAgentsDevEnvironment, stopElectricAgentsDevEnvironment, waitForElectricAgentsServer } from "./index-cwCTPq6Y.cjs";
-export { StartedBuiltinAgentsEnvironment, StartedDevEnvironment, StoppedDevEnvironment, getStartedBuiltinAgentsMessage, getStartedEnvironmentMessage, getStoppedEnvironmentMessage, readDotEnvFile, resolveAnthropicApiKey, resolveComposeProjectName, resolveElectricAgentsPort, resolvePullWakeOwnerId, resolvePullWakeRunnerId, startBuiltinAgentsServer, startElectricAgentsDevEnvironment, stopElectricAgentsDevEnvironment, waitForElectricAgentsServer };
+import { StartedBuiltinAgentsEnvironment, StartedDevEnvironment, StoppedDevEnvironment, getStartedBuiltinAgentsMessage, getStartedEnvironmentMessage, getStoppedEnvironmentMessage, readDotEnvFile, resolveAnthropicApiKey, resolveComposeProjectName, resolveElectricAgentsPort, resolvePullWakeOwnerPrincipal, resolvePullWakeRunnerId, startBuiltinAgentsServer, startElectricAgentsDevEnvironment, stopElectricAgentsDevEnvironment, waitForElectricAgentsServer } from "./index-OgX1QS9Q.cjs";
+export { StartedBuiltinAgentsEnvironment, StartedDevEnvironment, StoppedDevEnvironment, getStartedBuiltinAgentsMessage, getStartedEnvironmentMessage, getStoppedEnvironmentMessage, readDotEnvFile, resolveAnthropicApiKey, resolveComposeProjectName, resolveElectricAgentsPort, resolvePullWakeOwnerPrincipal, resolvePullWakeRunnerId, startBuiltinAgentsServer, startElectricAgentsDevEnvironment, stopElectricAgentsDevEnvironment, waitForElectricAgentsServer };

package/dist/start.d.ts

@@ -1,2 +1,2 @@
-import { StartedBuiltinAgentsEnvironment, StartedDevEnvironment, StoppedDevEnvironment, getStartedBuiltinAgentsMessage, getStartedEnvironmentMessage, getStoppedEnvironmentMessage, readDotEnvFile, resolveAnthropicApiKey, resolveComposeProjectName, resolveElectricAgentsPort, resolvePullWakeOwnerId, resolvePullWakeRunnerId, startBuiltinAgentsServer, startElectricAgentsDevEnvironment, stopElectricAgentsDevEnvironment, waitForElectricAgentsServer } from "./index-BSHO_Rei.js";
-export { StartedBuiltinAgentsEnvironment, StartedDevEnvironment, StoppedDevEnvironment, getStartedBuiltinAgentsMessage, getStartedEnvironmentMessage, getStoppedEnvironmentMessage, readDotEnvFile, resolveAnthropicApiKey, resolveComposeProjectName, resolveElectricAgentsPort, resolvePullWakeOwnerId, resolvePullWakeRunnerId, startBuiltinAgentsServer, startElectricAgentsDevEnvironment, stopElectricAgentsDevEnvironment, waitForElectricAgentsServer };
+import { StartedBuiltinAgentsEnvironment, StartedDevEnvironment, StoppedDevEnvironment, getStartedBuiltinAgentsMessage, getStartedEnvironmentMessage, getStoppedEnvironmentMessage, readDotEnvFile, resolveAnthropicApiKey, resolveComposeProjectName, resolveElectricAgentsPort, resolvePullWakeOwnerPrincipal, resolvePullWakeRunnerId, startBuiltinAgentsServer, startElectricAgentsDevEnvironment, stopElectricAgentsDevEnvironment, waitForElectricAgentsServer } from "./index-CwRI9tWl.js";
+export { StartedBuiltinAgentsEnvironment, StartedDevEnvironment, StoppedDevEnvironment, getStartedBuiltinAgentsMessage, getStartedEnvironmentMessage, getStoppedEnvironmentMessage, readDotEnvFile, resolveAnthropicApiKey, resolveComposeProjectName, resolveElectricAgentsPort, resolvePullWakeOwnerPrincipal, resolvePullWakeRunnerId, startBuiltinAgentsServer, startElectricAgentsDevEnvironment, stopElectricAgentsDevEnvironment, waitForElectricAgentsServer };

package/dist/start.js

@@ -1,6 +1,7 @@
 import { readDotEnvFile$1 as readDotEnvFile, resolveAnthropicApiKey$1 as resolveAnthropicApiKey } from "./env-DIhTv987.js";
 import { appendPathToUrl } from "@electric-ax/agents-runtime";
 import { fileURLToPath } from "node:url";
+import { mergeElectricPrincipalHeader } from "@electric-ax/agents/server-headers";
 import { spawn } from "node:child_process";
 import { BuiltinAgentsServer } from "@electric-ax/agents";
 
@@ -20,7 +21,8 @@ const ELECTRIC_AGENTS_SERVER_IMAGE_TAG = `latest`;
 const DEFAULT_ELECTRIC_AGENTS_PORT = 4437;
 const DEFAULT_COMPOSE_PROJECT_NAME = `electric-agents`;
 const DEFAULT_PULL_WAKE_RUNNER_ID = `builtin-agents`;
-const DEFAULT_PULL_WAKE_OWNER_ID = `builtin-agents`;
+const DEFAULT_PULL_WAKE_OWNER_PRINCIPAL = `/principal/system%3Abuiltin-agents`;
+const PRINCIPAL_URL_PREFIX = `/principal/`;
 const DOCKER_COMPOSE_FILE = fileURLToPath(new URL(`../docker-compose.full.yml`, import.meta.url));
 function resolveElectricAgentsPort(env = process.env, fileEnv = readDotEnvFile()) {
 	const raw = env.ELECTRIC_AGENTS_PORT?.trim() || fileEnv.ELECTRIC_AGENTS_PORT?.trim();
@@ -63,11 +65,18 @@ function runnerIdFromIdentity(identity) {
 	const slug = identity.toLowerCase().replace(/[^a-z0-9._-]+/g, `-`).replace(/^-+|-+$/g, ``);
 	return slug ? `builtin-${slug}` : DEFAULT_PULL_WAKE_RUNNER_ID;
 }
+function principalUrlFromConfig(value) {
+	return value.startsWith(PRINCIPAL_URL_PREFIX) ? value : `${PRINCIPAL_URL_PREFIX}${encodeURIComponent(value)}`;
+}
 function resolvePullWakeRunnerId(env = process.env, fileEnv = readDotEnvFile()) {
 	return readConfigValue(env, fileEnv, [`ELECTRIC_AGENTS_PULL_WAKE_RUNNER_ID`, `PULL_WAKE_RUNNER_ID`]) ?? runnerIdFromIdentity(readConfigValue(env, fileEnv, [`ELECTRIC_AGENTS_IDENTITY`]));
 }
-function resolvePullWakeOwnerId(env = process.env, fileEnv = readDotEnvFile()) {
-	return readConfigValue(env, fileEnv, [`ELECTRIC_AGENTS_IDENTITY`]) ?? DEFAULT_PULL_WAKE_OWNER_ID;
+function resolvePullWakeOwnerPrincipal(env = process.env, fileEnv = readDotEnvFile()) {
+	const principal = readConfigValue(env, fileEnv, [`ELECTRIC_AGENTS_PRINCIPAL`]);
+	if (principal) return principalUrlFromConfig(principal);
+	const identity = readConfigValue(env, fileEnv, [`ELECTRIC_AGENTS_IDENTITY`]);
+	if (identity) return principalUrlFromConfig(identity);
+	return DEFAULT_PULL_WAKE_OWNER_PRINCIPAL;
 }
 function parseAdditionalServerHeaders(env, fileEnv) {
 	const raw = readConfigValue(env, fileEnv, [`ELECTRIC_AGENTS_SERVER_HEADERS`]);
@@ -87,6 +96,9 @@ function parseAdditionalServerHeaders(env, fileEnv) {
 	const normalized = Object.fromEntries(headers.entries());
 	return Object.keys(normalized).length > 0 ? normalized : void 0;
 }
+function resolveServerHeaders(env, fileEnv) {
+	return mergeElectricPrincipalHeader(parseAdditionalServerHeaders(env, fileEnv), readConfigValue(env, fileEnv, [`ELECTRIC_AGENTS_PRINCIPAL`]));
+}
 function mergeHeaders(...sources) {
 	const headers = new Headers();
 	for (const source of sources) {
@@ -224,8 +236,8 @@ async function startBuiltinAgentsServer(options, params = {}) {
 	const fileEnv = readDotEnvFile(cwd);
 	const anthropicApiKey = resolveAnthropicApiKey(options, env, fileEnv);
 	const runnerId = resolvePullWakeRunnerId(env, fileEnv);
-	const ownerUserId = resolvePullWakeOwnerId(env, fileEnv);
-	const serverHeaders = mergeHeaders(parseAdditionalServerHeaders(env, fileEnv));
+	const ownerPrincipal = resolvePullWakeOwnerPrincipal(env, fileEnv);
+	const serverHeaders = mergeHeaders(resolveServerHeaders(env, fileEnv));
 	const agentServerUrl = params.agentServerUrl ?? env.ELECTRIC_AGENTS_URL?.trim() ?? `http://localhost:${resolveElectricAgentsPort(env, fileEnv)}`;
 	process.env.ANTHROPIC_API_KEY = anthropicApiKey;
 	await waitForElectricAgentsServer(agentServerUrl, { headers: serverHeaders });
@@ -235,7 +247,7 @@ async function startBuiltinAgentsServer(options, params = {}) {
 		loadProjectMcpConfig: true,
 		pullWake: {
 			runnerId,
-			ownerUserId,
+			ownerPrincipal,
 			registerRunner: true,
 			headers: serverHeaders,
 			claimHeaders: serverHeaders,
@@ -254,4 +266,4 @@ async function startBuiltinAgentsServer(options, params = {}) {
 }
 
 //#endregion
-export { getStartedBuiltinAgentsMessage, getStartedEnvironmentMessage, getStoppedEnvironmentMessage, readDotEnvFile, resolveAnthropicApiKey, resolveComposeProjectName, resolveElectricAgentsPort, resolvePullWakeOwnerId, resolvePullWakeRunnerId, startBuiltinAgentsServer, startElectricAgentsDevEnvironment, stopElectricAgentsDevEnvironment, waitForElectricAgentsServer };
+export { getStartedBuiltinAgentsMessage, getStartedEnvironmentMessage, getStoppedEnvironmentMessage, readDotEnvFile, resolveAnthropicApiKey, resolveComposeProjectName, resolveElectricAgentsPort, resolvePullWakeOwnerPrincipal, resolvePullWakeRunnerId, startBuiltinAgentsServer, startElectricAgentsDevEnvironment, stopElectricAgentsDevEnvironment, waitForElectricAgentsServer };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "electric-ax",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "CLI for Electric Agents",
   "author": "ElectricSQL team and contributors",
   "license": "Apache-2.0",
@@ -39,15 +39,15 @@
   "dependencies": {
     "@durable-streams/client": "https://pkg.pr.new/durable-streams/durable-streams/@durable-streams/client@350",
     "@durable-streams/state": "https://pkg.pr.new/durable-streams/durable-streams/@durable-streams/state@350",
-    "@electric-sql/client": "^1.5.17",
+    "@electric-sql/client": "^1.5.18",
     "@tanstack/db": "^0.6.4",
     "@tanstack/react-db": "^0.1.82",
     "commander": "^13.1.0",
     "ink": "^6.8.0",
     "omelette": "^0.4.17",
     "react": "^19.2.0",
-    "@electric-ax/agents": "0.4.1",
-    "@electric-ax/agents-runtime": "0.2.1"
+    "@electric-ax/agents": "0.4.3",
+    "@electric-ax/agents-runtime": "0.2.2"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.1.0",