dsh-moli 1.1.10 → 1.1.12

package/README.md

@@ -223,6 +223,102 @@ 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.
+
+### 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}
+```
+
+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.
+
+`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 +406,26 @@ 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
 ```
 
 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 +488,21 @@ 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. 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

@@ -209,6 +209,96 @@ 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 选择器**定位，不接受像素坐标：工具自己测量元素并派发真实的鼠标与键盘事件，所以页面的
+处理器会像人操作时一样执行。
+
+### 选哪个浏览器：`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}
+```
+
+它能做到包装层做不到的事：切换 target、跨域 iframe、文件上传、额外的请求头、网络拦截。`params` 可以是对象
+或 JSON 字符串。
+
+本工具需要 **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 +374,22 @@ 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
 ```
 
 上面配置里的 `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 +436,17 @@ 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` 路径。未安装引擎时跳过。
+- `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

@@ -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,174 @@ 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', 'cdp', '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. 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.' },
+    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.' },
+    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 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.',
+    },
+  },
+};
+
+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' },
+    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' },
+    pid: { type: 'integer' },
+    endpoint: { type: 'string' },
+    logPath: { type: 'string' },
+    settled: { type: 'boolean' },
+    settledMs: { type: 'integer' },
+    stopped: { type: 'boolean' },
+    scope: { type: 'string' },
+  },
+};
+
+/**
+ * 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') {
+    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 [{
+      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 +525,133 @@ 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; },
+    // 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,
+    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) {
+      // 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') {
+        return withCallEndpoint(async () => ({ ok: true, action: 'close', ...(await session.close()) }));
+      }
+      if (args.action === 'status') {
+        return withCallEndpoint(async () => ({ ok: true, action: 'status', ...(await session.status()) }));
+      }
+      if (args.action === 'start') {
+        if (!sessionSupported()) return { ok: false, action: 'start', error: sessionUnsupportedReason() };
+        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 && (options.sessionBrowser ?? 'moli') === 'moli'
+        && (options.sessionCdpEndpoint === undefined || options.sessionCdpEndpoint === '')) {
+        return {
+          ok: false,
+          action: String(args.action),
+          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() };
+
+      if (exec?.signal?.aborted === true) return { ok: false, action: String(args.action), error: 'the call was aborted before it started' };
+
+      try {
+        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.'
+          : /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'})`);
 }