@electric-ax/agents 0.4.11 → 0.4.12

package/dist/entrypoint.js

@@ -4,7 +4,8 @@ import fs from "node:fs";
 import pino from "pino";
 import { fileURLToPath } from "node:url";
 import { MOONSHOT_API_BASE_URL, MOONSHOT_PROVIDER, appendPathToUrl, completeWithLowCostModel, createEntityRegistry, createPullWakeRunner, createRuntimeHandler, createSkillTools, createSkillsRegistry, db, detectAvailableProviders, getMoonshotApiKey, getMoonshotModels, readCodexAccessToken, registerToolProvider, unregisterToolProvider } from "@electric-ax/agents-runtime";
-import { braveSearchTool, createBashTool, createEditTool, createEventSourceTools, createFetchUrlTool, createReadFileTool, createSendTool, createWriteTool, fetchUrlTool } from "@electric-ax/agents-runtime/tools";
+import { braveSearchTool, createBashTool, createEditTool, createEventSourceTools, createFetchUrlTool, createReadFileTool, createSendTool, createWriteTool } from "@electric-ax/agents-runtime/tools";
+import { chooseDefaultSandbox, isE2BAvailable, remoteSandbox } from "@electric-ax/agents-runtime/sandbox";
 import { z } from "zod";
 import { createHash } from "node:crypto";
 import fs$1 from "node:fs/promises";
@@ -764,7 +765,8 @@ function createSpawnWorkerTool(ctx, modelConfig) {
 					wake: {
 						on: `runFinished`,
 						includeResponse: true
-					}
+					},
+					sandbox: `inherit`
 				});
 				const workerUrl = handle.entityUrl;
 				return {
@@ -1151,19 +1153,19 @@ function getToolName(tool) {
 	const name = tool.name;
 	return typeof name === `string` ? name : null;
 }
-function createHortonTools(workingDirectory, ctx, readSet, opts = {}) {
+function createHortonTools(sandbox, ctx, readSet, opts = {}) {
 	return [
-		createBashTool(workingDirectory),
-		createReadFileTool(workingDirectory, readSet),
-		createWriteTool(workingDirectory, readSet),
-		createEditTool(workingDirectory, readSet),
+		createBashTool(sandbox),
+		createReadFileTool(sandbox, readSet),
+		createWriteTool(sandbox, readSet),
+		createEditTool(sandbox, readSet),
 		braveSearchTool,
-		...opts.modelCatalog && opts.modelConfig ? [createFetchUrlTool({
+		...opts.modelCatalog && opts.modelConfig ? [createFetchUrlTool(sandbox, {
 			catalog: opts.modelCatalog,
 			modelConfig: opts.modelConfig,
 			log: (message) => serverLog.info(message),
 			logPrefix: opts.logPrefix ?? `[horton]`
-		})] : [fetchUrlTool],
+		})] : [createFetchUrlTool(sandbox)],
 		createSpawnWorkerTool(ctx, opts.modelConfig),
 		createSendTool(ctx.send, { selfEntityUrl: ctx.entityUrl }),
 		...opts.docsSearchTool ? [opts.docsSearchTool] : []
@@ -1217,11 +1219,10 @@ async function extractFirstUserMessage(ctx) {
 function messageSeq(message) {
 	return typeof message._seq === `number` ? message._seq : -1;
 }
-function readAgentsMd(workingDirectory) {
-	const agentsMdPath = path.join(workingDirectory, `AGENTS.md`);
+async function readAgentsMd(sandbox) {
+	const agentsMdPath = path.posix.join(sandbox.workingDirectory, `AGENTS.md`);
 	try {
-		if (!fs.existsSync(agentsMdPath) || !fs.statSync(agentsMdPath).isFile()) return null;
-		const content = fs.readFileSync(agentsMdPath, `utf8`);
+		const content = (await sandbox.readFile(agentsMdPath)).toString(`utf8`);
 		return [
 			`<context_file kind="instructions" path="${agentsMdPath}">`,
 			content,
@@ -1232,16 +1233,16 @@ function readAgentsMd(workingDirectory) {
 	}
 }
 function createAssistantHandler(options) {
-	const { workingDirectory, streamFn, docsSupport, docsSearchTool, skillsRegistry, modelCatalog, docsUrl } = options;
+	const { streamFn, docsSupport, docsSearchTool, skillsRegistry, modelCatalog, docsUrl } = options;
 	const hasSkills = Boolean(skillsRegistry && skillsRegistry.catalog.size > 0);
 	return async function assistantHandler(ctx, wake) {
 		const readSet = new Set();
-		const effectiveCwd = typeof ctx.args.workingDirectory === `string` && ctx.args.workingDirectory.trim().length > 0 ? ctx.args.workingDirectory : workingDirectory;
 		const modelConfig = resolveBuiltinModelConfig(modelCatalog, ctx.args);
-		const agentsMd = readAgentsMd(effectiveCwd);
+		const sandboxCwd = ctx.sandbox.workingDirectory;
+		const agentsMd = await readAgentsMd(ctx.sandbox);
 		const tools = [
 			...ctx.electricTools,
-			...createHortonTools(effectiveCwd, ctx, readSet, {
+			...createHortonTools(ctx.sandbox, ctx, readSet, {
 				docsSearchTool,
 				modelConfig,
 				modelCatalog,
@@ -1332,7 +1333,7 @@ function createAssistantHandler(options) {
 			}
 		});
 		ctx.useAgent({
-			systemPrompt: buildHortonSystemPrompt(effectiveCwd, {
+			systemPrompt: buildHortonSystemPrompt(sandboxCwd, {
 				hasDocsSupport: Boolean(docsSupport),
 				hasSkills,
 				docsUrl,
@@ -1360,7 +1361,6 @@ function registerHorton(registry, options) {
 		serverLog.warn(`[horton-docs] warmup failed: ${error instanceof Error ? error.message : String(error)}`);
 	});
 	const assistantHandler = createAssistantHandler({
-		workingDirectory,
 		streamFn,
 		docsSupport,
 		docsSearchTool,
@@ -1417,26 +1417,26 @@ function parseWorkerArgs(value) {
 	if (typeof value.reasoningEffort === `string` && REASONING_EFFORT_VALUES.includes(value.reasoningEffort)) args.reasoningEffort = value.reasoningEffort;
 	return args;
 }
-function buildToolsForWorker(tools, workingDirectory, ctx, readSet) {
+function buildToolsForWorker(tools, sandbox, ctx, readSet) {
 	const out = [];
 	for (const name of tools) switch (name) {
 		case `bash`:
-			out.push(createBashTool(workingDirectory));
+			out.push(createBashTool(sandbox));
 			break;
 		case `read`:
-			out.push(createReadFileTool(workingDirectory, readSet));
+			out.push(createReadFileTool(sandbox, readSet));
 			break;
 		case `write`:
-			out.push(createWriteTool(workingDirectory, readSet));
+			out.push(createWriteTool(sandbox, readSet));
 			break;
 		case `edit`:
-			out.push(createEditTool(workingDirectory, readSet));
+			out.push(createEditTool(sandbox, readSet));
 			break;
 		case `web_search`:
 			out.push(braveSearchTool);
 			break;
 		case `fetch_url`:
-			out.push(fetchUrlTool);
+			out.push(createFetchUrlTool(sandbox));
 			break;
 		case `spawn_worker`:
 			out.push(createSpawnWorkerTool(ctx));
@@ -1544,13 +1544,13 @@ function buildSharedStateTools(shared, schema, mode) {
 	return tools;
 }
 function registerWorker(registry, options) {
-	const { workingDirectory, streamFn, modelCatalog } = options;
+	const { streamFn, modelCatalog } = options;
 	registry.define(`worker`, {
 		description: `Internal — generic worker spawned by other agents. Configure via spawn args (systemPrompt + tools + optional sharedDb).`,
 		async handler(ctx) {
 			const args = parseWorkerArgs(ctx.args);
 			const readSet = new Set();
-			const builtinTools = buildToolsForWorker(args.tools, workingDirectory, ctx, readSet);
+			const builtinTools = buildToolsForWorker(args.tools, ctx.sandbox, ctx, readSet);
 			const modelConfig = resolveBuiltinModelConfig(modelCatalog, args);
 			const sharedStateTools = [];
 			if (args.sharedDb) {
@@ -1628,6 +1628,7 @@ async function createBuiltinAgentHandler(options) {
 		modelCatalog
 	});
 	typeNames.push(`worker`);
+	const sandboxProfiles = await buildBuiltinSandboxProfiles(cwd);
 	const runtime = createRuntimeHandler({
 		baseUrl: agentServerUrl,
 		serveEndpoint,
@@ -1638,7 +1639,8 @@ async function createBuiltinAgentHandler(options) {
 		idleTimeout: 5 * 6e4,
 		createElectricTools: createBuiltinElectricTools(createElectricTools),
 		publicUrl,
-		name: runtimeName ?? `builtin-agents`
+		name: runtimeName ?? `builtin-agents`,
+		sandboxProfiles
 	});
 	return {
 		handler: runtime.onEnter,
@@ -1652,6 +1654,85 @@ async function registerBuiltinAgentTypes(bootstrap) {
 	await bootstrap.runtime.registerTypes();
 	serverLog.info(`[builtin-agents] ${bootstrap.typeNames.length} built-in agent types ready: ${bootstrap.typeNames.join(`, `)}`);
 }
+/**
+* Guard so repeated `buildBuiltinSandboxProfiles` calls in one process don't
+* re-run the boot sweep.
+*/
+let dockerSweptOnBoot = false;
+function sweepOrphanedDockerSandboxesOnce(sweep) {
+	if (dockerSweptOnBoot) return;
+	dockerSweptOnBoot = true;
+	sweep().then((removed) => {
+		if (removed.length > 0) serverLog.info(`[builtin-agents] docker sandbox boot sweep removed ${removed.length} leftover container(s)`);
+	}).catch((err) => serverLog.warn(`[builtin-agents] docker sandbox boot sweep error: ${err instanceof Error ? err.message : String(err)}`));
+}
+/**
+* Built-in sandbox profiles. `local` is always available. `docker` is
+* gated on Docker being reachable so a user without Docker installed
+* sees only what works — the UI never offers a non-functional choice.
+*/
+async function buildBuiltinSandboxProfiles(workingDirectory) {
+	const profiles = [{
+		name: `local`,
+		label: `Local`,
+		description: `Runs on the host without isolation. Full filesystem access.`,
+		factory: ({ args }) => chooseDefaultSandbox(resolveCwd(args, workingDirectory))
+	}];
+	try {
+		const { isDockerAvailable } = await import(`@electric-ax/agents-runtime/sandbox/docker`);
+		if (await isDockerAvailable()) {
+			const { dockerSandbox, sweepOrphanedDockerSandboxes } = await import(`@electric-ax/agents-runtime/sandbox/docker`);
+			sweepOrphanedDockerSandboxesOnce(sweepOrphanedDockerSandboxes);
+			profiles.push({
+				name: `docker`,
+				label: `Docker`,
+				description: `Runs in a hardened Docker container: dropped capabilities, no privilege escalation, and CPU/memory/process limits. The chosen working directory is mounted read-write and, by default, network egress is unrestricted (allow-all).`,
+				factory: ({ args, sandboxKey, persistent, owner, entityType, entityUrl }) => {
+					const cwd = readWorkingDirectoryArg(args);
+					return dockerSandbox({
+						initialNetworkPolicy: { mode: `allow-all` },
+						extraMounts: cwd ? [{
+							hostPath: cwd,
+							containerPath: `/work`,
+							readOnly: false
+						}] : void 0,
+						sandboxKey,
+						persistent,
+						owner,
+						entityType,
+						entityUrl
+					});
+				}
+			});
+		} else serverLog.info(`[builtin-agents] docker daemon not reachable — docker sandbox profile not registered`);
+	} catch (err) {
+		serverLog.warn(`[builtin-agents] failed to probe docker availability: ${err instanceof Error ? err.message : String(err)}`);
+	}
+	if (process.env.E2B_API_KEY) if (await isE2BAvailable()) profiles.push({
+		name: `e2b`,
+		label: `E2B`,
+		description: `Runs in a remote E2B microVM. Persistent sandboxes survive across wakes and are reachable from any runner.`,
+		remote: true,
+		factory: ({ sandboxKey, persistent, owner }) => remoteSandbox({
+			provider: `e2b`,
+			apiKey: process.env.E2B_API_KEY,
+			sandboxKey,
+			persistent,
+			owner,
+			initialNetworkPolicy: { mode: `allow-all` }
+		})
+	});
+	else serverLog.info(`[builtin-agents] E2B_API_KEY set but the "e2b" package is not installed — e2b sandbox profile not registered`);
+	console.log(`[builtin-agents] sandbox profiles advertised: ${profiles.map((p) => p.name).join(`, `)}`);
+	return profiles;
+}
+function readWorkingDirectoryArg(args) {
+	const v = args.workingDirectory;
+	return typeof v === `string` && v.trim().length > 0 ? v : null;
+}
+function resolveCwd(args, fallback) {
+	return readWorkingDirectoryArg(args) ?? fallback;
+}
 
 //#endregion
 //#region src/server.ts
@@ -1860,6 +1941,7 @@ 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 profiles = this.bootstrap?.runtime.sandboxProfileDescriptors ?? [];
 		const response = await fetch(appendPathToUrl(this.options.agentServerUrl, `/_electric/runners`), {
 			method: `POST`,
 			headers,
@@ -1868,7 +1950,8 @@ var BuiltinAgentsServer = class {
 				owner_principal: pullWake.ownerPrincipal,
 				label: pullWake.label ?? `Built-in agents`,
 				kind: `local`,
-				admin_status: `enabled`
+				admin_status: `enabled`,
+				sandbox_profiles: profiles
 			})
 		});
 		if (!response.ok) throw new Error(`Failed to register pull-wake runner ${pullWake.runnerId}: ${response.status} ${await response.text()}`);

package/dist/index.cjs

@@ -27,6 +27,7 @@ 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"));
 const __electric_ax_agents_runtime_tools = __toESM(require("@electric-ax/agents-runtime/tools"));
+const __electric_ax_agents_runtime_sandbox = __toESM(require("@electric-ax/agents-runtime/sandbox"));
 const node_fs = __toESM(require("node:fs"));
 const pino = __toESM(require("pino"));
 const zod = __toESM(require("zod"));
@@ -788,7 +789,8 @@ function createSpawnWorkerTool(ctx, modelConfig) {
 					wake: {
 						on: `runFinished`,
 						includeResponse: true
-					}
+					},
+					sandbox: `inherit`
 				});
 				const workerUrl = handle.entityUrl;
 				return {
@@ -1176,19 +1178,19 @@ function getToolName(tool) {
 	const name = tool.name;
 	return typeof name === `string` ? name : null;
 }
-function createHortonTools(workingDirectory, ctx, readSet, opts = {}) {
+function createHortonTools(sandbox, ctx, readSet, opts = {}) {
 	return [
-		(0, __electric_ax_agents_runtime_tools.createBashTool)(workingDirectory),
-		(0, __electric_ax_agents_runtime_tools.createReadFileTool)(workingDirectory, readSet),
-		(0, __electric_ax_agents_runtime_tools.createWriteTool)(workingDirectory, readSet),
-		(0, __electric_ax_agents_runtime_tools.createEditTool)(workingDirectory, readSet),
+		(0, __electric_ax_agents_runtime_tools.createBashTool)(sandbox),
+		(0, __electric_ax_agents_runtime_tools.createReadFileTool)(sandbox, readSet),
+		(0, __electric_ax_agents_runtime_tools.createWriteTool)(sandbox, readSet),
+		(0, __electric_ax_agents_runtime_tools.createEditTool)(sandbox, readSet),
 		__electric_ax_agents_runtime_tools.braveSearchTool,
-		...opts.modelCatalog && opts.modelConfig ? [(0, __electric_ax_agents_runtime_tools.createFetchUrlTool)({
+		...opts.modelCatalog && opts.modelConfig ? [(0, __electric_ax_agents_runtime_tools.createFetchUrlTool)(sandbox, {
 			catalog: opts.modelCatalog,
 			modelConfig: opts.modelConfig,
 			log: (message) => serverLog.info(message),
 			logPrefix: opts.logPrefix ?? `[horton]`
-		})] : [__electric_ax_agents_runtime_tools.fetchUrlTool],
+		})] : [(0, __electric_ax_agents_runtime_tools.createFetchUrlTool)(sandbox)],
 		createSpawnWorkerTool(ctx, opts.modelConfig),
 		(0, __electric_ax_agents_runtime_tools.createSendTool)(ctx.send, { selfEntityUrl: ctx.entityUrl }),
 		...opts.docsSearchTool ? [opts.docsSearchTool] : []
@@ -1242,11 +1244,10 @@ async function extractFirstUserMessage(ctx) {
 function messageSeq(message) {
 	return typeof message._seq === `number` ? message._seq : -1;
 }
-function readAgentsMd(workingDirectory) {
-	const agentsMdPath = node_path.default.join(workingDirectory, `AGENTS.md`);
+async function readAgentsMd(sandbox) {
+	const agentsMdPath = node_path.default.posix.join(sandbox.workingDirectory, `AGENTS.md`);
 	try {
-		if (!node_fs.default.existsSync(agentsMdPath) || !node_fs.default.statSync(agentsMdPath).isFile()) return null;
-		const content = node_fs.default.readFileSync(agentsMdPath, `utf8`);
+		const content = (await sandbox.readFile(agentsMdPath)).toString(`utf8`);
 		return [
 			`<context_file kind="instructions" path="${agentsMdPath}">`,
 			content,
@@ -1257,16 +1258,16 @@ function readAgentsMd(workingDirectory) {
 	}
 }
 function createAssistantHandler(options) {
-	const { workingDirectory, streamFn, docsSupport, docsSearchTool, skillsRegistry, modelCatalog, docsUrl } = options;
+	const { streamFn, docsSupport, docsSearchTool, skillsRegistry, modelCatalog, docsUrl } = options;
 	const hasSkills = Boolean(skillsRegistry && skillsRegistry.catalog.size > 0);
 	return async function assistantHandler(ctx, wake) {
 		const readSet = new Set();
-		const effectiveCwd = typeof ctx.args.workingDirectory === `string` && ctx.args.workingDirectory.trim().length > 0 ? ctx.args.workingDirectory : workingDirectory;
 		const modelConfig = resolveBuiltinModelConfig(modelCatalog, ctx.args);
-		const agentsMd = readAgentsMd(effectiveCwd);
+		const sandboxCwd = ctx.sandbox.workingDirectory;
+		const agentsMd = await readAgentsMd(ctx.sandbox);
 		const tools = [
 			...ctx.electricTools,
-			...createHortonTools(effectiveCwd, ctx, readSet, {
+			...createHortonTools(ctx.sandbox, ctx, readSet, {
 				docsSearchTool,
 				modelConfig,
 				modelCatalog,
@@ -1357,7 +1358,7 @@ function createAssistantHandler(options) {
 			}
 		});
 		ctx.useAgent({
-			systemPrompt: buildHortonSystemPrompt(effectiveCwd, {
+			systemPrompt: buildHortonSystemPrompt(sandboxCwd, {
 				hasDocsSupport: Boolean(docsSupport),
 				hasSkills,
 				docsUrl,
@@ -1385,7 +1386,6 @@ function registerHorton(registry, options) {
 		serverLog.warn(`[horton-docs] warmup failed: ${error instanceof Error ? error.message : String(error)}`);
 	});
 	const assistantHandler = createAssistantHandler({
-		workingDirectory,
 		streamFn,
 		docsSupport,
 		docsSearchTool,
@@ -1442,26 +1442,26 @@ function parseWorkerArgs(value) {
 	if (typeof value.reasoningEffort === `string` && REASONING_EFFORT_VALUES.includes(value.reasoningEffort)) args.reasoningEffort = value.reasoningEffort;
 	return args;
 }
-function buildToolsForWorker(tools, workingDirectory, ctx, readSet) {
+function buildToolsForWorker(tools, sandbox, ctx, readSet) {
 	const out = [];
 	for (const name of tools) switch (name) {
 		case `bash`:
-			out.push((0, __electric_ax_agents_runtime_tools.createBashTool)(workingDirectory));
+			out.push((0, __electric_ax_agents_runtime_tools.createBashTool)(sandbox));
 			break;
 		case `read`:
-			out.push((0, __electric_ax_agents_runtime_tools.createReadFileTool)(workingDirectory, readSet));
+			out.push((0, __electric_ax_agents_runtime_tools.createReadFileTool)(sandbox, readSet));
 			break;
 		case `write`:
-			out.push((0, __electric_ax_agents_runtime_tools.createWriteTool)(workingDirectory, readSet));
+			out.push((0, __electric_ax_agents_runtime_tools.createWriteTool)(sandbox, readSet));
 			break;
 		case `edit`:
-			out.push((0, __electric_ax_agents_runtime_tools.createEditTool)(workingDirectory, readSet));
+			out.push((0, __electric_ax_agents_runtime_tools.createEditTool)(sandbox, readSet));
 			break;
 		case `web_search`:
 			out.push(__electric_ax_agents_runtime_tools.braveSearchTool);
 			break;
 		case `fetch_url`:
-			out.push(__electric_ax_agents_runtime_tools.fetchUrlTool);
+			out.push((0, __electric_ax_agents_runtime_tools.createFetchUrlTool)(sandbox));
 			break;
 		case `spawn_worker`:
 			out.push(createSpawnWorkerTool(ctx));
@@ -1569,13 +1569,13 @@ function buildSharedStateTools(shared, schema, mode) {
 	return tools;
 }
 function registerWorker(registry, options) {
-	const { workingDirectory, streamFn, modelCatalog } = options;
+	const { streamFn, modelCatalog } = options;
 	registry.define(`worker`, {
 		description: `Internal — generic worker spawned by other agents. Configure via spawn args (systemPrompt + tools + optional sharedDb).`,
 		async handler(ctx) {
 			const args = parseWorkerArgs(ctx.args);
 			const readSet = new Set();
-			const builtinTools = buildToolsForWorker(args.tools, workingDirectory, ctx, readSet);
+			const builtinTools = buildToolsForWorker(args.tools, ctx.sandbox, ctx, readSet);
 			const modelConfig = resolveBuiltinModelConfig(modelCatalog, args);
 			const sharedStateTools = [];
 			if (args.sharedDb) {
@@ -1654,6 +1654,7 @@ async function createBuiltinAgentHandler(options) {
 		modelCatalog
 	});
 	typeNames.push(`worker`);
+	const sandboxProfiles = await buildBuiltinSandboxProfiles(cwd);
 	const runtime = (0, __electric_ax_agents_runtime.createRuntimeHandler)({
 		baseUrl: agentServerUrl,
 		serveEndpoint,
@@ -1664,7 +1665,8 @@ async function createBuiltinAgentHandler(options) {
 		idleTimeout: 5 * 6e4,
 		createElectricTools: createBuiltinElectricTools(createElectricTools),
 		publicUrl,
-		name: runtimeName ?? `builtin-agents`
+		name: runtimeName ?? `builtin-agents`,
+		sandboxProfiles
 	});
 	return {
 		handler: runtime.onEnter,
@@ -1688,6 +1690,85 @@ async function registerBuiltinAgentTypes(bootstrap) {
 	serverLog.info(`[builtin-agents] ${bootstrap.typeNames.length} built-in agent types ready: ${bootstrap.typeNames.join(`, `)}`);
 }
 const registerAgentTypes = registerBuiltinAgentTypes;
+/**
+* Guard so repeated `buildBuiltinSandboxProfiles` calls in one process don't
+* re-run the boot sweep.
+*/
+let dockerSweptOnBoot = false;
+function sweepOrphanedDockerSandboxesOnce(sweep) {
+	if (dockerSweptOnBoot) return;
+	dockerSweptOnBoot = true;
+	sweep().then((removed) => {
+		if (removed.length > 0) serverLog.info(`[builtin-agents] docker sandbox boot sweep removed ${removed.length} leftover container(s)`);
+	}).catch((err) => serverLog.warn(`[builtin-agents] docker sandbox boot sweep error: ${err instanceof Error ? err.message : String(err)}`));
+}
+/**
+* Built-in sandbox profiles. `local` is always available. `docker` is
+* gated on Docker being reachable so a user without Docker installed
+* sees only what works — the UI never offers a non-functional choice.
+*/
+async function buildBuiltinSandboxProfiles(workingDirectory) {
+	const profiles = [{
+		name: `local`,
+		label: `Local`,
+		description: `Runs on the host without isolation. Full filesystem access.`,
+		factory: ({ args }) => (0, __electric_ax_agents_runtime_sandbox.chooseDefaultSandbox)(resolveCwd(args, workingDirectory))
+	}];
+	try {
+		const { isDockerAvailable } = await import(`@electric-ax/agents-runtime/sandbox/docker`);
+		if (await isDockerAvailable()) {
+			const { dockerSandbox, sweepOrphanedDockerSandboxes } = await import(`@electric-ax/agents-runtime/sandbox/docker`);
+			sweepOrphanedDockerSandboxesOnce(sweepOrphanedDockerSandboxes);
+			profiles.push({
+				name: `docker`,
+				label: `Docker`,
+				description: `Runs in a hardened Docker container: dropped capabilities, no privilege escalation, and CPU/memory/process limits. The chosen working directory is mounted read-write and, by default, network egress is unrestricted (allow-all).`,
+				factory: ({ args, sandboxKey, persistent, owner, entityType, entityUrl }) => {
+					const cwd = readWorkingDirectoryArg(args);
+					return dockerSandbox({
+						initialNetworkPolicy: { mode: `allow-all` },
+						extraMounts: cwd ? [{
+							hostPath: cwd,
+							containerPath: `/work`,
+							readOnly: false
+						}] : void 0,
+						sandboxKey,
+						persistent,
+						owner,
+						entityType,
+						entityUrl
+					});
+				}
+			});
+		} else serverLog.info(`[builtin-agents] docker daemon not reachable — docker sandbox profile not registered`);
+	} catch (err) {
+		serverLog.warn(`[builtin-agents] failed to probe docker availability: ${err instanceof Error ? err.message : String(err)}`);
+	}
+	if (process.env.E2B_API_KEY) if (await (0, __electric_ax_agents_runtime_sandbox.isE2BAvailable)()) profiles.push({
+		name: `e2b`,
+		label: `E2B`,
+		description: `Runs in a remote E2B microVM. Persistent sandboxes survive across wakes and are reachable from any runner.`,
+		remote: true,
+		factory: ({ sandboxKey, persistent, owner }) => (0, __electric_ax_agents_runtime_sandbox.remoteSandbox)({
+			provider: `e2b`,
+			apiKey: process.env.E2B_API_KEY,
+			sandboxKey,
+			persistent,
+			owner,
+			initialNetworkPolicy: { mode: `allow-all` }
+		})
+	});
+	else serverLog.info(`[builtin-agents] E2B_API_KEY set but the "e2b" package is not installed — e2b sandbox profile not registered`);
+	console.log(`[builtin-agents] sandbox profiles advertised: ${profiles.map((p) => p.name).join(`, `)}`);
+	return profiles;
+}
+function readWorkingDirectoryArg(args) {
+	const v = args.workingDirectory;
+	return typeof v === `string` && v.trim().length > 0 ? v : null;
+}
+function resolveCwd(args, fallback) {
+	return readWorkingDirectoryArg(args) ?? fallback;
+}
 
 //#endregion
 //#region src/server.ts
@@ -1896,6 +1977,7 @@ 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 profiles = this.bootstrap?.runtime.sandboxProfileDescriptors ?? [];
 		const response = await fetch((0, __electric_ax_agents_runtime.appendPathToUrl)(this.options.agentServerUrl, `/_electric/runners`), {
 			method: `POST`,
 			headers,
@@ -1904,7 +1986,8 @@ var BuiltinAgentsServer = class {
 				owner_principal: pullWake.ownerPrincipal,
 				label: pullWake.label ?? `Built-in agents`,
 				kind: `local`,
-				admin_status: `enabled`
+				admin_status: `enabled`,
+				sandbox_profiles: profiles
 			})
 		});
 		if (!response.ok) throw new Error(`Failed to register pull-wake runner ${pullWake.runnerId}: ${response.status} ${await response.text()}`);

package/dist/index.d.cts

@@ -2,6 +2,7 @@ import { AgentConfig, AgentTool, AvailableProvider, DispatchPolicy, EntityRegist
 import { AgentTool as AgentTool$1, StreamFn } from "@mariozechner/pi-agent-core";
 import { IncomingMessage, ServerResponse } from "node:http";
 import { ListedEntry as McpListedEntry, McpConfig, McpServerConfig, McpServerConfig as McpServerConfig$1, Registry, Registry as McpRegistry, RegistrySnapshot, RegistrySubscriber } from "@electric-ax/agents-mcp";
+import { Sandbox } from "@electric-ax/agents-runtime/sandbox";
 import { ChangeEvent } from "@durable-streams/state";
 import { braveSearchTool } from "@electric-ax/agents-runtime/tools";
 
@@ -167,7 +168,7 @@ declare function buildHortonSystemPrompt(workingDirectory: string, opts?: {
   modelProvider?: string;
   modelId?: string;
 }): string;
-declare function createHortonTools(workingDirectory: string, ctx: HandlerContext, readSet: Set<string>, opts?: {
+declare function createHortonTools(sandbox: Sandbox, ctx: HandlerContext, readSet: Set<string>, opts?: {
   docsSearchTool?: AgentTool$1;
   modelConfig?: ReturnType<typeof resolveBuiltinModelConfig>;
   modelCatalog?: BuiltinModelCatalog;

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { AgentConfig, AgentTool, AvailableProvider, DispatchPolicy, EntityRegistry, HandlerContext, HeadersProvider, ProcessWakeConfig, PullWakeRunnerConfig, RuntimeHandler, SkillsRegistry, WakeEvent } from "@electric-ax/agents-runtime";
 import { braveSearchTool } from "@electric-ax/agents-runtime/tools";
+import { Sandbox } from "@electric-ax/agents-runtime/sandbox";
 import { ListedEntry as McpListedEntry, McpConfig, McpServerConfig, McpServerConfig as McpServerConfig$1, Registry, Registry as McpRegistry, RegistrySnapshot, RegistrySubscriber } from "@electric-ax/agents-mcp";
 import { AgentTool as AgentTool$1, StreamFn } from "@mariozechner/pi-agent-core";
 import { IncomingMessage, ServerResponse } from "node:http";
@@ -167,7 +168,7 @@ declare function buildHortonSystemPrompt(workingDirectory: string, opts?: {
   modelProvider?: string;
   modelId?: string;
 }): string;
-declare function createHortonTools(workingDirectory: string, ctx: HandlerContext, readSet: Set<string>, opts?: {
+declare function createHortonTools(sandbox: Sandbox, ctx: HandlerContext, readSet: Set<string>, opts?: {
   docsSearchTool?: AgentTool$1;
   modelConfig?: ReturnType<typeof resolveBuiltinModelConfig>;
   modelCatalog?: BuiltinModelCatalog;

package/dist/index.js

@@ -2,12 +2,13 @@ import { mergeElectricPrincipalHeader } from "./server-headers-KD5yHFYT.js";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { MOONSHOT_API_BASE_URL, MOONSHOT_PROVIDER, appendPathToUrl, completeWithLowCostModel, createEntityRegistry, createPullWakeRunner, createRuntimeHandler, createSkillTools, createSkillsRegistry, db, detectAvailableProviders, getMoonshotApiKey, getMoonshotModels, readCodexAccessToken, registerToolProvider, unregisterToolProvider } from "@electric-ax/agents-runtime";
-import { braveSearchTool, braveSearchTool as braveSearchTool$1, createBashTool, createEditTool, createEventSourceTools, createFetchUrlTool, createReadFileTool, createSendTool, createWriteTool, fetchUrlTool } from "@electric-ax/agents-runtime/tools";
-import fs from "node:fs";
+import { braveSearchTool, braveSearchTool as braveSearchTool$1, createBashTool, createEditTool, createEventSourceTools, createFetchUrlTool, createReadFileTool, createSendTool, createWriteTool } from "@electric-ax/agents-runtime/tools";
+import { chooseDefaultSandbox, isE2BAvailable, remoteSandbox } from "@electric-ax/agents-runtime/sandbox";
+import fsSync from "node:fs";
 import pino from "pino";
 import { z } from "zod";
 import { createHash } from "node:crypto";
-import fs$1 from "node:fs/promises";
+import fs from "node:fs/promises";
 import Database from "better-sqlite3";
 import { Type } from "@sinclair/typebox";
 import { load } from "sqlite-vec";
@@ -27,7 +28,7 @@ function getLogger() {
 	try {
 		if (USE_FILE_LOGS) {
 			const logDir = process.env.ELECTRIC_AGENTS_LOG_DIR ?? path.resolve(process.cwd(), `logs`);
-			fs.mkdirSync(logDir, { recursive: true });
+			fsSync.mkdirSync(logDir, { recursive: true });
 			const logFile = path.join(logDir, `builtin-agents-${Date.now()}.jsonl`);
 			streams.push({ stream: pino.destination({
 				dest: logFile,
@@ -161,7 +162,7 @@ function normalizeWhitespace(value) {
 }
 async function collectMarkdownFiles(root) {
 	async function walk(dir) {
-		const entries = await fs$1.readdir(dir, { withFileTypes: true });
+		const entries = await fs.readdir(dir, { withFileTypes: true });
 		const files = [];
 		for (const entry of entries) {
 			const fullPath = path.join(dir, entry.name);
@@ -337,7 +338,7 @@ function resolveDocsRoot(workingDirectory) {
 			requireIndex: false
 		}
 	].filter((value) => Boolean(value));
-	for (const candidate of candidates) if (fs.existsSync(candidate.path) && (!candidate.requireIndex || fs.existsSync(path.join(candidate.path, `index.md`)))) return candidate.path;
+	for (const candidate of candidates) if (fsSync.existsSync(candidate.path) && (!candidate.requireIndex || fsSync.existsSync(path.join(candidate.path, `index.md`)))) return candidate.path;
 	return null;
 }
 var DocsKnowledgeBase = class {
@@ -358,7 +359,7 @@ var DocsKnowledgeBase = class {
 		this.readyPromise = this.ensureIngested();
 	}
 	openDatabase() {
-		fs.mkdirSync(path.dirname(this.dbPath), { recursive: true });
+		fsSync.mkdirSync(path.dirname(this.dbPath), { recursive: true });
 		try {
 			const db$1 = new Database(this.dbPath);
 			load(db$1);
@@ -425,11 +426,11 @@ var DocsKnowledgeBase = class {
 		};
 	}
 	async ensureIngested() {
-		await fs$1.mkdir(path.dirname(this.dbPath), { recursive: true });
+		await fs.mkdir(path.dirname(this.dbPath), { recursive: true });
 		const files = (await collectMarkdownFiles(this.docsRoot)).sort();
 		const docs = await Promise.all(files.map(async (filePath) => ({
 			path: path.relative(this.docsRoot, filePath),
-			content: await fs$1.readFile(filePath, `utf8`)
+			content: await fs.readFile(filePath, `utf8`)
 		})));
 		const fingerprint = createFingerprint(docs);
 		if (!this.db) {
@@ -764,7 +765,8 @@ function createSpawnWorkerTool(ctx, modelConfig) {
 					wake: {
 						on: `runFinished`,
 						includeResponse: true
-					}
+					},
+					sandbox: `inherit`
 				});
 				const workerUrl = handle.entityUrl;
 				return {
@@ -1152,19 +1154,19 @@ function getToolName(tool) {
 	const name = tool.name;
 	return typeof name === `string` ? name : null;
 }
-function createHortonTools(workingDirectory, ctx, readSet, opts = {}) {
+function createHortonTools(sandbox, ctx, readSet, opts = {}) {
 	return [
-		createBashTool(workingDirectory),
-		createReadFileTool(workingDirectory, readSet),
-		createWriteTool(workingDirectory, readSet),
-		createEditTool(workingDirectory, readSet),
+		createBashTool(sandbox),
+		createReadFileTool(sandbox, readSet),
+		createWriteTool(sandbox, readSet),
+		createEditTool(sandbox, readSet),
 		braveSearchTool$1,
-		...opts.modelCatalog && opts.modelConfig ? [createFetchUrlTool({
+		...opts.modelCatalog && opts.modelConfig ? [createFetchUrlTool(sandbox, {
 			catalog: opts.modelCatalog,
 			modelConfig: opts.modelConfig,
 			log: (message) => serverLog.info(message),
 			logPrefix: opts.logPrefix ?? `[horton]`
-		})] : [fetchUrlTool],
+		})] : [createFetchUrlTool(sandbox)],
 		createSpawnWorkerTool(ctx, opts.modelConfig),
 		createSendTool(ctx.send, { selfEntityUrl: ctx.entityUrl }),
 		...opts.docsSearchTool ? [opts.docsSearchTool] : []
@@ -1218,11 +1220,10 @@ async function extractFirstUserMessage(ctx) {
 function messageSeq(message) {
 	return typeof message._seq === `number` ? message._seq : -1;
 }
-function readAgentsMd(workingDirectory) {
-	const agentsMdPath = path.join(workingDirectory, `AGENTS.md`);
+async function readAgentsMd(sandbox) {
+	const agentsMdPath = path.posix.join(sandbox.workingDirectory, `AGENTS.md`);
 	try {
-		if (!fs.existsSync(agentsMdPath) || !fs.statSync(agentsMdPath).isFile()) return null;
-		const content = fs.readFileSync(agentsMdPath, `utf8`);
+		const content = (await sandbox.readFile(agentsMdPath)).toString(`utf8`);
 		return [
 			`<context_file kind="instructions" path="${agentsMdPath}">`,
 			content,
@@ -1233,16 +1234,16 @@ function readAgentsMd(workingDirectory) {
 	}
 }
 function createAssistantHandler(options) {
-	const { workingDirectory, streamFn, docsSupport, docsSearchTool, skillsRegistry, modelCatalog, docsUrl } = options;
+	const { streamFn, docsSupport, docsSearchTool, skillsRegistry, modelCatalog, docsUrl } = options;
 	const hasSkills = Boolean(skillsRegistry && skillsRegistry.catalog.size > 0);
 	return async function assistantHandler(ctx, wake) {
 		const readSet = new Set();
-		const effectiveCwd = typeof ctx.args.workingDirectory === `string` && ctx.args.workingDirectory.trim().length > 0 ? ctx.args.workingDirectory : workingDirectory;
 		const modelConfig = resolveBuiltinModelConfig(modelCatalog, ctx.args);
-		const agentsMd = readAgentsMd(effectiveCwd);
+		const sandboxCwd = ctx.sandbox.workingDirectory;
+		const agentsMd = await readAgentsMd(ctx.sandbox);
 		const tools = [
 			...ctx.electricTools,
-			...createHortonTools(effectiveCwd, ctx, readSet, {
+			...createHortonTools(ctx.sandbox, ctx, readSet, {
 				docsSearchTool,
 				modelConfig,
 				modelCatalog,
@@ -1333,7 +1334,7 @@ function createAssistantHandler(options) {
 			}
 		});
 		ctx.useAgent({
-			systemPrompt: buildHortonSystemPrompt(effectiveCwd, {
+			systemPrompt: buildHortonSystemPrompt(sandboxCwd, {
 				hasDocsSupport: Boolean(docsSupport),
 				hasSkills,
 				docsUrl,
@@ -1361,7 +1362,6 @@ function registerHorton(registry, options) {
 		serverLog.warn(`[horton-docs] warmup failed: ${error instanceof Error ? error.message : String(error)}`);
 	});
 	const assistantHandler = createAssistantHandler({
-		workingDirectory,
 		streamFn,
 		docsSupport,
 		docsSearchTool,
@@ -1418,26 +1418,26 @@ function parseWorkerArgs(value) {
 	if (typeof value.reasoningEffort === `string` && REASONING_EFFORT_VALUES.includes(value.reasoningEffort)) args.reasoningEffort = value.reasoningEffort;
 	return args;
 }
-function buildToolsForWorker(tools, workingDirectory, ctx, readSet) {
+function buildToolsForWorker(tools, sandbox, ctx, readSet) {
 	const out = [];
 	for (const name of tools) switch (name) {
 		case `bash`:
-			out.push(createBashTool(workingDirectory));
+			out.push(createBashTool(sandbox));
 			break;
 		case `read`:
-			out.push(createReadFileTool(workingDirectory, readSet));
+			out.push(createReadFileTool(sandbox, readSet));
 			break;
 		case `write`:
-			out.push(createWriteTool(workingDirectory, readSet));
+			out.push(createWriteTool(sandbox, readSet));
 			break;
 		case `edit`:
-			out.push(createEditTool(workingDirectory, readSet));
+			out.push(createEditTool(sandbox, readSet));
 			break;
 		case `web_search`:
 			out.push(braveSearchTool$1);
 			break;
 		case `fetch_url`:
-			out.push(fetchUrlTool);
+			out.push(createFetchUrlTool(sandbox));
 			break;
 		case `spawn_worker`:
 			out.push(createSpawnWorkerTool(ctx));
@@ -1545,13 +1545,13 @@ function buildSharedStateTools(shared, schema, mode) {
 	return tools;
 }
 function registerWorker(registry, options) {
-	const { workingDirectory, streamFn, modelCatalog } = options;
+	const { streamFn, modelCatalog } = options;
 	registry.define(`worker`, {
 		description: `Internal — generic worker spawned by other agents. Configure via spawn args (systemPrompt + tools + optional sharedDb).`,
 		async handler(ctx) {
 			const args = parseWorkerArgs(ctx.args);
 			const readSet = new Set();
-			const builtinTools = buildToolsForWorker(args.tools, workingDirectory, ctx, readSet);
+			const builtinTools = buildToolsForWorker(args.tools, ctx.sandbox, ctx, readSet);
 			const modelConfig = resolveBuiltinModelConfig(modelCatalog, args);
 			const sharedStateTools = [];
 			if (args.sharedDb) {
@@ -1630,6 +1630,7 @@ async function createBuiltinAgentHandler(options) {
 		modelCatalog
 	});
 	typeNames.push(`worker`);
+	const sandboxProfiles = await buildBuiltinSandboxProfiles(cwd);
 	const runtime = createRuntimeHandler({
 		baseUrl: agentServerUrl,
 		serveEndpoint,
@@ -1640,7 +1641,8 @@ async function createBuiltinAgentHandler(options) {
 		idleTimeout: 5 * 6e4,
 		createElectricTools: createBuiltinElectricTools(createElectricTools),
 		publicUrl,
-		name: runtimeName ?? `builtin-agents`
+		name: runtimeName ?? `builtin-agents`,
+		sandboxProfiles
 	});
 	return {
 		handler: runtime.onEnter,
@@ -1664,6 +1666,85 @@ async function registerBuiltinAgentTypes(bootstrap) {
 	serverLog.info(`[builtin-agents] ${bootstrap.typeNames.length} built-in agent types ready: ${bootstrap.typeNames.join(`, `)}`);
 }
 const registerAgentTypes = registerBuiltinAgentTypes;
+/**
+* Guard so repeated `buildBuiltinSandboxProfiles` calls in one process don't
+* re-run the boot sweep.
+*/
+let dockerSweptOnBoot = false;
+function sweepOrphanedDockerSandboxesOnce(sweep) {
+	if (dockerSweptOnBoot) return;
+	dockerSweptOnBoot = true;
+	sweep().then((removed) => {
+		if (removed.length > 0) serverLog.info(`[builtin-agents] docker sandbox boot sweep removed ${removed.length} leftover container(s)`);
+	}).catch((err) => serverLog.warn(`[builtin-agents] docker sandbox boot sweep error: ${err instanceof Error ? err.message : String(err)}`));
+}
+/**
+* Built-in sandbox profiles. `local` is always available. `docker` is
+* gated on Docker being reachable so a user without Docker installed
+* sees only what works — the UI never offers a non-functional choice.
+*/
+async function buildBuiltinSandboxProfiles(workingDirectory) {
+	const profiles = [{
+		name: `local`,
+		label: `Local`,
+		description: `Runs on the host without isolation. Full filesystem access.`,
+		factory: ({ args }) => chooseDefaultSandbox(resolveCwd(args, workingDirectory))
+	}];
+	try {
+		const { isDockerAvailable } = await import(`@electric-ax/agents-runtime/sandbox/docker`);
+		if (await isDockerAvailable()) {
+			const { dockerSandbox, sweepOrphanedDockerSandboxes } = await import(`@electric-ax/agents-runtime/sandbox/docker`);
+			sweepOrphanedDockerSandboxesOnce(sweepOrphanedDockerSandboxes);
+			profiles.push({
+				name: `docker`,
+				label: `Docker`,
+				description: `Runs in a hardened Docker container: dropped capabilities, no privilege escalation, and CPU/memory/process limits. The chosen working directory is mounted read-write and, by default, network egress is unrestricted (allow-all).`,
+				factory: ({ args, sandboxKey, persistent, owner, entityType, entityUrl }) => {
+					const cwd = readWorkingDirectoryArg(args);
+					return dockerSandbox({
+						initialNetworkPolicy: { mode: `allow-all` },
+						extraMounts: cwd ? [{
+							hostPath: cwd,
+							containerPath: `/work`,
+							readOnly: false
+						}] : void 0,
+						sandboxKey,
+						persistent,
+						owner,
+						entityType,
+						entityUrl
+					});
+				}
+			});
+		} else serverLog.info(`[builtin-agents] docker daemon not reachable — docker sandbox profile not registered`);
+	} catch (err) {
+		serverLog.warn(`[builtin-agents] failed to probe docker availability: ${err instanceof Error ? err.message : String(err)}`);
+	}
+	if (process.env.E2B_API_KEY) if (await isE2BAvailable()) profiles.push({
+		name: `e2b`,
+		label: `E2B`,
+		description: `Runs in a remote E2B microVM. Persistent sandboxes survive across wakes and are reachable from any runner.`,
+		remote: true,
+		factory: ({ sandboxKey, persistent, owner }) => remoteSandbox({
+			provider: `e2b`,
+			apiKey: process.env.E2B_API_KEY,
+			sandboxKey,
+			persistent,
+			owner,
+			initialNetworkPolicy: { mode: `allow-all` }
+		})
+	});
+	else serverLog.info(`[builtin-agents] E2B_API_KEY set but the "e2b" package is not installed — e2b sandbox profile not registered`);
+	console.log(`[builtin-agents] sandbox profiles advertised: ${profiles.map((p) => p.name).join(`, `)}`);
+	return profiles;
+}
+function readWorkingDirectoryArg(args) {
+	const v = args.workingDirectory;
+	return typeof v === `string` && v.trim().length > 0 ? v : null;
+}
+function resolveCwd(args, fallback) {
+	return readWorkingDirectoryArg(args) ?? fallback;
+}
 
 //#endregion
 //#region src/server.ts
@@ -1872,6 +1953,7 @@ 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 profiles = this.bootstrap?.runtime.sandboxProfileDescriptors ?? [];
 		const response = await fetch(appendPathToUrl(this.options.agentServerUrl, `/_electric/runners`), {
 			method: `POST`,
 			headers,
@@ -1880,7 +1962,8 @@ var BuiltinAgentsServer = class {
 				owner_principal: pullWake.ownerPrincipal,
 				label: pullWake.label ?? `Built-in agents`,
 				kind: `local`,
-				admin_status: `enabled`
+				admin_status: `enabled`,
+				sandbox_profiles: profiles
 			})
 		});
 		if (!response.ok) throw new Error(`Failed to register pull-wake runner ${pullWake.runnerId}: ${response.status} ${await response.text()}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@electric-ax/agents",
-  "version": "0.4.11",
+  "version": "0.4.12",
   "description": "Built-in Electric Agents runtimes such as Horton and worker",
   "repository": {
     "type": "git",
@@ -49,7 +49,7 @@
     "sqlite-vec": "^0.1.9",
     "zod": "^4.3.6",
     "@electric-ax/agents-mcp": "0.2.2",
-    "@electric-ax/agents-runtime": "0.3.7"
+    "@electric-ax/agents-runtime": "0.3.8"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",