acrylblends 1.1.0 → 1.3.0

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,7 +49,11 @@ 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 {
@@ -52,8 +64,25 @@ 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')
@@ -64,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 {
@@ -76,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> => {
@@ -110,62 +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)
+    .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(body.message, body.driver)
+      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, pageOf(body.page))
+      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(', ')
@@ -175,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. */
@@ -191,12 +275,12 @@ export function apply(ctx: Context, config: PanelConfig = {}): void {
     ended: boolean
     endedAt?: number
   }
-  let current: Run | undefined
   let runs = 0
   /** 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,
@@ -213,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)
@@ -224,14 +309,19 @@ 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) {
@@ -241,8 +331,9 @@ export function apply(ctx: Context, config: PanelConfig = {}): void {
         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
@@ -340,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
@@ -373,7 +460,7 @@ export function apply(ctx: Context, config: PanelConfig = {}): void {
                 return
               }
               if (!authed) {
-                if (message.t !== 'hello' || !sameToken(message.token)) {
+                if (message.t !== 'hello' || !visitors.accepts(visitor, message.token)) {
                   ws.close(4401, 'token')
                   return
                 }
@@ -386,8 +473,9 @@ export function apply(ctx: Context, config: PanelConfig = {}): void {
               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
@@ -397,7 +485,7 @@ 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')
@@ -405,6 +493,7 @@ export function apply(ctx: Context, config: PanelConfig = {}): void {
                 }
                 watch(
                   startRun(
+                    visitor,
                     checked.driverName,
                     checked.message,
                     checked.driver,
@@ -413,10 +502,10 @@ export function apply(ctx: Context, config: PanelConfig = {}): void {
                   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() {
@@ -430,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
+}

package/plugins/agent-panel/visitors.ts

@@ -0,0 +1,231 @@
+/**
+ * Who uses the panel, and what each one may do.
+ *
+ * - In development one person does, the app's owner: every page of the app shares one token and one run, so a run asked in the frame is followed from any tab of the app.
+ * - As the Assistant every visitor of the app is their own: a visitor is known by an HttpOnly cookie that the panel's session sets, and has their own token, their own run and
+ *   their own limits. A visitor never sees, follows or stops another visitor's run, and never waits for one.
+ *
+ * The Assistant spends the owner's model key for anyone who opens the app, so its asks are bounded: per visitor per hour, for all visitors per day, runs at once, and the length of
+ * a question. The agent's own step budget bounds each run.
+ */
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto'
+
+/** The cookie that names a visitor of the Assistant. HttpOnly: the page's scripts never read it. */
+export const VISITOR_COOKIE = 'acryl-visitor'
+
+/** The Assistant's limits; each one has a default. */
+export interface AssistantLimits {
+  /** Questions one visitor may ask in an hour. */
+  readonly perVisitorPerHour?: number
+  /** Questions all visitors together may ask in a day: every one of them spends the owner's model key. */
+  readonly perDay?: number
+  /** Runs going at once, across visitors. */
+  readonly concurrent?: number
+  /** Characters in one question. */
+  readonly messageLength?: number
+}
+
+export const DEFAULT_LIMITS: Required<AssistantLimits> = {
+  perVisitorPerHour: 20,
+  perDay: 300,
+  concurrent: 4,
+  messageLength: 1000,
+}
+
+/** The question length the development panel accepts (one person, who owns the key). */
+const OWNER_MESSAGE_LENGTH = 8000
+const HOUR_MS = 60 * 60 * 1000
+const DAY_MS = 24 * HOUR_MS
+/** Visitors kept at most; the one seen longest ago without a run going is let go first. */
+const DEFAULT_CAPACITY = 5000
+
+/** What a visitor's run must say about itself. */
+export interface RunState {
+  readonly ended: boolean
+}
+
+export interface Visitor<R extends RunState> {
+  readonly id: string
+  readonly token: string
+  /** The visitor in the audit: a short hash, never the cookie itself. */
+  readonly tag: string
+  /** The visitor's latest run, going or ended (what a page that loads shows again). */
+  current: R | undefined
+  /** When this visitor's asks of the last hour started. */
+  readonly asks: number[]
+  lastSeen: number
+}
+
+/** Why an ask is refused, with the HTTP status to answer. */
+export interface Refusal {
+  readonly error: string
+  readonly status: 400 | 409 | 429 | 503
+}
+
+export interface VisitorsOptions {
+  /** One visitor for every page (development); otherwise one per cookie (the Assistant). */
+  readonly shared: boolean
+  readonly limits?: AssistantLimits
+  readonly now?: () => number
+  readonly capacity?: number
+}
+
+const newSecret = (): string => randomBytes(24).toString('base64url')
+
+/** The value of one cookie in a `Cookie` header. */
+export function cookieValue(header: string | undefined | null, name: string): string | undefined {
+  if (header === undefined || header === null) return undefined
+  for (const part of header.split(';')) {
+    const at = part.indexOf('=')
+    if (at === -1) continue
+    if (part.slice(0, at).trim() === name) return part.slice(at + 1).trim()
+  }
+  return undefined
+}
+
+/** Whether two secrets are the same, in constant time. */
+export function sameSecret(presented: unknown, expected: string): boolean {
+  if (typeof presented !== 'string') return false
+  const a = Buffer.from(presented)
+  const b = Buffer.from(expected)
+  return a.length === b.length && timingSafeEqual(a, b)
+}
+
+const minutes = (ms: number): string => {
+  const count = Math.max(1, Math.ceil(ms / 60_000))
+  return `${String(count)} minute${count === 1 ? '' : 's'}`
+}
+
+export class Visitors<R extends RunState> {
+  private readonly shared: boolean
+  private readonly limits: Required<AssistantLimits>
+  private readonly now: () => number
+  private readonly capacity: number
+  private readonly byId = new Map<string, Visitor<R>>()
+  /** When every ask of the last day started, across visitors. */
+  private readonly day: number[] = []
+  private readonly owner: Visitor<R> | undefined
+
+  constructor(options: VisitorsOptions) {
+    this.shared = options.shared
+    this.limits = { ...DEFAULT_LIMITS, ...options.limits }
+    this.now = options.now ?? Date.now
+    this.capacity = options.capacity ?? DEFAULT_CAPACITY
+    this.owner = this.shared ? this.make() : undefined
+  }
+
+  /** The visitor a request belongs to: the owner in development, else the one its cookie names; `undefined` when it names none this app knows. */
+  of(cookieHeader: string | undefined | null): Visitor<R> | undefined {
+    if (this.owner !== undefined) return this.owner
+    const id = cookieValue(cookieHeader, VISITOR_COOKIE)
+    const visitor = id === undefined ? undefined : this.byId.get(id)
+    if (visitor !== undefined) visitor.lastSeen = this.now()
+    return visitor
+  }
+
+  /**
+   * The visitor of a session request, made when the request names none. `setCookie` is the header to answer with, only for a new visitor: HttpOnly, SameSite=Strict, the whole
+   * app (`Path=/`), a day long, and Secure when the page came over https.
+   */
+  session(
+    cookieHeader: string | undefined | null,
+    secure: boolean,
+  ): { visitor: Visitor<R>; setCookie?: string } {
+    const known = this.of(cookieHeader)
+    if (known !== undefined) return { visitor: known }
+    const visitor = this.make()
+    this.keep(visitor)
+    const setCookie = `${VISITOR_COOKIE}=${visitor.id}; Path=/; HttpOnly; SameSite=Strict; Max-Age=${String(DAY_MS / 1000)}${secure ? '; Secure' : ''}`
+    return { visitor, setCookie }
+  }
+
+  /** Whether `presented` is this visitor's token. */
+  accepts(visitor: Visitor<R> | undefined, presented: unknown): visitor is Visitor<R> {
+    return visitor !== undefined && sameSecret(presented, visitor.token)
+  }
+
+  /** Whether any visitor holds this token (a terminal driver checks a request with no other context). */
+  knows(cookieHeader: string | undefined | null, presented: unknown): boolean {
+    return this.accepts(this.of(cookieHeader), presented)
+  }
+
+  /** The question's length check, which comes before anything is counted. */
+  checkMessage(message: string): Refusal | undefined {
+    const most = this.shared ? OWNER_MESSAGE_LENGTH : this.limits.messageLength
+    if (message === '' || message.length > most)
+      return { error: `write a message of at most ${String(most)} characters`, status: 400 }
+    return undefined
+  }
+
+  /**
+   * Whether this visitor may start a run now. The visitor's own run going is refused first (409); then, for the Assistant, the visitor's hour, the runs going at once and the
+   * day. An admitted ask is counted.
+   */
+  admit(visitor: Visitor<R>): Refusal | undefined {
+    if (visitor.current !== undefined && !visitor.current.ended)
+      return { error: 'a run is already going; wait for it to end', status: 409 }
+    if (this.shared) return undefined
+    const now = this.now()
+    prune(visitor.asks, now - HOUR_MS)
+    prune(this.day, now - DAY_MS)
+    const hour = visitor.asks[0]
+    if (visitor.asks.length >= this.limits.perVisitorPerHour && hour !== undefined)
+      return {
+        error: `You have asked ${String(this.limits.perVisitorPerHour)} questions this hour. Ask again in ${minutes(hour + HOUR_MS - now)}.`,
+        status: 429,
+      }
+    let going = 0
+    for (const other of this.byId.values())
+      if (other.current !== undefined && !other.current.ended) going += 1
+    if (going >= this.limits.concurrent)
+      return {
+        error: 'The assistant is helping other people right now. Ask again in a moment.',
+        status: 503,
+      }
+    const first = this.day[0]
+    if (this.day.length >= this.limits.perDay && first !== undefined)
+      return {
+        error: `The assistant has answered all the questions it can today. It is back in ${minutes(first + DAY_MS - now)}.`,
+        status: 429,
+      }
+    visitor.asks.push(now)
+    this.day.push(now)
+    return undefined
+  }
+
+  /** How many visitors are kept (for tests and diagnostics). */
+  get size(): number {
+    return this.owner === undefined ? this.byId.size : 1
+  }
+
+  private make(): Visitor<R> {
+    const id = newSecret()
+    return {
+      id,
+      token: newSecret(),
+      tag: createHash('sha256').update(id).digest('hex').slice(0, 12),
+      current: undefined,
+      asks: [],
+      lastSeen: this.now(),
+    }
+  }
+
+  /** Keep a new visitor; past the capacity, let go of the visitors seen longest ago that have no run going. */
+  private keep(visitor: Visitor<R>): void {
+    if (this.byId.size >= this.capacity) {
+      const idle = [...this.byId.values()]
+        .filter((other) => other.current === undefined || other.current.ended)
+        .sort((a, b) => a.lastSeen - b.lastSeen)
+      for (const other of idle.slice(0, this.byId.size - this.capacity + 1))
+        this.byId.delete(other.id)
+    }
+    this.byId.set(visitor.id, visitor)
+  }
+}
+
+/** Drop the times up to `since` from the front of an ascending list: an ask exactly an hour (or a day) old is out of the window. */
+function prune(times: number[], since: number): void {
+  let drop = 0
+  while (drop < times.length && (times[drop] ?? 0) <= since) drop += 1
+  if (drop > 0) times.splice(0, drop)
+}