acrylblends 1.0.5 → 1.0.6

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

@@ -6,7 +6,7 @@
 import { MAX_SNAPSHOT_NODES, MAX_WAIT_MS } from '../page/protocol.ts'
 
 /** Every verb, in the order `brief` lists them. */
-export const VERBS = ['brief', 'look', 'act', 'plugin-list', 'plugin-add', 'plugin-remove', 'plugin-reload', 'tool-list', 'tool-call'] as const
+export const VERBS = ['brief', 'look', 'act', 'plugin-list', 'plugin-add', 'plugin-remove', 'plugin-reload', 'tool-list', 'tool-call', 'window-list', 'window-open', 'window-focus', 'window-close', 'window-resize', 'menu-list', 'menu-click'] as const
 export type Verb = (typeof VERBS)[number]
 
 /** The JSON Schema of a verb's arguments, as MCP lists it. */
@@ -35,13 +35,14 @@ export const VERB_SPECS: Readonly<Record<Verb, VerbSpec>> = {
     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',
       properties: {
         cursor: { type: 'integer', minimum: 0, description: 'where the previous part ended' },
         maxNodes: { 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,
     },
@@ -66,6 +67,7 @@ export const VERB_SPECS: Readonly<Record<Verb, VerbSpec>> = {
         name: { type: 'string', description: 'wait: its name' },
         gone: { type: 'boolean', description: 'wait: until it is gone instead' },
         timeoutMs: { 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'],
       additionalProperties: false,
@@ -101,6 +103,41 @@ export const VERB_SPECS: Readonly<Record<Verb, VerbSpec>> = {
     description: 'Run one of the app tools that tool-list names.',
     arguments: { type: 'object', properties: { tool: { type: 'string' }, args: { description: 'the tool\'s input' } }, 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: 10_000 }, height: { type: 'integer', minimum: 200, maximum: 10_000 } }, 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. */

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

@@ -23,6 +23,7 @@ import { DOOR_PREFIX, privateApi } from './host/http.ts'
 import { mcpRoutes } from './host/mcp-routes.ts'
 import { operatorRoutes } from './host/operator-routes.ts'
 import { pageChannelRoutes } from './host/page-routes.ts'
+import { ShellChannel, shellRoutes } from './host/shell.ts'
 import { realNode, writeShims, type ShimTarget } from './host/shim.ts'
 
 /** Stable Cordis plugin name, equal to the package name and the Loader row id. */
@@ -113,9 +114,11 @@ export function apply(ctx: Context, rawConfig: Config = {}): void {
   }
   const secret = newSecret()
   const channel = new UiChannel()
+  const shell = new ShellChannel()
   const audit = new AuditLog(auditPath(stateDir(app.root)))
   const door = new Door({
     channel,
+    shell,
     audit,
     app: { name: app.name, root: app.root, url: loopbackUrl(server.url) },
     extensions: () => ctx.get('extensions') as unknown as ExtensionsPort | undefined,
@@ -124,6 +127,7 @@ export function apply(ctx: Context, rawConfig: Config = {}): void {
     reloadOnChange: config.reloadOnChange !== false,
   })
   ctx.effect(() => () => { channel.close() }, 'acryl-door: page channel')
+  ctx.effect(() => () => { shell.close() }, 'acryl-door: desktop shell channel')
   // One script tag for the page (`page.js`): it imports the module tree served below it.
   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' }))
@@ -154,6 +158,7 @@ export function apply(ctx: Context, rawConfig: Config = {}): void {
     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),
   ))
@@ -164,7 +169,8 @@ export function apply(ctx: Context, rawConfig: Config = {}): void {
   ctx.effect(function* () {
     yield ctx.reflect.provide('door', door)
     writeDoorFile(app.root, loopbackUrl(server.url), secret)
-    writeShims(app.root, shimTarget())
+    // A shim that cannot be replaced (Windows, held open by a running `acryl`) leaves the old one in place; it must not stop the app from starting.
+    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')
 }

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

@@ -26,6 +26,8 @@ const BACKOFF_MAX_MS = 10_000
 
 export interface PageChannelOptions {
   readonly windowId: string
+  /** The desktop window this page is in (`AcrylWindow/<n>` in the user agent, set by the Electron shell), so the Host can drive it by the number `window list` prints. */
+  readonly shellWindow?: number
   readonly focused: () => boolean
   /** Where the door's routes are, e.g. `/api/acryl-door`. */
   readonly base: string
@@ -56,7 +58,7 @@ export class PageChannel {
   connect(): void {
     if (this.disposed || this.source !== undefined) return
     const create = this.options.createSource ?? ((url: string): ChannelSource => new EventSource(url))
-    const query = `window=${encodeURIComponent(this.options.windowId)}&focused=${this.options.focused() ? '1' : '0'}`
+    const query = `window=${encodeURIComponent(this.options.windowId)}&focused=${this.options.focused() ? '1' : '0'}${this.options.shellWindow === undefined ? '' : `&shell=${String(this.options.shellWindow)}`}`
     const source = create(`${this.options.base}/channel?${query}`)
     this.source = source
     this.lastHeard = this.now()

package/plugins/acryl-door/src/page/index.ts

@@ -21,7 +21,8 @@ export function startDoor(document: Document, base: string = DOOR_BASE): () => v
   const focused = (): boolean => document.visibilityState === 'visible' && document.hasFocus()
   const detachInput = clock.attach(document)
   const removeIndicator = mountIndicator(driver, document)
-  const channel = new PageChannel(driver, { windowId, focused, base })
+  const shellWindow = Number(/\bAcrylWindow\/(\d{1,9})\b/u.exec(view.navigator?.userAgent ?? '')?.[1])
+  const channel = new PageChannel(driver, { windowId, focused, base, ...(Number.isSafeInteger(shellWindow) && shellWindow > 0 ? { shellWindow } : {}) })
   const reportFocus = (): void => { channel.reportFocus(focused()) }
   view.addEventListener('focus', reportFocus)
   view.addEventListener('blur', reportFocus)

package/plugins/acryl-door/src/page/protocol.ts

@@ -212,6 +212,8 @@ export interface AuditEntry {
   readonly tool: string
   /** The control touched, when the call had one. */
   readonly target?: { readonly role: string; readonly name: string }
+  /** The desktop window the call was about (the number `window list` prints), when it had one. */
+  readonly window?: number
   readonly outcome: 'ok' | 'refused' | 'failed'
   /** The error code for a refusal or failure, or a short note for a success. */
   readonly detail?: string

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

@@ -0,0 +1,130 @@
+/**
+ * What the door and the desktop shell say to each other. The shell is the Electron main process of `npm run desktop`; it reaches the door as a page does (an event
+ * stream down, a POST up) and answers calls about the app's windows and menu. This file is plain data and checks, so the shell side can follow it without importing the door.
+ */
+
+/** The shell's operations, one per door verb (`window-list` is `acryl window list`). */
+export const SHELL_OPS = ['window-list', 'window-open', 'window-focus', 'window-close', 'window-resize', 'menu-list', 'menu-click'] as const
+export type ShellOp = (typeof SHELL_OPS)[number]
+
+export type ShellRequest =
+  | { readonly op: 'window-list' }
+  | { readonly op: 'window-open'; readonly path?: string }
+  | { readonly op: 'window-focus'; readonly id: number }
+  /** `force`: the window may be the last, and closing the last one ends the desktop app (and with it the server it started). */
+  | { readonly op: 'window-close'; readonly id: number; readonly force?: boolean }
+  | { readonly op: 'window-resize'; readonly id: number; readonly width: number; readonly height: number }
+  | { readonly op: 'menu-list' }
+  /** `force`: the item may end the desktop app (Quit, or Close Window on the last window). */
+  | { readonly op: 'menu-click'; readonly path: string; readonly force?: boolean }
+
+export interface ShellWindow {
+  /** Electron's own window id: the number `window list` prints and `--window` takes. */
+  readonly id: number
+  readonly title: string
+  /** The path (with query) the window shows, never the origin. */
+  readonly path: string
+  readonly focused: boolean
+  readonly width: number
+  readonly height: number
+}
+
+export interface ShellMenuItem {
+  /** Labels from the top of the menu, joined with `>`: `File>New Note`. */
+  readonly path: string
+  readonly label: string
+  readonly enabled: boolean
+  /** True for an item that ends the desktop app (Quit, or Close Window): `menu click` presses it only with `force`. */
+  readonly ends?: boolean
+}
+
+export type ShellResult =
+  | { readonly windows: readonly ShellWindow[] }
+  | { readonly items: readonly ShellMenuItem[] }
+  | { readonly ok: true; readonly detail: string; readonly id?: number }
+
+/** Door to shell. */
+export interface ShellCall {
+  readonly t: 'call'
+  readonly id: number
+  readonly request: ShellRequest
+}
+
+/** Shell to door. */
+export type ShellAnswer =
+  | { readonly t: 'result'; readonly id: number; readonly value: ShellResult }
+  | { readonly t: 'error'; readonly id: number; readonly code: string; readonly message: string }
+
+export type ShellErrorCode = 'invalid' | 'no-desktop' | 'no-such-window' | 'last-window' | 'no-such-menu-item' | 'disabled' | 'quits-app' | 'timeout' | 'disconnected' | 'unloaded' | 'aborted' | 'failed'
+
+export class ShellError extends Error {
+  readonly code: ShellErrorCode
+
+  constructor(code: ShellErrorCode, message: string) {
+    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: unknown): value is Record<string, unknown> => typeof value === 'object' && value !== null && !Array.isArray(value)
+
+function only(value: Record<string, unknown>, allowed: readonly string[]): void {
+  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: Record<string, unknown>): number {
+  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: Record<string, unknown>, key: 'width' | 'height'): number {
+  const number = value[key]
+  if (typeof number !== 'number' || !Number.isInteger(number) || number < 200 || number > 10_000) throw new ShellError('invalid', `${key} must be a whole number of pixels from 200 to 10000`)
+  return number
+}
+
+/** @throws ShellError `invalid`. */
+export function parseShellRequest(op: ShellOp, input: unknown): ShellRequest {
+  const value = isRecord(input) ? input : {}
+  switch (op) {
+    case 'window-list': only(value, []); return { op }
+    case 'window-open': {
+      only(value, ['path'])
+      if (value.path === undefined) 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 !== undefined && 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 !== undefined && 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. */
+export function parseShellAnswer(value: unknown): ShellAnswer | null {
+  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 as unknown as ShellResult }
+  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`). */
+export function shellErrorCode(code: string): ShellErrorCode {
+  return (['invalid', 'no-such-window', 'last-window', 'no-such-menu-item', 'disabled', 'quits-app'] as const).find(known => known === code) ?? 'failed'
+}

package/plugins/agent-panel/headless.ts

@@ -1,10 +1,11 @@
 /** The panel's own drivers, all `chat`: the app's agent, and the coding agents (`claude`, `codex`, `pi`) started headless in the app folder. */
-import { spawn, spawnSync } from 'node:child_process'
+import { type ChildProcess, spawn, spawnSync } from 'node:child_process'
 import { readFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { join } from 'node:path'
 import type { Context } from '@deepseek-ai/cordis'
 import type { ChatDriver, ChatEvent } from './drivers.ts'
+import { resolveLaunch } from './launch.ts'
 
 export type HeadlessName = 'claude' | 'codex' | 'pi'
 
@@ -58,6 +59,15 @@ export function command(
   }
 }
 
+/** Stop a program and what it started: Windows has no process groups, so the tree goes by its root (`SIGTERM` there ends only the one process). */
+function stopProgram(child: ChildProcess): void {
+  if (process.platform === 'win32' && child.pid !== undefined) {
+    spawnSync('taskkill', ['/PID', String(child.pid), '/T', '/F'], { stdio: 'ignore' })
+    return
+  }
+  child.kill('SIGTERM')
+}
+
 export function onPath(program: string): boolean {
   const found = spawnSync(process.platform === 'win32' ? 'where' : 'which', [program], {
     encoding: 'utf8',
@@ -89,7 +99,10 @@ export function availableHeadless(wanted?: readonly HeadlessName[]): HeadlessNam
   const found: HeadlessName[] = []
   for (const driver of wanted ?? (['claude', 'codex', 'pi'] as const)) {
     if (driver === 'pi' && !piHasDeepseekKey()) continue
-    if (onPath(driver)) found.push(driver)
+    if (!onPath(driver)) continue
+    // On Windows an npm-installed program is offered only when its script can be started directly: a driver that is listed must start.
+    if ('error' in resolveLaunch(driver, [])) continue
+    found.push(driver)
   }
   return found
 }
@@ -131,8 +144,13 @@ export function headlessDriver(name: HeadlessName, root: string): ChatDriver {
     kind: 'chat',
     name,
     async *start({ message, signal }) {
-      const { file, args } = command(name, message, root)
-      const child = spawn(file, args, {
+      const wanted = command(name, message, root)
+      const launch = resolveLaunch(wanted.file, wanted.args)
+      if ('error' in launch) {
+        yield { event: 'error', data: { message: launch.error } }
+        return
+      }
+      const child = spawn(launch.file, launch.args, {
         cwd: root,
         env: process.env,
         stdio: ['ignore', 'pipe', 'pipe'],
@@ -144,16 +162,19 @@ export function headlessDriver(name: HeadlessName, root: string): ChatDriver {
         queue.push(event)
         wake?.()
       }
-      signal.addEventListener('abort', () => child.kill('SIGTERM'), { once: true })
+      signal.addEventListener('abort', () => stopProgram(child), { once: true })
       child.stdout.on('data', (chunk: Buffer) =>
         push({ event: 'text', data: { text: chunk.toString() } }),
       )
       child.stderr.on('data', (chunk: Buffer) =>
         push({ event: 'tool', data: { tool: name, info: chunk.toString().slice(0, 500) } }),
       )
-      child.on('error', () => {
+      child.on('error', (cause) => {
         ended = true
-        push({ event: 'error', data: { message: `${name} could not be started` } })
+        push({
+          event: 'error',
+          data: { message: `${name} could not be started: ${cause.message}` },
+        })
       })
       child.on('exit', (code) => {
         ended = true
@@ -169,7 +190,7 @@ export function headlessDriver(name: HeadlessName, root: string): ChatDriver {
           else await new Promise<void>((resolve) => (wake = resolve))
         }
       } finally {
-        if (child.exitCode === null) child.kill('SIGTERM')
+        if (child.exitCode === null) stopProgram(child)
       }
     },
   }

package/plugins/agent-panel/launch.ts

@@ -0,0 +1,67 @@
+/**
+ * Starting a coding agent (`claude`, `codex`, `pi`) without a shell. Off Windows the program is spawned by name. On Windows an npm-installed CLI is a `.cmd` shim, which CreateProcess
+ * cannot start, and a shell would pass the person's message through cmd.exe quoting (`& | < > ^ "` would run or break). So the shim is read: npm writes the script it runs
+ * (`"%dp0%\node_modules\<package>\dist\cli.js"`), and that script is started with Node directly, as one process. A native `.exe` (the Windows installer of claude) is started as it is.
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import { win32 } from 'node:path'
+
+export interface Launch {
+  readonly file: string
+  readonly args: string[]
+}
+
+export interface LaunchDeps {
+  readonly platform?: NodeJS.Platform
+  readonly env?: NodeJS.ProcessEnv
+  readonly exists?: (path: string) => boolean
+  readonly read?: (path: string) => string
+  /** The Node that starts a shim's script (this process's). */
+  readonly execPath?: string
+}
+
+/** The script an npm `.cmd` shim runs: the quoted path after `%dp0%\`, ending in .js, .cjs or .mjs. */
+const SHIM_SCRIPT = /"%dp0%[\\/]([^"\r\n]+?\.(?:mjs|cjs|js))"/iu
+
+/**
+ * @returns how to start `program` with `args`, or a sentence saying why it cannot be started here. A program that is not found is also a sentence.
+ */
+export function resolveLaunch(
+  program: string,
+  args: readonly string[],
+  deps: LaunchDeps = {},
+): Launch | { readonly error: string } {
+  const platform = deps.platform ?? process.platform
+  if (platform !== 'win32') return { file: program, args: [...args] }
+  const env = deps.env ?? process.env
+  const exists = deps.exists ?? existsSync
+  const read = deps.read ?? ((path: string) => readFileSync(path, 'utf8'))
+  const execPath = deps.execPath ?? process.execPath
+  const folders = (env.PATH ?? env.Path ?? '').split(';').filter(Boolean)
+  for (const folder of folders) {
+    for (const extension of ['.exe', '.com', '.cmd', '.bat']) {
+      const found = win32.join(folder, `${program}${extension}`)
+      if (!exists(found)) continue
+      if (extension === '.exe' || extension === '.com') return { file: found, args: [...args] }
+      let text: string
+      try {
+        text = read(found)
+      } catch {
+        return { error: `${program} is installed as ${found} but that file cannot be read` }
+      }
+      const script = SHIM_SCRIPT.exec(text)?.[1]
+      if (script === undefined) {
+        return {
+          error: `${program} is installed as ${found}, a batch file the panel cannot start without a shell (a shell would pass the message through cmd.exe quoting). Install the native program, or an npm package that creates an npm shim`,
+        }
+      }
+      const directory = win32.dirname(found)
+      const node = win32.join(directory, 'node.exe')
+      return {
+        file: exists(node) ? node : execPath,
+        args: [win32.join(directory, script), ...args],
+      }
+    }
+  }
+  return { error: `${program} was not found on the PATH` }
+}