dsh-moli 1.1.10 → 1.1.11

package/README.md

@@ -223,6 +223,52 @@ moli_fetch url=https://example.com dump=pdf        writeTo=/abs/path/a.pdf
 
 Screenshot and PDF dumps need `writeTo`; the bytes are written verbatim rather than printed.
 
+### `moli_session` — an interactive browser
+
+`moli_fetch` loads a page and prints it. That covers reading, and nothing else: it cannot dismiss a
+consent wall, fill a search box, scroll a lazy list, or wait for a client-side route to change.
+`moli_session` drives a persistent browser instead, over the Chrome DevTools Protocol endpoint that
+`moli serve` publishes. State — cookies, navigation, typed input — survives between calls until you
+stop it.
+
+```
+moli_session action=open  url=https://example.com        # start the browser and navigate
+moli_session action=snapshot                             # the rendered page as text
+moli_session action=click selector="#accept-cookies"
+moli_session action=type  selector="#q" text="moli" submit=true
+moli_session action=scroll dy=1200
+moli_session action=waitFor selector=".results"
+moli_session action=eval  expression="document.title"
+moli_session action=screenshot writeTo=/abs/path/a.png
+moli_session action=status                               # is it running, and on what page
+moli_session action=close                                # stop it and free the port
+```
+
+Elements are addressed by **CSS selector**, never by pixel coordinates: the tool measures the element
+and dispatches real mouse and key events, so page handlers run exactly as they do for a person.
+
+**One thing to know before relying on `click`.** This engine's element geometry is document-absolute
+and does not follow scrolling, and its hit test is bounded by the viewport height. Measured on Moli
+1.1.16: an element at document `y=1008` reports the same `y` at `scrollY` 0, 400 and 800, while
+`elementFromPoint` stops answering past `y=1080`. The consequence is that synthetic input cannot reach
+an element below the first viewport, on any page long enough to scroll. `click` says so, naming the
+element, and points at the route that does work:
+
+```
+moli_session action=eval expression="document.querySelector('#far-down').click()"
+```
+
+`eval` runs a click inside the page and bypasses the input layer, so it reaches elements the input API
+cannot. Note that it also skips hover and focus behaviour, which is the difference between clicking a
+control and calling its handler.
+
+The session needs **Node 21 or newer** for the built-in `WebSocket`; on Node 20 the tool answers with
+that reason instead of failing obscurely. `moli_fetch` and `moli_probe` still work on 20.12.
+
+`moli_session` also takes `port` (default 9222). If that port is already served by a `moli serve` you
+started yourself, the tool connects to it rather than failing to bind — and `close` then leaves it
+alone, because it is not ours to stop.
+
 ## Relationship to Moli's own agent skills
 
 Moli ships official agent skills in its repository — [`moli-webfetch`](https://github.com/lexmount/moli/tree/main/skills/moli-webfetch),
@@ -310,12 +356,24 @@ Override any field under the plugin's `config` entry in the profile patch layer.
         maxChars: 200000                                         # inline text truncation
         proxy: 'http://127.0.0.1:7890'                           # forward proxy for moli, downloads, and the installer's engine download
         insecureTls: true                                        # see the TLS notes below
+        sessionPort: 9222                                        # CDP port for moli_session
+        blockPrivateNetworks: false                              # refuse private addresses (see the note below)
+        blockCidrs: []                                           # extra CIDRs to refuse
 ```
 
 The plugin-level `proxy` above is the default; `moli_fetch` also takes a `proxy` argument, so a single
 call can route through a different proxy without changing the profile. A loopback URL always bypasses
 whichever proxy is in effect.
 
+`blockPrivateNetworks` is **off by default, matching the engine**: `moli fetch http://10.0.0.1/` reaches
+a private address, so the plugin does not silently narrow what the moli you installed already does.
+Turn it on, or list `blockCidrs`, when the agent is following links on pages you do not control and
+you want the engine to refuse private destinations. Two caveats worth knowing before you rely on it:
+moli documents the policy as applying to **directly connected** targets, so a configured `proxy`
+routes around it, and only `blockCidrs` (which the proxy must enforce) covers that path. The sharpest
+target this protects is the cloud metadata address `169.254.169.254`, which hands out instance
+credentials on a VM.
+
 Without `exePath`, the plugin probes `exePath` → `MOLI_BIN` → `%LOCALAPPDATA%\Moli\bin\moli.exe` →
 `%USERPROFILE%\.local\bin\moli.exe`, then scans inside `%LOCALAPPDATA%\Moli` for a `moli.exe`, so an
 installation under a versioned subdirectory is still found.
@@ -378,6 +436,12 @@ Four suites live in [`verify/`](verify/), and all are runnable against a working
   `dump` discards its value, an expression that throws is classified as such instead of being blamed
   on the installation, truncation keeps the tail as well as the head, `proxy` is a per-call parameter,
   and `moli_probe` states which process its `httpsOk` describes.
+- `session-verify.mjs` drives `moli_session` end to end against a `data:` URL fixture, so it needs no
+  network and no site stays still underneath it: lifecycle and port release, snapshot, click, type
+  with and without clearing, press, scroll, `waitFor` in both directions, eval including a throwing
+  expression, screenshot byte signature, navigation by clicking a link, restart after close, and the
+  viewport limit described above — which is asserted as a limit, with the `eval` route that works
+  around it asserted next to it.
 
 `.github/workflows/verify.yml` runs the first two on Linux, Windows and macOS (they need no engine and
 no network) and attempts the engine-dependent suites on Linux and Windows, reporting a missing engine

package/README.zh.md

@@ -209,6 +209,46 @@ moli_fetch url=https://example.com dump=pdf        writeTo=/绝对路径/a.pdf
 
 截图与 PDF 必须给 `writeTo`；字节是原样落盘的，不会打印到输出里。
 
+### `moli_session` —— 可交互的浏览器
+
+`moli_fetch` 是"加载一页、打印出来"，只能读。它点不掉同意墙、填不了搜索框、滚不动懒加载列表，也等不到
+客户端路由切换。`moli_session` 驱动的是一个**常驻浏览器**，走 `moli serve` 暴露的 Chrome DevTools
+Protocol。状态（cookie、导航位置、已输入的内容）在多次调用之间保持，直到你显式停止。
+
+```
+moli_session action=open  url=https://example.com        # 启动浏览器并导航
+moli_session action=snapshot                             # 渲染后的页面文本
+moli_session action=click selector="#accept-cookies"
+moli_session action=type  selector="#q" text="moli" submit=true
+moli_session action=scroll dy=1200
+moli_session action=waitFor selector=".results"
+moli_session action=eval  expression="document.title"
+moli_session action=screenshot writeTo=/绝对路径/a.png
+moli_session action=status                               # 是否在运行、当前在哪一页
+moli_session action=close                                # 停止并释放端口
+```
+
+元素一律用 **CSS 选择器**定位，不接受像素坐标：工具自己测量元素并派发真实的鼠标与键盘事件，所以页面的
+处理器会像人操作时一样执行。
+
+**依赖 `click` 之前需要知道一件事。** 这个引擎的元素几何是**文档绝对坐标且不随滚动更新**，而它的命中测试
+**受视口高度限制**。在 Moli 1.1.16 上实测：文档 `y=1008` 的元素在 `scrollY` 为 0、400、800 时报告的 `y`
+完全相同，而 `elementFromPoint` 在 `y=1080` 之后一律返回 null。后果是：**在长到需要滚动的页面上，合成输入
+无法触达首个视口以下的元素。** `click` 会如实报出这一点并点名元素，同时给出真正可行的路径：
+
+```
+moli_session action=eval expression="document.querySelector('#far-down').click()"
+```
+
+`eval` 在页面内部执行点击，绕开输入层，因此能触达输入 API 达不到的元素。注意它同时跳过了 hover 与 focus
+行为——这正是"点击一个控件"与"调用它的处理器"的区别。
+
+本工具需要 **Node 21 或更新版本**（内置 `WebSocket`）；在 Node 20 上会直接说明原因，而不是给出费解的失败。
+`moli_fetch` 与 `moli_probe` 仍支持 20.12。
+
+`moli_session` 也接受 `port`（默认 9222）。如果该端口已经由你自己启动的 `moli serve` 占用，工具会连接它
+而不是绑定失败——此时 `close` **不会**停掉它，因为那不是我们的进程。
+
 ## 与 Moli 官方 agent skill 的关系
 
 Moli 仓库自带官方 agent skill：[`moli-webfetch`](https://github.com/lexmount/moli/tree/main/skills/moli-webfetch)、
@@ -284,11 +324,20 @@ cookie 驱动的查询参数。那次实测同时覆盖了代理下载路由与
         maxChars: 200000                                         # 内联文本截断阈值
         proxy: 'http://127.0.0.1:7890'                           # 转给本地正向代理（moli、下载、安装器内部引擎下载都走它）
         insecureTls: true                                        # 见下方 TLS 说明
+        sessionPort: 9222                                        # moli_session 的 CDP 端口
+        blockPrivateNetworks: false                              # 拒绝私网地址（见下方说明）
+        blockCidrs: []                                           # 额外拒绝的 CIDR
 ```
 
 上面配置里的 `proxy` 是默认值；`moli_fetch` 也能接收 `proxy` 参数，因此单次调用可以走另一个代理而不必改
 profile。无论生效的是哪个代理，loopback 地址一律绕过它。
 
+`blockPrivateNetworks` **默认关闭，与引擎一致**：`moli fetch http://10.0.0.1/` 本来就能访问私网地址，插件
+不会悄悄收窄你已安装的 moli 的能力。当 agent 会在你无法控制的页面上跟着链接走、而你希望引擎拒绝私网目标时，
+再打开它或配置 `blockCidrs`。依赖它之前有两点需要知道：moli 文档写明该策略只作用于**直连**目标，因此配置了
+`proxy` 就会绕过它，只有 `blockCidrs`（由代理执行）能覆盖那条路径。这个开关保护的最锐利目标是云元数据地址
+`169.254.169.254`——在虚拟机上它会交出实例凭据。
+
 未设置 `exePath` 时探测顺序：`exePath` → 环境变量 `MOLI_BIN` → `%LOCALAPPDATA%\Moli\bin\moli.exe`
 → `%USERPROFILE%\.local\bin\moli.exe`，随后还会在 `%LOCALAPPDATA%\Moli` 内递归查找 `moli.exe`，
 所以装在带版本号的子目录里也能找到。
@@ -335,6 +384,10 @@ profile。无论生效的是哪个代理，loopback 地址一律绕过它。
 - `report-verify.mjs` 守住一份使用体验报告里的发现：`eval` 与 `dump` 同用会丢弃表达式值（已在参数描述里
   写明）、表达式抛异常时被正确归类而不是甩锅给"安装有问题"、截断同时保留头尾、`proxy` 是可按调用传入的参数、
   以及 `moli_probe` 会说明它的 `httpsOk` 描述的是哪个进程。
+- `session-verify.mjs` 用 `data:` URL 夹具端到端驱动 `moli_session`，因此不依赖网络、也不会因为站点变化而
+  失效：生命周期与端口释放、snapshot、click、带与不带清空的 type、press、scroll、两个方向的 `waitFor`、
+  含抛异常的 eval、截图字节签名、点击链接导航、关闭后重启，以及上面那条视口限制——限制被当作**限制**断言，
+  紧随其后断言真正能绕过它的 `eval` 路径。
 
 `.github/workflows/verify.yml` 在 Linux、Windows、macOS 上跑前两个（无需引擎、无需网络），在 Linux 与 Windows
 上尝试依赖引擎的几套；若 runner 上没有引擎，则报告为跳过而不是失败。

package/index.js

@@ -1,6 +1,8 @@
 /** Host half of dsh-moli: expose the local `moli` headless browser as callable tools. */
+import { performAction } from './lib/actions.js';
 import { MANUAL_INSTALL, installMoli } from './lib/install.js';
 import { findMoli, moliCandidates, probe, runFetch } from './lib/moli.js';
+import { SessionManager, sessionSupported, sessionUnsupportedReason } from './lib/session.js';
 
 export const name = 'dsh-moli';
 export const inject = ['tools'];
@@ -226,6 +228,151 @@ function renderProbe(_args, value) {
   return [{ type: 'text', text: lines.join('\n') }];
 }
 
+/** Actions `moli_session` accepts. */
+const SESSION_ACTIONS = ['start', 'open', 'snapshot', 'click', 'type', 'press', 'scroll', 'waitFor', 'eval', 'screenshot', 'status', 'close'];
+
+/**
+ * Parameters of `moli_session`.
+ *
+ * Raw JSON Schema with a root `type: "object"`, like the other tools: `schemaOf`
+ * projects this straight to the provider, so the author DSL would arrive as
+ * `type: null` and be rejected.
+ */
+const SESSION_PARAMETERS = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['action'],
+  properties: {
+    action: {
+      type: 'string',
+      enum: SESSION_ACTIONS,
+      description: 'start: ensure the browser is running. open: navigate. snapshot: read the rendered page. '
+        + 'click/type/press/scroll: interact. waitFor: wait for a selector to appear or disappear. '
+        + 'eval: run JavaScript in the page. screenshot: write a PNG. status: report the session. close: stop the browser.',
+    },
+    url: { type: 'string', description: 'open: absolute http:// or https:// URL to navigate to.' },
+    selector: { type: 'string', description: 'CSS selector for click, type, scroll and waitFor.' },
+    text: { type: 'string', description: 'type: the text to enter.' },
+    submit: { type: 'boolean', description: 'type: press Enter after entering the text.' },
+    clear: { type: 'boolean', description: 'type: empty the field before entering text.' },
+    key: { type: 'string', description: 'press: key name, e.g. Enter, Tab, Escape, ArrowDown.' },
+    dy: { type: 'number', description: 'scroll: pixels to move down (negative moves up). Defaults to 800.' },
+    block: { type: 'string', enum: ['start', 'center', 'end', 'nearest'], description: 'scroll: where to align the element. Defaults to center.' },
+    state: { type: 'string', enum: ['attached', 'detached'], description: 'waitFor: wait for the selector to appear (attached) or vanish (detached).' },
+    expression: { type: 'string', description: 'eval: a JavaScript expression; promises are awaited and the value is returned.' },
+    writeTo: { type: 'string', description: 'screenshot: absolute path for the PNG. Required, since images are not returned inline.' },
+    format: { type: 'string', enum: ['png', 'jpeg'], description: 'screenshot: image format. Defaults to png.' },
+    includeHtml: { type: 'boolean', description: 'snapshot: also return the rendered HTML.' },
+    maxChars: { type: 'integer', description: 'snapshot: truncate the text to this many characters.' },
+    timeoutMs: { type: 'integer', description: 'Deadline for this action. Defaults to the plugin configuration.' },
+    port: { type: 'integer', description: 'start: CDP port. Defaults to the plugin configuration (9222).' },
+  },
+};
+
+const SESSION_OUTPUT_SCHEMA = {
+  type: 'object',
+  additionalProperties: true,
+  required: ['ok'],
+  properties: {
+    ok: { type: 'boolean' },
+    action: { type: 'string' },
+    error: { type: 'string' },
+    hint: { type: 'string' },
+    url: { type: 'string' },
+    title: { type: 'string' },
+    text: { type: 'string' },
+    chars: { type: 'integer' },
+    truncated: { type: 'boolean' },
+    links: { type: 'array', items: { type: 'object', additionalProperties: true } },
+    fields: { type: 'array', items: { type: 'object', additionalProperties: true } },
+    html: { type: 'string' },
+    selector: { type: 'string' },
+    clicked: { type: 'object', additionalProperties: true },
+    navigated: { type: 'boolean' },
+    submitted: { type: 'boolean' },
+    value: {},
+    serialized: { type: 'string' },
+    key: { type: 'string' },
+    y: { type: 'number' },
+    height: { type: 'number' },
+    viewport: { type: 'number' },
+    state: { type: 'string' },
+    waitedMs: { type: 'integer' },
+    path: { type: 'string' },
+    bytes: { type: 'integer' },
+    format: { type: 'string' },
+    running: { type: 'boolean' },
+    ownedByThisPlugin: { type: 'boolean' },
+    external: { type: 'boolean' },
+    pid: { type: 'integer' },
+    endpoint: { type: 'string' },
+    logPath: { type: 'string' },
+    settled: { type: 'boolean' },
+    settledMs: { type: 'integer' },
+    stopped: { type: 'boolean' },
+  },
+};
+
+/**
+ * Render a `moli_session` value for the model.
+ *
+ * A snapshot is the one result worth formatting rather than dumping as JSON: the
+ * link and field tables are what the next action usually depends on.
+ *
+ * @param _args - the call arguments, unused.
+ * @param value - the canonical result value.
+ * @returns result content blocks.
+ */
+function renderSession(_args, value) {
+  if (value.ok !== true) {
+    const lines = [`moli_session failed${typeof value.action === 'string' ? ` (${value.action})` : ''}: ${value.error ?? 'unknown error'}`];
+    if (typeof value.hint === 'string' && value.hint !== '') lines.push(value.hint);
+    if (typeof value.bytes === 'number') lines.push(`(the image was ${String(value.bytes)} bytes but could not be written)`);
+    return [{ type: 'text', text: lines.join('\n') }];
+  }
+  if (value.action === 'snapshot') {
+    const lines = [`${String(value.title)} — ${String(value.url)}`, ''];
+    lines.push(String(value.text ?? ''));
+    if (Array.isArray(value.links) && value.links.length > 0) {
+      lines.push('', `Links (${String(value.links.length)}):`);
+      for (const link of value.links.slice(0, 25)) lines.push(`  ${String(link.text)} -> ${String(link.href)}`);
+    }
+    if (Array.isArray(value.fields) && value.fields.length > 0) {
+      lines.push('', `Fields (${String(value.fields.length)}):`);
+      for (const field of value.fields.slice(0, 25)) lines.push(`  <${String(field.tag)}${field.type === '' ? '' : ` type=${String(field.type)}`}${field.name === '' ? '' : ` name=${String(field.name)}`}${field.id === '' ? '' : ` id=${String(field.id)}`}>`);
+    }
+    return [{ type: 'text', text: lines.join('\n') }];
+  }
+  if (value.action === 'status') {
+    return [{
+      type: 'text',
+      text: value.running === true
+        ? `Session running at ${String(value.endpoint)}${value.external === true ? ' (started outside this plugin, so close will not stop it)' : ''}${value.url === undefined ? '' : `\nCurrent page: ${String(value.title)} — ${String(value.url)}`}`
+        : 'No session is running. Call moli_session with action "start" or "open" to launch one.',
+    }];
+  }
+  if (value.action === 'click') {
+    return [{
+      type: 'text',
+      text: `Clicked ${String(value.clicked?.tag ?? 'element')}${value.clicked?.text === undefined || value.clicked.text === '' ? '' : ` (“${String(value.clicked.text)}”)`}`
+        + `${value.navigated === true ? `, which navigated to ${String(value.url)}` : '; the page did not navigate'}`,
+    }];
+  }
+  if (value.action === 'type') {
+    return [{ type: 'text', text: `Entered text${value.submitted === true ? ' and pressed Enter' : ''}; the field now reads ${JSON.stringify(String(value.value ?? ''))}` }];
+  }
+  if (value.action === 'screenshot') {
+    return [{ type: 'text', text: `Screenshot written to ${String(value.path)} (${String(value.bytes)} bytes). Read that file to see it.` }];
+  }
+  if (value.action === 'eval') {
+    return [{ type: 'text', text: String(value.serialized ?? '') }];
+  }
+  if (value.action === 'close') {
+    return [{ type: 'text', text: value.stopped === true ? 'Session stopped.' : 'Nothing to stop: no session was running that this plugin started.' }];
+  }
+  return [{ type: 'text', text: JSON.stringify(value) }];
+}
+
 /**
  * Register the Moli tools.
  *
@@ -355,5 +502,95 @@ export function apply(ctx, config) {
     },
   });
 
-  ctx.logger?.info?.(`dsh-moli: registered moli_fetch and moli_probe (${cachedExe ?? 'moli missing'})`);
+  // ---------------------------------------------------------------------------
+  // moli_session: an interactive browser, for the work a one-shot fetch cannot do
+  // ---------------------------------------------------------------------------
+  //
+  // This is the plugin's only stateful tool. `moli serve` is a long-lived child
+  // that has to outlive a single call, so one manager is created per plugin
+  // instance and its lifecycle is explicit (`start` implicitly, `close` by hand).
+  // Registration stays synchronous: the server is spawned on first use, never at
+  // load time, so a plugin load cannot delay Host startup or open a port.
+  const session = new SessionManager({
+    get exe() { return cachedExe; },
+    port: options.sessionPort ?? 9222,
+    host: '127.0.0.1',
+    insecureTls,
+    proxy: options.proxy,
+    userAgent: options.sessionUserAgent,
+    profileDir: options.profileDir,
+    resources: options.sessionResources === true,
+    // Off, matching the engine's own default: `moli fetch <private-ip>` can reach
+    // a private address, so the plugin does not silently narrow what a user's
+    // installed engine already does. Set it to true, or pass blockCidrs, to have
+    // the engine refuse private addresses for directly connected targets.
+    blockPrivateNetworks: options.blockPrivateNetworks === true,
+    blockCidrs: Array.isArray(options.blockCidrs) ? options.blockCidrs : [],
+    startTimeoutMs: options.sessionStartTimeoutMs ?? 20000,
+  });
+
+  ctx.tools.register({
+    name: 'moli_session',
+    description: 'Drive an interactive browser through a persistent session, for what a one-shot fetch cannot'
+      + ' do: click through consent walls, fill and submit a search box, scroll a lazy list, wait for a'
+      + ' client-side route change, or run a script in the page. Keeps one browser alive across calls, so'
+      + ' state (cookies, navigation, form input) persists until you stop it with action "close".'
+      + ' Start with "open"; read the page with "snapshot"; interact with "click", "type", "press" and'
+      + ' "scroll"; use "eval" as the escape hatch. Elements are addressed by CSS selector, never by pixel'
+      + ' coordinates.',
+    parameters: SESSION_PARAMETERS,
+    output: { schema: SESSION_OUTPUT_SCHEMA, render: renderSession },
+    // One browser, one page: overlapping actions would interleave input events and
+    // navigate the page out from under each other.
+    isConcurrencySafe: () => false,
+    async execute(args, exec) {
+      // `status` and `close` are meaningful with nothing running, so they are
+      // answered before the engine is required.
+      if (args.action === 'close') {
+        const outcome = await session.close();
+        return { ok: true, action: 'close', ...outcome };
+      }
+      if (args.action === 'status') {
+        const state = await session.status();
+        return { ok: true, action: 'status', ...state };
+      }
+      if (args.action === 'start') {
+        if (!sessionSupported()) return { ok: false, action: 'start', error: sessionUnsupportedReason() };
+        const { external } = await session.ensure();
+        const state = await session.status();
+        return { ok: true, action: 'start', started: true, external, ...state };
+      }
+
+      if (engine() === undefined) {
+        return {
+          ok: false,
+          action: String(args.action),
+          error: 'moli was not found, so a session cannot be started',
+          hint: 'Call moli_probe with action "install", or set the plugin config field `exePath`.',
+        };
+      }
+      if (!sessionSupported()) return { ok: false, action: String(args.action), error: sessionUnsupportedReason() };
+
+      if (exec?.signal?.aborted === true) return { ok: false, action: String(args.action), error: 'the call was aborted before it started' };
+
+      try {
+        const { connection } = await session.ensure();
+        const result = await performAction(connection, args, { maxChars });
+        // A closed socket means the browser went away under us; drop it so the
+        // next call starts a fresh one instead of failing forever.
+        if (connection.closed === true) void session.close();
+        return result;
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const hint = /timed out/u.test(message)
+          ? 'The action exceeded its deadline. Raise timeoutMs, or check `waitFor` for a selector that never appears.'
+          : /ECONNREFUSED|closed|WebSocket/u.test(message)
+            ? 'The browser connection was lost. Call moli_session with action "status", then "start" to relaunch it.'
+            : undefined;
+        return { ok: false, action: String(args.action), error: message, ...(hint === undefined ? {} : { hint }) };
+      }
+    },
+  });
+
+  ctx.logger?.info?.(`dsh-moli: registered moli_fetch, moli_probe and moli_session (${cachedExe ?? 'moli missing'})`);
 }

package/lib/actions.js

@@ -0,0 +1,380 @@
+/**
+ * The actions a session can perform.
+ *
+ * Kept apart from {@link ./session.js} so the transport (server lifecycle, CDP
+ * plumbing) and the behaviour (what `click` means) can be read and tested
+ * separately. Every action takes the CDP connection and returns a plain value;
+ * none of them throws for a page-level problem, because "that selector matched
+ * nothing" is a result the caller has to see, not a transport failure.
+ *
+ * Selector handling is deliberately uniform: an element is located by CSS
+ * selector in the page, measured, and then driven through real input events. The
+ * alternative -- taking viewport coordinates from the caller -- makes the model
+ * guess pixels, and the coordinates go stale the moment the page reflows.
+ *
+ * @module dsh-moli/lib/actions
+ */
+import { existsSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
+
+/** CSS-selector quoting, so a selector can be embedded in an expression safely. */
+const quote = value => JSON.stringify(String(value));
+
+/**
+ * Resolve a selector to a click point, or explain why there is not one.
+ *
+ * **This engine's geometry is document-absolute and ignores scrolling.**
+ * `getBoundingClientRect()` returns the same `y` at `scrollY` 0, 400 and 800, and
+ * `elementFromPoint()` agrees with it -- scanning the hit test at
+ * `rect.y + scrollY` returns null while `rect.y` hits the element. The mouse
+ * input APIs share that frame, so a click dispatched at `rect.y` lands even when
+ * the page is scrolled.
+ *
+ * Measured against moli 1.1.16. This is not the web platform's behaviour, and it
+ * matters: the textbook recipe of "scroll the element into view, then read the
+ * viewport rectangle" produces coordinates that are wrong by the scroll offset,
+ * and the failure is silent on a short page and total on a long one. Nothing here
+ * may depend on the scroll position.
+ *
+ * @returns `{ box, point, tag, text, covered }` on success, `{ error }` otherwise.
+ */
+async function boxOf(connection, selector) {
+  const expression = `(() => {
+    const el = document.querySelector(${quote(selector)});
+    if (el === null) return { missing: true };
+    const rect = el.getBoundingClientRect();
+    const style = getComputedStyle(el);
+    const cx = rect.x + rect.width / 2;
+    const cy = rect.y + rect.height / 2;
+    // The hit test is the authority on whether a click can land, and it uses the
+    // same frame as the rectangle. An element that is scrolled out of view still
+    // passes, because in this engine the input is not clipped to the viewport.
+    const found = document.elementFromPoint(cx, cy);
+    const hitSelf = found !== null && (found === el || el.contains(found) || found.contains(el));
+    return {
+      box: { x: rect.x, y: rect.y, width: rect.width, height: rect.height },
+      point: hitSelf ? { x: cx, y: cy } : null,
+      covered: hitSelf || found === null ? null : found.tagName.toLowerCase() + (found.id ? '#' + found.id : ''),
+      tag: el.tagName.toLowerCase(),
+      text: (el.innerText || el.value || el.getAttribute('aria-label') || '').trim().slice(0, 80),
+      visible: style.visibility !== 'hidden' && style.display !== 'none' && rect.width > 0 && rect.height > 0,
+      scrollY: window.scrollY,
+      viewportHeight: innerHeight,
+    };
+  })()`;
+  const result = await connection.evaluate(expression);
+  if (result.throws !== undefined) return { error: result.throws };
+  const value = result.value;
+  if (value === undefined) return { error: 'the page returned nothing for that selector' };
+  if (value.missing === true) return { error: `no element matches ${JSON.stringify(selector)}` };
+  return value;
+}
+
+/**
+ * Measure a selector.
+ *
+ * `scrollIntoView` is attempted because it is harmless and does move the page for
+ * a human reading it, but nothing here depends on it: the geometry does not
+ * follow the scroll, so the measurement is identical either way. See {@link boxOf}
+ * for the engine detail and its consequence.
+ */
+async function ensureVisible(connection, selector) {
+  await connection.evaluate(`(() => {
+    const el = document.querySelector(${quote(selector)});
+    if (el !== null) el.scrollIntoView({ block: 'center', inline: 'center' });
+  })()`);
+  await sleep(50);
+  return boxOf(connection, selector);
+}
+
+/**
+ * Turn a measurement into a click that is known to land on the element.
+ *
+ * A click outside the viewport, or one whose point is covered by another element,
+ * is reported rather than dispatched: dispatching anyway produces a silent no-op
+ * that looks like success to the caller.
+ */
+async function clickSelector(connection, selector) {
+  const found = await ensureVisible(connection, selector);
+  if (found.error !== undefined) return { ok: false, error: found.error };
+  if (found.visible !== true) return { ok: false, error: `${JSON.stringify(selector)} is not visible (display:none or visibility:hidden)` };
+  if (found.point === null) {
+    // The engine's hit test is clipped to the viewport height while its geometry
+    // ignores scrolling, so an element whose absolute y is past the viewport
+    // cannot be reached by synthetic input at all -- scrolling does not change
+    // either number. Report that plainly and point at the route that does work.
+    const beyondViewport = found.box.y + found.box.height / 2 > (found.viewportHeight ?? 0);
+    return {
+      ok: false,
+      selector,
+      error: found.covered === null
+        ? (beyondViewport
+          ? `${JSON.stringify(selector)} is below the viewport (y=${String(Math.round(found.box.y))}) and this engine cannot send input there`
+          : `${JSON.stringify(selector)} has no box to click`)
+        : `${JSON.stringify(selector)} is covered by another element (${found.covered})`,
+      hint: beyondViewport
+        ? 'Moli\'s hit test is bounded by the viewport height and its element geometry does not follow scrolling, so synthetic clicks cannot reach elements further down the document. Use eval to click it in the page instead -- for example `document.querySelector("SEL").click()` -- which bypasses the input layer entirely.'
+        : found.covered === null
+          ? 'The element may be display:none, zero-sized, or only a wrapper.'
+          : 'Something is on top of it -- commonly a consent banner or a modal. Dismiss that first, or press Escape.',
+    };
+  }
+  await clickAt(connection, found.point.x, found.point.y);
+  return { ok: true, found, x: found.point.x, y: found.point.y };
+}
+
+/** Dispatch a full click: move, press, release. Real events, so page handlers run. */
+async function clickAt(connection, x, y, { clickCount = 1 } = {}) {
+  await connection.send('Input.dispatchMouseEvent', { type: 'mouseMoved', x, y });
+  await connection.send('Input.dispatchMouseEvent', { type: 'mousePressed', x, y, button: 'left', clickCount });
+  await connection.send('Input.dispatchMouseEvent', { type: 'mouseReleased', x, y, button: 'left', clickCount });
+}
+
+/**
+ * Wait until the page has no pending load and the document is unchanged for a
+ * short settle window. Used after navigation and after clicks that may navigate.
+ */
+async function settle(connection, { quietMs = 250, timeoutMs = 20000 } = {}) {
+  const started = Date.now();
+  let lastSignature;
+  let stableSince = Date.now();
+  while (Date.now() - started < timeoutMs) {
+    const result = await connection.evaluate('document.readyState + "|" + document.title + "|" + location.href');
+    const signature = String(result.value);
+    if (signature !== lastSignature) {
+      lastSignature = signature;
+      stableSince = Date.now();
+    } else if (Date.now() - stableSince >= quietMs) {
+      return { settled: true, ms: Date.now() - started };
+    }
+    await sleep(100);
+  }
+  return { settled: false, ms: Date.now() - started };
+}
+
+/** A readable, size-bounded view of the rendered page. */
+async function snapshot(connection, { maxChars, includeHtml }) {
+  const expression = `(() => {
+    const text = document.body === null ? '' : document.body.innerText.trim();
+    const links = [...document.querySelectorAll('a[href]')].slice(0, 200).map(a => ({ text: (a.innerText || '').trim().slice(0, 80), href: a.href }));
+    return JSON.stringify({
+      url: location.href,
+      title: document.title,
+      text,
+      links,
+      forms: [...document.querySelectorAll('input,textarea,select')].slice(0, 50).map(el => ({
+        tag: el.tagName.toLowerCase(), type: el.type || '', name: el.name || '', id: el.id || '', placeholder: el.placeholder || '',
+      })),
+      html: ${includeHtml === true ? 'document.documentElement.outerHTML' : "''"},
+    });
+  })()`;
+  const result = await connection.evaluate(expression);
+  if (result.throws !== undefined) return { ok: false, error: result.throws };
+  const data = JSON.parse(String(result.value));
+  const limit = typeof maxChars === 'number' && maxChars > 0 ? maxChars : 200000;
+  const truncated = data.text.length > limit;
+  return {
+    ok: true,
+    url: data.url,
+    title: data.title,
+    text: truncated ? `${data.text.slice(0, limit)}\n\n… [dsh-moli] ${String(data.text.length - limit)} characters omitted; pass a larger maxChars to keep them.` : data.text,
+    chars: data.text.length,
+    truncated,
+    links: data.links,
+    fields: data.forms,
+    ...(includeHtml === true ? { html: data.html.slice(0, limit) } : {}),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// the action table
+// ---------------------------------------------------------------------------
+
+/**
+ * Run one action against a live connection.
+ *
+ * @param connection - the CDP connection from {@link SessionManager#ensure}.
+ * @param args - the tool arguments.
+ * @param options - output limits and the resolved session manager.
+ * @returns the action's value.
+ */
+export async function performAction(connection, args, options) {
+  const action = args.action;
+  const timeoutMs = args.timeoutMs ?? 30000;
+
+  switch (action) {
+    case 'open': {
+      if (typeof args.url !== 'string' || args.url === '') return { ok: false, error: 'open needs a url' };
+      await connection.send('Page.navigate', { url: args.url }, timeoutMs);
+      const result = await settle(connection, { timeoutMs });
+      const url = await connection.evaluate('location.href');
+      const title = await connection.evaluate('document.title');
+      return { ok: true, action, url: url.value, title: title.value, settled: result.settled, settledMs: result.ms };
+    }
+
+    case 'snapshot':
+      return snapshot(connection, { maxChars: args.maxChars ?? options.maxChars, includeHtml: args.includeHtml === true });
+
+    case 'click': {
+      if (typeof args.selector !== 'string' || args.selector === '') return { ok: false, error: 'click needs a selector' };
+      const before = await connection.evaluate('location.href');
+      const outcome = await clickSelector(connection, args.selector);
+      if (outcome.ok !== true) return { ok: false, action, selector: args.selector, ...outcome };
+      // A click may navigate, open a dialog, or only run a handler; settling
+      // covers the first, and reporting the URL change covers all three.
+      const settled = await settle(connection, { timeoutMs: Math.min(timeoutMs, 10000) });
+      const after = await connection.evaluate('location.href');
+      return {
+        ok: true,
+        action,
+        selector: args.selector,
+        clicked: { tag: outcome.found.tag, text: outcome.found.text, x: Math.round(outcome.x), y: Math.round(outcome.y) },
+        navigated: before.value !== after.value,
+        url: after.value,
+        settled: settled.settled,
+      };
+    }
+
+    case 'type': {
+      if (typeof args.selector !== 'string' || args.selector === '') return { ok: false, error: 'type needs a selector' };
+      if (typeof args.text !== 'string') return { ok: false, error: 'type needs text' };
+      // Same measurement discipline as click: a field far down the page has to be
+      // scrolled into view before it can be focused and typed into reliably.
+      const found = await ensureVisible(connection, args.selector);
+      if (found.error !== undefined) return { ok: false, error: found.error, selector: args.selector };
+      // Focus through the page so the element is the real editing target, then
+      // clear it when asked: typing into a pre-filled field would append.
+      const focused = await connection.evaluate(
+        `(() => { const el = document.querySelector(${quote(args.selector)}); if (el === null) return 'missing'; el.focus(); ${args.clear === true ? 'if ("value" in el) { el.value = ""; }' : ''} return document.activeElement === el ? 'focused' : 'not-focused'; })()`);
+      if (focused.value !== 'focused') return { ok: false, error: `could not focus ${JSON.stringify(args.selector)} (${String(focused.value ?? focused.throws)})` };
+      await connection.send('Input.insertText', { text: args.text });
+      let submitted = false;
+      if (args.submit === true) {
+        await keyPress(connection, 'Enter');
+        submitted = true;
+        await settle(connection, { timeoutMs: Math.min(timeoutMs, 10000) });
+      }
+      const value = await connection.evaluate(`(() => { const el = document.querySelector(${quote(args.selector)}); return el === null ? null : (el.value ?? el.innerText ?? null); })()`);
+      return { ok: true, action, selector: args.selector, submitted, value: value.value };
+    }
+
+    case 'press':
+      if (typeof args.key !== 'string' || args.key === '') return { ok: false, error: 'press needs key' };
+      await keyPress(connection, args.key);
+      return { ok: true, action, key: args.key };
+
+    case 'scroll': {
+      let expression;
+      if (typeof args.selector === 'string' && args.selector !== '') {
+        expression = `(() => { const el = document.querySelector(${quote(args.selector)}); if (el === null) return null; el.scrollIntoView({ block: '${String(args.block ?? 'center')}' }); return window.scrollY; })()`;
+      } else {
+        const dy = typeof args.dy === 'number' ? args.dy : 800;
+        expression = `(() => { window.scrollBy(0, ${String(dy)}); return window.scrollY; })()`;
+      }
+      const result = await connection.evaluate(expression);
+      if (result.value === null) return { ok: false, error: `no element matches ${JSON.stringify(String(args.selector))}` };
+      const metrics = await connection.evaluate('JSON.stringify({ y: window.scrollY, height: document.body === null ? 0 : document.body.scrollHeight, viewport: innerHeight })');
+      return { ok: true, action, ...JSON.parse(String(metrics.value)) };
+    }
+
+    case 'waitFor': {
+      if (typeof args.selector !== 'string' || args.selector === '') return { ok: false, error: 'waitFor needs a selector' };
+      const deadline = Date.now() + timeoutMs;
+      const start = Date.now();
+      // `detached` means the selector matches nothing. It is deliberately not
+      // "hidden": a `display:none` element still matches, and conflating the two
+      // would make this wait forever on something the caller can already see is
+      // absent from the DOM.
+      const wantPresent = args.state !== 'detached';
+      for (;;) {
+        const present = (await connection.evaluate(`document.querySelector(${quote(args.selector)}) !== null`)).value === true;
+        if (present === wantPresent) {
+          return {
+            ok: true, action, selector: args.selector,
+            state: present ? 'attached' : 'detached',
+            waitedMs: Date.now() - start,
+          };
+        }
+        if (Date.now() > deadline) {
+          return {
+            ok: false, action, selector: args.selector,
+            error: `timed out after ${String(timeoutMs)}ms waiting for ${JSON.stringify(args.selector)} to be ${wantPresent ? 'attached' : 'detached'}`,
+            // A hidden element still matches the selector, which is the usual
+            // reason someone reaches for `detached` and waits for ever.
+            hint: '`detached` means the element is absent from the DOM; a hidden element still matches the selector. Use eval to check getComputedStyle, or wait for the attribute or class that hides it.',
+          };
+        }
+        await sleep(150);
+      }
+    }
+
+    case 'eval': {
+      if (typeof args.expression !== 'string' || args.expression === '') return { ok: false, error: 'eval needs expression' };
+      const result = await connection.evaluate(args.expression, { awaitPromise: true, timeoutMs });
+      if (result.throws !== undefined) return { ok: false, action, error: result.throws, hint: 'The expression threw. Check that the page is in the state you expect and that the selector matches an element.' };
+      const value = result.value;
+      const serialized = typeof value === 'string' ? value : JSON.stringify(value);
+      return { ok: true, action, value, serialized: serialized ?? 'undefined' };
+    }
+
+    case 'screenshot': {
+      const result = await connection.send('Page.captureScreenshot', { format: args.format ?? 'png' }, timeoutMs);
+      const data = result.data;
+      if (typeof data !== 'string') return { ok: false, error: 'the engine returned no image data' };
+      if (typeof args.writeTo !== 'string' || args.writeTo === '') {
+        return { ok: false, error: 'screenshot needs writeTo (an absolute path): the image cannot be returned inline', bytes: Buffer.from(data, 'base64').length };
+      }
+      const directory = dirname(args.writeTo);
+      if (!existsSync(directory)) return { ok: false, error: `the destination directory does not exist: ${directory}` };
+      const buffer = Buffer.from(data, 'base64');
+      writeFileSync(args.writeTo, buffer);
+      return { ok: true, action, path: args.writeTo, bytes: buffer.length, format: args.format ?? 'png' };
+    }
+
+    case 'status':
+      return { ok: true, action };
+
+    case 'close':
+      return { ok: true, action };
+
+    default:
+      return { ok: false, error: `unknown action ${JSON.stringify(String(action))}` };
+  }
+}
+
+/**
+ * Press one key.
+ *
+ * The engine needs the key, the code and the legacy virtual key code to produce a
+ * complete event; `Enter` also needs the character fields, which is why the table
+ * carries more than the key name.
+ */
+const KEYS = {
+  Enter: { code: 'Enter', keyCode: 13, text: '\r' },
+  Tab: { code: 'Tab', keyCode: 9 },
+  Escape: { code: 'Escape', keyCode: 27 },
+  Backspace: { code: 'Backspace', keyCode: 8 },
+  ArrowUp: { code: 'ArrowUp', keyCode: 38 },
+  ArrowDown: { code: 'ArrowDown', keyCode: 40 },
+  ArrowLeft: { code: 'ArrowLeft', keyCode: 37 },
+  ArrowRight: { code: 'ArrowRight', keyCode: 39 },
+  PageUp: { code: 'PageUp', keyCode: 33 },
+  PageDown: { code: 'PageDown', keyCode: 34 },
+  Home: { code: 'Home', keyCode: 36 },
+  End: { code: 'End', keyCode: 35 },
+  Delete: { code: 'Delete', keyCode: 46 },
+};
+
+async function keyPress(connection, name) {
+  const spec = KEYS[name] ?? { code: name, keyCode: 0 };
+  const base = { key: name, code: spec.code, windowsVirtualKeyCode: spec.keyCode, nativeVirtualKeyCode: spec.keyCode };
+  const down = { ...base, type: spec.text === undefined ? 'rawKeyDown' : 'keyDown' };
+  if (spec.text !== undefined) down.text = spec.text;
+  await connection.send('Input.dispatchKeyEvent', down);
+  await connection.send('Input.dispatchKeyEvent', { ...base, type: 'keyUp' });
+}
+
+/** Exported for tests: the selector-and-box step, without an input dispatch. */
+export const __internal = { boxOf, ensureVisible, settle, snapshot, KEYS };

package/lib/session.js

@@ -0,0 +1,372 @@
+/**
+ * Interactive browser sessions, backed by `moli serve` and driven over CDP.
+ *
+ * Why this exists next to the fetch tool: `moli_fetch` is one shot -- it loads a
+ * page and prints it. That covers reading. It cannot click a cookie banner, fill
+ * a search box, scroll a lazy list, or wait for a client-side route change, which
+ * is most of what "use the web" means for an agent.
+ *
+ * `moli serve` already exposes Chrome DevTools Protocol, WebDriver Classic and
+ * WebDriver BiDi; this module talks CDP over the loopback WebSocket that the
+ * server publishes at `/json/list`. No dependency is added: Node's built-in
+ * `WebSocket` (21+) does the transport, which is why this feature needs a newer
+ * Node than the rest of the plugin.
+ *
+ * Two design constraints come from the plugin's history and shape everything here:
+ *
+ * - **A server is a long-lived child, unlike every other call in this plugin.**
+ *   `runOnce` spawns, waits and reaps. A serve process must outlive a single tool
+ *   call, so its lifecycle is explicit: started lazily on first use, held across
+ *   calls, and stopped by `close`. Nothing here may block the DSH host, so the
+ *   child is spawned asynchronously and every wait is cancellable.
+ * - **The sandbox blocks named pipes, not loopback TCP.** The plugin writes child
+ *   stdout to real files for that reason. HTTP and WebSocket over 127.0.0.1 are
+ *   fine -- verified under the restricted sandbox -- so CDP works where an
+ *   inherited pipe would not.
+ *
+ * @module dsh-moli/lib/session
+ */
+import { spawn } from 'node:child_process';
+import { closeSync, existsSync, mkdirSync, openSync, statSync, writeFileSync } from 'node:fs';
+import { createConnection } from 'node:net';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+/** CDP needs Node's built-in WebSocket, which arrived in 21. */
+export const MIN_NODE_FOR_SESSION = '21.0.0';
+
+/** Whether this Node can run a session at all. */
+export function sessionSupported() {
+  return typeof globalThis.WebSocket === 'function';
+}
+
+/** The message used when it cannot, so callers do not have to phrase it. */
+export function sessionUnsupportedReason() {
+  return `moli_session needs Node >= ${MIN_NODE_FOR_SESSION} for the built-in WebSocket; this is Node ${process.versions.node}. moli_fetch and moli_probe work on older versions.`;
+}
+
+// ---------------------------------------------------------------------------
+// small helpers
+// ---------------------------------------------------------------------------
+
+const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
+
+/** Whether something is listening on host:port, used before spawning a server. */
+export function portListens(host, port, timeoutMs = 700) {
+  return new Promise(resolve => {
+    const socket = createConnection({ host, port });
+    const settle = value => {
+      socket.removeAllListeners();
+      socket.destroy();
+      resolve(value);
+    };
+    socket.setTimeout(timeoutMs);
+    socket.once('connect', () => settle(true));
+    socket.once('timeout', () => settle(false));
+    socket.once('error', () => settle(false));
+  });
+}
+
+/** GET a JSON document from the local server, with a deadline. */
+async function getJson(url, timeoutMs) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetch(url, { signal: controller.signal });
+    if (!response.ok) throw new Error(`HTTP ${String(response.status)} for ${url}`);
+    return await response.json();
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// CDP client
+// ---------------------------------------------------------------------------
+
+/**
+ * A single WebSocket connection to one page target.
+ *
+ * `send` resolves with the CDP result or rejects with the protocol error, and
+ * never rejects on a target that has gone away without a reply -- the socket
+ * close path settles everything outstanding, so a caller cannot hang forever.
+ */
+class CdpConnection {
+  constructor(ws, targetId) {
+    this.ws = ws;
+    this.targetId = targetId;
+    this.nextId = 1;
+    this.pending = new Map();
+    this.listeners = new Set();
+    this.closed = false;
+    this.lastError = undefined;
+
+    ws.addEventListener('message', event => {
+      let message;
+      try { message = JSON.parse(String(event.data)); } catch { return; }
+      if (message.id !== undefined && this.pending.has(message.id)) {
+        const entry = this.pending.get(message.id);
+        this.pending.delete(message.id);
+        if (message.error !== undefined) entry.reject(new Error(`${entry.method}: ${String(message.error.message ?? JSON.stringify(message.error))}`));
+        else entry.resolve(message.result ?? {});
+        return;
+      }
+      if (message.method !== undefined) {
+        for (const listener of this.listeners) {
+          try { listener(message); } catch { /* a listener must not break the socket */ }
+        }
+      }
+    });
+
+    const failAll = reason => {
+      this.closed = true;
+      this.lastError = reason;
+      for (const [, entry] of this.pending) entry.reject(new Error(reason));
+      this.pending.clear();
+    };
+    ws.addEventListener('close', () => failAll('the CDP connection closed'));
+    ws.addEventListener('error', () => failAll('the CDP connection errored'));
+  }
+
+  /** Subscribe to protocol events; returns an unsubscribe function. */
+  onEvent(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+
+  /** Send one CDP command. */
+  send(method, params = {}, timeoutMs = 30000) {
+    if (this.closed) return Promise.reject(new Error(this.lastError ?? 'the CDP connection is closed'));
+    const id = this.nextId++;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`${method} timed out after ${String(timeoutMs)}ms`));
+      }, timeoutMs);
+      this.pending.set(id, {
+        method,
+        resolve: value => { clearTimeout(timer); resolve(value); },
+        reject: error => { clearTimeout(timer); reject(error); },
+      });
+      try {
+        this.ws.send(JSON.stringify({ id, method, params }));
+      } catch (error) {
+        this.pending.delete(id);
+        clearTimeout(timer);
+        reject(error instanceof Error ? error : new Error(String(error)));
+      }
+    });
+  }
+
+  /**
+   * Evaluate an expression in the page and return its value.
+   *
+   * A thrown expression is returned as `{ throws }` rather than rejected: the
+   * caller is a model, and "your selector matched nothing" is information, not a
+   * transport failure.
+   */
+  async evaluate(expression, { awaitPromise = false, timeoutMs = 30000 } = {}) {
+    const result = await this.send('Runtime.evaluate', {
+      expression,
+      returnByValue: true,
+      awaitPromise,
+      userGesture: true,
+    }, timeoutMs);
+    if (result.exceptionDetails !== undefined) {
+      const detail = result.exceptionDetails;
+      const text = detail.exception?.description ?? detail.text ?? 'the expression threw';
+      return { throws: String(text).split('\n')[0] };
+    }
+    return { value: result.result?.value };
+  }
+
+  close() {
+    this.closed = true;
+    try { this.ws.close(); } catch { /* already gone */ }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// server lifecycle
+// ---------------------------------------------------------------------------
+
+/**
+ * Owns the `moli serve` child and the connection to it.
+ *
+ * One session per plugin instance. `ensure` is idempotent: it reuses a live
+ * child, and if the port is already served by someone else's moli (the user's own
+ * `moli serve`, another profile) it connects to that instead of failing to bind.
+ */
+export class SessionManager {
+  /**
+   * @param options - resolved engine path, plugin config, and a logger.
+   */
+  constructor(options) {
+    this.options = options;
+    this.child = undefined;
+    this.connection = undefined;
+    this.port = options.port ?? 9222;
+    this.host = options.host ?? '127.0.0.1';
+    this.external = false;
+    this.pid = undefined;
+  }
+
+  /** The running child, or undefined when nothing was started by us. */
+  get started() {
+    return this.child !== undefined && this.child.exitCode === null;
+  }
+
+  /**
+   * Start the server if needed and return a live CDP connection.
+   *
+   * @returns the connection, plus whether the server was already running.
+   */
+  async ensure() {
+    if (this.connection !== undefined && this.connection.closed === false) {
+      return { connection: this.connection, external: this.external };
+    }
+    this.connection = undefined;
+
+    // Someone else may already serve this port: the user's own moli serve, or a
+    // previous run that outlived us. Connecting to it is friendlier than refusing
+    // to bind, and it is detectable: the CDP endpoint identifies the browser.
+    if (await portListens(this.host, this.port)) {
+      const version = await this.#probeVersion();
+      if (version !== undefined) {
+        const connection = await this.#connect();
+        this.external = true;
+        this.connection = connection;
+        return { connection, external: true, version };
+      }
+      throw new Error(
+        `port ${String(this.port)} is in use but does not answer as a CDP endpoint. `
+        + 'Pass a different `port`, or stop whatever is listening there.');
+    }
+
+    if (!this.options.exe) throw new Error('no moli engine is available to start a session');
+
+    const args = ['serve', '--host', this.host, '--port', String(this.port)];
+    // Layout is what makes geometry, hit-testing and screenshots real; without it
+    // the engine keeps compatibility geometry and clicks land in the wrong place.
+    args.push('--layout');
+    if (this.options.insecureTls === true) args.push('--insecure-disable-tls-host-verification');
+    if (this.options.proxy !== undefined && this.options.proxy !== '') args.push('--http-proxy', this.options.proxy);
+    if (this.options.userAgent !== undefined && this.options.userAgent !== '') args.push('--user-agent', this.options.userAgent);
+    if (this.options.profileDir !== undefined && this.options.profileDir !== '') args.push('--profile-dir', this.options.profileDir);
+    if (this.options.resources === true) args.push('--resource');
+    if (this.options.blockPrivateNetworks === true) args.push('--block-private-networks');
+    for (const cidr of this.options.blockCidrs ?? []) args.push('--block-cidrs', cidr);
+
+    // Child output goes to real files: the sandbox blocks inherited pipes, the
+    // same reason lib/moli.js redirects every other child.
+    const logPath = join(tmpdir(), `dsh-moli-serve-${String(process.pid)}.log`);
+    const outFd = openSync(logPath, 'w');
+    const child = spawn(this.options.exe, args, { stdio: ['ignore', outFd, outFd], windowsHide: true });
+    closeSync(outFd);
+    this.child = child;
+    this.pid = child.pid;
+    this.logPath = logPath;
+
+    const exited = new Promise(resolve => child.once('exit', code => resolve(code)));
+    // Wait for the port, or for the child to die trying.
+    const started = Date.now();
+    const deadline = started + (this.options.startTimeoutMs ?? 20000);
+    for (;;) {
+      if (child.exitCode !== null) {
+        throw new Error(`moli serve exited with ${String(child.exitCode)} before listening; see ${logPath}`);
+      }
+      if (await portListens(this.host, this.port, 400)) break;
+      if (Date.now() > deadline) {
+        child.kill('SIGTERM');
+        throw new Error(`moli serve did not listen on ${this.host}:${String(this.port)} within ${String(this.options.startTimeoutMs ?? 20000)}ms; see ${logPath}`);
+      }
+      await sleep(150);
+    }
+
+    // The socket can open a moment before the target is published.
+    let connection;
+    let lastError;
+    for (let attempt = 0; attempt < 20; attempt++) {
+      try { connection = await this.#connect(); break; }
+      catch (error) { lastError = error; await sleep(150); }
+    }
+    if (connection === undefined) {
+      child.kill('SIGTERM');
+      throw new Error(`moli serve is listening on port ${String(this.port)} but no page target was reachable: ${String(lastError?.message ?? 'unknown')}`);
+    }
+    void exited;
+    this.external = false;
+    this.connection = connection;
+    return { connection, external: false };
+  }
+
+  /** Ask the CDP endpoint who it is; undefined when it is not a CDP endpoint. */
+  async #probeVersion() {
+    try {
+      const version = await getJson(`http://${this.host}:${String(this.port)}/json/version`, 3000);
+      return typeof version.Browser === 'string' ? version : undefined;
+    } catch {
+      return undefined;
+    }
+  }
+
+  /** Open a WebSocket to the first page target and enable the domains we use. */
+  async #connect() {
+    if (!sessionSupported()) throw new Error(sessionUnsupportedReason());
+    const targets = await getJson(`http://${this.host}:${String(this.port)}/json/list`, 5000);
+    const page = Array.isArray(targets) ? targets.find(t => t.type === 'page' || t.type === undefined) : undefined;
+    if (page === undefined || typeof page.webSocketDebuggerUrl !== 'string') {
+      throw new Error(`no page target on http://${this.host}:${String(this.port)}/json/list`);
+    }
+    const ws = new WebSocket(page.webSocketDebuggerUrl);
+    await new Promise((resolve, reject) => {
+      const timer = setTimeout(() => reject(new Error('the CDP WebSocket did not open in time')), 10000);
+      ws.addEventListener('open', () => { clearTimeout(timer); resolve(); }, { once: true });
+      ws.addEventListener('error', () => { clearTimeout(timer); reject(new Error('the CDP WebSocket failed to open')); }, { once: true });
+    });
+    const connection = new CdpConnection(ws, page.id);
+    for (const domain of ['Page.enable', 'Runtime.enable', 'DOM.enable']) {
+      await connection.send(domain, {}, 10000);
+    }
+    return connection;
+  }
+
+  /** Stop the server if we started it. A reused external server is left alone. */
+  async close() {
+    const connection = this.connection;
+    this.connection = undefined;
+    if (connection !== undefined) connection.close();
+    const child = this.child;
+    this.child = undefined;
+    this.pid = undefined;
+    const wasExternal = this.external;
+    this.external = false;
+    if (child === undefined || child.exitCode !== null) {
+      return { stopped: false, external: wasExternal };
+    }
+    child.kill('SIGTERM');
+    const deadline = Date.now() + 5000;
+    while (child.exitCode === null && Date.now() < deadline) await sleep(100);
+    if (child.exitCode === null) child.kill('SIGKILL');
+    return { stopped: true, external: false, logPath: this.logPath };
+  }
+
+  /** Diagnostic view of the session, for the tool's `status` action. */
+  async status() {
+    const running = this.started || this.external;
+    const base = {
+      running,
+      ownedByThisPlugin: this.started,
+      external: this.external,
+      pid: this.pid,
+      endpoint: `http://${this.host}:${String(this.port)}`,
+      logPath: this.logPath,
+    };
+    if (!running) return base;
+    const connection = this.connection;
+    if (connection === undefined) return base;
+    const url = await connection.evaluate('location.href');
+    const title = await connection.evaluate('document.title');
+    return { ...base, url: url.value, title: title.value };
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-moli",
-  "version": "1.1.10",
+  "version": "1.1.11",
   "type": "module",
   "description": "DeepSeek Harness tools for the local Moli headless browser: rendered fetches, markdown, semantic trees, screenshots, and PDFs.",
   "license": "MIT",