acrylblends 0.7.8 → 0.8.1

package/plugins/acryl-router-http/upstream.json

@@ -2,7 +2,7 @@
   "source": {
     "repo": "acryldev/acryl",
     "path": "plugins/acryl-router-http",
-    "commit": "f132283c43337f5e1d58dfbbbc15786efb5e756c"
+    "commit": "20bdc263d6f0f8febbd967007bda4cf4a802efd2"
   },
   "vendored": [
     "src",

package/plugins/acryl-state/upstream.json

@@ -2,7 +2,7 @@
   "source": {
     "repo": "acryldev/acryl",
     "path": "plugins/acryl-state",
-    "commit": "f132283c43337f5e1d58dfbbbc15786efb5e756c"
+    "commit": "20bdc263d6f0f8febbd967007bda4cf4a802efd2"
   },
   "vendored": [
     "src",

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

@@ -0,0 +1,159 @@
+// The panel in the page: a button at the corner opens a side panel (a shadow root, so the app's CSS cannot touch it and it cannot touch the app's). It asks the app's
+// agent through POST /api/agent-panel/ask, shows the answer as it arrives, and reloads the page after a run that installed or removed a plugin.
+const PREFIX = '/api/agent-panel'
+
+interface Session {
+  token: string
+  drivers: string[]
+}
+interface PanelEvent {
+  event: string
+  data: Record<string, unknown>
+}
+
+/** The events of a server-sent stream, as they arrive. */
+async function* events(response: Response): AsyncGenerator<PanelEvent> {
+  const reader = response.body!.getReader()
+  const decoder = new TextDecoder()
+  let buffer = ''
+  for (;;) {
+    const { value, done } = await reader.read()
+    if (done) return
+    buffer += decoder.decode(value, { stream: true }).replace(/\r\n/gu, '\n')
+    for (let end = buffer.indexOf('\n\n'); end !== -1; end = buffer.indexOf('\n\n')) {
+      const block = buffer.slice(0, end)
+      buffer = buffer.slice(end + 2)
+      let event = 'message'
+      let data = ''
+      for (const line of block.split('\n')) {
+        if (line.startsWith('event:')) event = line.slice(6).trim()
+        else if (line.startsWith('data:')) data += line.slice(5).trim()
+      }
+      if (data !== '') yield { event, data: JSON.parse(data) as Record<string, unknown> }
+    }
+  }
+}
+
+const css = `
+:host { all: initial }
+* { box-sizing: border-box; font: 14px system-ui, sans-serif }
+button.open { position: fixed; right: 16px; bottom: 16px; z-index: 2147483000; border: 0; border-radius: 24px; padding: 10px 16px; background: #1f2937; color: #fff; cursor: pointer; box-shadow: 0 2px 8px #0004 }
+section { position: fixed; top: 0; right: 0; bottom: 0; width: min(380px, 100vw); z-index: 2147483001; display: none; flex-direction: column; background: #fff; color: #111827; border-left: 1px solid #d1d5db; box-shadow: -2px 0 12px #0003 }
+section.shown { display: flex }
+header { display: flex; gap: 8px; align-items: center; padding: 8px 12px; border-bottom: 1px solid #e5e7eb }
+header strong { flex: 1 }
+#log { flex: 1; overflow: auto; padding: 12px; display: flex; flex-direction: column; gap: 8px }
+.msg { white-space: pre-wrap; padding: 8px 10px; border-radius: 8px; background: #f3f4f6 }
+.me { background: #dbeafe; align-self: flex-end }
+.tool { font: 12px ui-monospace, monospace; color: #4b5563; background: none; padding: 0 }
+.err { background: #fee2e2 }
+form { display: flex; flex-direction: column; gap: 6px; padding: 10px 12px; border-top: 1px solid #e5e7eb }
+textarea { width: 100%; min-height: 64px; resize: vertical; padding: 8px; border: 1px solid #d1d5db; border-radius: 6px }
+.row { display: flex; gap: 8px; align-items: center }
+.row button, header button { padding: 6px 12px; border: 1px solid #d1d5db; border-radius: 6px; background: #fff; cursor: pointer }
+.row button.send { background: #1f2937; color: #fff; border-color: #1f2937 }
+`
+
+async function start(): Promise<void> {
+  const reply = await fetch(`${PREFIX}/session`)
+  if (!reply.ok) return
+  const session = (await reply.json()) as Session
+
+  const host = document.createElement('div')
+  host.id = 'agent-panel'
+  const shadow = host.attachShadow({ mode: 'open' })
+  shadow.innerHTML = `<style>${css}</style>
+    <button class="open" type="button">Ask the agent</button>
+    <section aria-label="Agent panel">
+      <header><strong>Agent</strong><select aria-label="Agent">${session.drivers.map((d) => `<option>${d}</option>`).join('')}</select><button class="close" type="button" aria-label="Close">×</button></header>
+      <div id="log" role="log"></div>
+      <form><textarea aria-label="Message" placeholder="What should the app do?"></textarea>
+        <div class="row"><button class="send" type="submit">Send</button><button class="stop" type="button" disabled>Stop</button></div></form>
+    </section>`
+  const $ = <T extends Element>(selector: string): T => shadow.querySelector<T>(selector)!
+  const panel = $<HTMLElement>('section')
+  const log = $<HTMLElement>('#log')
+  const input = $<HTMLTextAreaElement>('textarea')
+  const send = $<HTMLButtonElement>('.send')
+  const stop = $<HTMLButtonElement>('.stop')
+  const driver = $<HTMLSelectElement>('select')
+  const show = (open: boolean): void => {
+    panel.classList.toggle('shown', open)
+    if (open) input.focus()
+  }
+  $('button.open').addEventListener('click', () => show(true))
+  $('button.close').addEventListener('click', () => show(false))
+  const line = (text: string, kind = ''): HTMLElement => {
+    const el = document.createElement('div')
+    el.className = `msg ${kind}`
+    el.textContent = text
+    log.append(el)
+    log.scrollTop = log.scrollHeight
+    return el
+  }
+
+  let controller: AbortController | undefined
+  stop.addEventListener('click', () => controller?.abort())
+  shadow.querySelector('form')!.addEventListener('submit', async (submitted) => {
+    submitted.preventDefault()
+    const message = input.value.trim()
+    if (message === '' || controller) return
+    input.value = ''
+    line(message, 'me')
+    controller = new AbortController()
+    send.disabled = true
+    stop.disabled = false
+    let changed = false
+    let answer: HTMLElement | undefined
+    try {
+      const response = await fetch(`${PREFIX}/ask`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', 'x-agent-panel-token': session.token },
+        body: JSON.stringify({ message, driver: driver.value }),
+        signal: controller.signal,
+      })
+      if (!response.ok) {
+        line(
+          ((await response.json().catch(() => ({}))) as { error?: string }).error ??
+            `The panel answered ${response.status}.`,
+          'err',
+        )
+        return
+      }
+      for await (const { event, data } of events(response)) {
+        if (event === 'text') {
+          answer ??= line('')
+          answer.textContent += String(data.text ?? '')
+        } else if (event === 'tool') {
+          line(`${String(data.tool)}${data.error ? ` failed: ${String(data.error)}` : ''}`, 'tool')
+        } else if (event === 'change') {
+          changed = true
+          line(`plugin ${String(data.extension)}: ${String(data.action)}`, 'tool')
+        } else if (event === 'error') {
+          line(String(data.message ?? 'The run failed.'), 'err')
+        } else if (event === 'done') {
+          changed = changed || data.changed === true
+        }
+      }
+    } catch (error) {
+      line(
+        controller?.signal.aborted
+          ? 'Stopped.'
+          : `The request failed: ${error instanceof Error ? error.message : String(error)}`,
+        'err',
+      )
+    } finally {
+      controller = undefined
+      send.disabled = false
+      stop.disabled = true
+    }
+    // A plugin was installed or removed: the new feature is served by the running app, so the page only needs to be loaded again (unless something is being typed).
+    if (changed && input.value.trim() === '') {
+      line('Reloading the page to show it.', 'tool')
+      setTimeout(() => location.reload(), 900)
+    }
+  })
+  document.body.append(host)
+}
+
+void start()

package/plugins/agent-panel/index.ts

@@ -0,0 +1,232 @@
+/**
+ * The built-in agent (spec 049 slice 14): a chat panel inside the running app. The person says what they want; the app's own agent (`driver: 'agent'`) or a coding
+ * agent started in the app folder (`'claude'`, `'codex'`, `'pi'`) builds it through the door, and when a plugin was installed or removed the page reloads, so the new feature
+ * shows with no restart.
+ *
+ * - A middleware appends one script tag (`/api/agent-panel/panel.js`) to every HTML response of the routes mounted after it, so no page is edited.
+ * - `GET /api/agent-panel/session` gives the page the drivers it may use and a token; `POST /api/agent-panel/ask` runs one message and answers server-sent events:
+ *   `text`, `tool`, `change`, `done`, `error`.
+ * - Only the app's own page may ask (a same-origin request carrying the token), one run at a time, and every ask is written to `.acryl/audit/agent-panel.jsonl`.
+ * - Development only: the plugin does nothing with `NODE_ENV=production` or `ACRYL_DOOR=off`.
+ */
+import { spawn, spawnSync } from 'node:child_process'
+import { randomBytes } from 'node:crypto'
+import { appendFileSync, mkdirSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import type { Context } from '@deepseek-ai/cordis'
+import { clientModules } from '../acryl-node-server/src/client-modules.ts'
+import { streamSSE } from '../acryl-router/src/helpers/index.ts'
+import { Acryl } from '../acryl-router/src/index.ts'
+import type {} from '../agent/index.ts'
+import type {} from '../extensions/index.ts'
+
+export const name = 'agent-panel'
+export const inject = ['router', 'agent', 'extensions', 'appInstance']
+
+const PREFIX = '/api/agent-panel'
+const CLIENT_DIR = join(import.meta.dirname, 'client')
+
+export type DriverName = 'agent' | 'claude' | 'codex' | 'pi'
+
+export interface PanelConfig {
+  /** Driver programs to offer besides the app's own agent; default: the ones found on the machine. */
+  drivers?: readonly Exclude<DriverName, 'agent'>[]
+}
+
+/** The command line of each coding agent started headless in the app folder (the same ones the product test uses). */
+function command(
+  driver: Exclude<DriverName, 'agent'>,
+  message: string,
+  root: string,
+): { file: string; args: string[] } {
+  switch (driver) {
+    case 'claude':
+      return {
+        file: 'claude',
+        args: [
+          '-p',
+          message,
+          '--permission-mode',
+          'acceptEdits',
+          '--allowedTools',
+          'Read,Edit,Write,Glob,Grep,Bash(npm *),Bash(npx *),Bash(node *),Bash(.acryl/bin/acryl *),Bash(curl *)',
+        ],
+      }
+    case 'codex':
+      return {
+        file: 'codex',
+        args: [
+          'exec',
+          '--skip-git-repo-check',
+          '-s',
+          'workspace-write',
+          '-c',
+          'sandbox_workspace_write.network_access=true',
+          '-C',
+          root,
+          message,
+        ],
+      }
+    case 'pi':
+      return {
+        file: 'pi',
+        args: [
+          '-p',
+          message,
+          '--provider',
+          'deepseek',
+          '--model',
+          'deepseek-v4-pro',
+          '--no-session',
+        ],
+      }
+  }
+}
+
+function onPath(program: string): boolean {
+  const found = spawnSync(process.platform === 'win32' ? 'where' : 'which', [program], {
+    encoding: 'utf8',
+  })
+  return found.status === 0
+}
+
+/** The drivers this machine can offer: the app's own agent always; a program when it is installed (pi also needs its key in the environment). */
+export function availableDrivers(wanted?: readonly Exclude<DriverName, 'agent'>[]): DriverName[] {
+  const found: DriverName[] = ['agent']
+  for (const driver of wanted ?? (['claude', 'codex', 'pi'] as const)) {
+    if (driver === 'pi' && !process.env.DEEPSEEK_API_KEY) continue
+    if (onPath(driver)) found.push(driver)
+  }
+  return found
+}
+
+/** Whether a request comes from the app's own page: a browser says so itself (`Sec-Fetch-Site: same-origin`), or the Origin is the Host. */
+export function fromOwnPage(headers: Headers): boolean {
+  const site = headers.get('sec-fetch-site')
+  if (site !== null) return site === 'same-origin'
+  const origin = headers.get('origin')
+  const host = headers.get('host')
+  return origin !== null && host !== null && new URL(origin).host === host
+}
+
+export function apply(ctx: Context, config: PanelConfig = {}): void {
+  if (process.env.NODE_ENV === 'production' || process.env.ACRYL_DOOR === 'off') return
+  const root = ctx.appInstance.root
+  const token = randomBytes(24).toString('hex')
+  const auditFile = join(root, '.acryl', 'audit', 'agent-panel.jsonl')
+  const audit = (entry: Record<string, unknown>): void => {
+    try {
+      mkdirSync(dirname(auditFile), { recursive: true })
+      appendFileSync(auditFile, `${JSON.stringify({ at: new Date().toISOString(), ...entry })}\n`)
+    } catch {
+      // The audit never stops a run.
+    }
+  }
+  const drivers = availableDrivers(config.drivers)
+  let running = false
+
+  const tag = `<script type="module" src="${PREFIX}/panel.js"></script>`
+  const app = new Acryl()
+    // The script tag, on every HTML page the routes mounted after this plugin answer.
+    .use('*', async (c, next) => {
+      await next()
+      if (!(c.res.headers.get('content-type') ?? '').includes('text/html')) return
+      const html = await c.res.text()
+      const headers = new Headers(c.res.headers)
+      headers.delete('content-length')
+      c.res = new Response(
+        html.includes('</body>') ? html.replace('</body>', `${tag}</body>`) : html + tag,
+        { status: c.res.status, headers },
+      )
+    })
+    .get(`${PREFIX}/panel.js`, (c) =>
+      c.body(`import '${PREFIX}/client/main.ts'\n`, 200, {
+        'content-type': 'text/javascript; charset=utf-8',
+        'cache-control': 'no-cache',
+      }),
+    )
+    .route(`${PREFIX}/client`, clientModules({ root: CLIENT_DIR }))
+    .get(`${PREFIX}/session`, (c) => {
+      if (!fromOwnPage(c.req.raw.headers))
+        return c.json({ error: "only the app's own page may use the panel" }, 403)
+      return c.json({ token, drivers })
+    })
+    .post(`${PREFIX}/ask`, async (c) => {
+      if (!fromOwnPage(c.req.raw.headers) || c.req.header('x-agent-panel-token') !== token)
+        return c.json({ error: "only the app's own page may ask" }, 403)
+      const body = (await c.req.json().catch(() => ({}))) as { message?: unknown; driver?: unknown }
+      const message = typeof body.message === 'string' ? body.message.trim() : ''
+      const driver = (typeof body.driver === 'string' ? body.driver : 'agent') as DriverName
+      if (message === '' || message.length > 8000)
+        return c.json({ error: 'write a message of at most 8000 characters' }, 400)
+      if (!drivers.includes(driver))
+        return c.json(
+          { error: `the driver "${driver}" is not available here (${drivers.join(', ')})` },
+          400,
+        )
+      if (running) return c.json({ error: 'a run is already going; wait for it to end' }, 409)
+      running = true
+      return streamSSE(c, async (stream) => {
+        const send = (event: string, data: unknown): Promise<void> =>
+          stream.writeSSE({ event, data: JSON.stringify(data) })
+        let changed = false
+        const off = ctx.on('extensions/changed', (extension: string, action: string) => {
+          changed = true
+          void send('change', { extension, action })
+        })
+        audit({ ask: 'start', driver, characters: message.length })
+        try {
+          if (driver === 'agent') {
+            const result = await ctx.agent.run(message)
+            for (const call of result.trace)
+              await send('tool', {
+                tool: call.tool,
+                input: call.input,
+                ...(call.error ? { error: call.error } : { result: call.result }),
+              })
+            await send('text', {
+              text:
+                result.status === 'completed'
+                  ? result.output
+                  : result.status === 'cancelled'
+                    ? 'The run was cancelled.'
+                    : `The run stopped after ${result.steps} steps without an answer.`,
+            })
+          } else {
+            const { file, args } = command(driver, message, root)
+            const child = spawn(file, args, {
+              cwd: root,
+              env: process.env,
+              stdio: ['ignore', 'pipe', 'pipe'],
+            })
+            stream.onAbort(() => {
+              child.kill('SIGTERM')
+            })
+            child.stdout.on(
+              'data',
+              (chunk: Buffer) => void send('text', { text: chunk.toString() }),
+            )
+            child.stderr.on(
+              'data',
+              (chunk: Buffer) =>
+                void send('tool', { tool: driver, info: chunk.toString().slice(0, 500) }),
+            )
+            const code = await new Promise<number>((done) => {
+              child.on('error', () => done(1))
+              child.on('exit', (exit) => done(exit ?? 1))
+            })
+            if (code !== 0)
+              await send('error', { message: `${driver} ended with exit code ${code}` })
+          }
+          await send('done', { changed })
+        } catch (error) {
+          await send('error', { message: error instanceof Error ? error.message : String(error) })
+        } finally {
+          off()
+          running = false
+          audit({ ask: 'end', driver, changed })
+        }
+      })
+    })
+  ctx.router.route('/', app)
+}

package/plugins/agent-panel/plugin.json

@@ -0,0 +1,21 @@
+{
+  "name": "agent-panel",
+  "description": "A chat panel inside the running app: the person writes what they want, the app's own agent (or Claude Code, Codex or pi started in the app folder) builds it through the same door, and the page reloads when a plugin was installed, with no restart. Development only; opt-in with acrylblends add agent-panel.",
+  "requires": [
+    "acryl-router",
+    "acryl-node-server",
+    "agent",
+    "builder",
+    "extensions",
+    "sandbox",
+    "tasks",
+    "instance"
+  ],
+  "inject": ["router", "agent", "extensions", "appInstance"],
+  "provides": [],
+  "dependencies": {
+    "@deepseek-ai/cordis": "4.0.4"
+  },
+  "mount": "add a row `- id: agent-panel` / `name: agent-panel` to blend.yaml BEFORE the `routes` row (its middleware adds one script tag to every HTML page the routes after it answer) and register it in src/app.ts: 'agent-panel': panel; open the app in a browser and use the button at the corner of the page",
+  "gitignore": [".acryl/"]
+}

package/plugins/desktop/upstream.json

@@ -5,7 +5,7 @@
       "apps/acryl-desktop/src/shell/desktop-user-data.ts": "user-data.ts",
       "apps/acryl-desktop/src/shell/shutdown.ts": "shutdown.ts"
     },
-    "commit": "f132283c43337f5e1d58dfbbbc15786efb5e756c"
+    "commit": "20bdc263d6f0f8febbd967007bda4cf4a802efd2"
   },
   "rewrittenSpecifiers": 0,
   "digest": "sha256:7dfe960a8bbb476c35540d2202a7aaa62b33492c2ac3e34314e2ecfca45f32f2"

package/plugins/desktop-web/upstream.json

@@ -5,7 +5,7 @@
       "apps/acryl-desktop/src/shell/desktop-user-data.ts": "user-data.ts",
       "apps/acryl-desktop/src/shell/shutdown.ts": "shutdown.ts"
     },
-    "commit": "f132283c43337f5e1d58dfbbbc15786efb5e756c"
+    "commit": "20bdc263d6f0f8febbd967007bda4cf4a802efd2"
   },
   "rewrittenSpecifiers": 0,
   "digest": "sha256:7dfe960a8bbb476c35540d2202a7aaa62b33492c2ac3e34314e2ecfca45f32f2"

package/plugins/extensions/resolve.ts

@@ -5,9 +5,9 @@
  * (ACRYL needed the same fallback on Deno); the returned function removes the hook.
  *
  * The framework plugins are not packages in an app (they are source under `plugins/`), so `aliases` names the files a framework specifier such as
- * `acryl-router` stands for. A staged plugin then imports the same module the app itself runs, so `App` is the very class the router mounts.
+ * `acryl-router` stands for (and the ports and providers beside it: `acryl-kv`, `acryl-kv-json`, `acryl-db`, ..., and each as `#acryl-kv` ... the name the app's `package.json` "imports" gives them). A staged plugin then imports the same module the app itself runs, so `App` is the very class the router mounts.
  */
-import { existsSync, mkdirSync, realpathSync } from 'node:fs'
+import { existsSync, mkdirSync, readdirSync, realpathSync } from 'node:fs'
 import { registerHooks } from 'node:module'
 import { join } from 'node:path'
 import { fileURLToPath, pathToFileURL } from 'node:url'
@@ -90,6 +90,20 @@ export function routerAliases(): Record<string, string> {
   add('acryl-router', 'index.ts')
   add('acryl-router/middleware', 'middleware/index.ts')
   add('acryl-router/helpers', 'helpers/index.ts')
+  // The ports and their providers sit beside the router as source too (`acrylblends add kv` copies `acryl-kv` and `acryl-kv-json`). A plugin installed live, a
+  // provider of your own for example, imports them by name and gets the very modules the app runs.
+  const plugins = new URL('../', import.meta.url)
+  for (const folder of readdirSync(fileURLToPath(plugins), { withFileTypes: true })) {
+    if (!folder.isDirectory() || !folder.name.startsWith('acryl-')) continue
+    const entry = fileURLToPath(new URL(`${folder.name}/src/index.ts`, plugins))
+    if (!existsSync(entry)) continue
+    // The bare name, and the app's own `#name` (a `package.json` "imports" entry that `acrylblends add` writes): a staged copy lives in the app's home, which may be
+    // outside the app folder, where Node would not find that entry.
+    aliases[folder.name] ??= entry
+    aliases[`#${folder.name}`] = entry
+    const suite = fileURLToPath(new URL(`${folder.name}/src/conformance.ts`, plugins))
+    if (existsSync(suite)) aliases[`#${folder.name}/conformance`] = suite
+  }
   return aliases
 }
 

package/plugins/tsconfig.json

@@ -26,6 +26,12 @@
     "acryl-db-sqlite/tests/loader.spec.ts",
     "acryl-kv-json/tests/loader.spec.ts",
     "acryl-kv-db/tests/loader.spec.ts",
+    "acryl-door/tests/harness.ts",
+    "acryl-door/tests/host/loader.spec.ts",
+    "acryl-door/tests/host/door.spec.ts",
+    "acryl-door/tests/host/shim.spec.ts",
+    "acryl-door/tests/host/verbs.spec.ts",
+    "acryl-door/tests/page",
     "acryl-state/src/react.ts",
     "acryl-state/tests/react.spec.ts",
     "acryl-router-http/tests/adapter.spec.ts",

package/shared/DEFAULTS.md

@@ -6,8 +6,8 @@ and swap it at the one place that mounts it.
 
 | Choice | Default | To swap it |
 | --- | --- | --- |
-| Records | none until you add one: `npx acrylblends add db` mounts the `db` port on SQLite | mount another provider of `db` in `src/app.ts`; plugins use `ctx.db` and do not change |
-| Small state | none until you add one: `npx acrylblends add kv` mounts the `kv` port on one JSON file | mount `acryl-kv-db` (the same port over `db`) or a provider of your own |
+| Records | the `db` port on SQLite (already mounted in the notes and chat templates; elsewhere `npx acrylblends add db`) | mount another provider of `db` in `src/app.ts`; plugins use `ctx.db` and do not change |
+| Small state | the `kv` port on one JSON file (`npx acrylblends add kv`) | mount `acryl-kv-db` (the same port over `db`) or a provider of your own |
 | Server | Node (`acryl-node-server`) | mount the adapter of another runtime in `src/app.ts` |
 | Window | the browser | `npx acrylblends add desktop` adds an Electron window on the same server |
 
@@ -23,11 +23,11 @@ install a second time). Do not create `src/plugins/` or `extensions/`.
 
 ## The door
 
-The door is a command in this folder, `.acryl/bin/acryl`, that lets you look at and change the running app; it reaches only the app running from this folder. Its state (a secret and an audit log) lives under `.acryl/`, which git ignores: never commit it. If `.acryl/bin/acryl` is not here, this app has no door yet: run it with its scripts and check it with `npm test`.
+The door is a command in this folder, `.acryl/bin/acryl`, that lets you look at and change the running app. The running app writes it, and it reaches only the app running from this folder. Its state (a secret and an audit log) lives under `.acryl/`, which git ignores: never commit it. It is on in development and off with `NODE_ENV=production` or `ACRYL_DOOR=off`; one process at a time serves a folder's door, so a second `npm start` in the same folder stops with a message that says so (the tests set `ACRYL_DOOR=off`). If `.acryl/bin/acryl` is not here, the app is not running: start it with `npm run dev` (in the background) and open its address in a browser.
 
 ```
-.acryl/bin/acryl brief                      what this app is: its plugins, where the docs are, the verbs
-.acryl/bin/acryl look                       a snapshot of the page, with refs (r1, r2, ...)
+.acryl/bin/acryl brief                      what this app is: its plugins, where the docs are, the verbs, and whether a page is open
+.acryl/bin/acryl look                       the page as text, with refs (1.1, 1.2, ...): roles, names, values, visible text
 .acryl/bin/acryl act click --ref <r>
 .acryl/bin/acryl act type --ref <r> --text <t> [--submit] [--no-clear]
 .acryl/bin/acryl act select --ref <r> --option <o>
@@ -36,5 +36,10 @@ The door is a command in this folder, `.acryl/bin/acryl`, that lets you look at
 .acryl/bin/acryl act wait (--text <t> | --role <role> [--name <n>]) [--gone] [--timeout-ms <ms>]
 .acryl/bin/acryl plugin list | add <folder> | remove <name> | reload
 .acryl/bin/acryl tool list | call --tool <name> --args '<json>'
+.acryl/bin/acryl verbs                      the verb list
 ```
-Every verb takes `--json`. `plugin add plugins/<name>` checks the plugin, installs it and makes it live without a restart. `tool call` reaches only the tools on the door's allowlist (empty by default). On Windows the command is `.acryl\bin\acryl.cmd`.
+
+- `look` and `act` need the app's page open in a browser (`brief` says `Page: not open` when it is not). Look again before each `act`: refs belong to the latest `look`.
+- A password field is not shown and cannot be typed into through the door; sign in by hand, or test the sign-in with a test.
+- Every verb takes `--json`. The exit code is 0 for done, 1 when the verb failed, 2 for a usage error and 3 when no app is running in this folder.
+- `plugin add plugins/<name>` checks the plugin, installs it and makes it live without a restart (the `extensions` plugin does this; every template that has the door has it, in development only: it is left out with `NODE_ENV=production`). `tool call` reaches only the tools on the door's allowlist (empty by default). On Windows the command is `.acryl\bin\acryl.cmd`.

package/shared/SKILL.md

@@ -10,5 +10,5 @@ description: How to change, run and check the __APP_NAME__ app. Use it before ad
 2. **Make the change small.** Your own routes are a plugin (`src/routes.ts`) that builds an `Acryl` app and mounts it; test a route with `await app.request('/path')`.
 3. **One plugin folder.** A plugin lives in `plugins/<name>/` (`npx acrylblends add <name>` copies a library plugin there). There is no `src/plugins/` and no `extensions/`.
 4. **Defaults are swappable.** The database, the key-value store, the server and the window are plugins behind ports. The table "Defaults you can swap" in `AGENTS.md` names each default and where it is swapped. Never reach around a port to a driver: `npx acrylblends check-deps` fails the check.
-5. **Look at the running app.** The door is a command in this folder, `.acryl/bin/acryl`, that lets you look at and change the running app; it reaches only the app running from this folder. Its state (a secret and an audit log) lives under `.acryl/`, which git ignores: never commit it. If `.acryl/bin/acryl` is not here, this app has no door yet: run it with its scripts and check it with `npm test`. Start with `.acryl/bin/acryl brief`, then `look` for the page and `act` to click or type on it; the full list is in `AGENTS.md`.
+5. **Look at the running app.** Start it (`npm run dev`, in the background), open its address in a browser, then run `.acryl/bin/acryl brief`, `look` and `act`: the door shows the page as text with refs and clicks or types on it. Read the section "The door" of `AGENTS.md` for the verbs. Without the door, check the page by hand.
 6. **Done means checked.** `npm test` passes, and the change shows in the running app after a restart. No secret goes in a file or in `git status`: keys come from environment variables.

package/templates/agent/blend.yaml

@@ -54,3 +54,6 @@ spec:
       name: acryl-node-server
       config:
         hostname: "{{parameters.hostname}}"
+    # The door: an agent working in this folder looks at the page and acts on it through .acryl/bin/acryl. Development only: src/app.ts leaves it out when NODE_ENV=production.
+    - id: acryl-door
+      name: acryl-door

package/templates/agent/src/app.ts

@@ -2,6 +2,7 @@ import { existsSync } from 'node:fs'
 import { join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { Context, type Fiber } from '@deepseek-ai/cordis'
+import * as door from '../plugins/acryl-door/src/index.ts'
 import * as nodeServer from '../plugins/acryl-node-server/src/index.ts'
 import * as router from '../plugins/acryl-router/src/index.ts'
 import * as state from '../plugins/acryl-state/src/index.ts'
@@ -36,6 +37,7 @@ export const registry = {
   sandbox: sandboxPlugin,
   routes,
   'acryl-node-server': nodeServer,
+  'acryl-door': door,
 }
 
 /** The manifest next to this app's source. */
@@ -55,6 +57,7 @@ export function readManifest(values?: Readonly<Record<string, ParameterValue>>)
 
 export interface App {
   readonly root: Context
+  /** The address the server listens on; empty when the app was made with `listen: false`. */
   readonly url: string
   stop(): Promise<void>
 }
@@ -69,9 +72,22 @@ export async function createApp(
     values?: Readonly<Record<string, ParameterValue>>
     /** A real model (any OpenAI-compatible API) in place of the offline scripted one. */
     model?: OpenAIConfig
+    /** Start the HTTP server (default). Tests pass `false` and call `app.root.router.request(path)`: it needs no port, so it also runs where a sandbox forbids listening. */
+    listen?: boolean
   } = {},
 ): Promise<App> {
-  const manifest = readManifest(options.values)
+  const read = readManifest(options.values)
+  // Rows left out: the server (and so the door, which needs it) when the app is reached in process; the door in production and with ACRYL_DOOR=off (one process at a time
+  // serves a folder's door, so the tests that start several apps set it).
+  const listen = options.listen !== false
+  const leaveOut = new Set<string>()
+  if (!listen) leaveOut.add('acryl-node-server').add('acryl-door')
+  if (process.env.NODE_ENV === 'production' || process.env.ACRYL_DOOR === 'off')
+    leaveOut.add('acryl-door')
+  const manifest = {
+    ...read,
+    plugins: read.plugins.map((row) => (leaveOut.has(row.use) ? { ...row, disabled: true } : row)),
+  }
   const extensionsDir = join(chosen.root, 'plugins')
   // One release of grace: an app made before 0.7.8 kept what the agent wrote in `extensions/`. It is still installed, with a warning.
   const legacyDir = join(chosen.root, 'extensions')
@@ -103,7 +119,7 @@ export async function createApp(
   ]
   return {
     root,
-    url: root.nodeServer.url,
+    url: listen ? root.nodeServer.url : '',
     async stop() {
       for (const fiber of [...fibers].reverse()) await fiber.dispose()
     },

package/templates/agent/src/routes.ts

@@ -7,6 +7,12 @@ import type {} from '../plugins/tasks/index.ts'
 
 export const APP_NAME = '__APP_NAME__'
 
+/** The door's page script (`.acryl/bin/acryl look` and `act`), in development only: `src/app.ts` leaves the door out in production and with ACRYL_DOOR=off. */
+const DOOR_TAG =
+  process.env.NODE_ENV !== 'production' && process.env.ACRYL_DOOR !== 'off'
+    ? '<script type="module" src="/api/acryl-door/page.js"></script>'
+    : ''
+
 /**
  * The app's own routes on the router: `POST /ask` for the agent; `GET /extensions` and `GET /tasks` to observe what it did (every run is a
  * durable task owning one task per tool call); `POST /tasks/cancel`. What changes is also streamed: `GET /api/state/tasks/events` and
@@ -25,7 +31,14 @@ export const routes = {
     }
     const app = new Acryl()
       .use(bodyLimit({ maxSize: 64 * 1024 }))
-      .get('/', (c) => c.json({ app: APP_NAME, ok: true }))
+      // A browser gets a page (the door's and the agent panel's script tags are added where they are mounted); everything else gets the JSON.
+      .get('/', (c) =>
+        (c.req.header('accept') ?? '').includes('text/html')
+          ? c.html(
+              `<!doctype html><html lang="en"><head><meta charset="utf-8"><title>${APP_NAME}</title></head><body><h1>${APP_NAME}</h1><p>This app runs an agent. Ask it for a feature (<code>POST /ask</code>), or add the chat panel with <code>npx acrylblends add agent-panel</code>.</p>${DOOR_TAG}</body></html>`,
+            )
+          : c.json({ app: APP_NAME, ok: true }),
+      )
       .get('/health', (c) => c.json({ ok: true }))
       .get('/extensions', (c) =>
         c.json({