acrylblends 0.7.7 → 0.8.0

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

@@ -0,0 +1,142 @@
+/**
+ * The Host's side of the page channel: the connected pages of the app, and calls that go to the current one (moved from
+ * `acryl-agent-control`, spec 041).
+ *
+ * The Host cannot reach into a page, so each page opens one event stream to the Host and answers calls by POST. With several pages open,
+ * the one the user focused last is the one the agent drives. A page that reconnects with the same window id replaces its old stream.
+ */
+
+import {
+  UiControlError,
+  type ChannelToHost,
+  type ChannelToPage,
+  type UiRequest,
+  type UiResult,
+} from '../page/protocol.ts'
+
+/** The slice of a page's stream the channel needs, so tests can supply their own. */
+export interface PageStream {
+  send(data: string): void
+  close(): void
+}
+
+interface Pending {
+  readonly connection: Connection
+  readonly resolve: (value: UiResult) => void
+  readonly reject: (cause: UiControlError) => void
+  readonly timer: NodeJS.Timeout
+  readonly cleanup: () => void
+}
+
+interface Connection {
+  readonly stream: PageStream
+  readonly windowId: string
+  focused: boolean
+  /** Order of last focus (or connection), so the most recent wins. */
+  lastActive: number
+}
+
+/** How long a call may take before it is given up (a wait may take up to 10 seconds itself). */
+const DEFAULT_CALL_TIMEOUT_MS = 30_000
+
+export class UiChannel {
+  private readonly connections = new Map<string, Connection>()
+  private readonly pending = new Map<number, Pending>()
+  private nextId = 1
+  private clock = 0
+  private closed = false
+
+  /**
+   * 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 {
+    const previous = this.connections.get(windowId)
+    if (previous !== undefined) this.drop(previous, true)
+    const connection: Connection = { stream, windowId, focused, lastActive: ++this.clock }
+    this.connections.set(windowId, connection)
+    return () => { if (this.connections.get(windowId) === connection) this.drop(connection, false) }
+  }
+
+  /** A message a page sent by POST. Only the window that was asked may answer a call, so another page cannot forge a result. */
+  receive(windowId: string, message: ChannelToHost): void {
+    const connection = this.connections.get(windowId)
+    if (connection === undefined) return
+    if (message.t === 'focus') {
+      connection.focused = message.focused
+      if (message.focused) connection.lastActive = ++this.clock
+      return
+    }
+    const entry = this.pending.get(message.id)
+    if (entry === undefined || entry.connection !== connection) return
+    if (message.t === 'result') this.settle(message.id, message.value)
+    else this.settle(message.id, undefined, new UiControlError(message.code, message.message))
+  }
+
+  /** True when at least one page is connected. */
+  get connected(): boolean {
+    return this.connections.size > 0
+  }
+
+  /** 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 }))
+  }
+
+  /**
+   * 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> {
+    if (this.closed) return Promise.reject(new UiControlError('unloaded', 'the door was unloaded'))
+    const target = this.byRecency()[0]
+    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'))
+    const id = this.nextId
+    this.nextId += 1
+    return new Promise<UiResult>((resolve, reject) => {
+      const timer = setTimeout(() => { this.settle(id, undefined, new UiControlError('timeout', 'the page did not answer in time')) }, options.timeoutMs ?? DEFAULT_CALL_TIMEOUT_MS)
+      const onAbort = (): void => { this.settle(id, undefined, new UiControlError('aborted', 'the call was cancelled')) }
+      signal?.addEventListener('abort', onAbort, { once: true })
+      this.pending.set(id, { connection: target, resolve, reject, timer, cleanup: () => { signal?.removeEventListener('abort', onAbort) } })
+      const frame: ChannelToPage = { t: 'call', id, request }
+      try {
+        target.stream.send(JSON.stringify(frame))
+      } catch {
+        this.settle(id, undefined, new UiControlError('disconnected', 'the page could not be reached'))
+      }
+    })
+  }
+
+  /** Close every page's stream and settle every pending call as `unloaded`. */
+  close(): void {
+    this.closed = true
+    for (const id of [...this.pending.keys()]) this.settle(id, undefined, new UiControlError('unloaded', 'the door was unloaded'))
+    for (const connection of [...this.connections.values()]) connection.stream.close()
+    this.connections.clear()
+  }
+
+  private byRecency(): Connection[] {
+    return [...this.connections.values()].sort((a, b) => b.lastActive - a.lastActive)
+  }
+
+  /** Forget a connection; its calls in flight settle as `disconnected` at once rather than waiting for their timeout. */
+  private drop(connection: Connection, closeStream: boolean): void {
+    this.connections.delete(connection.windowId)
+    for (const [id, entry] of [...this.pending]) {
+      if (entry.connection === connection) this.settle(id, undefined, new UiControlError('disconnected', 'the page went away before it answered'))
+    }
+    if (closeStream) connection.stream.close()
+  }
+
+  private settle(id: number, value: UiResult | undefined, failure?: UiControlError): 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 if (value !== undefined) entry.resolve(value)
+  }
+}

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

@@ -0,0 +1,39 @@
+/**
+ * The door in the built-in chat: each verb registered in the app's `tools` registry (the one the chat's agent reads), as
+ * `door_<verb>`. A tool answers the verb's text, what an agent reads in a terminal; a failed verb throws with its code, as the operator
+ * client prints it.
+ */
+
+import { UiControlError } from '../page/protocol.ts'
+import { DoorError, type Door, type ToolsPort } from './door.ts'
+import { chatToolName, VERB_SPECS, VERBS } from './verbs.ts'
+
+/** Register every verb. @returns the function that removes them all; it also aborts the calls still running. */
+export function registerChatTools(tools: ToolsPort, door: Door): () => void {
+  const running = new AbortController()
+  const removers: Array<() => void> = []
+  const removeAll = (): void => {
+    running.abort()
+    for (const remove of removers.splice(0).reverse()) remove()
+  }
+  try {
+    for (const verb of VERBS) {
+      removers.push(tools.register(chatToolName(verb), {
+        description: VERB_SPECS[verb].description,
+        run: async (input: unknown) => {
+          try {
+            return (await door.run(verb, input ?? {}, running.signal)).text
+          } catch (cause) {
+            if (cause instanceof DoorError || cause instanceof UiControlError) throw new Error(`${cause.code}: ${cause.message}`, { cause })
+            throw cause
+          }
+        },
+      }))
+    }
+  } catch (cause) {
+    // A name already taken: leave nothing half registered.
+    removeAll()
+    throw cause
+  }
+  return removeAll
+}

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

@@ -0,0 +1,94 @@
+/**
+ * The door's connection file, `<app>/.acryl/door.json`: where the running app listens and this run's secret, for the operator client in
+ * the same folder. The secret is never on a command line or in an environment variable another process can read.
+ *
+ * Protection: on macOS and Linux the folder is `0700` and the file `0600`, so only the OS user who started the app can read it. On
+ * Windows file modes mean nothing; the file is protected by where it lives, the app folder in the user's profile, whose ACL gives access
+ * to that user, SYSTEM and Administrators only. The door does not widen it. The folder also carries its own `.gitignore` of `*`, so
+ * `git add -A` never stages the secret even in an app whose `.gitignore` lacks the `.acryl/` line.
+ */
+
+import { randomBytes } from 'node:crypto'
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/** The folder of the door's state below the app folder. */
+export const STATE_DIR = '.acryl'
+export const DOOR_FILE = 'door.json'
+
+export interface DoorFile {
+  readonly version: 1
+  /** The origin the operator reaches, on a loopback address. */
+  readonly url: string
+  readonly secret: string
+  /** The process that wrote it; a file whose process is gone is stale. */
+  readonly pid: number
+}
+
+export function stateDir(appRoot: string): string {
+  return join(appRoot, STATE_DIR)
+}
+
+export function doorFilePath(appRoot: string): string {
+  return join(stateDir(appRoot), DOOR_FILE)
+}
+
+/** A fresh secret for this run; a restart rotates it. */
+export function newSecret(): string {
+  return randomBytes(24).toString('hex')
+}
+
+/** The state folder, private, with its own `.gitignore`. */
+export function ensureStateDir(appRoot: string): string {
+  const dir = stateDir(appRoot)
+  mkdirSync(dir, { recursive: true, mode: 0o700 })
+  if (process.platform !== 'win32') chmodSync(dir, 0o700)
+  const ignore = join(dir, '.gitignore')
+  if (!existsSync(ignore)) writeFileSync(ignore, '# The door\'s state: this run\'s secret and the audit. Never commit it.\n*\n')
+  return dir
+}
+
+/** The connection file as written, or undefined when there is none or it does not parse. */
+export function readDoorFile(appRoot: string): DoorFile | undefined {
+  try {
+    const value = JSON.parse(readFileSync(doorFilePath(appRoot), 'utf8')) as Partial<DoorFile>
+    if (value.version === 1 && typeof value.url === 'string' && typeof value.secret === 'string' && typeof value.pid === 'number') return value as DoorFile
+  } catch {
+    // Missing or unreadable: there is no door to reach.
+  }
+  return undefined
+}
+
+/** True while the process is alive (a process of another user still counts: `EPERM`). */
+function alive(pid: number): boolean {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (cause) {
+    return (cause as NodeJS.ErrnoException).code === 'EPERM'
+  }
+}
+
+/**
+ * Write this run's connection file, replacing a stale one.
+ * @throws when another live process already serves this folder's door: two apps from one folder would race for one file.
+ */
+export function writeDoorFile(appRoot: string, url: string, secret: string): string {
+  const dir = ensureStateDir(appRoot)
+  const existing = readDoorFile(appRoot)
+  if (existing !== undefined && existing.pid !== process.pid && alive(existing.pid)) {
+    throw new Error(`acryl-door: another process (pid ${String(existing.pid)}) serves the door of ${appRoot}; stop it first`)
+  }
+  const file = doorFilePath(appRoot)
+  const temporary = join(dir, `${DOOR_FILE}.${String(process.pid)}.tmp`)
+  const content: DoorFile = { version: 1, url, secret, pid: process.pid }
+  writeFileSync(temporary, `${JSON.stringify(content)}\n`, { mode: 0o600 })
+  if (process.platform !== 'win32') chmodSync(temporary, 0o600)
+  renameSync(temporary, file)
+  return file
+}
+
+/** Remove the connection file, only when it is this run's: a newer run's file is left alone. */
+export function removeDoorFile(appRoot: string, secret: string): void {
+  if (readDoorFile(appRoot)?.secret === secret) rmSync(doorFilePath(appRoot), { force: true })
+}

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)
+    }
+  })
+}