acrylblends 0.7.8 → 0.8.1

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'
 
+/** 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),

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

@@ -1,6 +1,7 @@
 import assert from 'node:assert/strict'
+import { mkdirSync } from 'node:fs'
 import { mkdtemp, rm } from 'node:fs/promises'
-import { tmpdir } from 'node:os'
+import { createServer } from 'node:net'
 import { join } from 'node:path'
 import { test } from 'node:test'
 import { fileURLToPath } from 'node:url'
@@ -8,12 +9,18 @@ import { pinnedInstance, withPort } from '../plugins/instance/index.ts'
 import { type App, createApp } from '../src/app.ts'
 import { APP_NAME } from '../src/routes.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))
 
 /** Boot the app in a throwaway home on any free port, run the test, always stop it and remove the home. */
 async function withApp(run: (app: App) => Promise<void>) {
-  const home = await mkdtemp(join(tmpdir(), 'app-test-'))
-  const app = await createApp(withPort(pinnedInstance(home, { root: projectRoot }), 0))
+  const home = await mkdtemp(join(scratch, 'app-test-'))
+  const app = await createApp(withPort(pinnedInstance(home, { root: projectRoot }), 0), {
+    listen: false,
+  })
   try {
     await run(app)
   } finally {
@@ -24,21 +31,35 @@ async function withApp(run: (app: App) => Promise<void>) {
 
 test('serves the index route', () =>
   withApp(async (app) => {
-    const response = await fetch(`${app.url}/`)
+    const response = await app.root.router.request(`/`)
     assert.equal(response.status, 200)
     assert.deepEqual(await response.json(), { app: APP_NAME, ok: true })
   }))
 
 test('answers health checks and 404 for unknown paths', () =>
   withApp(async (app) => {
-    assert.equal((await fetch(`${app.url}/health`)).status, 200)
-    const missing = await fetch(`${app.url}/nope`)
+    assert.equal((await app.root.router.request(`/health`)).status, 200)
+    const missing = await app.root.router.request(`/nope`)
     assert.equal(missing.status, 404)
     await missing.body?.cancel()
   }))
 
-test('stops listening when stopped', async () => {
-  const home = await mkdtemp(join(tmpdir(), 'app-test-'))
+/** 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. */
+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)))
+})
+const skip = canListen ? false : 'this environment does not allow listening on a port'
+if (!canListen)
+  console.log(
+    `skipped: the test that starts the real server (${skip}); every other test ran in process`,
+  )
+
+test('stops listening when stopped', { skip }, async () => {
+  const home = await mkdtemp(join(scratch, 'app-test-'))
+  // The door is left out (ACRYL_DOOR=off): one process at a time serves a folder's door.
+  process.env.ACRYL_DOOR = 'off'
   const app = await createApp(withPort(pinnedInstance(home, { root: projectRoot }), 0))
   await app.stop()
   await assert.rejects(fetch(`${app.url}/health`))

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

@@ -1,18 +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 { createApp } from '../src/app.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 })
+
 /** The agent extends the running app through POST /ask; a restart keeps what it built. */
 test('the agent builds, updates, protects and removes a plugin in the running app, and a restart keeps it', async () => {
-  const project = await mkdtemp(join(tmpdir(), 'builder-project-'))
+  const project = await mkdtemp(join(scratch, 'builder-project-'))
   const chosen = withPort(pinnedInstance(join(project, '.acrylblends'), { root: project }), 0)
-  let app = await createApp(chosen)
+  let app = await createApp(chosen, { listen: false })
   const ask = async (question: string) => {
-    const response = await fetch(`${app.url}/ask`, {
+    const response = await app.root.router.request(`/ask`, {
       method: 'POST',
       headers: { 'content-type': 'application/json' },
       body: JSON.stringify({ question }),
@@ -20,7 +25,7 @@ test('the agent builds, updates, protects and removes a plugin in the running ap
     return ((await response.json()) as { output: string }).output
   }
   const hello = async () => {
-    const response = await fetch(`${app.url}/hello`)
+    const response = await app.root.router.request(`/hello`)
     return response.status === 200
       ? ((await response.json()) as { text: string }).text
       : response.status
@@ -36,14 +41,14 @@ test('the agent builds, updates, protects and removes a plugin in the running ap
     // The broken version stays on disk, so put the working one back before restarting.
     await ask('update route hello /hello Bonjour')
     await app.stop()
-    app = await createApp(chosen)
+    app = await createApp(chosen, { listen: false })
     assert.equal(await hello(), 'Bonjour')
 
     assert.equal(await ask('remove plugin hello'), 'hello: done.')
     assert.equal(await hello(), 404)
 
     // Every run is a durable task that owns its tool calls, and the records survived the restart.
-    const records = (await (await fetch(`${app.url}/tasks`)).json()) as Array<{
+    const records = (await (await app.root.router.request(`/tasks`)).json()) as Array<{
       kind: string
       status: string
       parent?: string
@@ -63,12 +68,12 @@ test('the agent builds, updates, protects and removes a plugin in the running ap
 })
 
 test('with approval on, an install waits for the owner; approving it makes it live', async () => {
-  const project = await mkdtemp(join(tmpdir(), 'approval-project-'))
+  const project = await mkdtemp(join(scratch, 'approval-project-'))
   const chosen = withPort(pinnedInstance(join(project, '.acrylblends'), { root: project }), 0)
-  const app = await createApp(chosen, { values: { approval: true } })
+  const app = await createApp(chosen, { values: { approval: true }, listen: false })
   const post = async (path: string, body: unknown) =>
     (await (
-      await fetch(`${app.url}${path}`, {
+      await app.root.router.request(`${path}`, {
         method: 'POST',
         headers: { 'content-type': 'application/json' },
         body: JSON.stringify(body),
@@ -79,8 +84,8 @@ test('with approval on, an install waits for the owner; approving it makes it li
       (await post('/ask', { question: 'create route hello /hello Hello' })).output,
       "hello: waiting for the owner's approval.",
     )
-    assert.equal((await fetch(`${app.url}/hello`)).status, 404)
-    const listed = (await (await fetch(`${app.url}/extensions`)).json()) as {
+    assert.equal((await app.root.router.request(`/hello`)).status, 404)
+    const listed = (await (await app.root.router.request(`/extensions`)).json()) as {
       waitingForApproval: Array<{ name: string }>
     }
     assert.deepEqual(
@@ -91,8 +96,10 @@ test('with approval on, an install waits for the owner; approving it makes it li
       ((await post('/extensions/approve', { name: 'hello' })) as { state?: string }).state,
       'active',
     )
-    assert.deepEqual(await (await fetch(`${app.url}/hello`)).json(), { text: 'Hello' })
-    const tasks = (await (await fetch(`${app.url}/tasks`)).json()) as Array<{ manifest?: string }>
+    assert.deepEqual(await (await app.root.router.request(`/hello`)).json(), { text: 'Hello' })
+    const tasks = (await (await app.root.router.request(`/tasks`)).json()) as Array<{
+      manifest?: string
+    }>
     assert.ok(
       tasks.length > 0 && tasks.every((task) => /^sha256:[0-9a-f]{64}$/.test(task.manifest ?? '')),
     )
@@ -103,13 +110,13 @@ test('with approval on, an install waits for the owner; approving it makes it li
 })
 
 test('the agent builds a sandboxed tool, calls it, and the sandbox refuses a tool that reads outside its folder', async () => {
-  const project = await mkdtemp(join(tmpdir(), 'tool-project-'))
+  const project = await mkdtemp(join(scratch, 'tool-project-'))
   const chosen = withPort(pinnedInstance(join(project, '.acrylblends'), { root: project }), 0)
-  const app = await createApp(chosen)
+  const app = await createApp(chosen, { listen: false })
   const ask = async (question: string) =>
     (
       (await (
-        await fetch(`${app.url}/ask`, {
+        await app.root.router.request(`/ask`, {
           method: 'POST',
           headers: { 'content-type': 'application/json' },
           body: JSON.stringify({ question }),
@@ -121,7 +128,7 @@ test('the agent builds a sandboxed tool, calls it, and the sandbox refuses a too
     assert.equal(await ask('run tool triple 14'), '{"n":42}')
     const refused = await ask('spy tool snoop')
     assert.match(refused, /^Refused: its check failed: denied:/)
-    const listed = (await (await fetch(`${app.url}/extensions`)).json()) as {
+    const listed = (await (await app.root.router.request(`/extensions`)).json()) as {
       installed: Array<{ name: string }>
     }
     assert.deepEqual(
@@ -135,13 +142,13 @@ test('the agent builds a sandboxed tool, calls it, and the sandbox refuses a too
 })
 
 test('what happens is streamed from the state cells: the run as a task, and the install as an extension', async () => {
-  const project = await mkdtemp(join(tmpdir(), 'events-project-'))
+  const project = await mkdtemp(join(scratch, 'events-project-'))
   const chosen = withPort(pinnedInstance(join(project, '.acrylblends'), { root: project }), 0)
-  const app = await createApp(chosen)
+  const app = await createApp(chosen, { listen: false })
   const controller = new AbortController()
   /** Follow one server-sent stream: its text so far. */
   const follow = async (path: string) => {
-    const stream = await fetch(`${app.url}${path}`, { signal: controller.signal })
+    const stream = await app.root.router.request(`${path}`, { signal: controller.signal })
     assert.equal(stream.status, 200, path)
     const reader = stream.body!.getReader()
     const decoder = new TextDecoder()
@@ -153,12 +160,12 @@ test('what happens is streamed from the state cells: the run as a task, and the
         seen.text += decoder.decode(value, { stream: true })
       }
     })().catch(() => undefined)
-    return { seen, pump }
+    return { seen, pump, reader }
   }
   try {
     const tasksStream = await follow('/api/state/tasks/events')
     const extensionsStream = await follow('/api/state/extensions/events')
-    await fetch(`${app.url}/ask`, {
+    await app.root.router.request(`/ask`, {
       method: 'POST',
       headers: { 'content-type': 'application/json' },
       body: JSON.stringify({ question: 'create route hello /hello Hello' }),
@@ -185,7 +192,11 @@ test('what happens is streamed from the state cells: the run as a task, and the
       arrived(extensionsStream.seen, /"name":"hello"[^\n]*"state":"active"/),
       'the extension is reported',
     )
+    // In process there is no socket to close: the readers are cancelled, which ends the streams and lets the pumps finish.
     controller.abort()
+    await Promise.all([tasksStream.reader.cancel(), extensionsStream.reader.cancel()]).catch(
+      () => undefined,
+    )
     await Promise.all([tasksStream.pump, extensionsStream.pump])
   } finally {
     await app.stop()

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

@@ -1,16 +1,20 @@
 import assert from 'node:assert/strict'
+import { mkdirSync } from 'node:fs'
 import { mkdtemp, rm } from 'node:fs/promises'
-import { createServer } from 'node:http'
-import type { AddressInfo } from 'node:net'
-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 { createApp } from '../src/app.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 })
+
 /** A plugin no scripted command knows: the model writes it from scratch. */
 const COUNTER = `import type { Context } from '@deepseek-ai/cordis'
 import { Acryl } from 'acrylblends'
+
 export const name = 'counter'
 export const inject = ['router']
 export function apply(ctx: Context) {
@@ -45,42 +49,43 @@ async function modelApi() {
     },
     { content: 'I built a counter: GET /count.' },
   ]
-  const server = createServer(async (request, response) => {
-    for await (const _ of request) {
-      // the body is not needed: the replies are in order
-    }
-    response.writeHead(200, { 'content-type': 'application/json' })
-    response.end(
-      JSON.stringify({ choices: [{ message: replies.shift() ?? { content: 'no more' } }] }),
-    )
-  })
-  await new Promise<void>((done) => server.listen(0, '127.0.0.1', done))
+  // The model API is answered in process: the global fetch is wrapped for the model's address, so no port is needed.
+  const realFetch = globalThis.fetch
+  const url = 'http://model.test/v1'
+  globalThis.fetch = async (input, init) => {
+    const target = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url
+    if (!target.startsWith(url)) return realFetch(input, init)
+    return Response.json({ choices: [{ message: replies.shift() ?? { content: 'no more' } }] })
+  }
   return {
-    url: `http://127.0.0.1:${(server.address() as AddressInfo).port}/v1`,
-    close: () => new Promise<void>((done) => server.close(() => done())),
+    url,
+    close: async () => {
+      globalThis.fetch = realFetch
+    },
   }
 }
 
 test('with a real model, the agent writes a new Cordis plugin and the running app serves it', async () => {
   const api = await modelApi()
-  const project = await mkdtemp(join(tmpdir(), 'model-project-'))
+  const project = await mkdtemp(join(scratch, 'model-project-'))
   const app = await createApp(
     withPort(pinnedInstance(join(project, '.acrylblends'), { root: project }), 0),
     {
       model: { baseUrl: api.url, model: 'test' },
+      listen: false,
     },
   )
   try {
     const answer = await (
-      await fetch(`${app.url}/ask`, {
+      await app.root.router.request(`/ask`, {
         method: 'POST',
         headers: { 'content-type': 'application/json' },
         body: JSON.stringify({ question: 'add a counter route' }),
       })
     ).json()
     assert.equal((answer as { output: string }).output, 'I built a counter: GET /count.')
-    assert.deepEqual(await (await fetch(`${app.url}/count`)).json(), { count: 1 })
-    assert.deepEqual(await (await fetch(`${app.url}/count`)).json(), { count: 2 })
+    assert.deepEqual(await (await app.root.router.request(`/count`)).json(), { count: 1 })
+    assert.deepEqual(await (await app.root.router.request(`/count`)).json(), { count: 2 })
   } finally {
     await app.stop()
     await api.close()

package/templates/blank/src/app.ts

@@ -30,8 +30,19 @@ export function readManifest(values?: Readonly<Record<string, ParameterValue>>)
   })
 }
 
+/** The manifest without its server row: the app is then reached in process, through `root.router.request`. */
+function withoutServer<M extends { plugins: readonly { use: string }[] }>(manifest: M): M {
+  return {
+    ...manifest,
+    plugins: manifest.plugins.map((row) =>
+      row.use === 'acryl-node-server' ? { ...row, disabled: true } : row,
+    ),
+  }
+}
+
 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>
 }
@@ -39,7 +50,11 @@ export interface App {
 /** The app: `instance` first (where it lives, chosen at run time), then the manifest's rows in order. */
 export async function createApp(
   chosen: AppInstance,
-  options: { values?: Readonly<Record<string, ParameterValue>> } = {},
+  options: {
+    values?: Readonly<Record<string, ParameterValue>>
+    /** 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 root = new Context()
@@ -47,13 +62,18 @@ export async function createApp(
   await first.await()
   const fibers: Fiber[] = [
     first,
-    ...(await compose(root, manifest, registry, {
-      server: { port: chosen.port.start, scan: chosen.port.scan ? 20 : 0 },
-    })),
+    ...(await compose(
+      root,
+      options.listen === false ? withoutServer(manifest) : manifest,
+      registry,
+      {
+        server: { port: chosen.port.start, scan: chosen.port.scan ? 20 : 0 },
+      },
+    )),
   ]
   return {
     root,
-    url: root.nodeServer.url,
+    url: options.listen === false ? '' : root.nodeServer.url,
     async stop() {
       for (const fiber of [...fibers].reverse()) await fiber.dispose()
     },

package/templates/blank/test/app.test.ts

@@ -1,6 +1,7 @@
 import assert from 'node:assert/strict'
+import { mkdirSync } from 'node:fs'
 import { mkdtemp, rm } from 'node:fs/promises'
-import { tmpdir } from 'node:os'
+import { createServer } from 'node:net'
 import { join } from 'node:path'
 import { test } from 'node:test'
 import { fileURLToPath } from 'node:url'
@@ -8,12 +9,18 @@ import { pinnedInstance, withPort } from '../plugins/instance/index.ts'
 import { type App, createApp } from '../src/app.ts'
 import { APP_NAME } from '../src/routes.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))
 
 /** Boot the app in a throwaway home on any free port, run the test, always stop it and remove the home. */
 async function withApp(run: (app: App) => Promise<void>) {
-  const home = await mkdtemp(join(tmpdir(), 'app-test-'))
-  const app = await createApp(withPort(pinnedInstance(home, { root: projectRoot }), 0))
+  const home = await mkdtemp(join(scratch, 'app-test-'))
+  const app = await createApp(withPort(pinnedInstance(home, { root: projectRoot }), 0), {
+    listen: false,
+  })
   try {
     await run(app)
   } finally {
@@ -24,14 +31,14 @@ async function withApp(run: (app: App) => Promise<void>) {
 
 test('serves the index route', () =>
   withApp(async (app) => {
-    const response = await fetch(`${app.url}/`)
+    const response = await app.root.router.request(`/`)
     assert.equal(response.status, 200)
     assert.deepEqual(await response.json(), { app: APP_NAME, ok: true })
   }))
 
 test('renders a .tsx page, and an error in it names the .tsx line', () =>
   withApp(async (app) => {
-    const response = await fetch(`${app.url}/about`)
+    const response = await app.root.router.request(`/about`)
     assert.equal(response.status, 200)
     assert.match(await response.text(), /<main><h1>About<\/h1>/)
     const { failingPage } = await import('../src/about.tsx')
@@ -46,14 +53,26 @@ test('renders a .tsx page, and an error in it names the .tsx line', () =>
 
 test('answers health checks and 404 for unknown paths', () =>
   withApp(async (app) => {
-    assert.equal((await fetch(`${app.url}/health`)).status, 200)
-    const missing = await fetch(`${app.url}/nope`)
+    assert.equal((await app.root.router.request(`/health`)).status, 200)
+    const missing = await app.root.router.request(`/nope`)
     assert.equal(missing.status, 404)
     await missing.body?.cancel()
   }))
 
-test('stops listening when stopped', async () => {
-  const home = await mkdtemp(join(tmpdir(), 'app-test-'))
+/** 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. */
+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)))
+})
+const skip = canListen ? false : 'this environment does not allow listening on a port'
+if (!canListen)
+  console.log(
+    `skipped: the test that starts the real server (${skip}); every other test ran in process`,
+  )
+
+test('stops listening when stopped', { skip }, async () => {
+  const home = await mkdtemp(join(scratch, 'app-test-'))
   const app = await createApp(withPort(pinnedInstance(home, { root: projectRoot }), 0))
   await app.stop()
   await assert.rejects(fetch(`${app.url}/health`))

package/templates/chat/AGENTS.md

@@ -0,0 +1,16 @@
+
+## This app (chat): a streamed answer, history in a database
+
+A Cordis app: `blend.yaml` lists the plugins that are mounted (`acryl-router`, `acryl-db-sqlite`, `routes`, `acryl-node-server`), `src/app.ts` is the one file that names the SQLite provider, and `src/routes.ts` is the app's own plugin: it builds the app on the `db` port and mounts it.
+
+- **The dependency rule:** only `src/app.ts` (the `opener` in `package.json`) imports the provider. Every other file takes a `Db` (`import type { Db } from '../plugins/acryl-db/src/index.ts'`) as an argument and never imports `node:sqlite`, `pg`, another driver or `acryl-db-sqlite`. `npm test` and `npm run check` run `acrylblends check-deps`, which names the file and line of a violation; do not move the `opener` entry to silence it.
+- `src/llm.ts`: `Llm`, what the app needs from a model (messages in, pieces out, an aborted signal stops the work), and `openAiCompatible`, which calls an OpenAI-compatible chat completions API with `stream: true`. The base URL is `DEEPSEEK_BASE_URL` (default `https://api.deepseek.com`), the model `DEEPSEEK_MODEL` (default `deepseek-chat`), the key **only** the environment variable `DEEPSEEK_API_KEY`, read at the moment of the call: never write it to a file, a response or a log.
+- `src/db.ts`: `chatStore(db)`. The routes only call `chatStore`; keep SQL out of them. Every `db` call returns a promise: `await` it. The database is `data/chat.sqlite` (or the file `$CHAT_DB` names), opened by the `db` row with `migrations/` applied on start. The shape of the database is `migrations/NNN-name.sql`: to change it add the next numbered file and never edit one that has run. See `docs/framework/guides/data.md`.
+- `src/chat-app.ts`: `createApp(db, llm)`. `POST /api/chat` answers Server-Sent Events: `meta` (the conversation id), a `token` per piece, then `done` or `error`. The request's signal (`c.req.raw.signal`) goes to the model call, so a closed tab or the Stop button stops the request to the model; what had arrived is kept.
+- `src/client/chat.tsx`: the client component (own `tsconfig.json`, browser types): sends the message with `fetch`, reads the events as they arrive, shows the answer growing, and aborts on Stop. `clientModules` compiles it when the browser asks; `npm run build` compiles it once into `dist/client`. See `docs/framework/guides/client-modules.md`.
+- `test/chat.test.ts` tests every route with a mock `Llm` (never the network); keep it that way. It boots the whole app on a database file in a throwaway home and takes `app.root.db`. `test/server.test.ts` starts the real server and stops it with a signal.
+- To try it with a real model: `DEEPSEEK_API_KEY=... npm run dev`.
+
+## Before you ship
+
+Read `docs/framework/getting-started/deploy.md`. In short: `npm ci --omit=dev`, `npm run build`, `NODE_ENV=production npm start`; the app listens on `127.0.0.1` (`HOST=0.0.0.0` only in a container); the SQLite file goes outside the code folder (`CHAT_DB=/var/lib/chat/chat.sqlite`) and is backed up; the model key is an environment variable of the service (a root-only environment file for systemd), never a file in the repository. Anyone who can reach the app can spend your key: put it behind a login or on a private network before it is public.

package/templates/chat/blend.yaml

@@ -0,0 +1,32 @@
+# The app as data, in ACRYL's Blend format (blends.acryl.dev/v1alpha1): which plugins it mounts, in what order, with what config.
+# Edit this, not app.ts, to switch a plugin off (disabled: true) or change its config. `npm run lock` records what the app is built from.
+apiVersion: blends.acryl.dev/v1alpha1
+kind: Blueprint
+metadata:
+  id: acrylblends.__APP_NAME__
+  name: __APP_NAME__
+  version: 0.1.0
+  visibility: private # `npm run save` never pushes a private app to a public remote
+spec:
+  runtime: cordis
+  parameters:
+    # The address the server listens on.
+    hostname: { type: string, default: 127.0.0.1 }
+  rows:
+    - id: router
+      name: acryl-router
+    # The db port, on one SQLite file. The file and the migrations folder are set in src/app.ts (data/chat.sqlite, or the file the CHAT_DB environment variable names).
+    - id: db
+      name: acryl-db-sqlite
+    - id: routes
+      name: routes
+    # Plugins installed while the app runs (the door's `plugin add`): development only, src/app.ts leaves it out 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/chat/gitignore

@@ -0,0 +1,6 @@
+node_modules/
+.acrylblends/
+.acryl/
+data/
+*.sqlite
+*.sqlite-*

package/templates/chat/migrations/001-chat.sql

@@ -0,0 +1,12 @@
+CREATE TABLE conversations (
+  id INTEGER PRIMARY KEY,
+  title TEXT NOT NULL,
+  created_at TEXT NOT NULL
+);
+
+CREATE TABLE messages (
+  id INTEGER PRIMARY KEY,
+  conversation_id INTEGER NOT NULL REFERENCES conversations(id) ON DELETE CASCADE,
+  role TEXT NOT NULL CHECK (role IN ('user', 'assistant')),
+  content TEXT NOT NULL
+);

package/templates/chat/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "__APP_NAME__",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "imports": {
+    "#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 ./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": "acrylblends check-deps && node --import ./plugins/acryl-node-server/src/register.ts --test \"test/**/*.test.{ts,tsx}\"",
+    "check": "tsc --noEmit && tsc --noEmit -p src/client && acrylblends check-deps",
+    "build": "acrylblends build-client",
+    "lock": "node plugins/manifest/lock.ts",
+    "save": "node plugins/save/cli.ts",
+    "upgrade": "node plugins/manifest/upgrade-cli.ts"
+  },
+  "dependencies": {
+    "acrylblends": "__ACRYLBLENDS_RANGE__",
+    "typescript": "6.0.3"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0"
+  },
+  "acryl": {
+    "opener": "src/app.ts"
+  }
+}