acrylblends 0.7.7 → 0.8.0

package/plugins/acryl-door/src/host/operator-routes.ts

@@ -0,0 +1,38 @@
+/**
+ * The operator's routes: an agent's shell on this machine, through `.acryl/bin/acryl`. Loopback only, with this run's secret.
+ *
+ * `POST <prefix>/call` takes `{ verb, args }` and answers {@link CallResponse}; `GET <prefix>/verbs` lists the verbs. A caller that goes
+ * away aborts its call through the request's signal.
+ */
+
+import { Acryl } from '../../../acryl-router/src/index.ts'
+import { UiControlError } from '../page/protocol.ts'
+import { Door, DoorError } from './door.ts'
+import { error, INVALID_JSON, jsonBody, operatorOnly, readJson, type ReportError } from './http.ts'
+import { VERBS } from './verbs.ts'
+
+export type CallResponse =
+  | { readonly ok: true; readonly value: unknown; readonly text: string }
+  | { readonly ok: false; readonly code: string; readonly message: string }
+
+export function operatorRoutes(prefix: string, secret: string, door: Door, reportError: ReportError): Acryl {
+  return new Acryl()
+    .get(`${prefix}/verbs`, operatorOnly(secret), c => c.json({ verbs: VERBS }))
+    .post(`${prefix}/call`, operatorOnly(secret), jsonBody, async (c) => {
+      const body = await readJson(c)
+      if (body === INVALID_JSON || typeof body !== 'object' || body === null || typeof (body as { verb?: unknown }).verb !== 'string') {
+        return c.json({ ok: false, code: 'invalid', message: 'the body is { verb, args }' } satisfies CallResponse, 400)
+      }
+      const { verb, args } = body as { verb: string; args?: unknown }
+      try {
+        const answer = await door.run(verb, args, c.req.raw.signal)
+        return c.json({ ok: true, value: answer.value, text: answer.text } satisfies CallResponse)
+      } catch (cause) {
+        if (cause instanceof UiControlError || cause instanceof DoorError) {
+          return c.json({ ok: false, code: cause.code, message: cause.message } satisfies CallResponse, cause.code === 'invalid' || cause.code === 'unknown-verb' ? 400 : 200)
+        }
+        reportError(`run the door verb ${verb}`, cause)
+        return c.json(error('the verb could not be run'), 500)
+      }
+    })
+}

package/plugins/acryl-door/src/host/page-routes.ts

@@ -0,0 +1,65 @@
+/**
+ * The page channel on the router: an event stream down to the page and POST up, so it needs no WebSocket upgrade on any adapter.
+ *
+ * `GET <prefix>/channel?window=<id>&focused=0|1` is the page's stream. The Host writes each call as `event: call` and a `ping` every
+ * heartbeat, so a page that hears nothing for a while knows the stream died and reconnects. `POST <prefix>/channel/answer` carries
+ * `{ window, message }` (a result, an error or a focus change). Both are for the app's own page only (same origin, loopback).
+ */
+
+import { Acryl } from '../../../acryl-router/src/index.ts'
+import { streamSSE } from '../../../acryl-router/src/helpers/index.ts'
+import { loopbackOnly } from '../../../acryl-router/src/middleware/index.ts'
+import { parseChannelToHost, WINDOW_ID } from '../page/protocol.ts'
+import type { UiChannel } from './channel.ts'
+import { error, INVALID_JSON, jsonBody, ownPage, readJson } from './http.ts'
+
+/** How often the Host writes a `ping`; the page gives up on a stream that is silent for three of these. */
+export const HEARTBEAT_MS = 15_000
+
+export interface PageRoutesOptions {
+  /** Where the channel lives, e.g. `/api/acryl-door`. */
+  readonly prefix: string
+  readonly heartbeatMs?: number
+  /** The only hostnames the page may be served from (default: every loopback name), e.g. `['127.0.0.1']` for a Host that serves only that. */
+  readonly hostnames?: readonly string[]
+}
+
+export function pageChannelRoutes(channel: UiChannel, options: PageRoutesOptions): Acryl {
+  const heartbeatMs = options.heartbeatMs ?? HEARTBEAT_MS
+  const page = options.hostnames === undefined ? ownPage : loopbackOnly({ callers: 'own-page', hostnames: options.hostnames })
+  return new Acryl()
+    .get(`${options.prefix}/channel`, page, (c) => {
+      const windowId = c.req.query('window')
+      if (windowId === undefined || !WINDOW_ID.test(windowId)) return c.json(error('a window id is required'), 400)
+      const focused = c.req.query('focused') === '1'
+      const signal = c.req.raw.signal
+      return streamSSE(c, async (stream) => {
+        let end = (): void => {}
+        const ended = new Promise<void>((resolve) => { end = resolve })
+        stream.onAbort(end)
+        signal.addEventListener('abort', end, { once: true })
+        const write = (event: string, data: string): void => {
+          stream.writeSSE({ event, data }).catch(end)
+        }
+        const detach = channel.attach(windowId, focused, { send: (data) => { write('call', data) }, close: end })
+        const beat = setInterval(() => { write('ping', '') }, heartbeatMs)
+        try {
+          write('ready', '')
+          await ended
+        } finally {
+          clearInterval(beat)
+          signal.removeEventListener('abort', end)
+          detach()
+        }
+      })
+    })
+    .post(`${options.prefix}/channel/answer`, page, jsonBody, async (c) => {
+      const body = await readJson(c)
+      if (body === INVALID_JSON || typeof body !== 'object' || body === null) return c.json(error('invalid request body'), 400)
+      const { window: windowId, message } = body as { window?: unknown; message?: unknown }
+      const parsed = parseChannelToHost(message)
+      if (typeof windowId !== 'string' || !WINDOW_ID.test(windowId) || parsed === null) return c.json(error('invalid message'), 400)
+      channel.receive(windowId, parsed)
+      return c.body(null, 204)
+    })
+}

package/plugins/acryl-door/src/host/shim.ts

@@ -0,0 +1,65 @@
+/**
+ * The app folder's own command (spec 049 slice 10): `<app>/.acryl/bin/acryl` (and `acryl.cmd` on Windows) runs this door's operator
+ * client against this folder only (`--dir <app>`), with the Node that runs the app. An agent working in the folder calls it by that path,
+ * so it reaches the app running from this folder and never a user's own `acryl` on PATH or another app's door.
+ *
+ * Written each time the door starts, so a moved app or a new Node is picked up. It stays when the app stops: run then, it says that no
+ * app is running in the folder (exit 3). It carries no secret; the client reads `door.json` at each call.
+ */
+
+import { chmodSync, mkdirSync, renameSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { ensureStateDir } from './door-file.ts'
+
+/** The folder of the command below the app folder's `.acryl/`. */
+export const BIN_DIR = 'bin'
+
+export interface ShimTarget {
+  /** The Node executable. */
+  readonly node: string
+  /** Node options the client needs, e.g. `--experimental-strip-types` when it runs from source on a Node that needs the flag. */
+  readonly nodeOptions: readonly string[]
+  /** The operator client's entry file. */
+  readonly client: string
+  /** True when `node` is Electron, which runs as Node only with `ELECTRON_RUN_AS_NODE` set. */
+  readonly electron: boolean
+}
+
+/** A word for `sh`: single-quoted, with each `'` closed, escaped and reopened. */
+function shWord(value: string): string {
+  return `'${value.replaceAll('\'', '\'\\\'\'')}'`
+}
+
+/** A word for `cmd.exe`: double-quoted; `%` doubled so a batch file does not expand it. A path cannot hold `"`. */
+function cmdWord(value: string): string {
+  return `"${value.replaceAll('%', '%%')}"`
+}
+
+export function posixShim(root: string, target: ShimTarget): string {
+  const words = [target.node, ...target.nodeOptions, target.client, '--dir', root].map(shWord).join(' ')
+  const env = target.electron ? 'export ELECTRON_RUN_AS_NODE=1\n' : ''
+  return `#!/bin/sh\n# This app's door (acryl-door): reaches only the app running from this folder. Rewritten each time the app starts.\n${env}exec ${words} "$@"\n`
+}
+
+export function windowsShim(root: string, target: ShimTarget): string {
+  const words = [target.node, ...target.nodeOptions, target.client, '--dir', root].map(cmdWord).join(' ')
+  const env = target.electron ? 'set ELECTRON_RUN_AS_NODE=1\r\n' : ''
+  return `@echo off\r\nsetlocal\r\nrem This app's door (acryl-door): reaches only the app running from this folder. Rewritten each time the app starts.\r\n${env}${words} %*\r\n`
+}
+
+function writeAtomically(file: string, content: string, mode: number): void {
+  const temporary = `${file}.${String(process.pid)}.tmp`
+  writeFileSync(temporary, content, { mode })
+  if (process.platform !== 'win32') chmodSync(temporary, mode)
+  renameSync(temporary, file)
+}
+
+/** Write `.acryl/bin/acryl` and `.acryl/bin/acryl.cmd` for the app at `root`. @returns the folder they are in. */
+export function writeShims(root: string, target: ShimTarget): string {
+  const bin = join(ensureStateDir(root), BIN_DIR)
+  mkdirSync(bin, { recursive: true, mode: 0o700 })
+  if (process.platform !== 'win32') chmodSync(bin, 0o700)
+  writeAtomically(join(bin, 'acryl'), posixShim(root, target), 0o700)
+  writeAtomically(join(bin, 'acryl.cmd'), windowsShim(root, target), 0o600)
+  return bin
+}

package/plugins/acryl-door/src/host/verbs.ts

@@ -0,0 +1,109 @@
+/**
+ * The one verb list (spec 049 slice 13). Every face of the door reads it: the operator client (`acryl <verb>`, its `verbs` and `brief`),
+ * MCP (`tools/list`) and the built-in chat (the `tools` registry). A verb added here is in all three, or the comparison test fails.
+ */
+
+import { MAX_SNAPSHOT_NODES, MAX_WAIT_MS } from '../page/protocol.ts'
+
+/** Every verb, in the order `brief` lists them. */
+export const VERBS = ['brief', 'look', 'act', 'plugin-list', 'plugin-add', 'plugin-remove', 'plugin-reload', 'tool-list', 'tool-call'] as const
+export type Verb = (typeof VERBS)[number]
+
+/** The JSON Schema of a verb's arguments, as MCP lists it. */
+export interface ArgumentsSchema {
+  readonly type: 'object'
+  readonly properties: Readonly<Record<string, unknown>>
+  readonly required?: readonly string[]
+  readonly additionalProperties: boolean
+}
+
+export interface VerbSpec {
+  /** The operator client's form, as `brief` prints it. */
+  readonly usage: string
+  /** What the verb does, for a model choosing a tool. */
+  readonly description: string
+  readonly arguments: ArgumentsSchema
+}
+
+const none: ArgumentsSchema = { type: 'object', properties: {}, additionalProperties: false }
+const ref = { type: 'string', description: 'a ref from the latest look, e.g. 3.12' }
+
+export const VERB_SPECS: Readonly<Record<Verb, VerbSpec>> = {
+  'brief': {
+    usage: 'brief: this summary',
+    description: 'What this app is, which files to read first, whether its page is open, and the verbs.',
+    arguments: none,
+  },
+  'look': {
+    usage: 'look [--cursor <n>] [--max-nodes <n>]: the page as text, with refs',
+    description: 'The open page as text: its roles, names, values and visible text, each with a ref to act on. A long page comes in parts (cursor).',
+    arguments: {
+      type: 'object',
+      properties: {
+        cursor: { type: 'integer', minimum: 0, description: 'where the previous part ended' },
+        maxNodes: { type: 'integer', minimum: 1, maximum: MAX_SNAPSHOT_NODES },
+      },
+      additionalProperties: false,
+    },
+  },
+  'act': {
+    usage: 'act click|type|select|press|scroll|wait ...: do one thing on the page (refs from the latest look)',
+    description: 'Do one thing on the page: click, type, select, press a key, scroll, or wait for text or a control. Look again before the next act.',
+    arguments: {
+      type: 'object',
+      properties: {
+        op: { type: 'string', enum: ['click', 'type', 'select', 'press', 'scroll', 'wait'] },
+        ref,
+        text: { type: 'string', description: 'type: what to type; wait: the text to wait for' },
+        submit: { type: 'boolean', description: 'type: press Enter after' },
+        clear: { type: 'boolean', description: 'type: false keeps what the field holds' },
+        option: { type: 'string', description: 'select: the option to choose' },
+        key: { type: 'string', description: 'press: a character or Enter, Escape, Tab, ArrowDown, ...' },
+        direction: { type: 'string', enum: ['up', 'down', 'left', 'right'] },
+        amount: { type: 'number', minimum: 1, maximum: 10_000, description: 'scroll: pixels' },
+        role: { type: 'string', description: 'wait: the role to wait for' },
+        name: { type: 'string', description: 'wait: its name' },
+        gone: { type: 'boolean', description: 'wait: until it is gone instead' },
+        timeoutMs: { type: 'integer', minimum: 0, maximum: MAX_WAIT_MS },
+      },
+      required: ['op'],
+      additionalProperties: false,
+    },
+  },
+  'plugin-list': {
+    usage: 'plugin list: the plugins installed while the app runs',
+    description: 'The plugins installed into the running app.',
+    arguments: none,
+  },
+  'plugin-add': {
+    usage: 'plugin add <folder>: check, install and start a plugin folder, live',
+    description: 'Check, install and start a plugin folder inside the app, without a restart.',
+    arguments: { type: 'object', properties: { folder: { type: 'string', description: 'a folder inside the app, e.g. plugins/pomodoro' } }, required: ['folder'], additionalProperties: false },
+  },
+  'plugin-remove': {
+    usage: 'plugin remove <name>: stop and remove an installed plugin',
+    description: 'Stop and remove an installed plugin.',
+    arguments: { type: 'object', properties: { name: { type: 'string' } }, required: ['name'], additionalProperties: false },
+  },
+  'plugin-reload': {
+    usage: 'plugin reload: bring every installed plugin in line with its folder',
+    description: 'Bring every installed plugin in line with its folder (after editing one).',
+    arguments: none,
+  },
+  'tool-list': {
+    usage: 'tool list: the app tools the door offers',
+    description: 'The app\'s own tools that the door offers.',
+    arguments: none,
+  },
+  'tool-call': {
+    usage: 'tool call --tool <name> [--args <json>]: run one of them',
+    description: 'Run one of the app tools that tool-list names.',
+    arguments: { type: 'object', properties: { tool: { type: 'string' }, args: { description: 'the tool\'s input' } }, required: ['tool'], additionalProperties: false },
+  },
+}
+
+/** A verb's name in the `tools` registry the built-in chat reads: prefixed, so it never meets an app tool's name. */
+export const chatToolName = (verb: Verb): string => `door_${verb.replaceAll('-', '_')}`
+
+/** True for a name the door itself registers in the `tools` registry. */
+export const isDoorToolName = (name: string): boolean => VERBS.some(verb => chatToolName(verb) === name)

package/plugins/acryl-door/src/index.ts

@@ -0,0 +1,133 @@
+/**
+ * `acryl-door`: the Door of the five nouns, as a Cordis plugin of a framework app (spec 049 slice 9). An agent working in the app folder
+ * looks at the running page, acts on it, and installs plugins live, through `.acryl/bin/acryl`; everything else it does with its own
+ * file tools and shell.
+ *
+ * The page loads `/api/acryl-door/page.js` (one script tag) and keeps an event stream open to the Host; the Host sends it calls. An
+ * operator on this machine reaches `/api/acryl-door/call` with the secret from `<app>/.acryl/door.json`. One effect owns the channel and
+ * the audit, the routes are mounted after it, and a second effect writes the connection file last, so disposal removes the file first,
+ * then the routes (their in-flight calls end), then closes the channel (every pending call settles).
+ */
+
+import { join } from 'node:path'
+import type { Context } from '@deepseek-ai/cordis'
+import z from '@deepseek-ai/schemastery'
+import { Acryl } from '../../acryl-router/src/index.ts'
+import { clientModules } from '../../acryl-node-server/src/client-modules.ts'
+import { auditPath, AuditLog } from './host/audit.ts'
+import { UiChannel } from './host/channel.ts'
+import { registerChatTools } from './host/chat-tools.ts'
+import { Door, type ExtensionsPort, type ToolsPort } from './host/door.ts'
+import { newSecret, removeDoorFile, stateDir, writeDoorFile } from './host/door-file.ts'
+import { DOOR_PREFIX, privateApi } from './host/http.ts'
+import { mcpRoutes } from './host/mcp-routes.ts'
+import { operatorRoutes } from './host/operator-routes.ts'
+import { pageChannelRoutes } from './host/page-routes.ts'
+import { writeShims, type ShimTarget } from './host/shim.ts'
+
+/** Stable Cordis plugin name, equal to the package name and the Loader row id. */
+export const name = 'acryl-door'
+
+/** The part of acrylblends' `appInstance` the door reads: the app folder and its name. */
+interface AppFolder {
+  readonly root: string
+  readonly name: string
+}
+
+/** The part of `acryl-node-server` the door reads: where the app listens. */
+interface Listening {
+  readonly url: string
+}
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    door: Door
+  }
+}
+
+export const inject = ['router', 'appInstance', 'nodeServer']
+
+export interface Config {
+  tools?: { expose?: string[] }
+}
+
+export const Config: z<Config> = z.object({
+  tools: z.object({
+    // Not a `door_` name: those are the door's own verbs in the registry, never offered back as app tools.
+    expose: z.array(z.string().pattern(/^(?!door_)[A-Za-z][A-Za-z0-9_-]{0,63}$/u)).description('App tools (from the tools registry) the door offers; none by default.'),
+  }),
+})
+
+/** The page module, served compiled from source by the app's own TypeScript. */
+const PAGE_DIR = join(import.meta.dirname, import.meta.url.endsWith('.ts') ? 'page' : join('..', 'src', 'page'))
+
+/** The operator client this build runs: the source next to this file, or the built `cli.js`. */
+const CLIENT = import.meta.url.endsWith('.ts') ? join(import.meta.dirname, 'cli', 'acryl.ts') : join(import.meta.dirname, 'cli.js')
+
+/** How the folder's `.acryl/bin/acryl` starts the client: with the Node that runs the app, and its type-stripping flag when run from source. */
+function shimTarget(): ShimTarget {
+  const fromSource = CLIENT.endsWith('.ts')
+  return {
+    node: process.execPath,
+    nodeOptions: fromSource ? process.execArgv.filter(option => /^--experimental-(strip|transform)-types$/u.test(option)) : [],
+    client: CLIENT,
+    electron: process.versions.electron !== undefined,
+  }
+}
+
+/** A listening address as one the operator reaches: an any-address bind is reached on loopback. */
+function loopbackUrl(url: string): string {
+  const parsed = new URL(url)
+  if (parsed.hostname === '0.0.0.0' || parsed.hostname === '[::]') parsed.hostname = '127.0.0.1'
+  return parsed.origin
+}
+
+export function apply(ctx: Context, rawConfig: Config = {}): void {
+  const config = Config(rawConfig)
+  const app = ctx.get('appInstance') as unknown as AppFolder
+  const server = ctx.get('nodeServer') as unknown as Listening
+  if (typeof app?.root !== 'string') throw new Error('acryl-door: the appInstance service has no app folder (root)')
+  const reportError = (operation: string, cause: unknown): void => {
+    ctx.logger?.error?.(`acryl-door: failed to ${operation}: ${cause instanceof Error ? cause.message : String(cause)}`)
+  }
+  const secret = newSecret()
+  const channel = new UiChannel()
+  const audit = new AuditLog(auditPath(stateDir(app.root)))
+  const door = new Door({
+    channel,
+    audit,
+    app: { name: app.name, root: app.root },
+    extensions: () => ctx.get('extensions') as unknown as ExtensionsPort | undefined,
+    tools: () => ctx.get('tools') as unknown as ToolsPort | undefined,
+    expose: config.tools?.expose ?? [],
+  })
+  ctx.effect(() => () => { channel.close() }, 'acryl-door: page channel')
+  // One script tag for the page (`page.js`): it imports the module tree served below it.
+  const pageModule = new Acryl()
+    .get(`${DOOR_PREFIX}/page.js`, c => c.body(`import '${DOOR_PREFIX}/page/main.ts'\n`, 200, { 'content-type': 'text/javascript; charset=utf-8' }))
+    .route(`${DOOR_PREFIX}/page`, clientModules({ root: PAGE_DIR }))
+  ctx.router.route('/', privateApi(
+    DOOR_PREFIX,
+    pageModule,
+    pageChannelRoutes(channel, { prefix: DOOR_PREFIX }),
+    operatorRoutes(DOOR_PREFIX, secret, door, reportError),
+    mcpRoutes(DOOR_PREFIX, secret, door, reportError),
+  ))
+  // The built-in chat's agent reads the `tools` registry: the verbs are in it while both are up.
+  ctx.inject(['tools'], (inner) => {
+    inner.effect(() => registerChatTools(inner.get('tools') as unknown as ToolsPort, door), 'acryl-door: the verbs in the tools registry')
+  })
+  ctx.effect(function* () {
+    yield ctx.reflect.provide('door', door)
+    writeDoorFile(app.root, loopbackUrl(server.url), secret)
+    writeShims(app.root, shimTarget())
+    yield () => { removeDoorFile(app.root, secret) }
+  }, 'acryl-door: the door service, .acryl/door.json and .acryl/bin/acryl')
+}
+
+export { Door, DoorError, type VerbAnswer } from './host/door.ts'
+export { chatToolName, VERB_SPECS, VERBS, type Verb, type VerbSpec } from './host/verbs.ts'
+export { mcpTools } from './host/mcp-routes.ts'
+export { DOOR_PREFIX } from './host/http.ts'
+export { doorFilePath, readDoorFile, STATE_DIR, type DoorFile } from './host/door-file.ts'
+export type { CallResponse } from './host/operator-routes.ts'

package/plugins/acryl-door/src/page/api.ts

@@ -0,0 +1,9 @@
+/**
+ * The door's page core for another page to build its own door on (`acryl-door/page`): the channel to the Host, the driver of the
+ * document, the user-input clock and the plain DOM indicator. ACRYL's DSH client uses the first three with its own React indicator.
+ */
+
+export { PageChannel, SILENCE_MS, type ChannelSource, type PageChannelOptions } from './channel.ts'
+export { UiDriver, type DriverActivity, type UiDriverOptions } from './driver/driver.ts'
+export { UserInputClock } from './user-input.ts'
+export { mountIndicator } from './indicator.ts'

package/plugins/acryl-door/src/page/channel.ts

@@ -0,0 +1,135 @@
+/**
+ * The page's end of the door's channel.
+ *
+ * It keeps an event stream open to the Host (`GET <base>/channel`), runs each call on the driver, and posts the answer back. The Host
+ * writes a `ping` every few seconds; a stream silent for {@link SILENCE_MS} is dropped and opened again, so a page whose connection died
+ * without an error (a sleeping laptop, a proxy) resumes on its own. A page that reconnects keeps its window id, and the Host settles a
+ * call in flight on the old stream as `disconnected`.
+ */
+
+import { UiControlError, parseChannelToPage, type ChannelToHost } from './protocol.ts'
+import type { UiDriver } from './driver/driver.ts'
+
+/** The slice of an `EventSource` the channel uses, so tests can supply their own. */
+export interface ChannelSource {
+  addEventListener(type: string, listener: (event: MessageEvent) => void): void
+  onerror: ((event: Event) => void) | null
+  close(): void
+  readonly readyState: number
+}
+
+/** The Host's heartbeat is 15 s; three missed beats and the stream counts as dead. */
+export const SILENCE_MS = 45_000
+const CLOSED = 2
+const BACKOFF_START_MS = 500
+const BACKOFF_MAX_MS = 10_000
+
+export interface PageChannelOptions {
+  readonly windowId: string
+  readonly focused: () => boolean
+  /** Where the door's routes are, e.g. `/api/acryl-door`. */
+  readonly base: string
+  readonly createSource?: (url: string) => ChannelSource
+  readonly post?: (url: string, body: string) => Promise<unknown>
+  readonly silenceMs?: number
+  readonly now?: () => number
+}
+
+export class PageChannel {
+  private source: ChannelSource | undefined
+  private reconnectTimer: ReturnType<typeof setTimeout> | undefined
+  private watchdog: ReturnType<typeof setInterval> | undefined
+  private backoff = BACKOFF_START_MS
+  private lastHeard = 0
+  private disposed = false
+  private readonly now: () => number
+
+  private readonly driver: UiDriver
+  private readonly options: PageChannelOptions
+
+  constructor(driver: UiDriver, options: PageChannelOptions) {
+    this.driver = driver
+    this.options = options
+    this.now = options.now ?? (() => Date.now())
+  }
+
+  connect(): void {
+    if (this.disposed || this.source !== undefined) return
+    const create = this.options.createSource ?? ((url: string): ChannelSource => new EventSource(url))
+    const query = `window=${encodeURIComponent(this.options.windowId)}&focused=${this.options.focused() ? '1' : '0'}`
+    const source = create(`${this.options.base}/channel?${query}`)
+    this.source = source
+    this.lastHeard = this.now()
+    const heard = (): void => {
+      this.lastHeard = this.now()
+      this.backoff = BACKOFF_START_MS
+    }
+    source.addEventListener('ready', heard)
+    source.addEventListener('ping', heard)
+    source.addEventListener('call', (event) => {
+      heard()
+      if (typeof event.data === 'string') this.answer(event.data)
+    })
+    // An EventSource retries by itself after a network error; once it gives up (CLOSED), the channel starts over.
+    source.onerror = () => { if (source.readyState === CLOSED) this.restart(source) }
+    const silence = this.options.silenceMs ?? SILENCE_MS
+    this.watchdog = setInterval(() => {
+      if (this.now() - this.lastHeard > silence) this.restart(source)
+    }, Math.max(50, Math.floor(silence / 3)))
+  }
+
+  /** Tell the Host whether this window is the one in front. */
+  reportFocus(focused: boolean): void {
+    this.send({ t: 'focus', focused })
+  }
+
+  dispose(): void {
+    this.disposed = true
+    if (this.reconnectTimer !== undefined) clearTimeout(this.reconnectTimer)
+    this.stop()
+  }
+
+  /** Drop the stream and open a new one after the backoff. */
+  private restart(source: ChannelSource): void {
+    if (this.source !== source) return
+    this.stop()
+    if (this.disposed) return
+    this.reconnectTimer = setTimeout(() => { this.reconnectTimer = undefined; this.connect() }, this.backoff)
+    this.backoff = Math.min(this.backoff * 2, BACKOFF_MAX_MS)
+  }
+
+  private stop(): void {
+    if (this.watchdog !== undefined) clearInterval(this.watchdog)
+    this.watchdog = undefined
+    const source = this.source
+    this.source = undefined
+    if (source !== undefined) {
+      source.onerror = null
+      source.close()
+    }
+  }
+
+  private answer(text: string): void {
+    let call
+    try {
+      call = parseChannelToPage(text)
+    } catch {
+      // A malformed call carries no usable id; there is nothing to answer.
+      return
+    }
+    this.driver.handle(call.request).then(
+      (value) => { this.send({ t: 'result', id: call.id, value }) },
+      (cause: unknown) => {
+        const failure = cause instanceof UiControlError ? cause : new UiControlError('not-actionable', cause instanceof Error ? cause.message : 'the action failed')
+        this.send({ t: 'error', id: call.id, code: failure.code, message: failure.message })
+      },
+    )
+  }
+
+  private send(message: ChannelToHost): void {
+    const post = this.options.post ?? ((url: string, body: string) => fetch(url, { method: 'POST', headers: { 'content-type': 'application/json' }, body }))
+    post(`${this.options.base}/channel/answer`, JSON.stringify({ window: this.options.windowId, message })).catch(() => {
+      // The Host is gone or restarting; the call it made settles on its side.
+    })
+  }
+}