acrylblends 0.7.8 → 0.8.1

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

@@ -0,0 +1,195 @@
+/**
+ * The door's verbs, one implementation for every face: `brief`, `look`, `act`, `plugin list|add|remove|reload` and `tool list|call`
+ * (`verbs.ts` lists them; the operator client, MCP and the built-in chat all call these). Each verb takes plain JSON arguments,
+ * returns a typed value and a text rendering, and fails with a {@link DoorError} or a {@link UiControlError} carrying a code.
+ */
+
+import { existsSync } from 'node:fs'
+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 type { UiChannel } from './channel.ts'
+import { VERB_SPECS, VERBS } from './verbs.ts'
+
+export type DoorErrorCode = 'invalid' | 'unknown-verb' | 'unavailable' | 'not-exposed' | 'outside-app' | 'failed'
+
+export class DoorError extends Error {
+  readonly code: DoorErrorCode
+
+  constructor(code: DoorErrorCode, message: string) {
+    super(message)
+    this.code = code
+    this.name = 'DoorError'
+  }
+}
+
+/** The slice of acrylblends' `extensions` service the plugin verbs use, declared here so the door does not depend on that plugin. */
+export interface ExtensionsPort {
+  install(source: string): Promise<unknown>
+  remove(name: string): Promise<unknown>
+  reload(): Promise<unknown>
+  list(): readonly unknown[]
+}
+
+/** 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
+  list(): ReadonlyArray<{ readonly name: string; readonly description: string }>
+  call(name: string, input: unknown): Promise<unknown>
+}
+
+export interface DoorDeps {
+  readonly channel: UiChannel
+  readonly audit: AuditLog
+  /** The app's name and folder. */
+  readonly app: { readonly name: string; readonly root: string }
+  /** Read at each call: the services may come and go while the door runs. */
+  readonly extensions: () => ExtensionsPort | undefined
+  readonly tools: () => ToolsPort | undefined
+  /** The app tools the door offers; anything else is refused before it reaches the registry. */
+  readonly expose: readonly string[]
+}
+
+/** What one verb answered: the value for `--json` and programs, the text for an agent reading a terminal. */
+export interface VerbAnswer {
+  readonly value: unknown
+  readonly text: string
+}
+
+/** 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']
+
+export class Door {
+  private readonly deps: DoorDeps
+
+  constructor(deps: DoorDeps) {
+    this.deps = deps
+  }
+
+  /** Run one verb. @throws DoorError or UiControlError. */
+  async run(verb: string, args: unknown, signal: AbortSignal): Promise<VerbAnswer> {
+    const input = (typeof args === 'object' && args !== null && !Array.isArray(args) ? args : {}) as Record<string, unknown>
+    switch (verb) {
+      case 'brief': return this.brief()
+      case 'look': {
+        const snapshot = await this.look(input, signal)
+        return { value: snapshot, text: renderSnapshot(snapshot, cursor => `run look --cursor ${String(cursor)}`) }
+      }
+      case 'act': {
+        const result = await this.act(input, signal)
+        return { value: result, text: `done${result.target === undefined ? '' : `: ${result.target.role} "${result.target.name}"`}${result.detail === undefined ? '' : ` (${result.detail})`}; look again before the next act` }
+      }
+      case 'plugin-list': return this.plugin(extensions => extensions.list())
+      case 'plugin-add': return this.plugin(extensions => extensions.install(this.insideApp(input.folder)))
+      case 'plugin-remove': {
+        const name = input.name
+        if (typeof name !== 'string' || name === '') throw new DoorError('invalid', 'plugin remove needs a plugin name')
+        return this.plugin(extensions => extensions.remove(name))
+      }
+      case 'plugin-reload': return this.plugin(extensions => extensions.reload())
+      case 'tool-list': {
+        const offered = this.offeredTools()
+        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)
+      default: throw new DoorError('unknown-verb', `unknown verb ${JSON.stringify(verb)}; the verbs are ${VERBS.join(', ')}`)
+    }
+  }
+
+  brief(): VerbAnswer {
+    const { name, root } = this.deps.app
+    const read = SELF_KNOWLEDGE.filter(path => existsSync(resolve(root, path)))
+    const value = {
+      app: name,
+      root,
+      read,
+      page: this.deps.channel.connected ? 'open' : 'not open',
+      plugins: this.deps.extensions() === undefined ? 'unavailable' : 'available',
+      verbs: VERBS.map(verb => VERB_SPECS[verb].usage),
+    }
+    const text = [
+      `App ${name} in ${root}.`,
+      read.length === 0 ? 'No AGENTS.md or skill in the folder.' : `Read first: ${read.join(', ')}.`,
+      `Page: ${value.page}${value.page === 'not open' ? ' (open the app in a browser to look and act)' : ''}.`,
+      `Live plugins: ${value.plugins}.`,
+      'Verbs:',
+      ...value.verbs.map(line => `  ${line}`),
+    ].join('\n')
+    return { value, text }
+  }
+
+  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>
+  }
+
+  act(input: Record<string, unknown>, signal: AbortSignal): Promise<UiActionResult> {
+    if (input.op === 'snapshot') throw new DoorError('invalid', 'use look to see the page')
+    return this.callPage(`act ${String(input.op)}`, this.parse(input), signal) as Promise<UiActionResult>
+  }
+
+  private parse(input: Record<string, unknown>): UiRequest {
+    try {
+      return parseUiRequest(input)
+    } catch (cause) {
+      throw new DoorError('invalid', cause instanceof Error ? cause.message : 'invalid request')
+    }
+  }
+
+  /** 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> {
+    const approval: AuditEntry['approval'] = 'token'
+    try {
+      const value = await this.deps.channel.call(request, { signal, ...(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 })
+      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 })
+      throw cause
+    }
+  }
+
+  private async plugin(run: (extensions: ExtensionsPort) => unknown): Promise<VerbAnswer> {
+    const extensions = this.deps.extensions()
+    if (extensions === undefined) throw new DoorError('unavailable', 'this app has no extensions plugin, so plugins cannot be installed while it runs')
+    const value = await run(extensions)
+    return { value, text: JSON.stringify(value, null, 2) }
+  }
+
+  /** A folder named by an agent, resolved from the app folder; it must be inside the app. */
+  private insideApp(folder: unknown): string {
+    if (typeof folder !== 'string' || folder === '') throw new DoorError('invalid', 'plugin add needs a folder, e.g. plugins/pomodoro')
+    const root = this.deps.app.root
+    const full = resolve(root, folder)
+    const path = relative(root, full)
+    if (path === '' || path.startsWith('..') || isAbsolute(path)) throw new DoorError('outside-app', `${folder} is not a folder inside the app (${root})`)
+    return full
+  }
+
+  private offeredTools(): Array<{ name: string; description: string }> {
+    const tools = this.deps.tools()
+    if (tools === undefined) return []
+    const allowed = new Set(this.deps.expose)
+    return tools.list().filter(tool => allowed.has(tool.name)).map(({ name, description }) => ({ name, description }))
+  }
+
+  private async callTool(input: Record<string, unknown>): Promise<VerbAnswer> {
+    const name = input.tool
+    if (typeof name !== 'string' || name === '') throw new DoorError('invalid', 'tool call needs --tool <name>')
+    if (!this.deps.expose.includes(name)) throw new DoorError('not-exposed', `${name} is not offered through the door`)
+    const tools = this.deps.tools()
+    if (tools === undefined || !tools.list().some(tool => tool.name === name)) throw new DoorError('unavailable', `${name} is not available right now`)
+    let value: unknown
+    try {
+      value = await tools.call(name, input.args ?? {})
+    } catch (cause) {
+      throw new DoorError('failed', cause instanceof Error ? cause.message : String(cause))
+    }
+    return { value, text: typeof value === 'string' ? value : JSON.stringify(value, null, 2) }
+  }
+}

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

@@ -0,0 +1,80 @@
+/**
+ * What every door route shares (moved from `acryl-agent-control`, spec 041). Two kinds of caller reach it, each with its own guard: the
+ * app's own page (same origin, on a loopback address), and an operator on this machine (`.acryl/bin/acryl`, an agent's shell) presenting
+ * this run's secret.
+ */
+
+import { timingSafeEqual } from 'node:crypto'
+import { Acryl, type Context, type MiddlewareHandler } from '../../../acryl-router/src/index.ts'
+import { bodyLimit, loopbackAuthority, loopbackOnly, methodNotAllowed } from '../../../acryl-router/src/middleware/index.ts'
+
+/** Every door route lives below this path. */
+export const DOOR_PREFIX = '/api/acryl-door'
+
+/** The cap on a JSON request body. */
+export const MAX_BODY_BYTES = 64 * 1024
+
+export type ReportError = (operation: string, cause: unknown) => void
+
+/** The JSON body of a refusal. */
+export function error(message: string): { readonly error: string } {
+  return { error: message }
+}
+
+/** The app's own page, on a loopback address, and nothing else: another origin, another port and a script on the machine are refused. */
+export const ownPage: MiddlewareHandler = loopbackOnly({ callers: 'own-page' })
+
+/** A constant-time comparison of a `Bearer` header with the secret. */
+export function tokenMatches(header: string | undefined, secret: string): boolean {
+  const presented = header?.startsWith('Bearer ') === true ? header.slice('Bearer '.length) : ''
+  const a = Buffer.from(presented)
+  const b = Buffer.from(secret)
+  return a.length === b.length && timingSafeEqual(a, b)
+}
+
+/**
+ * Only an operator on this machine: a loopback peer addressing this server's own port (`loopbackAuthority`), presenting this run's
+ * secret. Anything else is 403 `forbidden`, which the client reads as "refused: the app restarted and the secret rotated?".
+ */
+export function operatorOnly(secret: string): MiddlewareHandler {
+  return async (c, next) => {
+    if (loopbackAuthority(c) === undefined || !tokenMatches(c.req.header('authorization'), secret)) return c.json(error('forbidden'), 403)
+    await next()
+  }
+}
+
+/** The headers every private answer carries, set after the handler so a refusal carries them too. */
+const privateHeaders: MiddlewareHandler = async (c, next) => {
+  await next()
+  c.header('cache-control', 'no-store')
+  c.header('x-content-type-options', 'nosniff')
+}
+
+/**
+ * The door's routes as one app: each part's routes, every answer with the private headers, and a known path asked with another method
+ * answered 405 with its `Allow` before any guard runs. The middleware is scoped to the prefix, so it never wraps another plugin's routes.
+ */
+export function privateApi(prefix: string, ...routes: readonly Acryl[]): Acryl {
+  const app = new Acryl()
+  app.use(`${prefix}/*`, privateHeaders, methodNotAllowed({
+    app,
+    onMethodNotAllowed: (c, allowed) => c.json(error('method not allowed'), 405, { allow: allowed.join(', ') }),
+  }))
+  for (const part of routes) app.route('/', part)
+  return app
+}
+
+/** Refuse a body over {@link MAX_BODY_BYTES} with 413 before the handler reads it. */
+export const jsonBody: MiddlewareHandler = bodyLimit({ maxSize: MAX_BODY_BYTES, onError: c => c.json(error('request body is too large'), 413) })
+
+/** Returned by {@link readJson} for a body that is not JSON. */
+export const INVALID_JSON = Symbol('invalid JSON')
+
+/** The parsed body, or {@link INVALID_JSON}. */
+export async function readJson(c: Context): Promise<unknown> {
+  try {
+    return await c.req.json<unknown>()
+  } catch {
+    return INVALID_JSON
+  }
+}

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

@@ -0,0 +1,83 @@
+/**
+ * The door over MCP: `POST <prefix>/mcp`, streamable HTTP in its request/response form (one JSON-RPC message or a batch in, its JSON
+ * answer out, 202 for notifications only; no event stream is offered). Each verb is one tool, named as the verb, with the arguments the
+ * operator client sends. The same guard as the operator's routes: loopback, this run's secret.
+ */
+
+import { Acryl } from '../../../acryl-router/src/index.ts'
+import { UiControlError } from '../page/protocol.ts'
+import type { Door } from './door.ts'
+import { DoorError } from './door.ts'
+import { INVALID_JSON, jsonBody, operatorOnly, readJson, type ReportError } from './http.ts'
+import { VERB_SPECS, VERBS, type Verb } from './verbs.ts'
+
+const SUPPORTED_PROTOCOLS = ['2025-06-18', '2025-03-26', '2024-11-05'] as const
+const SERVER_INFO = { name: 'acryl-door', version: '1' } as const
+
+interface JsonRpcRequest { readonly jsonrpc: '2.0'; readonly id?: string | number | null; readonly method: string; readonly params?: unknown }
+
+function isRequest(value: unknown): value is JsonRpcRequest {
+  return typeof value === 'object' && value !== null && (value as { jsonrpc?: unknown }).jsonrpc === '2.0' && typeof (value as { method?: unknown }).method === 'string'
+}
+
+const rpcError = (id: JsonRpcRequest['id'], code: number, message: string) => ({ jsonrpc: '2.0', id: id ?? null, error: { code, message } })
+const result = (id: JsonRpcRequest['id'], value: unknown) => ({ jsonrpc: '2.0', id: id ?? null, result: value })
+
+/** The verbs as MCP tools. */
+export function mcpTools(): Array<{ name: Verb; description: string; inputSchema: unknown }> {
+  return VERBS.map(verb => ({ name: verb, description: VERB_SPECS[verb].description, inputSchema: VERB_SPECS[verb].arguments }))
+}
+
+const isVerb = (name: unknown): name is Verb => typeof name === 'string' && (VERBS as readonly string[]).includes(name)
+
+/** One JSON-RPC message; `undefined` for a notification (no answer owed). */
+async function answer(message: JsonRpcRequest, door: Door, signal: AbortSignal): Promise<Record<string, unknown> | undefined> {
+  const isNotification = message.id === undefined
+  switch (message.method) {
+    case 'initialize': {
+      const asked = (message.params as { protocolVersion?: unknown } | undefined)?.protocolVersion
+      const protocolVersion = (SUPPORTED_PROTOCOLS as readonly unknown[]).includes(asked) ? asked : SUPPORTED_PROTOCOLS[0]
+      return result(message.id, { protocolVersion, capabilities: { tools: { listChanged: false } }, serverInfo: SERVER_INFO })
+    }
+    case 'ping':
+      return isNotification ? undefined : result(message.id, {})
+    case 'tools/list':
+      return result(message.id, { tools: mcpTools() })
+    case 'tools/call': {
+      // MCP allows extra fields on params (`_meta`, a progress token); only `name` and `arguments` mean anything here.
+      const params = typeof message.params === 'object' && message.params !== null ? message.params as Record<string, unknown> : {}
+      if (!isVerb(params.name)) return rpcError(message.id, -32602, `unknown tool ${JSON.stringify(params.name)}; the tools are ${VERBS.join(', ')}`)
+      try {
+        const verbAnswer = await door.run(params.name, params.arguments ?? {}, signal)
+        return result(message.id, { content: [{ type: 'text', text: verbAnswer.text }], structuredContent: { value: verbAnswer.value }, isError: false })
+      } catch (cause) {
+        // A verb that failed is a tool result the model reads, with the same code the operator client prints.
+        if (cause instanceof DoorError || cause instanceof UiControlError) return result(message.id, { content: [{ type: 'text', text: `${cause.code}: ${cause.message}` }], isError: true })
+        throw cause
+      }
+    }
+    default:
+      return isNotification ? undefined : rpcError(message.id, -32601, `method not found: ${message.method}`)
+  }
+}
+
+export function mcpRoutes(prefix: string, secret: string, door: Door, reportError: ReportError): Acryl {
+  return new Acryl().post(`${prefix}/mcp`, operatorOnly(secret), jsonBody, async (c) => {
+    const body = await readJson(c)
+    if (body === INVALID_JSON) return c.json(rpcError(null, -32700, 'parse error'), 400)
+    try {
+      const messages = Array.isArray(body) ? body : [body]
+      const answers: Record<string, unknown>[] = []
+      for (const message of messages) {
+        if (!isRequest(message)) { answers.push(rpcError(null, -32600, 'invalid request')); continue }
+        const response = await answer(message, door, c.req.raw.signal)
+        if (response !== undefined) answers.push(response)
+      }
+      if (answers.length === 0) return c.body(null, 202)
+      return c.json(Array.isArray(body) ? answers : (answers[0] as object))
+    } catch (cause) {
+      reportError('answer an MCP request', cause)
+      return c.json(rpcError(null, -32603, 'internal error'), 500)
+    }
+  })
+}

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

@@ -0,0 +1,38 @@
+/**
+ * The operator's routes: an agent's shell on this machine, through `.acryl/bin/acryl`. Loopback only, with this run's secret.
+ *
+ * `POST <prefix>/call` takes `{ verb, args }` and answers {@link CallResponse}; `GET <prefix>/verbs` lists the verbs. A caller that goes
+ * away aborts its call through the request's signal.
+ */
+
+import { Acryl } from '../../../acryl-router/src/index.ts'
+import { UiControlError } from '../page/protocol.ts'
+import { Door, DoorError } from './door.ts'
+import { error, INVALID_JSON, jsonBody, operatorOnly, readJson, type ReportError } from './http.ts'
+import { VERBS } from './verbs.ts'
+
+export type CallResponse =
+  | { readonly ok: true; readonly value: unknown; readonly text: string }
+  | { readonly ok: false; readonly code: string; readonly message: string }
+
+export function operatorRoutes(prefix: string, secret: string, door: Door, reportError: ReportError): Acryl {
+  return new Acryl()
+    .get(`${prefix}/verbs`, operatorOnly(secret), c => c.json({ verbs: VERBS }))
+    .post(`${prefix}/call`, operatorOnly(secret), jsonBody, async (c) => {
+      const body = await readJson(c)
+      if (body === INVALID_JSON || typeof body !== 'object' || body === null || typeof (body as { verb?: unknown }).verb !== 'string') {
+        return c.json({ ok: false, code: 'invalid', message: 'the body is { verb, args }' } satisfies CallResponse, 400)
+      }
+      const { verb, args } = body as { verb: string; args?: unknown }
+      try {
+        const answer = await door.run(verb, args, c.req.raw.signal)
+        return c.json({ ok: true, value: answer.value, text: answer.text } satisfies CallResponse)
+      } catch (cause) {
+        if (cause instanceof UiControlError || cause instanceof DoorError) {
+          return c.json({ ok: false, code: cause.code, message: cause.message } satisfies CallResponse, cause.code === 'invalid' || cause.code === 'unknown-verb' ? 400 : 200)
+        }
+        reportError(`run the door verb ${verb}`, cause)
+        return c.json(error('the verb could not be run'), 500)
+      }
+    })
+}

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

@@ -0,0 +1,65 @@
+/**
+ * The page channel on the router: an event stream down to the page and POST up, so it needs no WebSocket upgrade on any adapter.
+ *
+ * `GET <prefix>/channel?window=<id>&focused=0|1` is the page's stream. The Host writes each call as `event: call` and a `ping` every
+ * heartbeat, so a page that hears nothing for a while knows the stream died and reconnects. `POST <prefix>/channel/answer` carries
+ * `{ window, message }` (a result, an error or a focus change). Both are for the app's own page only (same origin, loopback).
+ */
+
+import { Acryl } from '../../../acryl-router/src/index.ts'
+import { streamSSE } from '../../../acryl-router/src/helpers/index.ts'
+import { loopbackOnly } from '../../../acryl-router/src/middleware/index.ts'
+import { parseChannelToHost, WINDOW_ID } from '../page/protocol.ts'
+import type { UiChannel } from './channel.ts'
+import { error, INVALID_JSON, jsonBody, ownPage, readJson } from './http.ts'
+
+/** How often the Host writes a `ping`; the page gives up on a stream that is silent for three of these. */
+export const HEARTBEAT_MS = 15_000
+
+export interface PageRoutesOptions {
+  /** Where the channel lives, e.g. `/api/acryl-door`. */
+  readonly prefix: string
+  readonly heartbeatMs?: number
+  /** The only hostnames the page may be served from (default: every loopback name), e.g. `['127.0.0.1']` for a Host that serves only that. */
+  readonly hostnames?: readonly string[]
+}
+
+export function pageChannelRoutes(channel: UiChannel, options: PageRoutesOptions): Acryl {
+  const heartbeatMs = options.heartbeatMs ?? HEARTBEAT_MS
+  const page = options.hostnames === undefined ? ownPage : loopbackOnly({ callers: 'own-page', hostnames: options.hostnames })
+  return new Acryl()
+    .get(`${options.prefix}/channel`, page, (c) => {
+      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 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(windowId, focused, { 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(`${options.prefix}/channel/answer`, page, 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)
+      const { window: windowId, message } = body as { window?: unknown; message?: unknown }
+      const parsed = parseChannelToHost(message)
+      if (typeof windowId !== 'string' || !WINDOW_ID.test(windowId) || parsed === null) return c.json(error('invalid message'), 400)
+      channel.receive(windowId, parsed)
+      return c.body(null, 204)
+    })
+}

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

@@ -0,0 +1,65 @@
+/**
+ * The app folder's own command (spec 049 slice 10): `<app>/.acryl/bin/acryl` (and `acryl.cmd` on Windows) runs this door's operator
+ * client against this folder only (`--dir <app>`), with the Node that runs the app. An agent working in the folder calls it by that path,
+ * so it reaches the app running from this folder and never a user's own `acryl` on PATH or another app's door.
+ *
+ * Written each time the door starts, so a moved app or a new Node is picked up. It stays when the app stops: run then, it says that no
+ * app is running in the folder (exit 3). It carries no secret; the client reads `door.json` at each call.
+ */
+
+import { chmodSync, mkdirSync, renameSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { ensureStateDir } from './door-file.ts'
+
+/** The folder of the command below the app folder's `.acryl/`. */
+export const BIN_DIR = 'bin'
+
+export interface ShimTarget {
+  /** The Node executable. */
+  readonly node: string
+  /** Node options the client needs, e.g. `--experimental-strip-types` when it runs from source on a Node that needs the flag. */
+  readonly nodeOptions: readonly string[]
+  /** The operator client's entry file. */
+  readonly client: string
+  /** True when `node` is Electron, which runs as Node only with `ELECTRON_RUN_AS_NODE` set. */
+  readonly electron: boolean
+}
+
+/** A word for `sh`: single-quoted, with each `'` closed, escaped and reopened. */
+function shWord(value: string): string {
+  return `'${value.replaceAll('\'', '\'\\\'\'')}'`
+}
+
+/** A word for `cmd.exe`: double-quoted; `%` doubled so a batch file does not expand it. A path cannot hold `"`. */
+function cmdWord(value: string): string {
+  return `"${value.replaceAll('%', '%%')}"`
+}
+
+export function posixShim(root: string, target: ShimTarget): string {
+  const words = [target.node, ...target.nodeOptions, target.client, '--dir', root].map(shWord).join(' ')
+  const env = target.electron ? 'export ELECTRON_RUN_AS_NODE=1\n' : ''
+  return `#!/bin/sh\n# This app's door (acryl-door): reaches only the app running from this folder. Rewritten each time the app starts.\n${env}exec ${words} "$@"\n`
+}
+
+export function windowsShim(root: string, target: ShimTarget): string {
+  const words = [target.node, ...target.nodeOptions, target.client, '--dir', root].map(cmdWord).join(' ')
+  const env = target.electron ? 'set ELECTRON_RUN_AS_NODE=1\r\n' : ''
+  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 {
+  const temporary = `${file}.${String(process.pid)}.tmp`
+  writeFileSync(temporary, content, { mode })
+  if (process.platform !== 'win32') chmodSync(temporary, mode)
+  renameSync(temporary, file)
+}
+
+/** Write `.acryl/bin/acryl` and `.acryl/bin/acryl.cmd` for the app at `root`. @returns the folder they are in. */
+export function writeShims(root: string, target: ShimTarget): string {
+  const bin = join(ensureStateDir(root), BIN_DIR)
+  mkdirSync(bin, { recursive: true, mode: 0o700 })
+  if (process.platform !== 'win32') chmodSync(bin, 0o700)
+  writeAtomically(join(bin, 'acryl'), posixShim(root, target), 0o700)
+  writeAtomically(join(bin, 'acryl.cmd'), windowsShim(root, target), 0o600)
+  return bin
+}

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

@@ -0,0 +1,109 @@
+/**
+ * The one verb list (spec 049 slice 13). Every face of the door reads it: the operator client (`acryl <verb>`, its `verbs` and `brief`),
+ * MCP (`tools/list`) and the built-in chat (the `tools` registry). A verb added here is in all three, or the comparison test fails.
+ */
+
+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 type Verb = (typeof VERBS)[number]
+
+/** The JSON Schema of a verb's arguments, as MCP lists it. */
+export interface ArgumentsSchema {
+  readonly type: 'object'
+  readonly properties: Readonly<Record<string, unknown>>
+  readonly required?: readonly string[]
+  readonly additionalProperties: boolean
+}
+
+export interface VerbSpec {
+  /** The operator client's form, as `brief` prints it. */
+  readonly usage: string
+  /** What the verb does, for a model choosing a tool. */
+  readonly description: string
+  readonly arguments: ArgumentsSchema
+}
+
+const none: ArgumentsSchema = { type: 'object', properties: {}, additionalProperties: false }
+const ref = { type: 'string', description: 'a ref from the latest look, e.g. 3.12' }
+
+export const VERB_SPECS: Readonly<Record<Verb, VerbSpec>> = {
+  'brief': {
+    usage: 'brief: this summary',
+    description: 'What this app is, which files to read first, whether its page is open, and the verbs.',
+    arguments: none,
+  },
+  'look': {
+    usage: 'look [--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 },
+      },
+      additionalProperties: false,
+    },
+  },
+  'act': {
+    usage: 'act click|type|select|press|scroll|wait ...: do one thing on the page (refs from the latest look)',
+    description: 'Do one thing on the page: click, type, select, press a key, scroll, or wait for text or a control. Look again before the next act.',
+    arguments: {
+      type: 'object',
+      properties: {
+        op: { type: 'string', enum: ['click', 'type', 'select', 'press', 'scroll', 'wait'] },
+        ref,
+        text: { type: 'string', description: 'type: what to type; wait: the text to wait for' },
+        submit: { type: 'boolean', description: 'type: press Enter after' },
+        clear: { type: 'boolean', description: 'type: false keeps what the field holds' },
+        option: { type: 'string', description: 'select: the option to choose' },
+        key: { type: 'string', description: 'press: a character or Enter, Escape, Tab, ArrowDown, ...' },
+        direction: { type: 'string', enum: ['up', 'down', 'left', 'right'] },
+        amount: { type: 'number', minimum: 1, maximum: 10_000, description: 'scroll: pixels' },
+        role: { type: 'string', description: 'wait: the role to wait for' },
+        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 },
+      },
+      required: ['op'],
+      additionalProperties: false,
+    },
+  },
+  'plugin-list': {
+    usage: 'plugin list: the plugins installed while the app runs',
+    description: 'The plugins installed into the running app.',
+    arguments: none,
+  },
+  'plugin-add': {
+    usage: 'plugin add <folder>: check, install and start a plugin folder, live',
+    description: 'Check, install and start a plugin folder inside the app, without a restart.',
+    arguments: { type: 'object', properties: { folder: { type: 'string', description: 'a folder inside the app, e.g. plugins/pomodoro' } }, required: ['folder'], additionalProperties: false },
+  },
+  'plugin-remove': {
+    usage: 'plugin remove <name>: stop and remove an installed plugin',
+    description: 'Stop and remove an installed plugin.',
+    arguments: { type: 'object', properties: { name: { type: 'string' } }, required: ['name'], additionalProperties: false },
+  },
+  'plugin-reload': {
+    usage: 'plugin reload: bring every installed plugin in line with its folder',
+    description: 'Bring every installed plugin in line with its folder (after editing one).',
+    arguments: none,
+  },
+  'tool-list': {
+    usage: 'tool list: the app tools the door offers',
+    description: 'The app\'s own tools that the door offers.',
+    arguments: none,
+  },
+  'tool-call': {
+    usage: 'tool call --tool <name> [--args <json>]: run one of them',
+    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 },
+  },
+}
+
+/** A verb's name in the `tools` registry the built-in chat reads: prefixed, so it never meets an app tool's name. */
+export const chatToolName = (verb: Verb): string => `door_${verb.replaceAll('-', '_')}`
+
+/** True for a name the door itself registers in the `tools` registry. */
+export const isDoorToolName = (name: string): boolean => VERBS.some(verb => chatToolName(verb) === name)