dsh-moli 1.1.3 → 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,8 +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.
@@ -367,6 +429,23 @@ Four suites live in [`verify/`](verify/), and all are runnable against a working
 - `win-verify.mjs` (Windows hosts) runs the same pure assertions, then executes the `DefaultWebProxy`
   prelude in a real `powershell.exe` and inspects the proxy object and credentials it set, exercises
   the Windows download routes, and runs `installMoli` end to end.
+- `empty-verify.mjs` asserts, against three compiled stub engines, that a fetch which exits 0 with no
+  output is a successful empty result rather than an error, that a non-zero exit still fails, and that
+  a complaint on stderr with no stdout is not mistaken for an empty page.
+- `report-verify.mjs` guards the findings from a usage report: `eval` documents that pairing it with
+  `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
+as a skip rather than a failure.
 
 Beyond those, `lib/moli.js` and the tool layer were exercised end to end against Moli 1.1.16 on
 Windows: registration, probe, Markdown and JSON dumps, `eval` (including a tight-timeout regression
@@ -380,6 +459,32 @@ Confirmed at runtime too: a JavaScript-rendered page (GitHub search) returned 14
 Markdown containing 30 real repository matches when fetched through a local proxy. A throwaway
 profile with the plugin installed composes its config with no `JsonSchemaError` and no skipped bundle.
 
+## Releasing
+
+Publishing goes through GitHub Actions' OIDC identity, so **no npm token exists to expire**:
+
+```bash
+npm version patch          # or minor / major
+git push && git tag v1.1.6 && git push origin v1.1.6
+```
+
+`.github/workflows/publish.yml` checks that the tag matches `package.json`, runs the offline suites,
+and publishes. One-time setup on npmjs.com: **package → Settings → Trusted Publisher → GitHub
+Actions**, with user `27painter`, repository `dsh-moli`, workflow filename `publish.yml`, and the
+`npm publish` action allowed.
+
+**Do not publish with a stored token.** This machine was configured with a classic token that bypasses
+2FA, and npm is retiring those; when it was revoked, the publish failed with
+
+```
+E404 Not Found - PUT https://registry.npmjs.org/dsh-moli
+     The requested resource 'dsh-moli@1.1.5' could not be found or you do not have permission
+```
+
+which reads as a missing package and is actually an authorisation failure. Run
+`node scripts/preflight-publish.mjs` before any local publish: it reports whether the credential can
+authenticate and names that misleading 404 when it cannot.
+
 ## License
 
 MIT. See [LICENSE](LICENSE).

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,8 +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`，
 所以装在带版本号的子目录里也能找到。
@@ -327,6 +379,18 @@ cookie 驱动的查询参数。那次实测同时覆盖了代理下载路由与
   这正是异步路径的验收标准。
 - `win-verify.mjs`（Windows 主机）跑同样的纯函数断言，然后在真实 `powershell.exe` 里执行 `DefaultWebProxy`
   prelude 并检查它设置的代理对象与凭据，练习 Windows 下载路由，并端到端跑 `installMoli`。
+- `empty-verify.mjs` 用三个编译好的桩引擎断言：退出码 0 且无输出属于"成功但内容为空"，而不是错误；非零退出
+  仍然失败；stderr 有抱怨而 stdout 为空不会被误当成空页面。
+- `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 上没有引擎，则报告为跳过而不是失败。
 
 此外，`lib/moli.js` 与工具层在 Windows 上对 Moli 1.1.16 做了端到端验证：注册、probe、Markdown 与 JSON
 dump、`eval`（含针对 `-t` 参数位置的紧超时回归防护）、PNG 与 PDF 产物签名、截断、全部拒绝路径（二元 dump
@@ -337,6 +401,30 @@ dump、`eval`（含针对 `-t` 参数位置的紧超时回归防护）、PNG 与
 30 处真实结果匹配。另有一个装了本插件的一次性 profile，组合其配置时既无 `JsonSchemaError` 也无被跳过的
 bundle。
 
+## 发布
+
+发布走 GitHub Actions 的 OIDC 身份，**本机不存任何 npm token，因此没有会失效的凭据**：
+
+```bash
+npm version patch          # 或 minor / major
+git push && git tag v1.1.6 && git push origin v1.1.6
+```
+
+`.github/workflows/publish.yml` 会先校验 tag 与 `package.json` 版本一致、跑离线测试套件，然后发布。
+npmjs.com 上需要一次性配置：**package → Settings → Trusted Publisher → GitHub Actions**，用户
+`27painter`、仓库 `dsh-moli`、workflow 文件名 `publish.yml`，并允许 `npm publish` 动作。
+
+**不要再用本机存储的 token 发布。** 这台机器原先配的是一个绕过 2FA 的 classic token，npm 正在淘汰这类
+token；它被吊销后，发布会报：
+
+```
+E404 Not Found - PUT https://registry.npmjs.org/dsh-moli
+     The requested resource 'dsh-moli@1.1.5' could not be found or you do not have permission
+```
+
+**这看起来像"包不存在"，实际是认证失败。** 任何本地发布之前先跑
+`node scripts/preflight-publish.mjs`：它会告诉你凭据能否认证，不能时明确点出这个误导性的 404。
+
 ## 许可
 
 MIT，见 [LICENSE](LICENSE)。

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'];
@@ -65,7 +67,7 @@ const FETCH_PARAMETERS = {
     },
     eval: {
       type: 'string',
-      description: 'JavaScript expression evaluated once the page is ready; its value is returned as text or JSON instead of the page.',
+      description: 'JavaScript expression evaluated once the page is ready; its value is returned as text or JSON instead of the page. Combining it with `dump` does NOT return both: the engine discards the expression value and dumps the resulting page state instead (its own documented semantics). Use `eval` alone to read a value, or `dump` alone to read the page.',
     },
     wait: {
       type: 'string',
@@ -85,6 +87,10 @@ const FETCH_PARAMETERS = {
     resources: { type: 'boolean', description: 'Also fetch images, fonts, audio, video, and text tracks.' },
     withFrames: { type: 'boolean', description: 'Include subframes in the output.' },
     insecureTls: { type: 'boolean', description: 'Skip TLS host verification. Use only for a known-broken local endpoint.' },
+    proxy: {
+      type: 'string',
+      description: 'Forward proxy for this call, e.g. "http://127.0.0.1:7890". Overrides the plugin configuration for one call; loopback URLs always bypass it.',
+    },
     profileDir: { type: 'string', description: 'Moli profile directory carrying imported cookies or storage.' },
     cookieFile: { type: 'string', description: 'Netscape/curl cookie-jar file to send.' },
   },
@@ -111,6 +117,8 @@ const FETCH_OUTPUT_SCHEMA = {
     chars: { type: 'integer' },
     bytes: { type: 'integer' },
     empty: { type: 'boolean' },
+    omitted: { type: 'integer' },
+    evalFailed: { type: 'boolean' },
     truncated: { type: 'boolean' },
     error: { type: 'string' },
     hint: { type: 'string' },
@@ -132,6 +140,7 @@ const PROBE_OUTPUT_SCHEMA = {
     exe: { type: 'string' },
     version: { type: 'string' },
     httpsOk: { type: 'boolean' },
+    httpsOkScope: { type: 'string' },
     sandboxTlsBlock: { type: 'boolean' },
     revocationBlock: { type: 'boolean' },
     detail: { type: 'string' },
@@ -219,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.
  *
@@ -265,11 +419,13 @@ export function apply(ctx, config) {
           manualInstall: MANUAL_INSTALL,
         };
       }
+      // A per-call proxy wins over the plugin configuration, so one host behind a
+      // different proxy does not require a reconfiguration.
       return runFetch({
         exe,
         args: { ...args, timeoutMs: args.timeoutMs ?? defaultTimeoutMs },
         maxChars,
-        proxy,
+        proxy: typeof args.proxy === 'string' && args.proxy !== '' ? args.proxy : proxy,
         insecureTls,
       });
     },
@@ -335,6 +491,10 @@ export function apply(ctx, config) {
         exe: result.exe,
         version: result.version,
         httpsOk: result.httpsOk,
+        // Says which process the HTTPS result describes. Under the file sandbox a
+        // restricted shell cannot reach the network while this path can, so the
+        // caller should not read httpsOk as "this machine has internet".
+        httpsOkScope: result.httpsOkScope,
         sandboxTlsBlock: result.sandboxTlsBlock,
         revocationBlock: result.revocationBlock,
         detail: result.detail,
@@ -342,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'})`);
 }