acrylblends 0.7.8 → 0.8.1

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.
+    })
+  }
+}

package/plugins/acryl-door/src/page/driver/accessibility.ts

@@ -0,0 +1,163 @@
+/** Roles, accessible names and states of DOM elements, in the small subset a snapshot needs. */
+
+import { isSensitive } from './sensitivity.ts'
+
+const INPUT_ROLES: Record<string, string> = {
+  checkbox: 'checkbox', radio: 'radio', button: 'button', submit: 'button', reset: 'button', image: 'button',
+  range: 'slider', number: 'spinbutton', search: 'searchbox', text: 'textbox', email: 'textbox', url: 'textbox', tel: 'textbox', password: 'textbox',
+}
+
+const LANDMARKS: Record<string, string> = { nav: 'navigation', main: 'main', aside: 'complementary', dialog: 'dialog', form: 'form' }
+
+/** ARIA roles an element may declare that the driver treats as interactive or structural. */
+const EXPLICIT_ROLES = new Set([
+  'button', 'link', 'tab', 'tabpanel', 'menu', 'menuitem', 'menuitemcheckbox', 'menuitemradio', 'checkbox', 'radio', 'switch', 'textbox',
+  'searchbox', 'combobox', 'listbox', 'option', 'slider', 'spinbutton', 'dialog', 'alertdialog', 'alert', 'status', 'navigation', 'main',
+  'heading', 'tree', 'treeitem', 'row', 'gridcell', 'tablist', 'toolbar', 'region', 'form', 'img',
+])
+
+/** @returns the element's role, or null when it is not something a snapshot lists. */
+export function roleOf(el: Element): string | null {
+  const explicit = el.getAttribute('role')?.trim().toLowerCase().split(/\s+/)[0]
+  if (explicit !== undefined && explicit !== '' && EXPLICIT_ROLES.has(explicit)) return explicit
+  const tag = el.tagName.toLowerCase()
+  if (tag === 'a') return el.hasAttribute('href') ? 'link' : null
+  if (tag === 'button' || tag === 'summary') return 'button'
+  if (tag === 'select') return (el as HTMLSelectElement).multiple ? 'listbox' : 'combobox'
+  if (tag === 'textarea') return 'textbox'
+  if (/^h[1-6]$/.test(tag)) return 'heading'
+  if (tag === 'img') return el.getAttribute('alt')?.trim() ? 'img' : null
+  if (tag === 'input') {
+    const type = (el.getAttribute('type') ?? 'text').toLowerCase()
+    if (type === 'hidden') return null
+    return INPUT_ROLES[type] ?? 'textbox'
+  }
+  if (el.hasAttribute('contenteditable') && el.getAttribute('contenteditable') !== 'false') return 'textbox'
+  // A form is only a landmark when it has a name; an unnamed one is noise in a snapshot.
+  if (tag === 'form') return el.hasAttribute('aria-label') || el.hasAttribute('aria-labelledby') ? 'form' : null
+  return LANDMARKS[tag] ?? null
+}
+
+/** Roles whose accessible name is the text they contain, so that text is not listed again on its own. */
+export const NAMED_BY_CONTENT: ReadonlySet<string> = new Set(['button', 'link', 'tab', 'menuitem', 'menuitemcheckbox', 'menuitemradio', 'option', 'heading', 'switch', 'treeitem', 'checkbox', 'radio', 'alert', 'status'])
+
+/** Roles that show their content as a value (a field, a native select), so the text inside them is not listed on its own either. */
+export const SHOWN_AS_VALUE: ReadonlySet<string> = new Set(['textbox', 'searchbox', 'combobox', 'spinbutton'])
+
+export const collapse = (value: string): string => value.replace(/\s+/g, ' ').trim()
+export const clip = (value: string, max: number): string => (value.length > max ? `${value.slice(0, max - 1)}…` : value)
+
+/** The text a reader would hear: like `textContent`, but leaving out what is `aria-hidden` or `hidden` (a check mark, an icon glyph). */
+function readableText(root: Node): string {
+  const parts: string[] = []
+  const walk = (node: Node): void => {
+    if (node.nodeType === Node.TEXT_NODE) parts.push(node.textContent ?? '')
+    else if (!(node instanceof Element && (node.getAttribute('aria-hidden') === 'true' || node.hasAttribute('hidden')))) node.childNodes.forEach(walk)
+  }
+  // The element being named is never skipped itself; only what it contains.
+  root.childNodes.forEach(walk)
+  return parts.join('')
+}
+
+const textOf = (el: Element, max: number): string => clip(collapse(readableText(el)), max)
+
+/** The role of a run of visible text that is not already a control's name or a field's value: what an agent reads a value from. */
+export const TEXT_ROLE = 'text'
+
+/** The longest text run a snapshot carries. */
+export const MAX_TEXT = 200
+
+/** One run of text as a snapshot lists it: collapsed and clipped, empty when there is nothing to read. */
+export const textRun = (raw: string): string => clip(collapse(raw), MAX_TEXT)
+
+/** The runs of text directly inside an element (between its child elements), as a snapshot lists them. */
+export function textRunsOf(el: Element): string[] {
+  const runs: string[] = []
+  let run = ''
+  for (const child of Array.from(el.childNodes)) {
+    if (child.nodeType === Node.TEXT_NODE) run += child.textContent ?? ''
+    else if (child instanceof Element) { runs.push(textRun(run)); run = '' }
+  }
+  runs.push(textRun(run))
+  return runs.filter(text => text !== '')
+}
+
+/** ARIA-style accessible name, kept short. */
+export function nameOf(el: Element, role: string): string {
+  const aria = el.getAttribute('aria-label')?.trim()
+  if (aria !== undefined && aria !== '') return clip(collapse(aria), 120)
+  const by = el.getAttribute('aria-labelledby')
+  if (by !== null && by.trim() !== '') {
+    const joined = collapse(by.split(/\s+/).map(id => el.ownerDocument.getElementById(id)?.textContent ?? '').join(' '))
+    if (joined !== '') return clip(joined, 120)
+  }
+  if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement || el instanceof HTMLSelectElement) {
+    const id = el.id
+    const explicit = id === '' ? null : el.ownerDocument.querySelector(`label[for="${CSS.escape(id)}"]`)
+    const wrapping = el.closest('label')
+    const label = explicit ?? wrapping
+    const labelText = label === null ? '' : collapse(readableText(label))
+    if (labelText !== '') return clip(labelText, 120)
+    if (el instanceof HTMLInputElement && (el.type === 'button' || el.type === 'submit' || el.type === 'reset') && el.value !== '') return clip(el.value, 120)
+    const placeholder = el.getAttribute('placeholder')?.trim()
+    if (placeholder !== undefined && placeholder !== '') return clip(placeholder, 120)
+  }
+  if (role === 'img') return clip(collapse(el.getAttribute('alt') ?? ''), 120)
+  if (NAMED_BY_CONTENT.has(role)) {
+    const text = textOf(el, 120)
+    if (text !== '') return text
+  }
+  if (role === 'alert' || role === 'status' || role === 'dialog' || role === 'alertdialog') {
+    const text = textOf(el, 160)
+    if (text !== '') return text
+  }
+  return clip(collapse(el.getAttribute('title') ?? ''), 120)
+}
+
+/** The state words a snapshot shows for an element. */
+export function statesOf(el: Element, role: string): string[] {
+  const states: string[] = []
+  const aria = (name: string): string | null => el.getAttribute(name)
+  if ((el as HTMLButtonElement).disabled === true || aria('aria-disabled') === 'true') states.push('disabled')
+  if (el instanceof HTMLInputElement && (el.type === 'checkbox' || el.type === 'radio')) { if (el.checked) states.push('checked') } else if (aria('aria-checked') === 'true') states.push('checked')
+  if (aria('aria-expanded') === 'true') states.push('expanded')
+  if (aria('aria-expanded') === 'false') states.push('collapsed')
+  if (aria('aria-selected') === 'true') states.push('selected')
+  if (aria('aria-pressed') === 'true') states.push('pressed')
+  if (aria('aria-current') !== null && aria('aria-current') !== 'false') states.push('current')
+  if (aria('aria-invalid') === 'true') states.push('invalid')
+  if ((el as HTMLInputElement).required === true || aria('aria-required') === 'true') states.push('required')
+  if ((el as HTMLInputElement).readOnly === true || aria('aria-readonly') === 'true') states.push('readonly')
+  if (el.ownerDocument.activeElement === el) states.push('focused')
+  void role
+  return states
+}
+
+/** The visible value of an editable field, or undefined when it is empty, not editable, or sensitive. */
+export function valueOf(el: Element, role: string): string | undefined {
+  if (role !== 'textbox' && role !== 'searchbox' && role !== 'combobox' && role !== 'spinbutton') return undefined
+  if (isSensitive(el)) return undefined
+  let value: string | undefined
+  if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement) value = el.value
+  else if (el instanceof HTMLSelectElement) value = el.selectedOptions[0]?.textContent ?? undefined
+  else if (el.hasAttribute('contenteditable')) value = el.textContent ?? undefined
+  return value === undefined || value === '' ? undefined : clip(value, 100)
+}
+
+/** Heading level, when the element is a heading. */
+export function levelOf(el: Element): number | undefined {
+  const explicit = Number(el.getAttribute('aria-level'))
+  if (Number.isInteger(explicit) && explicit >= 1 && explicit <= 6) return explicit
+  const match = /^h([1-6])$/.exec(el.tagName.toLowerCase())
+  return match === null ? undefined : Number(match[1])
+}
+
+/** Hidden from everyone: the driver skips it and everything inside it. */
+export function isHidden(el: Element): boolean {
+  if (el.hasAttribute('hidden') || el.getAttribute('aria-hidden') === 'true') return true
+  if (el instanceof HTMLInputElement && el.type === 'hidden') return true
+  const view = el.ownerDocument.defaultView
+  if (view === null) return false
+  const style = view.getComputedStyle(el)
+  return style.display === 'none' || style.visibility === 'hidden'
+}

package/plugins/acryl-door/src/page/driver/actions.ts

@@ -0,0 +1,186 @@
+/** The actions the driver performs on the page, each guarded by the same rules. */
+
+import { MAX_WAIT_MS, UiControlError, type UiActionResult, type UiRequest } from '../protocol.ts'
+import { isHidden, nameOf, roleOf } from './accessibility.ts'
+import type { RefTable } from './ref-table.ts'
+import { isProtected, isSensitive } from './sensitivity.ts'
+import { DRIVER_UI_ATTRIBUTE } from './snapshot.ts'
+
+type Request<Op extends UiRequest['op']> = Extract<UiRequest, { op: Op }>
+
+const EDITABLE_ROLES = new Set(['textbox', 'searchbox', 'spinbutton', 'combobox'])
+const POLL_MS = 50
+
+export interface ActionEnvironment {
+  readonly refs: RefTable
+  readonly document: () => Document
+  /** Resolves after `ms`; rejects when `signal` aborts. Injectable so tests need no real time. */
+  readonly sleep: (ms: number, signal: AbortSignal) => Promise<void>
+}
+
+const target = (role: string, name: string): { role: string; name: string } => ({ role, name })
+
+function effectivelyHidden(element: Element): boolean {
+  for (let node: Element | null = element; node !== null; node = node.parentElement) if (isHidden(node)) return true
+  return false
+}
+
+/** Everything an action checks before touching an element. */
+function prepare(env: ActionEnvironment, ref: string): { element: Element; role: string; name: string } {
+  const resolved = env.refs.resolve(ref)
+  const { element } = resolved
+  if (isSensitive(element)) throw new UiControlError('sensitive', 'that is a password, token or payment field; the agent does not read or type into it')
+  if (isProtected(element)) throw new UiControlError('protected', `"${resolved.name}" belongs to approval, permissions or Agent Control itself; only the user operates it`)
+  if (effectivelyHidden(element)) throw new UiControlError('not-actionable', `"${resolved.name}" is not visible`)
+  if ((element as HTMLButtonElement).disabled === true || element.getAttribute('aria-disabled') === 'true') {
+    throw new UiControlError('not-actionable', `"${resolved.name}" is disabled`)
+  }
+  return resolved
+}
+
+function mouse(element: Element, type: string): void {
+  element.dispatchEvent(new MouseEvent(type, { bubbles: true, cancelable: true }))
+}
+
+/** xterm.js reads neither the value of its input textarea nor a bare synthetic key: text arrives as a paste, and key handling reads the legacy `keyCode`. */
+function isTerminalInput(element: Element): boolean {
+  return element.classList.contains('xterm-helper-textarea')
+}
+
+function pasteInto(element: Element, text: string): void {
+  const clipboardData = new DataTransfer()
+  clipboardData.setData('text/plain', text)
+  element.dispatchEvent(new ClipboardEvent('paste', { clipboardData, bubbles: true, cancelable: true }))
+}
+
+const LEGACY_KEY_CODES: Readonly<Record<string, number>> = {
+  Backspace: 8, Tab: 9, Enter: 13, Escape: 27, ' ': 32, PageUp: 33, PageDown: 34, End: 35, Home: 36,
+  ArrowLeft: 37, ArrowUp: 38, ArrowRight: 39, ArrowDown: 40, Delete: 46,
+}
+
+function setNativeValue(element: HTMLInputElement | HTMLTextAreaElement, value: string): void {
+  const proto = element instanceof HTMLTextAreaElement ? HTMLTextAreaElement.prototype : HTMLInputElement.prototype
+  const setter = Object.getOwnPropertyDescriptor(proto, 'value')?.set
+  if (setter === undefined) element.value = value
+  else setter.call(element, value)
+}
+
+export function click(env: ActionEnvironment, request: Request<'click'>): UiActionResult {
+  const { element, role, name } = prepare(env, request.ref)
+  ;(element as HTMLElement).scrollIntoView?.({ block: 'nearest' })
+  ;(element as HTMLElement).focus?.()
+  mouse(element, 'mousedown')
+  mouse(element, 'mouseup')
+  ;(element as HTMLElement).click()
+  return { ok: true, target: target(role, name) }
+}
+
+export function typeText(env: ActionEnvironment, request: Request<'type'>): UiActionResult {
+  const { element, role, name } = prepare(env, request.ref)
+  if (!EDITABLE_ROLES.has(role) || (role === 'combobox' && element instanceof HTMLSelectElement)) {
+    throw new UiControlError('not-actionable', `"${name}" is a ${role}, not a text field; use select or click`)
+  }
+  if ((element as HTMLInputElement).readOnly === true || element.getAttribute('aria-readonly') === 'true') {
+    throw new UiControlError('not-actionable', `"${name}" is read-only`)
+  }
+  const clear = request.clear ?? true
+  ;(element as HTMLElement).focus?.()
+  if (isTerminalInput(element)) {
+    // A terminal has no text to clear: what is typed goes to the process that is running in it.
+    pasteInto(element, request.text)
+  } else if (element instanceof HTMLInputElement || element instanceof HTMLTextAreaElement) {
+    setNativeValue(element, clear ? request.text : element.value + request.text)
+    element.dispatchEvent(new Event('input', { bubbles: true }))
+    element.dispatchEvent(new Event('change', { bubbles: true }))
+  } else {
+    element.textContent = clear ? request.text : (element.textContent ?? '') + request.text
+    element.dispatchEvent(new Event('input', { bubbles: true }))
+  }
+  if (request.submit === true) pressKey(env, { op: 'press', key: 'Enter', ref: request.ref })
+  return { ok: true, target: target(role, name), detail: `typed ${String(request.text.length)} characters` }
+}
+
+export function selectOption(env: ActionEnvironment, request: Request<'select'>): UiActionResult {
+  const { element, role, name } = prepare(env, request.ref)
+  if (!(element instanceof HTMLSelectElement)) throw new UiControlError('not-actionable', `"${name}" is a ${role}, not a select; click it and pick the option`)
+  const wanted = request.option.trim().toLowerCase()
+  const options = Array.from(element.options)
+  const match = options.find(option => option.value.toLowerCase() === wanted) ?? options.find(option => (option.textContent ?? '').trim().toLowerCase() === wanted)
+  if (match === undefined) throw new UiControlError('not-found', `"${name}" has no option "${request.option}"`)
+  if (match.disabled) throw new UiControlError('not-actionable', `the option "${request.option}" is disabled`)
+  element.value = match.value
+  element.dispatchEvent(new Event('input', { bubbles: true }))
+  element.dispatchEvent(new Event('change', { bubbles: true }))
+  return { ok: true, target: target(role, name), detail: `selected ${match.textContent?.trim() ?? match.value}` }
+}
+
+export function pressKey(env: ActionEnvironment, request: Request<'press'>): UiActionResult {
+  const doc = env.document()
+  let element: Element
+  let role: string
+  let name: string
+  if (request.ref !== undefined) {
+    ({ element, role, name } = prepare(env, request.ref))
+  } else {
+    element = doc.activeElement ?? doc.body
+    if (isSensitive(element)) throw new UiControlError('sensitive', 'the focused field is a password, token or payment field')
+    if (isProtected(element)) throw new UiControlError('protected', 'the focused control belongs to approval, permissions or Agent Control itself')
+    role = roleOf(element) ?? 'page'
+    name = roleOf(element) === null ? '' : nameOf(element, role)
+  }
+  const key = request.key === 'Space' ? ' ' : request.key
+  const keyCode = LEGACY_KEY_CODES[key]
+  const init = { key, bubbles: true, cancelable: true, ...(keyCode === undefined ? {} : { keyCode, which: keyCode }) }
+  ;(element as HTMLElement).focus?.()
+  const proceed = element.dispatchEvent(new KeyboardEvent('keydown', init))
+  if (proceed) {
+    // A synthetic key event does not do what a real one does, so the two defaults that matter are done here.
+    if ((key === 'Enter' || key === ' ') && (role === 'button' || role === 'link')) (element as HTMLElement).click()
+    else if (key === 'Enter' && element instanceof HTMLInputElement && element.form !== null) element.form.requestSubmit?.()
+  }
+  element.dispatchEvent(new KeyboardEvent('keyup', init))
+  return { ok: true, target: target(role, name), detail: `pressed ${request.key}` }
+}
+
+export function scroll(env: ActionEnvironment, request: Request<'scroll'>): UiActionResult {
+  const doc = env.document()
+  const amount = request.amount ?? 400
+  const dx = request.direction === 'left' ? -amount : request.direction === 'right' ? amount : 0
+  const dy = request.direction === 'up' ? -amount : request.direction === 'down' ? amount : 0
+  if (request.ref !== undefined) {
+    const { element, role, name } = env.refs.resolve(request.ref)
+    ;(element as HTMLElement).scrollBy?.({ left: dx, top: dy })
+    if (typeof (element as HTMLElement).scrollBy !== 'function') { element.scrollTop += dy; element.scrollLeft += dx }
+    return { ok: true, target: target(role, name), detail: `scrolled ${request.direction}` }
+  }
+  const view = doc.defaultView
+  view?.scrollBy?.({ left: dx, top: dy })
+  return { ok: true, detail: `scrolled the page ${request.direction}` }
+}
+
+/** True when something visible on the page matches `request`. */
+function present(env: ActionEnvironment, request: Request<'wait'>): boolean {
+  const doc = env.document()
+  const walk = (element: Element): boolean => {
+    if (element.hasAttribute(DRIVER_UI_ATTRIBUTE) || isHidden(element) || isSensitive(element)) return false
+    const role = roleOf(element)
+    if (request.role !== undefined || request.name !== undefined) {
+      if (role !== null && (request.role === undefined || role === request.role.toLowerCase()) && (request.name === undefined || nameOf(element, role).toLowerCase().includes(request.name.toLowerCase()))) return true
+    }
+    if (request.text !== undefined && element.children.length === 0 && (element.textContent ?? '').toLowerCase().includes(request.text.toLowerCase())) return true
+    return Array.from(element.children).some(walk)
+  }
+  return walk(doc.body)
+}
+
+export async function wait(env: ActionEnvironment, request: Request<'wait'>, signal: AbortSignal): Promise<UiActionResult> {
+  const budget = Math.min(request.timeoutMs ?? 3000, MAX_WAIT_MS)
+  let waited = 0
+  const wantGone = request.gone === true
+  for (;;) {
+    if (present(env, request) !== wantGone) return { ok: true, detail: wantGone ? 'it is gone' : 'it is there' }
+    if (waited >= budget) throw new UiControlError('not-found', wantGone ? 'it did not go away in time' : 'it did not appear in time')
+    await env.sleep(POLL_MS, signal)
+    waited += POLL_MS
+  }
+}