dsh-moli 1.1.11 → 1.1.12

package/README.md

@@ -247,20 +247,70 @@ moli_session action=close                                # stop it and free the
 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:
+### Choosing a browser: `moli` or `chromium`
 
+`moli_session` can drive either engine, and you choose which — there is **no automatic fallback**,
+because switching engines when one click fails would make the timing and the behaviour depend on which
+operation happened to fail, and you could not tell which browser answered.
+
+```yaml
+config:
+  sessionBrowser: moli          # moli (default) or chromium
+  sessionBrowserPath: ''        # optional path to chrome.exe / msedge.exe / brave
+  sessionPort: 9222
 ```
+
+**Why the choice exists.** Moli'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 and Chrome 155, same page,
+same element:
+
+| | `rect.y` at scrollY 0 / 400 / 800 | click a control below the first viewport |
+|---|---|---|
+| **moli** | 1008 / 1008 / 1008 — never moves | **impossible**; synthetic input cannot reach it |
+| **chromium** | 1008 / 608 / 208 — follows the scroll | **works**; the browser scrolls to it |
+
+So moli is the good default — it is the engine this plugin wraps, it is lighter, and it is already
+installed — and a real Chromium is what you switch to when a task needs an element further down a long
+page. When moli refuses, it says so, names the element, and points at both routes:
+
+```
+moli_session action=click selector="#far-down"
+  → "#far-down" is below the viewport (y=2548) and this engine cannot send input there
+
+# either click from inside the page (reaches it, but skips hover and focus behaviour)
 moli_session action=eval expression="document.querySelector('#far-down').click()"
+
+# or use a real browser for that session
+config: sessionBrowser: chromium
+```
+
+With `chromium` the plugin starts the browser it finds (Chrome, Edge or Brave, or `sessionBrowserPath`)
+in `--headless=new` mode with its own profile, so it does not touch your normal browsing profile.
+
+### Driving a browser you already have open
+
+Pass `cdpEndpoint` to attach to a CDP port instead of starting anything. This is the only way to inherit
+your own cookies and logins: start your browser with `--remote-debugging-port=9222`, then
+
+```
+moli_session action=open url=https://example.com cdpEndpoint=http://127.0.0.1:9222
+```
+
+The endpoint applies to that call only. A browser this plugin did not start is **never stopped by
+`close`**, and `status` reports `external: true` so you can tell.
+
+### `cdp` — the raw protocol escape hatch
+
+Everything the named actions do is an abstraction chosen in advance. `action=cdp` is not:
+
+```
+moli_session action=cdp method=Browser.getVersion
+moli_session action=cdp method=Network.setExtraHTTPHeaders params={"headers":{"X-Thing":"1"}}
+moli_session action=cdp method=DOM.setFileInputFiles params={"files":["/abs/a.png"],"nodeId":42}
 ```
 
-`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.
+It reaches what the wrapper does not: other targets, cross-origin frames, file inputs, extra headers,
+network interception. `params` may be an object or a JSON string.
 
 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.
@@ -356,6 +406,8 @@ 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
+        sessionBrowser: moli                                     # or chromium, for the session tool
+        sessionBrowserPath: ''                                   # explicit chrome.exe / msedge.exe / brave
         sessionPort: 9222                                        # CDP port for moli_session
         blockPrivateNetworks: false                              # refuse private addresses (see the note below)
         blockCidrs: []                                           # extra CIDRs to refuse
@@ -441,7 +493,16 @@ Four suites live in [`verify/`](verify/), and all are runnable against a working
   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.
+  around it asserted next to it. It skips when no engine is installed.
+- `session-backends.mjs` is the comparison that justifies the second backend: the same page, the same
+  control below the viewport, asserted to be **refused on moli and clicked on Chromium**, plus the
+  `cdp` action on both. The Chromium half skips when the machine has no Chromium-family browser.
+- `session-attach-verify.mjs` covers external endpoints and ownership: attaching to a browser this
+  plugin did not start, identifying it correctly, refusing to stop it on `close`, and — the trap that
+  a behavioural probe got wrong — classifying an external **moli** as moli even though it answers
+  `/json/version` with `"Browser":"Chrome/145.0.0.0"`. It also asserts that naming a per-call endpoint
+  does not latch it, which an earlier version did: one call against a dead endpoint left the session
+  pointing at port 9 for the rest of the process.
 
 `.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

@@ -231,17 +231,67 @@ moli_session action=close                                # 停止并释放端口
 元素一律用 **CSS 选择器**定位，不接受像素坐标：工具自己测量元素并派发真实的鼠标与键盘事件，所以页面的
 处理器会像人操作时一样执行。
 
-**依赖 `click` 之前需要知道一件事。** 这个引擎的元素几何是**文档绝对坐标且不随滚动更新**，而它的命中测试
-**受视口高度限制**。在 Moli 1.1.16 上实测：文档 `y=1008` 的元素在 `scrollY` 为 0、400、800 时报告的 `y`
-完全相同，而 `elementFromPoint` 在 `y=1080` 之后一律返回 null。后果是：**在长到需要滚动的页面上，合成输入
-无法触达首个视口以下的元素。** `click` 会如实报出这一点并点名元素，同时给出真正可行的路径：
+### 选哪个浏览器：`moli` 还是 `chromium`
 
+`moli_session` 可以驱动两种引擎，由你选择——**没有自动降级**。因为"某个点击失败就换引擎"会让工具的耗时和
+行为取决于哪一步恰好失败，而且你无法知道最后是哪个浏览器在回答。
+
+```yaml
+config:
+  sessionBrowser: moli          # moli（默认）或 chromium
+  sessionBrowserPath: ''        # 可选，指定 chrome.exe / msedge.exe / brave
+  sessionPort: 9222
 ```
+
+**为什么需要这个选择。** moli 的元素几何是**文档绝对坐标且不随滚动更新**，命中测试又受视口高度限制。在
+Moli 1.1.16 与 Chrome 155 上，同一页面、同一元素实测：
+
+| | `rect.y` 在 scrollY 0 / 400 / 800 | 点击首个视口以下的控件 |
+|---|---|---|
+| **moli** | 1008 / 1008 / 1008 —— 纹丝不动 | **做不到**，合成输入触达不了 |
+| **chromium** | 1008 / 608 / 208 —— 跟随滚动 | **可以**，浏览器会滚动到它 |
+
+所以 moli 是合适的默认值——它是本插件包装的引擎、更轻、而且你已经装了；而当任务需要长页面下方的元素时，
+就换成真实 Chromium。moli 拒绝时会把原因、元素和两条出路都讲清楚：
+
+```
+moli_session action=click selector="#far-down"
+  → "#far-down" is below the viewport (y=2548) and this engine cannot send input there
+
+# 要么在页面内部点击（能触达，但会跳过 hover 与 focus 行为）
 moli_session action=eval expression="document.querySelector('#far-down').click()"
+
+# 要么这个会话改用真实浏览器
+config: sessionBrowser: chromium
+```
+
+选 `chromium` 时，插件会在 `--headless=new` 模式下用**独立 profile** 启动它找到的浏览器（Chrome、Edge 或
+Brave，也可用 `sessionBrowserPath` 指定），不会碰你日常使用的浏览器配置。
+
+### 驱动你自己已经开着的浏览器
+
+传 `cdpEndpoint` 即可连接到已有的 CDP 端口，什么都不启动。这是**继承你自己 cookie 与登录态的唯一途径**：
+用 `--remote-debugging-port=9222` 启动你的浏览器，然后
+
+```
+moli_session action=open url=https://example.com cdpEndpoint=http://127.0.0.1:9222
+```
+
+该端点**只对当次调用生效**。不是本插件启动的浏览器**永远不会被 `close` 关掉**，并且 `status` 会报
+`external: true` 让你能分辨。
+
+### `cdp` —— 原始协议逃生舱
+
+具名动作全都是"预先替你决定好的抽象"，而 `action=cdp` 不是：
+
+```
+moli_session action=cdp method=Browser.getVersion
+moli_session action=cdp method=Network.setExtraHTTPHeaders params={"headers":{"X-Thing":"1"}}
+moli_session action=cdp method=DOM.setFileInputFiles params={"files":["/绝对/a.png"],"nodeId":42}
 ```
 
-`eval` 在页面内部执行点击，绕开输入层，因此能触达输入 API 达不到的元素。注意它同时跳过了 hover 与 focus
-行为——这正是"点击一个控件"与"调用它的处理器"的区别。
+它能做到包装层做不到的事：切换 target、跨域 iframe、文件上传、额外的请求头、网络拦截。`params` 可以是对象
+或 JSON 字符串。
 
 本工具需要 **Node 21 或更新版本**（内置 `WebSocket`）；在 Node 20 上会直接说明原因，而不是给出费解的失败。
 `moli_fetch` 与 `moli_probe` 仍支持 20.12。
@@ -324,6 +374,8 @@ cookie 驱动的查询参数。那次实测同时覆盖了代理下载路由与
         maxChars: 200000                                         # 内联文本截断阈值
         proxy: 'http://127.0.0.1:7890'                           # 转给本地正向代理（moli、下载、安装器内部引擎下载都走它）
         insecureTls: true                                        # 见下方 TLS 说明
+        sessionBrowser: moli                                     # 或 chromium，供 session 工具使用
+        sessionBrowserPath: ''                                   # 显式指定 chrome.exe / msedge.exe / brave
         sessionPort: 9222                                        # moli_session 的 CDP 端口
         blockPrivateNetworks: false                              # 拒绝私网地址（见下方说明）
         blockCidrs: []                                           # 额外拒绝的 CIDR
@@ -387,7 +439,14 @@ profile。无论生效的是哪个代理，loopback 地址一律绕过它。
 - `session-verify.mjs` 用 `data:` URL 夹具端到端驱动 `moli_session`，因此不依赖网络、也不会因为站点变化而
   失效：生命周期与端口释放、snapshot、click、带与不带清空的 type、press、scroll、两个方向的 `waitFor`、
   含抛异常的 eval、截图字节签名、点击链接导航、关闭后重启，以及上面那条视口限制——限制被当作**限制**断言，
-  紧随其后断言真正能绕过它的 `eval` 路径。
+  紧随其后断言真正能绕过它的 `eval` 路径。未安装引擎时跳过。
+- `session-backends.mjs` 是**证明第二个后端存在必要性**的对照：同一页面、同一个视口以下的控件，断言它
+  **在 moli 上被拒绝、在 Chromium 上被点中**，并在两者上都验证 `cdp` 动作。机器上没有 Chromium 系浏览器时
+  跳过 Chromium 那半。
+- `session-attach-verify.mjs` 覆盖外部端点与归属权：连接不是本插件启动的浏览器、正确识别它、`close` 时拒绝
+  停掉它；以及那个**行为探测会搞错的陷阱**——外部端点是 **moli** 时仍判定为 moli，尽管它在 `/json/version`
+  里报的是 `"Browser":"Chrome/145.0.0.0"`。它还断言按调用传入的端点**不会粘住**——早期版本会：一次对死端点
+  的调用会让整个进程后续都指向 9 端口。
 
 `.github/workflows/verify.yml` 在 Linux、Windows、macOS 上跑前两个（无需引擎、无需网络），在 Linux 与 Windows
 上尝试依赖引擎的几套；若 runner 上没有引擎，则报告为跳过而不是失败。

package/index.js

@@ -229,7 +229,7 @@ function renderProbe(_args, value) {
 }
 
 /** Actions `moli_session` accepts. */
-const SESSION_ACTIONS = ['start', 'open', 'snapshot', 'click', 'type', 'press', 'scroll', 'waitFor', 'eval', 'screenshot', 'status', 'close'];
+const SESSION_ACTIONS = ['start', 'open', 'snapshot', 'click', 'type', 'press', 'scroll', 'waitFor', 'eval', 'cdp', 'screenshot', 'status', 'close'];
 
 /**
  * Parameters of `moli_session`.
@@ -248,7 +248,8 @@ const SESSION_PARAMETERS = {
       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.',
+        + 'eval: run JavaScript in the page. cdp: send a raw Chrome DevTools Protocol command. '
+        + 'screenshot: write a PNG. status: report the session and which browser it uses. 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.' },
@@ -260,12 +261,18 @@ const SESSION_PARAMETERS = {
     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.' },
+    method: { type: 'string', description: 'cdp: the protocol method to invoke, e.g. "Network.enable" or "DOM.setFileInputFiles".' },
+    params: { description: 'cdp: the method parameters, as an object or a JSON string. Optional.' },
     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.' },
+    maxChars: { type: 'integer', description: 'snapshot and cdp: truncate text output 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).' },
+    cdpEndpoint: {
+      type: 'string',
+      description: 'Attach to a browser that is already running, e.g. "http://127.0.0.1:9222", instead of starting one. This is how you drive your own Chrome with its logins: start it with --remote-debugging-port and pass that URL.',
+    },
   },
 };
 
@@ -301,6 +308,12 @@ const SESSION_OUTPUT_SCHEMA = {
     path: { type: 'string' },
     bytes: { type: 'integer' },
     format: { type: 'string' },
+    method: { type: 'string' },
+    result: {},
+    bytes: { type: 'integer' },
+    backend: { type: 'string' },
+    geometry: { type: 'string' },
+    browserVersion: { type: 'string' },
     running: { type: 'boolean' },
     ownedByThisPlugin: { type: 'boolean' },
     external: { type: 'boolean' },
@@ -310,6 +323,7 @@ const SESSION_OUTPUT_SCHEMA = {
     settled: { type: 'boolean' },
     settledMs: { type: 'integer' },
     stopped: { type: 'boolean' },
+    scope: { type: 'string' },
   },
 };
 
@@ -344,12 +358,21 @@ function renderSession(_args, value) {
     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.running !== true) {
+      return [{ type: 'text', text: 'No session is running. Call moli_session with action "start" or "open" to launch one.' }];
+    }
+    const lines = [
+      `Session running: ${String(value.backend)} (${String(value.browserVersion ?? 'version unknown')}) at ${String(value.endpoint)}`,
+    ];
+    if (value.geometry === 'absolute') {
+      lines.push('Geometry: moli\'s document-absolute frame — element input cannot reach below the first viewport. Use `browser: "chromium"` to lift that, or eval to click in the page.');
+    }
+    if (value.external === true) lines.push('Started outside this plugin, so close will not stop it.');
+    if (value.url !== undefined) lines.push(`Current page: ${String(value.title)} — ${String(value.url)}`);
+    return [{ type: 'text', text: lines.join('\n') }];
+  }
+  if (value.action === 'cdp') {
+    return [{ type: 'text', text: `${String(value.method)} → ${String(value.serialized ?? '').slice(0, 4000)}` }];
   }
   if (value.action === 'click') {
     return [{
@@ -513,6 +536,13 @@ export function apply(ctx, config) {
   // load time, so a plugin load cannot delay Host startup or open a port.
   const session = new SessionManager({
     get exe() { return cachedExe; },
+    // Which browser drives a session. Explicit, never automatic: switching engines
+    // because one click failed would make the timing and the behaviour depend on
+    // which operation happened to fail, and the caller could not tell which browser
+    // it was talking to.
+    browser: options.sessionBrowser ?? 'moli',
+    browserPath: options.sessionBrowserPath,
+    cdpEndpoint: options.sessionCdpEndpoint,
     port: options.sessionPort ?? 9222,
     host: '127.0.0.1',
     insecureTls,
@@ -544,29 +574,40 @@ export function apply(ctx, config) {
     // navigate the page out from under each other.
     isConcurrencySafe: () => false,
     async execute(args, exec) {
+      // A per-call endpoint is honoured by every action, including the ones that
+      // never reach `performAction`. Routing `close` through it is not cosmetic:
+      // `withEndpoint` is what marks the connection external, and `close` refuses
+      // to stop an external browser. Answering `close` before that mark existed
+      // meant a call that had just attached to the user's own Chrome could shut it
+      // down -- the one thing this design promises not to do.
+      const withCallEndpoint = work => (typeof args.cdpEndpoint === 'string' && args.cdpEndpoint !== ''
+        ? session.withEndpoint(args.cdpEndpoint, work)
+        : work());
+
       // `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 };
+        return withCallEndpoint(async () => ({ ok: true, action: 'close', ...(await session.close()) }));
       }
       if (args.action === 'status') {
-        const state = await session.status();
-        return { ok: true, action: 'status', ...state };
+        return withCallEndpoint(async () => ({ ok: true, action: 'status', ...(await session.status()) }));
       }
       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 };
+        return withCallEndpoint(async () => {
+          const { external, backend, geometry } = await session.ensure();
+          const state = await session.status();
+          return { ok: true, action: 'start', started: true, external, backend, geometry, ...state };
+        });
       }
 
-      if (engine() === undefined) {
+      if (engine() === undefined && (options.sessionBrowser ?? 'moli') === 'moli'
+        && (options.sessionCdpEndpoint === undefined || options.sessionCdpEndpoint === '')) {
         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`.',
+          error: 'moli was not found, so a moli session cannot be started',
+          hint: 'Call moli_probe with action "install", set the plugin config field `exePath`, or set `sessionBrowser: "chromium"` to drive the browser you already have.',
         };
       }
       if (!sessionSupported()) return { ok: false, action: String(args.action), error: sessionUnsupportedReason() };
@@ -574,23 +615,43 @@ export function apply(ctx, config) {
       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;
+        const perform = async ({ connection, geometry, backend }) => {
+          try {
+            return await performAction(connection, args, { maxChars, geometry, backend });
+          } finally {
+            // 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();
+          }
+        };
+        // A per-call endpoint drives a browser the caller already has open, which is
+        // the only way to inherit their logins. It is scoped to this call: an
+        // endpoint that latched would make one bad call poison every later one.
+        if (typeof args.cdpEndpoint === 'string' && args.cdpEndpoint !== '') {
+          return await session.withEndpoint(args.cdpEndpoint, perform);
+        }
+        return await perform(await session.ensure());
       } 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;
+          : /no Chromium-family browser/u.test(message)
+            ? 'Install Chrome, Edge or Brave, or set the plugin config field `sessionBrowserPath` to a browser executable.'
+            : /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 }) };
       }
     },
   });
 
+  // A serve process or a headless browser outlives a tool call, so it must be tied
+  // to the plugin's lifetime rather than left to the OS. Cordis disposes listeners
+  // registered through `ctx.on` together with the plugin's fiber, so registering
+  // one is enough; the returned disposer is not needed here.
+  if (typeof ctx.on === 'function') {
+    ctx.on('dispose', () => { void session.close(); });
+  }
+
   ctx.logger?.info?.(`dsh-moli: registered moli_fetch, moli_probe and moli_session (${cachedExe ?? 'moli missing'})`);
 }