acrylblends 1.0.4 → 1.0.6

package/lib/cordis/door.js

@@ -1,13 +1,280 @@
-import { t as Acryl } from "../app-BM0rTCp7.js";
-import { n as clientModules } from "../client-modules-CLvWOjbd.js";
-import { MAX_SNAPSHOT_NODES, MAX_WAIT_MS, UiControlError, parseUiRequest } from "../door/protocol.js";
-import { a as INVALID_JSON, c as operatorOnly, d as AuditLog, f as auditPath, i as DOOR_PREFIX, l as privateApi, o as error, p as UiChannel, r as pageChannelRoutes, s as jsonBody, t as renderSnapshot, u as readJson } from "../snapshot-text-BLz8nlSc.js";
-import "../src-dy3Fk9tA.js";
+import { t as Acryl } from "../app-CQcGWjrk.js";
+import { r as streamSSE } from "../streaming-BlDaph8U.js";
+import "../helpers-BEjcdbgw.js";
+import { n as clientModules } from "../client-modules-drj4mjhj.js";
+import { a as MAX_WAIT_MS, l as UiControlError, p as parseUiRequest, r as MAX_SNAPSHOT_NODES } from "../protocol-Dt0AZBOz.js";
+import { a as INVALID_JSON, c as operatorOnly, d as AuditLog, f as auditPath, i as DOOR_PREFIX, l as privateApi, o as error, p as UiChannel, r as pageChannelRoutes, s as jsonBody, t as renderSnapshot, u as readJson } from "../snapshot-text-CtQm3n8n.js";
+import "../src-BTBm4OPD.js";
 import { isAbsolute, join, relative, resolve } from "node:path";
 import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import z from "@deepseek-ai/schemastery";
 import { randomBytes } from "node:crypto";
 import { spawnSync } from "node:child_process";
+//#region ../../plugins/acryl-door/src/shell/protocol.ts
+var ShellError = class extends Error {
+	code;
+	constructor(code, message) {
+		super(message);
+		this.code = code;
+		this.name = "ShellError";
+	}
+};
+/** A path of the app, as `act navigate` takes one: one leading `/`, and no other site. */
+const APP_PATH = /^\/(?![/\\])[^\s\\]*$/u;
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function only(value, allowed) {
+	const extra = Object.keys(value).filter((key) => key !== "op" && !allowed.includes(key));
+	if (extra.length > 0) throw new ShellError("invalid", `unknown field ${extra.join(", ")}`);
+}
+function windowId(value) {
+	if (typeof value.id !== "number" || !Number.isSafeInteger(value.id) || value.id < 1) throw new ShellError("invalid", "id must be the number `window list` prints for the window");
+	return value.id;
+}
+function size(value, key) {
+	const number = value[key];
+	if (typeof number !== "number" || !Number.isInteger(number) || number < 200 || number > 1e4) throw new ShellError("invalid", `${key} must be a whole number of pixels from 200 to 10000`);
+	return number;
+}
+/** @throws ShellError `invalid`. */
+function parseShellRequest(op, input) {
+	const value = isRecord(input) ? input : {};
+	switch (op) {
+		case "window-list":
+			only(value, []);
+			return { op };
+		case "window-open":
+			only(value, ["path"]);
+			if (value.path === void 0) return { op };
+			if (typeof value.path !== "string" || !APP_PATH.test(value.path)) throw new ShellError("invalid", "path must be a path of this app, such as /settings (it starts with one /, and names no other site)");
+			return {
+				op,
+				path: value.path
+			};
+		case "window-focus":
+			only(value, ["id"]);
+			return {
+				op,
+				id: windowId(value)
+			};
+		case "window-close":
+			only(value, ["id", "force"]);
+			if (value.force !== void 0 && typeof value.force !== "boolean") throw new ShellError("invalid", "force must be true or false");
+			return {
+				op,
+				id: windowId(value),
+				...value.force === true ? { force: true } : {}
+			};
+		case "window-resize":
+			only(value, [
+				"id",
+				"width",
+				"height"
+			]);
+			return {
+				op,
+				id: windowId(value),
+				width: size(value, "width"),
+				height: size(value, "height")
+			};
+		case "menu-list":
+			only(value, []);
+			return { op };
+		case "menu-click":
+			only(value, ["path", "force"]);
+			if (typeof value.path !== "string" || value.path.trim() === "" || value.path.length > 300) throw new ShellError("invalid", "path is the labels from the top of the menu joined with >, e.g. \"File>New Note\" (`menu list` prints them)");
+			if (value.force !== void 0 && typeof value.force !== "boolean") throw new ShellError("invalid", "force must be true or false");
+			return {
+				op,
+				path: value.path,
+				...value.force === true ? { force: true } : {}
+			};
+	}
+}
+/** @param value - one parsed POST body from the shell; null when it is not a well-formed answer. */
+function parseShellAnswer(value) {
+	if (!isRecord(value) || typeof value.id !== "number" || !Number.isSafeInteger(value.id)) return null;
+	if (value.t === "result" && isRecord(value.value)) return {
+		t: "result",
+		id: value.id,
+		value: value.value
+	};
+	if (value.t === "error" && typeof value.code === "string" && typeof value.message === "string") return {
+		t: "error",
+		id: value.id,
+		code: value.code.slice(0, 40),
+		message: value.message.slice(0, 500)
+	};
+	return null;
+}
+/** Whatever code the shell used, as one the door knows (an unknown code is `failed`). */
+function shellErrorCode(code) {
+	return [
+		"invalid",
+		"no-such-window",
+		"last-window",
+		"no-such-menu-item",
+		"disabled",
+		"quits-app"
+	].find((known) => known === code) ?? "failed";
+}
+//#endregion
+//#region ../../plugins/acryl-door/src/host/shell.ts
+/**
+* The desktop shell's channel: the Electron main process of `npm run desktop`, which reaches the door as a page does (an event stream down, a POST up) and answers calls about
+* the app's windows and menu. One shell at a time: a new one replaces the old (the dev server restarted and the shell came back). It needs this run's secret, so no page can open it.
+*/
+const CALL_TIMEOUT_MS = 1e4;
+/** What a verb says when no desktop shell is attached: one line a model can act on. */
+const NO_DESKTOP = "no desktop window is attached; run npm run desktop";
+var ShellChannel = class {
+	current;
+	pending = /* @__PURE__ */ new Map();
+	nextId = 1;
+	closed = false;
+	attachWaiters = /* @__PURE__ */ new Set();
+	get connected() {
+		return this.current !== void 0;
+	}
+	/** @returns the function to call when this stream ends. */
+	attach(stream) {
+		const previous = this.current;
+		const connection = { stream };
+		this.current = connection;
+		if (previous !== void 0) {
+			this.failAll(new ShellError("disconnected", "the desktop shell reconnected before it answered"));
+			previous.stream.close();
+		}
+		for (const waiter of [...this.attachWaiters]) waiter();
+		return () => {
+			if (this.current !== connection) return;
+			this.current = void 0;
+			this.failAll(new ShellError("disconnected", "the desktop shell went away before it answered"));
+		};
+	}
+	/** A promise for the shell connecting (it reconnects after the dev server restarted). */
+	waitForShell(timeoutMs) {
+		if (this.current !== void 0) return Promise.resolve(true);
+		return new Promise((resolve) => {
+			const done = (value) => {
+				clearTimeout(timer);
+				this.attachWaiters.delete(waiter);
+				resolve(value);
+			};
+			const waiter = () => {
+				done(true);
+			};
+			const timer = setTimeout(() => {
+				done(false);
+			}, timeoutMs);
+			this.attachWaiters.add(waiter);
+		});
+	}
+	receive(body) {
+		const answer = parseShellAnswer(body);
+		if (answer === null) return;
+		if (answer.t === "result") this.settle(answer.id, answer.value);
+		else this.settle(answer.id, void 0, new ShellError(shellErrorCode(answer.code), answer.message));
+	}
+	/** @throws ShellError `no-desktop` when no shell is attached, else what the shell refused with. */
+	call(request, options = {}) {
+		if (this.closed) return Promise.reject(new ShellError("unloaded", "the door was unloaded"));
+		const target = this.current;
+		if (target === void 0) return Promise.reject(new ShellError("no-desktop", NO_DESKTOP));
+		const signal = options.signal;
+		if (signal?.aborted === true) return Promise.reject(new ShellError("aborted", "the call was cancelled"));
+		const id = this.nextId;
+		this.nextId += 1;
+		return new Promise((resolve, reject) => {
+			const timer = setTimeout(() => {
+				this.settle(id, void 0, new ShellError("timeout", "the desktop shell did not answer in time"));
+			}, options.timeoutMs ?? CALL_TIMEOUT_MS);
+			const onAbort = () => {
+				this.settle(id, void 0, new ShellError("aborted", "the call was cancelled"));
+			};
+			signal?.addEventListener("abort", onAbort, { once: true });
+			this.pending.set(id, {
+				resolve,
+				reject,
+				timer,
+				cleanup: () => {
+					signal?.removeEventListener("abort", onAbort);
+				}
+			});
+			try {
+				target.stream.send(JSON.stringify({
+					t: "call",
+					id,
+					request
+				}));
+			} catch {
+				this.settle(id, void 0, new ShellError("disconnected", "the desktop shell could not be reached"));
+			}
+		});
+	}
+	close() {
+		this.closed = true;
+		this.failAll(new ShellError("unloaded", "the door was unloaded"));
+		this.current?.stream.close();
+		this.current = void 0;
+	}
+	failAll(failure) {
+		for (const id of [...this.pending.keys()]) this.settle(id, void 0, failure);
+	}
+	settle(id, value, failure) {
+		const entry = this.pending.get(id);
+		if (entry === void 0) return;
+		this.pending.delete(id);
+		clearTimeout(entry.timer);
+		entry.cleanup();
+		if (failure !== void 0) entry.reject(failure);
+		else entry.resolve(value);
+	}
+};
+/** How often a `ping` is written, so the shell knows a silent stream died and reconnects. */
+const SHELL_HEARTBEAT_MS = 15e3;
+/** `GET <prefix>/shell/events` is the shell's stream and `POST <prefix>/shell/answer` carries its answers: both need this run's secret. */
+function shellRoutes(prefix, secret, channel, heartbeatMs = SHELL_HEARTBEAT_MS) {
+	return new Acryl().get(`${prefix}/shell/events`, operatorOnly(secret), (c) => {
+		const signal = c.req.raw.signal;
+		return streamSSE(c, async (stream) => {
+			let end = () => {};
+			const ended = new Promise((resolve) => {
+				end = resolve;
+			});
+			stream.onAbort(end);
+			signal.addEventListener("abort", end, { once: true });
+			const write = (event, data) => {
+				stream.writeSSE({
+					event,
+					data
+				}).catch(end);
+			};
+			const detach = channel.attach({
+				send: (data) => {
+					write("call", data);
+				},
+				close: end
+			});
+			const beat = setInterval(() => {
+				write("ping", "");
+			}, heartbeatMs);
+			try {
+				write("ready", "");
+				await ended;
+			} finally {
+				clearInterval(beat);
+				signal.removeEventListener("abort", end);
+				detach();
+			}
+		});
+	}).post(`${prefix}/shell/answer`, operatorOnly(secret), jsonBody, async (c) => {
+		const body = await readJson(c);
+		if (body === INVALID_JSON || typeof body !== "object" || body === null) return c.json(error("invalid request body"), 400);
+		channel.receive(body);
+		return c.json({ ok: true });
+	});
+}
+//#endregion
 //#region ../../plugins/acryl-door/src/host/verbs.ts
 /**
 * The one verb list (spec 049 slice 13). Every face of the door reads it: the operator client (`acryl <verb>`, its `verbs` and `brief`),
@@ -23,7 +290,14 @@ const VERBS = [
 	"plugin-remove",
 	"plugin-reload",
 	"tool-list",
-	"tool-call"
+	"tool-call",
+	"window-list",
+	"window-open",
+	"window-focus",
+	"window-close",
+	"window-resize",
+	"menu-list",
+	"menu-click"
 ];
 const none = {
 	type: "object",
@@ -37,7 +311,7 @@ const VERB_SPECS = {
 		arguments: none
 	},
 	"look": {
-		usage: "look [--cursor <n>] [--max-nodes <n>]: the page as text, with refs",
+		usage: "look [--window <n>] [--cursor <n>] [--max-nodes <n>]: the page as text, with refs",
 		description: "The open page as text: its roles, names, values and visible text, each with a ref to act on. A long page comes in parts (cursor).",
 		arguments: {
 			type: "object",
@@ -51,6 +325,11 @@ const VERB_SPECS = {
 					type: "integer",
 					minimum: 1,
 					maximum: MAX_SNAPSHOT_NODES
+				},
+				window: {
+					type: "integer",
+					minimum: 1,
+					description: "a desktop window (the id window-list prints); default: the page used last"
 				}
 			},
 			additionalProperties: false
@@ -134,6 +413,11 @@ const VERB_SPECS = {
 					type: "integer",
 					minimum: 0,
 					maximum: MAX_WAIT_MS
+				},
+				window: {
+					type: "integer",
+					minimum: 1,
+					description: "a desktop window (the id window-list prints); default: the page used last"
 				}
 			},
 			required: ["op"],
@@ -190,6 +474,109 @@ const VERB_SPECS = {
 			required: ["tool"],
 			additionalProperties: false
 		}
+	},
+	"window-list": {
+		usage: "window list: the windows of the desktop app",
+		description: "The windows of the desktop app: id, title, path, size, and which one is focused. Needs the desktop app (npm run desktop).",
+		arguments: none
+	},
+	"window-open": {
+		usage: "window open [--path <path of the app>]: open a new window",
+		description: "Open a new window of the desktop app on a path of the app (default: its start page). Answers with the new window's id; look and act take it as window.",
+		arguments: {
+			type: "object",
+			properties: { path: {
+				type: "string",
+				description: "a path of this app, e.g. /settings"
+			} },
+			additionalProperties: false
+		}
+	},
+	"window-focus": {
+		usage: "window focus --id <n>: bring a window to the front",
+		description: "Bring a window of the desktop app to the front. Look and act without a window then drive it.",
+		arguments: {
+			type: "object",
+			properties: { id: {
+				type: "integer",
+				minimum: 1,
+				description: "the id window-list prints"
+			} },
+			required: ["id"],
+			additionalProperties: false
+		}
+	},
+	"window-close": {
+		usage: "window close --id <n> [--force]: close a window",
+		description: "Close a window of the desktop app. The last window cannot be closed without force, because that ends the desktop app.",
+		arguments: {
+			type: "object",
+			properties: {
+				id: {
+					type: "integer",
+					minimum: 1
+				},
+				force: {
+					type: "boolean",
+					description: "allow closing the last window, which ends the desktop app"
+				}
+			},
+			required: ["id"],
+			additionalProperties: false
+		}
+	},
+	"window-resize": {
+		usage: "window resize --id <n> --width <px> --height <px>",
+		description: "Resize a window of the desktop app.",
+		arguments: {
+			type: "object",
+			properties: {
+				id: {
+					type: "integer",
+					minimum: 1
+				},
+				width: {
+					type: "integer",
+					minimum: 200,
+					maximum: 1e4
+				},
+				height: {
+					type: "integer",
+					minimum: 200,
+					maximum: 1e4
+				}
+			},
+			required: [
+				"id",
+				"width",
+				"height"
+			],
+			additionalProperties: false
+		}
+	},
+	"menu-list": {
+		usage: "menu list: the application menu",
+		description: "The desktop app's application menu as paths such as File>New Note, with the disabled items marked.",
+		arguments: none
+	},
+	"menu-click": {
+		usage: "menu click --path \"File>New Note\" [--force]: press a menu item",
+		description: "Press an item of the desktop app's application menu by its path (labels joined with >, as menu-list prints them). A disabled item is refused, and so is one that ends the app (Quit, Close Window on the last window) unless force is set.",
+		arguments: {
+			type: "object",
+			properties: {
+				path: {
+					type: "string",
+					description: "e.g. File>New Note"
+				},
+				force: {
+					type: "boolean",
+					description: "allow an item that ends the desktop app"
+				}
+			},
+			required: ["path"],
+			additionalProperties: false
+		}
 	}
 };
 /** A verb's name in the `tools` registry the built-in chat reads: prefixed, so it never meets an app tool's name. */
@@ -209,6 +596,12 @@ var DoorError = class extends Error {
 		this.name = "DoorError";
 	}
 };
+/** A shell answer as text an agent reads: windows and menu items one to a line. */
+function renderShell(result) {
+	if ("windows" in result) return result.windows.length === 0 ? "no windows are open" : result.windows.map((window) => `${String(window.id)}  ${JSON.stringify(window.title)}  ${window.path}  ${String(window.width)}x${String(window.height)}${window.focused ? "  focused" : ""}`).join("\n");
+	if ("items" in result) return result.items.length === 0 ? "the app has no menu" : result.items.map((item) => `${item.path}${item.enabled ? "" : "  (disabled)"}${item.ends === true ? "  (ends the app; needs force)" : ""}`).join("\n");
+	return result.detail;
+}
 /** The files an agent should read first, when the app has them. */
 const SELF_KNOWLEDGE = [
 	"AGENTS.md",
@@ -260,6 +653,13 @@ var Door = class {
 				};
 			}
 			case "tool-call": return this.callTool(input);
+			case "window-list":
+			case "window-open":
+			case "window-focus":
+			case "window-close":
+			case "window-resize":
+			case "menu-list":
+			case "menu-click": return this.desktop(verb, input, signal);
 			default: throw new DoorError("unknown-verb", `unknown verb ${JSON.stringify(verb)}; the verbs are ${VERBS.join(", ")}`);
 		}
 	}
@@ -289,20 +689,22 @@ var Door = class {
 		};
 	}
 	look(input, signal) {
+		const { window, rest } = this.windowOf(input);
 		const request = this.parse({
-			...input,
+			...rest,
 			op: "snapshot"
 		});
-		return this.callPage("look", request, signal);
+		return this.callPage("look", request, signal, window);
 	}
 	async act(input, signal) {
 		if (input.op === "snapshot") throw new DoorError("invalid", "use look to see the page");
-		const request = this.parse(input);
-		if (request.op !== "reload" && request.op !== "navigate") return await this.callPage(`act ${String(input.op)}`, request, signal);
+		const { window, rest } = this.windowOf(input);
+		const request = this.parse(rest);
+		if (request.op !== "reload" && request.op !== "navigate") return await this.callPage(`act ${String(input.op)}`, request, signal, window);
 		const back = this.deps.channel.expectAttach(this.deps.pageBackMs ?? PAGE_BACK_MS);
 		let answer;
 		try {
-			answer = await this.callPage(`act ${request.op}`, request, signal);
+			answer = await this.callPage(`act ${request.op}`, request, signal, window);
 		} catch (cause) {
 			if (!(cause instanceof UiControlError && cause.code === "disconnected")) throw cause;
 			answer = {
@@ -311,9 +713,95 @@ var Door = class {
 			};
 		}
 		if (!await back) throw new UiControlError("timeout", request.op === "reload" ? "the page did not come back after the reload" : `the page did not come back after going to ${request.path}: is there a page at that path, and does it load the door's script?`);
+		const landed = request.op === "navigate" ? await this.statusAt(request.path) : void 0;
 		return {
 			...answer,
-			detail: `${answer.detail ?? "done"}; the page is back: look again`
+			detail: `${answer.detail ?? "done"}${landed === void 0 ? "" : `; ${landed}`}; the page is back: look again`
+		};
+	}
+	/**
+	* What the app answers at a path the page was sent to, so an agent that mistyped one is told ("404 at /nope") and not left to find out from a page it did not expect.
+	* A second GET of the same path (a page is read-only); nothing when the app has no address or does not answer in time.
+	*/
+	async statusAt(path) {
+		const base = this.deps.app.url;
+		if (base === void 0) return void 0;
+		try {
+			const response = await fetch(new URL(path, base), {
+				headers: { accept: "text/html" },
+				signal: AbortSignal.timeout(3e3)
+			});
+			await response.body?.cancel();
+			return response.ok ? `${response.status} at ${path}` : `${response.status} at ${path}: the app serves no page there, look at what is shown and navigate to a path it does`;
+		} catch {
+			return;
+		}
+	}
+	/**
+	* The windows and the menu of the desktop app, through the shell. Every call is audited with the window it was about; a call with no shell attached answers one line that says what to run;
+	* closing the last window is refused unless the call says `force` (it ends the desktop app, and the session an agent works in with it).
+	*/
+	async desktop(verb, input, signal) {
+		const shell = this.deps.shell;
+		let request;
+		try {
+			request = parseShellRequest(verb, input);
+		} catch (cause) {
+			throw new DoorError("invalid", cause instanceof Error ? cause.message : "invalid request");
+		}
+		const windowId = "id" in request ? request.id : void 0;
+		const record = (outcome, detail, windowOf) => {
+			const id = windowOf ?? windowId;
+			this.deps.audit.record({
+				at: (/* @__PURE__ */ new Date()).toISOString(),
+				tool: verb,
+				...request.op === "menu-click" ? { target: {
+					role: "menuitem",
+					name: request.path
+				} } : {},
+				...id === void 0 ? {} : { window: id },
+				outcome,
+				...detail === void 0 ? {} : { detail },
+				approval: "token"
+			});
+		};
+		try {
+			if (shell === void 0 || !shell.connected) throw new ShellError("no-desktop", NO_DESKTOP);
+			if (request.op === "window-close" && request.force !== true) {
+				const { windows } = await shell.call({ op: "window-list" }, { signal });
+				if (windows.length === 1 && windows[0]?.id === request.id) throw new ShellError("last-window", `window ${String(request.id)} is the app's last window: closing it ends the desktop app. Open another window first, or pass force to end it on purpose`);
+			}
+			const result = await shell.call(request, { signal });
+			record("ok", void 0, "id" in result ? result.id : void 0);
+			return {
+				value: result,
+				text: renderShell(result)
+			};
+		} catch (cause) {
+			if (!(cause instanceof ShellError)) throw cause;
+			record([
+				"invalid",
+				"no-such-window",
+				"last-window",
+				"no-such-menu-item",
+				"disabled",
+				"quits-app",
+				"no-desktop"
+			].includes(cause.code) ? "refused" : "failed", cause.code);
+			throw new DoorError(cause.code, cause.message);
+		}
+	}
+	/** `window` on look and act: the desktop window (the number `window list` prints) whose page the call is for; without it, the page used last. */
+	windowOf(input) {
+		const { window, ...rest } = input;
+		if (window === void 0) return {
+			window: void 0,
+			rest
+		};
+		if (typeof window !== "number" || !Number.isSafeInteger(window) || window < 1) throw new DoorError("invalid", "window must be the number `window list` prints for the window");
+		return {
+			window,
+			rest
 		};
 	}
 	parse(input) {
@@ -324,11 +812,12 @@ var Door = class {
 		}
 	}
 	/** Run one call on the page and record it. The audit holds which control was touched and how it ended, never what was typed. */
-	async callPage(verb, request, signal) {
+	async callPage(verb, request, signal, window) {
 		const approval = "token";
 		try {
 			const value = await this.deps.channel.call(request, {
 				signal,
+				...window === void 0 ? {} : { window },
 				...request.op === "wait" ? { timeoutMs: (request.timeoutMs ?? 3e3) + 5e3 } : {}
 			});
 			const target = "target" in value ? value.target : void 0;
@@ -336,6 +825,7 @@ var Door = class {
 				at: (/* @__PURE__ */ new Date()).toISOString(),
 				tool: verb,
 				...target === void 0 ? {} : { target },
+				...window === void 0 ? {} : { window },
 				outcome: "ok",
 				approval
 			});
@@ -354,6 +844,7 @@ var Door = class {
 			this.deps.audit.record({
 				at: (/* @__PURE__ */ new Date()).toISOString(),
 				tool: verb,
+				...window === void 0 ? {} : { window },
 				outcome: refused ? "refused" : "failed",
 				detail: code,
 				approval
@@ -426,6 +917,7 @@ function registerChatTools(tools, door) {
 	try {
 		for (const verb of VERBS) removers.push(tools.register(chatToolName(verb), {
 			description: VERB_SPECS[verb].description,
+			parameters: VERB_SPECS[verb].arguments,
 			run: async (input) => {
 				try {
 					return (await door.run(verb, input ?? {}, running.signal)).text;
@@ -715,11 +1207,41 @@ function windowsShim(root, target) {
 	].map(cmdWord).join(" ");
 	return `@echo off\r\nsetlocal\r\nrem This app's door (acryl-door): reaches only the app running from this folder. Rewritten each time the app starts.\r\n${target.electron ? "set ELECTRON_RUN_AS_NODE=1\r\n" : ""}${words} %*\r\n`;
 }
-function writeAtomically(file, content, mode) {
+/** The error codes with which Windows refuses to replace a file that a running process (a `cmd.exe` executing the batch file) has open. */
+const LOCKED = /* @__PURE__ */ new Set([
+	"EPERM",
+	"EBUSY",
+	"EACCES"
+]);
+const realFs = {
+	rename: renameSync,
+	pause: (ms) => {
+		Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+	}
+};
+/**
+* Write `content` to `file` so a reader never sees half of it. A shim that already holds this content is left alone: a restart of the app (the dev server restarts on a change)
+* rewrites the same text, and on Windows replacing a batch file that an agent's `acryl` call is running fails with EPERM, which stopped the app from starting. A file that
+* is held while its content differs is retried for about a second, and then reported: the old shim stays (it still works), and the app starts.
+*/
+function writeAtomically(file, content, mode, fs = realFs) {
+	try {
+		if (readFileSync(file, "utf8") === content) return;
+	} catch {}
 	const temporary = `${file}.${String(process.pid)}.tmp`;
 	writeFileSync(temporary, content, { mode });
 	if (process.platform !== "win32") chmodSync(temporary, mode);
-	renameSync(temporary, file);
+	for (let attempt = 0;; attempt += 1) try {
+		fs.rename(temporary, file);
+		return;
+	} catch (cause) {
+		const code = cause.code;
+		if (code === void 0 || !LOCKED.has(code) || attempt >= 10) {
+			rmSync(temporary, { force: true });
+			throw cause;
+		}
+		fs.pause(25 * (attempt + 1));
+	}
 }
 /** Write `.acryl/bin/acryl` and `.acryl/bin/acryl.cmd` for the app at `root`. @returns the folder they are in. */
 function writeShims(root, target) {
@@ -779,6 +1301,11 @@ function loopbackUrl(url) {
 	if (parsed.hostname === "0.0.0.0" || parsed.hostname === "[::]") parsed.hostname = "127.0.0.1";
 	return parsed.origin;
 }
+const escapeHtml = (text) => text.replace(/[&<>"']/gu, (char) => `&#${char.charCodeAt(0)};`);
+/** The page of a path the app does not serve, development only: what is missing, a way back, and the door's script. */
+function notFoundPage(path, scriptTag) {
+	return `<!doctype html><html lang="en"><head><meta charset="utf-8"><title>404 Not Found</title></head><body><main><h1>404 Not Found</h1><p>This app has no page at <code>${escapeHtml(path)}</code>.</p><p><a href="/">Back to the app</a></p></main>${scriptTag}</body></html>`;
+}
 function apply(ctx, rawConfig = {}) {
 	const config = Config(rawConfig);
 	if (process.env.ACRYL_DOOR === "off" || process.env.NODE_ENV === "production" && config.allowInProduction !== true) return;
@@ -790,8 +1317,10 @@ function apply(ctx, rawConfig = {}) {
 	};
 	const secret = newSecret();
 	const channel = new UiChannel();
+	const shell = new ShellChannel();
 	const door = new Door({
 		channel,
+		shell,
 		audit: new AuditLog(auditPath(stateDir(app.root))),
 		app: {
 			name: app.name,
@@ -806,11 +1335,20 @@ function apply(ctx, rawConfig = {}) {
 	ctx.effect(() => () => {
 		channel.close();
 	}, "acryl-door: page channel");
+	ctx.effect(() => () => {
+		shell.close();
+	}, "acryl-door: desktop shell channel");
 	const pageModule = new Acryl().get(`${DOOR_PREFIX}/page.js`, (c) => c.body(`import '${DOOR_PREFIX}/page/main.ts'\n`, 200, { "content-type": "text/javascript; charset=utf-8" })).route(`${DOOR_PREFIX}/page`, clientModules({ root: PAGE_DIR }));
 	const tag = `<script type="module" src="${DOOR_PREFIX}/page.js"><\/script>`;
 	const addScript = async (c, next) => {
 		await next();
-		if (!(c.res.headers.get("content-type") ?? "").includes("text/html")) return;
+		if (!(c.res.headers.get("content-type") ?? "").includes("text/html")) {
+			if (c.res.status === 404 && (c.req.header("accept") ?? "").includes("text/html") && !(c.res.headers.get("content-type") ?? "").includes("json")) c.res = new Response(notFoundPage(c.req.path, tag), {
+				status: 404,
+				headers: { "content-type": "text/html; charset=utf-8" }
+			});
+			return;
+		}
 		const html = await c.res.text();
 		const headers = new Headers(c.res.headers);
 		headers.delete("content-length");
@@ -823,18 +1361,22 @@ function apply(ctx, rawConfig = {}) {
 	const router = ctx.router;
 	if (typeof router.wrap === "function") router.wrap(addScript);
 	else ctx.router.route("/", new Acryl().use("*", addScript));
-	ctx.router.route("/", privateApi(DOOR_PREFIX, pageModule, pageChannelRoutes(channel, { prefix: DOOR_PREFIX }), operatorRoutes(DOOR_PREFIX, secret, door, reportError), mcpRoutes(DOOR_PREFIX, secret, door, reportError)));
+	ctx.router.route("/", privateApi(DOOR_PREFIX, pageModule, pageChannelRoutes(channel, { prefix: DOOR_PREFIX }), shellRoutes(DOOR_PREFIX, secret, shell), operatorRoutes(DOOR_PREFIX, secret, door, reportError), mcpRoutes(DOOR_PREFIX, secret, door, reportError)));
 	ctx.inject(["tools"], (inner) => {
 		inner.effect(() => registerChatTools(inner.get("tools"), door), "acryl-door: the verbs in the tools registry");
 	});
 	ctx.effect(function* () {
 		yield ctx.reflect.provide("door", door);
 		writeDoorFile(app.root, loopbackUrl(server.url), secret);
-		writeShims(app.root, shimTarget());
+		try {
+			writeShims(app.root, shimTarget());
+		} catch (cause) {
+			reportError("write .acryl/bin", cause);
+		}
 		yield () => {
 			removeDoorFile(app.root, secret);
 		};
 	}, "acryl-door: the door service, .acryl/door.json and .acryl/bin/acryl");
 }
 //#endregion
-export { Config, DOOR_PREFIX, Door, DoorError, STATE_DIR, VERBS, VERB_SPECS, apply, chatToolName, doorFilePath, inject, mcpTools, name, readDoorFile };
+export { Config, DOOR_PREFIX, Door, DoorError, STATE_DIR, VERBS, VERB_SPECS, apply, chatToolName, doorFilePath, inject, mcpTools, name, notFoundPage, readDoorFile };