acrylblends 1.0.4 → 1.0.6

package/lib/ws.js

@@ -1,56 +1,2 @@
-//#region ../../plugins/acryl-router/src/core/helper/websocket/index.ts
-/**
-* A context for controlling WebSockets
-*/
-var WSContext = class {
-	#init;
-	constructor(init) {
-		this.#init = init;
-		this.raw = init.raw;
-		this.url = init.url ? new URL(init.url) : null;
-		this.protocol = init.protocol ?? null;
-	}
-	send(source, options) {
-		this.#init.send(source, options ?? {});
-	}
-	raw;
-	binaryType = "arraybuffer";
-	get readyState() {
-		return this.#init.readyState;
-	}
-	get bufferedAmount() {
-		return this.#init.bufferedAmount ?? 0;
-	}
-	url;
-	protocol;
-	close(code, reason) {
-		this.#init.close(code, reason);
-	}
-};
-const createWSMessageEvent = (source) => {
-	return new MessageEvent("message", { data: source });
-};
-/**
-* Create a WebSocket adapter/helper
-*/
-const defineWebSocketHelper = (handler) => {
-	return ((...args) => {
-		if (typeof args[0] === "function") {
-			const [createEvents, options] = args;
-			return async function upgradeWebSocket(c, next) {
-				const result = await handler(c, await createEvents(c), options);
-				if (result) return result;
-				await next();
-			};
-		} else {
-			const [c, events, options] = args;
-			return (async () => {
-				const upgraded = await handler(c, events, options);
-				if (!upgraded) throw new Error("Failed to upgrade WebSocket");
-				return upgraded;
-			})();
-		}
-	});
-};
-//#endregion
+import { n as createWSMessageEvent, r as defineWebSocketHelper, t as WSContext } from "./websocket-DsyBIKVA.js";
 export { WSContext, createWSMessageEvent, defineWebSocketHelper };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "acrylblends",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "The Acryl web framework (import { Acryl } from \"acrylblends\") and the acrylblends command that scaffolds Cordis apps.",
   "license": "MIT",
   "type": "module",

package/plugins/acryl-door/src/cli/acryl.ts

@@ -4,7 +4,7 @@
  * `.acryl/door.json` upward, or `--dir`), never through PATH or a machine-wide registry, so it reaches only the app running from that
  * folder. The secret is read from that file and sent as a `Bearer` header; it is never printed.
  *
- *   acryl brief | look | act <op> ... | plugin list|add|remove|reload | tool list|call | verbs      (--json for the raw value)
+ *   acryl brief | look | act <op> ... | plugin list|add|remove|reload | tool list|call | window list|open|focus|close|resize | menu list|click | verbs      (--json for the raw value)
  *   acryl control <...>   the same, the ACRYL Host form (`control snapshot`, `control click`, ... are look and act)
  *
  * Exit codes: 0 done, 1 the verb failed (its code and message are printed), 2 a usage error, 3 no running app in this folder.
@@ -16,8 +16,8 @@ import { fileURLToPath } from 'node:url'
 import { readDoorFile, STATE_DIR, DOOR_FILE } from '../host/door-file.ts'
 
 const ACT_OPS = new Set(['click', 'type', 'select', 'press', 'scroll', 'wait', 'reload', 'navigate'])
-const VALUED = new Set(['--dir', '--ref', '--text', '--option', '--key', '--direction', '--amount', '--cursor', '--max-nodes', '--role', '--name', '--timeout-ms', '--tool', '--args', '--path'])
-const FLAGS = new Set(['--json', '--submit', '--no-clear', '--gone', '--help'])
+const VALUED = new Set(['--dir', '--ref', '--text', '--option', '--key', '--direction', '--amount', '--cursor', '--max-nodes', '--role', '--name', '--timeout-ms', '--id', '--width', '--height', '--window', '--tool', '--args', '--path'])
+const FLAGS = new Set(['--json', '--submit', '--no-clear', '--gone', '--force', '--help'])
 
 export class UsageError extends Error {}
 
@@ -30,7 +30,7 @@ export interface Invocation {
 
 const USAGE = `usage: acryl <verb> [options] [--json] [--dir <app folder>]
   brief
-  look [--cursor <n>] [--max-nodes <n>]
+  look [--cursor <n>] [--max-nodes <n>] [--window <n>]
   act click --ref <r>
   act type --ref <r> --text <t> [--submit] [--no-clear]
   act select --ref <r> --option <o>
@@ -39,7 +39,11 @@ const USAGE = `usage: acryl <verb> [options] [--json] [--dir <app folder>]
   act reload
   act navigate --path <path of the app, e.g. /demo>
   act wait (--text <t> | --role <role> [--name <n>]) [--gone] [--timeout-ms <ms>]
+  (look and every act take --window <n>: the desktop window whose page it is for; window list prints the numbers)
   plugin list | plugin add <folder> | plugin remove <name> | plugin reload
+  window list | window open [--path <p>] | window focus --id <n> | window close --id <n> [--force]
+  window resize --id <n> --width <px> --height <px>
+  menu list | menu click --path "File>New Note" [--force]
   tool list | tool call --tool <name> [--args '<json>']
   verbs`
 
@@ -82,12 +86,14 @@ export function parseInvocation(argv: readonly string[]): Invocation {
     case 'look': {
       const cursor = integer(values, '--cursor')
       const maxNodes = integer(values, '--max-nodes')
-      return make('look', { ...(cursor === undefined ? {} : { cursor }), ...(maxNodes === undefined ? {} : { maxNodes }) })
+      const window = integer(values, '--window')
+      return make('look', { ...(cursor === undefined ? {} : { cursor }), ...(maxNodes === undefined ? {} : { maxNodes }), ...(window === undefined ? {} : { window }) })
     }
     case 'act': {
       if (second === undefined || !ACT_OPS.has(second)) throw new UsageError(`act needs one of ${[...ACT_OPS].join(', ')}\n${USAGE}`)
       const amount = integer(values, '--amount')
       const timeoutMs = integer(values, '--timeout-ms')
+      const window = integer(values, '--window')
       const pick = (flag: string, key: string): Record<string, string> => (values.has(flag) ? { [key]: values.get(flag) as string } : {})
       return make('act', {
         op: second,
@@ -95,6 +101,7 @@ export function parseInvocation(argv: readonly string[]): Invocation {
         ...pick('--direction', 'direction'), ...pick('--role', 'role'), ...pick('--name', 'name'), ...pick('--path', 'path'),
         ...(amount === undefined ? {} : { amount }),
         ...(timeoutMs === undefined ? {} : { timeoutMs }),
+        ...(window === undefined ? {} : { window }),
         ...(set.has('--submit') ? { submit: true } : {}),
         ...(set.has('--no-clear') ? { clear: false } : {}),
         ...(set.has('--gone') ? { gone: true } : {}),
@@ -106,6 +113,30 @@ export function parseInvocation(argv: readonly string[]): Invocation {
       if (second === 'remove') { if (third === undefined) throw new UsageError('plugin remove needs a plugin name'); return make('plugin-remove', { name: third }) }
       throw new UsageError(`plugin needs list, add, remove or reload\n${USAGE}`)
     }
+    case 'window': {
+      const id = integer(values, '--id')
+      if (second === 'list') return make('window-list')
+      if (second === 'open') return make('window-open', values.has('--path') ? { path: values.get('--path') } : {})
+      if (second === 'focus' || second === 'close' || second === 'resize') {
+        if (id === undefined) throw new UsageError(`window ${second} needs --id <n> (window list prints the ids)`)
+        if (second === 'focus') return make('window-focus', { id })
+        if (second === 'close') return make('window-close', { id, ...(set.has('--force') ? { force: true } : {}) })
+        const width = integer(values, '--width')
+        const height = integer(values, '--height')
+        if (width === undefined || height === undefined) throw new UsageError('window resize needs --width <px> and --height <px>')
+        return make('window-resize', { id, width, height })
+      }
+      throw new UsageError(`window needs list, open, focus, close or resize\n${USAGE}`)
+    }
+    case 'menu': {
+      if (second === 'list') return make('menu-list')
+      if (second === 'click') {
+        const path = values.get('--path')
+        if (path === undefined) throw new UsageError('menu click needs --path "File>New Note" (menu list prints the paths)')
+        return make('menu-click', { path, ...(set.has('--force') ? { force: true } : {}) })
+      }
+      throw new UsageError(`menu needs list or click\n${USAGE}`)
+    }
     case 'tool': {
       if (second === 'list') return make('tool-list')
       if (second === 'call') {

package/plugins/acryl-door/src/host/channel.ts

@@ -31,6 +31,8 @@ interface Pending {
 interface Connection {
   readonly stream: PageStream
   readonly windowId: string
+  /** The desktop window the page is in, when the Electron shell tagged it. */
+  readonly shellWindow: number | undefined
   focused: boolean
   /** Order of last focus (or connection), so the most recent wins. */
   lastActive: number
@@ -52,10 +54,10 @@ export class UiChannel {
    * Register a page's stream. A stream already open for the same window is closed first, and its calls settle as `disconnected`.
    * @returns the function to call when this stream ends.
    */
-  attach(windowId: string, focused: boolean, stream: PageStream): () => void {
+  attach(windowId: string, focused: boolean, stream: PageStream, shellWindow?: number): () => void {
     const previous = this.connections.get(windowId)
     if (previous !== undefined) this.drop(previous, true)
-    const connection: Connection = { stream, windowId, focused, lastActive: ++this.clock }
+    const connection: Connection = { stream, windowId, shellWindow, focused, lastActive: ++this.clock }
     this.connections.set(windowId, connection)
     for (const waiter of [...this.attachWaiters]) waiter()
     return () => { if (this.connections.get(windowId) === connection) this.drop(connection, false) }
@@ -82,17 +84,23 @@ export class UiChannel {
   }
 
   /** The windows currently connected, most recently active first (for diagnostics and tests). */
-  windows(): readonly { windowId: string; focused: boolean }[] {
-    return this.byRecency().map(({ windowId, focused }) => ({ windowId, focused }))
+  windows(): readonly { windowId: string; focused: boolean; shellWindow?: number }[] {
+    return this.byRecency().map(({ windowId, focused, shellWindow }) => ({ windowId, focused, ...(shellWindow === undefined ? {} : { shellWindow }) }))
   }
 
   /**
    * Ask the current page to do something.
    * @throws UiControlError `no-window`, `timeout`, `aborted`, `unloaded`, `disconnected`, or whatever the page refused with.
    */
-  call(request: UiRequest, options: { signal?: AbortSignal; timeoutMs?: number } = {}): Promise<UiResult> {
+  call(request: UiRequest, options: { signal?: AbortSignal; timeoutMs?: number; window?: number } = {}): Promise<UiResult> {
     if (this.closed) return Promise.reject(new UiControlError('unloaded', 'the door was unloaded'))
-    const target = this.byRecency()[0]
+    const ordered = this.byRecency()
+    // `window` is the number `window list` prints: that desktop window's page, not the one used last.
+    const target = options.window === undefined ? ordered[0] : ordered.find(connection => connection.shellWindow === options.window)
+    if (target === undefined && options.window !== undefined) {
+      const known = ordered.flatMap(connection => (connection.shellWindow === undefined ? [] : [String(connection.shellWindow)]))
+      return Promise.reject(new UiControlError('no-window', `no page of window ${String(options.window)} is connected to the door${known.length === 0 ? ' (no desktop window has a page connected)' : `; windows with a page: ${known.join(', ')}`}; window list prints the windows`))
+    }
     if (target === undefined) return Promise.reject(new UiControlError('no-window', 'no page of the app is open to control'))
     const signal = options.signal
     if (signal?.aborted === true) return Promise.reject(new UiControlError('aborted', 'the call was cancelled'))

package/plugins/acryl-door/src/host/chat-tools.ts

@@ -20,6 +20,8 @@ export function registerChatTools(tools: ToolsPort, door: Door): () => void {
     for (const verb of VERBS) {
       removers.push(tools.register(chatToolName(verb), {
         description: VERB_SPECS[verb].description,
+        // The model is told which fields the verb takes (an `act` needs its `op`), the same schema MCP lists.
+        parameters: VERB_SPECS[verb].arguments as unknown as Readonly<Record<string, unknown>>,
         run: async (input: unknown) => {
           try {
             return (await door.run(verb, input ?? {}, running.signal)).text

package/plugins/acryl-door/src/host/door.ts

@@ -9,10 +9,12 @@ import { isAbsolute, relative, resolve } from 'node:path'
 import { parseUiRequest, UiControlError, type AuditEntry, type UiActionResult, type UiRequest, type UiResult, type UiSnapshot } from '../page/protocol.ts'
 import { renderSnapshot } from '../page/snapshot-text.ts'
 import type { AuditLog } from './audit.ts'
+import { ShellError, parseShellRequest, type ShellErrorCode, type ShellOp, type ShellRequest, type ShellResult } from '../shell/protocol.ts'
 import type { UiChannel } from './channel.ts'
+import { NO_DESKTOP, type ShellChannel } from './shell.ts'
 import { VERB_SPECS, VERBS } from './verbs.ts'
 
-export type DoorErrorCode = 'invalid' | 'unknown-verb' | 'unavailable' | 'not-exposed' | 'outside-app' | 'failed'
+export type DoorErrorCode = 'invalid' | 'unknown-verb' | 'unavailable' | 'not-exposed' | 'outside-app' | 'failed' | ShellErrorCode
 
 export class DoorError extends Error {
   readonly code: DoorErrorCode
@@ -35,13 +37,15 @@ export interface ExtensionsPort {
 /** The slice of acrylblends' `tools` registry (the `agent` plugin's) the tool verbs use, and where the built-in chat finds the verbs. */
 export interface ToolsPort {
   /** @returns the function that removes the tool. @throws when the name is taken. */
-  register(name: string, tool: { readonly description: string; run(input: unknown): unknown }): () => void
+  register(name: string, tool: { readonly description: string; readonly parameters?: Readonly<Record<string, unknown>>; run(input: unknown): unknown }): () => void
   list(): ReadonlyArray<{ readonly name: string; readonly description: string }>
   call(name: string, input: unknown): Promise<unknown>
 }
 
 export interface DoorDeps {
   readonly channel: UiChannel
+  /** The desktop shell (the Electron main process of `npm run desktop`), when the app can have one. */
+  readonly shell?: ShellChannel
   readonly audit: AuditLog
   /** The app's name, folder and, when it listens, its address (what `brief` prints so an agent can curl the running app). */
   readonly app: { readonly name: string; readonly root: string; readonly url?: string | undefined }
@@ -62,6 +66,17 @@ export interface VerbAnswer {
   readonly text: string
 }
 
+/** A shell answer as text an agent reads: windows and menu items one to a line. */
+function renderShell(result: ShellResult): string {
+  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', 'CLAUDE.md', '.agents/skills', '.claude/skills', 'docs', 'plugins']
 
@@ -101,6 +116,8 @@ export class Door {
         return { value: offered, text: offered.length === 0 ? 'no app tools are offered through the door (tools.expose is empty)' : offered.map(tool => `${tool.name}: ${tool.description}`).join('\n') }
       }
       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(', ')}`)
     }
   }
@@ -130,25 +147,93 @@ export class Door {
   }
 
   look(input: Record<string, unknown>, signal: AbortSignal): Promise<UiSnapshot> {
-    const request = this.parse({ ...input, op: 'snapshot' })
-    return this.callPage('look', request, signal) as Promise<UiSnapshot>
+    const { window, rest } = this.windowOf(input)
+    const request = this.parse({ ...rest, op: 'snapshot' })
+    return this.callPage('look', request, signal, window) as Promise<UiSnapshot>
   }
 
   async act(input: Record<string, unknown>, signal: AbortSignal): Promise<UiActionResult> {
     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) as UiActionResult
+    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) as UiActionResult
     // The page is replaced: wait for the new one to connect, so the next look sees it. The page may drop before it has answered; that is the reload working.
     const back = this.deps.channel.expectAttach(this.deps.pageBackMs ?? PAGE_BACK_MS)
     let answer: UiActionResult
     try {
-      answer = await this.callPage(`act ${request.op}`, request, signal) as UiActionResult
+      answer = await this.callPage(`act ${request.op}`, request, signal, window) as UiActionResult
     } catch (cause) {
       if (!(cause instanceof UiControlError && cause.code === 'disconnected')) { void back; throw cause }
       answer = { ok: true, 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?`)
-    return { ...answer, detail: `${answer.detail ?? 'done'}; the page is back: look again` }
+    const landed = request.op === 'navigate' ? await this.statusAt(request.path) : undefined
+    return { ...answer, detail: `${answer.detail ?? 'done'}${landed === undefined ? '' : `; ${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.
+   */
+  private async statusAt(path: string): Promise<string | undefined> {
+    const base = this.deps.app.url
+    if (base === undefined) return undefined
+    try {
+      const response = await fetch(new URL(path, base), { headers: { accept: 'text/html' }, signal: AbortSignal.timeout(3000) })
+      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 undefined
+    }
+  }
+
+  /**
+   * 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).
+   */
+  private async desktop(verb: ShellOp, input: Record<string, unknown>, signal: AbortSignal): Promise<VerbAnswer> {
+    const shell = this.deps.shell
+    let request: ShellRequest
+    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 : undefined
+    const record = (outcome: AuditEntry['outcome'], detail?: string, windowOf?: number): void => {
+      const id = windowOf ?? windowId
+      this.deps.audit.record({
+        at: new Date().toISOString(), tool: verb,
+        ...(request.op === 'menu-click' ? { target: { role: 'menuitem', name: request.path } } : {}),
+        ...(id === undefined ? {} : { window: id }),
+        outcome, ...(detail === undefined ? {} : { detail }), approval: 'token',
+      })
+    }
+    try {
+      if (shell === undefined || !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 }) as Extract<ShellResult, { windows: unknown }>
+        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 })
+      const openedId = 'id' in result ? result.id : undefined
+      record('ok', undefined, openedId)
+      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. */
+  private windowOf(input: Record<string, unknown>): { window: number | undefined; rest: Record<string, unknown> } {
+    const { window, ...rest } = input
+    if (window === undefined) return { window: undefined, 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 }
   }
 
   private parse(input: Record<string, unknown>): UiRequest {
@@ -160,17 +245,17 @@ export class Door {
   }
 
   /** Run one call on the page and record it. The audit holds which control was touched and how it ended, never what was typed. */
-  private async callPage(verb: string, request: UiRequest, signal: AbortSignal): Promise<UiResult> {
+  private async callPage(verb: string, request: UiRequest, signal: AbortSignal, window?: number): Promise<UiResult> {
     const approval: AuditEntry['approval'] = 'token'
     try {
-      const value = await this.deps.channel.call(request, { signal, ...(request.op === 'wait' ? { timeoutMs: (request.timeoutMs ?? 3000) + 5000 } : {}) })
+      const value = await this.deps.channel.call(request, { signal, ...(window === undefined ? {} : { window }), ...(request.op === 'wait' ? { timeoutMs: (request.timeoutMs ?? 3000) + 5000 } : {}) })
       const target = 'target' in value ? value.target : undefined
-      this.deps.audit.record({ at: new Date().toISOString(), tool: verb, ...(target === undefined ? {} : { target }), outcome: 'ok', approval })
+      this.deps.audit.record({ at: new Date().toISOString(), tool: verb, ...(target === undefined ? {} : { target }), ...(window === undefined ? {} : { window }), outcome: 'ok', approval })
       return value
     } catch (cause) {
       const code = cause instanceof UiControlError ? cause.code : 'failed'
       const refused = cause instanceof UiControlError && ['protected', 'sensitive', 'killed', 'invalid', 'stale-ref', 'unknown-ref', 'not-actionable'].includes(cause.code)
-      this.deps.audit.record({ at: new Date().toISOString(), tool: verb, outcome: refused ? 'refused' : 'failed', detail: code, approval })
+      this.deps.audit.record({ at: new Date().toISOString(), tool: verb, ...(window === undefined ? {} : { window }), outcome: refused ? 'refused' : 'failed', detail: code, approval })
       throw cause
     }
   }

package/plugins/acryl-door/src/host/page-routes.ts

@@ -32,6 +32,8 @@ export function pageChannelRoutes(channel: UiChannel, options: PageRoutesOptions
       const windowId = c.req.query('window')
       if (windowId === undefined || !WINDOW_ID.test(windowId)) return c.json(error('a window id is required'), 400)
       const focused = c.req.query('focused') === '1'
+      const shellQuery = Number(c.req.query('shell'))
+      const shellWindow = Number.isSafeInteger(shellQuery) && shellQuery > 0 ? shellQuery : undefined
       const signal = c.req.raw.signal
       return streamSSE(c, async (stream) => {
         let end = (): void => {}
@@ -41,7 +43,7 @@ export function pageChannelRoutes(channel: UiChannel, options: PageRoutesOptions
         const write = (event: string, data: string): void => {
           stream.writeSSE({ event, data }).catch(end)
         }
-        const detach = channel.attach(windowId, focused, { send: (data) => { write('call', data) }, close: end })
+        const detach = channel.attach(windowId, focused, { send: (data) => { write('call', data) }, close: end }, shellWindow)
         const beat = setInterval(() => { write('ping', '') }, heartbeatMs)
         try {
           write('ready', '')

package/plugins/acryl-door/src/host/shell.ts

@@ -0,0 +1,147 @@
+/**
+ * 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.
+ */
+
+import { Acryl } from 'acryl-router'
+import { streamSSE } from 'acryl-router/helpers'
+import { parseShellAnswer, ShellError, shellErrorCode, type ShellCall, type ShellRequest, type ShellResult } from '../shell/protocol.ts'
+import { error, INVALID_JSON, jsonBody, operatorOnly, readJson } from './http.ts'
+import type { PageStream } from './channel.ts'
+
+const CALL_TIMEOUT_MS = 10_000
+/** What a verb says when no desktop shell is attached: one line a model can act on. */
+export const NO_DESKTOP = 'no desktop window is attached; run npm run desktop'
+
+interface Pending {
+  readonly resolve: (value: ShellResult) => void
+  readonly reject: (cause: ShellError) => void
+  readonly timer: NodeJS.Timeout
+  readonly cleanup: () => void
+}
+
+export class ShellChannel {
+  private current: { readonly stream: PageStream } | undefined
+  private readonly pending = new Map<number, Pending>()
+  private nextId = 1
+  private closed = false
+  private readonly attachWaiters = new Set<() => void>()
+
+  get connected(): boolean {
+    return this.current !== undefined
+  }
+
+  /** @returns the function to call when this stream ends. */
+  attach(stream: PageStream): () => void {
+    const previous = this.current
+    const connection = { stream }
+    this.current = connection
+    if (previous !== undefined) {
+      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 = undefined
+      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: number): Promise<boolean> {
+    if (this.current !== undefined) return Promise.resolve(true)
+    return new Promise((resolve) => {
+      const done = (value: boolean): void => { clearTimeout(timer); this.attachWaiters.delete(waiter); resolve(value) }
+      const waiter = (): void => { done(true) }
+      const timer = setTimeout(() => { done(false) }, timeoutMs)
+      this.attachWaiters.add(waiter)
+    })
+  }
+
+  receive(body: unknown): void {
+    const answer = parseShellAnswer(body)
+    if (answer === null) return
+    if (answer.t === 'result') this.settle(answer.id, answer.value)
+    else this.settle(answer.id, undefined, new ShellError(shellErrorCode(answer.code), answer.message))
+  }
+
+  /** @throws ShellError `no-desktop` when no shell is attached, else what the shell refused with. */
+  call(request: ShellRequest, options: { signal?: AbortSignal; timeoutMs?: number } = {}): Promise<ShellResult> {
+    if (this.closed) return Promise.reject(new ShellError('unloaded', 'the door was unloaded'))
+    const target = this.current
+    if (target === undefined) 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<ShellResult>((resolve, reject) => {
+      const timer = setTimeout(() => { this.settle(id, undefined, new ShellError('timeout', 'the desktop shell did not answer in time')) }, options.timeoutMs ?? CALL_TIMEOUT_MS)
+      const onAbort = (): void => { this.settle(id, undefined, 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 } satisfies ShellCall))
+      } catch {
+        this.settle(id, undefined, new ShellError('disconnected', 'the desktop shell could not be reached'))
+      }
+    })
+  }
+
+  close(): void {
+    this.closed = true
+    this.failAll(new ShellError('unloaded', 'the door was unloaded'))
+    this.current?.stream.close()
+    this.current = undefined
+  }
+
+  private failAll(failure: ShellError): void {
+    for (const id of [...this.pending.keys()]) this.settle(id, undefined, failure)
+  }
+
+  private settle(id: number, value: ShellResult | undefined, failure?: ShellError): void {
+    const entry = this.pending.get(id)
+    if (entry === undefined) return
+    this.pending.delete(id)
+    clearTimeout(entry.timer)
+    entry.cleanup()
+    if (failure !== undefined) entry.reject(failure)
+    else entry.resolve(value as ShellResult)
+  }
+}
+
+/** How often a `ping` is written, so the shell knows a silent stream died and reconnects. */
+export const SHELL_HEARTBEAT_MS = 15_000
+
+/** `GET <prefix>/shell/events` is the shell's stream and `POST <prefix>/shell/answer` carries its answers: both need this run's secret. */
+export function shellRoutes(prefix: string, secret: string, channel: ShellChannel, heartbeatMs = SHELL_HEARTBEAT_MS): Acryl {
+  return new Acryl()
+    .get(`${prefix}/shell/events`, operatorOnly(secret), (c) => {
+      const signal = c.req.raw.signal
+      return streamSSE(c, async (stream) => {
+        let end = (): void => {}
+        const ended = new Promise<void>((resolve) => { end = resolve })
+        stream.onAbort(end)
+        signal.addEventListener('abort', end, { once: true })
+        const write = (event: string, data: string): void => {
+          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 })
+    })
+}

package/plugins/acryl-door/src/host/shim.ts

@@ -8,7 +8,7 @@
  */
 
 import { spawnSync } from 'node:child_process'
-import { chmodSync, mkdirSync, renameSync, writeFileSync } from 'node:fs'
+import { chmodSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
 import { ensureStateDir } from './door-file.ts'
 
@@ -70,11 +70,47 @@ export function windowsShim(root: string, target: ShimTarget): string {
   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${env}${words} %*\r\n`
 }
 
-function writeAtomically(file: string, content: string, mode: number): void {
+/** 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 = new Set(['EPERM', 'EBUSY', 'EACCES'])
+
+export interface ShimFs {
+  readonly rename: (from: string, to: string) => void
+  readonly pause: (ms: number) => void
+}
+
+const realFs: ShimFs = {
+  rename: renameSync,
+  // A synchronous sleep: the door writes the shims while it starts, and the wait is a few milliseconds at most.
+  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.
+ */
+export function writeAtomically(file: string, content: string, mode: number, fs: ShimFs = realFs): void {
+  try {
+    if (readFileSync(file, 'utf8') === content) return
+  } catch {
+    // Not there yet, or unreadable: write it.
+  }
   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 as NodeJS.ErrnoException).code
+      if (code === undefined || !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. */