@electric-ax/agents 0.4.14 → 0.4.15

package/dist/entrypoint.js

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
 import path from "node:path";
-import { Agent, cacheStores, interceptors, setGlobalDispatcher } from "undici";
+import { cacheStores, getGlobalDispatcher, interceptors, setGlobalDispatcher } from "undici";
 import fs from "node:fs";
 import pino from "pino";
 import { fileURLToPath } from "node:url";
 import { MOONSHOT_API_BASE_URL, MOONSHOT_PROVIDER, appendPathToUrl, buildSkillSlashCommands, completeWithLowCostModel, createContextSkillLoader, createEntityRegistry, createPullWakeRunner, createRuntimeHandler, createSkillsRegistry, db, detectAvailableProviders, getMoonshotApiKey, getMoonshotModel, getMoonshotModels, readCodexAccessToken, registerToolProvider, unregisterToolProvider } from "@electric-ax/agents-runtime";
-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 { braveSearchTool, createBashTool, createEditTool, createEventSourceTools, createFetchUrlTool, createReadFileTool, createScheduleTools, createSendTool, createWriteTool } from "@electric-ax/agents-runtime/tools";
+import { chooseDefaultSandbox, isE2BAvailable, lazySandbox, remoteSandbox } from "@electric-ax/agents-runtime/sandbox";
 import { z } from "zod";
 import { createHash } from "node:crypto";
 import fs$1 from "node:fs/promises";
@@ -25,7 +25,7 @@ function installDurableStreamsFetchCache(options = {}) {
 		location: options.sqliteLocation,
 		maxCount: options.maxCount
 	}) : new cacheStores.MemoryCacheStore({ maxSize: MEMORY_CACHE_SIZE_BYTES });
-	setGlobalDispatcher(new Agent().compose(interceptors.cache({ store })));
+	setGlobalDispatcher(getGlobalDispatcher().compose(interceptors.cache({ store })));
 }
 
 //#endregion
@@ -806,6 +806,60 @@ function createSpawnWorkerTool(ctx, modelConfig) {
 	};
 }
 
+//#endregion
+//#region src/tools/fork.ts
+function createForkTool(ctx) {
+	return {
+		name: `fork`,
+		label: `Fork`,
+		description: `Fork a session at its latest completed agent response, producing a child copy of the conversation up to that point. The new fork is YOUR child — same parent-ownership model as a spawned worker — and it reports back to you the same way: when its next run finishes you'll be woken with its response. End your turn after forking.
+
+Prefer supplying an 'initialMessage' so the fork is dispatched immediately in a single call — no follow-up 'send' needed. If you omit it, the fork boots idle and you'll need to call 'send' afterwards. For chat-rendered messages use the shape \`{ "text": "..." }\` so the prompt shows up in the chat UI.
+
+Use this to explore multiple alternative continuations in parallel from the same starting point. End your current turn first so the fork includes your latest response — the anchor is always the most recently completed run.
+
+Omit 'entityUrl' to fork your own session. Pass a different session's URL to fork that session instead (the new fork is still your child). The optional 'id' names the new fork's instance — useful when you want stable, predictable URLs (e.g. labelling branches in a parallel exploration); omit to let the server mint one.`,
+		parameters: Type.Object({
+			entityUrl: Type.Optional(Type.String({ description: `URL of the session to fork. Omit to fork your own session.` })),
+			id: Type.Optional(Type.String({ description: `Instance id for the new fork (the \`<id>\` in \`/horton/<id>\`). Mirrors spawn_worker's id parameter. Omit to let the server assign one.` })),
+			initialMessage: Type.Optional(Type.Any({ description: `Initial inbox message delivered to the fork by the server in the same round-trip — the fork wakes and starts running immediately, no follow-up 'send' needed. Use the shape \`{ "text": "..." }\` for chat-rendered prompts. Omit to leave the fork idle (then call 'send' separately).` })),
+			tags: Type.Optional(Type.Record(Type.String(), Type.String(), { description: `Optional tags stamped on the new fork, on top of those copied from the source. Useful for labelling experiments (e.g. \`{ "experiment": "ecosystem-maturity" }\`).` }))
+		}),
+		execute: async (_toolCallId, params) => {
+			const { entityUrl, id, initialMessage, tags } = params;
+			try {
+				const opts = {
+					...initialMessage !== void 0 && { initialMessage },
+					...tags !== void 0 && { tags }
+				};
+				const forkId = id ?? `fork-${nanoid(10)}`;
+				const handle = entityUrl !== void 0 ? await ctx.fork(entityUrl, forkId, opts) : await ctx.forkSelf(forkId, opts);
+				const dispatchNote = initialMessage !== void 0 ? `The initial message has been delivered to the fork — it will start running.` : `The fork boots idle — use the 'send' tool to dispatch a follow-up prompt.`;
+				return {
+					content: [{
+						type: `text`,
+						text: `Forked at ${handle.entityUrl}. ${dispatchNote} End your turn; you'll wake with the fork's response when its next run finishes (same as a spawned worker).`
+					}],
+					details: {
+						forked: true,
+						forkUrl: handle.entityUrl
+					}
+				};
+			} catch (err) {
+				const message = err instanceof Error ? err.message : `Unknown error`;
+				serverLog.warn(`[fork tool] failed to fork ${entityUrl ?? `<self>`}: ${message}`, err instanceof Error ? err : void 0);
+				return {
+					content: [{
+						type: `text`,
+						text: `Error forking session: ${message}`
+					}],
+					details: { forked: false }
+				};
+			}
+		}
+	};
+}
+
 //#endregion
 //#region src/model-catalog.ts
 const MODEL_INPUTS_SCHEMA_DEF = `electricModelInputs`;
@@ -1096,6 +1150,7 @@ async function generateTitle(userMessage, llmCall, onFallback) {
 function buildHortonSystemPrompt(workingDirectory, opts = {}) {
 	const docsTools = opts.hasDocsSupport ? `\n- search_electric_agents_docs: hybrid search over the built-in Electric Agents docs index` : ``;
 	const eventSourceTools = opts.hasEventSourceTools ? `\n- list_event_sources: list external webhook/event feeds you can subscribe to, including available buckets and parameters\n- subscribe_event_source: subscribe yourself to one of those feeds or buckets so matching future events wake you\n- list_event_source_subscriptions: list your active event source subscriptions\n- unsubscribe_event_source: remove one of your event source subscriptions by id` : ``;
+	const scheduleTools = opts.hasScheduleTools ? `\n- upsert_cron_schedule: create or update a recurring cron wake for yourself. Always include payload with the concrete instruction/message you should receive when the cron fires.\n- delete_schedule: delete one of your cron or future-send schedules by stable id\n- list_schedules: list your manifest-backed cron and future-send schedules` : ``;
 	const skillsTools = opts.hasSkills ? `\n- use_skill: load a skill (knowledge, instructions, or a tutorial) into your context to help with the user's request\n- remove_skill: unload a skill from context when you're done with it` : ``;
 	const docsGuidance = opts.hasDocsSupport ? `\n- For ANY question about Electric Agents or this framework, ALWAYS use search_electric_agents_docs FIRST. Do not use web_search or fetch_url for Electric Agents topics unless the docs search returns no useful results.\n- The search tool returns chunk content directly — you do not need to read the source files.\n- Use repo read/bash tools only for non-doc files or when you need to inspect exact implementation code in the workspace.` : ``;
 	const skillsGuidance = opts.hasSkills ? `\n# Skills\nYou have access to skills — specialized knowledge and guided workflows you can load on demand. Your context includes a skills catalog listing what's available. When the user's request matches a skill's description or keywords, load it with use_skill.
@@ -1149,8 +1204,9 @@ When a user opens with a greeting ("hi", "hello", "hey", etc.) or a broad statem
 - web_search: search the web
 - fetch_url: fetch and convert a URL to markdown
 - spawn_worker: dispatch a subagent for an isolated task
+- fork: spawn a child session that inherits this conversation's history up to the latest completed response. Same parent-ownership model as spawn_worker — when the fork's next run finishes, you'll wake with its response.
 - send: send a message to an Electric Agent/entity. To schedule future work for yourself, call send with self: true and afterMs.
-${eventSourceTools}${docsTools}${skillsTools}
+${eventSourceTools}${scheduleTools}${docsTools}${skillsTools}
 
 # Working with files
 - Prefer edit over write when modifying existing files.
@@ -1177,6 +1233,20 @@ When you spawn a worker, write its system prompt the way you'd brief a colleague
 
 After spawning, end your turn (optionally with a brief "I've dispatched a worker for X; I'll respond when it finishes"). When the worker finishes, you'll receive a message describing which worker completed and what it returned. Multiple workers may finish at different times — check the message for the worker URL to know which one you're hearing about.
 
+# When to fork (vs spawn_worker)
+\`fork\` is the **sibling primitive to spawn_worker** — both create a child you own, both report back to you on a future wake. The difference is only in what the child boots with:
+
+- **spawn_worker** → child boots with an **empty context**; you brief it from scratch via a system prompt + initial message. Use when the worker doesn't need to know what we've said so far.
+- **fork** → child boots with **a copy of THIS conversation's history** up to your latest completed response. Use when each child needs to know what we've already established (the user's framing, your prior analysis, an earlier decision, the constraints, etc.).
+
+**Trigger pattern: prefer fork when generating multiple variants the user wants to compare.** If the user asks for "three different X" or "two takes on Y" or "evaluate these N approaches" and each variant should reflect the conversation we've had so far, **don't inline the variants in one response** — fork once per variant, send each a tailored follow-up, and synthesize when they report back. Inlining feels faster but the variants end up cross-contaminating in your single response; forks keep them honestly independent. The exception is trivial generation (a list of names, a couple of one-liners) where each variant takes a sentence — there, inline is fine.
+
+Workflow when forking yourself for parallel exploration:
+1. **End your current turn first.** The fork's history stops at your *latest completed* run. Anything you say mid-turn is NOT in the fork. If you want your analysis baked into each fork, finish it and end the turn before calling fork.
+2. On the next wake, call \`fork\` once per branch with a different \`initialMessage\` per call — that's how the branches diverge from a shared starting point. Each fork is YOUR child, just like a spawned worker, and the server delivers \`initialMessage\` to the fork in the same round-trip, so the fork starts running immediately (no follow-up \`send\` needed). Use the shape \`{ text: "..." }\` for the message so it renders in the chat UI.
+3. End your turn. You'll wake automatically when each fork's run finishes (same wake mechanism as spawn_worker); the wake message identifies the fork and includes its response.
+4. If you're waiting on multiple forks, don't synthesize on the first wake — quietly end the turn with "got N of M, waiting" until you have what you need to compare.
+
 # Reporting
 Report outcomes faithfully. If a command failed, say so with the relevant output. If you didn't run a verification step, say that rather than implying you did. Don't hedge confirmed results with unnecessary disclaimers.
 
@@ -1202,6 +1272,7 @@ function createHortonTools(sandbox, ctx, readSet, opts = {}) {
 			logPrefix: opts.logPrefix ?? `[horton]`
 		})] : [createFetchUrlTool(sandbox)],
 		createSpawnWorkerTool(ctx, opts.modelConfig),
+		createForkTool(ctx),
 		createSendTool(ctx.send, { selfEntityUrl: ctx.entityUrl }),
 		...opts.docsSearchTool ? [opts.docsSearchTool] : []
 	];
@@ -1294,6 +1365,7 @@ function createAssistantHandler(options) {
 			...mcp.tools()
 		];
 		const hasEventSourceTools = tools.some((tool) => getToolName(tool) === `list_event_sources`);
+		const hasScheduleTools = tools.some((tool) => getToolName(tool) === `upsert_cron_schedule`);
 		const titlePromise = !ctx.tags.title ? (async () => {
 			const firstUserMessage = await extractFirstUserMessage(ctx);
 			if (!firstUserMessage) return;
@@ -1374,7 +1446,8 @@ function createAssistantHandler(options) {
 				docsUrl,
 				modelProvider: modelConfig.provider,
 				modelId: String(modelConfig.model),
-				hasEventSourceTools
+				hasEventSourceTools,
+				hasScheduleTools
 			}),
 			...modelConfig,
 			tools,
@@ -1646,7 +1719,10 @@ function dedupeToolsByName(tools) {
 }
 function createBuiltinElectricTools(custom) {
 	return async (context) => {
-		const builtinTools = createEventSourceTools(context);
+		const builtinTools = [...createEventSourceTools(context), ...createScheduleTools({
+			...context,
+			db: context.db
+		})];
 		const customTools = custom ? await custom(context) : [];
 		return dedupeToolsByName([...builtinTools, ...customTools]);
 	};
@@ -1688,7 +1764,7 @@ async function createBuiltinAgentHandler(options) {
 		modelCatalog
 	});
 	typeNames.push(`worker`);
-	const sandboxProfiles = await buildBuiltinSandboxProfiles(cwd);
+	const { profiles: sandboxProfiles, shutdownSandboxes } = await buildBuiltinSandboxProfiles(cwd);
 	const runtime = createRuntimeHandler({
 		baseUrl: agentServerUrl,
 		serveEndpoint,
@@ -1707,7 +1783,8 @@ async function createBuiltinAgentHandler(options) {
 		runtime,
 		registry,
 		typeNames,
-		skillsRegistry
+		skillsRegistry,
+		shutdownSandboxes
 	};
 }
 async function registerBuiltinAgentTypes(bootstrap) {
@@ -1718,18 +1795,22 @@ async function registerBuiltinAgentTypes(bootstrap) {
 * Guard so repeated `buildBuiltinSandboxProfiles` calls in one process don't
 * re-run the boot sweep.
 */
-let dockerSweptOnBoot = false;
+let dockerBootSweep = null;
 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)`);
+	dockerBootSweep ??= sweep().then((reclaimed) => {
+		if (reclaimed.length > 0) serverLog.info(`[builtin-agents] docker sandbox boot sweep reclaimed ${reclaimed.length} leftover container(s)`);
 	}).catch((err) => serverLog.warn(`[builtin-agents] docker sandbox boot sweep error: ${err instanceof Error ? err.message : String(err)}`));
+	return dockerBootSweep;
 }
 /**
 * 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.
+*
+* Also returns `shutdownSandboxes` when a host-local provider registered: an
+* immediate teardown of this process's live containers that the embedding
+* server must run on shutdown (the providers' debounced idle teardowns die
+* with the process).
 */
 async function buildBuiltinSandboxProfiles(workingDirectory) {
 	const profiles = [{
@@ -1738,29 +1819,36 @@ async function buildBuiltinSandboxProfiles(workingDirectory) {
 		description: `Runs on the host without isolation. Full filesystem access.`,
 		factory: ({ args }) => chooseDefaultSandbox(resolveCwd(args, workingDirectory))
 	}];
+	let shutdownSandboxes = null;
 	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);
+			const { dockerSandbox, reclaimDockerSandboxByKey, shutdownAllDockerSandboxes, sweepOrphanedDockerSandboxes } = await import(`@electric-ax/agents-runtime/sandbox/docker`);
+			await sweepOrphanedDockerSandboxesOnce(sweepOrphanedDockerSandboxes);
+			shutdownSandboxes = shutdownAllDockerSandboxes;
 			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 }) => {
+				factory: async ({ 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
+					return lazySandbox({
+						name: `docker`,
+						workingDirectory: `/work`,
+						factory: () => dockerSandbox({
+							initialNetworkPolicy: { mode: `allow-all` },
+							extraMounts: cwd ? [{
+								hostPath: cwd,
+								containerPath: `/work`,
+								readOnly: false
+							}] : void 0,
+							sandboxKey,
+							persistent,
+							owner,
+							entityType,
+							entityUrl
+						}),
+						reclaim: owner ? () => reclaimDockerSandboxByKey(sandboxKey) : void 0
 					});
 				}
 			});
@@ -1784,7 +1872,10 @@ async function buildBuiltinSandboxProfiles(workingDirectory) {
 	});
 	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;
+	return {
+		profiles,
+		shutdownSandboxes
+	};
 }
 function readWorkingDirectoryArg(args) {
 	const v = args.workingDirectory;
@@ -1990,6 +2081,9 @@ var BuiltinAgentsServer = class {
 			await Promise.race([this.bootstrap.runtime.drainWakes().catch((err) => {
 				serverLog.error(`[builtin-agents] drainWakes failed during shutdown:`, err);
 			}), new Promise((resolve) => setTimeout(resolve, 5e3))]);
+			if (this.bootstrap.shutdownSandboxes) await Promise.race([this.bootstrap.shutdownSandboxes().catch((err) => {
+				serverLog.error(`[builtin-agents] sandbox shutdown failed during shutdown:`, err);
+			}), new Promise((resolve) => setTimeout(resolve, 5e3))]);
 			this.bootstrap = null;
 		}
 		this.mcpStopping = true;

package/dist/index.cjs

@@ -818,6 +818,60 @@ function createSpawnWorkerTool(ctx, modelConfig) {
 	};
 }
 
+//#endregion
+//#region src/tools/fork.ts
+function createForkTool(ctx) {
+	return {
+		name: `fork`,
+		label: `Fork`,
+		description: `Fork a session at its latest completed agent response, producing a child copy of the conversation up to that point. The new fork is YOUR child — same parent-ownership model as a spawned worker — and it reports back to you the same way: when its next run finishes you'll be woken with its response. End your turn after forking.
+
+Prefer supplying an 'initialMessage' so the fork is dispatched immediately in a single call — no follow-up 'send' needed. If you omit it, the fork boots idle and you'll need to call 'send' afterwards. For chat-rendered messages use the shape \`{ "text": "..." }\` so the prompt shows up in the chat UI.
+
+Use this to explore multiple alternative continuations in parallel from the same starting point. End your current turn first so the fork includes your latest response — the anchor is always the most recently completed run.
+
+Omit 'entityUrl' to fork your own session. Pass a different session's URL to fork that session instead (the new fork is still your child). The optional 'id' names the new fork's instance — useful when you want stable, predictable URLs (e.g. labelling branches in a parallel exploration); omit to let the server mint one.`,
+		parameters: __sinclair_typebox.Type.Object({
+			entityUrl: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.String({ description: `URL of the session to fork. Omit to fork your own session.` })),
+			id: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.String({ description: `Instance id for the new fork (the \`<id>\` in \`/horton/<id>\`). Mirrors spawn_worker's id parameter. Omit to let the server assign one.` })),
+			initialMessage: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.Any({ description: `Initial inbox message delivered to the fork by the server in the same round-trip — the fork wakes and starts running immediately, no follow-up 'send' needed. Use the shape \`{ "text": "..." }\` for chat-rendered prompts. Omit to leave the fork idle (then call 'send' separately).` })),
+			tags: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.Record(__sinclair_typebox.Type.String(), __sinclair_typebox.Type.String(), { description: `Optional tags stamped on the new fork, on top of those copied from the source. Useful for labelling experiments (e.g. \`{ "experiment": "ecosystem-maturity" }\`).` }))
+		}),
+		execute: async (_toolCallId, params) => {
+			const { entityUrl, id, initialMessage, tags } = params;
+			try {
+				const opts = {
+					...initialMessage !== void 0 && { initialMessage },
+					...tags !== void 0 && { tags }
+				};
+				const forkId = id ?? `fork-${(0, nanoid.nanoid)(10)}`;
+				const handle = entityUrl !== void 0 ? await ctx.fork(entityUrl, forkId, opts) : await ctx.forkSelf(forkId, opts);
+				const dispatchNote = initialMessage !== void 0 ? `The initial message has been delivered to the fork — it will start running.` : `The fork boots idle — use the 'send' tool to dispatch a follow-up prompt.`;
+				return {
+					content: [{
+						type: `text`,
+						text: `Forked at ${handle.entityUrl}. ${dispatchNote} End your turn; you'll wake with the fork's response when its next run finishes (same as a spawned worker).`
+					}],
+					details: {
+						forked: true,
+						forkUrl: handle.entityUrl
+					}
+				};
+			} catch (err) {
+				const message = err instanceof Error ? err.message : `Unknown error`;
+				serverLog.warn(`[fork tool] failed to fork ${entityUrl ?? `<self>`}: ${message}`, err instanceof Error ? err : void 0);
+				return {
+					content: [{
+						type: `text`,
+						text: `Error forking session: ${message}`
+					}],
+					details: { forked: false }
+				};
+			}
+		}
+	};
+}
+
 //#endregion
 //#region src/model-catalog.ts
 const MODEL_INPUTS_SCHEMA_DEF = `electricModelInputs`;
@@ -1109,6 +1163,7 @@ async function generateTitle(userMessage, llmCall, onFallback) {
 function buildHortonSystemPrompt(workingDirectory, opts = {}) {
 	const docsTools = opts.hasDocsSupport ? `\n- search_electric_agents_docs: hybrid search over the built-in Electric Agents docs index` : ``;
 	const eventSourceTools = opts.hasEventSourceTools ? `\n- list_event_sources: list external webhook/event feeds you can subscribe to, including available buckets and parameters\n- subscribe_event_source: subscribe yourself to one of those feeds or buckets so matching future events wake you\n- list_event_source_subscriptions: list your active event source subscriptions\n- unsubscribe_event_source: remove one of your event source subscriptions by id` : ``;
+	const scheduleTools = opts.hasScheduleTools ? `\n- upsert_cron_schedule: create or update a recurring cron wake for yourself. Always include payload with the concrete instruction/message you should receive when the cron fires.\n- delete_schedule: delete one of your cron or future-send schedules by stable id\n- list_schedules: list your manifest-backed cron and future-send schedules` : ``;
 	const skillsTools = opts.hasSkills ? `\n- use_skill: load a skill (knowledge, instructions, or a tutorial) into your context to help with the user's request\n- remove_skill: unload a skill from context when you're done with it` : ``;
 	const docsGuidance = opts.hasDocsSupport ? `\n- For ANY question about Electric Agents or this framework, ALWAYS use search_electric_agents_docs FIRST. Do not use web_search or fetch_url for Electric Agents topics unless the docs search returns no useful results.\n- The search tool returns chunk content directly — you do not need to read the source files.\n- Use repo read/bash tools only for non-doc files or when you need to inspect exact implementation code in the workspace.` : ``;
 	const skillsGuidance = opts.hasSkills ? `\n# Skills\nYou have access to skills — specialized knowledge and guided workflows you can load on demand. Your context includes a skills catalog listing what's available. When the user's request matches a skill's description or keywords, load it with use_skill.
@@ -1162,8 +1217,9 @@ When a user opens with a greeting ("hi", "hello", "hey", etc.) or a broad statem
 - web_search: search the web
 - fetch_url: fetch and convert a URL to markdown
 - spawn_worker: dispatch a subagent for an isolated task
+- fork: spawn a child session that inherits this conversation's history up to the latest completed response. Same parent-ownership model as spawn_worker — when the fork's next run finishes, you'll wake with its response.
 - send: send a message to an Electric Agent/entity. To schedule future work for yourself, call send with self: true and afterMs.
-${eventSourceTools}${docsTools}${skillsTools}
+${eventSourceTools}${scheduleTools}${docsTools}${skillsTools}
 
 # Working with files
 - Prefer edit over write when modifying existing files.
@@ -1190,6 +1246,20 @@ When you spawn a worker, write its system prompt the way you'd brief a colleague
 
 After spawning, end your turn (optionally with a brief "I've dispatched a worker for X; I'll respond when it finishes"). When the worker finishes, you'll receive a message describing which worker completed and what it returned. Multiple workers may finish at different times — check the message for the worker URL to know which one you're hearing about.
 
+# When to fork (vs spawn_worker)
+\`fork\` is the **sibling primitive to spawn_worker** — both create a child you own, both report back to you on a future wake. The difference is only in what the child boots with:
+
+- **spawn_worker** → child boots with an **empty context**; you brief it from scratch via a system prompt + initial message. Use when the worker doesn't need to know what we've said so far.
+- **fork** → child boots with **a copy of THIS conversation's history** up to your latest completed response. Use when each child needs to know what we've already established (the user's framing, your prior analysis, an earlier decision, the constraints, etc.).
+
+**Trigger pattern: prefer fork when generating multiple variants the user wants to compare.** If the user asks for "three different X" or "two takes on Y" or "evaluate these N approaches" and each variant should reflect the conversation we've had so far, **don't inline the variants in one response** — fork once per variant, send each a tailored follow-up, and synthesize when they report back. Inlining feels faster but the variants end up cross-contaminating in your single response; forks keep them honestly independent. The exception is trivial generation (a list of names, a couple of one-liners) where each variant takes a sentence — there, inline is fine.
+
+Workflow when forking yourself for parallel exploration:
+1. **End your current turn first.** The fork's history stops at your *latest completed* run. Anything you say mid-turn is NOT in the fork. If you want your analysis baked into each fork, finish it and end the turn before calling fork.
+2. On the next wake, call \`fork\` once per branch with a different \`initialMessage\` per call — that's how the branches diverge from a shared starting point. Each fork is YOUR child, just like a spawned worker, and the server delivers \`initialMessage\` to the fork in the same round-trip, so the fork starts running immediately (no follow-up \`send\` needed). Use the shape \`{ text: "..." }\` for the message so it renders in the chat UI.
+3. End your turn. You'll wake automatically when each fork's run finishes (same wake mechanism as spawn_worker); the wake message identifies the fork and includes its response.
+4. If you're waiting on multiple forks, don't synthesize on the first wake — quietly end the turn with "got N of M, waiting" until you have what you need to compare.
+
 # Reporting
 Report outcomes faithfully. If a command failed, say so with the relevant output. If you didn't run a verification step, say that rather than implying you did. Don't hedge confirmed results with unnecessary disclaimers.
 
@@ -1215,6 +1285,7 @@ function createHortonTools(sandbox, ctx, readSet, opts = {}) {
 			logPrefix: opts.logPrefix ?? `[horton]`
 		})] : [(0, __electric_ax_agents_runtime_tools.createFetchUrlTool)(sandbox)],
 		createSpawnWorkerTool(ctx, opts.modelConfig),
+		createForkTool(ctx),
 		(0, __electric_ax_agents_runtime_tools.createSendTool)(ctx.send, { selfEntityUrl: ctx.entityUrl }),
 		...opts.docsSearchTool ? [opts.docsSearchTool] : []
 	];
@@ -1307,6 +1378,7 @@ function createAssistantHandler(options) {
 			...__electric_ax_agents_mcp.mcp.tools()
 		];
 		const hasEventSourceTools = tools.some((tool) => getToolName(tool) === `list_event_sources`);
+		const hasScheduleTools = tools.some((tool) => getToolName(tool) === `upsert_cron_schedule`);
 		const titlePromise = !ctx.tags.title ? (async () => {
 			const firstUserMessage = await extractFirstUserMessage(ctx);
 			if (!firstUserMessage) return;
@@ -1387,7 +1459,8 @@ function createAssistantHandler(options) {
 				docsUrl,
 				modelProvider: modelConfig.provider,
 				modelId: String(modelConfig.model),
-				hasEventSourceTools
+				hasEventSourceTools,
+				hasScheduleTools
 			}),
 			...modelConfig,
 			tools,
@@ -1660,7 +1733,10 @@ function dedupeToolsByName(tools) {
 }
 function createBuiltinElectricTools(custom) {
 	return async (context) => {
-		const builtinTools = (0, __electric_ax_agents_runtime_tools.createEventSourceTools)(context);
+		const builtinTools = [...(0, __electric_ax_agents_runtime_tools.createEventSourceTools)(context), ...(0, __electric_ax_agents_runtime_tools.createScheduleTools)({
+			...context,
+			db: context.db
+		})];
 		const customTools = custom ? await custom(context) : [];
 		return dedupeToolsByName([...builtinTools, ...customTools]);
 	};
@@ -1702,7 +1778,7 @@ async function createBuiltinAgentHandler(options) {
 		modelCatalog
 	});
 	typeNames.push(`worker`);
-	const sandboxProfiles = await buildBuiltinSandboxProfiles(cwd);
+	const { profiles: sandboxProfiles, shutdownSandboxes } = await buildBuiltinSandboxProfiles(cwd);
 	const runtime = (0, __electric_ax_agents_runtime.createRuntimeHandler)({
 		baseUrl: agentServerUrl,
 		serveEndpoint,
@@ -1721,7 +1797,8 @@ async function createBuiltinAgentHandler(options) {
 		runtime,
 		registry,
 		typeNames,
-		skillsRegistry
+		skillsRegistry,
+		shutdownSandboxes
 	};
 }
 async function createAgentHandler(agentServerUrl, workingDirectory, streamFn, createElectricTools, serveEndpoint) {
@@ -1742,18 +1819,22 @@ const registerAgentTypes = registerBuiltinAgentTypes;
 * Guard so repeated `buildBuiltinSandboxProfiles` calls in one process don't
 * re-run the boot sweep.
 */
-let dockerSweptOnBoot = false;
+let dockerBootSweep = null;
 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)`);
+	dockerBootSweep ??= sweep().then((reclaimed) => {
+		if (reclaimed.length > 0) serverLog.info(`[builtin-agents] docker sandbox boot sweep reclaimed ${reclaimed.length} leftover container(s)`);
 	}).catch((err) => serverLog.warn(`[builtin-agents] docker sandbox boot sweep error: ${err instanceof Error ? err.message : String(err)}`));
+	return dockerBootSweep;
 }
 /**
 * 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.
+*
+* Also returns `shutdownSandboxes` when a host-local provider registered: an
+* immediate teardown of this process's live containers that the embedding
+* server must run on shutdown (the providers' debounced idle teardowns die
+* with the process).
 */
 async function buildBuiltinSandboxProfiles(workingDirectory) {
 	const profiles = [{
@@ -1762,29 +1843,36 @@ async function buildBuiltinSandboxProfiles(workingDirectory) {
 		description: `Runs on the host without isolation. Full filesystem access.`,
 		factory: ({ args }) => (0, __electric_ax_agents_runtime_sandbox.chooseDefaultSandbox)(resolveCwd(args, workingDirectory))
 	}];
+	let shutdownSandboxes = null;
 	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);
+			const { dockerSandbox, reclaimDockerSandboxByKey, shutdownAllDockerSandboxes, sweepOrphanedDockerSandboxes } = await import(`@electric-ax/agents-runtime/sandbox/docker`);
+			await sweepOrphanedDockerSandboxesOnce(sweepOrphanedDockerSandboxes);
+			shutdownSandboxes = shutdownAllDockerSandboxes;
 			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 }) => {
+				factory: async ({ 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
+					return (0, __electric_ax_agents_runtime_sandbox.lazySandbox)({
+						name: `docker`,
+						workingDirectory: `/work`,
+						factory: () => dockerSandbox({
+							initialNetworkPolicy: { mode: `allow-all` },
+							extraMounts: cwd ? [{
+								hostPath: cwd,
+								containerPath: `/work`,
+								readOnly: false
+							}] : void 0,
+							sandboxKey,
+							persistent,
+							owner,
+							entityType,
+							entityUrl
+						}),
+						reclaim: owner ? () => reclaimDockerSandboxByKey(sandboxKey) : void 0
 					});
 				}
 			});
@@ -1808,7 +1896,10 @@ async function buildBuiltinSandboxProfiles(workingDirectory) {
 	});
 	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;
+	return {
+		profiles,
+		shutdownSandboxes
+	};
 }
 function readWorkingDirectoryArg(args) {
 	const v = args.workingDirectory;
@@ -1827,7 +1918,7 @@ function installDurableStreamsFetchCache(options = {}) {
 		location: options.sqliteLocation,
 		maxCount: options.maxCount
 	}) : new undici.cacheStores.MemoryCacheStore({ maxSize: MEMORY_CACHE_SIZE_BYTES });
-	(0, undici.setGlobalDispatcher)(new undici.Agent().compose(undici.interceptors.cache({ store })));
+	(0, undici.setGlobalDispatcher)((0, undici.getGlobalDispatcher)().compose(undici.interceptors.cache({ store })));
 }
 
 //#endregion
@@ -2026,6 +2117,9 @@ var BuiltinAgentsServer = class {
 			await Promise.race([this.bootstrap.runtime.drainWakes().catch((err) => {
 				serverLog.error(`[builtin-agents] drainWakes failed during shutdown:`, err);
 			}), new Promise((resolve) => setTimeout(resolve, 5e3))]);
+			if (this.bootstrap.shutdownSandboxes) await Promise.race([this.bootstrap.shutdownSandboxes().catch((err) => {
+				serverLog.error(`[builtin-agents] sandbox shutdown failed during shutdown:`, err);
+			}), new Promise((resolve) => setTimeout(resolve, 5e3))]);
 			this.bootstrap = null;
 		}
 		this.mcpStopping = true;
@@ -2166,6 +2260,7 @@ exports.builtinModelProviderLabel = builtinModelProviderLabel
 exports.createAgentHandler = createAgentHandler
 exports.createBuiltinAgentHandler = createBuiltinAgentHandler
 exports.createBuiltinElectricTools = createBuiltinElectricTools
+exports.createForkTool = createForkTool
 exports.createHortonDocsSupport = createHortonDocsSupport
 exports.createHortonTools = createHortonTools
 exports.createSpawnWorkerTool = createSpawnWorkerTool

package/dist/index.d.cts

@@ -14,6 +14,13 @@ interface AgentHandlerResult {
   registry: EntityRegistry;
   typeNames: Array<string>;
   skillsRegistry: SkillsRegistry | null;
+  /**
+   * Immediately tears down the idle sandboxes this process created (set when
+   * a provider with host-local state — docker — is registered). MUST be called
+   * on shutdown, after wakes drain: the providers' debounced idle teardowns
+   * die with the process, which would leave containers running.
+   */
+  shutdownSandboxes: (() => Promise<void>) | null;
 }
 type BuiltinElectricToolsFactory = NonNullable<ProcessWakeConfig[`createElectricTools`]>;
 interface BuiltinAgentHandlerOptions {
@@ -190,6 +197,7 @@ declare function generateTitle(userMessage: string, llmCall: (prompt: string) =>
 declare function buildHortonSystemPrompt(workingDirectory: string, opts?: {
   hasDocsSupport?: boolean;
   hasEventSourceTools?: boolean;
+  hasScheduleTools?: boolean;
   hasSkills?: boolean;
   docsUrl?: string;
   modelProvider?: string;
@@ -223,6 +231,10 @@ declare const WORKER_TOOL_NAMES: readonly ["bash", "read", "write", "edit", "web
 type WorkerToolName = (typeof WORKER_TOOL_NAMES)[number];
 declare function createSpawnWorkerTool(ctx: HandlerContext, modelConfig?: BuiltinAgentModelConfig): AgentTool$1;
 
+//#endregion
+//#region src/tools/fork.d.ts
+declare function createForkTool(ctx: HandlerContext): AgentTool$1;
+
 //#endregion
 //#region src/docs/knowledge-base.d.ts
 interface HortonDocsSupport {
@@ -242,4 +254,4 @@ declare function createHortonDocsSupport(workingDirectory: string, opts?: {
 }): HortonDocsSupport | null;
 
 //#endregion
-export { AgentHandlerResult, BuiltinAgentHandlerOptions, BuiltinAgentsEntrypointOptions, BuiltinAgentsEntrypointServer, BuiltinAgentsServer, BuiltinAgentsServerOptions, BuiltinElectricToolsFactory, BuiltinModelCatalogOptions, BuiltinModelChoice, BuiltinModelProvider, DEFAULT_BUILTIN_AGENT_HANDLER_PATH, HORTON_MODEL, McpConfig, McpListedEntry, McpRegistry, McpServerConfig, RegistrySnapshot, RegistrySubscriber, RunBuiltinAgentsEntrypointOptions, WORKER_TOOL_NAMES, WorkerToolName, braveSearchTool, buildHortonSystemPrompt, builtinModelProviderLabel, createAgentHandler, createBuiltinAgentHandler, createBuiltinElectricTools, createHortonDocsSupport, createHortonTools, createSpawnWorkerTool, generateTitle, listBuiltinModelChoices, registerAgentTypes, registerBuiltinAgentTypes, registerHorton, registerWorker, resolveBuiltinAgentsEntrypointOptions, runBuiltinAgentsEntrypoint };
+export { AgentHandlerResult, BuiltinAgentHandlerOptions, BuiltinAgentsEntrypointOptions, BuiltinAgentsEntrypointServer, BuiltinAgentsServer, BuiltinAgentsServerOptions, BuiltinElectricToolsFactory, BuiltinModelCatalogOptions, BuiltinModelChoice, BuiltinModelProvider, DEFAULT_BUILTIN_AGENT_HANDLER_PATH, HORTON_MODEL, McpConfig, McpListedEntry, McpRegistry, McpServerConfig, RegistrySnapshot, RegistrySubscriber, RunBuiltinAgentsEntrypointOptions, WORKER_TOOL_NAMES, WorkerToolName, braveSearchTool, buildHortonSystemPrompt, builtinModelProviderLabel, createAgentHandler, createBuiltinAgentHandler, createBuiltinElectricTools, createForkTool, createHortonDocsSupport, createHortonTools, createSpawnWorkerTool, generateTitle, listBuiltinModelChoices, registerAgentTypes, registerBuiltinAgentTypes, registerHorton, registerWorker, resolveBuiltinAgentsEntrypointOptions, runBuiltinAgentsEntrypoint };

package/dist/index.d.ts

@@ -14,6 +14,13 @@ interface AgentHandlerResult {
   registry: EntityRegistry;
   typeNames: Array<string>;
   skillsRegistry: SkillsRegistry | null;
+  /**
+   * Immediately tears down the idle sandboxes this process created (set when
+   * a provider with host-local state — docker — is registered). MUST be called
+   * on shutdown, after wakes drain: the providers' debounced idle teardowns
+   * die with the process, which would leave containers running.
+   */
+  shutdownSandboxes: (() => Promise<void>) | null;
 }
 type BuiltinElectricToolsFactory = NonNullable<ProcessWakeConfig[`createElectricTools`]>;
 interface BuiltinAgentHandlerOptions {
@@ -190,6 +197,7 @@ declare function generateTitle(userMessage: string, llmCall: (prompt: string) =>
 declare function buildHortonSystemPrompt(workingDirectory: string, opts?: {
   hasDocsSupport?: boolean;
   hasEventSourceTools?: boolean;
+  hasScheduleTools?: boolean;
   hasSkills?: boolean;
   docsUrl?: string;
   modelProvider?: string;
@@ -223,6 +231,10 @@ declare const WORKER_TOOL_NAMES: readonly ["bash", "read", "write", "edit", "web
 type WorkerToolName = (typeof WORKER_TOOL_NAMES)[number];
 declare function createSpawnWorkerTool(ctx: HandlerContext, modelConfig?: BuiltinAgentModelConfig): AgentTool$1;
 
+//#endregion
+//#region src/tools/fork.d.ts
+declare function createForkTool(ctx: HandlerContext): AgentTool$1;
+
 //#endregion
 //#region src/docs/knowledge-base.d.ts
 interface HortonDocsSupport {
@@ -242,4 +254,4 @@ declare function createHortonDocsSupport(workingDirectory: string, opts?: {
 }): HortonDocsSupport | null;
 
 //#endregion
-export { AgentHandlerResult, BuiltinAgentHandlerOptions, BuiltinAgentsEntrypointOptions, BuiltinAgentsEntrypointServer, BuiltinAgentsServer, BuiltinAgentsServerOptions, BuiltinElectricToolsFactory, BuiltinModelCatalogOptions, BuiltinModelChoice, BuiltinModelProvider, DEFAULT_BUILTIN_AGENT_HANDLER_PATH, HORTON_MODEL, McpConfig, McpListedEntry, McpRegistry, McpServerConfig, RegistrySnapshot, RegistrySubscriber, RunBuiltinAgentsEntrypointOptions, WORKER_TOOL_NAMES, WorkerToolName, braveSearchTool, buildHortonSystemPrompt, builtinModelProviderLabel, createAgentHandler, createBuiltinAgentHandler, createBuiltinElectricTools, createHortonDocsSupport, createHortonTools, createSpawnWorkerTool, generateTitle, listBuiltinModelChoices, registerAgentTypes, registerBuiltinAgentTypes, registerHorton, registerWorker, resolveBuiltinAgentsEntrypointOptions, runBuiltinAgentsEntrypoint };
+export { AgentHandlerResult, BuiltinAgentHandlerOptions, BuiltinAgentsEntrypointOptions, BuiltinAgentsEntrypointServer, BuiltinAgentsServer, BuiltinAgentsServerOptions, BuiltinElectricToolsFactory, BuiltinModelCatalogOptions, BuiltinModelChoice, BuiltinModelProvider, DEFAULT_BUILTIN_AGENT_HANDLER_PATH, HORTON_MODEL, McpConfig, McpListedEntry, McpRegistry, McpServerConfig, RegistrySnapshot, RegistrySubscriber, RunBuiltinAgentsEntrypointOptions, WORKER_TOOL_NAMES, WorkerToolName, braveSearchTool, buildHortonSystemPrompt, builtinModelProviderLabel, createAgentHandler, createBuiltinAgentHandler, createBuiltinElectricTools, createForkTool, createHortonDocsSupport, createHortonTools, createSpawnWorkerTool, generateTitle, listBuiltinModelChoices, registerAgentTypes, registerBuiltinAgentTypes, registerHorton, registerWorker, resolveBuiltinAgentsEntrypointOptions, runBuiltinAgentsEntrypoint };

package/dist/index.js

@@ -2,8 +2,8 @@ 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, buildSkillSlashCommands, completeWithLowCostModel, createContextSkillLoader, createEntityRegistry, createPullWakeRunner, createRuntimeHandler, createSkillsRegistry, db, detectAvailableProviders, getMoonshotApiKey, getMoonshotModel, getMoonshotModels, readCodexAccessToken, registerToolProvider, unregisterToolProvider } from "@electric-ax/agents-runtime";
-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 { braveSearchTool, braveSearchTool as braveSearchTool$1, createBashTool, createEditTool, createEventSourceTools, createFetchUrlTool, createReadFileTool, createScheduleTools, createSendTool, createWriteTool } from "@electric-ax/agents-runtime/tools";
+import { chooseDefaultSandbox, isE2BAvailable, lazySandbox, remoteSandbox } from "@electric-ax/agents-runtime/sandbox";
 import fsSync from "node:fs";
 import pino from "pino";
 import { z } from "zod";
@@ -15,7 +15,7 @@ import { load } from "sqlite-vec";
 import { nanoid } from "nanoid";
 import { getModels } from "@mariozechner/pi-ai";
 import { bridgeMcpTool, buildPromptTools, buildResourceTools, createRegistry, keychainPersistence, loadConfig, mcp, watchConfig } from "@electric-ax/agents-mcp";
-import { Agent, cacheStores, interceptors, setGlobalDispatcher } from "undici";
+import { cacheStores, getGlobalDispatcher, interceptors, setGlobalDispatcher } from "undici";
 
 //#region src/log.ts
 const LOG_LEVEL = process.env.ELECTRIC_AGENTS_LOG_LEVEL ?? `info`;
@@ -794,6 +794,60 @@ function createSpawnWorkerTool(ctx, modelConfig) {
 	};
 }
 
+//#endregion
+//#region src/tools/fork.ts
+function createForkTool(ctx) {
+	return {
+		name: `fork`,
+		label: `Fork`,
+		description: `Fork a session at its latest completed agent response, producing a child copy of the conversation up to that point. The new fork is YOUR child — same parent-ownership model as a spawned worker — and it reports back to you the same way: when its next run finishes you'll be woken with its response. End your turn after forking.
+
+Prefer supplying an 'initialMessage' so the fork is dispatched immediately in a single call — no follow-up 'send' needed. If you omit it, the fork boots idle and you'll need to call 'send' afterwards. For chat-rendered messages use the shape \`{ "text": "..." }\` so the prompt shows up in the chat UI.
+
+Use this to explore multiple alternative continuations in parallel from the same starting point. End your current turn first so the fork includes your latest response — the anchor is always the most recently completed run.
+
+Omit 'entityUrl' to fork your own session. Pass a different session's URL to fork that session instead (the new fork is still your child). The optional 'id' names the new fork's instance — useful when you want stable, predictable URLs (e.g. labelling branches in a parallel exploration); omit to let the server mint one.`,
+		parameters: Type.Object({
+			entityUrl: Type.Optional(Type.String({ description: `URL of the session to fork. Omit to fork your own session.` })),
+			id: Type.Optional(Type.String({ description: `Instance id for the new fork (the \`<id>\` in \`/horton/<id>\`). Mirrors spawn_worker's id parameter. Omit to let the server assign one.` })),
+			initialMessage: Type.Optional(Type.Any({ description: `Initial inbox message delivered to the fork by the server in the same round-trip — the fork wakes and starts running immediately, no follow-up 'send' needed. Use the shape \`{ "text": "..." }\` for chat-rendered prompts. Omit to leave the fork idle (then call 'send' separately).` })),
+			tags: Type.Optional(Type.Record(Type.String(), Type.String(), { description: `Optional tags stamped on the new fork, on top of those copied from the source. Useful for labelling experiments (e.g. \`{ "experiment": "ecosystem-maturity" }\`).` }))
+		}),
+		execute: async (_toolCallId, params) => {
+			const { entityUrl, id, initialMessage, tags } = params;
+			try {
+				const opts = {
+					...initialMessage !== void 0 && { initialMessage },
+					...tags !== void 0 && { tags }
+				};
+				const forkId = id ?? `fork-${nanoid(10)}`;
+				const handle = entityUrl !== void 0 ? await ctx.fork(entityUrl, forkId, opts) : await ctx.forkSelf(forkId, opts);
+				const dispatchNote = initialMessage !== void 0 ? `The initial message has been delivered to the fork — it will start running.` : `The fork boots idle — use the 'send' tool to dispatch a follow-up prompt.`;
+				return {
+					content: [{
+						type: `text`,
+						text: `Forked at ${handle.entityUrl}. ${dispatchNote} End your turn; you'll wake with the fork's response when its next run finishes (same as a spawned worker).`
+					}],
+					details: {
+						forked: true,
+						forkUrl: handle.entityUrl
+					}
+				};
+			} catch (err) {
+				const message = err instanceof Error ? err.message : `Unknown error`;
+				serverLog.warn(`[fork tool] failed to fork ${entityUrl ?? `<self>`}: ${message}`, err instanceof Error ? err : void 0);
+				return {
+					content: [{
+						type: `text`,
+						text: `Error forking session: ${message}`
+					}],
+					details: { forked: false }
+				};
+			}
+		}
+	};
+}
+
 //#endregion
 //#region src/model-catalog.ts
 const MODEL_INPUTS_SCHEMA_DEF = `electricModelInputs`;
@@ -1085,6 +1139,7 @@ async function generateTitle(userMessage, llmCall, onFallback) {
 function buildHortonSystemPrompt(workingDirectory, opts = {}) {
 	const docsTools = opts.hasDocsSupport ? `\n- search_electric_agents_docs: hybrid search over the built-in Electric Agents docs index` : ``;
 	const eventSourceTools = opts.hasEventSourceTools ? `\n- list_event_sources: list external webhook/event feeds you can subscribe to, including available buckets and parameters\n- subscribe_event_source: subscribe yourself to one of those feeds or buckets so matching future events wake you\n- list_event_source_subscriptions: list your active event source subscriptions\n- unsubscribe_event_source: remove one of your event source subscriptions by id` : ``;
+	const scheduleTools = opts.hasScheduleTools ? `\n- upsert_cron_schedule: create or update a recurring cron wake for yourself. Always include payload with the concrete instruction/message you should receive when the cron fires.\n- delete_schedule: delete one of your cron or future-send schedules by stable id\n- list_schedules: list your manifest-backed cron and future-send schedules` : ``;
 	const skillsTools = opts.hasSkills ? `\n- use_skill: load a skill (knowledge, instructions, or a tutorial) into your context to help with the user's request\n- remove_skill: unload a skill from context when you're done with it` : ``;
 	const docsGuidance = opts.hasDocsSupport ? `\n- For ANY question about Electric Agents or this framework, ALWAYS use search_electric_agents_docs FIRST. Do not use web_search or fetch_url for Electric Agents topics unless the docs search returns no useful results.\n- The search tool returns chunk content directly — you do not need to read the source files.\n- Use repo read/bash tools only for non-doc files or when you need to inspect exact implementation code in the workspace.` : ``;
 	const skillsGuidance = opts.hasSkills ? `\n# Skills\nYou have access to skills — specialized knowledge and guided workflows you can load on demand. Your context includes a skills catalog listing what's available. When the user's request matches a skill's description or keywords, load it with use_skill.
@@ -1138,8 +1193,9 @@ When a user opens with a greeting ("hi", "hello", "hey", etc.) or a broad statem
 - web_search: search the web
 - fetch_url: fetch and convert a URL to markdown
 - spawn_worker: dispatch a subagent for an isolated task
+- fork: spawn a child session that inherits this conversation's history up to the latest completed response. Same parent-ownership model as spawn_worker — when the fork's next run finishes, you'll wake with its response.
 - send: send a message to an Electric Agent/entity. To schedule future work for yourself, call send with self: true and afterMs.
-${eventSourceTools}${docsTools}${skillsTools}
+${eventSourceTools}${scheduleTools}${docsTools}${skillsTools}
 
 # Working with files
 - Prefer edit over write when modifying existing files.
@@ -1166,6 +1222,20 @@ When you spawn a worker, write its system prompt the way you'd brief a colleague
 
 After spawning, end your turn (optionally with a brief "I've dispatched a worker for X; I'll respond when it finishes"). When the worker finishes, you'll receive a message describing which worker completed and what it returned. Multiple workers may finish at different times — check the message for the worker URL to know which one you're hearing about.
 
+# When to fork (vs spawn_worker)
+\`fork\` is the **sibling primitive to spawn_worker** — both create a child you own, both report back to you on a future wake. The difference is only in what the child boots with:
+
+- **spawn_worker** → child boots with an **empty context**; you brief it from scratch via a system prompt + initial message. Use when the worker doesn't need to know what we've said so far.
+- **fork** → child boots with **a copy of THIS conversation's history** up to your latest completed response. Use when each child needs to know what we've already established (the user's framing, your prior analysis, an earlier decision, the constraints, etc.).
+
+**Trigger pattern: prefer fork when generating multiple variants the user wants to compare.** If the user asks for "three different X" or "two takes on Y" or "evaluate these N approaches" and each variant should reflect the conversation we've had so far, **don't inline the variants in one response** — fork once per variant, send each a tailored follow-up, and synthesize when they report back. Inlining feels faster but the variants end up cross-contaminating in your single response; forks keep them honestly independent. The exception is trivial generation (a list of names, a couple of one-liners) where each variant takes a sentence — there, inline is fine.
+
+Workflow when forking yourself for parallel exploration:
+1. **End your current turn first.** The fork's history stops at your *latest completed* run. Anything you say mid-turn is NOT in the fork. If you want your analysis baked into each fork, finish it and end the turn before calling fork.
+2. On the next wake, call \`fork\` once per branch with a different \`initialMessage\` per call — that's how the branches diverge from a shared starting point. Each fork is YOUR child, just like a spawned worker, and the server delivers \`initialMessage\` to the fork in the same round-trip, so the fork starts running immediately (no follow-up \`send\` needed). Use the shape \`{ text: "..." }\` for the message so it renders in the chat UI.
+3. End your turn. You'll wake automatically when each fork's run finishes (same wake mechanism as spawn_worker); the wake message identifies the fork and includes its response.
+4. If you're waiting on multiple forks, don't synthesize on the first wake — quietly end the turn with "got N of M, waiting" until you have what you need to compare.
+
 # Reporting
 Report outcomes faithfully. If a command failed, say so with the relevant output. If you didn't run a verification step, say that rather than implying you did. Don't hedge confirmed results with unnecessary disclaimers.
 
@@ -1191,6 +1261,7 @@ function createHortonTools(sandbox, ctx, readSet, opts = {}) {
 			logPrefix: opts.logPrefix ?? `[horton]`
 		})] : [createFetchUrlTool(sandbox)],
 		createSpawnWorkerTool(ctx, opts.modelConfig),
+		createForkTool(ctx),
 		createSendTool(ctx.send, { selfEntityUrl: ctx.entityUrl }),
 		...opts.docsSearchTool ? [opts.docsSearchTool] : []
 	];
@@ -1283,6 +1354,7 @@ function createAssistantHandler(options) {
 			...mcp.tools()
 		];
 		const hasEventSourceTools = tools.some((tool) => getToolName(tool) === `list_event_sources`);
+		const hasScheduleTools = tools.some((tool) => getToolName(tool) === `upsert_cron_schedule`);
 		const titlePromise = !ctx.tags.title ? (async () => {
 			const firstUserMessage = await extractFirstUserMessage(ctx);
 			if (!firstUserMessage) return;
@@ -1363,7 +1435,8 @@ function createAssistantHandler(options) {
 				docsUrl,
 				modelProvider: modelConfig.provider,
 				modelId: String(modelConfig.model),
-				hasEventSourceTools
+				hasEventSourceTools,
+				hasScheduleTools
 			}),
 			...modelConfig,
 			tools,
@@ -1636,7 +1709,10 @@ function dedupeToolsByName(tools) {
 }
 function createBuiltinElectricTools(custom) {
 	return async (context) => {
-		const builtinTools = createEventSourceTools(context);
+		const builtinTools = [...createEventSourceTools(context), ...createScheduleTools({
+			...context,
+			db: context.db
+		})];
 		const customTools = custom ? await custom(context) : [];
 		return dedupeToolsByName([...builtinTools, ...customTools]);
 	};
@@ -1678,7 +1754,7 @@ async function createBuiltinAgentHandler(options) {
 		modelCatalog
 	});
 	typeNames.push(`worker`);
-	const sandboxProfiles = await buildBuiltinSandboxProfiles(cwd);
+	const { profiles: sandboxProfiles, shutdownSandboxes } = await buildBuiltinSandboxProfiles(cwd);
 	const runtime = createRuntimeHandler({
 		baseUrl: agentServerUrl,
 		serveEndpoint,
@@ -1697,7 +1773,8 @@ async function createBuiltinAgentHandler(options) {
 		runtime,
 		registry,
 		typeNames,
-		skillsRegistry
+		skillsRegistry,
+		shutdownSandboxes
 	};
 }
 async function createAgentHandler(agentServerUrl, workingDirectory, streamFn, createElectricTools, serveEndpoint) {
@@ -1718,18 +1795,22 @@ const registerAgentTypes = registerBuiltinAgentTypes;
 * Guard so repeated `buildBuiltinSandboxProfiles` calls in one process don't
 * re-run the boot sweep.
 */
-let dockerSweptOnBoot = false;
+let dockerBootSweep = null;
 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)`);
+	dockerBootSweep ??= sweep().then((reclaimed) => {
+		if (reclaimed.length > 0) serverLog.info(`[builtin-agents] docker sandbox boot sweep reclaimed ${reclaimed.length} leftover container(s)`);
 	}).catch((err) => serverLog.warn(`[builtin-agents] docker sandbox boot sweep error: ${err instanceof Error ? err.message : String(err)}`));
+	return dockerBootSweep;
 }
 /**
 * 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.
+*
+* Also returns `shutdownSandboxes` when a host-local provider registered: an
+* immediate teardown of this process's live containers that the embedding
+* server must run on shutdown (the providers' debounced idle teardowns die
+* with the process).
 */
 async function buildBuiltinSandboxProfiles(workingDirectory) {
 	const profiles = [{
@@ -1738,29 +1819,36 @@ async function buildBuiltinSandboxProfiles(workingDirectory) {
 		description: `Runs on the host without isolation. Full filesystem access.`,
 		factory: ({ args }) => chooseDefaultSandbox(resolveCwd(args, workingDirectory))
 	}];
+	let shutdownSandboxes = null;
 	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);
+			const { dockerSandbox, reclaimDockerSandboxByKey, shutdownAllDockerSandboxes, sweepOrphanedDockerSandboxes } = await import(`@electric-ax/agents-runtime/sandbox/docker`);
+			await sweepOrphanedDockerSandboxesOnce(sweepOrphanedDockerSandboxes);
+			shutdownSandboxes = shutdownAllDockerSandboxes;
 			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 }) => {
+				factory: async ({ 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
+					return lazySandbox({
+						name: `docker`,
+						workingDirectory: `/work`,
+						factory: () => dockerSandbox({
+							initialNetworkPolicy: { mode: `allow-all` },
+							extraMounts: cwd ? [{
+								hostPath: cwd,
+								containerPath: `/work`,
+								readOnly: false
+							}] : void 0,
+							sandboxKey,
+							persistent,
+							owner,
+							entityType,
+							entityUrl
+						}),
+						reclaim: owner ? () => reclaimDockerSandboxByKey(sandboxKey) : void 0
 					});
 				}
 			});
@@ -1784,7 +1872,10 @@ async function buildBuiltinSandboxProfiles(workingDirectory) {
 	});
 	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;
+	return {
+		profiles,
+		shutdownSandboxes
+	};
 }
 function readWorkingDirectoryArg(args) {
 	const v = args.workingDirectory;
@@ -1803,7 +1894,7 @@ function installDurableStreamsFetchCache(options = {}) {
 		location: options.sqliteLocation,
 		maxCount: options.maxCount
 	}) : new cacheStores.MemoryCacheStore({ maxSize: MEMORY_CACHE_SIZE_BYTES });
-	setGlobalDispatcher(new Agent().compose(interceptors.cache({ store })));
+	setGlobalDispatcher(getGlobalDispatcher().compose(interceptors.cache({ store })));
 }
 
 //#endregion
@@ -2002,6 +2093,9 @@ var BuiltinAgentsServer = class {
 			await Promise.race([this.bootstrap.runtime.drainWakes().catch((err) => {
 				serverLog.error(`[builtin-agents] drainWakes failed during shutdown:`, err);
 			}), new Promise((resolve) => setTimeout(resolve, 5e3))]);
+			if (this.bootstrap.shutdownSandboxes) await Promise.race([this.bootstrap.shutdownSandboxes().catch((err) => {
+				serverLog.error(`[builtin-agents] sandbox shutdown failed during shutdown:`, err);
+			}), new Promise((resolve) => setTimeout(resolve, 5e3))]);
 			this.bootstrap = null;
 		}
 		this.mcpStopping = true;
@@ -2127,4 +2221,4 @@ async function runBuiltinAgentsEntrypoint({ env = process.env, cwd = process.cwd
 }
 
 //#endregion
-export { BuiltinAgentsServer, DEFAULT_BUILTIN_AGENT_HANDLER_PATH, HORTON_MODEL, WORKER_TOOL_NAMES, braveSearchTool, buildHortonSystemPrompt, builtinModelProviderLabel, createAgentHandler, createBuiltinAgentHandler, createBuiltinElectricTools, createHortonDocsSupport, createHortonTools, createSpawnWorkerTool, generateTitle, listBuiltinModelChoices, registerAgentTypes, registerBuiltinAgentTypes, registerHorton, registerWorker, resolveBuiltinAgentsEntrypointOptions, runBuiltinAgentsEntrypoint };
+export { BuiltinAgentsServer, DEFAULT_BUILTIN_AGENT_HANDLER_PATH, HORTON_MODEL, WORKER_TOOL_NAMES, braveSearchTool, buildHortonSystemPrompt, builtinModelProviderLabel, createAgentHandler, createBuiltinAgentHandler, createBuiltinElectricTools, createForkTool, createHortonDocsSupport, createHortonTools, createSpawnWorkerTool, generateTitle, listBuiltinModelChoices, registerAgentTypes, registerBuiltinAgentTypes, registerHorton, registerWorker, resolveBuiltinAgentsEntrypointOptions, runBuiltinAgentsEntrypoint };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@electric-ax/agents",
-  "version": "0.4.14",
+  "version": "0.4.15",
   "description": "Built-in Electric Agents runtimes such as Horton and worker",
   "repository": {
     "type": "git",
@@ -50,7 +50,7 @@
     "undici": "^7.24.7",
     "zod": "^4.3.6",
     "@electric-ax/agents-mcp": "0.2.2",
-    "@electric-ax/agents-runtime": "0.3.10"
+    "@electric-ax/agents-runtime": "0.3.11"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",