acrylblends 1.0.6 → 1.0.8

package/docs/framework/guides/production.md

@@ -10,7 +10,7 @@
 | **The door** (`acryl-door`: `.acryl/bin/acryl`, the page script, the operator routes) | **experimental**: starts when the server is up | starts nothing: no service, no route, no `.acryl/` folder, no script in the page. `ACRYL_DOOR=off` also turns it off. A host that means to run it in production sets `allowInProduction: true` in the plugin's config |
 | **The agent panel** (`agent-panel`) | **experimental**: a script tag on every HTML page and `/api/agent-panel/*` | does nothing (no tag, no routes). `ACRYL_DOOR=off` too |
 | **The PTY driver** (`driver-pty`) | **experimental**: terminal drivers in the panel, `/api/driver-pty/*` | does nothing. `ACRYL_DOOR=off` too |
-| **Live plugin install and the agent** (`extensions`, `builder`, `agent`: `POST /ask`) | **experimental**: install, update, remove and reload plugins while the app runs; the agent builds them | left out: the `nodejs`, `notes` and `chat` templates drop the `extensions` row, and the `agent` template drops `agent`, `builder` and `extensions` (since 1.0.1) unless `ACRYL_PRODUCTION_KEEP` names them |
+| **Live plugin install and the agent** (`extensions`, `builder`, `agent`: `POST /ask`) | **experimental**: install, update, remove and reload plugins while the app runs; the agent builds them | left out: the `nodejs`, `notes` and `chat` templates drop the `extensions` row, and the `agent` template drops `agent` and `builder` (since 1.0.1) and starts the `extensions` read-only (since 1.0.7: the plugins in `plugins/` run as deployed, nothing can be installed or changed) unless `ACRYL_PRODUCTION_KEEP` names them |
 | **The chat template's model endpoint** (`POST /api/chat`) | answers anyone | **closed** (503) unless `CHAT_ACCESS_TOKEN` is set, or `ACRYL_PRODUCTION_KEEP=chat` makes it public with a warning and a per-address limit (since 1.0.2) |
 | `acrylblends/bun` | **experimental**: one smoke gate runs it on Bun | the same |
 
@@ -18,9 +18,9 @@ Experimental means: it works and is gated, its interface may still change in a m
 
 ## The `agent` template in production
 
-The `agent` template mounts an agent behind `POST /ask` that spends the model key and can write plugins into the running app (`builder`) and install them (`extensions`, with `POST /extensions/approve` deciding installs). **None of that is behind a login.** Since 1.0.1, with `NODE_ENV=production` the template leaves the `agent`, `builder` and `extensions` rows out, along with the door: `/ask`, `/extensions*` and `/tasks*` are not mounted, and the page and `GET /health` stay. 1.0.0 left them mounted.
+The `agent` template mounts an agent behind `POST /ask` that spends the model key and can write plugins into the running app (`builder`) and install them (`extensions`, with `POST /extensions/approve` deciding installs). **None of that is behind a login.** Since 1.0.1, with `NODE_ENV=production` the template leaves the `agent` and `builder` rows out, along with the door: `/ask`, `/extensions*` and `/tasks*` are not mounted, and the page and `GET /health` stay. 1.0.0 left them mounted. **What the agent built is still served**: 1.0.1 to 1.0.6 also left the `extensions` row out, so an app whose pages were extensions (the workshop's board) lost them in production. Since 1.0.7 the row starts again, read-only: the extension folders of `plugins/` (what the agent installed in development, committed with the app) are loaded once from where they are, nothing can be installed, updated, removed or approved while the app runs, and the start prints one line, `extensions (read-only): board, notes` (or `extensions: none found in plugins/`). If `.acrylblends/extensions.json` records an extension that `plugins/` has no folder for, a `WARNING` names it: commit its folder, or install it again in development.
 
-- To keep a row anyway, name it: `ACRYL_PRODUCTION_KEEP=agent,builder,extensions` (a comma list). Each row kept prints a `WARNING` line at start saying what it gives a visitor. Put your own login in front before you do.
+- To keep a row anyway, name it: `ACRYL_PRODUCTION_KEEP=agent,builder,extensions` (a comma list; naming `extensions` keeps the live install, not just the read-only start). Each row kept prints a `WARNING` line at start saying what it gives a visitor. Put your own login in front before you do.
 - **An app made by 1.0.0 keeps its own `src/app.ts` and `src/routes.ts`**, which `acrylblends upgrade` never touches (they are your files). Until you change them: deploy with the `agent`, `builder` and `extensions` rows set to `disabled: true` in `blend.yaml`, or start from another template, or copy the new `src/app.ts` and `src/routes.ts` of a fresh `acrylblends init my-app --template agent` over yours.
 
 ## The `chat` template in production

package/lib/{audit-GcLtvNLV.d.ts → audit-BD8_2pkh.d.ts}

@@ -1,4 +1,4 @@
-import { _ as UiRequest, n as AuditEntry, r as ChannelToHost, v as UiResult } from "./protocol-CR31M7K_.js";
+import { _ as UiRequest, n as AuditEntry, r as ChannelToHost, v as UiResult } from "./protocol-a2aqrp2X.js";
 
 //#region ../../plugins/acryl-door/src/host/channel.d.ts
 /** The slice of a page's stream the channel needs, so tests can supply their own. */
@@ -6,7 +6,19 @@ interface PageStream {
   send(data: string): void;
   close(): void;
 }
+interface ChannelOptions {
+  /** How long a page has to acknowledge a read-only call (`look`, `wait`) before the next page is tried. */
+  readonly ackMs?: number;
+}
+/**
+ * The pages and who drives which. One page answers a call, chosen the same way every time: the page the Host just sent somewhere (it comes back as a new page, `prefer`), else the
+ * one in front (it reports `focused`), else the most recently active; a page that did not acknowledge a call in time goes to the end of the line. An explicit desktop `window` picks its page.
+ */
 declare class UiChannel {
+  private readonly ackMs;
+  /** The page the Host sent to a new place and that came back: it keeps being driven until the person focuses another page. */
+  private preferred;
+  constructor(options?: ChannelOptions);
   private readonly connections;
   private readonly pending;
   private nextId;
@@ -29,8 +41,11 @@ declare class UiChannel {
     focused: boolean;
     shellWindow?: number;
   }[];
+  /** Drive this page from now on (it is the one the Host just sent to a new place), until the person focuses another. */
+  prefer(windowId: string): void;
   /**
-   * Ask the current page to do something.
+   * Ask the current page to do something. A read-only call (`look`, `wait`) that the page does not acknowledge in time goes to the next page, and the silent one is last in line
+   * until it speaks; a call that changes the page is never sent to a second page, because the first might still run it.
    * @throws UiControlError `no-window`, `timeout`, `aborted`, `unloaded`, `disconnected`, or whatever the page refused with.
    */
   call(request: UiRequest, options?: {
@@ -38,11 +53,17 @@ declare class UiChannel {
     timeoutMs?: number;
     window?: number;
   }): Promise<UiResult>;
+  private callOne;
   /**
    * A promise for the next time a page connects (a page that reloaded or moved opens a new stream). Ask for it BEFORE the call that makes the page leave, or a fast page is missed.
    * @returns whether a page connected within `timeoutMs`.
    */
   expectAttach(timeoutMs: number, count?: number): Promise<boolean>;
+  /**
+   * A promise for the window id of the next page that connects and was not connected when this was asked (the page that came back after a reload or a move).
+   * @returns that id, or `undefined` when no new page connected within `timeoutMs`.
+   */
+  expectNewPage(timeoutMs: number): Promise<string | undefined>;
   /**
    * Ask every connected page to reload (the app just changed under them) and wait, up to `timeoutMs`, for them to come back. Best effort: a page that does not come back
    * (it was closed, or it moved to a page without the door) is not an error here.
@@ -51,7 +72,8 @@ declare class UiChannel {
   reloadAll(timeoutMs?: number): Promise<number>;
   /** Close every page's stream and settle every pending call as `unloaded`. */
   close(): void;
-  private byRecency;
+  /** The order pages are driven in: the one the Host sent somewhere, suspect ones last, the one in front, then the most recently active. */
+  private ordered;
   /** Forget a connection; its calls in flight settle as `disconnected` at once rather than waiting for their timeout. */
   private drop;
   private settle;

package/lib/cordis/door.d.ts

@@ -1,5 +1,5 @@
-import { f as UiActionResult, y as UiSnapshot } from "../protocol-CR31M7K_.js";
-import { i as UiChannel, r as PageStream, t as AuditLog } from "../audit-GcLtvNLV.js";
+import { f as UiActionResult, y as UiSnapshot } from "../protocol-a2aqrp2X.js";
+import { i as UiChannel, r as PageStream, t as AuditLog } from "../audit-BD8_2pkh.js";
 import { Context } from "@deepseek-ai/cordis";
 import z from "@deepseek-ai/schemastery";
 

package/lib/cordis/door.js

@@ -1,10 +1,12 @@
 import { t as Acryl } from "../app-CQcGWjrk.js";
 import { r as streamSSE } from "../streaming-BlDaph8U.js";
+import { r as loopbackAuthority } from "../loopback-only-BbasoF7R.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 { a as MAX_WAIT_MS, d as parseChannelToHost, l as UiControlError, p as parseUiRequest, r as MAX_SNAPSHOT_NODES, u as WINDOW_ID } from "../protocol-CQ_if7Dg.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-m13Pk-AI.js";
 import "../src-BTBm4OPD.js";
+import "../middleware-BfG_fp8P.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";
@@ -701,7 +703,7 @@ var Door = class {
 		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);
+		const back = this.deps.channel.expectNewPage(this.deps.pageBackMs ?? PAGE_BACK_MS);
 		let answer;
 		try {
 			answer = await this.callPage(`act ${request.op}`, request, signal, window);
@@ -712,7 +714,9 @@ var Door = class {
 				detail: request.op === "reload" ? "reloading" : `going to ${request.path}`
 			};
 		}
-		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 came = await back;
+		if (came !== void 0) this.deps.channel.prefer(came);
+		if (came === void 0) 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,
@@ -1151,6 +1155,66 @@ function operatorRoutes(prefix, secret, door, reportError) {
 		}
 	});
 }
+/** The upgrade request comes from this app's own page: a loopback peer on this port, and an `Origin` that is exactly this app's origin. Nothing else is read as proof. */
+const ownOrigin = async (c, next) => {
+	const authority = loopbackAuthority(c);
+	const origin = c.req.header("origin");
+	const site = c.req.header("sec-fetch-site");
+	if (authority === void 0 || origin === void 0 || origin !== authority.origin || site !== void 0 && site !== "same-origin") return c.json(error("only this app's own page may open the channel"), 403);
+	const windowId = c.req.query("window");
+	if (windowId === void 0 || !WINDOW_ID.test(windowId)) return c.json(error("a window id is required"), 400);
+	await next();
+};
+function pageSocketRoutes(channel, options) {
+	const heartbeatMs = options.heartbeatMs ?? 15e3;
+	return new Acryl().get(`${options.prefix}/channel/ws`, ownOrigin, options.upgrade((c) => {
+		const windowId = c.req.query("window");
+		const focused = c.req.query("focused") === "1";
+		const shellQuery = Number(c.req.query("shell"));
+		const shellWindow = Number.isSafeInteger(shellQuery) && shellQuery > 0 ? shellQuery : void 0;
+		let detach;
+		let beat;
+		return {
+			onOpen(_event, ws) {
+				const write = (frame) => {
+					ws.send(JSON.stringify(frame));
+				};
+				detach = channel.attach(windowId, focused, {
+					send: (data) => {
+						write({
+							e: "call",
+							d: data
+						});
+					},
+					close: () => {
+						ws.close(1e3, "replaced");
+					}
+				}, shellWindow);
+				write({ e: "ready" });
+				beat = setInterval(() => {
+					try {
+						write({ e: "ping" });
+					} catch {}
+				}, heartbeatMs);
+			},
+			onMessage(event) {
+				if (typeof event.data !== "string") return;
+				let message;
+				try {
+					message = JSON.parse(event.data);
+				} catch {
+					return;
+				}
+				const parsed = parseChannelToHost(message);
+				if (parsed !== null) channel.receive(windowId, parsed);
+			},
+			onClose() {
+				if (beat !== void 0) clearInterval(beat);
+				detach?.();
+			}
+		};
+	}, { textOnly: true }));
+}
 /** The oldest Node the client runs on (the framework's own floor). */
 const MIN_NODE = [22, 19];
 /**
@@ -1195,7 +1259,7 @@ function posixShim(root, target) {
 		"--dir",
 		root
 	].map(shWord).join(" ");
-	return `#!/bin/sh\n# This app's door (acryl-door): reaches only the app running from this folder. Rewritten each time the app starts.\n${target.electron ? "export ELECTRON_RUN_AS_NODE=1\n" : ""}exec ${words} "$@"\n`;
+	return `#!/bin/sh\n# This app's door (acryl-door): reaches only the app running from this folder. Rewritten each time the app starts.\n${`${target.electron ? "export ELECTRON_RUN_AS_NODE=1\n" : ""}export MSYS_NO_PATHCONV=1\nexport MSYS2_ARG_CONV_EXCL='*'\n`}exec ${words} "$@"\n`;
 }
 function windowsShim(root, target) {
 	const words = [
@@ -1361,7 +1425,16 @@ 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 }), shellRoutes(DOOR_PREFIX, secret, shell), operatorRoutes(DOOR_PREFIX, secret, door, reportError), mcpRoutes(DOOR_PREFIX, secret, door, reportError)));
+	let upgrade;
+	try {
+		upgrade = ctx.nodeServer?.upgrades?.();
+	} catch (cause) {
+		reportError("open the page channel over a WebSocket (the pages use the event stream)", cause);
+	}
+	ctx.router.route("/", privateApi(DOOR_PREFIX, pageModule, pageChannelRoutes(channel, { prefix: DOOR_PREFIX }), ...upgrade === void 0 ? [] : [pageSocketRoutes(channel, {
+		prefix: DOOR_PREFIX,
+		upgrade
+	})], 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");
 	});

package/lib/door/host.d.ts

@@ -1,6 +1,6 @@
 import { t as Acryl } from "../app-D8riatvv.js";
-import { n as AuditEntry, y as UiSnapshot } from "../protocol-CR31M7K_.js";
-import { i as UiChannel, n as auditPath, r as PageStream, t as AuditLog } from "../audit-GcLtvNLV.js";
+import { n as AuditEntry, y as UiSnapshot } from "../protocol-a2aqrp2X.js";
+import { i as UiChannel, n as auditPath, r as PageStream, t as AuditLog } from "../audit-BD8_2pkh.js";
 
 //#region ../../plugins/acryl-door/src/host/page-routes.d.ts
 /** How often the Host writes a `ping`; the page gives up on a stream that is silent for three of these. */

package/lib/door/host.js

@@ -1,2 +1,2 @@
-import { d as AuditLog, f as auditPath, n as HEARTBEAT_MS, p as UiChannel, r as pageChannelRoutes, t as renderSnapshot } from "../snapshot-text-CtQm3n8n.js";
+import { d as AuditLog, f as auditPath, n as HEARTBEAT_MS, p as UiChannel, r as pageChannelRoutes, t as renderSnapshot } from "../snapshot-text-m13Pk-AI.js";
 export { AuditLog, HEARTBEAT_MS, UiChannel, auditPath, pageChannelRoutes, renderSnapshot };

package/lib/door/page.d.ts

@@ -1,4 +1,4 @@
-import { _ as UiRequest, v as UiResult } from "../protocol-CR31M7K_.js";
+import { _ as UiRequest, v as UiResult } from "../protocol-a2aqrp2X.js";
 
 //#region ../../plugins/acryl-door/src/page/driver/driver.d.ts
 interface DriverActivity {
@@ -55,6 +55,12 @@ declare class UiDriver {
   private emit;
 }
 //#endregion
+//#region ../../plugins/acryl-door/src/page/socket-source.d.ts
+interface SocketSource extends ChannelSource {
+  /** Send one message up; false when the socket is not open (the caller posts it instead). */
+  send(text: string): boolean;
+}
+//#endregion
 //#region ../../plugins/acryl-door/src/page/channel.d.ts
 /** The slice of an `EventSource` the channel uses, so tests can supply their own. */
 interface ChannelSource {
@@ -73,6 +79,11 @@ interface PageChannelOptions {
   /** Where the door's routes are, e.g. `/api/acryl-door`. */
   readonly base: string;
   readonly createSource?: (url: string) => ChannelSource;
+  /** Opens the WebSocket form of the channel (`<base>/channel/ws`); the browser's own by default. Pass `transport: 'stream'` to keep to the event stream. */
+  readonly createSocket?: (url: string) => SocketSource;
+  readonly transport?: 'auto' | 'stream';
+  /** Where the page says it fell back to the event stream (the console by default). */
+  readonly warn?: (message: string) => void;
   readonly post?: (url: string, body: string) => Promise<unknown>;
   readonly silenceMs?: number;
   readonly now?: () => number;
@@ -82,6 +93,9 @@ declare class PageChannel {
   private reconnectTimer;
   private watchdog;
   private backoff;
+  /** The WebSocket form is tried first; once it fails to open (a proxy that cannot upgrade, no `ws` on the server) the page keeps to the event stream. */
+  private socketAllowed;
+  private socketReady;
   private lastHeard;
   private disposed;
   private readonly now;
@@ -89,8 +103,17 @@ declare class PageChannel {
   private readonly options;
   constructor(driver: UiDriver, options: PageChannelOptions);
   connect(): void;
+  /** The WebSocket did not open: use the event stream from now on, and say why once. */
+  private fallBack;
   /** Tell the Host whether this window is the one in front. */
   reportFocus(focused: boolean): void;
+  /**
+   * Let go of the stream without ending the channel: the page is going away but the browser may keep it (the back/forward cache keeps a page that was left, still holding its
+   * connections). A browser allows six connections per host, so pages kept like that would queue the live page's own answers behind them. `resume` opens the stream again.
+   */
+  suspend(): void;
+  /** The page is back (restored from the cache): open the stream again with the same window id. */
+  resume(): void;
   dispose(): void;
   /** Drop the stream and open a new one after the backoff. */
   private restart;

package/lib/door/page.js

@@ -1,4 +1,54 @@
-import { a as MAX_WAIT_MS, f as parseChannelToPage, l as UiControlError, o as MUTATING_OPS, r as MAX_SNAPSHOT_NODES } from "../protocol-Dt0AZBOz.js";
+import { a as MAX_WAIT_MS, f as parseChannelToPage, l as UiControlError, o as MUTATING_OPS, r as MAX_SNAPSHOT_NODES } from "../protocol-CQ_if7Dg.js";
+//#region ../../plugins/acryl-door/src/page/socket-source.ts
+function socketSource(socket) {
+	const listeners = /* @__PURE__ */ new Map();
+	let closed = false;
+	const source = {
+		onerror: null,
+		get readyState() {
+			return closed || socket.readyState >= 2 ? 2 : socket.readyState;
+		},
+		addEventListener(type, listener) {
+			listeners.set(type, [...listeners.get(type) ?? [], listener]);
+		},
+		send(text) {
+			if (socket.readyState !== 1) return false;
+			try {
+				socket.send(text);
+				return true;
+			} catch {
+				return false;
+			}
+		},
+		close() {
+			closed = true;
+			socket.onmessage = null;
+			socket.onerror = null;
+			socket.onclose = null;
+			try {
+				socket.close(1e3, "page left");
+			} catch {}
+		}
+	};
+	socket.onmessage = (event) => {
+		if (typeof event.data !== "string") return;
+		let frame;
+		try {
+			frame = JSON.parse(event.data);
+		} catch {
+			return;
+		}
+		if (typeof frame.e !== "string") return;
+		for (const listener of listeners.get(frame.e) ?? []) listener({ data: typeof frame.d === "string" ? frame.d : "" });
+	};
+	const lost = (event) => {
+		if (!closed) source.onerror?.(event);
+	};
+	socket.onerror = lost;
+	socket.onclose = lost;
+	return source;
+}
+//#endregion
 //#region ../../plugins/acryl-door/src/page/channel.ts
 /**
 * The page's end of the door's channel.
@@ -18,6 +68,9 @@ var PageChannel = class {
 	reconnectTimer;
 	watchdog;
 	backoff = BACKOFF_START_MS;
+	/** The WebSocket form is tried first; once it fails to open (a proxy that cannot upgrade, no `ws` on the server) the page keeps to the event stream. */
+	socketAllowed;
+	socketReady = false;
 	lastHeard = 0;
 	disposed = false;
 	now;
@@ -27,32 +80,49 @@ var PageChannel = class {
 		this.driver = driver;
 		this.options = options;
 		this.now = options.now ?? (() => Date.now());
+		this.socketAllowed = options.transport !== "stream" && (options.createSocket !== void 0 || options.createSource === void 0 && typeof WebSocket !== "undefined");
 	}
 	connect() {
 		if (this.disposed || this.source !== void 0) return;
-		const create = this.options.createSource ?? ((url) => new EventSource(url));
 		const query = `window=${encodeURIComponent(this.options.windowId)}&focused=${this.options.focused() ? "1" : "0"}${this.options.shellWindow === void 0 ? "" : `&shell=${String(this.options.shellWindow)}`}`;
-		const source = create(`${this.options.base}/channel?${query}`);
+		const viaSocket = this.socketAllowed;
+		this.socketReady = false;
+		const source = viaSocket ? (this.options.createSocket ?? ((url) => socketSource(new WebSocket(url))))(`${socketBase(this.options.base)}/channel/ws?${query}`) : (this.options.createSource ?? ((url) => new EventSource(url)))(`${this.options.base}/channel?${query}`);
 		this.source = source;
 		this.lastHeard = this.now();
 		const heard = () => {
 			this.lastHeard = this.now();
 			this.backoff = BACKOFF_START_MS;
 		};
-		source.addEventListener("ready", heard);
+		source.addEventListener("ready", () => {
+			this.socketReady = true;
+			heard();
+		});
 		source.addEventListener("ping", heard);
 		source.addEventListener("call", (event) => {
 			heard();
 			if (typeof event.data === "string") this.answer(event.data);
 		});
 		source.onerror = () => {
-			if (source.readyState === CLOSED) this.restart(source);
+			if (source.readyState !== CLOSED) return;
+			if (viaSocket && !this.socketReady) this.fallBack(source);
+			else this.restart(source);
 		};
 		const silence = this.options.silenceMs ?? 45e3;
 		this.watchdog = setInterval(() => {
 			if (this.now() - this.lastHeard > silence) this.restart(source);
 		}, Math.max(50, Math.floor(silence / 3)));
 	}
+	/** The WebSocket did not open: use the event stream from now on, and say why once. */
+	fallBack(source) {
+		if (this.source !== source) return;
+		this.socketAllowed = false;
+		(this.options.warn ?? ((message) => {
+			console.warn(message);
+		}))("acryl-door: the page channel could not open a WebSocket (the server has no upgrade route, or a proxy refused it); using server-sent events, which count against the browser's six connections per host");
+		this.stop();
+		this.connect();
+	}
 	/** Tell the Host whether this window is the one in front. */
 	reportFocus(focused) {
 		this.send({
@@ -60,6 +130,22 @@ var PageChannel = class {
 			focused
 		});
 	}
+	/**
+	* Let go of the stream without ending the channel: the page is going away but the browser may keep it (the back/forward cache keeps a page that was left, still holding its
+	* connections). A browser allows six connections per host, so pages kept like that would queue the live page's own answers behind them. `resume` opens the stream again.
+	*/
+	suspend() {
+		if (this.disposed) return;
+		if (this.reconnectTimer !== void 0) clearTimeout(this.reconnectTimer);
+		this.reconnectTimer = void 0;
+		this.stop();
+	}
+	/** The page is back (restored from the cache): open the stream again with the same window id. */
+	resume() {
+		if (this.disposed) return;
+		this.backoff = BACKOFF_START_MS;
+		this.connect();
+	}
 	dispose() {
 		this.disposed = true;
 		if (this.reconnectTimer !== void 0) clearTimeout(this.reconnectTimer);
@@ -93,6 +179,10 @@ var PageChannel = class {
 		} catch {
 			return;
 		}
+		this.send({
+			t: "ack",
+			id: call.id
+		});
 		this.driver.handle(call.request).then((value) => {
 			this.send({
 				t: "result",
@@ -110,6 +200,7 @@ var PageChannel = class {
 		});
 	}
 	send(message) {
+		if (this.source?.send?.(JSON.stringify(message)) === true) return;
 		(this.options.post ?? ((url, body) => fetch(url, {
 			method: "POST",
 			headers: { "content-type": "application/json" },
@@ -120,16 +211,53 @@ var PageChannel = class {
 		})).catch(() => {});
 	}
 };
+/** The WebSocket address of the door's routes: this page's own origin, `ws:` or `wss:`, then the base path. */
+function socketBase(base) {
+	const here = globalThis.location;
+	if (here === void 0) return base;
+	return `${here.protocol === "https:" ? "wss" : "ws"}://${here.host}${base}`;
+}
 //#endregion
 //#region ../../plugins/acryl-door/src/page/driver/sensitivity.ts
 /**
 * What the agent may never see or type into, decided by rule and not by trusting the agent:
 * secrets and payment fields (sensitive), and controls that govern the agent itself (protected).
 */
-/** Field names and labels that mean a secret or a payment detail. */
-const SENSITIVE_WORDS = /pass(?:word|code|phrase)|secret|token|api[-_ ]?key|credential|private[-_ ]?key|\bpin\b|card|cvv|cvc|iban|routing|account[-_ ]?number|ssn|social[-_ ]?security|one[-_ ]?time|otp/i;
+/**
+* Field names and labels that unmistakably name a secret or a payment detail. A word that is only sometimes one is not here: a bare "card" is the title of a card on a board,
+* "pin" a map marker, "routing" a page. What a field *is* decides first: a password input, an `autocomplete` of a credential or a payment detail, a value
+* that looks like a key. The words only catch a field that says what it holds in plain text.
+*/
+const SENSITIVE_WORDS = new RegExp([
+	"pass(?:word|code|phrase)",
+	"secret",
+	"api[-_ ]?key",
+	"private[-_ ]?key",
+	"credential",
+	"\\btoken\\b",
+	"(?:pin|security)[-_ ]?(?:code|number)",
+	"\\bcvv\\b",
+	"\\bcvc\\b",
+	"(?:credit|debit|payment)?[-_ ]?card[-_ ]?(?:number|no|num|code|expir)",
+	"\\bcc[-_ ]?(?:num|number|exp|csc)",
+	"iban",
+	"(?:bank[-_ ]?)?routing[-_ ]?number",
+	"account[-_ ]?number",
+	"\\bssn\\b",
+	"social[-_ ]?security",
+	"one[-_ ]?time[-_ ]?(?:code|password)",
+	"\\botp\\b"
+].join("|"), "i");
 /** `autocomplete` values that browsers treat as credentials or payment data. */
 const SENSITIVE_AUTOCOMPLETE = /^(?:cc-|current-password|new-password|one-time-code)/;
+/** A value that is a key or a token by its shape: a known prefix, a JSON web token, or one long unbroken string that mixes lower case, upper case and digits (a git hash is lower-case hex and is not one). */
+const KEY_PREFIX = /^(?:sk[-_]|pk[-_]|rk[-_]|ghp_|gho_|ghs_|github_pat_|glpat-|xox[abprs]-|AKIA[0-9A-Z]{12,}|AIza[0-9A-Za-z_-]{20,}|eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.)/;
+function looksLikeSecret(value) {
+	const text = value.trim();
+	if (text.length < 20 || /\s/u.test(text)) return false;
+	if (KEY_PREFIX.test(text)) return true;
+	return text.length >= 32 && /^[A-Za-z0-9+/_=-]+$/u.test(text) && /[a-z]/u.test(text) && /[A-Z]/u.test(text) && /\d/u.test(text);
+}
 const label = (el, attr) => el.getAttribute(attr) ?? "";
 /** True for a form field (or anything marked) that holds a secret or payment detail. */
 function isSensitive(el) {
@@ -137,12 +265,13 @@ function isSensitive(el) {
 	if (!(el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement || el instanceof HTMLSelectElement)) return false;
 	if (el instanceof HTMLInputElement && el.type === "password") return true;
 	if (label(el, "autocomplete").trim().toLowerCase().split(/\s+/).some((token) => SENSITIVE_AUTOCOMPLETE.test(token))) return true;
-	return SENSITIVE_WORDS.test([
+	if (SENSITIVE_WORDS.test([
 		el.name,
 		el.id,
 		label(el, "placeholder"),
 		label(el, "aria-label")
-	].join(" "));
+	].join(" "))) return true;
+	return !(el instanceof HTMLSelectElement) && looksLikeSecret(el.value);
 }
 /** Areas whose controls the agent may look at but never operate. */
 const PROTECTED_REGION = /approval|permission|policy|agent control|ui control|acryl-agent-control|acryl-door|kill switch/i;

package/lib/door/protocol.d.ts

@@ -1,2 +1,2 @@
-import { C as parseUiRequest, S as parseChannelToPage, _ as UiRequest, a as DEFAULT_SNAPSHOT_NODES, b as WINDOW_ID, c as MAX_WAIT_MS, d as UI_OPS, f as UiActionResult, g as UiOp, h as UiNode, i as ChannelToPage, l as MUTATING_OPS, m as UiErrorCode, n as AuditEntry, o as MAX_SNAPSHOT_NODES, p as UiControlError, r as ChannelToHost, s as MAX_TEXT_LENGTH, t as APP_PATH, u as UI_ERROR_CODES, v as UiResult, x as parseChannelToHost, y as UiSnapshot } from "../protocol-CR31M7K_.js";
+import { C as parseUiRequest, S as parseChannelToPage, _ as UiRequest, a as DEFAULT_SNAPSHOT_NODES, b as WINDOW_ID, c as MAX_WAIT_MS, d as UI_OPS, f as UiActionResult, g as UiOp, h as UiNode, i as ChannelToPage, l as MUTATING_OPS, m as UiErrorCode, n as AuditEntry, o as MAX_SNAPSHOT_NODES, p as UiControlError, r as ChannelToHost, s as MAX_TEXT_LENGTH, t as APP_PATH, u as UI_ERROR_CODES, v as UiResult, x as parseChannelToHost, y as UiSnapshot } from "../protocol-a2aqrp2X.js";
 export { APP_PATH, AuditEntry, ChannelToHost, ChannelToPage, DEFAULT_SNAPSHOT_NODES, MAX_SNAPSHOT_NODES, MAX_TEXT_LENGTH, MAX_WAIT_MS, MUTATING_OPS, UI_ERROR_CODES, UI_OPS, UiActionResult, UiControlError, UiErrorCode, UiNode, UiOp, UiRequest, UiResult, UiSnapshot, WINDOW_ID, parseChannelToHost, parseChannelToPage, parseUiRequest };

package/lib/door/protocol.js

@@ -1,2 +1,2 @@
-import { a as MAX_WAIT_MS, c as UI_OPS, d as parseChannelToHost, f as parseChannelToPage, i as MAX_TEXT_LENGTH, l as UiControlError, n as DEFAULT_SNAPSHOT_NODES, o as MUTATING_OPS, p as parseUiRequest, r as MAX_SNAPSHOT_NODES, s as UI_ERROR_CODES, t as APP_PATH, u as WINDOW_ID } from "../protocol-Dt0AZBOz.js";
+import { a as MAX_WAIT_MS, c as UI_OPS, d as parseChannelToHost, f as parseChannelToPage, i as MAX_TEXT_LENGTH, l as UiControlError, n as DEFAULT_SNAPSHOT_NODES, o as MUTATING_OPS, p as parseUiRequest, r as MAX_SNAPSHOT_NODES, s as UI_ERROR_CODES, t as APP_PATH, u as WINDOW_ID } from "../protocol-CQ_if7Dg.js";
 export { APP_PATH, DEFAULT_SNAPSHOT_NODES, MAX_SNAPSHOT_NODES, MAX_TEXT_LENGTH, MAX_WAIT_MS, MUTATING_OPS, UI_ERROR_CODES, UI_OPS, UiControlError, WINDOW_ID, parseChannelToHost, parseChannelToPage, parseUiRequest };

package/lib/{protocol-Dt0AZBOz.js → protocol-CQ_if7Dg.js}

@@ -196,6 +196,10 @@ function parseChannelToHost(value) {
 		t: "focus",
 		focused: value.focused
 	};
+	if (value.t === "ack" && typeof value.id === "number") return {
+		t: "ack",
+		id: value.id
+	};
 	if (value.t === "result" && typeof value.id === "number" && isRecord(value.value)) return {
 		t: "result",
 		id: value.id,

package/lib/{protocol-CR31M7K_.d.ts → protocol-a2aqrp2X.d.ts}

@@ -107,6 +107,9 @@ type ChannelToPage = {
 type ChannelToHost = {
   readonly t: 'focus';
   readonly focused: boolean;
+} /** The page received call `id` and is about to run it: proof that it is alive, sent before anything is done. */ | {
+  readonly t: 'ack';
+  readonly id: number;
 } | {
   readonly t: 'result';
   readonly id: number;