acrylblends 1.0.10 → 1.2.0

package/plugins/agent-panel/headless.ts

@@ -112,8 +112,11 @@ export function agentDriver(ctx: Context): ChatDriver {
   return {
     kind: 'chat',
     name: 'agent',
-    async *start({ message, signal }) {
-      const result = await ctx.agent.run(message, { signal })
+    async *start({ message, signal, page }) {
+      const result = await ctx.agent.run(message, {
+        signal,
+        ...(page === undefined ? {} : { page }),
+      })
       for (const call of result.trace)
         yield {
           event: 'tool',

package/plugins/agent-panel/index.ts

@@ -7,9 +7,15 @@
  * - `GET /api/agent-panel/session` gives the page the drivers it may use and a token; `POST /api/agent-panel/ask` runs one message and answers server-sent events:
  *   `text`, `tool`, `change`, `done`, `error`.
  * - Only the app's own page may ask (a same-origin request carrying the token), one run at a time, and every ask is written to `.acryl/audit/agent-panel.jsonl`.
- * - Development only: the plugin does nothing with `NODE_ENV=production` or `ACRYL_DOOR=off`.
+ * - Who asks (`visitors.ts`): in development one person, the owner, whose pages share one token and one run. As the Assistant each visitor has their own token, run and
+ *   replay, named by an HttpOnly cookie: no visitor sees, follows or stops another's run, and the asks are bounded (per visitor per hour, per day, runs at once).
+ * - The routes live under the app's mount: the root of the app's own server, or the frame's prefix (`/app`) when the frame hosts it, where the host's own
+ *   `/api` routes would otherwise answer first. The row's `mount` config names it.
+ * - Development only: the plugin does nothing with `NODE_ENV=production` or `ACRYL_DOOR=off`, except as the Assistant (`assistant: true`): then it runs in production too,
+ *   docked open on the right, with the app's own agent only. The app gives that agent the page tools alone and a page-only door, so it uses the app for a visitor and
+ *   cannot change it (src/app.ts, `ACRYL_ASSISTANT=on`). In the ACRYL frame's canvas the panel follows the frame's view: Build hides it, and Preview shows it only as
+ *   the Assistant and only when the app's production environment names one (`assistantInProduction` in the session).
  */
-import { randomBytes, timingSafeEqual } from 'node:crypto'
 import { appendFileSync, mkdirSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import type { Context } from '@deepseek-ai/cordis'
@@ -19,7 +25,7 @@ import { Acryl, type MiddlewareHandler } from '../acryl-router/src/index.ts'
 import { loopbackAuthority } from '../acryl-router/src/middleware/index.ts'
 import type {} from '../agent/index.ts'
 import type {} from '../extensions/index.ts'
-import type { ChatDriver } from './drivers.ts'
+import type { ChatDriver, Driver } from './drivers.ts'
 import {
   agentDriver,
   availableHeadless,
@@ -27,7 +33,9 @@ import {
   headlessDriver,
   whyNotChat,
 } from './headless.ts'
+import { mountedBase, mountedPrefix } from './mount.ts'
 import { provideDrivers } from './registry.ts'
+import { type AssistantLimits, type Visitor, Visitors } from './visitors.ts'
 
 export type {
   ChatDriver,
@@ -41,14 +49,40 @@ export type {
 export const name = 'agent-panel'
 export const inject = ['router', 'agent', 'extensions', 'appInstance']
 
-const PREFIX = '/api/agent-panel'
+/** The panel's own routes, fixed relative to the app's mount. */
+const PANEL_PATH = '/api/agent-panel'
+
+/** The one driver the Assistant offers its visitors: the app's own agent, held to the page tools. */
+const ASSISTANT_DRIVER = 'agent'
+
+/** The slice of the door the panel uses; the door is optional (it is a development plugin, and a different row). */
+interface DoorPort {
+  driveFor(windowId: string): () => void
+}
 const CLIENT_DIR = join(import.meta.dirname, 'client')
 
 export interface PanelConfig {
   /** Headless coding agents to offer besides the app's own agent; default: the ones found on the machine. */
   drivers?: readonly HeadlessName[]
+  /**
+   * The URL prefix the app is mounted at: empty on the app's own server, `/app` when the ACRYL frame hosts it (the same prefix `makeApp` and
+   * `routerHttp.mount` take). The panel's routes, script tag and client live under it, so they belong to the app and are served wherever it is.
+   */
+  mount?: string
+  /** The Assistant: a production panel for the app's visitors, with the app's own agent only (no coding agent, no terminal). Runs with `NODE_ENV=production`. */
+  assistant?: boolean
+  /** The Assistant's limits on what visitors may ask (`visitors.ts` has the defaults); the development panel has none but one run at a time. */
+  limits?: AssistantLimits
 }
 
+/** Whether the page came over https (directly, or through a proxy that says so): the visitor cookie is then Secure. */
+const overHttps = (url: string, headers: Headers): boolean =>
+  url.startsWith('https:') || headers.get('x-forwarded-proto')?.split(',')[0]?.trim() === 'https'
+
+/** The panel's routes under a checked mount: empty, or an absolute path such as `/app` with no trailing slash (the `routerHttp.mount` rule). */
+const panelPrefix = (mount: string | undefined): string =>
+  mountedPrefix(mount, PANEL_PATH, 'agent-panel')
+
 /** Whether a request comes from the app's own page: a browser says so itself (`Sec-Fetch-Site: same-origin`), or the Origin is the Host. */
 export function fromOwnPage(headers: Headers): boolean {
   const site = headers.get('sec-fetch-site')
@@ -59,9 +93,24 @@ export function fromOwnPage(headers: Headers): boolean {
 }
 
 export function apply(ctx: Context, config: PanelConfig = {}): void {
-  if (process.env.NODE_ENV === 'production' || process.env.ACRYL_DOOR === 'off') return
+  const assistant = config.assistant === true
+  if (process.env.ACRYL_DOOR === 'off' || (process.env.NODE_ENV === 'production' && !assistant))
+    return
+  const PREFIX = panelPrefix(config.mount)
+  // The panel's routes mount at the app's own mount and keep the fixed path inside (`/app` + `/api/agent-panel/...`); the frame's router prefixes the
+  // mount path itself, so a prefix inside the routes too would become `/app/app/...`. PREFIX stays absolute for the page's script tag and client URLs.
+  const MOUNT = mountedBase(config.mount, 'agent-panel')
   const root = ctx.appInstance.root
-  const token = randomBytes(24).toString('hex')
+  const visitors = new Visitors<Run>({
+    shared: !assistant,
+    ...(config.limits === undefined ? {} : { limits: config.limits }),
+  })
+  /** The visitor of a request that must carry its token, or `undefined` when it does not come from the app's own page with the right one. */
+  const caller = (headers: Headers, presented: unknown): Visitor<Run> | undefined => {
+    if (!fromOwnPage(headers)) return undefined
+    const visitor = visitors.of(headers.get('cookie'))
+    return visitors.accepts(visitor, presented) ? visitor : undefined
+  }
   const auditFile = join(root, '.acryl', 'audit', 'agent-panel.jsonl')
   const audit = (entry: Record<string, unknown>): void => {
     try {
@@ -71,13 +120,17 @@ export function apply(ctx: Context, config: PanelConfig = {}): void {
       // The audit never stops a run.
     }
   }
+  // The Assistant's visitors use the app's own agent and nothing else: no plugin's driver (a terminal, a coding agent) is open to them, whatever plugins the app mounts.
   const registry = provideDrivers(
     ctx,
-    (headers) => fromOwnPage(headers) && headers.get('x-agent-panel-token') === token,
+    (headers) => !assistant && caller(headers, headers.get('x-agent-panel-token')) !== undefined,
   )
+  const offered = (): Driver[] =>
+    registry.list().filter((driver) => !assistant || driver.name === ASSISTANT_DRIVER)
   ctx.effect(() => registry.register(agentDriver(ctx)))
-  for (const program of availableHeadless(config.drivers))
-    ctx.effect(() => registry.register(headlessDriver(program, root)))
+  if (!assistant)
+    for (const program of availableHeadless(config.drivers))
+      ctx.effect(() => registry.register(headlessDriver(program, root)))
 
   const tag = `<script type="module" src="${PREFIX}/panel.js"></script>`
   const addScript = async (c: { res: Response }, next: () => Promise<void>): Promise<void> => {
@@ -105,58 +158,95 @@ export function apply(ctx: Context, config: PanelConfig = {}): void {
       if (wrapped) return next()
       await addScript(c, next)
     })
-    .get(`${PREFIX}/panel.js`, (c) =>
-      c.body(`import '${PREFIX}/client/main.ts'\n`, 200, {
-        'content-type': 'text/javascript; charset=utf-8',
-        'cache-control': 'no-cache',
-      }),
+    .get(`${PANEL_PATH}/panel.js`, (c) =>
+      c.body(
+        `import { start } from '${PREFIX}/client/main.ts'\nstart(${JSON.stringify(PREFIX)})\n`,
+        200,
+        {
+          'content-type': 'text/javascript; charset=utf-8',
+          'cache-control': 'no-cache',
+        },
+      ),
     )
-    .route(`${PREFIX}/client`, clientModules({ root: CLIENT_DIR }))
-    .get(`${PREFIX}/session`, (c) => {
+    .route(`${PANEL_PATH}/client`, clientModules({ root: CLIENT_DIR, mount: `${PREFIX}/client` }))
+    .get(`${PANEL_PATH}/session`, (c) => {
       if (!fromOwnPage(c.req.raw.headers))
         return c.json({ error: "only the app's own page may use the panel" }, 403)
+      const { visitor, setCookie } = visitors.session(
+        c.req.header('cookie'),
+        overHttps(c.req.url, c.req.raw.headers),
+      )
+      if (setCookie !== undefined) c.header('set-cookie', setCookie)
       return c.json({
-        token,
-        drivers: registry.list().map((driver) => ({ name: driver.name, kind: driver.kind })),
+        token: visitor.token,
+        ...(assistant ? { assistant: true } : {}),
+        // The frame's Preview shows the app as production would. This is the fact that lets its page show the Assistant when the app's production
+        // environment names it (ACRYL_ASSISTANT=on), even though the frame host itself runs in development and never mounts the Assistant row.
+        ...(process.env.ACRYL_ASSISTANT === 'on' ? { assistantInProduction: true } : {}),
+        // A terminal driver names the browser module that draws its view and the prefix its endpoints live under: the plugin that owns the view
+        // also knows where the app is mounted, so the panel never guesses either.
+        drivers: offered().map((driver) => ({
+          name: driver.name,
+          kind: driver.kind,
+          ...(driver.kind === 'terminal' ? { view: driver.view } : {}),
+        })),
       })
     })
-    .post(`${PREFIX}/ask`, async (c) => {
-      if (!fromOwnPage(c.req.raw.headers) || c.req.header('x-agent-panel-token') !== token)
-        return c.json({ error: "only the app's own page may ask" }, 403)
-      const body = (await c.req.json().catch(() => ({}))) as { message?: unknown; driver?: unknown }
-      const checked = checkAsk(body.message, body.driver)
+    .post(`${PANEL_PATH}/ask`, async (c) => {
+      const visitor = caller(c.req.raw.headers, c.req.header('x-agent-panel-token'))
+      if (visitor === undefined) return c.json({ error: "only the app's own page may ask" }, 403)
+      const body = (await c.req.json().catch(() => ({}))) as {
+        message?: unknown
+        driver?: unknown
+        page?: unknown
+      }
+      const checked = checkAsk(visitor, body.message, body.driver)
       if ('error' in checked) return c.json({ error: checked.error }, checked.status)
-      const run = startRun(checked.driverName, checked.message, checked.driver)
+      const run = startRun(
+        visitor,
+        checked.driverName,
+        checked.message,
+        checked.driver,
+        pageOf(body.page),
+      )
       return follow(c, run, false)
     })
     // Stop: the only thing that cancels a run. A page that goes away (a reload, a move to another page, a closed tab) does not: the agent goes on, and the page picks it up again.
-    .post(`${PREFIX}/stop`, (c) => {
-      if (!fromOwnPage(c.req.raw.headers) || c.req.header('x-agent-panel-token') !== token)
+    .post(`${PANEL_PATH}/stop`, (c) => {
+      const visitor = caller(c.req.raw.headers, c.req.header('x-agent-panel-token'))
+      if (visitor === undefined)
         return c.json({ error: "only the app's own page may stop a run" }, 403)
-      current?.cancel.abort()
+      // A visitor's own run, never another's.
+      visitor.current?.cancel.abort()
       return c.json({ ok: true })
     })
     // The latest run, for a page that just loaded: what was asked, then every event so far, then the rest as it happens (until the run ends).
-    .get(`${PREFIX}/run`, (c) => {
-      if (!fromOwnPage(c.req.raw.headers) || c.req.header('x-agent-panel-token') !== token)
+    .get(`${PANEL_PATH}/run`, (c) => {
+      const visitor = caller(c.req.raw.headers, c.req.header('x-agent-panel-token'))
+      if (visitor === undefined)
         return c.json({ error: "only the app's own page may read the run" }, 403)
-      return current === undefined ? c.json({ run: null }) : follow(c, current, true)
+      return visitor.current === undefined
+        ? c.json({ run: null })
+        : follow(c, visitor.current, true)
     })
-  /** What `/ask` and the socket's `ask` both check: a message of a sensible size, a chat driver that is here, and no run going. */
+  /**
+   * What `/ask` and the socket's `ask` both check: a message of a sensible size, a chat driver that is here, and no run of this visitor going; for the Assistant also its
+   * limits (an admitted ask is counted).
+   */
   const checkAsk = (
+    visitor: Visitor<Run>,
     rawMessage: unknown,
     rawDriver: unknown,
   ):
     | { message: string; driverName: string; driver: ChatDriver }
-    | { error: string; status: 400 | 409 } => {
+    | { error: string; status: 400 | 409 | 429 | 503 } => {
     const message = typeof rawMessage === 'string' ? rawMessage.trim() : ''
     const driverName = typeof rawDriver === 'string' ? rawDriver : 'agent'
-    if (message === '' || message.length > 8000)
-      return { error: 'write a message of at most 8000 characters', status: 400 }
-    const driver = registry.get(driverName)
+    const tooLong = visitors.checkMessage(message)
+    if (tooLong !== undefined) return tooLong
+    const driver = offered().find((one) => one.name === driverName)
     if (driver?.kind !== 'chat') {
-      const chat = registry
-        .list()
+      const chat = offered()
         .filter((d) => d.kind === 'chat')
         .map((d) => d.name)
         .join(', ')
@@ -166,8 +256,11 @@ export function apply(ctx: Context, config: PanelConfig = {}): void {
         status: 400,
       }
     }
-    if (current !== undefined && !current.ended)
-      return { error: 'a run is already going; wait for it to end', status: 409 }
+    const refused = visitors.admit(visitor)
+    if (refused !== undefined) {
+      if (assistant) audit({ ask: 'refused', visitor: visitor.tag, status: refused.status })
+      return refused
+    }
     return { message, driverName, driver }
   }
   /** One run of an agent: its events as they came, and who is following. It lives in the app, not in a page. */
@@ -182,9 +275,17 @@ export function apply(ctx: Context, config: PanelConfig = {}): void {
     ended: boolean
     endedAt?: number
   }
-  let current: Run | undefined
   let runs = 0
-  const startRun = (driverName: string, message: string, driver: ChatDriver): Run => {
+  /** The door's id of the page that asked, when it sent one that looks like it. */
+  const pageOf = (raw: unknown): string | undefined =>
+    typeof raw === 'string' && /^[A-Za-z0-9-]{1,80}$/u.test(raw) ? raw : undefined
+  const startRun = (
+    visitor: Visitor<Run>,
+    driverName: string,
+    message: string,
+    driver: ChatDriver,
+    page?: string,
+  ): Run => {
     runs += 1
     const run: Run = {
       id: runs,
@@ -196,7 +297,8 @@ export function apply(ctx: Context, config: PanelConfig = {}): void {
       cancel: new AbortController(),
       ended: false,
     }
-    current = run
+    visitor.current = run
+    const who = assistant ? { visitor: visitor.tag } : {}
     const emit = (event: string, data: unknown): void => {
       const item = { event, data }
       run.events.push(item)
@@ -207,21 +309,31 @@ export function apply(ctx: Context, config: PanelConfig = {}): void {
       changed = true
       emit('change', { extension, action })
     })
-    ctx.effect(() => () => run.cancel.abort(), `agent-panel: run ${runs}`)
-    audit({ ask: 'start', driver: driverName, characters: message.length })
+    // The run ends when the plugin unloads; the effect goes when the run ends, so runs do not pile up on the plugin.
+    const unloadStops = ctx.effect(() => () => run.cancel.abort(), `agent-panel: run ${runs}`)
+    audit({ ask: 'start', ...who, driver: driverName, characters: message.length })
+    // The agent's door calls name no window: while this run goes, they are for the page whose panel asked, not for another tab or window that happens to be open.
+    const door = page === undefined ? undefined : (ctx.get('door') as DoorPort | undefined)
+    const releasePage = door?.driveFor(page as string)
     void (async () => {
       try {
-        for await (const { event, data } of driver.start({ message, signal: run.cancel.signal }))
+        for await (const { event, data } of driver.start({
+          message,
+          signal: run.cancel.signal,
+          ...(page === undefined ? {} : { page }),
+        }))
           emit(event, data)
         emit('done', { changed })
       } catch (error) {
         emit('error', { message: error instanceof Error ? error.message : String(error) })
       } finally {
         off()
+        releasePage?.()
         run.ended = true
         run.endedAt = Date.now()
-        audit({ ask: 'end', driver: driverName, changed })
+        audit({ ask: 'end', ...who, driver: driverName, changed })
         for (const follower of [...run.followers]) follower({ event: 'end', data: {} })
+        void unloadStops()
       }
     })()
     return run
@@ -319,17 +431,13 @@ export function apply(ctx: Context, config: PanelConfig = {}): void {
         return c.json({ error: "only the app's own page may use the panel" }, 403)
       await next()
     }
-    const sameToken = (presented: unknown): boolean => {
-      if (typeof presented !== 'string') return false
-      const a = Buffer.from(presented)
-      const b = Buffer.from(token)
-      return a.length === b.length && timingSafeEqual(a, b)
-    }
     ws.get(
       `${PREFIX}/run/ws`,
       own,
       upgrade(
-        () => {
+        (c) => {
+          // The visitor the socket's cookie names (the owner in development): its hello must carry that visitor's token, and it reaches that visitor's runs only.
+          const visitor = visitors.of(c.req.header('cookie'))
           let authed = false
           let following: { detach(): void } | undefined
           let hello: NodeJS.Timeout | undefined
@@ -339,26 +447,35 @@ export function apply(ctx: Context, config: PanelConfig = {}): void {
             },
             onMessage(event, ws) {
               if (typeof event.data !== 'string') return
-              let message: { t?: unknown; token?: unknown; message?: unknown; driver?: unknown }
+              let message: {
+                t?: unknown
+                token?: unknown
+                message?: unknown
+                driver?: unknown
+                page?: unknown
+              }
               try {
                 message = JSON.parse(event.data) as typeof message
               } catch {
                 return
               }
               if (!authed) {
-                if (message.t !== 'hello' || !sameToken(message.token)) {
+                if (message.t !== 'hello' || !visitors.accepts(visitor, message.token)) {
                   ws.close(4401, 'token')
                   return
                 }
                 authed = true
                 if (hello !== undefined) clearTimeout(hello)
+                // The page waits for this before it counts the socket as open: a token it was given by an earlier start of the app is refused (4401) and it asks for a new one.
+                ws.send(JSON.stringify({ e: 'accepted', d: {} }))
                 return
               }
               const send = (e: string, d: unknown): void => {
                 ws.send(JSON.stringify({ e, d }))
               }
+              if (visitor === undefined) return
               if (message.t === 'stop') {
-                current?.cancel.abort()
+                visitor.current?.cancel.abort()
                 return
               }
               if (following !== undefined) return
@@ -368,18 +485,27 @@ export function apply(ctx: Context, config: PanelConfig = {}): void {
                 void pumped.done.then(() => ws.close(1000, 'run ended'))
               }
               if (message.t === 'ask') {
-                const checked = checkAsk(message.message, message.driver)
+                const checked = checkAsk(visitor, message.message, message.driver)
                 if ('error' in checked) {
                   send('error', { message: checked.error })
                   ws.close(1000, 'refused')
                   return
                 }
-                watch(startRun(checked.driverName, checked.message, checked.driver), false)
+                watch(
+                  startRun(
+                    visitor,
+                    checked.driverName,
+                    checked.message,
+                    checked.driver,
+                    pageOf(message.page),
+                  ),
+                  false,
+                )
               } else if (message.t === 'follow') {
-                if (current === undefined) {
+                if (visitor.current === undefined) {
                   send('idle', {})
                   ws.close(1000, 'no run')
-                } else watch(current, true)
+                } else watch(visitor.current, true)
               }
             },
             onClose() {
@@ -393,5 +519,5 @@ export function apply(ctx: Context, config: PanelConfig = {}): void {
     )
     inner.router.route('/', ws)
   })
-  ctx.router.route('/', app)
+  ctx.router.route(MOUNT === '' ? '/' : MOUNT, app)
 }

package/plugins/agent-panel/mount.ts

@@ -0,0 +1,27 @@
+/**
+ * A plugin's own route prefix under the app's mount. The app is served at the root of its own server `''`, or at the prefix a host serves it at (`/app` in
+ * the ACRYL frame); a plugin that mounts routes of its own (the panel, the PTY driver) takes that mount as config and derives its prefix from it, so its
+ * routes belong to the app wherever the app is served. The same rule `routerHttp.mount` applies.
+ */
+export function mountedPrefix(mount: string | undefined, path: string, plugin: string): string {
+  if (mount === undefined || mount === '') return path
+  if (!/^\/[A-Za-z0-9._~\-/]*[A-Za-z0-9._~-]$/u.test(mount))
+    throw new TypeError(
+      `${plugin}: the app's mount "${mount}" must be empty or an absolute path such as "/app"`,
+    )
+  return `${mount}${path}`
+}
+
+/**
+ * The app's own mount, validated like {@link mountedPrefix}: empty at the root or the prefix a host serves the app at (`/app`). A plugin's routes are
+ * mounted at this path and keep only their own fixed path inside, so the frame's router (which prefixes a mount with the app's base) composes
+ * `/app` + `/api/agent-panel/panel.js` once, not twice.
+ */
+export function mountedBase(mount: string | undefined, plugin: string): string {
+  if (mount === undefined || mount === '') return ''
+  if (!/^\/[A-Za-z0-9._~\-/]*[A-Za-z0-9._~-]$/u.test(mount))
+    throw new TypeError(
+      `${plugin}: the app's mount "${mount}" must be empty or an absolute path such as "/app"`,
+    )
+  return mount
+}