acrylblends 1.1.0 → 1.3.0

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

@@ -73,12 +73,17 @@ function alive(pid: number): boolean {
  * 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)
+/** @throws when another live process already serves this folder's door: two apps from one folder would race for one file. */
+export function assertDoorIsFree(appRoot: string): void {
   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`)
   }
+}
+
+export function writeDoorFile(appRoot: string, url: string, secret: string): string {
+  const dir = ensureStateDir(appRoot)
+  assertDoorIsFree(appRoot)
   const file = doorFilePath(appRoot)
   const temporary = join(dir, `${DOOR_FILE}.${String(process.pid)}.tmp`)
   const content: DoorFile = { version: 1, url, secret, pid: process.pid }

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

@@ -6,6 +6,7 @@
 
 import { existsSync } from 'node:fs'
 import { isAbsolute, relative, resolve } from 'node:path'
+import { underAppBase } from '../page/base.ts'
 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'
@@ -14,7 +15,7 @@ import type { UiChannel } from './channel.ts'
 import { NO_DESKTOP, type ShellChannel } from './shell.ts'
 import { VERB_SPECS, VERBS } from './verbs.ts'
 
-export type DoorErrorCode = 'invalid' | 'unknown-verb' | 'unavailable' | 'not-exposed' | 'outside-app' | 'failed' | ShellErrorCode
+export type DoorErrorCode = 'invalid' | 'unknown-verb' | 'unavailable' | 'not-exposed' | 'outside-app' | 'failed' | 'refused' | ShellErrorCode
 
 export class DoorError extends Error {
   readonly code: DoorErrorCode
@@ -34,10 +35,45 @@ export interface ExtensionsPort {
   list(): readonly unknown[]
 }
 
+/** The slice of acrylblends' `pluginShare` service the pull verb uses. */
+export interface PluginSharePort {
+  pull(source: string): Promise<{ readonly ok: boolean; readonly action?: string; readonly reason?: string; readonly next?: string }>
+  planPublish(name: string, options?: PublishOptionsView): Promise<PublishPlanView | { readonly ok: false; readonly reason: string; readonly next: string }>
+  publish(name: string, confirmed: PublishPlanView, options?: PublishOptionsView): Promise<{ readonly ok: boolean; readonly reason?: string }>
+}
+
+/** Who a plan publishes as, and under which license; the service's defaults when absent. */
+export interface PublishOptionsView {
+  readonly owner?: string
+  readonly license?: string
+}
+
+/** A plan as the door shows it. The service owns it; the door passes it back unchanged. */
+export interface PublishPlanView {
+  readonly owner: string
+  readonly repo: string
+  readonly version: string
+  readonly visibility: string
+  readonly license: string
+  readonly createsRepository: boolean
+  readonly files: readonly string[]
+  readonly digest: string
+  readonly pullLine: string
+}
+
+/** What a plan says, for a person deciding. */
+export function renderPublishPlan(plan: PublishPlanView): string {
+  return [
+    `Publish to ${plan.owner}/${plan.repo}${plan.createsRepository ? ' (a new repository)' : ''}, ${plan.visibility}, version ${plan.version}, license ${plan.license}.`,
+    `Files: ${plan.files.join(', ')}.`,
+    `A friend gets exactly these bytes with: ${plan.pullLine}`,
+  ].join('\n')
+}
+
 /** 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; readonly parameters?: Readonly<Record<string, unknown>>; run(input: unknown): unknown }): () => void
+  register(name: string, tool: { readonly description: string; readonly parameters?: Readonly<Record<string, unknown>>; run(input: unknown, options?: { signal?: AbortSignal; page?: string }): unknown }): () => void
   list(): ReadonlyArray<{ readonly name: string; readonly description: string }>
   call(name: string, input: unknown): Promise<unknown>
 }
@@ -49,8 +85,12 @@ export interface DoorDeps {
   readonly audit: AuditLog
   /** The app's name, folder and, when it listens, its address (what `brief` prints so an agent can curl the running app). */
   readonly app: { readonly name: string; readonly root: string; readonly url?: string | undefined }
+  /** The prefix the app's pages answer under (the frame's canvas, `/app`); absent on the app's own server, at the root. */
+  readonly appBase?: string | undefined
   /** Read at each call: the services may come and go while the door runs. */
   readonly extensions: () => ExtensionsPort | undefined
+  /** Read at each call, as `extensions` is; absent where the app has no plugin-share row. */
+  readonly pluginShare?: () => PluginSharePort | undefined
   readonly tools: () => ToolsPort | undefined
   /** The app tools the door offers; anything else is refused before it reaches the registry. */
   readonly expose: readonly string[]
@@ -60,6 +100,11 @@ export interface DoorDeps {
   readonly pageBackMs?: number
 }
 
+/** Who a verb runs for: `page`, the door's id of the page a run was asked from; its look and act go to that page alone (followed into its tab), never to another one. */
+export interface VerbScope {
+  readonly page?: 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
@@ -96,20 +141,22 @@ export class Door {
   }
 
   /** Run one verb. @throws DoorError or UiControlError. */
-  async run(verb: string, args: unknown, signal: AbortSignal): Promise<VerbAnswer> {
+  async run(verb: string, args: unknown, signal: AbortSignal, scope: VerbScope = {}): 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)
+        const snapshot = await this.look(input, signal, scope)
         return { value: snapshot, text: renderSnapshot(snapshot, cursor => `run look --cursor ${String(cursor)}`) }
       }
       case 'act': {
-        const result = await this.act(input, signal)
+        const result = await this.act(input, signal, scope)
         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(), false)
       case 'plugin-add': return this.plugin(extensions => extensions.install(this.insideApp(input.folder)))
+      case 'plugin-pull': return this.pull(input.source)
+      case 'plugin-publish': return this.planPublish(input)
       case 'plugin-remove': {
         const name = input.name
         if (typeof name !== 'string' || name === '') throw new DoorError('invalid', 'plugin remove needs a plugin name')
@@ -151,30 +198,47 @@ export class Door {
     return { value, text }
   }
 
-  look(input: Record<string, unknown>, signal: AbortSignal): Promise<UiSnapshot> {
-    const { window, rest } = this.windowOf(input)
+  look(input: Record<string, unknown>, signal: AbortSignal, scope: VerbScope = {}): Promise<UiSnapshot> {
+    const { window, rest } = this.windowOf(input, scope)
     const request = this.parse({ ...rest, op: 'snapshot' })
-    return this.callPage('look', request, signal, window) as Promise<UiSnapshot>
+    return this.callPage('look', request, signal, window, scope.page) as Promise<UiSnapshot>
   }
 
-  async act(input: Record<string, unknown>, signal: AbortSignal): Promise<UiActionResult> {
+  async act(input: Record<string, unknown>, signal: AbortSignal, scope: VerbScope = {}): Promise<UiActionResult> {
     if (input.op === 'snapshot') throw new DoorError('invalid', 'use look to see the page')
-    const { window, rest } = this.windowOf(input)
+    const { window, rest } = this.windowOf(input, scope)
     const request = this.parse(rest)
-    if (request.op !== 'reload' && request.op !== 'navigate') return await this.callPage(`act ${String(input.op)}`, request, signal, window) as UiActionResult
-    // The page is replaced: wait for the new one to connect, so the next look sees it. The page may drop before it has answered; that is the reload working.
-    const back = this.deps.channel.expectNewPage(this.deps.pageBackMs ?? PAGE_BACK_MS)
+    const page = scope.page
+    // A reload or a navigate replaces the page; a click, a key or typing may (a link, a form that submits), and the page says so when it does.
+    const moves = request.op === 'reload' || request.op === 'navigate'
+    if (!moves && request.op !== 'click' && request.op !== 'press' && request.op !== 'type')
+      return await this.callPage(`act ${String(input.op)}`, request, signal, window, page) as UiActionResult
+    // Wait for the new page to connect, so the next look sees it; the wait starts before the act, or a fast page is missed. The page may drop before it has answered;
+    // that is the move working. A run's own page comes back in its own tab; no other page that happens to connect meanwhile is taken for it.
+    const backMs = this.deps.pageBackMs ?? PAGE_BACK_MS
+    const stay = new AbortController()
+    const back = page === undefined ? this.deps.channel.expectNewPage(backMs, stay.signal) : this.deps.channel.expectPageBack(page, backMs, stay.signal)
     let answer: UiActionResult
+    let left = moves
     try {
-      answer = await this.callPage(`act ${request.op}`, request, signal, window) as UiActionResult
+      answer = await this.callPage(`act ${request.op}`, request, signal, window, page) as UiActionResult
+      left ||= answer.leaving === true
     } catch (cause) {
-      if (!(cause instanceof UiControlError && cause.code === 'disconnected')) { void back; throw cause }
-      answer = { ok: true, detail: request.op === 'reload' ? 'reloading' : `going to ${request.path}` }
+      if (!(cause instanceof UiControlError && cause.code === 'disconnected')) { stay.abort(); throw cause }
+      answer = { ok: true, detail: request.op === 'reload' ? 'reloading' : request.op === 'navigate' ? `going to ${request.path}` : 'the page is going to another address' }
+      left = true
+    }
+    if (!left) {
+      stay.abort()
+      return answer
     }
     const came = await back
-    // The page that came back is the one this agent was driving: it stays the target until the person focuses another page.
-    if (came !== undefined) this.deps.channel.prefer(came)
-    if (came === undefined) throw new UiControlError('timeout', request.op === 'reload' ? 'the page did not come back after the reload' : `the page did not come back after going to ${request.path}: is there a page at that path, and does it load the door's script?`)
+    // The page that came back is the one this agent was driving: it stays the target until the person focuses another page. A run that names its page follows that page's tab instead.
+    if (came !== undefined && page === undefined) this.deps.channel.prefer(came)
+    if (came === undefined)
+      throw new UiControlError('timeout', request.op === 'reload' ? 'the page did not come back after the reload'
+        : request.op === 'navigate' ? `the page did not come back after going to ${request.path}: is there a page at that path, and does it load the door's script?`
+        : `the ${request.op} took the page to another address, and no page came back: does the page there load the door's script?`)
     const landed = request.op === 'navigate' ? await this.statusAt(request.path) : undefined
     return { ...answer, detail: `${answer.detail ?? 'done'}${landed === undefined ? '' : `; ${landed}`}; the page is back: look again` }
   }
@@ -187,7 +251,10 @@ export class Door {
     const base = this.deps.app.url
     if (base === undefined) return undefined
     try {
-      const response = await fetch(new URL(path, base), { headers: { accept: 'text/html' }, signal: AbortSignal.timeout(3000) })
+      // The app's own path, under the host prefix when the pages answer there (the frame's canvas): /board is /app/board in the canvas and /board at the
+      // root, and the app's root is the prefix itself (`/app`, where its rows mount `/`), as the page's navigation join does it.
+      const target = underAppBase(this.deps.appBase ?? '', path)
+      const response = await fetch(new URL(target, base), { headers: { accept: 'text/html' }, signal: AbortSignal.timeout(3000) })
       await response.body?.cancel()
       return response.ok ? `${response.status} at ${path}` : `${response.status} at ${path}: the app serves no page there, look at what is shown and navigate to a path it does`
     } catch {
@@ -237,9 +304,11 @@ export class Door {
   }
 
   /** `window` on look and act: the desktop window (the number `window list` prints) whose page the call is for; without it, the page used last. */
-  private windowOf(input: Record<string, unknown>): { window: number | undefined; rest: Record<string, unknown> } {
+  private windowOf(input: Record<string, unknown>, scope: VerbScope = {}): { window: number | undefined; rest: Record<string, unknown> } {
     const { window, ...rest } = input
     if (window === undefined) return { window: undefined, rest }
+    // A run that is for one page cannot be pointed at a desktop window instead.
+    if (scope.page !== undefined) throw new DoorError('invalid', 'this run drives only the page it was asked from; window does not apply')
     if (typeof window !== 'number' || !Number.isSafeInteger(window) || window < 1) throw new DoorError('invalid', 'window must be the number `window list` prints for the window')
     return { window, rest }
   }
@@ -253,10 +322,10 @@ export class Door {
   }
 
   /** Run one call on the page and record it. The audit holds which control was touched and how it ended, never what was typed. */
-  private async callPage(verb: string, request: UiRequest, signal: AbortSignal, window?: number): Promise<UiResult> {
+  private async callPage(verb: string, request: UiRequest, signal: AbortSignal, window?: number, page?: string): Promise<UiResult> {
     const approval: AuditEntry['approval'] = 'token'
     try {
-      const value = await this.deps.channel.call(request, { signal, ...(window === undefined ? {} : { window }), ...(request.op === 'wait' ? { timeoutMs: (request.timeoutMs ?? 3000) + 5000 } : {}) })
+      const value = await this.deps.channel.call(request, { signal, ...(window === undefined ? {} : { window }), ...(page === undefined ? {} : { page }), ...(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 }), ...(window === undefined ? {} : { window }), outcome: 'ok', approval })
       return value
@@ -270,7 +339,7 @@ export class Door {
 
   private async plugin(run: (extensions: ExtensionsPort) => unknown, mutates = true): 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')
+    if (extensions === undefined) throw new DoorError('unavailable', 'this door has no extensions plugin to drive. In ACRYL\'s frame none is needed: a saved change in src/ or plugins/ reloads the app by itself, so do not restart it. Elsewhere, the app has no way to install plugins while it runs')
     const value = await run(extensions)
     // The app changed under the open pages: reload them (not when the plugin was already as it should be), and answer once they are back.
     const unchanged = typeof value === 'object' && value !== null && (value as { action?: unknown }).action === 'unchanged'
@@ -278,6 +347,41 @@ export class Door {
     return { value, text: JSON.stringify(value, null, 2) }
   }
 
+  private share(): PluginSharePort {
+    const share = this.deps.pluginShare?.()
+    if (share === undefined) throw new DoorError('unavailable', 'plugin-share is not running in this app. If the app just changed it is restarting, so try again in a moment. An app made by an older version does not have it, and upgrade does not add it: run `npx acrylblends add plugin-share` and follow its README')
+    return share
+  }
+
+  /** Only a plan: no argument of any verb can publish, so an agent never says yes for a person. */
+  private async planPublish(input: Record<string, unknown>): Promise<VerbAnswer> {
+    const { name, owner, license } = input
+    if (typeof name !== 'string' || name === '') throw new DoorError('invalid', 'plugin publish needs a plugin name, e.g. plugin publish pomodoro')
+    const value = await this.share().planPublish(name, {
+      ...(typeof owner === 'string' && owner !== '' ? { owner } : {}),
+      ...(typeof license === 'string' && license !== '' ? { license } : {}),
+    })
+    if ('ok' in value) throw new DoorError('refused', `${value.reason}. ${value.next}.`)
+    return { value, text: `${renderPublishPlan(value)}\nNothing was sent. Only a person can say yes: they run \`npm run acryl -- plugin publish ${name}\` in their own terminal, or press Share in the frame. \`--license <id>\` changes the license before the yes.` }
+  }
+
+  /** The person's yes, from their own terminal. Not a verb: MCP and the chat do not have it. */
+  async publishConfirmed(name: string, confirmed: PublishPlanView, options: PublishOptionsView): Promise<unknown> {
+    const value = await this.share().publish(name, confirmed, options)
+    this.deps.audit.record({ at: new Date().toISOString(), tool: 'plugin-publish', target: { role: 'plugin', name: `${confirmed.owner}/${confirmed.repo}@${confirmed.version}` }, outcome: value.ok ? 'ok' : 'refused', approval: 'token' })
+    return value
+  }
+
+  private async pull(source: unknown): Promise<VerbAnswer> {
+    if (typeof source !== 'string' || source === '') throw new DoorError('invalid', 'plugin pull needs a source, e.g. plugin pull github:someone/pomodoro@0.1.0')
+    const value = await this.share().pull(source)
+    // A refusal is a failed command, so a script does not read it as done; it changed nothing, and the open pages stay.
+    if (!value.ok) throw new DoorError('refused', `${value.reason ?? 'the pull was refused'}. ${value.next ?? 'nothing changed'}.`)
+    // Neither did pulling what is already there change anything.
+    if (value.action !== 'unchanged' && this.deps.reloadOnChange !== false) await this.deps.channel.reloadAll()
+    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')

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

@@ -7,7 +7,7 @@
 
 import { Acryl } from 'acryl-router'
 import { UiControlError } from '../page/protocol.ts'
-import { Door, DoorError } from './door.ts'
+import { Door, DoorError, type PublishPlanView } from './door.ts'
 import { error, INVALID_JSON, jsonBody, operatorOnly, readJson, type ReportError } from './http.ts'
 import { VERBS } from './verbs.ts'
 
@@ -35,4 +35,24 @@ export function operatorRoutes(prefix: string, secret: string, door: Door, repor
         return c.json(error('the verb could not be run'), 500)
       }
     })
+    // A person's yes to a plan, from the prompt in their own terminal. Not a verb, so MCP and the chat do not offer it. An agent with this machine's
+    // secret could still reach it: the door keeps honest agents from publishing by accident, the person's account is the real boundary.
+    .post(`${prefix}/publish-confirmed`, operatorOnly(secret), jsonBody, async (c) => {
+      const body = await readJson(c)
+      const { name, confirm, owner, license } = (body === INVALID_JSON || typeof body !== 'object' || body === null ? {} : body) as { name?: unknown; confirm?: unknown; owner?: unknown; license?: unknown }
+      if (typeof name !== 'string' || typeof confirm !== 'object' || confirm === null) {
+        return c.json({ ok: false, code: 'invalid', message: 'the body is { name, confirm }' } satisfies CallResponse, 400)
+      }
+      try {
+        const value = await door.publishConfirmed(name, confirm as PublishPlanView, {
+          ...(typeof owner === 'string' ? { owner } : {}),
+          ...(typeof license === 'string' ? { license } : {}),
+        })
+        return c.json({ ok: true, value, text: JSON.stringify(value, null, 2) } satisfies CallResponse)
+      } catch (cause) {
+        if (cause instanceof DoorError) return c.json({ ok: false, code: cause.code, message: cause.message } satisfies CallResponse, 409)
+        reportError('publish a plugin', cause)
+        return c.json(error('the plugin could not be published'), 500)
+      }
+    })
 }

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

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

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

@@ -9,7 +9,7 @@
  */
 
 import { Acryl, type MiddlewareHandler } from 'acryl-router'
-import type { UpgradeWebSocket } from 'acryl-router/helpers'
+import type { UpgradeWebSocket, WSEvents } from 'acryl-router/helpers'
 import { loopbackAuthority } from 'acryl-router/middleware'
 import { parseChannelToHost, WINDOW_ID } from '../page/protocol.ts'
 import type { UiChannel } from './channel.ts'
@@ -20,7 +20,8 @@ export const SOCKET_HEARTBEAT_MS = 15_000
 
 export interface PageSocketOptions {
   readonly prefix: string
-  readonly upgrade: UpgradeWebSocket
+  /** The live upgrade helper: the route is mounted once, so the helper is read per request (a restarting host has a new one). */
+  readonly upgrade: () => UpgradeWebSocket | undefined
   readonly heartbeatMs?: number
 }
 
@@ -39,14 +40,13 @@ export const ownOrigin: MiddlewareHandler = async (c, next) => {
 
 export function pageSocketRoutes(channel: UiChannel, options: PageSocketOptions): Acryl {
   const heartbeatMs = options.heartbeatMs ?? SOCKET_HEARTBEAT_MS
-  return new Acryl().get(
-    `${options.prefix}/channel/ws`,
-    ownOrigin,
-    options.upgrade((c) => {
+  const events = (c: Parameters<MiddlewareHandler>[0]): WSEvents => {
       const windowId = c.req.query('window') as string
       const focused = c.req.query('focused') === '1'
       const shellQuery = Number(c.req.query('shell'))
       const shellWindow = Number.isSafeInteger(shellQuery) && shellQuery > 0 ? shellQuery : undefined
+      const tabQuery = c.req.query('tab')
+      const tab = tabQuery !== undefined && WINDOW_ID.test(tabQuery) ? tabQuery : undefined
       let detach: (() => void) | undefined
       let beat: NodeJS.Timeout | undefined
       return {
@@ -55,7 +55,7 @@ export function pageSocketRoutes(channel: UiChannel, options: PageSocketOptions)
             ws.send(JSON.stringify(frame))
           }
           // A call that cannot be written fails at once (`disconnected`), and a socket that is gone is dropped by its close: the door never holds a call for it.
-          detach = channel.attach(windowId, focused, { send: data => { write({ e: 'call', d: data }) }, notify: (event, data) => { write({ e: event, d: data }) }, close: () => { ws.close(1000, 'replaced') } }, shellWindow)
+          detach = channel.attach(windowId, focused, { send: data => { write({ e: 'call', d: data }) }, notify: (event, data) => { write({ e: event, d: data }) }, close: () => { ws.close(1000, 'replaced') } }, shellWindow, tab)
           write({ e: 'ready' })
           beat = setInterval(() => {
             try { write({ e: 'ping' }) } catch { /* the close event follows */ }
@@ -73,6 +73,16 @@ export function pageSocketRoutes(channel: UiChannel, options: PageSocketOptions)
           detach?.()
         },
       }
-    }, { textOnly: true }),
+  }
+  // Mounted once, ahead of the private routes: the route must keep its precedence across a host restart, so the middleware asks for the live helper
+  // at request time and refuses cleanly while none is ready.
+  return new Acryl().get(
+    `${options.prefix}/channel/ws`,
+    ownOrigin,
+    async (c, next) => {
+      const allow = options.upgrade()
+      if (allow === undefined) return c.json(error('the page channel is not ready yet'), 503)
+      return allow(events, { textOnly: true })(c, next)
+    },
   )
 }

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

@@ -6,7 +6,10 @@
 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', 'window-list', 'window-open', 'window-focus', 'window-close', 'window-resize', 'menu-list', 'menu-click'] as const
+/** The verbs that only use the page: what a page-only door (a production assistant) offers. */
+export const PAGE_VERBS = ['look', 'act'] as const satisfies readonly Verb[]
+
+export const VERBS = ['brief', 'look', 'act', 'plugin-list', 'plugin-add', 'plugin-pull', 'plugin-publish', '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. */
@@ -83,6 +86,16 @@ export const VERB_SPECS: Readonly<Record<Verb, VerbSpec>> = {
     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-pull': {
+    usage: 'plugin pull <source>: fetch a plugin someone released (github:<owner>/<repo>[@<version>][@sha256:<digest>], or a .tgz), check it and start it, live',
+    description: 'Fetch a plugin someone released, without running anything; check its digest, that it works on every OS and that this app has the services it needs; then install and start it without a restart. A refusal says why and changes nothing.',
+    arguments: { type: 'object', properties: { source: { type: 'string', description: 'github:<owner>/<repo>[@<version>][@sha256:<digest>], or a .tgz path or https address' } }, required: ['source'], additionalProperties: false },
+  },
+  'plugin-publish': {
+    usage: 'plugin publish <name> [--owner <account>] [--license <id>]: show what publishing this plugin would send; in a person\'s own terminal, ask them',
+    description: 'Show what publishing a plugin would send: the account, repository, version, license, files and the line a friend pulls it with. Sends nothing. Only a person can say yes, in their own terminal or with Share in the frame; tell them the plan and how.',
+    arguments: { type: 'object', properties: { name: { type: 'string', description: 'a plugin of plugins/' }, owner: { type: 'string', description: 'the GitHub account or organization; the signed-in one when absent' }, license: { type: 'string', description: 'an SPDX license id; MIT when absent' } }, required: ['name'], additionalProperties: false },
+  },
   'plugin-remove': {
     usage: 'plugin remove <name>: stop and remove an installed plugin',
     description: 'Stop and remove an installed plugin.',