@electric-ax/agents 0.4.16 → 0.4.18

package/dist/entrypoint.js

@@ -4,8 +4,8 @@ import { cacheStores, getGlobalDispatcher, interceptors, setGlobalDispatcher } f
 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, createScheduleTools, createSendTool, createWriteTool } from "@electric-ax/agents-runtime/tools";
+import { GOAL_SLASH_COMMAND, MOONSHOT_API_BASE_URL, MOONSHOT_PROVIDER, appendPathToUrl, buildSkillSlashCommands, commentsCollection, completeWithLowCostModel, createContextSkillLoader, createEntityRegistry, createPullWakeRunner, createRuntimeHandler, createSkillsRegistry, db, detectAvailableProviders, dispatchGoalCommand, formatTokenCount, getMoonshotApiKey, getMoonshotModel, getMoonshotModels, isGoalCommandText, parseGoalCommand, pgSync, readCodexAccessToken, registerToolProvider, unregisterToolProvider } from "@electric-ax/agents-runtime";
+import { braveSearchTool, createBashTool, createEditTool, createEventSourceTools, createFetchUrlTool, createMarkGoalCompleteTool, 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";
@@ -19,13 +19,19 @@ import { bridgeMcpTool, buildPromptTools, buildResourceTools, createRegistry, ke
 
 //#region src/durable-streams-cache.ts
 const MEMORY_CACHE_SIZE_BYTES = 100 * 1024 * 1024;
+let installed = false;
 function installDurableStreamsFetchCache(options = {}) {
 	if (options === false) return;
+	if (installed) {
+		console.warn(`[agents] installDurableStreamsFetchCache called more than once; ignoring`);
+		return;
+	}
 	const store = options.store === `sqlite` || options.sqliteLocation ? new cacheStores.SqliteCacheStore({
 		location: options.sqliteLocation,
 		maxCount: options.maxCount
 	}) : new cacheStores.MemoryCacheStore({ maxSize: MEMORY_CACHE_SIZE_BYTES });
 	setGlobalDispatcher(getGlobalDispatcher().compose(interceptors.cache({ store })));
+	installed = true;
 }
 
 //#endregion
@@ -806,6 +812,69 @@ function createSpawnWorkerTool(ctx, modelConfig) {
 	};
 }
 
+//#endregion
+//#region src/tools/observe-pg-sync.ts
+function asToolResult(value) {
+	return {
+		content: [{
+			type: `text`,
+			text: typeof value === `string` ? value : JSON.stringify(value, null, 2)
+		}],
+		details: {}
+	};
+}
+const PgSyncOperation = Type.Union([
+	Type.Literal(`insert`),
+	Type.Literal(`update`),
+	Type.Literal(`delete`)
+]);
+function createObservePgSyncTool(ctx) {
+	return {
+		name: `observe_pg_sync`,
+		label: `Observe Postgres Sync`,
+		description: `Observe an Electric Postgres shape stream and wake this agent when matching row changes arrive.`,
+		parameters: Type.Object({
+			url: Type.Optional(Type.String({ description: `Optional Electric shape endpoint URL. Defaults to the server-configured pg-sync URL.` })),
+			table: Type.String({
+				minLength: 1,
+				pattern: `\\S`,
+				description: `Postgres table name to observe.`
+			}),
+			columns: Type.Optional(Type.Array(Type.String(), { description: `Optional list of columns to include in the shape.` })),
+			where: Type.Optional(Type.String({ description: `Optional Electric shape WHERE clause.` })),
+			params: Type.Optional(Type.Union([Type.Array(Type.String()), Type.Record(Type.String(), Type.String())])),
+			replica: Type.Optional(Type.Union([Type.Literal(`default`), Type.Literal(`full`)])),
+			wake: Type.Optional(Type.Object({
+				ops: Type.Optional(Type.Array(PgSyncOperation)),
+				debounceMs: Type.Optional(Type.Number())
+			}, { additionalProperties: false }))
+		}),
+		execute: async (_toolCallId, params) => {
+			const args = params;
+			if (typeof args.table !== `string` || args.table.trim().length === 0) throw new Error(`table is required`);
+			const source = pgSync({
+				url: args.url,
+				table: args.table,
+				columns: args.columns,
+				where: args.where,
+				params: args.params,
+				replica: args.replica
+			});
+			const wake = {
+				on: `change`,
+				...args.wake?.ops ? { ops: args.wake.ops } : {},
+				...args.wake?.debounceMs !== void 0 ? { debounceMs: args.wake.debounceMs } : {}
+			};
+			await ctx.observe(source, { wake });
+			return asToolResult({
+				sourceRef: source.sourceRef,
+				streamUrl: source.streamUrl,
+				wake
+			});
+		}
+	};
+}
+
 //#endregion
 //#region src/tools/fork.ts
 function createForkTool(ctx) {
@@ -860,6 +929,49 @@ Omit 'entityUrl' to fork your own session. Pass a different session's URL to for
 	};
 }
 
+//#endregion
+//#region src/tools/set-title.ts
+function createSetTitleTool(ctx) {
+	return {
+		name: `set_title`,
+		label: `Set Title`,
+		description: `Set the chat session title shown in the UI. Use this when the current title is missing, stale, misleading, or the user asks to rename the session. Provide a concise, human-readable title.`,
+		parameters: Type.Object({ title: Type.String({ description: `New session title. Whitespace is trimmed and the title must not be empty.` }) }),
+		execute: async (_toolCallId, params) => {
+			const { title } = params;
+			const trimmedTitle = typeof title === `string` ? title.trim() : ``;
+			if (trimmedTitle.length === 0) return {
+				content: [{
+					type: `text`,
+					text: `Error: title must be a non-empty string.`
+				}],
+				details: { updated: false }
+			};
+			try {
+				await ctx.setTag(`title`, trimmedTitle);
+				return {
+					content: [{
+						type: `text`,
+						text: `Session title set to “${trimmedTitle}”.`
+					}],
+					details: {
+						updated: true,
+						title: trimmedTitle
+					}
+				};
+			} catch (err) {
+				return {
+					content: [{
+						type: `text`,
+						text: `Error setting session title: ${err instanceof Error ? err.message : `Unknown error`}`
+					}],
+					details: { updated: false }
+				};
+			}
+		}
+	};
+}
+
 //#endregion
 //#region src/model-catalog.ts
 const MODEL_INPUTS_SCHEMA_DEF = `electricModelInputs`;
@@ -975,25 +1087,66 @@ function filterChoicesByEnabledModels(choices, values) {
 	const filtered = choices.filter((choice) => enabled.has(choice.value));
 	return filtered.length > 0 ? filtered : choices;
 }
+/**
+* Anthropic-specific budget mapping for `reasoningEffort`.
+*
+* Anthropic's `thinking.budget_tokens` is a hard cap on tokens spent
+* inside the thinking block before the model must commit to its
+* answer. Docs require ≥ 1024; we scale from there. Numbers tuned so
+* `medium` is the spot most "show your work" requests land, and
+* `high` covers tougher reasoning without uncapped spend.
+*
+* Keep in sync with provider doc updates — Anthropic has shifted the
+* minimum once already (older models capped lower).
+*/
+const ANTHROPIC_THINKING_BUDGET_BY_EFFORT = {
+	minimal: 1024,
+	low: 2048,
+	medium: 8192,
+	high: 24576
+};
 function withProviderPayloadDefaults(config, choice, reasoningEffort) {
-	if (choice.provider !== `openai` && choice.provider !== `openai-codex` || !choice.reasoning) return config;
-	const defaultEffort = choice.provider === `openai-codex` ? `low` : `minimal`;
-	const effort = reasoningEffort === `minimal` && choice.provider === `openai-codex` ? `low` : reasoningEffort ?? defaultEffort;
-	return {
-		...config,
-		onPayload: (payload) => {
-			if (typeof payload !== `object` || payload === null) return void 0;
-			const body = payload;
-			const existingReasoning = typeof body.reasoning === `object` && body.reasoning !== null ? body.reasoning : {};
-			return {
-				...body,
-				reasoning: {
-					...existingReasoning,
-					effort
-				}
-			};
-		}
-	};
+	if (!choice.reasoning) return config;
+	if (choice.provider === `openai` || choice.provider === `openai-codex`) {
+		const defaultEffort = choice.provider === `openai-codex` ? `low` : `minimal`;
+		const effort = reasoningEffort === `minimal` && choice.provider === `openai-codex` ? `low` : reasoningEffort ?? defaultEffort;
+		return {
+			...config,
+			onPayload: (payload) => {
+				if (typeof payload !== `object` || payload === null) return void 0;
+				const body = payload;
+				const existingReasoning = typeof body.reasoning === `object` && body.reasoning !== null ? body.reasoning : {};
+				return {
+					...body,
+					reasoning: {
+						...existingReasoning,
+						effort
+					}
+				};
+			}
+		};
+	}
+	if (choice.provider === `anthropic`) {
+		const effectiveEffort = reasoningEffort ?? `minimal`;
+		const budgetTokens = ANTHROPIC_THINKING_BUDGET_BY_EFFORT[effectiveEffort];
+		return {
+			...config,
+			onPayload: (payload) => {
+				if (typeof payload !== `object` || payload === null) return void 0;
+				const body = payload;
+				const existingThinking = typeof body.thinking === `object` && body.thinking !== null ? body.thinking : {};
+				return {
+					...body,
+					thinking: {
+						...existingThinking,
+						type: `enabled`,
+						budget_tokens: budgetTokens
+					}
+				};
+			}
+		};
+	}
+	return config;
 }
 function parseReasoningEffort(value) {
 	return value === `minimal` || value === `low` || value === `medium` || value === `high` ? value : null;
@@ -1041,7 +1194,7 @@ function modelInputSchemaDefs(catalog) {
 
 //#endregion
 //#region src/agents/horton.ts
-const TITLE_SYSTEM_PROMPT = "You generate concise chat session titles in 3-5 words. Respond with only the title, no quotes, no punctuation, no preamble.";
+const TITLE_SYSTEM_PROMPT = "You generate a concise 3-5 word chat session title from the user's first message. Respond with only the title — no quotes, punctuation, preamble, or explanation. The user may reference images, files, or attachments you cannot see; infer a title from their intent anyway. Never apologize or say anything is missing — always output a short title.";
 const TITLE_USER_PROMPT = (userMessage) => `User request:\n${userMessage}`;
 const TITLE_GENERATION_TIMEOUT_MS = 8e3;
 const HORTON_SKILLS_SLASH_COMMAND_OWNER = `horton:skills`;
@@ -1135,12 +1288,16 @@ function withTimeout(promise, ms, description) {
 		if (timeout) clearTimeout(timeout);
 	});
 }
+function looksLikeNonTitle(title) {
+	if (title.split(/\s+/).filter(Boolean).length > 8) return true;
+	return /[!?,]/.test(title);
+}
 async function generateTitle(userMessage, llmCall, onFallback) {
 	try {
 		const raw = await llmCall(TITLE_USER_PROMPT(userMessage));
 		const title = raw.trim();
-		if (title.length > 0) return title;
-		onFallback?.(`empty LLM title response`);
+		if (title.length > 0 && !looksLikeNonTitle(title)) return title;
+		onFallback?.(title.length === 0 ? `empty LLM title response` : `non-title LLM response`);
 		return buildFallbackTitle(userMessage);
 	} catch (err) {
 		onFallback?.(err instanceof Error ? err.message : String(err));
@@ -1150,6 +1307,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 titleTool = `\n- set_title: set or rename this chat session's UI title`;
 	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.` : ``;
@@ -1205,8 +1363,9 @@ When a user opens with a greeting ("hi", "hello", "hey", etc.) or a broad statem
 - 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.
+- observe_pg_sync: observe an Electric Postgres sync stream and wake on matching changes
 - send: send a message to an Electric Agent/entity. To schedule future work for yourself, call send with self: true and afterMs.
-${eventSourceTools}${scheduleTools}${docsTools}${skillsTools}
+${eventSourceTools}${titleTool}${scheduleTools}${docsTools}${skillsTools}
 
 # Working with files
 - Prefer edit over write when modifying existing files.
@@ -1251,7 +1410,18 @@ Workflow when forking yourself for parallel exploration:
 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.
 
 Working directory: ${workingDirectory}
-The current year is ${new Date().getFullYear()}.`;
+The current year is ${new Date().getFullYear()}.${buildGoalGuidance(opts.activeGoal)}`;
+}
+function buildGoalGuidance(goal) {
+	if (!goal) return ``;
+	const budgetLine = goal.tokenBudget === null ? `unlimited` : `${goal.tokensUsed} / ${goal.tokenBudget} tokens used`;
+	return `
+
+# Active goal
+- Objective: ${goal.objective}
+- Token budget: ${budgetLine}
+
+The user set this goal with /goal set. Work autonomously toward it: do NOT ask the user clarifying questions or pause for confirmation — make reasonable assumptions and proceed. When you believe the goal is met, call the \`mark_goal_complete\` tool. If you hit a blocker that genuinely requires the user (e.g. credentials, a destructive action), call \`mark_goal_complete\` with a summary explaining what's needed. The runtime will abort this run automatically if you exceed the token budget.`;
 }
 function getToolName(tool) {
 	if (typeof tool !== `object` || tool === null) return null;
@@ -1273,7 +1443,10 @@ function createHortonTools(sandbox, ctx, readSet, opts = {}) {
 		})] : [createFetchUrlTool(sandbox)],
 		createSpawnWorkerTool(ctx, opts.modelConfig),
 		createForkTool(ctx),
+		createObservePgSyncTool(ctx),
+		createSetTitleTool(ctx),
 		createSendTool(ctx.send, { selfEntityUrl: ctx.entityUrl }),
+		...ctx.getGoal()?.status === `active` ? [createMarkGoalCompleteTool(ctx)] : [],
 		...opts.docsSearchTool ? [opts.docsSearchTool] : []
 	];
 }
@@ -1342,11 +1515,58 @@ async function readAgentsMd(sandbox) {
 		return null;
 	}
 }
+function extractWakeText(wake) {
+	if (wake.type !== `inbox`) return null;
+	const payload = wake.payload;
+	if (typeof payload === `string`) return payload;
+	if (payload && typeof payload === `object`) {
+		const record = payload;
+		if (typeof record.text === `string`) return record.text;
+		if (typeof record.source === `string`) return record.source;
+	}
+	return null;
+}
+async function tryHandleSlashCommand(ctx, wake) {
+	const text = extractWakeText(wake);
+	if (text === null) return false;
+	if (isGoalCommandText(text)) {
+		const command = parseGoalCommand(text);
+		const result = dispatchGoalCommand(ctx, command);
+		if (result.message) {
+			serverLog.info(`[horton ${ctx.entityUrl}] ${result.message}`);
+			writeSlashCommandReply(ctx, result.message);
+		}
+		if (command.kind === `set`) await kickoffGoalRun(ctx);
+		return result.handled;
+	}
+	return false;
+}
+const GOAL_KICKOFF_TEXT = `Start working toward the active goal now. Call \`mark_goal_complete\` when you believe it is done.`;
+async function kickoffGoalRun(ctx) {
+	const goal = ctx.getGoal();
+	if (!goal || goal.status !== `active`) return;
+	try {
+		await ctx.send(ctx.entityUrl, {
+			kind: `goal_kickoff`,
+			text: GOAL_KICKOFF_TEXT
+		}, { type: `inbox` });
+	} catch (err) {
+		serverLog.warn(`[horton ${ctx.entityUrl}] failed to enqueue goal kickoff: ${err instanceof Error ? err.message : String(err)}`);
+	}
+}
+function writeSlashCommandReply(ctx, text) {
+	try {
+		ctx.replyText(text);
+	} catch (err) {
+		serverLog.warn(`[horton ${ctx.entityUrl}] failed to render slash command reply: ${err instanceof Error ? err.message : String(err)}`);
+	}
+}
 function createAssistantHandler(options) {
 	const { streamFn, docsSupport, docsSearchTool, skillsRegistry, modelCatalog, docsUrl } = options;
 	const skillLoader = createContextSkillLoader(skillsRegistry, { slashCommandOwner: HORTON_SKILLS_SLASH_COMMAND_OWNER });
 	const hasSkills = skillLoader.hasSkills;
 	return async function assistantHandler(ctx, wake) {
+		if (await tryHandleSlashCommand(ctx, wake)) return;
 		const loadedSkills = await skillLoader.load(ctx);
 		const readSet = new Set();
 		const modelConfig = resolveBuiltinModelConfig(modelCatalog, ctx.args);
@@ -1439,6 +1659,26 @@ function createAssistantHandler(options) {
 				}
 			}
 		});
+		const goal = ctx.getGoal();
+		const enforcedGoal = goal && goal.status === `active` ? goal : void 0;
+		const activeGoalPromptInfo = enforcedGoal ? {
+			objective: enforcedGoal.objective,
+			tokenBudget: enforcedGoal.tokenBudget,
+			tokensUsed: enforcedGoal.tokensUsed
+		} : void 0;
+		const budgetAbort = new AbortController();
+		let runTokensUsed = enforcedGoal?.tokensUsed ?? 0;
+		let budgetTripped = false;
+		const onStepEnd = enforcedGoal ? (stats) => {
+			if (budgetTripped) return;
+			runTokensUsed += stats.uncachedInput + stats.output;
+			ctx.updateGoalUsage(runTokensUsed);
+			if (enforcedGoal.tokenBudget !== null && runTokensUsed >= enforcedGoal.tokenBudget) {
+				budgetTripped = true;
+				serverLog.info(`[horton ${ctx.entityUrl}] goal budget exhausted (${runTokensUsed} tokens) — aborting run`);
+				budgetAbort.abort();
+			}
+		} : void 0;
 		ctx.useAgent({
 			systemPrompt: buildHortonSystemPrompt(sandboxCwd, {
 				hasDocsSupport: Boolean(docsSupport),
@@ -1447,13 +1687,26 @@ function createAssistantHandler(options) {
 				modelProvider: modelConfig.provider,
 				modelId: String(modelConfig.model),
 				hasEventSourceTools,
-				hasScheduleTools
+				hasScheduleTools,
+				...activeGoalPromptInfo && { activeGoal: activeGoalPromptInfo }
 			}),
 			...modelConfig,
 			tools,
-			...streamFn && { streamFn }
+			...streamFn && { streamFn },
+			...onStepEnd && { onStepEnd }
 		});
-		await ctx.agent.run();
+		try {
+			await ctx.agent.run(void 0, budgetAbort.signal);
+		} catch (err) {
+			if (!budgetTripped) throw err;
+			serverLog.info(`[horton ${ctx.entityUrl}] agent.run aborted by budget enforcement`);
+		}
+		if (enforcedGoal) ctx.updateGoalUsage(runTokensUsed, budgetTripped ? { status: `budget_limited` } : void 0);
+		if (budgetTripped && enforcedGoal && enforcedGoal.tokenBudget !== null) {
+			const budget = enforcedGoal.tokenBudget;
+			const suggestedNext = Math.max(budget * 2, budget + 1e4);
+			writeSlashCommandReply(ctx, `⚠️ Stopped — goal hit the token budget (${formatTokenCount(runTokensUsed)} / ${formatTokenCount(budget)} tokens used). Raise the budget with \`/goal set "..." --tokens ${formatTokenCount(suggestedNext)}\`, or call \`/goal complete\` to finalize.`);
+		}
 		await titlePromise;
 	};
 }
@@ -1493,7 +1746,8 @@ function registerHorton(registry, options) {
 			subject_value: `user`,
 			permission: `manage`
 		}],
-		slashCommands: buildSkillSlashCommands(skillsRegistry),
+		state: { comments: commentsCollection },
+		slashCommands: [GOAL_SLASH_COMMAND, ...buildSkillSlashCommands(skillsRegistry)],
 		handler: assistantHandler
 	});
 	return [`horton`];
@@ -1677,6 +1931,7 @@ function registerWorker(registry, options) {
 			subject_value: `user`,
 			permission: `manage`
 		}],
+		state: { comments: commentsCollection },
 		async handler(ctx) {
 			const args = parseWorkerArgs(ctx.args);
 			const readSet = new Set();
@@ -1728,7 +1983,7 @@ function createBuiltinElectricTools(custom) {
 	};
 }
 async function createBuiltinAgentHandler(options) {
-	const { agentServerUrl, serveEndpoint, workingDirectory, streamFn, enabledModelValues, createElectricTools, publicUrl, runtimeName, baseSkillsDir: baseSkillsDirOverride, serverHeaders, defaultDispatchPolicyForType } = options;
+	const { agentServerUrl, serveEndpoint, workingDirectory, streamFn, enabledModelValues, createElectricTools, publicUrl, runtimeName, baseSkillsDir: baseSkillsDirOverride, serverHeaders, defaultDispatchPolicyForType, dockerSandbox: dockerSandboxOpts } = options;
 	const modelCatalog = await createBuiltinModelCatalog({
 		allowMockFallback: Boolean(streamFn),
 		enabledModelValues
@@ -1764,7 +2019,7 @@ async function createBuiltinAgentHandler(options) {
 		modelCatalog
 	});
 	typeNames.push(`worker`);
-	const { profiles: sandboxProfiles, shutdownSandboxes } = await buildBuiltinSandboxProfiles(cwd);
+	const { profiles: sandboxProfiles, shutdownSandboxes } = await buildBuiltinSandboxProfiles(cwd, dockerSandboxOpts);
 	const runtime = createRuntimeHandler({
 		baseUrl: agentServerUrl,
 		serveEndpoint,
@@ -1784,7 +2039,8 @@ async function createBuiltinAgentHandler(options) {
 		registry,
 		typeNames,
 		skillsRegistry,
-		shutdownSandboxes
+		shutdownSandboxes,
+		modelCatalog
 	};
 }
 async function registerBuiltinAgentTypes(bootstrap) {
@@ -1803,6 +2059,21 @@ function sweepOrphanedDockerSandboxesOnce(sweep) {
 	return dockerBootSweep;
 }
 /**
+* Merge the profile's working-directory mount with embedder docker options
+* into the option fragment spread into `dockerSandbox()`. An internal helper:
+* exported from this module so the unit test can import it, but intentionally
+* not re-exported from `index.ts` (not part of the package's public API).
+*/
+function resolveDockerSandboxOpts(cwdMount, custom) {
+	const extraMounts = [...cwdMount ? [cwdMount] : [], ...custom?.extraMounts ?? []];
+	return {
+		...custom?.image !== void 0 && { image: custom.image },
+		...custom?.allowFloatingTag !== void 0 && { allowFloatingTag: custom.allowFloatingTag },
+		...custom?.env !== void 0 && { env: custom.env },
+		...extraMounts.length > 0 && { extraMounts }
+	};
+}
+/**
 * 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.
@@ -1812,7 +2083,7 @@ function sweepOrphanedDockerSandboxesOnce(sweep) {
 * server must run on shutdown (the providers' debounced idle teardowns die
 * with the process).
 */
-async function buildBuiltinSandboxProfiles(workingDirectory) {
+async function buildBuiltinSandboxProfiles(workingDirectory, dockerOpts) {
 	const profiles = [{
 		name: `local`,
 		label: `Local`,
@@ -1837,11 +2108,11 @@ async function buildBuiltinSandboxProfiles(workingDirectory) {
 						workingDirectory: `/work`,
 						factory: () => dockerSandbox({
 							initialNetworkPolicy: { mode: `allow-all` },
-							extraMounts: cwd ? [{
+							...resolveDockerSandboxOpts(cwd ? {
 								hostPath: cwd,
 								containerPath: `/work`,
 								readOnly: false
-							}] : void 0,
+							} : void 0, dockerOpts),
 							sandboxKey,
 							persistent,
 							owner,