acrylblends 1.0.9 → 1.1.0

package/plugins/acryl-state/src/client-source.ts

@@ -0,0 +1,244 @@
+/**
+ * The browser module served at `/api/state/client.js`, kept as text so it travels with the plugin wherever the plugin goes (copied into an app as source, or bundled): there is
+ * no file to find at run time and no compiler needed to serve it. `String.raw` keeps every backslash as written, so what is below is the module exactly as the browser gets it.
+ * The code has no imports and uses no backtick or dollar-brace of its own.
+ *
+ *   import { watch } from '/api/state/client.js'
+ *   const stop = watch('tasks.count', (value) => { badge.textContent = String(value) })
+ *
+ * One WebSocket for the whole page carries every key; a WebSocket is not one of the browser's six connections per host, so a page that watches ten keys, in as many windows,
+ * leaves every one of them free for requests. Where the WebSocket cannot open (no `ws` package on the server, a proxy that does not upgrade), each key is followed by its
+ * event stream instead, with one console warning.
+ */
+export const CLIENT_SOURCE = String.raw`// acryl-state: watch(key, onValue, onError?) follows a state key over one WebSocket for the page.
+const HEARTBEAT_SILENCE_MS = 45000
+const RETRY_MIN_MS = 250
+const RETRY_MAX_MS = 10000
+
+const here = import.meta.url
+const watchers = new Map()
+const latest = new Map()
+const streams = new Map()
+const complained = new Set()
+let socket
+let timer
+let watchdog
+let attempts = 0
+let opened = false
+let following = 'socket'
+let suspended = false
+let warnedStream = false
+
+const socketUrl = () => {
+  const url = new URL('ws', here)
+  url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:'
+  return url.href
+}
+const streamUrl = (key) => new URL(encodeURIComponent(key) + '/events?json=1', here).href
+
+const deliver = (key, text) => {
+  if (latest.get(key) === text) return
+  latest.set(key, text)
+  let value
+  try {
+    value = JSON.parse(text)
+  } catch {
+    return
+  }
+  for (const watcher of [...(watchers.get(key) ?? [])]) {
+    try {
+      watcher.onValue(value)
+    } catch (cause) {
+      console.error('acryl-state: a watcher of ' + key + ' threw', cause)
+    }
+  }
+}
+
+const fail = (key, message) => {
+  const set = watchers.get(key)
+  if (set === undefined) return
+  let told = false
+  for (const watcher of [...set]) {
+    if (watcher.onError === undefined) continue
+    told = true
+    try {
+      watcher.onError(new Error(message))
+    } catch (cause) {
+      console.error('acryl-state: an error handler of ' + key + ' threw', cause)
+    }
+  }
+  if (!told && !complained.has(key)) {
+    complained.add(key)
+    console.warn('acryl-state: ' + key + ': ' + message)
+  }
+}
+
+const send = (frame) => {
+  if (socket !== undefined && socket.readyState === 1) socket.send(JSON.stringify(frame))
+}
+
+const arm = () => {
+  clearTimeout(watchdog)
+  watchdog = setTimeout(() => lost(socket), HEARTBEAT_SILENCE_MS)
+}
+
+const closeSocket = () => {
+  clearTimeout(watchdog)
+  const current = socket
+  socket = undefined
+  if (current === undefined) return
+  current.onopen = current.onmessage = current.onerror = current.onclose = null
+  try {
+    current.close(1000, 'page left')
+  } catch {
+    // Already closed.
+  }
+}
+
+const closeStreams = () => {
+  for (const source of streams.values()) source.close()
+  streams.clear()
+}
+
+const openStream = (key) => {
+  if (streams.has(key) || typeof EventSource === 'undefined') return
+  const source = new EventSource(streamUrl(key))
+  streams.set(key, source)
+  source.addEventListener('value', (event) => deliver(key, event.data))
+  source.onerror = () => {
+    // A network error is retried by the browser itself; a refusal (the key does not exist) ends the stream for good.
+    if (source.readyState === 2) {
+      streams.delete(key)
+      fail(key, 'the event stream was refused (no such state?)')
+    }
+  }
+}
+
+const fallBack = () => {
+  following = 'stream'
+  if (!warnedStream) {
+    warnedStream = true
+    console.warn('acryl-state: the WebSocket did not open, so each key is followed by its own event stream (each holds one of the browser\'s six connections to this host)')
+  }
+  for (const key of watchers.keys()) openStream(key)
+}
+
+// A socket that closes, errors or goes quiet: before it ever opened this is a server without WebSockets, so the streams take over; after, the server went away and the page tries again.
+const lost = (which) => {
+  if (which !== socket) return
+  closeSocket()
+  if (watchers.size === 0 || suspended) return
+  if (!opened) {
+    fallBack()
+    return
+  }
+  const delay = Math.min(RETRY_MIN_MS * 2 ** attempts, RETRY_MAX_MS)
+  attempts += 1
+  clearTimeout(timer)
+  timer = setTimeout(connect, delay)
+}
+
+const connect = () => {
+  clearTimeout(timer)
+  if (socket !== undefined || watchers.size === 0 || suspended || following !== 'socket') return
+  let made
+  try {
+    made = new WebSocket(socketUrl())
+  } catch {
+    fallBack()
+    return
+  }
+  socket = made
+  made.onopen = () => {
+    opened = true
+    attempts = 0
+    arm()
+    for (const key of watchers.keys()) send({ t: 'sub', key })
+  }
+  made.onmessage = (event) => {
+    if (made !== socket) return
+    arm()
+    let frame
+    try {
+      frame = JSON.parse(event.data)
+    } catch {
+      return
+    }
+    if (frame === null || typeof frame !== 'object' || typeof frame.key !== 'string') return
+    if (typeof frame.error === 'string') fail(frame.key, frame.error)
+    else deliver(frame.key, JSON.stringify(frame.value))
+  }
+  made.onerror = () => lost(made)
+  made.onclose = () => lost(made)
+}
+
+const start = () => {
+  if (watchers.size === 0) return
+  if (following === 'stream') for (const key of watchers.keys()) openStream(key)
+  else connect()
+}
+
+if (typeof addEventListener === 'function') {
+  // A page in the back/forward cache keeps its connections open for as long as it is kept; let them go when the page is hidden for good, and open them again when it comes back.
+  addEventListener('pagehide', () => {
+    suspended = true
+    clearTimeout(timer)
+    closeSocket()
+    closeStreams()
+  })
+  addEventListener('pageshow', () => {
+    if (!suspended) return
+    suspended = false
+    start()
+  })
+}
+
+// Follow the state key: onValue gets the value now and after every change, as the JSON value the server holds (a string stays a string). onError, when given, is told of a key that
+// does not exist; without it the page console gets one warning. Returns the function that stops watching.
+export function watch(key, onValue, onError) {
+  if (typeof key !== 'string' || key === '') throw new TypeError('watch(key, onValue): the key is a state key like "tasks.count"')
+  if (typeof onValue !== 'function') throw new TypeError('watch(key, onValue): onValue is a function')
+  const watcher = { onValue, onError }
+  let set = watchers.get(key)
+  const first = set === undefined
+  if (first) {
+    set = new Set()
+    watchers.set(key, set)
+  }
+  set.add(watcher)
+  complained.delete(key)
+  if (!first && latest.has(key)) {
+    const text = latest.get(key)
+    queueMicrotask(() => {
+      if (!set.has(watcher)) return
+      try {
+        onValue(JSON.parse(text))
+      } catch (cause) {
+        console.error('acryl-state: a watcher of ' + key + ' threw', cause)
+      }
+    })
+  }
+  if (first && !suspended) {
+    if (following === 'stream') openStream(key)
+    else if (socket === undefined) connect()
+    else send({ t: 'sub', key })
+  }
+  let stopped = false
+  return () => {
+    if (stopped) return
+    stopped = true
+    set.delete(watcher)
+    if (set.size > 0) return
+    watchers.delete(key)
+    latest.delete(key)
+    complained.delete(key)
+    streams.get(key)?.close()
+    streams.delete(key)
+    send({ t: 'unsub', key })
+    if (watchers.size === 0) {
+      clearTimeout(timer)
+      closeSocket()
+    }
+  }
+}
+`

package/plugins/acryl-state/src/service.ts

@@ -6,10 +6,12 @@
  */
 
 import { Context, Service } from '@deepseek-ai/cordis'
-import { Acryl, type Context as RequestContext } from 'acryl-router'
-import { streamSSE } from 'acryl-router/helpers'
+import { Acryl, type Context as RequestContext, type MiddlewareHandler } from 'acryl-router'
+import { streamSSE, type UpgradeWebSocket } from 'acryl-router/helpers'
 import { loopbackOnly, methodNotAllowed } from 'acryl-router/middleware'
 import { createCell, createDerived, type Cell, type ReadonlyCell } from './cell.ts'
+import { CLIENT_SOURCE } from './client-source.ts'
+import { refuseStranger, stateSocket } from './socket.ts'
 
 declare module '@deepseek-ai/cordis' {
   interface Context {
@@ -24,6 +26,9 @@ export const name = 'acryl-state'
 
 const KEY_PATTERN = /^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)*$/
 
+/** Names under `/api/state` that are routes, not keys: a cell cannot be called by one. */
+const RESERVED_KEYS = new Set(['ws', 'client.js'])
+
 export class State extends Service {
   private readonly cells = new Map<string, ReadonlyCell<unknown>>()
 
@@ -33,6 +38,7 @@ export class State extends Service {
 
   private claim(key: string): void {
     if (!KEY_PATTERN.test(key)) throw new TypeError(`acryl-state: key "${key}" must be dotted lowercase words, like "market.sources"`)
+    if (RESERVED_KEYS.has(key)) throw new TypeError(`acryl-state: "${key}" is the name of a route under /api/state, choose another key`)
     if (this.cells.has(key)) throw new Error(`acryl-state: key "${key}" is already in use`)
   }
 
@@ -73,9 +79,10 @@ export class State extends Service {
 
   /**
    * The current value of `key` as a server-sent event stream: the value now, then one event per change, until the client cancels or the router
-   * is disposed (both abort the stream). A comment line goes out every 15 seconds so proxies and browsers keep an idle stream open.
+   * is disposed (both abort the stream). A comment line goes out every 15 seconds so proxies and browsers keep an idle stream open. A string value travels as it is; with `json`
+   * (the `?json=1` of the browser client) every value is JSON, so `"12"` and `12` can be told apart.
    */
-  stream(key: string, c: RequestContext): Response | undefined {
+  stream(key: string, c: RequestContext, json = false): Response | undefined {
     const cell = this.find(key)
     if (cell === undefined) return undefined
     return streamSSE(c, async stream => {
@@ -83,7 +90,7 @@ export class State extends Service {
       // Writes are asynchronous; chaining them keeps events in the order the cell changed.
       let queue: Promise<unknown> = Promise.resolve()
       const send = (value: unknown): void => {
-        queue = queue.then(() => stream.writeSSE({ event: 'value', data: typeof value === 'string' ? value : JSON.stringify(value) })).catch(() => {})
+        queue = queue.then(() => stream.writeSSE({ event: 'value', data: typeof value === 'string' && !json ? value : JSON.stringify(value) })).catch(() => {})
       }
       send(cell.get())
       const unsubscribe = cell.subscribe(send)
@@ -105,14 +112,34 @@ export function apply(ctx: Context): void {
   // app; the terminal calls the router in process and is the host's own code.
   ctx.inject(['router'], inner => {
     const api = new Acryl()
+    // The WebSocket form is mounted when a server that upgrades appears (the server row comes after this one in a blend); until then, and without the `ws` package, `/ws` answers 404 and the
+    // browser client follows the event streams. The route is registered before `/:key`, which would otherwise take `ws` for a key.
+    let socket: MiddlewareHandler | undefined
     api.use(loopbackOnly({ inProcess: 'allow' }), methodNotAllowed({ app: api }))
       .get('/', c => c.json({ keys: state.keys() }))
+      .get('/client.js', c => c.body(CLIENT_SOURCE, 200, { 'content-type': 'text/javascript; charset=utf-8', 'cache-control': 'no-cache' }))
+      .get('/ws', async (c, next) => {
+        const upgrade = socket
+        if (upgrade === undefined) return c.json({ error: 'this server does not upgrade to a WebSocket' }, 404)
+        const refusal = refuseStranger(c)
+        if (refusal !== undefined) return refusal
+        return await upgrade(c, next)
+      })
       .get('/:key', c => {
         const cell = state.find(c.req.param('key'))
         return cell === undefined ? c.json({ error: 'no such state' }, 404) : c.json({ key: cell.key, value: cell.get() })
       })
-      .get('/:key/events', c => state.stream(c.req.param('key'), c) ?? c.json({ error: 'no such state' }, 404))
+      .get('/:key/events', c => state.stream(c.req.param('key'), c, c.req.query('json') === '1') ?? c.json({ error: 'no such state' }, 404))
     inner.router.route('/api/state', api)
+    inner.inject(['nodeServer'], withServer => {
+      try {
+        const upgrade = (withServer as unknown as { nodeServer: { upgrades(): UpgradeWebSocket } }).nodeServer.upgrades()
+        socket = stateSocket(state, { upgrade })
+        withServer.effect(() => () => { socket = undefined }, 'acryl-state: the WebSocket route')
+      } catch (cause) {
+        ctx.logger.warn(`acryl-state: state is followed by event streams only (${cause instanceof Error ? cause.message : String(cause)})`)
+      }
+    })
     // Over HTTP only where an adapter exists (Web and Desktop); the terminal needs none.
     inner.inject(['routerHttp'], http => { http.routerHttp.mount('/api/state') })
   })

package/plugins/acryl-state/src/socket.ts

@@ -0,0 +1,96 @@
+/**
+ * State over a WebSocket. A server-sent event stream holds one of the browser's six connections per host for as long as the page lives, and an app that follows a few keys in
+ * several windows uses them all; a WebSocket is not one of those six, and one socket carries every key of a page.
+ *
+ * `GET /api/state/ws` upgrades. Up, one JSON message per frame: `{ "t": "sub", "key": "<key>" }` and `{ "t": "unsub", "key": "<key>" }`. Down: `{ "key": "<key>", "value": <json> }` once on
+ * `sub` and after every change, `{ "key": "<key>", "error": "<why>" }` for a key that cannot be followed, and `{ "t": "ping" }` every {@link SOCKET_HEARTBEAT_MS} so a page can tell a quiet
+ * socket from a dead one. `GET /api/state/client.js` is the browser module that speaks this (`watch(key, callback)`), with the event stream as its fallback.
+ *
+ * A WebSocket has no CORS, so the upgrade is checked here ({@link refuseStranger}): a loopback peer on this port with a loopback `Host`, and an `Origin` that, when the request has one,
+ * is exactly this app's own origin. A program on this machine that sends no `Origin` (a script, a test) is let in, as it is for the JSON and stream routes; a web page of another
+ * origin, and a name that only resolves to this machine (DNS rebinding), are not.
+ */
+
+import type { Context, MiddlewareHandler } from 'acryl-router'
+import type { UpgradeWebSocket } from 'acryl-router/helpers'
+import { loopbackAuthority } from 'acryl-router/middleware'
+import type { ReadonlyCell } from './cell.ts'
+
+/** How often the server writes a `ping`; a page gives up on a socket that is silent for three of these. */
+export const SOCKET_HEARTBEAT_MS = 15_000
+
+/** How many keys one socket may follow; a page watches a handful. */
+export const MAX_KEYS_PER_SOCKET = 256
+
+/** What the socket needs of the state service. */
+export interface Cells {
+  find(key: string): ReadonlyCell<unknown> | undefined
+}
+
+export interface StateSocketOptions {
+  readonly upgrade: UpgradeWebSocket
+  readonly heartbeatMs?: number
+}
+
+/** A refusal (403) unless the upgrade comes from this machine to this app, and from its own page when it comes from a page at all. */
+export function refuseStranger(c: Context): Response | undefined {
+  const authority = loopbackAuthority(c)
+  if (authority === undefined) return c.json({ error: 'request authority rejected' }, 403)
+  const origin = c.req.header('origin')
+  const site = c.req.header('sec-fetch-site')
+  if ((origin !== undefined && origin !== authority.origin) || (site !== undefined && site !== 'same-origin')) {
+    return c.json({ error: 'only this app\'s own page may follow its state' }, 403)
+  }
+  return undefined
+}
+
+/** The route handler that upgrades and follows keys of `cells` for as long as the socket is open. */
+export function stateSocket(cells: Cells, options: StateSocketOptions): MiddlewareHandler {
+  const heartbeatMs = options.heartbeatMs ?? SOCKET_HEARTBEAT_MS
+  return options.upgrade(() => {
+    const following = new Map<string, () => void>()
+    let beat: NodeJS.Timeout | undefined
+    return {
+      onOpen(_event, ws) {
+        beat = setInterval(() => {
+          try { ws.send(JSON.stringify({ t: 'ping' })) } catch { /* the close event follows */ }
+        }, heartbeatMs)
+        beat.unref()
+      },
+      onMessage(event, ws) {
+        if (typeof event.data !== 'string') return
+        let message: { t?: unknown, key?: unknown }
+        try { message = JSON.parse(event.data) as typeof message } catch { return }
+        if (typeof message.key !== 'string') return
+        const key = message.key
+        const tell = (frame: object): void => {
+          try { ws.send(JSON.stringify(frame)) } catch { /* the close event follows */ }
+        }
+        const value = (current: unknown): void => {
+          let text: string
+          try { text = JSON.stringify({ key, value: current === undefined ? null : current }) } catch { tell({ key, error: 'the value cannot be sent as JSON' }); return }
+          try { ws.send(text) } catch { /* the close event follows */ }
+        }
+        if (message.t === 'unsub') {
+          following.get(key)?.()
+          following.delete(key)
+          return
+        }
+        if (message.t !== 'sub') return
+        const cell = cells.find(key)
+        if (cell === undefined) { tell({ key, error: 'no such state' }); return }
+        const known = following.has(key)
+        if (!known && following.size >= MAX_KEYS_PER_SOCKET) { tell({ key, error: 'too many keys on one socket' }); return }
+        // A key asked for twice is answered again with its value, and followed once.
+        if (known) { value(cell.get()); return }
+        value(cell.get())
+        following.set(key, cell.subscribe(value))
+      },
+      onClose() {
+        if (beat !== undefined) clearInterval(beat)
+        for (const stop of following.values()) stop()
+        following.clear()
+      },
+    }
+  }, { textOnly: true })
+}

package/plugins/agent-panel/client/main.ts

@@ -42,70 +42,90 @@ interface RunSource {
   readonly events: AsyncIterable<PanelEvent>
 }
 
+/** The door's id for this page, when the door is in it: sent with a question so the agent's calls (which name no window) drive this page and not another open one. */
+function doorPage(): { page?: string } {
+  const published = (window as unknown as Record<symbol, { windowId?: unknown } | undefined>)[
+    Symbol.for('acryl.door.page')
+  ]
+  return typeof published?.windowId === 'string' ? { page: published.windowId } : {}
+}
+
 /** A WebSocket is not one of the browser's six connections per host, so the panel's Stop and a run still work when two windows stream their own state. */
 let socketBroken = false
 let activeSocket: WebSocket | undefined
 
-/** Open the run socket and send the token and the first action. Rejects when the page cannot upgrade (a proxy, a server without `ws`): the caller falls back to the stream. */
-function openSocket(token: string, action: Record<string, unknown>): Promise<WebSocket> {
+/** The server did not accept the token: it is not the one this page was given (the app restarted since, which `node --watch` does at every change of a file). */
+class Refused extends Error {}
+
+/**
+ * Open the run socket and send the token and the first action. Resolves once the server has accepted the token (its `accepted` frame), with the socket and its events: the
+ * frames of the run as panel events, until the socket closes. One set of handlers serves the socket for its whole life, so a frame is never handed to a handler that was
+ * replaced. Rejects with `Refused` when the token is not accepted, and with another error when the page cannot upgrade (a proxy, a server without `ws`): the caller falls back
+ * to the stream.
+ */
+function openSocket(
+  token: string,
+  action: Record<string, unknown>,
+): Promise<{ socket: WebSocket; events: AsyncGenerator<PanelEvent> }> {
   return new Promise((resolve, reject) => {
     const socket = new WebSocket(
       `${location.protocol === 'https:' ? 'wss' : 'ws'}://${location.host}${PREFIX}/run/ws`,
     )
+    const queue: PanelEvent[] = []
+    let wake: (() => void) | undefined
+    let closed = false
+    let accepted = false
     const timer = setTimeout(() => {
       socket.close()
-      reject(new Error('the socket did not open in time'))
+      reject(new Error('the socket was not accepted in time'))
     }, 4000)
     socket.onopen = () => {
-      clearTimeout(timer)
       socket.send(JSON.stringify({ t: 'hello', token }))
       socket.send(JSON.stringify(action))
-      resolve(socket)
     }
-    socket.onerror = () => {
-      clearTimeout(timer)
-      reject(new Error('the server refused the upgrade'))
+    socket.onmessage = (message) => {
+      try {
+        const frame = JSON.parse(String(message.data)) as { e?: unknown; d?: unknown }
+        if (frame.e === 'accepted' && !accepted) {
+          accepted = true
+          clearTimeout(timer)
+          resolve({ socket, events: read() })
+        } else if (typeof frame.e === 'string')
+          queue.push({ event: frame.e, data: (frame.d ?? {}) as Record<string, unknown> })
+      } catch {
+        // Not a frame of ours.
+      }
+      wake?.()
     }
-  })
-}
-
-/** The frames of an open run socket as panel events, until it closes. */
-async function* socketEvents(socket: WebSocket): AsyncGenerator<PanelEvent> {
-  const queue: PanelEvent[] = []
-  let wake: (() => void) | undefined
-  let closed: CloseEvent | undefined
-  socket.onmessage = (message) => {
-    try {
-      const frame = JSON.parse(String(message.data)) as { e?: unknown; d?: unknown }
-      if (typeof frame.e === 'string')
-        queue.push({ event: frame.e, data: (frame.d ?? {}) as Record<string, unknown> })
-    } catch {
-      // Not a frame of ours.
+    socket.onclose = (event) => {
+      clearTimeout(timer)
+      closed = true
+      if (!accepted)
+        reject(
+          event.code === 4401
+            ? new Refused('the token was not accepted')
+            : new Error('the socket closed before it was accepted'),
+        )
+      wake?.()
     }
-    wake?.()
-  }
-  socket.onclose = (event) => {
-    closed = event
-    wake?.()
-  }
-  for (;;) {
-    const next = queue.shift()
-    if (next !== undefined) {
-      yield next
-      continue
+    socket.onerror = () => {
+      clearTimeout(timer)
+      if (!accepted) reject(new Error('the server refused the upgrade'))
     }
-    if (closed !== undefined) {
-      if (closed.code === 4401)
-        yield {
-          event: 'error',
-          data: { message: 'the panel was not accepted (reload the page and try again)' },
+    async function* read(): AsyncGenerator<PanelEvent> {
+      for (;;) {
+        const next = queue.shift()
+        if (next !== undefined) {
+          yield next
+          continue
         }
-      return
+        if (closed) return
+        await new Promise<void>((done) => {
+          wake = done
+        })
+      }
     }
-    await new Promise<void>((resolve) => {
-      wake = resolve
-    })
-  }
+  })
 }
 
 const css = `
@@ -145,7 +165,7 @@ textarea { width: 100%; min-height: 64px; resize: vertical; padding: 8px; border
 async function start(): Promise<void> {
   const reply = await fetch(`${PREFIX}/session`)
   if (!reply.ok) return
-  const session = (await reply.json()) as Session
+  let session = (await reply.json()) as Session
 
   const host = document.createElement('div')
   host.id = 'agent-panel'
@@ -199,6 +219,7 @@ async function start(): Promise<void> {
           onChange(change: { extension: string; action: string }): void
         }): Promise<{ detach(): void; stop(): Promise<void> }>
       }
+      await refreshSession()
       terminal = await openTerminal({
         container: term,
         token: session.token,
@@ -265,26 +286,41 @@ async function start(): Promise<void> {
   // A run belongs to the app, not to this page: it goes on when the page reloads (the door reloads it after a plugin change, an agent may move it to another page) and the page that
   // loads next follows it again. Only Stop cancels it.
   const headers = { 'content-type': 'application/json', 'x-agent-panel-token': session.token }
+  /**
+   * The token belongs to one start of the app: `node --watch` restarts it at every change of a file, and a page left open across that restart holds a token the new server
+   * does not know. Ask for the session again; the caller tries once more with what it gets.
+   */
+  const refreshSession = async (): Promise<void> => {
+    const reply = await fetch(`${PREFIX}/session`)
+    if (!reply.ok) return
+    session = (await reply.json()) as Session
+    headers['x-agent-panel-token'] = session.token
+  }
   let following = false
-  stop.addEventListener('click', () => {
+  const stopRun = (): void => {
     // On the run's socket when there is one: a request would wait behind the browser's six connections per host.
     if (activeSocket?.readyState === WebSocket.OPEN)
       activeSocket.send(JSON.stringify({ t: 'stop' }))
     else void fetch(`${PREFIX}/stop`, { method: 'POST', headers })
-  })
-  /** A run over the socket when the server upgrades, else over the stream, with one console warning saying why. */
-  const openRun = async (
-    action: { t: 'ask'; message: string; driver: string } | { t: 'follow' },
-  ): Promise<RunSource | { error: string } | undefined> => {
+  }
+  stop.addEventListener('click', stopRun)
+  // The door's "Agent is driving" bar has a Stop too (the same page): it ends this run.
+  window.addEventListener('acryl:stop-run', stopRun)
+  const REFUSED = Symbol('refused')
+  /** A run over the socket when the server upgrades, else over the stream, with one console warning saying why. `REFUSED` when the server does not know the token. */
+  const tryOpenRun = async (
+    action: { t: 'ask'; message: string; driver: string; page?: string } | { t: 'follow' },
+  ): Promise<RunSource | { error: string } | undefined | typeof REFUSED> => {
     if (!socketBroken && typeof WebSocket !== 'undefined') {
       try {
-        const socket = await openSocket(session.token, action)
+        const { socket, events: frames } = await openSocket(session.token, action)
         activeSocket = socket
         socket.addEventListener('close', () => {
           if (activeSocket === socket) activeSocket = undefined
         })
-        return { events: socketEvents(socket) }
+        return { events: frames }
       } catch (cause) {
+        if (cause instanceof Refused) return REFUSED
         socketBroken = true
         console.warn(
           `agent-panel: the run could not open a WebSocket (${cause instanceof Error ? cause.message : String(cause)}); using server-sent events, which count against the browser's six connections per host`,
@@ -295,8 +331,9 @@ async function start(): Promise<void> {
       const response = await fetch(`${PREFIX}/ask`, {
         method: 'POST',
         headers,
-        body: JSON.stringify({ message: action.message, driver: action.driver }),
+        body: JSON.stringify({ message: action.message, driver: action.driver, page: action.page }),
       })
+      if (response.status === 403) return REFUSED
       if (!response.ok)
         return {
           error:
@@ -306,10 +343,23 @@ async function start(): Promise<void> {
       return { events: events(response) }
     }
     const latest = await fetch(`${PREFIX}/run`, { headers })
+    if (latest.status === 403) return REFUSED
     return latest.ok && (latest.headers.get('content-type') ?? '').includes('text/event-stream')
       ? { events: events(latest) }
       : undefined
   }
+  /** `tryOpenRun`, and when the token was refused, a new session and one more try without the person seeing anything; a second refusal is shown. */
+  const openRun = async (
+    action: { t: 'ask'; message: string; driver: string; page?: string } | { t: 'follow' },
+  ): Promise<RunSource | { error: string } | undefined> => {
+    const first = await tryOpenRun(action)
+    if (first !== REFUSED) return first
+    await refreshSession()
+    const second = await tryOpenRun(action)
+    return second === REFUSED
+      ? { error: 'the panel was not accepted (reload the page and try again)' }
+      : second
+  }
   /**
    * Show one run, as its events come, until it ends. `own` is true for a run this page just started (its question is on screen); a run found on load is shown from its question, and
    * a run that had already ended before the page loaded is only shown, never reloads the page.
@@ -400,7 +450,7 @@ async function start(): Promise<void> {
     input.value = ''
     line(message, 'me')
     try {
-      const run = await openRun({ t: 'ask', message, driver: driver.value })
+      const run = await openRun({ t: 'ask', message, driver: driver.value, ...doorPage() })
       if (run === undefined) return
       if ('error' in run) {
         line(run.error, 'err')