acrylblends 1.0.4 → 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. */
@@ -94,6 +95,13 @@ function loopbackUrl(url: string): string {
   return parsed.origin
 }
 
+const escapeHtml = (text: string): string => text.replace(/[&<>"']/gu, char => `&#${char.charCodeAt(0)};`)
+
+/** The page of a path the app does not serve, development only: what is missing, a way back, and the door's script. */
+export function notFoundPage(path: string, scriptTag: string): string {
+  return `<!doctype html><html lang="en"><head><meta charset="utf-8"><title>404 Not Found</title></head><body><main><h1>404 Not Found</h1><p>This app has no page at <code>${escapeHtml(path)}</code>.</p><p><a href="/">Back to the app</a></p></main>${scriptTag}</body></html>`
+}
+
 export function apply(ctx: Context, rawConfig: Config = {}): void {
   const config = Config(rawConfig)
   // Development only: nothing is started, mounted or written in production, or when switched off.
@@ -106,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,
@@ -117,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' }))
@@ -124,9 +135,15 @@ export function apply(ctx: Context, rawConfig: Config = {}): void {
   // The page script on every HTML page the app answers, whenever its plugin was mounted (the pages of a plugin that loaded at boot, before this one, included): a page an agent writes
   // can be looked at and driven without anyone adding the tag. A page that already carries it (the templates' own pages) is left as it is. Development only, like the rest of the door.
   const tag = `<script type="module" src="${DOOR_PREFIX}/page.js"></script>`
-  const addScript = async (c: { res: Response }, next: () => Promise<void>): Promise<void> => {
+  const addScript = async (c: { res: Response; req: { path: string; header(name: string): string | undefined } }, next: () => Promise<void>): Promise<void> => {
     await next()
-    if (!(c.res.headers.get('content-type') ?? '').includes('text/html')) return
+    if (!(c.res.headers.get('content-type') ?? '').includes('text/html')) {
+      // A path the app does not serve, opened as a page: the browser would show a bare "404 Not Found" with no script, and the window would be left where nothing can look at it or
+      // act on it (an agent that mistypes a path would need a person to bring the window back). The page says what is missing, carries the script, and keeps the 404.
+      if (c.res.status === 404 && (c.req.header('accept') ?? '').includes('text/html') && !(c.res.headers.get('content-type') ?? '').includes('json'))
+        c.res = new Response(notFoundPage(c.req.path, tag), { status: 404, headers: { 'content-type': 'text/html; charset=utf-8' } })
+      return
+    }
     const html = await c.res.text()
     const headers = new Headers(c.res.headers)
     headers.delete('content-length')
@@ -141,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),
   ))
@@ -151,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/acryl-node-server/src/register.ts

@@ -7,9 +7,9 @@
  * `typescript` is loaded from the app, on the first JSX file only; the framework itself has no dependencies.
  */
 
+import { existsSync, readFileSync } from 'node:fs'
 import { registerHooks } from 'node:module'
-import { readFileSync } from 'node:fs'
-import { fileURLToPath } from 'node:url'
+import { fileURLToPath, pathToFileURL } from 'node:url'
 import { compileModule } from './transpile.ts'
 
 /** The JSX runtime the docs set up; an app's tsconfig.json (or a file's own `@jsxImportSource` pragma) chooses another. */
@@ -27,3 +27,30 @@ registerHooks({
     return { format: 'module', source, shortCircuit: true }
   },
 })
+
+/**
+ * The framework's names for a file of the app: in an app the framework plugins are source under `plugins/`, not packages, so `acrylblends`, `acrylblends/body-limit` or `acryl-router`
+ * have nowhere to resolve from. A plugin installed while the app runs gets them from the extensions plugin; a plugin that is a ROW of `blend.yaml` is imported by `src/app.ts` before
+ * any of that exists, so the same names are resolved here, in the preload every `dev`, `start` and `test` script runs. Only a name that Node cannot resolve itself, only for the
+ * app's own files (never for something in `node_modules`), and only in an app that has the framework as vendored source: the published package resolves its own names.
+ */
+const plugins = new URL('../../', import.meta.url)
+const appRoot = new URL('../', plugins).href
+const resolver = new URL('extensions/resolve.ts', plugins)
+if (existsSync(fileURLToPath(new URL('acryl-router/src/index.ts', plugins))) && existsSync(fileURLToPath(resolver))) {
+  const { routerAliases } = (await import(resolver.href)) as { routerAliases(): Record<string, string> }
+  const aliases = routerAliases()
+  registerHooks({
+    resolve(specifier, context, nextResolve) {
+      try {
+        return nextResolve(specifier, context)
+      } catch (error) {
+        const alias = aliases[specifier]
+        const parent = context.parentURL
+        if (alias !== undefined && parent?.startsWith(appRoot) && !parent.includes('/node_modules/'))
+          return nextResolve(pathToFileURL(alias).href, context)
+        throw error
+      }
+    },
+  })
+}

package/plugins/agent/model.ts

@@ -21,7 +21,12 @@ export interface ModelInput {
     readonly reasoning?: string
   }>
   /** The tools the model may call. */
-  readonly tools?: ReadonlyArray<{ readonly name: string; readonly description: string }>
+  readonly tools?: ReadonlyArray<{
+    readonly name: string
+    readonly description: string
+    /** The JSON Schema of the tool's input, when it has one. */
+    readonly parameters?: Readonly<Record<string, unknown>>
+  }>
   /** Aborts when the run is cancelled: a provider that can stop its request passes this on. */
   readonly signal?: AbortSignal
 }

package/plugins/agent/tools.ts

@@ -3,6 +3,8 @@ import type { Context } from '@deepseek-ai/cordis'
 /** One tool: what it does (for the model) and how to run it. */
 export interface Tool {
   readonly description: string
+  /** The JSON Schema of the input (an object schema), sent to a real model so it knows which fields the tool takes. A tool without one takes any object. */
+  readonly parameters?: Readonly<Record<string, unknown>>
   /** `options.signal` aborts when the run is cancelled; a tool that can stop its work listens to it. */
   run(input: unknown, options?: { signal?: AbortSignal }): unknown | Promise<unknown>
 }
@@ -11,7 +13,11 @@ export interface Tool {
 export interface Tools {
   /** Register a tool. Returns the function that removes it. */
   register(name: string, tool: Tool): () => void
-  list(): Array<{ name: string; description: string }>
+  list(): Array<{
+    name: string
+    description: string
+    parameters?: Readonly<Record<string, unknown>>
+  }>
   call(name: string, input: unknown, options?: { signal?: AbortSignal }): Promise<unknown>
 }
 
@@ -31,7 +37,11 @@ export function tools(ctx: Context) {
       return () => void table.delete(name)
     },
     list: () =>
-      [...table.entries()].map(([name, tool]) => ({ name, description: tool.description })),
+      [...table.entries()].map(([name, tool]) => ({
+        name,
+        description: tool.description,
+        ...(tool.parameters === undefined ? {} : { parameters: tool.parameters }),
+      })),
     async call(name, input, options) {
       const tool = table.get(name)
       if (!tool) throw new Error(`unknown tool "${name}"`)

package/plugins/agent-panel/client/describe.ts

@@ -0,0 +1,44 @@
+// One line for a tool event of the panel's conversation: what the tool is doing, not only its name. A coding agent started in the folder reports its own log (`{ tool: 'codex', info }`):
+// its bookkeeping is dropped and its command or sentence is kept. The app's own agent reports a call (`{ tool, input, result | error }`): the name and a short form of the arguments.
+
+const MAX = 160
+
+const clip = (text: string): string => (text.length > MAX ? `${text.slice(0, MAX - 1)}…` : text)
+
+/** A shell command as the agent's log writes it: `/bin/zsh -lc 'npm test' in /path/to/app` becomes `npm test`. */
+function commandOf(line: string): string {
+  const withoutCwd = line.replace(/ in \/\S+\s*$/u, '')
+  const wrapped = /^(?:\/\S*\/)?(?:ba|z|da)?sh -l?c (['"])([\s\S]*)\1$/u.exec(withoutCwd.trim())
+  return wrapped?.[2] ?? withoutCwd.trim()
+}
+
+/** @returns the line to show, or `undefined` when the event says nothing worth a line (a hook ran, a token count). */
+export function describeTool(data: Record<string, unknown>): string | undefined {
+  const tool = String(data.tool ?? '')
+  if (typeof data.info === 'string') {
+    const lines = data.info
+      .split('\n')
+      .map((line) => line.trim())
+      .filter(
+        (line) =>
+          line !== '' &&
+          !/^hook:/u.test(line) &&
+          !/^tokens used/u.test(line) &&
+          !/^[\d,]+$/u.test(line),
+      )
+    if (lines.length === 0) return undefined
+    const [first = '', second = ''] = lines
+    if (first === 'exec') return second === '' ? undefined : `${tool}: $ ${clip(commandOf(second))}`
+    // The output of a command that ran: only a failure is worth a line.
+    if (/^succeeded in /u.test(first)) return undefined
+    if (/^exited \d+/u.test(first)) return `${tool}: ${clip(first.replace(/:$/u, ''))}`
+    return `${tool}: ${clip(lines.join(' '))}`
+  }
+  const input =
+    data.input === undefined ||
+    (typeof data.input === 'object' && data.input !== null && Object.keys(data.input).length === 0)
+      ? ''
+      : ` ${clip(JSON.stringify(data.input))}`
+  const failed = data.error ? ` failed: ${clip(String(data.error))}` : ''
+  return `${tool}${input}${failed}`
+}

package/plugins/agent-panel/client/main.ts

@@ -1,5 +1,7 @@
 // The panel in the page: a button at the corner opens a side panel (a shadow root, so the app's CSS cannot touch it and it cannot touch the app's). It asks the app's
 // agent through POST /api/agent-panel/ask, shows the answer as it arrives, and reloads the page after a run that installed or removed a plugin.
+import { describeTool } from './describe.ts'
+
 const PREFIX = '/api/agent-panel'
 
 interface Session {
@@ -181,7 +183,8 @@ async function start(): Promise<void> {
           answer ??= line('')
           answer.textContent += String(data.text ?? '')
         } else if (event === 'tool') {
-          line(`${String(data.tool)}${data.error ? ` failed: ${String(data.error)}` : ''}`, 'tool')
+          const described = describeTool(data)
+          if (described !== undefined) line(described, 'tool')
         } else if (event === 'change') {
           changed = true
           line(`plugin ${String(data.extension)}: ${String(data.action)}`, 'tool')

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/index.ts

@@ -73,18 +73,30 @@ export function apply(ctx: Context, config: PanelConfig = {}): void {
     ctx.effect(() => registry.register(headlessDriver(program, root)))
 
   const tag = `<script type="module" src="${PREFIX}/panel.js"></script>`
+  const addScript = async (c: { res: Response }, next: () => Promise<void>): Promise<void> => {
+    await next()
+    if (!(c.res.headers.get('content-type') ?? '').includes('text/html')) return
+    const html = await c.res.text()
+    if (html.includes(`${PREFIX}/panel.js`)) {
+      c.res = new Response(html, c.res)
+      return
+    }
+    const headers = new Headers(c.res.headers)
+    headers.delete('content-length')
+    c.res = new Response(
+      html.includes('</body>') ? html.replace('</body>', `${tag}</body>`) : html + tag,
+      { status: c.res.status, headers },
+    )
+  }
+  // The script tag on every HTML page the app answers, whenever the plugin that serves the page was mounted (a plugin an agent built loads at boot, before this one, after a restart).
+  // An app whose router copy is older has no `wrap`: the tag is then added to the pages of the routes mounted after this plugin only.
+  const router = ctx.router as unknown as { wrap?: (middleware: typeof addScript) => unknown }
+  const wrapped = typeof router.wrap === 'function'
+  if (wrapped) router.wrap?.(addScript)
   const app = new Acryl()
-    // The script tag, on every HTML page the routes mounted after this plugin answer.
     .use('*', async (c, next) => {
-      await next()
-      if (!(c.res.headers.get('content-type') ?? '').includes('text/html')) return
-      const html = await c.res.text()
-      const headers = new Headers(c.res.headers)
-      headers.delete('content-length')
-      c.res = new Response(
-        html.includes('</body>') ? html.replace('</body>', `${tag}</body>`) : html + tag,
-        { status: c.res.status, headers },
-      )
+      if (wrapped) return next()
+      await addScript(c, next)
     })
     .get(`${PREFIX}/panel.js`, (c) =>
       c.body(`import '${PREFIX}/client/main.ts'\n`, 200, {