@thincoder/core 0.10.5 → 0.10.7

package/browser/queue.mjs

@@ -0,0 +1,171 @@
+/**
+ * browser/queue.mjs — 调度策略：串行队列 ∥ 动作预算表 ∥ 动作控制器（超时 / 取消单点）∥ 步名跟踪
+ * （设计权威 = `docs/core/design/BROWSER-TOOL.md` §2.9——单时钟动作预算 + 三层帽；KD-18 ∥ KD-19）。
+ *
+ * 单时钟：预算 deadline 自**入队**起算（队列等待计入预算——有意）；到点 ⇒ 控制器 `abort`（超时因由）。
+ * 排队期到点 ⇒ 动作从未起执行（回执步名 `queue wait`）；动作内到点 ⇒ 步名 = 在飞阶段 / CDP 方法名。
+ * 控制器（超时 ∥ 取消共用——KD-19）：abort 后在飞操作以同一因由拒绝，其后一切调用**快速失败**
+ * （清理路径不得再起命令——防僵尸命令与下一动作交错）。
+ * 步名：`ctl.run(name, fn)` 压帧（栈顶 = `stuck in <步名>` 的读数源）；`h.call` 帧 = CDP 方法名（session 侧接线）。
+ */
+import { WAIT_TIMEOUT_DEFAULT, WAIT_TIMEOUT_MAX } from "./actions.mjs"
+
+/** 动作预算表（§2.9——机检）：动作 ⇒ 预算 ms。wait 无固定值（谓词帽 + 余量——`budgetFor` 解算）。 */
+export const ACTION_BUDGETS = {
+  navigate: 45_000, // 含会话自启（12s 启动帽内）+ 导航 + 就绪轮询 + 快照
+  click: 30_000,
+  evaluate: 30_000,
+  screenshot: 30_000,
+  close: 30_000,
+  press: 30_000,
+  hover: 30_000,
+  wheel: 30_000,
+  mouse: 30_000,
+  drag: 30_000,
+  touch: 30_000,
+  insert: 30_000,
+  clipboard: 30_000,
+  type: 15_000, // 单页内快动作
+  snapshot: 15_000,
+  wait: 45_000, // = 谓词帽缺省 30s + 15s 余量（timeoutMs 给出时按帽 + 余量重解——§2.9 表）
+}
+export const BUDGET_FALLBACK_MS = 30_000 // 未在册动作的兜底预算（防御——全部在册动作已列）
+export const BUDGET_MAX_MS = 120_000 // `timeoutMs` override 硬上限（§2.9）
+export const WAIT_MARGIN_MS = 15_000 // wait 预算余量（谓词帽之上——§2.9 表）
+export const QUEUE_WAIT_STEP = "queue wait"
+
+/** 预算解算（§2.9）：`timeoutMs` = 动作预算 override（硬上限 120s）；wait = 谓词帽 + 15s 余量（语义零变）。 */
+export function budgetFor(action, args = {}) {
+  const wanted = Number(args?.timeoutMs)
+  const given = Number.isFinite(wanted) && wanted > 0
+  if (action === "wait") {
+    return (given ? Math.min(wanted, WAIT_TIMEOUT_MAX) : WAIT_TIMEOUT_DEFAULT) + WAIT_MARGIN_MS
+  }
+  if (given) return Math.min(wanted, BUDGET_MAX_MS)
+  return ACTION_BUDGETS[action] ?? BUDGET_FALLBACK_MS
+}
+
+/** 单动作控制器：超时 / 取消 / 会话丢失共用一个中止点（一个机制多个因由——KD-19）。 */
+export class ActionController {
+  constructor({ action, budgetMs }) {
+    this.action = action
+    this.budgetMs = budgetMs
+    this.aborted = false
+    this.reason = null
+    this.error = null
+    this._deadline = Date.now() + budgetMs
+    this._steps = []
+    this._abortHooks = []
+    this._abortP = new Promise((resolve) => { this._resolveAbort = resolve })
+    this._timer = setTimeout(() => this.abort("timeout"), budgetMs)
+  }
+
+  /** 剩余预算（ms）——动作内调用帽的下界参照（§2.9 层一：动作内调用随控制器）。 */
+  remaining() {
+    return Math.max(1, this._deadline - Date.now())
+  }
+
+  /** 快速失败（§2.9）：abort 之后一切后续调用即刻拒绝（清理路径不得再起命令）。 */
+  failIfAborted() {
+    if (this.aborted) throw this.error
+  }
+
+  /** 步名帧 + 中止守卫：帧存活期栈顶 = `stuck in <name>` 读数源；work 随中止以同一因由拒绝。 */
+  run(name, work) {
+    this.failIfAborted()
+    this._steps.push(name)
+    let out
+    try { out = work() } catch (e) { this._pop(name); throw e }
+    return this.guard(Promise.resolve(out)).finally(() => this._pop(name))
+  }
+
+  /** 中止守卫：在飞工作与中止竞速（未中止 ⇒ 原样返回）。 */
+  guard(work) {
+    if (this.aborted) return Promise.reject(this.error)
+    return Promise.race([work, this._abortP.then(() => Promise.reject(this.error))])
+  }
+
+  /** 受控等待（§2.9 层一：轮询 sleep 同受控）。 */
+  async sleep(ms) {
+    let timer = null
+    try {
+      await this.guard(new Promise((resolve) => { timer = setTimeout(resolve, ms) }))
+    } finally {
+      if (timer) clearTimeout(timer)
+    }
+  }
+
+  /** 订阅一次中止（发出即退订）；返回退订函数。 */
+  onAbort(fn) {
+    if (this.aborted) { fn(); return () => {} }
+    this._abortHooks.push(fn)
+    return () => { this._abortHooks = this._abortHooks.filter((hook) => hook !== fn) }
+  }
+
+  /** 中止单点：因由 = timeout ∥ cancelled ∥ session-lost（错误句分形——§2.9 / §2.10）。 */
+  abort(reason, error = null) {
+    if (this.aborted) return this.error
+    this.aborted = true
+    this.reason = reason
+    this.error = error ?? this._makeError(reason)
+    if (this._timer) { clearTimeout(this._timer); this._timer = null }
+    this._resolveAbort()
+    for (const hook of this._abortHooks.splice(0)) { try { hook() } catch { /* 订阅者自担 */ } }
+    return this.error
+  }
+
+  /** 取消（§2.11 kill 单点——与超时共用控制器）。 */
+  cancel() {
+    return this.abort("cancelled")
+  }
+
+  /** 动作结束（清钟——不中止）。 */
+  finish() {
+    if (this._timer) { clearTimeout(this._timer); this._timer = null }
+  }
+
+  _pop(name) {
+    const at = this._steps.lastIndexOf(name)
+    if (at >= 0) this._steps.splice(at, 1)
+  }
+
+  _makeError(reason) {
+    const step = this._steps.at(-1) ?? QUEUE_WAIT_STEP
+    const message = reason === "cancelled"
+      ? `${this.action} cancelled (stuck in ${step})`
+      : `${this.action} timed out after ${this.budgetMs}ms (stuck in ${step}) — retry the action, or run \`close\` to reset the session`
+    const error = new Error(message)
+    error.browserAbort = true
+    error.abortReason = reason
+    return error
+  }
+}
+
+/** 串行队列（§2.4：批并行调用按调用序排队——单页不引入并发）。 */
+export function createActionQueue() {
+  let tail = Promise.resolve()
+  const chain = (task) => {
+    const next = tail.then(task)
+    tail = next.then(() => { /* 保持链活 */ }, () => { /* 失败不断链 */ })
+    return next
+  }
+  return {
+    /** 入队动作：`run(ctl)` 起执行；返回终态（回执 ∥ 拒绝）。排队中到点 ⇒ 即时以同失败形拒绝
+     *  （`queue wait`——动作从未起执行）；起执行后由任务自身守卫裁决 —— 回执/拒绝晚于动作收尾
+     *  （调用方拿到终态时会话侧清理已完成，不留残余控制器）。
+     *  signal（批 browser-async-fix 最小增补——可选取消柄）：abort ⇒ `cancel()`（queued 丢队 ∥ running 展开）；缺省 null 旧调用零变。 */
+    enqueue(action, args, run, signal = null) {
+      const ctl = new ActionController({ action, budgetMs: budgetFor(action, args) })
+      if (signal?.aborted) ctl.cancel()
+      else signal?.addEventListener("abort", () => ctl.cancel(), { once: true })
+      let started = false
+      const task = chain(() => { started = true; return run(ctl) }).finally(() => ctl.finish())
+      return new Promise((resolve, reject) => {
+        task.then(resolve, reject)
+        ctl.onAbort(() => { if (!started) reject(ctl.error) })
+      })
+    },
+    /** 队列直通（无预算语义——空闲关等动作外路径）。 */
+    chain,
+  }
+}

package/browser/session.mjs

@@ -0,0 +1,494 @@
+/**
+ * browser/session.mjs — 会话单例：惰性开启 ∥ 串行队列 ∥ 生命周期 ∥ 页原语 ∥ 安全助手 ∥ 分发表 ∥ 会话句柄。
+ * 设计权威 = `docs/core/design/BROWSER-TOOL.md` §2.4（会话模型）∥ §2.5（数据流）∥ §2.9–§2.10（动作预算 /
+ * 会话健康）∥ §3（安全面）∥ §5（拆分决定）。
+ *
+ * 单会话/进程（KD-5）：同进程所有 agent 共一份浏览器；动作串行（同一队列——批并行调用天然排队）。
+ * 硬超时（§2.9）：每动作入队即记预算 deadline（队列等待计入——有意），到点由 `queue.mjs` 动作控制器中止
+ * （错误句携卡点步名）；一切 CDP 命令经本档 `cdpCall` 单点接线（步名 = 方法名 ∥ 中止守卫 ∥ abort 后快速失败）。
+ * 会话健康（§2.10）：进程事件 ∥ 连接事件 ∥ 入口探针三源；外部关闭 ⇒ `failSession` 单点（拒在飞 ⇒ 态复位
+ * ⇒ 释放 profile 锁 ⇒ 置重开注记），下一次动作自愈重开（首回执尾行注记——置位一次，发出即清）。
+ * `headless` = 会话开启参数（KD-4：异值报错，不热切）；空闲 15 分钟自动关（KD-8）+ 进程退出杀树兜底。
+ * 动作实施层 = `actions.mjs`（基线八）+ `input-actions.mjs`（新七）+ `clipboard.mjs`——经会话句柄取能力，
+ * 不 import 本档（DAG 单向：`session → {actions, input-actions, clipboard} → {input, snapshot, cdp}`；`session → queue`，§5）。
+ *
+ * 注入缝（N-BT6）：`_deps.openBrowser` ∥ `_deps.killBrowser` ∥ `_deps.saveShot`——缺省 null ⇒
+ * 回落真实现（`??`）；用例注入后 `finally` 还原。
+ */
+import { mkdirSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+import { ACTIONS } from "./actions.mjs"
+import { CLIPBOARD_ACTIONS } from "./clipboard.mjs"
+import { INPUT_ACTIONS } from "./input-actions.mjs"
+import { DEFAULT_CALL_TIMEOUT_MS, connectCdp, newTabWebSocketUrl } from "./cdp.mjs"
+import { acquireProfileLock, browserPaths, killBrowser, launchBrowser, releaseProfileLock, resolveBrowser } from "./launch.mjs"
+import { createActionQueue } from "./queue.mjs"
+import {
+  COMPACT_ROWS, DEFAULT_MAX, MAX_ELEMENTS, assignRefs, createRefTable, focusExpression, normalizeSnapshot,
+  pageInfoExpression, renderSnapshot, snapshotExpression,
+} from "./snapshot.mjs"
+
+export const IDLE_MS = 15 * 60 * 1000
+const READY_TIMEOUT_MS = 10_000
+const NAV_SETTLE_MS = 1_000
+const GRACEFUL_CLOSE_MS = 3_000
+const CLOSE_CALL_MS = 3_000 // `Browser.close` 显式帽（§2.9 层二）
+const ENABLE_CALL_MS = 10_000 // `Page/Runtime/Network.enable` 显式帽（§2.9 层二）
+const PROBE_TIMEOUT_MS = 2_000 // 健康探针心跳帽（§2.9 层二 / §2.10 源③）
+const PROBE_FRESH_MS = 5_000 // 距上次成功 CDP 活动 >5s 才做心跳（§2.10 源③）
+const CALL_CAP_SLACK_MS = 1_000 // 动作内调用兜底帽对剩余预算的余量（预算先行：控制器先于兜底帽裁决）
+const REOPEN_NOTE = "[note: the previous browser session was closed externally — a fresh session was opened (page state lost; profile/login kept)]"
+
+/** 测试替身缝（缺省 null ⇒ 回落真实现）。 */
+export const _deps = { openBrowser: null, killBrowser: null, saveShot: null }
+
+/** 在飞动作的控制器（§2.9——单动作单控制器；串行队列 ⇒ 同刻至多一个）。 */
+let currentController = null
+
+const queue = createActionQueue()
+
+const sleep = (ms) => (currentController ? currentController.sleep(ms) : new Promise((r) => setTimeout(r, ms)))
+
+/** 控制器接线（无控制器 ⇒ 直通）：步名帧 + 中止守卫（§2.9）。 */
+function runFrame(name, work) {
+  return currentController ? currentController.run(name, work) : work()
+}
+
+const state = {
+  cdp: null,
+  child: null,
+  lockPath: null,
+  headless: null,
+  table: createRefTable(),
+  lastUrl: null,
+  lastTitle: null,
+  lastActivityAt: 0,
+  idleTimer: null,
+  reopenNote: false,
+  net: { inflight: new Set(), lastEventAt: 0 },
+}
+
+// ── 生命周期 ────────────────────────────────────────────────────────────────
+
+/** 真实现：发现 → profile 锁 → spawn → `/json/new` → WebSocket → 三域 enable（§2.4 开启序）。
+ *  开启段中途中止 ⇒ 连接复位 + 杀树兜底（含「launch 未返回」窗口：结算即补杀）+ 释放 profile 锁；置重开注记在 ensureSession。 */
+async function openBrowserReal({ headless }) {
+  const exe = resolveBrowser()
+  const paths = browserPaths()
+  acquireProfileLock(paths.lock)
+  let child = null, conn = null, launching = null
+  try {
+    const launched = await runFrame("launch browser", () => (launching = launchBrowser({ exe, headless, profile: paths.profile })))
+    child = launched.child
+    const wsUrl = await runFrame("connect CDP", () => newTabWebSocketUrl(launched.port))
+    conn = await runFrame("connect CDP", () => connectCdp(wsUrl))
+    for (const domain of ["Page.enable", "Runtime.enable", "Network.enable"]) {
+      await runFrame(domain, () => conn.call(domain, {}, { timeoutMs: ENABLE_CALL_MS }))
+    }
+    return { cdp: conn, child, headless, lock: paths.lock }
+  } catch (e) {
+    try { conn?.close() } catch { /* 已断 */ }
+    // 中止落在「launch 未返回」窗口 ⇒ child 未赋值：自启仍会结算 ⇒ 结算即补杀（§2.9 开启段中止——防孤儿）
+    if (child) { try { (_deps.killBrowser ?? killBrowser)(child) } catch { /* 已退出 */ } }
+    else if (launching) launching.then((l) => { try { (_deps.killBrowser ?? killBrowser)(l.child) } catch { /* 已退出 */ } }, () => { /* 自启自败（其内已杀树） */ })
+    releaseProfileLock(paths.lock)
+    throw e
+  }
+}
+
+/** 会话态复位（关闭 ∥ 外部关闭共用单点）。 */
+function resetState() {
+  disarmIdle()
+  state.cdp = null
+  state.child = null
+  state.lockPath = null
+  state.headless = null
+  state.lastUrl = null
+  state.lastTitle = null
+  state.lastActivityAt = 0
+  state.table = createRefTable()
+  state.net = { inflight: new Set(), lastEventAt: 0 }
+}
+
+function armIdle() {
+  if (state.idleTimer) clearTimeout(state.idleTimer)
+  state.idleTimer = setTimeout(() => {
+    // 走串行队列：空闲关不与在途动作交错（下一动作排在关后——同 profile 不会双开）
+    queue.chain(() => closeSession()).catch(() => { /* 空闲关失败不逸出 */ })
+  }, IDLE_MS)
+  state.idleTimer.unref?.() // 不为一台浏览器吊住宿主进程
+}
+
+function disarmIdle() {
+  if (state.idleTimer) { clearTimeout(state.idleTimer); state.idleTimer = null }
+}
+
+let exitHooked = false
+function registerExitHook() {
+  if (exitHooked) return
+  exitHooked = true
+  process.once("exit", () => { if (state.child) (_deps.killBrowser ?? killBrowser)(state.child) })
+}
+
+function headlessOf(args) {
+  return typeof args?.headless === "boolean" ? args.headless : undefined
+}
+
+// ── 会话健康（§2.10——外部关闭可感知 + 自愈）────────────────────────────────
+
+/** 外部关闭显式失败句（§2.10）：在飞动作与入口探针同一句式。 */
+function externalCloseError(cause) {
+  const error = new Error(`the browser session was closed externally (${cause}) — run the action again to reopen a fresh session`)
+  error.sessionLost = true
+  return error
+}
+
+/** 处置单点（§2.10）：拒在飞（同一因由实例）⇒ 态复位 ⇒ 释放 profile 锁（子进程仍活 ⇒ 杀树兜底）⇒ 置重开注记。
+ *  不调 `Browser.close`、不等自退（连接 / 进程已死）。 */
+function failSession(cause) {
+  const error = externalCloseError(cause)
+  currentController?.abort("session-lost", error)
+  const { cdp, child, lockPath } = state
+  resetState()
+  if (cdp) { try { cdp.close() } catch { /* 已断 */ } }
+  if (child) { try { (_deps.killBrowser ?? killBrowser)(child) } catch { /* 已退出 */ } }
+  if (lockPath) releaseProfileLock(lockPath)
+  state.reopenNote = true
+  return error
+}
+
+/** 健康接线（§2.10 源①②）：子进程 exit/error ∥ WS 断连 ⇒ 即时失败化。 */
+function attachSessionHealth(cdp) {
+  const child = state.child
+  if (child && typeof child.on === "function") {
+    const gone = () => { if (state.child === child) failSession("the browser process exited") }
+    child.on("exit", gone)
+    child.on("error", gone)
+  }
+  cdp.onDisconnect?.(() => { if (state.cdp === cdp) failSession("the connection to the browser dropped") })
+}
+
+/** 入口探针（§2.10 源③）：子进程存活 ∧ 连接未关（恒检——零成本）；距上次成功活动 >5s ⇒ 心跳 `Browser.getVersion`（2s 帽）。 */
+async function probeSession() {
+  const child = state.child
+  // 非真实子进程（无事件面的替身）⇒ 存活不可判——跳过该检（真实现恒有 ChildProcess 事件面）
+  if (child && typeof child.on === "function" && (child.exitCode !== null || child.signalCode != null)) {
+    throw failSession("the browser process exited")
+  }
+  if (state.cdp?.closed) throw failSession("the connection to the browser dropped")
+  if (Date.now() - state.lastActivityAt < PROBE_FRESH_MS) return
+  try {
+    await cdpCall("Browser.getVersion", {}, { timeoutMs: PROBE_TIMEOUT_MS })
+  } catch (e) {
+    if (e?.browserAbort || e?.sessionLost) throw e // 预算中止 / 会话已失 ⇒ 原样上报（fresh 判据已由它裁决）
+    throw failSession("the browser is not responding")
+  }
+}
+
+/** 会话开启（惰性 + headless 一致性判据 + 入口探针）；开启段中止 ⇒ 置重开注记（半开态已由
+ *  `openBrowserReal` 复位）——下一次动作干净重开，不中毒（§2.9 开启段中止）。 */
+async function ensureSession(wanted) {
+  if (state.cdp) {
+    if (wanted !== undefined && wanted !== state.headless) {
+      throw new Error(`session is already running (headless=${state.headless}) — close it first to switch mode`)
+    }
+    await probeSession()
+    return
+  }
+  let opened
+  try {
+    opened = await runFrame("launch browser", () => (_deps.openBrowser ?? openBrowserReal)({ headless: wanted === undefined ? true : wanted }))
+  } catch (e) {
+    if (e?.browserAbort) state.reopenNote = true
+    throw e
+  }
+  state.cdp = opened.cdp
+  state.child = opened.child ?? null
+  state.lockPath = opened.lock ?? null
+  state.headless = opened.headless === undefined ? (wanted ?? true) : opened.headless
+  state.table = createRefTable()
+  state.net = { inflight: new Set(), lastEventAt: Date.now() }
+  state.lastActivityAt = Date.now()
+  const net = state.net
+  opened.cdp.on("Network.requestWillBeSent", (p) => { net.inflight.add(p.requestId); net.lastEventAt = Date.now() })
+  opened.cdp.on("Network.loadingFinished", (p) => { net.inflight.delete(p.requestId); net.lastEventAt = Date.now() })
+  opened.cdp.on("Network.loadingFailed", (p) => { net.inflight.delete(p.requestId); net.lastEventAt = Date.now() })
+  attachSessionHealth(opened.cdp)
+  registerExitHook()
+  armIdle()
+}
+
+/** 等子进程自退（优雅关后）。 */
+async function waitForExit(child, maxMs) {
+  const deadline = Date.now() + maxMs
+  while (child.exitCode == null && Date.now() < deadline) await sleep(100)
+}
+
+/** 关闭会话（幂等）；返回是否有会话被关。
+ *  先 `Browser.close` 优雅关（浏览器自行落盘 profile——Cookie/localStorage 持久化是 F-BT6 的落盘前提；
+ *  实测：直杀树不落盘 ⇒ 二段会话拿不到 Cookie），再等自退，未退才走杀树兜底。
+ *  中止（预算 / 取消）⇒ 跳过优雅等待、直接杀树兜底，清理完成后以中止因由上报（§2.9 abort 语义）。 */
+export async function closeSession() {
+  const { cdp, child, lockPath } = state
+  resetState()
+  let aborted = null
+  if (cdp) {
+    try { await runFrame("Browser.close", () => cdp.call("Browser.close", {}, { timeoutMs: CLOSE_CALL_MS })) }
+    catch (e) { if (e?.browserAbort) aborted = e /* 已断 ∥ 不支持 ∥ 中止 ⇒ 转杀树兜底 */ }
+    try { cdp.close() } catch { /* 已断 */ }
+  }
+  if (child) {
+    if (!aborted) {
+      try { await runFrame("Browser.close", () => waitForExit(child, GRACEFUL_CLOSE_MS)) }
+      catch (e) { if (e?.browserAbort) aborted = e }
+    }
+    if (aborted || child.exitCode == null) {
+      try { (_deps.killBrowser ?? killBrowser)(child) } catch { /* 已退出 */ }
+    }
+  }
+  if (lockPath) releaseProfileLock(lockPath)
+  if (aborted) throw aborted
+  return Boolean(cdp)
+}
+
+/** 审批请示面用的「最近页 URL」（§3.1 文案；无会话 ⇒ null）。 */
+export function lastPageUrl() {
+  return state.lastUrl
+}
+
+// ── 页原语 ──────────────────────────────────────────────────────────────────
+
+/** 一切 CDP 命令的单点（§2.9 层一）：步名帧（方法名）∥ 中止守卫 ∥ abort 后快速失败；成功 ⇒ 记活动时刻。
+ *  缺省帽（层三 15s）在动作预算内让位于控制器（预算先行——层一优先：兜底帽 = 剩余预算 + 1s 余量）；
+ *  动作外路径按缺省帽兜底。 */
+function cdpCall(method, params = {}, { timeoutMs } = {}) {
+  const cdp = state.cdp
+  if (!cdp) throw new Error("no browser session — run navigate first")
+  const ctl = currentController
+  ctl?.failIfAborted()
+  const cap = timeoutMs ?? (ctl ? Math.max(DEFAULT_CALL_TIMEOUT_MS, ctl.remaining() + CALL_CAP_SLACK_MS) : DEFAULT_CALL_TIMEOUT_MS)
+  const work = ctl ? ctl.run(method, () => cdp.call(method, params, { timeoutMs: cap })) : cdp.call(method, params, { timeoutMs: cap })
+  return Promise.resolve(work).then(
+    (result) => { state.lastActivityAt = Date.now(); return result },
+    (e) => { if (ctl?.aborted) throw ctl.error; throw e },
+  )
+}
+
+async function evalRaw(expression) {
+  // CDP 形：`call()` 解到命令的 result（`{result: RemoteObject}`）——页面值在 `result.result.value`
+  const r = await cdpCall("Runtime.evaluate", { expression, awaitPromise: true, returnByValue: true })
+  if (r?.exceptionDetails) throw pageError(exceptionText(r.exceptionDetails)) // 页面侧异常 ⇒ 同失败回执面（带页摘）
+  return r?.result?.value
+}
+
+function exceptionText(details) {
+  const raw = details?.exception?.description ?? details?.text ?? "unknown page exception"
+  return String(raw).split("\n")[0]
+}
+
+async function pageInfo() {
+  const v = await evalRaw(pageInfoExpression())
+  const info = { url: String(v?.url ?? ""), title: String(v?.title ?? ""), readyState: String(v?.readyState ?? "") }
+  state.lastUrl = info.url
+  state.lastTitle = info.title
+  return info
+}
+
+async function waitForReady(maxMs = READY_TIMEOUT_MS) {
+  return runFrame("waitForReady", async () => {
+    const deadline = Date.now() + maxMs
+    for (;;) {
+      const info = await pageInfo()
+      if (info.readyState === "complete" || Date.now() >= deadline) return info
+      await sleep(100)
+    }
+  })
+}
+
+async function waitForUrlChange(before, maxMs = NAV_SETTLE_MS) {
+  return runFrame("wait poll", async () => {
+    const deadline = Date.now() + maxMs
+    for (;;) {
+      const info = await pageInfo()
+      if (info.url !== before) return info.url
+      if (Date.now() >= deadline) return null
+      await sleep(100)
+    }
+  })
+}
+
+/** 取快照 + 分配引用 + 渲染（会话内单一快照点）。 */
+async function takeSnapshot({ selector = null, max = DEFAULT_MAX } = {}) {
+  const wanted = Number(max)
+  const capped = Math.max(1, Math.min(Number.isFinite(wanted) ? Math.floor(wanted) : DEFAULT_MAX, MAX_ELEMENTS))
+  const snap = normalizeSnapshot(await evalRaw(snapshotExpression({ selector, max: capped })))
+  if (snap.missing) {
+    throw pageError(`snapshot selector "${selector}" matched nothing — pass a CSS selector present on the page`)
+  }
+  const rows = assignRefs(state.table, snap.elements)
+  state.lastUrl = snap.url
+  state.lastTitle = snap.title
+  return {
+    url: snap.url,
+    title: snap.title,
+    total: snap.total,
+    rows,
+    text: renderSnapshot({ url: snap.url, title: snap.title, rows, total: snap.total }),
+  }
+}
+
+/** ref → 引用表条目（未在表 ⇒ 同 stale 句式——§2.3 失效口径）。 */
+function resolveRef(ref) {
+  const entry = state.table.byRef.get(String(ref))
+  if (!entry) throw pageError(`ref ${ref} is stale (was "unknown") — run snapshot again`)
+  return entry
+}
+
+/** ref → 聚焦（§2.7）：表查 + `focusExpression`；不可聚焦 ⇒ 明示拒（不静默错投）。 */
+async function focusRef(ref) {
+  const entry = resolveRef(ref)
+  const f = await evalRaw(focusExpression(entry.selector, entry.tag))
+  if (!f?.found || f.tag) throw pageError(`ref ${ref} is stale (was "${entry.name}") — run snapshot again`)
+  if (f.focused === false) throw pageError(`ref ${ref} "${entry.name}" is not focusable — keys would go to another element`)
+  return { ref, name: entry.name, label: `${ref} "${entry.name}"` }
+}
+
+// ── 安全面 ──────────────────────────────────────────────────────────────────
+
+/** 域允许清单匹配（§3.2）：全等（大小写不敏感）∥ `*.` 前缀 = 子域通配。 */
+export function hostAllowed(host, list) {
+  const h = String(host).toLowerCase()
+  return list.some((entry) => {
+    const pattern = String(entry ?? "").trim().toLowerCase()
+    if (!pattern) return false
+    if (pattern.startsWith("*.")) return h.endsWith(`.${pattern.slice(2)}`)
+    return h === pattern
+  })
+}
+
+function allowDomainsOf(ctx) {
+  const list = ctx?.agent?.config?.browser?.allowDomains
+  return Array.isArray(list) ? list : []
+}
+
+/** 域强检（navigate 目标 ∥ click/evaluate/type 当前页——§3.2 两点）。 */
+function assertHostAllowed(url, ctx) {
+  const list = allowDomainsOf(ctx)
+  if (list.length === 0) return
+  let host = ""
+  try { host = new URL(url).hostname } catch { return }
+  if (!hostAllowed(host, list)) {
+    throw new Error(`blocked by browser.allowDomains — host "${host}" not allowed`)
+  }
+}
+
+/** 失败回执（§2.2）：`Error: <因由>` + 页摘 + 紧凑清单（≤30 行——页不可读时仅错误行）。 */
+async function failureReceipt(message) {
+  const parts = [`Error: ${message}`]
+  if (state.cdp) {
+    try { parts.push((await takeSnapshot({ max: COMPACT_ROWS })).text) } catch { /* 页不可读 ⇒ 仅错误行 */ }
+  }
+  return parts.join("\n")
+}
+
+function pageError(message) {
+  const err = new Error(message)
+  err.pageReceipt = true
+  return err
+}
+
+/** 真落盘（screenshot 缝的缺省实现）：`~/.thincoder/browser/shots/shot-<ISO>.png`。 */
+async function saveShotToDisk(buffer) {
+  const dir = browserPaths().shots
+  mkdirSync(dir, { recursive: true })
+  const path = join(dir, `shot-${new Date().toISOString().replace(/[:.]/g, "-")}-${process.pid}.png`)
+  writeFileSync(path, buffer)
+  return { path, bytes: buffer.length }
+}
+
+// ── 会话句柄（动作模块的能力面——§5：动作模块不 import 本档）──────────────────
+
+/** 等一条 CDP 事件（一次性；超时 / 中止 ⇒ 拒——html5 拖拽拦截链用）。 */
+function once(method, timeoutMs = 10_000) {
+  const ctl = currentController
+  ctl?.failIfAborted()
+  return new Promise((resolve, reject) => {
+    if (!state.cdp) { reject(new Error("no browser session")); return }
+    let timer = null
+    let off = null
+    let offAbort = null
+    let done = false
+    const finish = (fn, value) => {
+      if (done) return
+      done = true
+      if (timer) clearTimeout(timer)
+      off?.()
+      offAbort?.()
+      fn(value)
+    }
+    off = state.cdp.on(method, (params) => finish(resolve, params))
+    offAbort = ctl?.onAbort(() => finish(reject, ctl.error))
+    timer = setTimeout(() => finish(reject, new Error(`timed out waiting for ${method}`)), timeoutMs)
+    timer.unref?.()
+  })
+}
+
+const sessionHandle = {
+  ensureSession: (args) => ensureSession(headlessOf(args)),
+  closeSession,
+  connection: () => state.cdp,
+  call: (method, params) => cdpCall(method, params),
+  once: (method, timeoutMs) => runFrame(method, () => once(method, timeoutMs)),
+  evalRaw,
+  pageInfo,
+  waitForReady: (maxMs) => waitForReady(maxMs),
+  waitForUrlChange: (before, maxMs) => waitForUrlChange(before, maxMs),
+  takeSnapshot,
+  resolveRef,
+  focusRef,
+  assertHostAllowed,
+  failureReceipt,
+  pageError,
+  step: (name, fn) => runFrame(name, fn),
+  sleep,
+  saveShot: (buffer) => (_deps.saveShot ?? saveShotToDisk)(buffer),
+  networkState: () => state.net,
+}
+
+// ── 分发表 ∥ 入口 ────────────────────────────────────────────────────────────
+
+const ACTION_TABLE = { ...ACTIONS, ...INPUT_ACTIONS, ...CLIPBOARD_ACTIONS }
+
+async function dispatchAction(action, args, ctx) {
+  const handler = ACTION_TABLE[action]
+  if (typeof handler !== "function") throw new Error(`unknown browser action "${action}"`)
+  return handler(args, ctx, sessionHandle)
+}
+
+/** 自愈重开注记（§2.10）：重开后第一条回执尾行注记——置位一次，发出即清。 */
+function sealNote(receipt) {
+  if (!state.reopenNote || !state.cdp) return receipt
+  state.reopenNote = false
+  return `${receipt}\n${REOPEN_NOTE}`
+}
+
+async function runSerial(action, args, ctx, ctl) {
+  ctl.failIfAborted() // 排队期已到点 ⇒ 动作从未起执行（无展开）
+  try {
+    return sealNote(await dispatchAction(action, args, ctx))
+  } catch (e) {
+    if (e?.pageReceipt) return sealNote(await failureReceipt(e.message))
+    throw e
+  } finally {
+    if (state.cdp) armIdle() // 任何动作重置空闲计时（KD-8）
+  }
+}
+
+/** 动作入口：串行队列 + 单时钟动作预算（§2.9——deadline 自入队起算；批并行调用按调用序排队）。
+ *  `opts.signal`（批 browser-async-fix 最小增补——后台任务取消柄）：abort ⇒ 控制器 `cancel()`（queued 丢队 ∥ running 展开）；缺省 null 旧径零变。 */
+export function runAction(action, args, ctx, { signal = null } = {}) {
+  return queue.enqueue(action, args, (ctl) => {
+    currentController = ctl
+    return runSerial(action, args, ctx, ctl).finally(() => { currentController = null })
+  }, signal)
+}