@agimon-ai/doompi-core 0.0.1-alpha.100

package/dist/src/systems/main/adapters/headlessSessionHost.mjs

@@ -0,0 +1,1288 @@
+import { DOOM_CHILD_SESSION_MCP_TOOL_SERVICE, DOOM_CHILD_SESSION_SERVICE } from "../../child/types/childSession.mjs";
+import "../../../schemas/headless.mjs";
+import { createHistoryOwnership } from "../../../../historyOwnership.mjs";
+import { HeadlessHost, describeLoadSkillTool, headlessHarnessSkill } from "./headlessHost.mjs";
+import { harnessErrorMessage } from "../../../server/harnessErrorMessage.mjs";
+import { createDirectHarnessRuntime } from "../../../server/directHarnessRuntime.mjs";
+import { buildContextDetail } from "../../../../contextDetail.mjs";
+import { writeContextDetail } from "../../../../contextDetailStore.mjs";
+import { DOOM_CONTEXT_ENTRY_TYPE, projectContext } from "../../../../contextProjection.mjs";
+import { createHeadlessClient } from "../../../services/headlessClient/index.mjs";
+import { createPiExtensionHost, preloadPiExtensions, resolvePiExtensionEntries, resolvePiSettingsPackageEntries } from "../../../services/piExtensionHost/index.mjs";
+import { formatToolPrompt } from "../../../services/toolPrompt/index.mjs";
+import { createHeadlessChildSessionServiceProvider } from "../../child/adapters/headlessChildSessionService.mjs";
+import { randomUUID } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { Value } from "typebox/value";
+import { BACKGROUND_CONTEXT } from "@earendil-works/pi-agent-core/harness/context";
+import { value } from "@earendil-works/pi-agent-core/harness/session";
+import { formatSkillsForSystemPrompt } from "@earendil-works/pi-agent-core";
+import { ModelRuntime, SettingsManager, getAgentDir, loadProjectContextFiles, parseArgs, resolveCliModel, resolveModelScopeWithDiagnostics } from "@earendil-works/pi-coding-agent";
+//#region src/systems/main/adapters/headlessSessionHost.ts
+const EXTERNAL_OPERATION = "external";
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function stringArray(value) {
+	return Array.isArray(value) && value.every((entry) => typeof entry === "string") ? value : void 0;
+}
+/** Restores the last accepted live selection from journal projections, falling back on launch configuration. */
+function restoreHeadlessSelection(entries, fallback) {
+	let projected;
+	for (let index = entries.length - 1; index >= 0 && projected === void 0; index -= 1) {
+		const entry = entries[index];
+		if (!isRecord(entry) || entry.type !== "custom" || !isRecord(entry.data)) continue;
+		if (projected === void 0 && entry.customType === "doom-context") {
+			const selection = entry.data.selection;
+			if (!isRecord(selection) || typeof selection.majorMode !== "string") continue;
+			const domains = stringArray(selection.domains);
+			if (domains === void 0 || selection.profile !== void 0 && typeof selection.profile !== "string") continue;
+			projected = {
+				majorMode: selection.majorMode,
+				domains,
+				...typeof selection.profile === "string" ? { profile: selection.profile } : {}
+			};
+		}
+	}
+	return {
+		...fallback,
+		...projected
+	};
+}
+function isJsonValue(value) {
+	if (value === null || typeof value === "string" || typeof value === "boolean") return true;
+	if (typeof value === "number") return Number.isFinite(value);
+	if (Array.isArray(value)) return value.every(isJsonValue);
+	return isRecord(value) && Object.values(value).every(isJsonValue);
+}
+function isJsonObject(value) {
+	return isRecord(value) && Object.values(value).every(isJsonValue);
+}
+function isToolContent(value) {
+	return Array.isArray(value) && value.every((part) => {
+		if (!isRecord(part)) return false;
+		if (part.type === "text") return typeof part.text === "string";
+		return part.type === "image" && typeof part.data === "string" && typeof part.mimeType === "string";
+	});
+}
+function isUsage(value) {
+	if (!isRecord(value) || !isRecord(value.cost)) return false;
+	const cost = value.cost;
+	return [
+		"input",
+		"output",
+		"cacheRead",
+		"cacheWrite",
+		"totalTokens"
+	].every((key) => typeof value[key] === "number" && Number.isFinite(value[key])) && [
+		"input",
+		"output",
+		"cacheRead",
+		"cacheWrite",
+		"total"
+	].every((key) => typeof cost[key] === "number" && Number.isFinite(cost[key]));
+}
+function isAgentMessage(value) {
+	if (!isRecord(value) || typeof value.timestamp !== "number" || !Number.isFinite(value.timestamp)) return false;
+	if (value.role === "user") return typeof value.content === "string" || Array.isArray(value.content);
+	if (!Array.isArray(value.content)) return false;
+	if (value.role === "assistant") return typeof value.api === "string" && typeof value.provider === "string" && typeof value.model === "string" && typeof value.stopReason === "string" && isUsage(value.usage);
+	return value.role === "toolResult" && typeof value.toolCallId === "string" && typeof value.toolName === "string" && typeof value.isError === "boolean";
+}
+function isCompactResult(value) {
+	return isRecord(value) && typeof value.summary === "string" && typeof value.tokensBefore === "number" && Number.isFinite(value.tokensBefore) && Array.isArray(value.retainedTail) && value.retainedTail.every(isAgentMessage) && (value.usage === void 0 || isUsage(value.usage)) && (value.details === void 0 || isJsonValue(value.details));
+}
+const unsupported = (parsed) => {
+	const match = [
+		["--help", parsed.help],
+		["--version", parsed.version],
+		["--mode", parsed.mode],
+		["--print", parsed.print],
+		["--export", parsed.export],
+		["--no-session", parsed.noSession],
+		["--continue", parsed.continue],
+		["--resume", parsed.resume],
+		["--fork", parsed.fork],
+		["--list-models", parsed.listModels],
+		["--offline", parsed.offline],
+		["--tui-mode", parsed.tuiMode],
+		["--extensions", parsed.extensions],
+		["--no-extensions", parsed.noExtensions],
+		["--skills", parsed.skills],
+		["--no-skills", parsed.noSkills],
+		["--prompt-templates", parsed.promptTemplates],
+		["--no-prompt-templates", parsed.noPromptTemplates],
+		["--themes", parsed.themes],
+		["--no-themes", parsed.noThemes],
+		["--no-context-files", parsed.noContextFiles],
+		["--tools", parsed.tools],
+		["--exclude-tools", parsed.excludeTools],
+		["--no-tools", parsed.noTools],
+		["--no-builtin-tools", parsed.noBuiltinTools],
+		["--project-trust-override", parsed.projectTrustOverride],
+		["--verbose", parsed.verbose]
+	].find(([, value]) => value !== void 0 && value !== false);
+	if (match) return `Direct headless mode does not support ${match[0]}.`;
+	if (parsed.messages.length > 0 || parsed.fileArgs.length > 0) return "Direct headless mode does not support positional prompts or files.";
+	const unknown = parsed.unknownFlags.keys().next().value;
+	return typeof unknown === "string" ? `Direct headless mode does not support --${unknown}.` : void 0;
+};
+/** Validate the Pi flags that remain after Doom's harness flags are removed. */
+function validateDirectHeadlessArgs(agentArgs) {
+	if (agentArgs.includes("--mode")) throw new Error("Direct headless mode does not support --mode.");
+	const parsed = parseArgs([...agentArgs]);
+	const diagnostics = parsed.diagnostics.filter((diagnostic) => diagnostic.type === "error");
+	if (diagnostics.length) throw new Error(diagnostics.map((diagnostic) => diagnostic.message).join("\n"));
+	const error = unsupported(parsed);
+	if (error) throw new Error(error);
+	return parsed;
+}
+function modelIdentity(model) {
+	return {
+		provider: model.provider,
+		id: model.id
+	};
+}
+async function resolveModel(parsed, modelRuntime, settings) {
+	const cli = resolveCliModel({
+		cliProvider: parsed.provider,
+		cliModel: parsed.model,
+		cliThinking: parsed.thinking,
+		modelRuntime
+	});
+	if (cli.error) throw new Error(cli.error);
+	let scoped;
+	if (parsed.models !== void 0 && parsed.models.length > 0) {
+		scoped = (await resolveModelScopeWithDiagnostics(parsed.models, modelRuntime)).scopedModels[0]?.model;
+		if (scoped === void 0) throw new Error(`No configured model matched --models ${parsed.models.join(", ")}.`);
+	}
+	const configured = cli.model ?? scoped ?? (settings.getDefaultProvider() && settings.getDefaultModel() ? modelRuntime.getModel(settings.getDefaultProvider(), settings.getDefaultModel()) : void 0) ?? (await modelRuntime.getAvailable())[0];
+	if (configured === void 0) throw new Error("Direct headless mode could not resolve a configured model.");
+	return {
+		model: configured,
+		thinkingLevel: cli.thinkingLevel ?? parsed.thinking ?? settings.getModelThinkingLevel(configured.provider, configured.id) ?? settings.getDefaultThinkingLevel()
+	};
+}
+function mapResources(resources) {
+	const skills = [];
+	const advertised = [];
+	const promptTemplates = [];
+	const context = [];
+	for (const resource of resources) if (resource.kind === "skill") {
+		const skill = headlessHarnessSkill(resource);
+		skills.push(skill);
+		if (resource.path !== void 0 && !advertised.some((entry) => entry.name === skill.name)) advertised.push(skill);
+	} else if (resource.kind === "prompt") promptTemplates.push({
+		name: resource.name,
+		content: resource.text
+	});
+	else context.push(resource.text);
+	return {
+		harness: {
+			skills,
+			promptTemplates
+		},
+		context,
+		advertised
+	};
+}
+function toolAdapter(tool, executionContext, reportedErrors) {
+	return {
+		name: tool.name,
+		label: tool.label ?? tool.name,
+		description: tool.description,
+		parameters: tool.parameters,
+		...tool.promptSnippet === void 0 ? {} : { promptSnippet: tool.promptSnippet },
+		...tool.promptGuidelines === void 0 ? {} : { promptGuidelines: tool.promptGuidelines },
+		...tool.executionMode === void 0 ? {} : { executionMode: tool.executionMode === "parallel" ? "parallel" : "sequential" },
+		async execute(toolCallId, parameters, onUpdate, _toolContext, _invocation, context) {
+			const result = await tool.execute(toolCallId, parameters, context.abortSignal, (partial) => onUpdate({
+				content: partial.content,
+				details: partial.details
+			}), executionContext());
+			if (result.isError === true) reportedErrors.add(toolCallId);
+			return {
+				content: result.content,
+				details: result.details
+			};
+		}
+	};
+}
+function eventHook(event) {
+	return {
+		run_start: "agent_start",
+		run_resume: "agent_start",
+		run_end: "agent_settled",
+		turn_start: "turn_start",
+		turn_end: "turn_end",
+		message_start: "message_start",
+		message_update: "message_update",
+		message_end: "message_end",
+		tool_start: "tool_execution_start",
+		tool_update: "tool_execution_update",
+		tool_end: "tool_execution_end",
+		compaction_end: "session_compact",
+		navigation_end: "session_tree"
+	}[event];
+}
+function emitTo(listeners, frame) {
+	const snapshot = [...listeners];
+	for (const listener of snapshot) try {
+		listener(frame);
+	} catch {}
+}
+function createHeadlessCompositionPublisher(runtime, host, environment, groups, readSystemPrompt) {
+	let countTokens;
+	let contextRevision = 0;
+	let publishedContext;
+	let tail = Promise.resolve();
+	const publish = async (selection) => {
+		countTokens ??= (await import("gpt-tokenizer")).countTokens;
+		const inventory = host.getContextInventory(selection, countTokens);
+		const prompt = readSystemPrompt();
+		const promptCost = prompt === void 0 ? void 0 : {
+			tokens: countTokens(prompt.text),
+			stage: prompt.stage
+		};
+		const context = projectContext({
+			revision: contextRevision + 1,
+			majorMode: selection.majorMode,
+			...selection.profile === void 0 ? {} : { profile: selection.profile },
+			groups: groups(selection),
+			domains: selection.domains,
+			sources: inventory.sources,
+			skills: inventory.skills,
+			attribution: inventory.attribution,
+			countTokens,
+			...promptCost === void 0 ? {} : { systemPrompt: promptCost }
+		});
+		const contextKey = JSON.stringify({
+			...context,
+			revision: 0,
+			promptText: prompt?.text
+		});
+		if (contextKey === publishedContext) return;
+		const revision = contextRevision + 1;
+		const details = buildContextDetail({
+			sources: inventory.sources,
+			skills: inventory.skills,
+			countTokens,
+			...prompt === void 0 || promptCost === void 0 ? {} : { systemPrompt: {
+				text: prompt.text,
+				tokens: promptCost.tokens,
+				stage: prompt.stage
+			} }
+		});
+		await runtime.appendCustomEntry(DOOM_CONTEXT_ENTRY_TYPE, {
+			...context,
+			revision
+		});
+		writeContextDetail(runtime.sessionId, revision, details, environment);
+		contextRevision = revision;
+		publishedContext = contextKey;
+	};
+	return (selection = host.context.selection) => {
+		tail = tail.then(() => publish(selection), () => publish(selection));
+		return tail;
+	};
+}
+/** Create the gated, same-process host used by direct-headless startup tests. */
+async function createHeadlessSessionHost(options) {
+	const parsed = validateDirectHeadlessArgs(options.agentArgs);
+	const agentDir = getAgentDir();
+	const settings = SettingsManager.create(options.cwd, agentDir);
+	const modelRuntime = await ModelRuntime.create({
+		authPath: path.join(agentDir, "auth.json"),
+		modelsPath: path.join(agentDir, "models.json"),
+		refreshOnCreate: false
+	});
+	const piExtensionPaths = options.piExtensions === false ? [] : [...options.piExtensionPaths ?? resolvePiExtensionEntries(options.repoRoot), ...await resolvePiSettingsPackageEntries({
+		cwd: options.cwd,
+		agentDir,
+		settings,
+		...options.onNotice === void 0 ? {} : { onNotice: options.onNotice }
+	})];
+	const piPreload = await preloadPiExtensions({
+		cwd: options.cwd,
+		agentDir,
+		models: modelRuntime,
+		extensionPaths: [...new Set(piExtensionPaths)],
+		...options.onNotice === void 0 ? {} : { onNotice: options.onNotice }
+	});
+	const resolved = await resolveModel(parsed, modelRuntime, settings);
+	if (parsed.apiKey !== void 0) await modelRuntime.setRuntimeApiKey(resolved.model.provider, parsed.apiKey);
+	const reportedToolErrors = /* @__PURE__ */ new Set();
+	let promptPreparationFailed = false;
+	let headlessReady = false;
+	let toolGuidance = [];
+	const initialSystemPrompt = [parsed.systemPrompt, ...parsed.appendSystemPrompt ?? []].filter(Boolean).join("\n\n");
+	/**
+	* AGENTS.md and friends, in Pi's own framing.
+	*
+	* The server had none of this: its prompt began at the --system-prompt flag, so a
+	* repository's own instructions reached a terminal session and never a cockpit one.
+	* Mirrors @earendil-works/pi-coding-agent@0.86.0 dist/core/system-prompt.js:21-27
+	* (the customPrompt branch, which is the shape this host matches). `buildSystemPrompt`
+	* is not exported and the package exports map has no wildcard, so the four literals
+	* below are copied; re-diff them against that file on upgrade.
+	*
+	* Not trust-gated, deliberately: TRUST_REQUIRING_PROJECT_CONFIG_RESOURCES in Pi's
+	* trust-manager covers settings.json, extensions, skills, prompts, themes, SYSTEM.md
+	* and APPEND_SYSTEM.md, all of which execute or replace instructions. AGENTS.md is
+	* advisory prose and Pi appends it unconditionally; gating it here would be a
+	* divergence from Pi rather than parity with it.
+	*
+	* Resolved once: cwd is fixed for the host's lifetime, and composeSystemPrompt runs
+	* on every generation.
+	*/
+	const projectContextFiles = loadProjectContextFiles({
+		cwd: options.cwd,
+		agentDir
+	});
+	const projectContextBlock = (() => {
+		if (projectContextFiles.length === 0) return "";
+		return `<project_context>\n\nProject-specific instructions and guidelines:\n\n${projectContextFiles.map(({ path: filePath, content }) => `<project_instructions path="${filePath}">\n${content}\n</project_instructions>\n`).join("\n")}\n</project_context>`;
+	})();
+	const workingDirectoryLine = `Current working directory: ${options.cwd.replace(/\\/g, "/")}`;
+	/**
+	* Everything the prompt is made of before a package has had a say.
+	*
+	* Shared with the runtime callback below rather than copied. Assembling it is
+	* pure; the hook pass that follows it there is not, which is why the context
+	* panel is shown this rather than a prompt built for the panel's sake.
+	*/
+	const composeSystemPrompt = (resources) => {
+		const mapped = mapResources(resources);
+		const skills = toolGuidance.some((entry) => entry.name === "load_skill") ? "" : formatSkillsForSystemPrompt(mapped.advertised).trim();
+		return [
+			initialSystemPrompt,
+			projectContextBlock,
+			formatToolPrompt(toolGuidance),
+			skills,
+			...mapped.context,
+			workingDirectoryLine
+		].filter(Boolean).join("\n\n");
+	};
+	/** The last prompt a turn actually built, once one has. */
+	let builtSystemPrompt;
+	/**
+	* What the context panel is shown: the prompt a turn sent, or the hook-free
+	* base until one has.
+	*
+	* The base is composed from the applied snapshot rather than a fresh read, so
+	* it answers at exactly the moments the tool inventory beside it answers.
+	* Re-reading refuses while a selection is mid-apply, and the panel would then
+	* spend a published revision saying there is no prompt before the next one
+	* said there is.
+	*/
+	const readSystemPrompt = () => {
+		if (!headlessHost) return void 0;
+		if (builtSystemPrompt !== void 0) return {
+			text: builtSystemPrompt,
+			stage: "effective"
+		};
+		return {
+			text: composeSystemPrompt(headlessHost.appliedResources),
+			stage: "base"
+		};
+	};
+	const beforeTool = async (event) => {
+		if (!headlessReady || !headlessHost) throw new Error("Headless capabilities are not installed.");
+		const patches = await headlessHost.dispatchHook("tool_call", event);
+		let args = event.args;
+		let block;
+		for (const patch of patches) {
+			if (!isRecord(patch)) continue;
+			if (patch.args !== void 0) {
+				if (!isJsonObject(patch.args)) throw new Error("Invalid headless tool arguments");
+				args = patch.args;
+			}
+			if (patch.block === void 0) continue;
+			if (!isRecord(patch.block) || typeof patch.block.reason !== "string" || patch.block.terminate !== void 0 && typeof patch.block.terminate !== "boolean") throw new Error("Invalid headless tool denial");
+			block = {
+				reason: patch.block.reason,
+				...typeof patch.block.terminate === "boolean" ? { terminate: patch.block.terminate } : {}
+			};
+			break;
+		}
+		return {
+			...args === event.args ? {} : { args },
+			...block === void 0 ? {} : { block }
+		};
+	};
+	const afterTool = async (event) => {
+		if (!headlessReady || !headlessHost) throw new Error("Headless capabilities are not installed.");
+		const original = reportedToolErrors.delete(event.toolCallId) ? {
+			...event,
+			isError: true
+		} : event;
+		const patches = await headlessHost.dispatchHook("tool_result", original);
+		let content = original.content;
+		let details = original.details;
+		let isError = original.isError;
+		let usage = original.usage;
+		let terminate;
+		for (const patch of patches) {
+			if (!isRecord(patch)) continue;
+			if (isToolContent(patch.content)) content = patch.content;
+			if ("details" in patch && isJsonValue(patch.details)) details = patch.details;
+			if (typeof patch.isError === "boolean") isError = patch.isError;
+			if (isUsage(patch.usage)) usage = patch.usage;
+			if (typeof patch.terminate === "boolean") terminate = patch.terminate;
+		}
+		return {
+			...content === event.content ? {} : { content },
+			...details === event.details ? {} : { details },
+			...isError === event.isError ? {} : { isError },
+			...usage === event.usage ? {} : { usage },
+			...terminate === void 0 ? {} : { terminate }
+		};
+	};
+	const runtime = await createDirectHarnessRuntime({
+		cwd: options.cwd,
+		sessionId: options.sessionId,
+		...options.parentSessionId === void 0 ? {} : { parentSessionId: options.parentSessionId },
+		storage: "sqlite",
+		historyOwnership: createHistoryOwnership({ sourceFormat: "sqlite" }),
+		sessionName: parsed.name ?? options.sessionName,
+		...parsed.session === void 0 ? {} : { sessionPath: parsed.session },
+		sessionsRoot: parsed.sessionDir ?? path.join(agentDir, "server", "sessions"),
+		models: modelRuntime,
+		model: resolved.model,
+		...resolved.thinkingLevel === void 0 ? {} : { thinkingLevel: resolved.thinkingLevel },
+		beforeModelRequest: async ({ phase }) => {
+			if (!headlessReady || !headlessHost) throw new Error("Headless capabilities are not installed.");
+			if (phase === "turn" && options.inheritedSelection) await headlessHost.inheritSelection(await options.inheritedSelection());
+		},
+		transformContext: async (event) => {
+			if (!headlessReady || !headlessHost) throw new Error("Headless capabilities are not installed.");
+			const patches = await headlessHost.dispatchHook("context", event);
+			let messages = event.messages;
+			let systemPrompt = event.systemPrompt;
+			for (const patch of patches) {
+				if (!isRecord(patch)) continue;
+				if (patch.messages !== void 0) {
+					if (!Array.isArray(patch.messages)) throw new Error("Invalid headless context messages");
+					messages = patch.messages;
+				}
+				if (patch.systemPrompt !== void 0) {
+					if (typeof patch.systemPrompt !== "string") throw new Error("Invalid headless context system prompt");
+					systemPrompt = patch.systemPrompt;
+				}
+			}
+			return {
+				messages: await (piHost?.transformContext(messages) ?? messages),
+				systemPrompt
+			};
+		},
+		beforeTool,
+		afterTool,
+		beforePayload: async (event) => {
+			if (!headlessReady || !headlessHost) throw new Error("Headless capabilities are not installed.");
+			const patches = await headlessHost.dispatchHook("before_provider_request", event);
+			let payload = event.payload;
+			for (const patch of patches) {
+				if (patch === void 0 || patch === null) continue;
+				if (!isRecord(patch) || !("payload" in patch)) throw new Error("Invalid headless provider payload patch");
+				payload = patch.payload;
+			}
+			return { payload };
+		},
+		beforeCompaction: async (event) => {
+			if (!headlessReady || !headlessHost) throw new Error("Headless capabilities are not installed.");
+			const patches = await headlessHost.dispatchHook("session_before_compact", {
+				reason: event.reason,
+				preparation: event.preparation,
+				...event.customInstructions === void 0 ? {} : {
+					instructions: event.customInstructions,
+					customInstructions: event.customInstructions
+				}
+			});
+			try {
+				for (const patch of patches) {
+					if (patch === void 0 || patch === null) continue;
+					if (!isRecord(patch)) throw new Error("Invalid headless compaction patch");
+					if (patch.cancel !== void 0 && typeof patch.cancel !== "boolean") throw new Error("Invalid headless compaction cancellation");
+					if (patch.decline !== void 0 && typeof patch.decline !== "boolean") throw new Error("Invalid headless compaction decline");
+					const decline = patch.cancel === true || patch.decline === true;
+					if (decline && patch.compaction !== void 0) throw new Error("Conflicting headless compaction patch");
+					if (decline) return { decline: true };
+					if (patch.compaction !== void 0) {
+						if (!isCompactResult(patch.compaction)) throw new Error("Invalid headless compaction result");
+						return { compaction: patch.compaction };
+					}
+				}
+			} catch (error) {
+				options.onNotice?.(`Headless compaction hook rejected: ${error instanceof Error ? error.message : String(error)}`);
+				return { decline: true };
+			}
+			return piHost?.beforeCompaction(event);
+		},
+		systemPrompt: async () => {
+			try {
+				if (!headlessHost) throw new Error("Headless capabilities are not installed.");
+				let prompt = composeSystemPrompt(await headlessHost.readResources());
+				const patches = await headlessHost.dispatchHook("before_agent_start", { systemPrompt: prompt });
+				for (const patch of patches) if (patch && typeof patch === "object" && "systemPrompt" in patch && typeof patch.systemPrompt === "string") prompt = patch.systemPrompt;
+				promptPreparationFailed = false;
+				if (prompt !== builtSystemPrompt) {
+					builtSystemPrompt = prompt;
+					try {
+						await publishComposition();
+					} catch {}
+				}
+				return prompt;
+			} catch {
+				promptPreparationFailed = true;
+				return "";
+			}
+		},
+		listCommands: () => {
+			if (!headlessReady || !headlessHost) throw new Error("Headless capabilities are not installed.");
+			return headlessHost.listCommands();
+		},
+		dispatchCommand: async (text) => {
+			const match = /^\/(\S+)(?:\s+([\s\S]*))?$/.exec(text);
+			if (!match) return false;
+			if (!headlessReady || !headlessHost) throw new Error("Headless capabilities are not installed.");
+			const name = match[1];
+			const args = match[2] ?? "";
+			if (!headlessHost.listCommands().some((entry) => entry.name === name)) return false;
+			await headlessHost.dispatchCommand(name, args);
+			return true;
+		},
+		guardModelRequest: () => {
+			if (!headlessReady || promptPreparationFailed || !headlessHost?.status.ready) throw new Error("Headless capability preparation is not ready.");
+		}
+	});
+	const opened = await (async () => {
+		await runtime.session.setValue(value("doompi.session", "workspaceRoot"), options.repoRoot, BACKGROUND_CONTEXT);
+		await runtime.session.setValue(value("doompi.session", "execution"), JSON.stringify({
+			cwd: options.cwd,
+			repoRoot: options.repoRoot,
+			workspaceId: options.workspaceId,
+			groupingRoot: options.groupingRoot ?? options.repoRoot,
+			parentSessionId: options.parentSessionId,
+			sessionProvenance: options.sessionProvenance,
+			inheritedArtifact: options.inheritedArtifact
+		}), BACKGROUND_CONTEXT);
+		return {
+			model: await runtime.lane.getModel(BACKGROUND_CONTEXT),
+			entries: (await Promise.all([DOOM_CONTEXT_ENTRY_TYPE].map((customType) => runtime.lane.findEntries({
+				type: "custom",
+				customType,
+				order: "newestFirst",
+				limit: 1
+			}, BACKGROUND_CONTEXT)))).flat()
+		};
+	})().catch(async (error) => {
+		await runtime.dispose().catch((disposeError) => options.onNotice?.(`Session runtime failed to close: ${String(disposeError)}`));
+		throw error;
+	});
+	let currentModel = opened.model;
+	const sessionContext = options.workspaceId === void 0 ? void 0 : Object.freeze({
+		sessionId: runtime.sessionId,
+		workspaceId: options.workspaceId,
+		workspaceRoot: options.groupingRoot ?? options.repoRoot,
+		checkoutRoot: options.repoRoot,
+		cwd: options.cwd,
+		...options.parentSessionId === void 0 ? {} : { parentSessionId: options.parentSessionId },
+		...options.sessionProvenance === void 0 ? {} : { provenance: options.sessionProvenance }
+	});
+	const entries = opened.entries;
+	const listeners = /* @__PURE__ */ new Set();
+	const selectionListeners = /* @__PURE__ */ new Set();
+	let latestSelection = options.selection;
+	const initialSelection = restoreHeadlessSelection(entries, options.selection);
+	let headlessHost;
+	let mcpServiceRoot;
+	let mcpLifecycle = new AbortController();
+	let piHost;
+	let client;
+	let disposed = false;
+	let disposePromise;
+	let publishComposition = async () => {
+		throw new Error("Direct headless composition publisher is not installed.");
+	};
+	const readMcpContext = (signal) => {
+		signal.throwIfAborted();
+		const host = headlessHost;
+		if (!host || disposed) throw new Error("Session context is unavailable.");
+		const status = host.status;
+		if (!status.ready || status.requestedRevision !== status.appliedRevision) throw new Error("Session context is unavailable.");
+		const root = fs.realpathSync(options.repoRoot);
+		const globalInstruction = path.join(fs.realpathSync(agentDir), "AGENTS.md");
+		const instructions = projectContextFiles.flatMap(({ path: filePath, content }) => {
+			const relative = path.relative(options.repoRoot, filePath);
+			if (relative === "" || relative.startsWith("..") || path.isAbsolute(relative)) return [];
+			try {
+				const canonicalPath = fs.realpathSync(filePath);
+				if (canonicalPath === globalInstruction) return [];
+				const canonicalRelative = path.relative(root, canonicalPath);
+				if (canonicalRelative === "" || canonicalRelative.startsWith("..") || path.isAbsolute(canonicalRelative)) return [];
+			} catch {
+				return [];
+			}
+			return [{
+				path: relative.replaceAll(path.sep, "/"),
+				content
+			}];
+		});
+		const selection = host.context.selection;
+		const persona = host.appliedResources.find(({ name, kind }) => name === "doompi/profile-config" && kind === "context")?.text;
+		signal.throwIfAborted();
+		const current = host.status;
+		if (!current.ready || current.appliedRevision !== status.appliedRevision || current.requestedRevision !== current.appliedRevision) throw new Error("Session context changed. Call load_context again.");
+		return {
+			session: {
+				id: runtime.sessionId,
+				revision: status.appliedRevision
+			},
+			repository: {
+				root: options.repoRoot,
+				cwd: options.cwd
+			},
+			selection: {
+				profile: selection.profile ?? null,
+				domains: [...selection.domains],
+				majorMode: selection.majorMode,
+				activeLayers: [...selection.activeLayers],
+				minorModes: [...selection.state?.["minor-mode"] ?? []]
+			},
+			instructions,
+			persona: persona ?? null
+		};
+	};
+	const childSessionProvider = createHeadlessChildSessionServiceProvider({
+		parentSessionId: runtime.sessionId,
+		cwd: options.cwd,
+		sessionsRoot: parsed.sessionDir ?? path.join(agentDir, "server", "sessions"),
+		models: modelRuntime,
+		defaultModel: () => currentModel,
+		mcpTool: () => {
+			if (disposed || !headlessReady || !headlessHost?.status.ready) return void 0;
+			return mcpServiceRoot?.get(DOOM_CHILD_SESSION_MCP_TOOL_SERVICE);
+		}
+	});
+	const completeAuxiliaryModel = async (reference, request) => {
+		if (disposed || !headlessReady || promptPreparationFailed || !headlessHost?.status.ready) throw new Error("Headless capability preparation is not ready.");
+		request.signal?.throwIfAborted();
+		const separator = reference.indexOf("/");
+		const model = separator > 0 ? modelRuntime.getModel(reference.slice(0, separator), reference.slice(separator + 1)) : void 0;
+		if (!model || !modelRuntime.hasConfiguredAuth(model.provider)) throw new Error(`Model is not configured: ${reference}`);
+		if (!runtime.completeModel) throw new Error("The runtime does not support auxiliary model requests.");
+		const response = await runtime.completeModel(model, {
+			systemPrompt: request.systemPrompt,
+			messages: [{
+				role: "user",
+				content: request.input,
+				timestamp: Date.now()
+			}],
+			...request.tools ? { tools: [...request.tools] } : {}
+		}, {
+			signal: request.signal,
+			maxTokens: request.maxTokens,
+			cacheRetention: request.cacheRetention,
+			reasoningEffort: "none",
+			maxRetries: 0
+		});
+		request.signal?.throwIfAborted();
+		if (response.stopReason === "error" || response.stopReason === "aborted") throw new Error(response.errorMessage ?? `Model stopped: ${response.stopReason}`);
+		return response;
+	};
+	const executionContext = (selection) => ({
+		cwd: options.cwd,
+		repoRoot: options.repoRoot,
+		sessionId: runtime.sessionId,
+		...sessionContext === void 0 ? {} : { sessionContext },
+		environment: options.environment,
+		client: client.client,
+		model: currentModel === void 0 ? void 0 : modelIdentity(currentModel),
+		selection,
+		textCompletion: {
+			available(reference) {
+				const separator = reference.indexOf("/");
+				return separator > 0 && !!modelRuntime.getModel(reference.slice(0, separator), reference.slice(separator + 1)) && modelRuntime.hasConfiguredAuth(reference.slice(0, separator));
+			},
+			async complete(reference, request) {
+				return (await completeAuxiliaryModel(reference, {
+					...request,
+					tools: void 0
+				})).content.filter((part) => part.type === "text").map((part) => part.text).join("").trim();
+			}
+		},
+		toolCompletion: { async complete(reference, request) {
+			const response = await completeAuxiliaryModel(reference, request);
+			if (response.stopReason === "length") throw new Error("Auxiliary tool request exceeded its output limit.");
+			return {
+				toolCalls: response.content.filter((part) => part.type === "toolCall"),
+				usage: response.usage
+			};
+		} },
+		session: {
+			async readModelSettings() {
+				const model = await runtime.lane.getModel(BACKGROUND_CONTEXT);
+				const thinkingLevel = await runtime.lane.getThinkingLevel(BACKGROUND_CONTEXT);
+				return {
+					...model ? { model: modelIdentity(model) } : {},
+					thinkingLevel
+				};
+			},
+			async setModelSettings(settings) {
+				if (settings.model) await runtime.setModel(settings.model);
+				if (settings.thinkingLevel !== void 0) await runtime.setThinkingLevel(settings.thinkingLevel);
+			},
+			async forkSource() {
+				const metadata = runtime.session.metadata;
+				if (typeof metadata.path !== "string") throw new Error("The parent session has no persisted journal.");
+				const { leafId } = await runtime.readEntries();
+				return {
+					kind: "v4-fork",
+					sessionFile: metadata.path,
+					branch: runtime.laneName,
+					...leafId === null ? {} : { entryId: leafId }
+				};
+			},
+			entries: async (query) => await runtime.lane.findEntries({
+				...query,
+				order: query?.limit === void 0 ? "oldestFirst" : "newestFirst"
+			}, BACKGROUND_CONTEXT),
+			async appendCustomEntry(type, data) {
+				await runtime.appendCustomEntry(type, data);
+			},
+			prompt: (text, delivery) => delivery === "steer" ? runtime.steer(text) : delivery === "followUp" ? runtime.followUp(text) : runtime.prompt(text),
+			async admitPrompt(text, delivery) {
+				if (delivery === "followUp") return runtime.followUp(text);
+				(await runtime.submitPrompt(text, void 0, delivery === "steer" ? "steer" : void 0)).settled.catch((error) => client.client.notify({
+					body: error instanceof Error ? error.message : String(error),
+					level: "error"
+				}));
+			},
+			abort: () => runtime.abort(),
+			compact: (instructions) => runtime.compact(instructions),
+			async activity() {
+				const state = await runtime.readState();
+				return {
+					hasPendingMessages: Number(state.pendingMessageCount) > 0,
+					isIdle: !state.isStreaming && !state.isCompacting
+				};
+			},
+			setName: (name) => runtime.setName(name)
+		},
+		shutdown: () => stop()
+	});
+	client = createHeadlessClient({
+		appendCustomEntry: async (type, data) => {
+			await runtime.appendCustomEntry(type, data);
+		},
+		emitFrame: (frame) => emitTo(listeners, frame)
+	});
+	const unsubscribePresentation = runtime.onPresentationFrame((frame) => emitTo(listeners, frame));
+	const unsubscribeEvents = runtime.onEvent(async (event, _context) => {
+		if (event.type === "config_update" && event.property === "model") {
+			currentModel = await runtime.lane.getModel(BACKGROUND_CONTEXT);
+			if (headlessHost !== void 0 && currentModel !== void 0 && headlessHost.status.ready) await headlessHost.dispatchHook("model_select", { model: currentModel });
+		}
+		const hook = eventHook(event.type);
+		if (headlessHost !== void 0 && hook !== void 0 && headlessHost.status.ready) await headlessHost.dispatchHook(hook, event);
+	});
+	let appliedFacetTools = [];
+	let appliedSessionTools = /* @__PURE__ */ new Map();
+	let appliedSkills = /* @__PURE__ */ new Map();
+	let surfaceRevision = 0;
+	let toolSurfaceReady = false;
+	let toolReapplyQueued = false;
+	let mcpSurfaceRevision = 0;
+	let mcpSurfaceReady = false;
+	let appliedMcpTools = /* @__PURE__ */ new Map();
+	let appliedMcpSkills = /* @__PURE__ */ new Map();
+	let appliedMcpUiResources = /* @__PURE__ */ new Map();
+	let mcpRefreshQueued = false;
+	const scheduleMcpRefresh = () => {
+		if (mcpRefreshQueued || disposed || !headlessReady) return;
+		mcpRefreshQueued = true;
+		queueMicrotask(() => {
+			mcpRefreshQueued = false;
+			if (disposed || !headlessReady || !headlessHost?.status.ready) return;
+			prepareMcpSurface().catch((error) => options.onNotice?.(`MCP tool refresh failed: ${error instanceof Error ? error.message : String(error)}`));
+		});
+	};
+	const prepareMcpSurface = async () => {
+		if (!headlessHost?.status.ready) throw new Error("Headless capabilities are not installed.");
+		if (mcpServiceRoot === void 0) throw new Error("MCP session services are not installed.");
+		mcpSurfaceReady = false;
+		mcpLifecycle.abort();
+		const lifecycle = new AbortController();
+		mcpLifecycle = lifecycle;
+		const pluginContext = {
+			execution: headlessHost.context,
+			services: { get: (name) => mcpServiceRoot?.get(name) ?? piHost?.getService(name) },
+			selection: {
+				read: () => headlessHost.context.selection,
+				change: (change) => headlessHost.changeSelection(change)
+			},
+			loadContext: () => readMcpContext(lifecycle.signal),
+			signal: lifecycle.signal,
+			refresh: scheduleMcpRefresh
+		};
+		const nextTools = /* @__PURE__ */ new Map();
+		const nextSkills = /* @__PURE__ */ new Map();
+		const nextUiResources = /* @__PURE__ */ new Map();
+		for (const loaded of options.mcpPlugins ?? []) {
+			const selection = headlessHost.context.selection;
+			if (!loaded.declaration.owners.some((owner) => owner.majorMode === selection.majorMode && (owner.layer === "default" || selection.activeLayers.includes(owner.layer)))) continue;
+			const scope = typeof loaded.plugin.session === "function" ? await loaded.plugin.session(pluginContext) : loaded.plugin.session;
+			lifecycle.signal.throwIfAborted();
+			const resources = scope.uiResources ?? [];
+			for (const resource of resources) {
+				const uri = new URL(resource.uri);
+				if (uri.protocol !== "ui:" || !uri.hostname || uri.username || uri.password || uri.search || uri.hash || uri.href !== resource.uri || resource.mimeType !== "text/html;profile=mcp-app") throw new Error(`Invalid MCP UI resource '${resource.uri}'`);
+				if (nextUiResources.has(resource.uri) && nextUiResources.get(resource.uri).resource !== resource) throw new Error(`Duplicate MCP UI resource '${resource.uri}'`);
+				const descriptor = {
+					uri: resource.uri,
+					name: resource.name,
+					mimeType: resource.mimeType,
+					...resource.description === void 0 ? {} : { description: resource.description },
+					...resource._meta === void 0 ? {} : { _meta: resource._meta }
+				};
+				nextUiResources.set(resource.uri, {
+					descriptor,
+					resource
+				});
+			}
+			for (const tool of scope.tools ?? []) {
+				if (nextTools.has(tool.name)) throw new Error(`Duplicate MCP tool '${tool.name}'`);
+				const resourceUri = tool._meta?.ui?.resourceUri;
+				if (resourceUri !== void 0 && !resources.some((resource) => resource.uri === resourceUri)) throw new Error(`MCP tool '${tool.name}' references a UI resource not owned by its plugin`);
+				if (!headlessHost.allowsTool(tool.name)) continue;
+				nextTools.set(tool.name, {
+					descriptor: {
+						name: tool.name,
+						label: tool.label ?? tool.name,
+						description: tool.description,
+						parameters: tool.parameters,
+						...tool.annotations === void 0 ? {} : { annotations: tool.annotations },
+						...tool.outputSchema === void 0 ? {} : { outputSchema: tool.outputSchema },
+						...tool._meta === void 0 ? {} : { _meta: tool._meta }
+					},
+					execute: (toolCallId, parameters, signal, onUpdate, execution) => tool.execute(toolCallId, parameters, signal, onUpdate, execution ?? headlessHost.context)
+				});
+			}
+			for (const skill of scope.skills ?? []) {
+				if ([...nextSkills.values()].some((candidate) => candidate.descriptor.name === skill.name)) throw new Error(`Duplicate MCP skill '${skill.name}'`);
+				const uri = `doompi://session/${encodeURIComponent(runtime.sessionId)}/mcp/skills/${encodeURIComponent(skill.name)}`;
+				nextSkills.set(uri, {
+					descriptor: {
+						name: skill.name,
+						description: skill.description,
+						uri
+					},
+					skill
+				});
+			}
+		}
+		appliedMcpTools = nextTools;
+		appliedMcpSkills = nextSkills;
+		appliedMcpUiResources = nextUiResources;
+		mcpSurfaceRevision += 1;
+		mcpSurfaceReady = true;
+	};
+	const applyToolSurface = async (tools) => {
+		toolSurfaceReady = false;
+		const facetTools = tools.map((tool) => toolAdapter(tool.name === "load_skill" ? {
+			...tool,
+			description: describeLoadSkillTool(tool.description, headlessHost?.appliedResources ?? [])
+		} : tool, () => headlessHost.context, reportedToolErrors));
+		const facetNames = headlessHost?.declaredToolNames ?? new Set(facetTools.map((tool) => tool.name));
+		const piTools = (piHost?.tools ?? []).filter((tool) => !facetNames.has(tool.name) && headlessHost?.allowsTool(tool.name) !== false).map((tool) => ({
+			...tool,
+			async execute(...args) {
+				headlessHost.assertActive();
+				if (!toolSurfaceReady || !headlessHost.allowsTool(tool.name)) throw new Error(`Tool '${tool.name}' is no longer active`);
+				return tool.execute(...args);
+			}
+		}));
+		const piNames = new Set(piTools.map((tool) => tool.name));
+		const nextToolGuidance = [...(piHost?.toolGuidance ?? []).filter((entry) => piNames.has(entry.name)), ...tools.map((tool) => ({
+			name: tool.name,
+			...tool.promptSnippet === void 0 ? {} : { promptSnippet: tool.promptSnippet },
+			...tool.promptGuidelines === void 0 ? {} : { promptGuidelines: tool.promptGuidelines }
+		}))];
+		await runtime.replaceTools([...piTools, ...facetTools]);
+		const next = /* @__PURE__ */ new Map();
+		for (const tool of piTools) next.set(tool.name, {
+			descriptor: {
+				name: tool.name,
+				label: tool.label ?? tool.name,
+				description: tool.description,
+				parameters: tool.parameters
+			},
+			execute: (toolCallId, parameters, signal, onUpdate) => piHost.executeTool(tool.name, toolCallId, parameters, signal, onUpdate)
+		});
+		for (const tool of tools) next.set(tool.name, {
+			descriptor: {
+				name: tool.name,
+				label: tool.label ?? tool.name,
+				description: tool.description,
+				parameters: tool.parameters
+			},
+			execute: (toolCallId, parameters, signal, onUpdate) => tool.execute(toolCallId, parameters, signal, onUpdate, headlessHost.context)
+		});
+		toolGuidance = nextToolGuidance;
+		appliedSessionTools = next;
+		surfaceRevision += 1;
+		toolSurfaceReady = true;
+	};
+	/**
+	* Rebuilds the merged tool surface after a Pi extension narrowed its own tools.
+	*
+	* Deferred because the tool surface arbiter calls `setActiveTools` synchronously from inside
+	* `register`, and coalesced because several extensions register their restrictions in the same
+	* tick. The facet set is unchanged, so this never re-enters the kernel.
+	*/
+	let toolLine = Promise.resolve();
+	const applyLatestTools = () => {
+		toolLine = toolLine.catch(() => void 0).then(() => applyToolSurface(appliedFacetTools));
+		return toolLine;
+	};
+	const scheduleToolReapply = () => {
+		if (toolReapplyQueued) return;
+		toolReapplyQueued = true;
+		queueMicrotask(() => {
+			toolReapplyQueued = false;
+			if (disposed) return;
+			applyLatestTools().catch((error) => options.onNotice?.(`Pi extension tool refresh failed: ${error instanceof Error ? error.message : String(error)}`));
+		});
+	};
+	const prepareFacets = (root) => {
+		mcpServiceRoot = root;
+		root.plugin((context) => {
+			context.provide(DOOM_CHILD_SESSION_SERVICE, childSessionProvider.get());
+			context.effect(() => () => childSessionProvider.close(), "headless child session service lifetime");
+		});
+		if (headlessHost !== void 0) throw new Error("Direct headless facets were prepared more than once.");
+		if (piPreload !== void 0) piHost = createPiExtensionHost({
+			cwd: options.cwd,
+			agentDir,
+			models: modelRuntime,
+			settings,
+			runtime,
+			preload: piPreload,
+			getModel: () => currentModel,
+			getThinkingLevel: () => resolved.thinkingLevel ?? "off",
+			client: () => client?.client,
+			onActiveToolsChanged: scheduleToolReapply,
+			serverServices: {
+				sessionId: options.sessionId,
+				get: (name) => root.get(name)
+			},
+			...options.onNotice === void 0 ? {} : { onNotice: options.onNotice }
+		});
+		headlessHost = new HeadlessHost(root, {
+			candidates: options.candidates,
+			selection: initialSelection,
+			selectionOverrides: [.../* @__PURE__ */ new Set([...options.selectionOverrides ?? [], ...[
+				"majorMode",
+				"domains",
+				"profile"
+			].filter((axis) => JSON.stringify(initialSelection[axis]) !== JSON.stringify(options.selection[axis]))])],
+			context: executionContext,
+			resolveSelection: options.resolveSelection,
+			...options.allowedTools === void 0 ? {} : { allowedTools: () => options.allowedTools },
+			applyTools: async (tools) => {
+				appliedFacetTools = tools;
+				await applyLatestTools();
+			},
+			applyResources: async (next) => {
+				const mapped = mapResources(next);
+				const facetNames = new Set((mapped.harness.skills ?? []).map((skill) => skill.name));
+				const piSkills = (piHost?.skills ?? []).filter((skill) => !facetNames.has(skill.name));
+				const mergedSkills = [...piSkills, ...mapped.harness.skills ?? []];
+				await runtime.replaceResources(piSkills.length === 0 ? mapped.harness : {
+					...mapped.harness,
+					skills: mergedSkills
+				});
+				appliedSkills = new Map(mergedSkills.map((skill) => {
+					const uri = `doompi://session/${encodeURIComponent(runtime.sessionId)}/skills/${encodeURIComponent(skill.name)}`;
+					return [uri, {
+						descriptor: {
+							name: skill.name,
+							description: skill.description,
+							uri
+						},
+						content: skill.content
+					}];
+				}));
+				surfaceRevision += 1;
+				if (appliedFacetTools.some((tool) => tool.name === "load_skill")) await applyLatestTools();
+			},
+			onApplied: async (selection) => {
+				options.publishSelectionStatus?.((source, text) => client.client.setStatus(source, text), selection);
+				latestSelection = selection;
+				for (const listener of selectionListeners) listener(selection);
+			},
+			onError: (error) => options.onNotice?.(`Headless selection failed: ${harnessErrorMessage(error)}`)
+		});
+		publishComposition = createHeadlessCompositionPublisher(runtime, headlessHost, options.environment, (selection) => options.contextGroups?.(root, selection) ?? [], readSystemPrompt);
+		headlessHost.subscribeSelection(async (selection) => {
+			if (!headlessReady || !headlessHost?.status.ready) return;
+			try {
+				await prepareMcpSurface();
+			} catch (error) {
+				if (!(error instanceof Error && error.name === "AbortError")) options.onNotice?.(`MCP tool refresh failed: ${error instanceof Error ? error.message : String(error)}`);
+			}
+			await publishComposition(selection);
+		});
+	};
+	const activateFacets = async (installed) => {
+		if (headlessHost === void 0) throw new Error("Direct headless host was not prepared.");
+		const host = headlessHost;
+		const assertLive = () => {
+			if (disposed) throw new Error("The session was closed while it was starting.");
+		};
+		host.setAvailableSources(installed.installedPackages);
+		if (piHost !== void 0) try {
+			await piHost.load();
+		} catch (error) {
+			options.onNotice?.(`Pi extensions failed to load: ${error instanceof Error ? error.message : String(error)}`);
+		}
+		assertLive();
+		await host.select(initialSelection);
+		assertLive();
+		if (!host.status.ready) throw new Error(`Session capabilities failed to start: ${host.status.error ?? "selection is not ready"}`);
+		headlessReady = true;
+		await prepareMcpSurface();
+		assertLive();
+		await runtime.recover();
+		assertLive();
+		await host.dispatchHook("session_start", {});
+		await publishComposition();
+		runtime.resume().catch((error) => options.onNotice?.(`Session resume failed: ${harnessErrorMessage(error)}`));
+	};
+	const dispose = () => {
+		disposePromise ??= (async () => {
+			if (disposed) return;
+			const wasReady = headlessReady;
+			disposed = true;
+			headlessReady = false;
+			mcpSurfaceReady = false;
+			mcpLifecycle.abort();
+			const failures = [];
+			try {
+				await runtime.interrupt();
+			} catch (error) {
+				failures.push(error);
+			}
+			try {
+				if (wasReady && headlessHost?.status.ready) await headlessHost.dispatchHook("session_shutdown", {});
+			} catch (error) {
+				failures.push(error);
+			}
+			try {
+				await runtime.dispose();
+			} catch (error) {
+				failures.push(error);
+			}
+			try {
+				await piHost?.shutdown();
+			} catch (error) {
+				failures.push(error);
+			}
+			try {
+				await headlessHost?.close();
+			} catch (error) {
+				failures.push(error);
+			}
+			client?.dispose();
+			unsubscribePresentation();
+			unsubscribeEvents();
+			try {
+				await childSessionProvider.close();
+			} catch (error) {
+				failures.push(error);
+			}
+			if (failures.length) throw new AggregateError(failures, "Headless session shutdown failed");
+		})();
+		return disposePromise;
+	};
+	const stop = () => {
+		dispose().catch((error) => options.onNotice?.(harnessErrorMessage(error)));
+	};
+	const invokeSurfaceTool = async (invocation, readRevision, readTools, ready, lifecycleSignal) => {
+		if (disposed || !headlessReady || !ready() || !headlessHost?.status.ready) throw new Error("Headless capability preparation is not ready.");
+		if (invocation.revision !== readRevision()) throw new Error("The session tool surface has changed");
+		if (!isJsonObject(invocation.arguments)) throw new Error("Tool arguments must be a JSON object");
+		const applied = readTools().get(invocation.name);
+		if (applied === void 0) throw new Error(`Tool '${invocation.name}' is not active`);
+		if (!Value.Check(applied.descriptor.parameters, invocation.arguments)) throw new Error(`Invalid arguments for tool '${invocation.name}'`);
+		const signals = [invocation.signal, lifecycleSignal].filter((signal) => signal !== void 0);
+		const signal = signals.length === 0 ? void 0 : AbortSignal.any(signals);
+		signal?.throwIfAborted();
+		return runtime.runExternalOperation(async () => {
+			const toolCallId = `external-${randomUUID()}`;
+			const before = await beforeTool({
+				toolCallId,
+				toolName: invocation.name,
+				args: invocation.arguments
+			}, BACKGROUND_CONTEXT);
+			if (before?.block !== void 0) return {
+				content: [{
+					type: "text",
+					text: before.block.reason
+				}],
+				isError: true
+			};
+			const args = before?.args ?? invocation.arguments;
+			if (!Value.Check(applied.descriptor.parameters, args)) throw new Error(`A tool hook produced invalid arguments for '${invocation.name}'`);
+			await invocation.authorize?.();
+			signal?.throwIfAborted();
+			if (disposed || !headlessReady || !ready() || !headlessHost?.status.ready) throw new Error("Headless capability preparation is not ready.");
+			if (invocation.revision !== readRevision() || readTools().get(invocation.name) !== applied) throw new Error(`Tool '${invocation.name}' is no longer active`);
+			const startEvent = {
+				type: "tool_execution_start",
+				runId: EXTERNAL_OPERATION,
+				turnId: EXTERNAL_OPERATION,
+				toolCallId,
+				toolName: invocation.name,
+				args
+			};
+			emitTo(listeners, startEvent);
+			await headlessHost.dispatchHook("tool_execution_start", startEvent);
+			let result;
+			try {
+				result = await applied.execute(toolCallId, args, signal, (partial) => {
+					emitTo(listeners, {
+						type: "tool_execution_update",
+						runId: EXTERNAL_OPERATION,
+						turnId: EXTERNAL_OPERATION,
+						toolCallId,
+						toolName: invocation.name,
+						partialResult: partial
+					});
+					invocation.onUpdate?.(partial);
+				}, invocation.mcpSkills === void 0 ? void 0 : {
+					...headlessHost.context,
+					mcpSkills: invocation.mcpSkills
+				});
+			} catch (error) {
+				result = {
+					content: [{
+						type: "text",
+						text: error instanceof Error ? error.message : String(error)
+					}],
+					isError: true
+				};
+			}
+			const patch = await afterTool({
+				toolCallId,
+				toolName: invocation.name,
+				args,
+				content: result.content,
+				...isJsonValue(result.details) ? { details: result.details } : {},
+				isError: result.isError === true
+			}, BACKGROUND_CONTEXT);
+			const patched = {
+				content: patch?.content ?? result.content,
+				...patch?.content !== void 0 || patch?.isError !== void 0 || result.structuredContent === void 0 ? {} : { structuredContent: result.structuredContent },
+				...patch?.content !== void 0 || patch?.isError !== void 0 || patch?.details !== void 0 || result._meta === void 0 ? {} : { _meta: result._meta },
+				...patch?.details !== void 0 ? { details: patch.details } : result.details === void 0 ? {} : { details: result.details },
+				isError: patch?.isError ?? result.isError ?? false
+			};
+			const endEvent = {
+				type: "tool_execution_end",
+				runId: EXTERNAL_OPERATION,
+				turnId: EXTERNAL_OPERATION,
+				toolCallId,
+				toolName: invocation.name,
+				result: patched,
+				isError: patched.isError,
+				terminate: patch?.terminate ?? false
+			};
+			emitTo(listeners, endEvent);
+			await headlessHost.dispatchHook("tool_execution_end", endEvent);
+			return patched;
+		});
+	};
+	const toolSurface = {
+		readSurface() {
+			if (disposed || !headlessReady || !toolSurfaceReady || !headlessHost?.status.ready) throw new Error("Headless capability preparation is not ready.");
+			return {
+				revision: surfaceRevision,
+				tools: [...appliedSessionTools.values()].map((tool) => tool.descriptor),
+				skills: [...appliedSkills.values()].map((skill) => skill.descriptor)
+			};
+		},
+		invokeTool: (invocation) => invokeSurfaceTool(invocation, () => surfaceRevision, () => appliedSessionTools, () => toolSurfaceReady),
+		readSkill(revision, uri) {
+			if (disposed || !headlessReady || !toolSurfaceReady || !headlessHost?.status.ready) throw new Error("Headless capability preparation is not ready.");
+			if (revision !== surfaceRevision) throw new Error("The session skill surface has changed");
+			const skill = appliedSkills.get(uri);
+			if (skill === void 0) throw new Error("The session skill is not active");
+			return skill.content;
+		}
+	};
+	const mcpSurface = {
+		readSurface() {
+			if (disposed || !headlessReady || !mcpSurfaceReady || !headlessHost?.status.ready) throw new Error("MCP capability preparation is not ready.");
+			return {
+				revision: mcpSurfaceRevision,
+				tools: [...appliedMcpTools.values()].map((tool) => tool.descriptor),
+				skills: [...appliedMcpSkills.values()].map((skill) => skill.descriptor),
+				uiResources: [...appliedMcpUiResources.values()].map((resource) => resource.descriptor)
+			};
+		},
+		invokeTool: (invocation) => invokeSurfaceTool(invocation, () => mcpSurfaceRevision, () => appliedMcpTools, () => mcpSurfaceReady, mcpLifecycle.signal),
+		async readUiResource(revision, uri) {
+			if (disposed || !headlessReady || !mcpSurfaceReady || !headlessHost?.status.ready) throw new Error("MCP capability preparation is not ready.");
+			if (revision !== mcpSurfaceRevision) throw new Error("The session MCP surface has changed");
+			const resource = appliedMcpUiResources.get(uri)?.resource;
+			if (resource === void 0) throw new Error("The session MCP UI resource is not active");
+			const text = await resource.read();
+			if (disposed || !headlessReady || !mcpSurfaceReady || !headlessHost?.status.ready) throw new Error("MCP capability preparation is not ready.");
+			if (revision !== mcpSurfaceRevision || appliedMcpUiResources.get(uri)?.resource !== resource) throw new Error("The session MCP surface has changed");
+			return text;
+		},
+		async readSkill(revision, uri) {
+			if (disposed || !headlessReady || !mcpSurfaceReady || !headlessHost?.status.ready) throw new Error("MCP capability preparation is not ready.");
+			if (revision !== mcpSurfaceRevision) throw new Error("The session MCP surface has changed");
+			const skill = appliedMcpSkills.get(uri)?.skill;
+			if (skill === void 0) throw new Error("The session MCP skill is not active");
+			const text = await skill.read(headlessHost.context);
+			if (disposed || !headlessReady || !mcpSurfaceReady || !headlessHost?.status.ready) throw new Error("MCP capability preparation is not ready.");
+			if (revision !== mcpSurfaceRevision || appliedMcpSkills.get(uri)?.skill !== skill) throw new Error("The session MCP surface has changed");
+			return text;
+		}
+	};
+	return {
+		runtime,
+		...sessionContext === void 0 ? {} : { sessionContext },
+		get host() {
+			return headlessHost;
+		},
+		toolSurface,
+		mcpSurface,
+		prepareFacets,
+		activateFacets,
+		canDispatch: () => !disposed && headlessReady && !promptPreparationFailed && headlessHost?.status.ready === true,
+		onPresentationFrame(listener) {
+			listeners.add(listener);
+			return () => listeners.delete(listener);
+		},
+		onSelection(listener) {
+			selectionListeners.add(listener);
+			listener(latestSelection);
+			return () => {
+				selectionListeners.delete(listener);
+			};
+		},
+		respondToExtensionUi(frame) {
+			return client?.receive(frame) ?? false;
+		},
+		dispose
+	};
+}
+//#endregion
+export { createHeadlessSessionHost, restoreHeadlessSelection, validateDirectHeadlessArgs };
+
+//# sourceMappingURL=headlessSessionHost.mjs.map