acrylblends 0.7.7 → 0.8.0

package/plugins/desktop-web/main.ts

@@ -17,7 +17,7 @@ import { createDesktopShutdown, installShutdownRequests } from './shutdown.ts'
 import { resolveDesktopUserDataOverride } from './user-data.ts'
 import { windowOptions } from './window.ts'
 
-const projectRoot = fileURLToPath(new URL('../../..', import.meta.url))
+const projectRoot = fileURLToPath(new URL('../..', import.meta.url))
 const manifest = JSON.parse(readFileSync(join(projectRoot, 'package.json'), 'utf8')) as {
   name?: string
   acrylblends?: { desktopPath?: string }
@@ -73,7 +73,7 @@ if (!app.requestSingleInstanceLock()) {
 
   void app.whenReady().then(async () => {
     // The hook above is registered before the app's modules are loaded, so the app may have .tsx pages: they are loaded here, not as a static import.
-    const { default: acrylApp, close } = (await import('../../app.ts')) as {
+    const { default: acrylApp, close } = (await import('../../src/app.ts')) as {
       default: { fetch: Parameters<typeof serve>[0]['fetch'] }
       close?: () => Promise<void>
     }

package/plugins/desktop-web/plugin.json

@@ -9,9 +9,9 @@
     "electron": "44.9.3"
   },
   "scripts": {
-    "desktop": "electron src/plugins/desktop-web/main.ts"
+    "desktop": "electron plugins/desktop-web/main.ts"
   },
   "gitignore": [".acrylblends/"],
   "omit": ["**/*.test.*"],
-  "mount": "nothing to mount: run `npm install`, then `npm run desktop` (the window opens on the app's own server; every electron call is in src/plugins/desktop-web)"
+  "mount": "nothing to mount: run `npm install`, then `npm run desktop` (the window opens on the app's own server; every electron call is in plugins/desktop-web)"
 }

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": "f8e385e4389fe2fdc6fd2a4366a7f2a7389faacb"
+    "commit": "20bdc263d6f0f8febbd967007bda4cf4a802efd2"
   },
   "rewrittenSpecifiers": 0,
   "digest": "sha256:7dfe960a8bbb476c35540d2202a7aaa62b33492c2ac3e34314e2ecfca45f32f2"

package/plugins/extensions/index.ts

@@ -55,8 +55,24 @@ export interface ExtensionSource {
   readonly trust: Trust
 }
 
+/** The library copies a plugins folder holds (`library.json`, written by `acrylblends add`): the app mounts them itself, so they are not extensions. */
+function libraryCopies(dir: string): ReadonlySet<string> {
+  try {
+    const listed = (
+      JSON.parse(readFileSync(join(dir, 'library.json'), 'utf8')) as { plugins?: unknown }
+    ).plugins
+    return new Set(
+      Array.isArray(listed)
+        ? listed.filter((name): name is string => typeof name === 'string')
+        : [],
+    )
+  } catch {
+    return new Set()
+  }
+}
+
 export interface ExtensionsConfig {
-  /** Where extension folders may come from. Defaults to `<app home>/extensions`, trusted to install. */
+  /** Where extension folders may come from. An app passes its `plugins/` folder (library copies listed in its `library.json` are skipped). Defaults to `<app home>/extensions`, trusted to install, for a service used without an app folder. */
   sources?: readonly ExtensionSource[]
   /** When true, every source that would install by itself asks for approval instead (`ask`). */
   approval?: boolean
@@ -373,11 +389,13 @@ export class Extensions extends Service {
     const found: Array<{ name: string; dir: string; trust: Trust }> = []
     for (const source of this.sources) {
       if (!existsSync(source.dir)) continue
+      const library = libraryCopies(source.dir)
       for (const entry of readdirSync(source.dir, { withFileTypes: true })) {
         const dir = join(source.dir, entry.name)
         if (
           entry.isDirectory() &&
           NAME.test(entry.name) &&
+          !library.has(entry.name) &&
           ENTRIES.some((file) => existsSync(join(dir, file)))
         ) {
           if (!found.some((other) => other.name === entry.name))

package/plugins/extensions/plugin.json

@@ -8,5 +8,5 @@
     "@deepseek-ai/cordis": "4.0.4",
     "@webboxes/blends-core": "0.4.0"
   },
-  "mount": "mount it after instance: root.plugin(extensions, { sources: [{ dir: join(root, 'extensions'), trust: 'install' }] })"
+  "mount": "mount it after instance: root.plugin(extensions, { sources: [{ dir: join(root, 'plugins'), trust: 'install' }] })"
 }

package/plugins/extensions/resolve.ts

@@ -4,10 +4,10 @@
  * module inside the staging folder, resolves the same name from the app's project folder. Uses Node's public `module.registerHooks`
  * (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 `src/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.
+ * 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 (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/manifest/lock.ts

@@ -1,7 +1,7 @@
 /**
  * `npm run lock`: write `blend.lock.json` (formatVersion 3, the lock ACRYL writes too) next to the manifest, recording what the app is
  * built from: the manifest's identity and digest, the Blueprint it was resolved over, its resolved parameters and rows, and a content
- * digest of every plugin folder in `src/plugins/` and every extension in `extensions/`. Commit it; a diff of the lock is a review of
+ * digest of every plugin folder in `plugins/`. Commit it; a diff of the lock is a review of
  * what changed.
  */
 import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
@@ -69,7 +69,11 @@ export function writeLock(appRoot: string): LockV3 {
       version: document.metadata.version,
       digest: manifestDigest(text),
     },
-    modules: [...localModules(appRoot, 'src/plugins'), ...localModules(appRoot, 'extensions')],
+    modules: [
+      ...localModules(appRoot, 'plugins'),
+      ...localModules(appRoot, 'src/plugins'),
+      ...localModules(appRoot, 'extensions'),
+    ],
     ...(lineage
       ? {
           lineage: {
@@ -86,7 +90,7 @@ export function writeLock(appRoot: string): LockV3 {
 }
 
 if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
-  const appRoot = resolve(fileURLToPath(new URL('../../..', import.meta.url)))
+  const appRoot = resolve(fileURLToPath(new URL('../..', import.meta.url)))
   const locked = writeLock(appRoot)
   console.log(
     `wrote ${LOCK_FILE}: ${locked.rows.length} rows, ${locked.modules.length} local plugins`,

package/plugins/manifest/upgrade-cli.ts

@@ -65,6 +65,6 @@ const parse = (argv: readonly string[]) =>
 if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
   process.exitCode = runUpgrade(
     process.argv.slice(2),
-    resolve(fileURLToPath(new URL('../../..', import.meta.url))),
+    resolve(fileURLToPath(new URL('../..', import.meta.url))),
   )
 }

package/plugins/save/cli.ts

@@ -4,7 +4,7 @@ import { fileURLToPath } from 'node:url'
 import { saveFolder } from './index.ts'
 
 if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
-  const appRoot = fileURLToPath(new URL('../../..', import.meta.url))
+  const appRoot = fileURLToPath(new URL('../..', import.meta.url))
   const result = saveFolder(appRoot, process.argv.slice(2).join(' ').trim() || 'save the app')
   if (result.status === 'refused') {
     console.error(`not saved: ${result.reason}`)

package/plugins/save/plugin.json

@@ -8,5 +8,5 @@
     "@deepseek-ai/cordis": "4.0.4",
     "@webboxes/app-persistence": "0.1.1"
   },
-  "mount": "add a script \"save\": \"node src/plugins/save/cli.ts\" to package.json; mount the plugin to give the agent a save_app tool"
+  "mount": "add a script \"save\": \"node plugins/save/cli.ts\" to package.json; mount the plugin to give the agent a save_app tool"
 }

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/AGENTS.core.md

@@ -9,17 +9,17 @@ Start at `docs/framework/README.md`; `api/summary.md` is the one-page summary. R
 `api/context.md` (`c`), `cordis/validation.md` and `guides/validation.md`, `guides/helpers.md` (`streamSSE`), `concepts/middleware.md`, `cordis/plugin-lifecycle.md` (what a plugin
 owns and when it is unloaded), `cordis/mounting.md` and `cordis/node-server.md`. Pages marked "not yet available" describe parts that are not in this app.
 
-The docs write `import { Acryl } from 'acrylblends'` and `from 'acrylblends/<subpath>'`. In this app the framework is the vendored plugin source in `src/plugins/acryl-router/src`
+The docs write `import { Acryl } from 'acrylblends'` and `from 'acrylblends/<subpath>'`. In this app the framework is the vendored plugin source in `plugins/acryl-router/src`
 (read it, do not edit it: a change belongs in ACRYL, upstream), so from a file in `src/` import:
 
-- `./plugins/acryl-router/src/index.ts` for `Acryl`, `Context`, `HTTPException`, `connectionOf`, `getConnInfo` and the types;
-- `./plugins/acryl-router/src/middleware/index.ts` for every middleware (`cors`, `bodyLimit`, `trimTrailingSlash`, `loopbackOnly`, ...);
-- `./plugins/acryl-router/src/helpers/index.ts` for the helpers and validators (`streamSSE`, `schemaValidator`, `validator`, cookies, `testClient`, ...).
-- `./plugins/acryl-router/src/core/jsx/index.ts` for `acrylblends/jsx` (`jsx`, `Fragment`, the types), and `.../core/jsx/streaming.ts` for `acrylblends/jsx/streaming`.
+- `../plugins/acryl-router/src/index.ts` for `Acryl`, `Context`, `HTTPException`, `connectionOf`, `getConnInfo` and the types;
+- `../plugins/acryl-router/src/middleware/index.ts` for every middleware (`cors`, `bodyLimit`, `trimTrailingSlash`, `loopbackOnly`, ...);
+- `../plugins/acryl-router/src/helpers/index.ts` for the helpers and validators (`streamSSE`, `schemaValidator`, `validator`, cookies, `testClient`, ...).
+- `../plugins/acryl-router/src/core/jsx/index.ts` for `acrylblends/jsx` (`jsx`, `Fragment`, the types), and `.../core/jsx/streaming.ts` for `acrylblends/jsx/streaming`.
 
-**JSX: write `.tsx`.** The scripts in `package.json` run Node.js with `--import ./src/plugins/acryl-node-server/src/register.ts`, which compiles `.tsx` files with this app's own `typescript`; `tsconfig.json` sets `jsx: react-jsx` and `jsxImportSource: #acryl-jsx`, which `package.json`'s `imports` maps to the vendored runtime in `src/plugins/acryl-router`. See `src/about.tsx` (blank template) for a page and `test/app.test.ts` for how it is tested. Render a component with `.toString()` and return it with `c.html(...)`; import `jsx`, `Fragment` and the types from `./plugins/acryl-router/src/core/jsx/index.ts` when you need them. A command that starts the app without those scripts (a bare `node src/main.ts`) cannot load a `.tsx` file. Without a build step you can write the call JSX compiles to instead: `jsx('h1', { class: 'title' }, 'Hello')`, children after the props.
+**JSX: write `.tsx`.** The scripts in `package.json` run Node.js with `--import ./plugins/acryl-node-server/src/register.ts`, which compiles `.tsx` files with this app's own `typescript`; `tsconfig.json` sets `jsx: react-jsx` and `jsxImportSource: #acryl-jsx`, which `package.json`'s `imports` maps to the vendored runtime in `plugins/acryl-router`. See `src/about.tsx` (blank template) for a page and `test/app.test.ts` for how it is tested. Render a component with `.toString()` and return it with `c.html(...)`; import `jsx`, `Fragment` and the types from `../plugins/acryl-router/src/core/jsx/index.ts` when you need them. A command that starts the app without those scripts (a bare `node src/main.ts`) cannot load a `.tsx` file. Without a build step you can write the call JSX compiles to instead: `jsx('h1', { class: 'title' }, 'Hello')`, children after the props.
 
-A plugin written into `extensions/` while the app runs may use the docs' own names instead: `acrylblends` and `acrylblends/<subpath>` resolve to the same files. `App` is the
+A plugin written into `plugins/` while the app runs may use the docs' own names instead: `acrylblends` and `acrylblends/<subpath>` resolve to the same files. `App` is the
 deprecated name of `Acryl`.
 
 ## How a feature is built
@@ -28,8 +28,8 @@ Routes are an ordinary `Acryl` app that a plugin mounts once with `ctx.router.ro
 
 ```ts
 import type { Context } from '@deepseek-ai/cordis'
-import { Acryl, HTTPException } from './plugins/acryl-router/src/index.ts'
-import { schemaValidator, type StandardSchema } from './plugins/acryl-router/src/helpers/index.ts'
+import { Acryl, HTTPException } from '../plugins/acryl-router/src/index.ts'
+import { schemaValidator, type StandardSchema } from '../plugins/acryl-router/src/helpers/index.ts'
 
 export const name = 'notes'               // a plugin's name; blend.yaml refers to it
 export const inject = ['router']          // services it needs
@@ -44,7 +44,7 @@ export function apply(ctx: Context) {
 
 - A small route goes on the `App` in `src/routes.ts`. A new feature is a new plugin file: add it to `registry` in `src/app.ts`, add a row
   (`- id: notes` / `name: notes`) to `blend.yaml` before the `acryl-node-server` row, and pass runtime values (a data file) as its config in `createApp`.
-- State, when `src/plugins/acryl-state` exists: `const cell = ctx.state.cell<T>('notes.list', initial)` (add `'state'` to `inject`), then
+- State, when `plugins/acryl-state` exists: `const cell = ctx.state.cell<T>('notes.list', initial)` (add `'state'` to `inject`), then
   `cell.get()`, `cell.set(value)`, `cell.update(fn)` and `cell.subscribe(fn)` (returns the unsubscribe). Every cell is also served as JSON at `/api/state/<key>`
   and streamed at `/api/state/<key>/events`.
 - Test a route without a socket: `await ctx.router.request('/notes')`, or boot the app as `test/app.test.ts` does and use `fetch`.

package/shared/DEFAULTS.md

@@ -0,0 +1,45 @@
+
+## Defaults you can swap
+
+The framework is not rigid. Every choice is a plugin behind a port, and what the app starts with is only a fallback. Name the default before you change it,
+and swap it at the one place that mounts it.
+
+| Choice | Default | To swap it |
+| --- | --- | --- |
+| 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 |
+
+- **An outside tool** (a database server, a bundler, a router such as Vike) joins the app as a provider: a plugin in `plugins/<name>/` that implements a port and
+  passes that port's conformance tests, then `src/app.ts` mounts it. Postgres is such a provider and is not part of this package; add it when the app needs it.
+- **The dependency rule:** only the file that mounts a provider imports it; everything else takes the port as an argument or injects it. `npx acrylblends check-deps` enforces it.
+
+## Plugins
+
+There is one plugin folder: `plugins/` at the root of the app. A plugin is a folder `plugins/<name>/` with an `index.ts`. `npx acrylblends add <name>` copies a library
+plugin there; a plugin you or an agent write goes there too (the `extensions` plugin installs it into the running app, and `plugins/library.json` lists the copies it must not
+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. 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, 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>
+.acryl/bin/acryl act press --key <Enter|Escape|...>
+.acryl/bin/acryl act scroll [--ref <r>] --direction up|down [--amount <n>]
+.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
+```
+
+- `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 (when the app has the `extensions` plugin; `acrylblends init --template agent` does). `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

@@ -0,0 +1,14 @@
+---
+name: app-guide
+description: How to change, run and check the __APP_NAME__ app. Use it before adding a feature, a route, a plugin or a dependency to this app, and before saying the work is done.
+---
+
+# Working in __APP_NAME__
+
+1. **Read first.** `AGENTS.md` in this folder says how the app is laid out. The framework's API is in `docs/framework/`: start at `docs/framework/README.md`, and
+   `docs/framework/api/summary.md` is the one-page summary. Parts the docs mark "not yet available" are not in this app.
+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.** 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/AGENTS.md

@@ -1,6 +1,6 @@
 
 ## This app (agent)
 
-Besides `src/routes.ts`, the app runs an agent (`POST /ask`) that can write plugins into `extensions/` while the app runs and install them with
+Besides `src/routes.ts`, the app runs an agent (`POST /ask`) that can write plugins into `plugins/` while the app runs and install them with
 rollback; `GET /extensions` and `GET /tasks` show what it did. A plugin there is a folder with an `index.ts` exporting `name`, `inject`, `apply(ctx)`
 and an optional `check(ctx)` that receives the plugin's own context (so `ctx.router` reads as in `apply`). It may import `acryl-router`.

package/templates/agent/README.md

@@ -13,14 +13,14 @@ curl -X POST <url>/ask -H 'content-type: application/json' -d '{"question":"add
 # {"status":"completed","output":"The answer is 5.","steps":2}
 ```
 
-- `src/main.ts` chooses where the app lives (`src/plugins/instance`) and starts it.
+- `src/main.ts` chooses where the app lives (`plugins/instance`) and starts it.
 - `blend.yaml` is the app as data: which plugins it mounts, in what order, with what config and parameters. Switch
   one off with `disabled: true`. `npm run lock` writes `blend.lock.json`: the manifest's digest and a digest of
   every plugin folder, so a diff of the lock shows what changed.
 - `src/app.ts` holds the registry of plugins the code provides, and mounts the manifest's rows.
-- `src/plugins/agent` is the offline agent: a scripted model, a tool registry, memory, and one child fiber per run.
-- `src/plugins/extensions` installs, updates and removes plugins while the app runs; a failed update keeps the previous
-  version running. `src/plugins/builder` gives the agent tools to do that itself, writing into `extensions/`.
+- `plugins/agent` is the offline agent: a scripted model, a tool registry, memory, and one child fiber per run.
+- `plugins/extensions` installs, updates and removes plugins while the app runs; a failed update keeps the previous
+  version running. `plugins/builder` gives the agent tools to do that itself, writing into `plugins/`.
 
 Give it a real model and it builds any Cordis plugin you describe (any OpenAI-compatible API; nothing is installed):
 
@@ -40,9 +40,9 @@ curl <url>/tasks              # every run as a durable task, with the tool calls
 ```
 
 Other commands: `update route <name> <path> <text>`, `break plugin <name>` (shows the rollback), `remove plugin <name>`,
-`list plugins`. What the agent writes lands in `extensions/`, is part of your app, and starts again at the next start.
+`list plugins`. What the agent writes lands in `plugins/`, is part of your app, and starts again at the next start.
 - `src/routes.ts` is your own plugin: it builds an `App` (`import { App } from './plugins/acryl-router/src/index.ts'`) and mounts it with `ctx.router.route(prefix, app)`. Routes added to the app after it is mounted are not served. A page mounted at `/x` answers `/x`, not `/x/` (trailing slashes are strict). The router API is documented at https://acrylblends.github.io/docs/framework/the-acryl-framework and in `docs/framework` of the acrylblends repository.
-- `src/plugins/` holds the plugins copied from the ACRYLBLENDS library. They are yours now; edit them freely.
+- `plugins/` holds the plugins copied from the ACRYLBLENDS library. They are yours now; edit them freely.
   Add more with `acrylblends add <plugin>`.
 
 `npm run save -- "message"` commits the app with git (and pushes when it has a remote). It refuses a file that looks like

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/gitignore

@@ -1,2 +1,3 @@
 node_modules/
 .acrylblends/
+.acryl/

package/templates/agent/package.json

@@ -4,20 +4,20 @@
   "private": true,
   "type": "module",
   "imports": {
-    "#acryl-jsx/jsx-runtime": "./src/plugins/acryl-router/src/core/jsx/jsx-runtime.ts",
-    "#acryl-jsx/jsx-dev-runtime": "./src/plugins/acryl-router/src/core/jsx/jsx-dev-runtime.ts"
+    "#acryl-jsx/jsx-runtime": "./plugins/acryl-router/src/core/jsx/jsx-runtime.ts",
+    "#acryl-jsx/jsx-dev-runtime": "./plugins/acryl-router/src/core/jsx/jsx-dev-runtime.ts"
   },
   "engines": {
     "node": ">=22.19.0"
   },
   "scripts": {
-    "start": "node --import ./src/plugins/acryl-node-server/src/register.ts src/main.ts",
-    "dev": "node --watch --import ./src/plugins/acryl-node-server/src/register.ts src/main.ts",
-    "test": "node --import ./src/plugins/acryl-node-server/src/register.ts --test \"test/**/*.test.{ts,tsx}\"",
+    "start": "node --import ./plugins/acryl-node-server/src/register.ts src/main.ts",
+    "dev": "node --watch --import ./plugins/acryl-node-server/src/register.ts src/main.ts",
+    "test": "node --import ./plugins/acryl-node-server/src/register.ts --test \"test/**/*.test.{ts,tsx}\"",
     "check": "tsc --noEmit",
-    "lock": "node src/plugins/manifest/lock.ts",
-    "save": "node src/plugins/save/cli.ts",
-    "upgrade": "node src/plugins/manifest/upgrade-cli.ts"
+    "lock": "node plugins/manifest/lock.ts",
+    "save": "node plugins/save/cli.ts",
+    "upgrade": "node plugins/manifest/upgrade-cli.ts"
   },
   "dependencies": {
     "typescript": "6.0.3"

package/templates/agent/src/app.ts

@@ -1,23 +1,25 @@
+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 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'
-import { agent, memory, model, tools } from './plugins/agent/index.ts'
-import { builder } from './plugins/builder/index.ts'
-import { extensions } from './plugins/extensions/index.ts'
-import { type AppInstance, instance } from './plugins/instance/index.ts'
+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'
+import { agent, memory, model, tools } from '../plugins/agent/index.ts'
+import { builder } from '../plugins/builder/index.ts'
+import { extensions } from '../plugins/extensions/index.ts'
+import { type AppInstance, instance } from '../plugins/instance/index.ts'
 import {
   blueprintsIn,
   compose,
   loadManifest,
   type ParameterValue,
-} from './plugins/manifest/index.ts'
-import { type OpenAIConfig, openai } from './plugins/openai/index.ts'
-import { sandboxPlugin } from './plugins/sandbox/index.ts'
-import { save } from './plugins/save/index.ts'
-import { tasks } from './plugins/tasks/index.ts'
+} from '../plugins/manifest/index.ts'
+import { type OpenAIConfig, openai } from '../plugins/openai/index.ts'
+import { sandboxPlugin } from '../plugins/sandbox/index.ts'
+import { save } from '../plugins/save/index.ts'
+import { tasks } from '../plugins/tasks/index.ts'
 import { routes } from './routes.ts'
 
 /** The plugins this app's code provides. `blend.yaml` chooses, orders and configures them. */
@@ -35,6 +37,7 @@ export const registry = {
   sandbox: sandboxPlugin,
   routes,
   'acryl-node-server': nodeServer,
+  'acryl-door': door,
 }
 
 /** The manifest next to this app's source. */
@@ -54,12 +57,13 @@ 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>
 }
 
 /**
- * The app: `instance` first (where it lives, chosen at run time), then the manifest's rows in order. The app's own `extensions/`
+ * The app: `instance` first (where it lives, chosen at run time), then the manifest's rows in order. The app's `plugins/`
  * folder is trusted to install at start, and is where the builder writes.
  */
 export async function createApp(
@@ -68,10 +72,30 @@ 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 extensionsDir = join(chosen.root, 'extensions')
+  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')
+  const legacy = existsSync(legacyDir)
+  if (legacy)
+    console.warn(
+      'warning: extensions/ is the old folder for plugins the agent writes; move them to plugins/ ("git mv extensions/<name> plugins/<name>"). extensions/ is read for this release only.',
+    )
   const root = new Context()
   const first = root.plugin(instance, chosen)
   await first.await()
@@ -83,14 +107,19 @@ export async function createApp(
       // Runtime values the manifest cannot hold: the manifest's own digest (every task records it), and who may install.
       tasks: { manifest: `sha256:${manifest.digest}` },
       // The `approval` parameter in blend.yaml (the extensions row) turns this source into one that asks.
-      extensions: { sources: [{ dir: extensionsDir, trust: 'install' }] },
+      extensions: {
+        sources: [
+          { dir: extensionsDir, trust: 'install' },
+          ...(legacy ? [{ dir: legacyDir, trust: 'install' as const }] : []),
+        ],
+      },
       builder: { dir: extensionsDir },
       server: { port: chosen.port.start, scan: chosen.port.scan ? 20 : 0, hostname: chosen.host },
     })),
   ]
   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/main.ts

@@ -1,7 +1,7 @@
 import { fileURLToPath } from 'node:url'
+import { selectInstance } from '../plugins/instance/index.ts'
+import { modelConfigFrom } from '../plugins/openai/index.ts'
 import { createApp } from './app.ts'
-import { selectInstance } from './plugins/instance/index.ts'
-import { modelConfigFrom } from './plugins/openai/index.ts'
 import { APP_NAME } from './routes.ts'
 
 // The composition root: the one place that reads the environment. selectInstance chooses where the app lives;

package/templates/agent/src/routes.ts

@@ -1,12 +1,18 @@
 import type { Context } from '@deepseek-ai/cordis'
-import { Acryl } from './plugins/acryl-router/src/index.ts'
-import { bodyLimit } from './plugins/acryl-router/src/middleware/index.ts'
-import type {} from './plugins/agent/index.ts'
-import type {} from './plugins/extensions/index.ts'
-import type {} from './plugins/tasks/index.ts'
+import { Acryl } from '../plugins/acryl-router/src/index.ts'
+import { bodyLimit } from '../plugins/acryl-router/src/middleware/index.ts'
+import type {} from '../plugins/agent/index.ts'
+import type {} from '../plugins/extensions/index.ts'
+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({

package/templates/agent/template.json

@@ -11,6 +11,7 @@
     "extensions",
     "builder",
     "manifest",
-    "save"
+    "save",
+    "acryl-door"
   ]
 }

package/templates/agent/test/agent.test.ts

@@ -1,17 +1,23 @@
 import assert from 'node:assert/strict'
+import { mkdirSync } from 'node:fs'
 import { mkdtemp, rm } from 'node:fs/promises'
-import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { test } from 'node:test'
 import { fileURLToPath } from 'node:url'
+import { pinnedInstance, withPort } from '../plugins/instance/index.ts'
 import { type App, createApp } from '../src/app.ts'
-import { pinnedInstance, withPort } from '../src/plugins/instance/index.ts'
+
+/** Throwaway homes live inside the project (`.acrylblends/` is ignored by git): a sandboxed agent may not write to the system temp folder. */
+const scratch = join(fileURLToPath(new URL('..', import.meta.url)), '.acrylblends', 'test')
+mkdirSync(scratch, { recursive: true })
 
 const projectRoot = fileURLToPath(new URL('..', import.meta.url))
 
 async function withApp(run: (app: App) => Promise<void>) {
-  const home = await mkdtemp(join(tmpdir(), 'agent-test-'))
-  const app = await createApp(withPort(pinnedInstance(home, { root: projectRoot }), 0))
+  const home = await mkdtemp(join(scratch, 'agent-test-'))
+  const app = await createApp(withPort(pinnedInstance(home, { root: projectRoot }), 0), {
+    listen: false,
+  })
   try {
     await run(app)
   } finally {
@@ -21,7 +27,7 @@ async function withApp(run: (app: App) => Promise<void>) {
 }
 
 const ask = (app: App, body: unknown) =>
-  fetch(`${app.url}/ask`, {
+  app.root.router.request(`/ask`, {
     method: 'POST',
     headers: { 'content-type': 'application/json' },
     body: JSON.stringify(body),