acrylblends 1.0.0 → 1.0.1

package/docs/framework/guides/production.md

@@ -10,14 +10,17 @@
 | **The door** (`acryl-door`: `.acryl/bin/acryl`, the page script, the operator routes) | **experimental**: starts when the server is up | starts nothing: no service, no route, no `.acryl/` folder, no script in the page. `ACRYL_DOOR=off` also turns it off. A host that means to run it in production sets `allowInProduction: true` in the plugin's config |
 | **The agent panel** (`agent-panel`) | **experimental**: a script tag on every HTML page and `/api/agent-panel/*` | does nothing (no tag, no routes). `ACRYL_DOOR=off` too |
 | **The PTY driver** (`driver-pty`) | **experimental**: terminal drivers in the panel, `/api/driver-pty/*` | does nothing. `ACRYL_DOOR=off` too |
-| **Live plugin install** (`extensions`, `builder`) | **experimental**: install, update, remove and reload plugins while the app runs | the `nodejs`, `notes` and `chat` templates leave the `extensions` row out; the `agent` template does not (see below) |
+| **Live plugin install and the agent** (`extensions`, `builder`, `agent`: `POST /ask`) | **experimental**: install, update, remove and reload plugins while the app runs; the agent builds them | left out: the `nodejs`, `notes` and `chat` templates drop the `extensions` row, and the `agent` template drops `agent`, `builder` and `extensions` (since 1.0.1) unless `ACRYL_PRODUCTION_KEEP` names them |
 | `acrylblends/bun` | **experimental**: one smoke gate runs it on Bun | the same |
 
 Experimental means: it works and is gated, its interface may still change in a minor version, and it is not for the public internet. The door and the panel are loopback and own-page only, with a per-run secret and an audit log; that is a convenience fence for a developer's machine, not an authentication system.
 
-## The `agent` template is a development app
+## The `agent` template in production
 
-The `agent` template mounts an agent behind `POST /ask` that can write plugins into the running app (`builder`) and install them (`extensions`). Only its door is left out in production. Do not deploy it as it is: remove the `agent`, `builder` and `extensions` rows from `blend.yaml` (or start from `blank`, `nodejs`, `notes`, `chat` or `todo`), and if live install is wanted anywhere shared, set `approval: true` so an install waits for `POST /extensions/approve`.
+The `agent` template mounts an agent behind `POST /ask` that spends the model key and can write plugins into the running app (`builder`) and install them (`extensions`, with `POST /extensions/approve` deciding installs). **None of that is behind a login.** Since 1.0.1, with `NODE_ENV=production` the template leaves the `agent`, `builder` and `extensions` rows out, along with the door: `/ask`, `/extensions*` and `/tasks*` are not mounted, and the page and `GET /health` stay. 1.0.0 left them mounted.
+
+- To keep a row anyway, name it: `ACRYL_PRODUCTION_KEEP=agent,builder,extensions` (a comma list). Each row kept prints a `WARNING` line at start saying what it gives a visitor. Put your own login in front before you do.
+- **An app made by 1.0.0 keeps its own `src/app.ts` and `src/routes.ts`**, which `acrylblends upgrade` never touches (they are your files). Until you change them: deploy with the `agent`, `builder` and `extensions` rows set to `disabled: true` in `blend.yaml`, or start from another template, or copy the new `src/app.ts` and `src/routes.ts` of a fresh `acrylblends init my-app --template agent` over yours.
 
 ## What live plugin install does and does not promise
 
@@ -38,6 +41,6 @@ Installing a plugin (`ctx.extensions.install`, the door's `plugin add`, the buil
 ## Checklist for a deployment
 
 1. `NODE_ENV=production` (the process manager or the Dockerfile sets it; the templates' Dockerfile does).
-2. Start from a template that is not `agent`, or remove the agent rows.
+2. With the `agent` template, leave `ACRYL_PRODUCTION_KEEP` unset (1.0.1 and later), or remove the agent rows.
 3. Do not set `allowInProduction` on the door unless the host is a single-user desktop app.
 4. Keep `ACRYL_DOOR=off` in any environment where an agent should not be able to see the page.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "acrylblends",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "The Acryl web framework (import { Acryl } from \"acrylblends\") and the acrylblends command that scaffolds Cordis apps.",
   "license": "MIT",
   "type": "module",

package/templates/agent/AGENTS.md

@@ -4,3 +4,5 @@
 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`.
+
+**Production.** The agent, the builder and the extensions are development tools: `POST /ask` spends the model key and runs tools, a plugin installed live runs in this process, and none of it is behind a login. With `NODE_ENV=production` `src/app.ts` leaves those three rows out, so `/ask`, `/extensions*` and `/tasks*` are not mounted; the page and `GET /health` stay. `ACRYL_PRODUCTION_KEEP=agent,builder,extensions` keeps the named rows, and each one kept prints a `WARNING` line at start.

package/templates/agent/src/app.ts

@@ -62,6 +62,14 @@ export interface App {
   stop(): Promise<void>
 }
 
+/** The development rows production leaves out, and what each one gives a visitor. */
+const DEVELOPMENT_ROWS: Record<string, string> = {
+  agent: 'POST /ask runs the agent, which spends the model key and calls its tools',
+  builder: 'the agent can write plugin source into plugins/',
+  extensions:
+    'a plugin installed live runs in this process, and POST /extensions/approve decides installs',
+}
+
 /**
  * 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.
@@ -84,6 +92,29 @@ export async function createApp(
   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')
+  // 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`
+  // names the ones to keep (`agent,builder,extensions`); each one kept is announced at start, because none of them is behind a login.
+  if (process.env.NODE_ENV === 'production') {
+    const keep = new Set(
+      (process.env.ACRYL_PRODUCTION_KEEP ?? '')
+        .split(',')
+        .map((name) => name.trim())
+        .filter((name) => name !== ''),
+    )
+    for (const name of keep)
+      if (!(name in DEVELOPMENT_ROWS))
+        console.warn(
+          `WARNING: ACRYL_PRODUCTION_KEEP names "${name}", which is not one of ${Object.keys(DEVELOPMENT_ROWS).join(', ')}`,
+        )
+    for (const [row, danger] of Object.entries(DEVELOPMENT_ROWS)) {
+      if (keep.has(row))
+        console.warn(
+          `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 leaveOut.add(row)
+    }
+  }
   const manifest = {
     ...read,
     plugins: read.plugins.map((row) => (leaveOut.has(row.use) ? { ...row, disabled: true } : row)),

package/templates/agent/src/routes.ts

@@ -14,13 +14,14 @@ const DOOR_TAG =
     : ''
 
 /**
- * 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
- * `GET /api/state/extensions/events`. The mount is removed when the plugin is disposed.
+ * The app's own routes on the router. Always: the page and `GET /health`. While the agent, the extensions and the task recorder run: `POST /ask` for the agent; `GET /extensions`
+ * (and `POST /extensions/approve` and `/deny`) and `GET /tasks` to observe and steer 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 `GET /api/state/extensions/events`. In production `src/app.ts` leaves the agent, builder and extensions rows
+ * out (unless `ACRYL_PRODUCTION_KEEP` names them), and then those routes are not mounted at all. The mounts are removed when the plugin is disposed.
  */
 export const routes = {
   name: 'routes',
-  inject: ['router', 'agent', 'extensions', 'tasks'],
+  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: {
@@ -29,48 +30,54 @@ export const routes = {
       const body = await c.req.json().catch(() => undefined)
       return typeof body === 'object' && body !== null ? (body as Record<string, unknown>) : {}
     }
-    const app = new Acryl()
-      .use(bodyLimit({ maxSize: 64 * 1024 }))
+    const limit = bodyLimit({ maxSize: 64 * 1024 })
+    const base = 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></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>`,
+              `<!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 unless it is switched off (production switches it off, see ACRYL_PRODUCTION_KEEP in AGENTS.md). 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) =>
+    ctx.router.route('/', base)
+    // The routes that give a visitor the agent: mounted only while the agent, the extensions and the tasks run (see the header).
+    ctx.inject(['agent', 'extensions', 'tasks'], (inner) => {
+      const app = new Acryl().use(limit).get('/extensions', (c) =>
         c.json({
-          installed: ctx.extensions.list(),
-          notInstalled: ctx.extensions.pending(),
-          waitingForApproval: ctx.extensions.approvals(),
+          installed: inner.extensions.list(),
+          notInstalled: inner.extensions.pending(),
+          waitingForApproval: inner.extensions.approvals(),
         }),
       )
-    // The owner's decision on an install that is waiting (the `approval` parameter in blend.yaml).
-    for (const [path, decide] of [
-      ['/extensions/approve', (name: string) => ctx.extensions.approve(name)],
-      ['/extensions/deny', (name: string) => ctx.extensions.deny(name)],
-    ] as const) {
-      app.post(path, async (c) => {
-        const { name } = await json(c)
-        if (typeof name !== 'string') return c.json({ error: 'name must be a string' }, 400)
-        return c.json(await decide(name))
-      })
-    }
-    app
-      .get('/tasks', (c) => c.json(ctx.tasks.list().slice(0, 100)))
-      .post('/tasks/cancel', async (c) => {
-        const { id } = await json(c)
-        if (typeof id !== 'string' || !ctx.tasks.get(id))
-          return c.json({ error: 'no such task' }, 404)
-        return c.json({ cancelled: ctx.tasks.cancel(id) })
-      })
-      .post('/ask', async (c) => {
-        const { question } = await json(c)
-        if (typeof question !== 'string') return c.json({ error: 'question must be a string' }, 400)
-        return c.json(await ctx.agent.run(question))
-      })
-    ctx.router.route('/', app)
+      // The owner's decision on an install that is waiting (the `approval` parameter in blend.yaml).
+      for (const [path, decide] of [
+        ['/extensions/approve', (name: string) => inner.extensions.approve(name)],
+        ['/extensions/deny', (name: string) => inner.extensions.deny(name)],
+      ] as const) {
+        app.post(path, async (c) => {
+          const { name } = await json(c)
+          if (typeof name !== 'string') return c.json({ error: 'name must be a string' }, 400)
+          return c.json(await decide(name))
+        })
+      }
+      app
+        .get('/tasks', (c) => c.json(inner.tasks.list().slice(0, 100)))
+        .post('/tasks/cancel', async (c) => {
+          const { id } = await json(c)
+          if (typeof id !== 'string' || !inner.tasks.get(id))
+            return c.json({ error: 'no such task' }, 404)
+          return c.json({ cancelled: inner.tasks.cancel(id) })
+        })
+        .post('/ask', async (c) => {
+          const { question } = await json(c)
+          if (typeof question !== 'string')
+            return c.json({ error: 'question must be a string' }, 400)
+          return c.json(await inner.agent.run(question))
+        })
+      inner.router.route('/', app)
+    })
   },
 }

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

@@ -65,3 +65,77 @@ test('stops listening when stopped', { skip }, async () => {
   await assert.rejects(fetch(`${app.url}/health`))
   await rm(home, { recursive: true, force: true })
 })
+
+/** Boot in a given environment, with the warnings collected. */
+async function inEnvironment(
+  env: Record<string, string | undefined>,
+  run: (app: App, warnings: string[]) => Promise<void>,
+) {
+  const saved = Object.fromEntries(Object.keys(env).map((key) => [key, process.env[key]]))
+  const warnings: string[] = []
+  const warn = console.warn
+  console.warn = (message: unknown) => void warnings.push(String(message))
+  for (const [key, value] of Object.entries(env)) {
+    if (value === undefined) delete process.env[key]
+    else process.env[key] = value
+  }
+  try {
+    await withApp((app) => run(app, warnings))
+  } finally {
+    console.warn = warn
+    for (const [key, value] of Object.entries(saved)) {
+      if (value === undefined) delete process.env[key]
+      else process.env[key] = value
+    }
+  }
+}
+
+const asking = (app: App) =>
+  app.root.router.request('/ask', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ question: 'add 2 3' }),
+  })
+
+test('in production the agent, the builder and the extensions are left out: no /ask, no live install, no approve route; the page and /health stay', () =>
+  inEnvironment({ NODE_ENV: 'production', ACRYL_PRODUCTION_KEEP: undefined }, async (app) => {
+    assert.equal((await app.root.router.request('/health')).status, 200)
+    assert.equal((await app.root.router.request('/')).status, 200)
+    for (const [path, method] of [
+      ['/ask', 'POST'],
+      ['/extensions', 'GET'],
+      ['/extensions/approve', 'POST'],
+      ['/tasks', 'GET'],
+    ] as const) {
+      const response = await app.root.router.request(path, { method })
+      assert.equal(response.status, 404, `${method} ${path} answered ${response.status}`)
+      await response.body?.cancel()
+    }
+    assert.equal((app.root as unknown as { agent?: unknown }).agent, undefined)
+    assert.equal((app.root as unknown as { extensions?: unknown }).extensions, undefined)
+  }))
+
+test('ACRYL_PRODUCTION_KEEP keeps the named rows in production and says so at start; a name it does not know is reported', () =>
+  inEnvironment(
+    { NODE_ENV: 'production', ACRYL_PRODUCTION_KEEP: 'agent,extensions,nope' },
+    async (app, warnings) => {
+      const answer = await asking(app)
+      assert.equal(answer.status, 200)
+      assert.equal(((await answer.json()) as { status: string }).status, 'completed')
+      assert.equal((await app.root.router.request('/extensions')).status, 200)
+      assert.ok(
+        warnings.some((line) => line.includes('"agent" row runs in production')),
+        warnings.join('\n'),
+      )
+      assert.ok(warnings.some((line) => line.includes('"extensions" row runs in production')))
+      assert.ok(!warnings.some((line) => line.includes('"builder" row runs in production')))
+      assert.ok(warnings.some((line) => line.includes('names "nope"')))
+    },
+  ))
+
+test('outside production nothing changes: the agent answers and the extensions route is there', () =>
+  inEnvironment({ NODE_ENV: 'test', ACRYL_PRODUCTION_KEEP: undefined }, async (app, warnings) => {
+    assert.equal((await asking(app)).status, 200)
+    assert.equal((await app.root.router.request('/extensions')).status, 200)
+    assert.deepEqual(warnings, [])
+  }))