acrylblends 1.1.0 → 1.2.0

package/shared/skills/cordis-plugin/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: cordis-plugin
+description: Add a Cordis plugin to __APP_NAME__ - a plugins/<name>/ folder with name, inject, apply and an optional check, its routes as an Acryl app, how its blend.yaml row mounts it, and how to verify it. Use when a feature should be its own plugin, or when asked to extend the app.
+---
+
+# Adding a Cordis plugin
+
+A plugin is a folder `plugins/<name>/` with an `index.ts` exporting `name` (its id), `inject` (the services it needs) and `apply(ctx)`. Everything it acquires belongs to one `ctx.effect(...)`, so unloading the plugin or stopping the app releases it.
+
+```ts
+import type { Context } from '@deepseek-ai/cordis'
+import { Acryl } from 'acrylblends'
+
+export const name = 'due-dates'
+export const inject = ['router']
+
+export function apply(ctx: Context): void {
+  const app = new Acryl().get('/due-dates', (c) => c.json({ ok: true }))
+  ctx.router.route('/due-dates', app)
+}
+```
+
+- **Routes** are an `Acryl` app mounted with `ctx.router.route('/due-dates', app)`; removing the plugin removes them. Write the app's own path: the frame that hosts the app in development adds its canvas prefix, so the same route answers `/due-dates` under `npm start` and `/app/due-dates` in the canvas. Never put the frame's prefix in a plugin's route. Import the framework by name (`acrylblends`, `acrylblends/body-limit`); never guess a relative path into another plugin.
+- **State** lives in cells: `ctx.state.cell('due-dates.tasks', [])`. A page follows one with `watch` from `/api/state/client.js`, never with an `EventSource`, and never by polling what `watch` already pushes.
+- **Its row starts it.** Add a row to `blend.yaml` (`- id: <name>` and `name: <name>`, before the `acryl-node-server` row); `src/app.ts` finds the folder by that name, so it is never imported there. `disabled: true` on the row switches it off (Settings > Plugins does the same). `.acryl/bin/acryl plugin add plugins/<name>` installs a folder without a row live, for trying it; a folder with a row is the app's.
+- **Check it.** `npm test` and `npm run check` must pass. With the app running, use the door: `.acryl/bin/acryl look` reads the page as text with refs and `acryl act ...` acts on it; an install or reload shows the new feature in the page.

package/templates/agent/AGENTS.md

@@ -5,7 +5,7 @@ Besides `src/routes.ts`, the app runs an agent (`POST /ask`) that can write plug
 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`.
 
-**Write an extension, not a row.** A feature you build while the app runs is a folder `plugins/<name>/` installed with `.acryl/bin/acryl plugin add plugins/<name>` (the `extensions` plugin loads it again at every start). Add a row to `blend.yaml` and an entry to the `registry` of `src/app.ts` only when the person asks for a plugin that is part of the app itself. Both kinds may import the framework by name (`acrylblends`, `acrylblends/body-limit`, `acryl-router`); a row's relative imports of its sibling plugins also work.
+**Write an extension, not a row.** A feature you build while the app runs is a folder `plugins/<name>/` installed with `.acryl/bin/acryl plugin add plugins/<name>` (the `extensions` plugin loads it again at every start). Add a row to `blend.yaml` (`- id: <name>` / `name: <name>`; `src/app.ts` finds the folder by that name) only when the person asks for a plugin that is part of the app itself. Both kinds may import the framework by name (`acrylblends`, `acrylblends/body-limit`, `acryl-router`); a row's relative imports of its sibling plugins also work.
 
 **Drive the app you build.** `.acryl/bin/acryl look` reads the open page as text with refs, and `acryl act click|type|press|scroll|wait --ref <ref>` presses its buttons, opens its sidebars and fills its forms (look again before each act: the refs change). `act navigate --path /settings` goes to another page of the app; a path the app does not serve answers `404 at /nope` and the window shows a 404 page, so navigate on from there. In the desktop app (`npm run desktop`) the app's windows and menu are verbs too: `acryl window list`, `acryl window open --path /settings`, `acryl look --window <id>` (and `act ... --window <id>`) to drive that window's page, `acryl window resize|focus|close --id <id>`, `acryl menu list` and `acryl menu click --path "File>New Note"`. Closing the last window and Quit end the desktop app, so they need `--force`: do not use it unless the person asks. The app has a `/settings` page already (the appearance: system, light or dark, kept in the browser) and the desktop app's menu has a Settings item that opens it; add a person's other settings to that page, not to a new one, so `acryl menu click --path "File>Settings..."` and `acryl window open --path /settings` keep opening them (on macOS the item is in the application menu). Without a desktop app these answer "no desktop window is attached; run npm run desktop".
 

package/templates/agent/blend.yaml

@@ -24,10 +24,13 @@ spec:
       name: tasks
       config:
         store: "{{parameters.taskStore}}"
+    # The model the agent asks at each step: a scripted offline one until a provider key is set.
     - id: model
       name: model
+    # The tools the agent can call, each with what it does and the input it takes.
     - id: tools
       name: tools
+    # Long-term memory for the agent.
     - id: memory
       name: memory
     - id: agent
@@ -51,6 +54,7 @@ spec:
     # The panel: a chat button on every page in development (the app's own agent, or Codex, Claude or pi started in this folder). It starts nothing in production.
     - id: agent-panel
       name: agent-panel
+    # The app's own pages and API.
     - id: routes
       name: routes
     - id: server

package/templates/agent/gitignore

@@ -1,3 +1,4 @@
 node_modules/
 .acrylblends/
 .acryl/
+package-lock.json

package/templates/agent/package.json

@@ -16,6 +16,7 @@
     "test": "node --import ./plugins/acryl-node-server/src/register.ts --test \"test/**/*.test.{ts,tsx}\"",
     "check": "tsc --noEmit",
     "lock": "node plugins/manifest/lock.ts",
+    "snapshot": "node plugins/manifest/snapshot.ts",
     "save": "node plugins/save/cli.ts",
     "upgrade": "node plugins/manifest/upgrade-cli.ts"
   },

package/templates/agent/src/app.ts

@@ -6,22 +6,24 @@ 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 { agent, memory, model, scripted, tools } from '../plugins/agent/index.ts'
 import * as panel from '../plugins/agent-panel/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 {
+  appPluginNames,
   blueprintsIn,
   compose,
+  loadAppPlugins,
   loadManifest,
   type ParameterValue,
 } from '../plugins/manifest/index.ts'
-import { type OpenAIConfig, openai } from '../plugins/openai/index.ts'
+import { ASSISTANT_PROMPT, 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'
+import { FRAME_MOUNT_PREFIX, routes } from './routes.ts'
 
 /** The plugins this app's code provides. `blend.yaml` chooses, orders and configures them. */
 export const registry = {
@@ -44,6 +46,8 @@ export const registry = {
 
 /** The manifest next to this app's source. */
 export const MANIFEST = join(fileURLToPath(new URL('..', import.meta.url)), 'blend.yaml')
+/** The app's own plugins (a feature each), which `blend.yaml` mounts by their folder name next to the library copies `registry` imports. */
+const PLUGINS_DIR = join(fileURLToPath(new URL('..', import.meta.url)), 'plugins')
 
 /**
  * The app's manifest, resolved. A Blend finds its Blueprint in `blueprints/<id>.yaml`; an app that is itself a Blueprint never looks.
@@ -51,7 +55,7 @@ export const MANIFEST = join(fileURLToPath(new URL('..', import.meta.url)), 'ble
  */
 export function readManifest(values?: Readonly<Record<string, ParameterValue>>) {
   return loadManifest(MANIFEST, {
-    known: Object.keys(registry),
+    known: [...Object.keys(registry), ...appPluginNames(PLUGINS_DIR)],
     getBlueprint: blueprintsIn(join(fileURLToPath(new URL('..', import.meta.url)), 'blueprints')),
     ...(values ? { values } : {}),
   })
@@ -77,28 +81,61 @@ const DEVELOPMENT_ROWS: Record<string, string> = {
     'a plugin installed live runs in this process, and POST /extensions/approve decides installs',
 }
 
+/** The only tools the production Assistant's agent may call: look at the page and act on it. */
+const ASSISTANT_TOOLS = ['door_look', 'door_act']
+
+/** The most tokens one answer of the Assistant's model may use: with the step budget, what one visitor's question can cost at most. */
+const ASSISTANT_MAX_TOKENS = 1024
+
+/** Model calls per visitor question: look, open a page, look, filter, look and answer is six, with room for one wrong turn. */
+const ASSISTANT_STEPS = 10
+
+/** What the Assistant says while the app has no model: the scripted one cannot use the page. */
+export const ASSISTANT_NO_MODEL =
+  "This assistant is not set up yet: the app's owner has not chosen a model for it."
+
 /**
- * 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.
+ * The app's rows in the manifest's order, composed into `ctx`: the app's own server calls this from `createApp`, and the generated frame layer mounts it
+ * as one row, so the frame runs the app exactly as the app's own server does (same rows, same order, same config). `host: true` leaves the server and the
+ * door to the frame host, which mounts its own.
  */
-export async function createApp(
+export async function composeInto(
+  ctx: Context,
   chosen: AppInstance,
   options: {
     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
+    host?: boolean
   } = {},
-): Promise<App> {
+): Promise<Fiber[]> {
   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 listen = options.listen !== false && options.host !== true
   const leaveOut = new Set<string>()
   let extensionsReadOnly = false
-  if (!listen) leaveOut.add('acryl-node-server').add('acryl-door')
-  if (process.env.NODE_ENV === 'production' || process.env.ACRYL_DOOR === 'off')
+  // In the frame host the infrastructure rows are the host's own (its server, its web-server port, its router, the app instance, the door): the app
+  // contributes only the plugins that are its own.
+  if (!listen || options.host === true) leaveOut.add('acryl-node-server').add('acryl-door')
+  if (options.host === true)
+    for (const row of [
+      'instance',
+      'acryl-router',
+      'acryl-web-server',
+      'acryl-page',
+      'manifest',
+      'save',
+    ])
+      leaveOut.add(row)
+  // The Assistant (production, ACRYL_ASSISTANT=on): the agent panel docked for the app's visitors. Its agent keeps only the page tools and the door only the page,
+  // so it uses the app for a visitor (opens pages, filters, fills in forms) and cannot change the app, its code or its secrets. Not in the frame host.
+  const assistant =
+    process.env.NODE_ENV === 'production' &&
+    process.env.ACRYL_ASSISTANT === 'on' &&
+    process.env.ACRYL_DOOR !== 'off' &&
+    listen
+  if (!assistant && (process.env.NODE_ENV === 'production' || process.env.ACRYL_DOOR === 'off'))
     leaveOut.add('acryl-door')
   // Production: the rows that give a visitor power over the running app or the owner's model key are left out too. The agent (`POST /ask` spends the model key and runs tools),
   // the builder and the extensions (live plugin install runs code in this process, and `POST /extensions/approve` decides it) are development tools. `ACRYL_PRODUCTION_KEEP`
@@ -121,7 +158,7 @@ export async function createApp(
           `WARNING: the "${row}" row runs in production because ACRYL_PRODUCTION_KEEP names it: ${danger}. Nothing here is behind a login; put the app behind your own.`,
         )
       else if (row === 'extensions') extensionsReadOnly = true
-      else leaveOut.add(row)
+      else if (!(assistant && row === 'agent')) leaveOut.add(row)
     }
   }
   const manifest = {
@@ -136,31 +173,111 @@ export async function createApp(
     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()
+  // The Assistant's model is told it helps a visitor through the page alone, and each answer is capped, unless the app's model configuration says otherwise.
+  const modelConfig =
+    options.model && assistant
+      ? {
+          ...options.model,
+          system: options.model.system ?? ASSISTANT_PROMPT,
+          maxTokens: options.model.maxTokens ?? ASSISTANT_MAX_TOKENS,
+        }
+      : options.model
+  if (assistant && !options.model)
+    console.warn(
+      `WARNING: the Assistant has no model, so it answers every visitor "${ASSISTANT_NO_MODEL}" Set the app's model (ACRYLBLENDS_MODEL_URL and ACRYLBLENDS_MODEL, or model.json in the app's home).`,
+    )
+  // The rows that name one of the app's own plugin folders (a feature: plugins/<name>/ and its row) rather than a registry import. Each one that runs
+  // is imported here; all of them, off or on, belong to their row, so the extensions row never starts them a second time.
+  const ownRows = [
+    ...new Set(read.plugins.map((row) => row.use).filter((use) => !Object.hasOwn(registry, use))),
+  ]
+  const ownPlugins = await loadAppPlugins(
+    PLUGINS_DIR,
+    ownRows.filter((use) => manifest.plugins.some((row) => row.use === use && !row.disabled)),
+  )
   const fibers: Fiber[] = [
-    first,
     // The `model` row mounts the scripted model, or the real one when a model is configured.
-    ...(await compose(root, manifest, options.model ? { ...registry, model: openai } : registry, {
-      ...(options.model ? { model: { ...options.model } } : {}),
-      // 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: {
-        ...(extensionsReadOnly ? { readOnly: true } : {}),
-        sources: [
-          { dir: extensionsDir, trust: 'install' },
-          ...(legacy ? [{ dir: legacyDir, trust: 'install' as const }] : []),
-        ],
+    ...(await compose(
+      ctx,
+      manifest,
+      { ...registry, ...ownPlugins, ...(modelConfig ? { model: openai } : {}) },
+      {
+        ...(modelConfig ? { model: { ...modelConfig } } : {}),
+        // 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: {
+          ...(extensionsReadOnly ? { readOnly: true } : {}),
+          sources: [
+            { dir: extensionsDir, trust: 'install' },
+            ...(legacy ? [{ dir: legacyDir, trust: 'install' as const }] : []),
+          ],
+          rows: ownRows,
+        },
+        builder: { dir: extensionsDir },
+        ...(assistant
+          ? {
+              // Every answer comes right after a look, so it says what the visitor's page shows now.
+              agent: { tools: ASSISTANT_TOOLS, steps: ASSISTANT_STEPS, answerAfter: 'door_look' },
+              'acryl-door': { pageOnly: true },
+              'agent-panel': { assistant: true },
+              // The visitor reaches the agent through the panel only: no /ask, /tasks or /extensions routes.
+              routes: { agentRoutes: false },
+            }
+          : {}),
+        // The rows that serve routes of their own mount them under the app's prefix, as makeApp does. On the app's own server that prefix is the root (the
+        // row's default); the frame host serves the app at FRAME_MOUNT_PREFIX, and its own `/api` routes would answer for a row left at the root. The
+        // app's own routes row takes the same prefix for its mount and for the absolute URLs its pages write, so the page and its assets answer at `/app`.
+        ...(options.host === true
+          ? {
+              'agent-panel': { mount: FRAME_MOUNT_PREFIX },
+              'driver-pty': { mount: FRAME_MOUNT_PREFIX },
+              feedback: { mount: FRAME_MOUNT_PREFIX },
+              routes: { prefix: FRAME_MOUNT_PREFIX, ...(assistant ? { agentRoutes: false } : {}) },
+            }
+          : {}),
+        // The frame host runs the server itself and its app instance carries no port; only the app's own server configures one.
+        ...(options.host === true
+          ? {}
+          : {
+              server: {
+                port: chosen.port.start,
+                scan: chosen.port.scan ? 20 : 0,
+                hostname: chosen.host,
+              },
+            }),
       },
-      builder: { dir: extensionsDir },
-      server: { port: chosen.port.start, scan: chosen.port.scan ? 20 : 0, hostname: chosen.host },
-    })),
+    )),
   ]
+  // Without a model the scripted one would echo the visitor's words back: it says in one sentence that the Assistant is not set up.
+  if (assistant && !options.model)
+    scripted(ctx.get('model') as Parameters<typeof scripted>[0])?.teach(() => ({
+      text: ASSISTANT_NO_MODEL,
+    }))
+  return fibers
+}
+
+/**
+ * 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(
+  chosen: AppInstance,
+  options: {
+    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 root = new Context()
+  const first = root.plugin(instance, chosen)
+  await first.await()
+  const fibers: Fiber[] = [first, ...(await composeInto(root, chosen, options))]
   return {
     root,
-    url: listen ? root.nodeServer.url : '',
+    url: options.listen === false ? '' : root.nodeServer.url,
     async stop() {
       for (const fiber of [...fibers].reverse()) await fiber.dispose()
     },

package/templates/agent/src/frame.ts

@@ -0,0 +1,17 @@
+/**
+ * The app as the ACRYL frame hosts it (`npm run dev`): the generated layer mounts this row, which claims {@link FRAME_MOUNT_PREFIX} on the frame's web
+ * server. The app's own rows (the generated `app-plugins` row, which calls `composeInto`) mount the app at that prefix, so its pages and its routes
+ * answer at `/app`. Nothing here runs in production: `npm start` composes the app on its own server (no `routerHttp` service, so this row is not
+ * mounted there), where the routes are at the root as they always were.
+ */
+import type { Context } from '@deepseek-ai/cordis'
+import { FRAME_MOUNT_PREFIX } from './routes.ts'
+
+export const name = 'app-routes'
+
+/** The frame always has it: its layer carries the web adapter. */
+export const inject = ['routerHttp']
+
+export function apply(ctx: Context): void {
+  ctx.routerHttp.mount(FRAME_MOUNT_PREFIX)
+}

package/templates/agent/src/main.ts

@@ -1,16 +1,18 @@
+import { join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { selectInstance } from '../plugins/instance/index.ts'
-import { modelConfigFrom } from '../plugins/openai/index.ts'
+import { MODEL_FILE, modelConfigFrom, modelConfigFromFile } from '../plugins/openai/index.ts'
 import { createApp } from './app.ts'
 import { APP_NAME } from './routes.ts'
 
 // The composition root: the one place that reads the environment. selectInstance chooses where the app lives;
-// modelConfigFrom picks a real model when ACRYLBLENDS_MODEL_URL and ACRYLBLENDS_MODEL are set (ACRYLBLENDS_MODEL_KEY for hosted APIs).
+// modelConfigFrom picks a real model when ACRYLBLENDS_MODEL_URL and ACRYLBLENDS_MODEL are set (ACRYLBLENDS_MODEL_KEY for hosted APIs); without them, the model kept in the app's
+// home (model.json, readable by its owner only) is used, so a started app needs no flag.
 const chosen = selectInstance({
   projectRoot: fileURLToPath(new URL('..', import.meta.url)),
   env: process.env,
 })
-const model = modelConfigFrom(process.env)
+const model = modelConfigFrom(process.env) ?? modelConfigFromFile(join(chosen.home, MODEL_FILE))
 const app = await createApp(chosen, model ? { model } : {})
 console.log(
   `${APP_NAME} listening on ${app.url} (data in ${chosen.home}; model: ${model ? `${model.model} at ${model.baseUrl}` : 'offline scripted'})`,

package/templates/agent/src/routes.ts

@@ -7,6 +7,9 @@ import type {} from '../plugins/tasks/index.ts'
 
 export const APP_NAME = '__APP_NAME__'
 
+/** The only place the app's mount prefix is named: the root on its own server (`npm start`), `/app` when the ACRYL frame hosts it (`npm run dev`). */
+export const FRAME_MOUNT_PREFIX = '/app'
+
 /** 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'
@@ -50,43 +53,59 @@ const APPEARANCE_JS = `(function () {
 /** The home and settings pages' own layout; their colours come from /appearance.js. */
 const APPEARANCE_STYLE =
   '<style>body{font:16px system-ui,sans-serif;margin:2rem auto;max-width:42rem;padding:0 1rem}a{color:inherit}</style>'
-const APPEARANCE_SCRIPT = '<script src="/appearance.js"></script>'
+const appearanceScript = (prefix: string) => `<script src="${prefix}/appearance.js"></script>`
 
 /** `/settings`: the one setting the template has, the appearance. The desktop app's Settings menu item opens this page. */
-const settingsPage = `<!doctype html><html lang="en"><head><meta charset="utf-8"><title>Settings - ${APP_NAME}</title>${APPEARANCE_STYLE}${APPEARANCE_SCRIPT}</head><body><h1>Settings</h1><p><label for="theme">Appearance</label> <select id="theme" name="theme"><option value="system">Match the system</option><option value="light">Light</option><option value="dark">Dark</option></select></p><p id="saved" role="status"></p><p><a href="/">Back to ${APP_NAME}</a></p><script>(function(){var select=document.getElementById('theme'),saved=document.getElementById('saved');try{select.value=localStorage.getItem('theme')||'system'}catch(e){}select.addEventListener('change',function(){var value=select.value;try{if(value==='system'){localStorage.removeItem('theme');delete document.documentElement.dataset.theme}else{localStorage.setItem('theme',value);document.documentElement.dataset.theme=value}saved.textContent='Saved: '+select.options[select.selectedIndex].text}catch(e){saved.textContent='This browser would not keep the setting.'}})})()</script></body></html>`
+const settingsPage = (prefix: string) =>
+  `<!doctype html><html lang="en"><head><meta charset="utf-8"><title>Settings - ${APP_NAME}</title>${APPEARANCE_STYLE}${appearanceScript(prefix)}</head><body><h1>Settings</h1><p><label for="theme">Appearance</label> <select id="theme" name="theme"><option value="system">Match the system</option><option value="light">Light</option><option value="dark">Dark</option></select></p><p id="saved" role="status"></p><p><a href="${prefix}/">Back to ${APP_NAME}</a></p><script>(function(){var select=document.getElementById('theme'),saved=document.getElementById('saved');try{select.value=localStorage.getItem('theme')||'system'}catch(e){}select.addEventListener('change',function(){var value=select.value;try{if(value==='system'){localStorage.removeItem('theme');delete document.documentElement.dataset.theme}else{localStorage.setItem('theme',value);document.documentElement.dataset.theme=value}saved.textContent='Saved: '+select.options[select.selectedIndex].text}catch(e){saved.textContent='This browser would not keep the setting.'}})})()</script></body></html>`
 
-export const routes = {
-  name: 'routes',
-  inject: ['router'],
-  apply(ctx: Context) {
-    // A body here is a name, an id or a question; anything bigger is refused before it is read.
-    const json = async (c: {
-      req: { json(): Promise<unknown> }
-    }): Promise<Record<string, unknown>> => {
-      const body = await c.req.json().catch(() => undefined)
-      return typeof body === 'object' && body !== null ? (body as Record<string, unknown>) : {}
-    }
-    const limit = bodyLimit({ maxSize: 64 * 1024 })
-    const base = new Acryl()
+/**
+ * The app's own pages and routes, mountable at any prefix: the standalone server mounts it at the root, the frame row at {@link FRAME_MOUNT_PREFIX}.
+ * Every absolute URL a page writes is derived from the prefix it is mounted at.
+ */
+export function makeApp(prefix = ''): Acryl {
+  const limit = bodyLimit({ maxSize: 64 * 1024 })
+  return (
+    new Acryl()
       .use(limit)
       // 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>${APPEARANCE_STYLE}${APPEARANCE_SCRIPT}</head><body><h1>${APP_NAME}</h1><p>This app runs an agent unless it is switched off (production switches it off, see ACRYL_PRODUCTION_KEEP in AGENTS.md). Ask it for a feature in the agent panel on this page (or with <code>POST /ask</code>).</p>${DOOR_TAG}</body></html>`,
+              `<!doctype html><html lang="en"><head><meta charset="utf-8"><title>${APP_NAME}</title>${APPEARANCE_STYLE}${appearanceScript(prefix)}</head><body><h1>${APP_NAME}</h1><p>This app runs an agent unless it is switched off (production switches it off, see ACRYL_PRODUCTION_KEEP in AGENTS.md). In ACRYL, ask it for a change in the chat beside the app (or with <code>POST /ask</code>); published with the assistant on, it helps visitors use the app without changing it.</p>${DOOR_TAG}</body></html>`,
             )
           : c.json({ app: APP_NAME, ok: true }),
       )
       .get('/health', (c) => c.json({ ok: true }))
-      .get('/settings', (c) => c.html(settingsPage))
+      .get('/settings', (c) => c.html(settingsPage(prefix)))
       .get('/appearance.js', (c) =>
         c.body(APPEARANCE_JS, 200, {
           'content-type': 'text/javascript; charset=utf-8',
           'cache-control': 'no-cache',
         }),
       )
-    ctx.router.route('/', base)
+  )
+}
+
+/** The app's own routes: an `App` mounted on the router at `options.prefix` (empty or absent: the root). */
+export const routes = {
+  name: 'routes',
+  inject: ['router'],
+  apply(ctx: Context, options: { readonly prefix?: string; readonly agentRoutes?: boolean } = {}) {
+    const prefix = options.prefix ?? ''
+    // A body here is a name, an id or a question; anything bigger is refused before it is read.
+    const json = async (c: {
+      req: { json(): Promise<unknown> }
+    }): Promise<Record<string, unknown>> => {
+      const body = await c.req.json().catch(() => undefined)
+      return typeof body === 'object' && body !== null ? (body as Record<string, unknown>) : {}
+    }
+    const limit = bodyLimit({ maxSize: 64 * 1024 })
+    // The app's own page and routes at the one prefix; the agent routes below mount at the same prefix.
+    ctx.router.route(prefix === '' ? '/' : prefix, makeApp(prefix))
     // The routes that give a visitor the agent: mounted only while the agent, the extensions and the tasks run (see the header).
+    // `agentRoutes: false` (the production Assistant) keeps them unmounted although the agent runs.
+    if (options.agentRoutes === false) return
     ctx.inject(['agent', 'extensions', 'tasks'], (inner) => {
       const app = new Acryl().use(limit).get('/extensions', (c) =>
         c.json({
@@ -120,7 +139,7 @@ export const routes = {
             return c.json({ error: 'question must be a string' }, 400)
           return c.json(await inner.agent.run(question))
         })
-      inner.router.route('/', app)
+      inner.router.route(prefix === '' ? '/' : prefix, app)
     })
   },
 }

package/templates/agent/template.json

@@ -4,6 +4,8 @@
     "acryl-router",
     "acryl-state",
     "acryl-node-server",
+    "acryl-page",
+    "acryl-web-server",
     "tasks",
     "agent",
     "openai",

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

@@ -45,10 +45,24 @@ test('answers health checks and 404 for unknown paths', () =>
   }))
 
 /** A sandbox may forbid listening on a port (Codex's workspace-write does); the one test that starts the real server is skipped there, and says so. */
+/**
+ * Whether this environment forbids listening at all: only a sandbox's refusal (EPERM/EACCES) means the real-server test must skip. A loaded
+ * machine can fail a bind transiently, so that is retried briefly; any other outcome lets the real test run, where a host that truly cannot
+ * listen fails loudly instead of hiding behind a skip.
+ */
 const canListen = await new Promise<boolean>((done) => {
-  const probe = createServer()
-  probe.once('error', () => done(false))
-  probe.listen(0, '127.0.0.1', () => probe.close(() => done(true)))
+  let attempts = 0
+  const probeOnce = (): void => {
+    attempts += 1
+    const probe = createServer()
+    probe.once('error', (error: NodeJS.ErrnoException) => {
+      if (error.code === 'EPERM' || error.code === 'EACCES') done(false)
+      else if (attempts < 3) setTimeout(probeOnce, 100)
+      else done(true)
+    })
+    probe.listen(0, '127.0.0.1', () => probe.close(() => done(true)))
+  }
+  probeOnce()
 })
 const skip = canListen ? false : 'this environment does not allow listening on a port'
 if (!canListen)
@@ -200,3 +214,31 @@ test('the app has a /settings page with the appearance setting, and the home pag
     for (const listener of listeners) listener({ key: null })
     assert.equal(dataset.theme, undefined)
   }))
+
+test('the frame row mounts the same routes under /app; the app on its own server keeps its old URLs', () =>
+  inEnvironment({ NODE_ENV: 'test', ACRYL_PRODUCTION_KEEP: undefined }, async (app) => {
+    // The frame row claims that prefix on the frame's web adapter only; the app's own rows mount the routes there (the generated app-plugins row),
+    // so the frame row does not ask for the host router (127 app URLs).
+    const frame = await import('../src/frame.ts')
+    assert.deepEqual([...frame.inject].sort(), ['routerHttp'])
+    const { FRAME_MOUNT_PREFIX, routes } = await import('../src/routes.ts')
+    routes.apply(app.root, { prefix: FRAME_MOUNT_PREFIX })
+    for (const path of ['', '/health', '/settings', '/appearance.js']) {
+      const response = await app.root.router.request(`${FRAME_MOUNT_PREFIX}${path}`, {
+        headers: { accept: 'text/html' },
+      })
+      assert.equal(response.status, 200, path)
+      await response.body?.cancel()
+    }
+    // The page under the prefix writes its own URLs from it.
+    const page = await (
+      await app.root.router.request(`${FRAME_MOUNT_PREFIX}/settings`, {
+        headers: { accept: 'text/html' },
+      })
+    ).text()
+    assert.match(page, new RegExp(`src="${FRAME_MOUNT_PREFIX}/appearance.js"`, 'u'))
+    assert.match(page, new RegExp(`href="${FRAME_MOUNT_PREFIX}/"`, 'u'))
+    const missing = await app.root.router.request(`${FRAME_MOUNT_PREFIX}/nope`)
+    assert.equal(missing.status, 404)
+    await missing.body?.cancel()
+  }))

package/templates/blank/AGENTS.md

@@ -1,5 +1,6 @@
 
 ## This app (blank)
 
-`src/routes.ts` is the app's own plugin: add routes to its `App`. `blend.yaml` lists the plugins that are mounted. `acrylblends add <plugin>` copies
-another library plugin (for example `acryl-state`) into `plugins/`.
+The first screen (`src/routes.ts`) shows the app's name and, below it, the widget of every plugin that registers one with `ctx.home.widget`
+(the `home` row). A new feature is a plugin of its own with its row in `blend.yaml`, never a change to `src/routes.ts`. `acrylblends add <plugin>`
+copies another library plugin (for example `acryl-state`) into `plugins/`.

package/templates/blank/blend.yaml

@@ -15,9 +15,20 @@ spec:
   rows:
     - id: router
       name: acryl-router
+    # The home page's widgets: a feature plugin puts its UI on the home page with ctx.home.widget, and it leaves with the plugin.
+    - id: home
+      name: home
     - id: routes
       name: routes
+    # A feature is a plugin: its folder plugins/<name>/ plus a row of its own above this one (`- id: notes` / `name: notes`), which Settings > Plugins
+    # switches with `disabled: true`. This row starts the folders that have no row yet (a live install with `.acryl/bin/acryl plugin add`); a folder with
+    # a row is never started twice. Read-only when NODE_ENV=production.
+    - id: extensions
+      name: extensions
     - id: server
       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/blank/gitignore

@@ -1,3 +1,4 @@
 node_modules/
 .acrylblends/
 .acryl/
+package-lock.json

package/templates/blank/package.json

@@ -16,6 +16,7 @@
     "test": "node --import ./plugins/acryl-node-server/src/register.ts --test \"test/**/*.test.{ts,tsx}\"",
     "check": "tsc --noEmit",
     "lock": "node plugins/manifest/lock.ts",
+    "snapshot": "node plugins/manifest/snapshot.ts",
     "save": "node plugins/save/cli.ts",
     "upgrade": "node plugins/manifest/upgrade-cli.ts"
   },