dsh-moli 1.1.13 → 1.1.15

package/README.md

@@ -210,8 +210,9 @@ An unresolvable bundle is **skipped silently** apart from one stderr line
 ## Usage
 
 `moli_fetch` parameters: `url` (required), `dump`, `writeTo`, `eval`, `scroll`, `wait`,
-`waitSelector`, `delayMs`, `timeoutMs`, `maxChars`, `headers`, `userAgent`, `layout`, `scrollbars`,
-`noJs`, `noCss`, `resources`, `withFrames`, `insecureTls`, `profileDir`, `cookieFile`, `proxy`.
+`waitSelector`, `waitScript`, `waitResponseUrl`, `waitResponseJson`, `delayMs`, `timeoutMs`,
+`maxChars`, `headers`, `userAgent`, `layout`, `scrollbars`, `noJs`, `noCss`, `resources`,
+`withFrames`, `insecureTls`, `failOnHttpError`, `profileDir`, `cookieFile`, `proxy`.
 
 ```
 moli_fetch url=https://example.com dump=markdown             # token-efficient text
@@ -244,6 +245,43 @@ scrolled `dump=screenshot` shows that part of the page.
 It runs as part of the engine's own pre-capture evaluation and therefore composes with `eval`: the
 scroll happens first, and the expression still returns its own value.
 
+### `failOnHttpError` — stop reading an error page as content
+
+By default a 404 is returned like any other page, so a failed fetch looks successful. Setting
+`failOnHttpError` turns a final status of 400 or above into `ok: false` with the status named — and
+**keeps the body**, because an error page is often the thing you need to read.
+
+```
+moli_fetch url=https://example.com/nope dump=markdown failOnHttpError=true
+```
+
+| | default | `failOnHttpError: true` |
+|---|---|---|
+| a 404 | `ok: true`, the error page as content | `ok: false`, `status: 404`, body still returned |
+| a screenshot of a 404 | written as a normal image | still written, and reported as a failure |
+
+It is off by default so existing calls keep their behaviour. A JSON dump already reported the status
+on its own; markdown and HTML dumps did not, and that is the gap this closes.
+
+### Waiting for what the page actually fetches
+
+`wait: "networkidle"` plus `delayMs` is a guess about how long a list takes to arrive. These wait for
+the request itself:
+
+```
+# the response that carries the data
+moli_fetch url=https://example.com/feed dump=markdown waitResponseUrl="/api/feed"
+
+# the payload, when the URL is not distinctive
+moli_fetch url=https://example.com/feed dump=markdown waitResponseJson="data.list.0.id=42"
+
+# the page's own idea of readiness
+moli_fetch url=https://example.com/app dump=markdown waitScript="window.appReady === true"
+```
+
+`waitResponseJson` takes `PATH=VALUE`, where `PATH` addresses the field and `VALUE` is compared
+literally. Use these when a fixed delay either wastes time or reads the page too early.
+
 ## 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),
@@ -273,10 +311,13 @@ capabilities always visible to the model.
 2. **Binary output is copied byte for byte.** PowerShell's `>` operator re-encodes a native
    program's output as UTF-16, inserting a `00` after every byte, which corrupts a screenshot.
    Bytes here are written verbatim, so the PNG signature stays `89504e470d0a1a0a`.
-3. **No external dependencies.** A profile plugin is loaded from its real path on disk (a `link:`
+3. **One optional external dependency.** A profile plugin is loaded from its real path on disk (a `link:`
    dependency stays a symlink target), so a bare specifier such as `@deepseek-ai/schemastery`
-   resolves against the plugin directory instead of the profile's `node_modules` and the plugin
-   fails to load. This plugin imports only `node:` builtins and its own files.
+   resolves against the plugin directory instead of the profile's `node_modules`. The import is
+   therefore guarded: without schemastery (a `link:` install) the settings form does not appear and
+   the plugin degrades to plain patch-layer configuration, while `moli_fetch` and `moli_probe` keep
+   registering. With it (a normal npm install, which brings the dependency along) the settings page
+   is available.
 
 ## Platform support
 
@@ -320,6 +361,8 @@ exercised the proxy download route as well as the engine paths.
 ## Configuration
 
 Override any field under the plugin's `config` entry in the profile patch layer. All are optional.
+The same fields are also editable from the **Moli 安装与抓取** settings section on the plugin's page in
+the Plugins manager (a `plugins.bundle.config` form registered by the browser half).
 
 ```yaml
 - insert:
@@ -341,6 +384,22 @@ Without `exePath`, the plugin probes `exePath` → `MOLI_BIN` → `%LOCALAPPDATA
 `%USERPROFILE%\.local\bin\moli.exe`, then scans inside `%LOCALAPPDATA%\Moli` for a `moli.exe`, so an
 installation under a versioned subdirectory is still found.
 
+### Engine lifecycle from the settings page
+
+The settings section also carries an **engine** row that detects the installed engine and lets you
+install or uninstall it without touching the profile:
+
+- **state** — `engineState` is `installed` (with `engineVersion`), `missing`, or a short error text.
+- **install** — the form writes `engineAction: "install"`; the host downloads and runs the official
+  installer asynchronously, then reports the outcome back through `engineState` / `engineVersion`.
+- **uninstall** — `engineAction: "uninstall"` removes the engine. On Windows only the installer-owned
+  `%LOCALAPPDATA%\Moli` tree is deleted; without one, nothing is touched. On POSIX the located binary
+  is removed and the now-empty install directories are pruned.
+
+These three fields (`engineAction`, `engineState`, `engineVersion`) are part of the live Config schema;
+`engineAction` is a `none`/`install`/`uninstall` union. They are meant to be driven by the settings
+form, so prefer editing the four fields above for routine configuration.
+
 ## Known limitations
 
 - **macOS is untested, and Linux was tested by the contributor rather than the maintainer.** The
@@ -378,8 +437,14 @@ installation under a versioned subdirectory is still found.
 
 ## Verification
 
-Four suites live in [`verify/`](verify/), and all are runnable against a working tree:
+Eight suites live in [`verify/`](verify/), and all are runnable against a working tree:
 
+- `config-verify.mjs` checks the settings surface and engine lifecycle added by the plugin's browser
+  half: the volatile `Config` schema (every declared field, `engineAction` as a `none`/`install`/
+  `uninstall` union), `apply` reading both a plain config and a volatile `.get()` reference, the
+  `settings/document-updated` wiring, `uninstallMoli` (platform-aware: POSIX removes the located
+  binary, Windows removes only the installer-owned `%LOCALAPPDATA%\Moli` tree), and the client.js
+  shape (`plugins.bundle.config` registration, zh/en dictionaries, raw `true`/`false` select labels).
 - `schema-verify.mjs` checks the tool definitions with the registry's own validator, including
   controls that assert the two invalid schema shapes still fail.
 - `install-verify.mjs` drives the install pipeline against a loopback HTTP server: route ordering,
@@ -403,6 +468,13 @@ Four suites live in [`verify/`](verify/), and all are runnable against a working
   `bottom`, nonsense rejected, the caller's `eval` value preserved) and then, when an engine is
   present, fetches a page whose `scroll` handler fills a slot and asserts the content appears with
   `scroll` and the placeholder appears without it — a property of the output, not of an internal call.
+- `http-verify.mjs` asserts the parameter-to-flag mapping directly, because a parameter that never
+  reaches the engine is indistinguishable from a feature that does not work. It then fetches a 404 and
+  checks that `failOnHttpError` reports it while keeping the body, that a healthy page is unaffected,
+  and that a screenshot of an error page is still written as a valid PNG rather than decoded as text.
+  The end-to-end half needs an HTTP error from a real server: loopback is unreachable from inside this
+  sandbox — `curl.exe` times out on `127.0.0.1` while the Node host reaches it — so it uses a path
+  under `example.com` and skips when the network is away.
 
 `.github/workflows/verify.yml` runs `schema-verify`, `empty-verify` and `scroll-verify` on Linux,
 Windows and macOS (they need no engine and no network) and attempts the engine-dependent suites on
@@ -414,6 +486,12 @@ through a proxy, that proxy too. Useful where a network is available, but a suit
 because a website changed is worse than no suite, so it stays a local check. If you run it and see
 failures in sections 4–6 while sections 1–3 pass, suspect the network before the code.
 
+### Prerequisites for the suites
+
+The plugin has one optional runtime dependency — [`@deepseek-ai/schemastery`](https://www.npmjs.com/package/@deepseek-ai/schemastery) — used by the live `Config` schema that registers the settings namespace (optional because the import is guarded, so a `link:` install without it still loads and registers the tools). Suites that import the plugin (`config-verify`, `schema-verify`, `empty-verify`, `report-verify`, `http-verify`) need it resolvable from the working tree, so run `npm install` first.
+
+`schema-verify` additionally imports the registry's own validator out of the npm-global `@deepseek-ai/dsh` install (`@deepseek-ai/dsh-tools`); `report-verify` and the engine suites need a real Moli engine, and `empty-verify` needs a C compiler to build its stub engines. On Windows, `@deepseek-ai/schemastery` can be resolved through a directory junction into the fork's `node_modules` from the npm-global DSH tree, the same way the suites resolve `dsh-tools`.
+
 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
 guard for the `-t` argument position), PNG and PDF artifacts with valid signatures, truncation, every
@@ -467,6 +545,21 @@ 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.
 
+### Deprecating a version: do it on the website
+
+Publishing is scripted; deprecating deliberately is not. Use the package's page on npmjs.com —
+**package → Settings → Deprecate** — and name the versions and the reason.
+
+`npm deprecate dsh-moli@1.1.11 "…"` produces the same misleading failure as above when the local
+credential is dead, and there is a second reason not to reach for a token here. npm restricted
+2FA-bypass granular tokens from package-management operations on 31 July 2026, so the kind of token
+that used to make `deprecate` scriptable is being withdrawn, while `publish` has a supported
+token-free path through OIDC. A release process that needs a token only for the rare act of
+deprecating is a process that will be broken the next time it is needed, which is exactly what
+happened with 1.1.11 and 1.1.12.
+
+The 1.0.0 and 1.0.1 deprecations were done this way, from the website.
+
 ## License
 
 MIT. See [LICENSE](LICENSE).

package/README.zh.md

@@ -196,8 +196,9 @@ profile 插件需要两半都齐：依赖边（`dependencies`）+ `dsh.profile.b
 ## 用法
 
 `moli_fetch` 参数：`url`（必填）、`dump`、`writeTo`、`eval`、`scroll`、`wait`、`waitSelector`、
-`delayMs`、`timeoutMs`、`maxChars`、`headers`、`userAgent`、`layout`、`scrollbars`、`noJs`、
-`noCss`、`resources`、`withFrames`、`insecureTls`、`profileDir`、`cookieFile`、`proxy`。
+`waitScript`、`waitResponseUrl`、`waitResponseJson`、`delayMs`、`timeoutMs`、`maxChars`、`headers`、
+`userAgent`、`layout`、`scrollbars`、`noJs`、`noCss`、`resources`、`withFrames`、`insecureTls`、
+`failOnHttpError`、`profileDir`、`cookieFile`、`proxy`。
 
 ```
 moli_fetch url=https://example.com dump=markdown            # 省 token 的正文
@@ -229,6 +230,41 @@ moli_fetch url=https://example.com/feed dump=markdown scroll=-400    # 往回滚
 它作为引擎自身"抓取前求值"的一部分执行，因此与 `eval` 可组合：**先滚动，表达式再读取页面，并且仍然返回
 它自己的值**。
 
+### `failOnHttpError` —— 别再把错误页当正文读
+
+默认情况下 404 和普通页面一样被返回，于是**抓取失败看起来是成功的**。加上 `failOnHttpError` 后，最终状态码
+400 及以上会变成 `ok: false` 并报出状态码——**而且保留响应体**，因为错误页往往正是你需要读的东西。
+
+```
+moli_fetch url=https://example.com/nope dump=markdown failOnHttpError=true
+```
+
+| | 默认 | `failOnHttpError: true` |
+|---|---|---|
+| 一个 404 | `ok: true`，错误页作为正文 | `ok: false`、`status: 404`，响应体仍然返回 |
+| 404 的截图 | 当普通图片写出 | 仍然写出，但报告为失败 |
+
+默认关闭，因此现有调用行为不变。JSON dump 本来就能自己报出状态码；markdown 与 HTML 不能，这个开关补的正是
+这个缺口。
+
+### 等待页面真正取回的东西
+
+`wait: "networkidle"` 加 `delayMs` 是在**猜**列表要多久才到。下面这几个等的是请求本身：
+
+```
+# 等待承载数据的那次响应
+moli_fetch url=https://example.com/feed dump=markdown waitResponseUrl="/api/feed"
+
+# URL 不够有特征时，按载荷内容等
+moli_fetch url=https://example.com/feed dump=markdown waitResponseJson="data.list.0.id=42"
+
+# 让页面用自己的方式表示"就绪"
+moli_fetch url=https://example.com/app dump=markdown waitScript="window.appReady === true"
+```
+
+`waitResponseJson` 接收 `PATH=VALUE`：`PATH` 定位字段，`VALUE` 按字面比较。当固定延时不是浪费时间就是读得太
+早时，用这几个。
+
 ## 与 Moli 官方 agent skill 的关系
 
 Moli 仓库自带官方 agent skill：[`moli-webfetch`](https://github.com/lexmount/moli/tree/main/skills/moli-webfetch)、
@@ -253,9 +289,10 @@ Moli 仓库自带官方 agent skill：[`moli-webfetch`](https://github.com/lexmo
    重定向到临时文件再读回。
 2. **二进制按原始字节落盘。** PowerShell 的 `>` 会把原生程序输出按 UTF-16 重编码（每字节后插
    `00`），截图因此损坏。这里直接写字节，PNG 签名保持 `89504e470d0a1a0a`。
-3. **零外部依赖。** profile 插件按磁盘真实路径加载（`link:` 依赖仍是符号链接目标），任何裸包名
-   导入（例如 `@deepseek-ai/schemastery`）都会解析到插件目录而非 profile 的 `node_modules`，导致
-   插件加载失败。本插件只导入 `node:` 内置模块和自己的文件。
+3. **一个可选的外部依赖。** profile 插件按磁盘真实路径加载（`link:` 依赖仍是符号链接目标），任何裸包名
+   导入（例如 `@deepseek-ai/schemastery`）都会解析到插件目录而非 profile 的 `node_modules`。因此该导入
+   是**受保护的**：没有 schemastery（`link:` 安装）时设置界面不出现、插件退化为纯补丁层配置，而
+   `moli_fetch` 与 `moli_probe` 照常注册；有它（普通 npm 安装会自动带上）时设置页面可用。
 
 ## 平台支持
 
@@ -292,7 +329,7 @@ cookie 驱动的查询参数。那次实测同时覆盖了代理下载路由与
 
 ## 配置
 
-在 profile 的补丁层里覆盖 `config`，全部可选：
+在 profile 的补丁层里覆盖 `config`，全部可选。也可以在图 **Moli 设置** 界面里编辑（见下方「设置页入口」）。
 
 ```yaml
 - insert:
@@ -313,6 +350,32 @@ profile。无论生效的是哪个代理，loopback 地址一律绕过它。
 → `%USERPROFILE%\.local\bin\moli.exe`，随后还会在 `%LOCALAPPDATA%\Moli` 内递归查找 `moli.exe`，
 所以装在带版本号的子目录里也能找到。
 
+### 设置页入口
+
+插件自带一个**设置界面**，挂在插件管理页的对应插件条目上（`plugins.bundle.config` 槽位，由浏览器端
+`client.js` 注册）。两种方式进入：
+
+1. **插件管理页**：打开 DSH Web 界面的插件管理页，找到 **dsh-moli** 条目，其配置区即是本设置界面；
+   引擎状态、安装/卸载按钮、以及下方所有配置字段都在这里编辑。
+2. **直接改 profile**：按上面的 YAML 改 `cordis.patch.yml` 同样生效，两边是同一份 `config`，保存即同步。
+
+设置界面跟随 DSH 当前语言（内置 `zh` / `en`，英语兜底），布尔字段（如 `insecureTls`）以下拉选择
+**原始值**（`true` / `false`）显示，不做本地化翻译。
+
+### 引擎生命周期（设置页的「引擎」行）
+
+设置界面顶部有一条**引擎**状态行，自动检测已安装的引擎，并可一键安装/卸载，无需动 profile：
+
+- **状态** — `engineState` 为 `installed`（同时给出 `engineVersion`）、`missing`，或一段简短错误文本。
+- **安装** — 点「安装引擎」后表单写入 `engineAction: "install"`，主机异步下载并运行官方安装器，
+  完成后通过 `engineState` / `engineVersion` 回写结果。
+- **卸载** — 「卸载引擎」写入 `engineAction: "uninstall"`。Windows 上只删除安装器所属的
+  `%LOCALAPPDATA%\Moli` 目录树；没有该目录树时**不触碰任何文件**。POSIX 上删除定位到的二进制，
+  并清理随之变空的安装目录。
+
+`engineAction` / `engineState` / `engineVersion` 三个字段属于动态 Config schema（`engineAction` 是
+`none` / `install` / `uninstall` 三选一），设计上由设置界面驱动；日常改配置请优先用上面的四个字段。
+
 ## 已知限制
 
 - **macOS 未经验证，Linux 是由贡献者而非维护者验证的。** 维护者是一名**没有 macOS / Linux 电脑**的
@@ -340,8 +403,13 @@ profile。无论生效的是哪个代理，loopback 地址一律绕过它。
 
 ## 验证情况
 
-[`verify/`](verify/) 下有四个可直接对工作区运行的测试：
+[`verify/`](verify/) 下有八个可直接对工作区运行的测试：
 
+- `config-verify.mjs` 检查设置面与引擎生命周期：动态 `Config` schema（每个已声明字段、`engineAction`
+  为 `none`/`install`/`uninstall` 三选一）、`apply` 同时接受普通配置与动态 `.get()` 引用、
+  `settings/document-updated` 接线、`uninstallMoli`（平台感知：POSIX 删除定位到的二进制，Windows
+  只删除安装器所属的 `%LOCALAPPDATA%\Moli` 目录树）、以及 client.js 的形状（`plugins.bundle.config`
+  注册、zh/en 词典、`true`/`false` 下拉显示原始值）。
 - `schema-verify.mjs` 用注册表自己的校验器检查工具定义，并带有断言"两种非法 schema 形状仍会被拒"的对照组。
 - `install-verify.mjs` 用本地回环 HTTP 服务器驱动安装链路：路由顺序、被提供字节的 SHA256、校验不匹配时
   拒绝执行、匹配时真正执行、以及全部路径失败的诊断。
@@ -358,10 +426,27 @@ profile。无论生效的是哪个代理，loopback 地址一律绕过它。
 - `scroll-verify.mjs` 在无引擎时校验表达式构造（像素值、负数、`top`、`bottom`、无效输入被拒、调用方的 `eval`
   值被保留），有引擎时抓取一个"滚动处理器填充槽位"的页面，断言带 `scroll` 时内容出现、不带时只有占位符——
   断言的是**输出**的性质，而不是内部调用。
+- `http-verify.mjs` 直接断言"参数 → 引擎选项"的映射，因为**参数没送到引擎和功能不生效，从外面看是一样的**。
+  随后抓一个 404，验证 `failOnHttpError` 会报告失败同时保留响应体、健康页面不受影响、以及错误页的截图仍然被
+  写为合法 PNG 而不是被当文本解码。端到端部分需要一个真实服务器的 HTTP 错误：**本沙箱内无法访问 loopback**
+  ——`curl.exe` 连 `127.0.0.1` 会超时，而 Node 宿主进程可以——所以它用 `example.com` 下的一个路径，网络不可用
+  时跳过。
 
-`.github/workflows/verify.yml` 在 Linux、Windows、macOS 上跑 `schema-verify`、`empty-verify` 与
-`scroll-verify`（无需引擎、无需网络），在 Linux 与 Windows 上尝试依赖引擎的几套；若 runner 上没有引擎，
-则报告为跳过而不是失败。
+### 测试前置条件
+
+插件有一个可选的运行期依赖——[`@deepseek-ai/schemastery`](https://www.npmjs.com/package/@deepseek-ai/schemastery)，
+由动态 `Config` schema（注册设置命名空间的那份）使用。凡是 import 插件本体的套件（`config-verify`、
+`schema-verify`、`empty-verify`、`report-verify`、`http-verify`）都需要它能从工作区解析，所以先跑
+`npm install`。
+
+`schema-verify` 额外需要从 npm 全局安装的 `@deepseek-ai/dsh` 里 import 注册表自己的校验器
+（`@deepseek-ai/dsh-tools`）；`report-verify` 与引擎类套件需要真实 Moli 引擎，`empty-verify` 需要
+C 编译器来构建它的桩引擎。在 Windows 上，`@deepseek-ai/schemastery` 可以通过目录 junction 指到
+npm 全局 DSH 树来解析（与套件解析 `dsh-tools` 的方式相同）。
+
+`.github/workflows/verify.yml` 在 Linux、Windows、macOS 上跑 `schema-verify`、`empty-verify`、
+`scroll-verify` 与 `http-verify`（无需引擎、无需网络），在 Linux 与 Windows 上尝试依赖引擎的几套；
+若 runner 上没有引擎，则报告为跳过而不是失败。
 
 `report-verify.mjs` **故意不放进 CI**：其中三项会抓 `example.com`，还有一项抓一个具体的论坛帖子，因此它
 需要能上外网——如果这台机器的流量走代理，还需要那个代理可用。有网络时它是有用的，但**一个因为网站改版就变
@@ -414,6 +499,19 @@ E404 Not Found - PUT https://registry.npmjs.org/dsh-moli
 **这看起来像"包不存在"，实际是认证失败。** 任何本地发布之前先跑
 `node scripts/preflight-publish.mjs`：它会告诉你凭据能否认证，不能时明确点出这个误导性的 404。
 
+### 废弃某个版本：去网站操作，别用命令行
+
+发布是脚本化的，**废弃则刻意不做成脚本**。用 npmjs.com 上的包页面——**package → Settings →
+Deprecate**——选版本、写理由。
+
+`npm deprecate dsh-moli@1.1.11 "…"` 在本机凭据失效时会给出上面那个同样误导的失败，而且这里还有第二个
+理由不要依赖 token：npm 在 **2026 年 7 月 31 日**起禁止 2FA-bypass 类型的 granular token 执行**包管理**
+操作，也就是说"以前能让 `deprecate` 脚本化"的那类凭据正在被取消；而 `publish` 有受支持的、免 token 的
+OIDC 路径。**一个只在"偶尔废弃版本"时才需要 token 的流程，注定在下次需要它时是坏的**——1.1.11 与 1.1.12
+遇到的正是这种情况。
+
+1.0.0 与 1.0.1 的废弃就是通过网站完成的。
+
 ## 许可
 
 MIT，见 [LICENSE](LICENSE)。

package/client.js

@@ -0,0 +1,347 @@
+/**
+ * dsh-moli — browser half.
+ *
+ * Settings section (Moli install & fetch): the plugin's configuration —
+ * engine lifecycle (install / uninstall), forward proxy, per-call timeout,
+ * inline truncation budget, the TLS no-verify switch, and the engine path —
+ * edited on the plugin's page in the Plugins manager.
+ *
+ * Hand-written ModuleLoader bundle — no build step required.
+ */
+window.__ModuleLoader__.load({
+  id: "dsh-moli",
+  factory: (require) => {
+    var module = { exports: {} };
+    var exports = module.exports;
+    Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+    var react = require("react");
+    var h = react.createElement;
+
+    // ── CSS (theme tokens, same vocabulary as dsh-soul-md) ────────────────
+    var CSS = ".__moli_root{max-width:640px;display:flex;flex-direction:column;gap:10px}" +
+      ".__moli_field{display:flex;flex-direction:column;gap:4px}" +
+      ".__moli_label{font-size:12px;font-weight:600;color:var(--dsw-alias-label-primary);display:flex;align-items:center;gap:6px}" +
+      ".__moli_hint{font-size:11px;color:var(--dsw-alias-label-tertiary)}" +
+      ".__moli_input{border:1px solid var(--dsw-alias-border-l2);background:var(--dsw-alias-bg-layer-3);font:inherit;color:var(--dsw-alias-label-primary);border-radius:8px;padding:6px 10px;font-size:13px;box-sizing:border-box;width:100%}" +
+      ".__moli_actions{display:flex;gap:8px;align-items:center;margin-top:4px}" +
+      ".__moli_btn{border:1px solid var(--dsw-alias-border-l2);background:var(--dsw-alias-bg-layer-3);color:var(--dsw-alias-label-primary);border-radius:8px;padding:6px 14px;font:inherit;font-size:13px;cursor:pointer}" +
+      ".__moli_btn:hover:not(:disabled){border-color:var(--dsw-alias-state-business-primary)}" +
+      ".__moli_btn:disabled{opacity:.5;cursor:default}" +
+      ".__moli_btnPrimary{border-color:var(--dsw-alias-state-business-primary, #3964fe);background:var(--dsw-alias-state-business-primary, #3964fe);color:#fff}" +
+      ".__moli_btnDanger{border-color:var(--dsw-alias-state-error-primary, #f85149);color:var(--dsw-alias-state-error-primary, #f85149)}" +
+      ".__moli_status{font-size:12px;color:var(--dsw-alias-label-tertiary)}" +
+      ".__moli_error{font-size:12px;color:var(--dsw-alias-state-error-primary)}" +
+      ".__moli_unavailable{font-size:13px;color:var(--dsw-alias-label-tertiary)}" +
+      ".__moli_group{border:1px solid var(--dsw-alias-border-l2);border-radius:10px;padding:10px 12px;display:flex;flex-direction:column;gap:8px}" +
+      ".__moli_engineRow{display:flex;align-items:center;gap:8px;flex-wrap:wrap}" +
+      ".__moli_engineState{font-size:13px;color:var(--dsw-alias-label-primary);font-weight:600}" +
+      ".__moli_engineDetail{font-size:11px;color:var(--dsw-alias-label-tertiary)}";
+    if (typeof document !== "undefined") {
+      var style = document.createElement("style");
+      style.textContent = CSS;
+      style.setAttribute("data-dsh-moli", "");
+      if (!document.head.querySelector("style[data-dsh-moli]")) document.head.appendChild(style);
+    }
+
+    // ── locale ────────────────────────────────────────────────────────────
+    var zh = {
+      nav: "Moli 设置",
+      sectionTitle: "Moli 安装与抓取",
+      unavailable: "配置不可用（可能当前 profile 未启用本插件）。",
+      loading: "正在读取配置…",
+      saved: "已保存。",
+      save: "保存",
+      error: "保存失败",
+      notApplied: "写入被宿主拒绝，表单已按宿主实际状态刷新。",
+      engineSection: "引擎",
+      engineInstalled: "已安装",
+      engineMissing: "未安装",
+      engineUnknown: "检测中…",
+      engineWorking: "正在处理…",
+      engineActionInstall: "安装引擎",
+      engineActionUninstall: "卸载引擎",
+      engineVersion: "版本 {version}",
+      engineInstallHint: "未检测到 Moli 引擎。点击「安装引擎」下载官方安装器并运行（需联网，可能耗时数分钟）。",
+      engineUninstallHint: "点击「卸载引擎」将删除本机安装的 Moli 二进制。",
+      fieldProxy: "转发代理",
+      hintProxy: '每次调用的代理覆盖项；留空表示直连。例如 "http://127.0.0.1:7890"。回环地址总是绕过代理。',
+      fieldDefaultTimeoutMs: "默认超时（毫秒）",
+      hintDefaultTimeoutMs: "单次调用默认超时，默认 30000（30 秒）。",
+      fieldMaxChars: "内联文本截断（字符）",
+      hintMaxChars: "内联文本最多返回的字符数，默认 200000；超出时保留头尾并注明省略量，传 writeTo 可保留全文。",
+      fieldInsecureTls: "跳过 TLS 验证（insecureTls）",
+      hintInsecureTls: '本网络证书吊销应答不可达时，GitHub 等 HTTPS 主机可能报错；开启后透传 moli 的 no-verify 标志。默认开启。',
+      fieldExePath: "引擎路径（exePath）",
+      hintExePath: "可选。指定 moli 可执行文件的绝对路径；留空则自动在常见安装位置查找。",
+      placeholderProxy: "http://127.0.0.1:7890",
+      placeholderExePath: "/home/user/.local/bin/moli",
+    };
+    var en = {
+      nav: "Moli settings",
+      sectionTitle: "Moli install & fetch",
+      unavailable: "Configuration unavailable (this profile may not enable the plugin).",
+      loading: "Loading configuration…",
+      saved: "Saved.",
+      save: "Save",
+      error: "Save failed",
+      notApplied: "The write was refused by the host; the form was reloaded to what the host actually holds.",
+      engineSection: "Engine",
+      engineInstalled: "Installed",
+      engineMissing: "Not installed",
+      engineUnknown: "Detecting…",
+      engineWorking: "Working…",
+      engineActionInstall: "Install engine",
+      engineActionUninstall: "Uninstall engine",
+      engineVersion: "version {version}",
+      engineInstallHint: "No Moli engine found. Click “Install engine” to download and run the official installer (needs network; may take a few minutes).",
+      engineUninstallHint: "Click “Uninstall engine” to remove the locally installed Moli binary.",
+      fieldProxy: "Forward proxy",
+      hintProxy: 'Per-call proxy override; leave empty for direct. E.g. "http://127.0.0.1:7890". Loopback URLs always bypass it.',
+      fieldDefaultTimeoutMs: "Default timeout (ms)",
+      hintDefaultTimeoutMs: "Per-call default timeout; 30000 (30 s) by default.",
+      fieldMaxChars: "Inline truncation budget (chars)",
+      hintMaxChars: "Max characters returned inline; 200000 by default. Beyond it the head and tail are kept with an omitted-count note; pass writeTo to keep everything.",
+      fieldInsecureTls: "Skip TLS verification (insecureTls)",
+      hintInsecureTls: "When this network's CRL/OCSP responder is unreachable, HTTPS hosts like GitHub fail; enabling passes moli's no-verify flag. On by default.",
+      fieldExePath: "Engine path (exePath)",
+      hintExePath: "Optional. Absolute path to the moli executable; leave empty to search the usual install locations.",
+      placeholderProxy: "http://127.0.0.1:7890",
+      placeholderExePath: "/home/user/.local/bin/moli",
+    };
+
+    // ── write helper (same contract as dsh-soul-md) ───────────────────────
+    function settingsOpsApplied(snapshot, ops) {
+      var v = snapshot && snapshot.status === "ready" ? snapshot.value : void 0;
+      if (v === void 0) return false;
+      return ops.every(function (op) {
+        if (op.op === "unset") return v[op.path[0]] === void 0;
+        return v[op.path[0]] === op.value;
+      });
+    }
+    function commitSettingsOps(scope, ops) {
+      if (ops.length === 0) return Promise.resolve(true);
+      var run;
+      if (typeof scope.mutate === "function") {
+        run = scope.mutate(ops, scope.getSnapshot().revision);
+      } else {
+        run = ops.reduce(function (chain, op) {
+          return chain.then(function () {
+            return op.op === "unset" ? scope.unset(op.path[0]) : scope.set(op.path[0], op.value);
+          });
+        }, Promise.resolve());
+      }
+      return Promise.resolve(run).then(function () {
+        return settingsOpsApplied(scope.getSnapshot(), ops);
+      });
+    }
+
+    // ── field descriptors ─────────────────────────────────────────────────
+    // `select` fields store booleans (single option pair); the draft holds the
+    // string option and the ops map it back to a boolean.
+    var FIELDS = [
+      { key: "proxy", label: "fieldProxy", type: "text", hint: "hintProxy", placeholder: "placeholderProxy" },
+      { key: "defaultTimeoutMs", label: "fieldDefaultTimeoutMs", type: "number", min: 1000, hint: "hintDefaultTimeoutMs" },
+      { key: "maxChars", label: "fieldMaxChars", type: "number", min: 100, hint: "hintMaxChars" },
+      { key: "insecureTls", label: "fieldInsecureTls", type: "select", options: [["true", "true"], ["false", "false"]], hint: "hintInsecureTls" },
+      { key: "exePath", label: "fieldExePath", type: "text", hint: "hintExePath", placeholder: "placeholderExePath" },
+    ];
+    function toDraft(value) {
+      var out = {};
+      for (var i = 0; i < FIELDS.length; i++) {
+        var f = FIELDS[i];
+        var v = value && value[f.key];
+        if (f.type === "number") out[f.key] = typeof v === "number" ? String(v) : "";
+        else if (f.type === "select") out[f.key] = v ? "true" : "false";
+        else out[f.key] = typeof v === "string" ? v : "";
+      }
+      return out;
+    }
+    function draftOps(draft) {
+      var ops = [];
+      for (var i = 0; i < FIELDS.length; i++) {
+        var f = FIELDS[i];
+        if (f.type === "number") {
+          var n = Number(draft[f.key]);
+          if (draft[f.key] !== "" && Number.isFinite(n)) ops.push({ op: "set", path: [f.key], value: n });
+        } else if (f.type === "select") {
+          ops.push({ op: "set", path: [f.key], value: draft[f.key] === "true" });
+        } else {
+          ops.push({ op: "set", path: [f.key], value: typeof draft[f.key] === "string" ? draft[f.key] : "" });
+        }
+      }
+      return ops;
+    }
+
+    // ── settings section ──────────────────────────────────────────────────
+    function MoliConfigSection(props) {
+      useLocale(props.locale);
+      var t = props.t;
+      var scope = props.scope;
+      var [snapshot, setSnapshot] = react.useState(function () { return scope.getSnapshot(); });
+      var ready = snapshot.status === "ready" && snapshot.value !== void 0;
+      var [draft, setDraft] = react.useState(null);
+      var [busy, setBusy] = react.useState(false);
+      var [notice, setNotice] = react.useState(null);
+      var [error, setError] = react.useState(null);
+      var writePending = react.useRef(false);
+
+      react.useEffect(function () {
+        var alive = true;
+        var sync = function () { if (alive) setSnapshot(scope.getSnapshot()); };
+        var un = typeof scope.subscribe === "function" ? scope.subscribe(sync) : null;
+        // Bound once per plugin, shared across mounts: unmount only unsubscribes,
+        // never disposes, so a later remount does not find a dead write queue.
+        return function () { alive = false; if (un) un(); };
+      }, [scope]);
+
+      if (snapshot.status === "unavailable") {
+        return h("p", { className: "__moli_unavailable" }, t("unavailable"));
+      }
+      if (!ready) return h("p", { className: "__moli_status" }, t("loading"));
+
+      var value = snapshot.value;
+      var currentDraft = draft === null ? toDraft(value) : draft;
+      var valueKey = JSON.stringify(toDraft(value));
+      var draftKey = JSON.stringify(currentDraft);
+      var dirty = valueKey !== draftKey;
+      var saving = busy;
+
+      function setField(f, v) { setNotice(null); setError(null); setDraft(function (p) { return Object.assign({}, p, { [f.key]: v }); }); }
+
+      function onSave() {
+        if (writePending.current) return;
+        writePending.current = true;
+        setBusy(true); setNotice(null); setError(null);
+        commitSettingsOps(scope, draftOps(currentDraft)).then(function (ok) {
+          writePending.current = false;
+          setBusy(false);
+          setSnapshot(scope.getSnapshot());
+          if (!ok) { setError(t("notApplied")); return; }
+          setNotice(t("saved"));
+          setDraft(null);
+        }).catch(function (e) {
+          writePending.current = false;
+          setBusy(false);
+          setSnapshot(scope.getSnapshot());
+          setError(String(e && e.message || e));
+        });
+      }
+
+      // Engine lifecycle: the Host reacts to `engineAction` and reports back
+      // through `engineState` / `engineVersion`. While the action is pending the
+      // form shows "working…"; scope updates (including the reset to `none`)
+      // drive the display back to the resulting state.
+      var engineState = typeof value.engineState === "string" ? value.engineState : "unknown";
+      var engineVersion = typeof value.engineVersion === "string" ? value.engineVersion : "";
+      var engineAction = typeof value.engineAction === "string" ? value.engineAction : "none";
+      var engineWorking = engineAction !== "none";
+      var engineLabel = engineWorking ? t("engineWorking")
+        : engineState === "installed" ? t("engineInstalled")
+          : engineState === "missing" ? t("engineMissing")
+            : t("engineUnknown");
+
+      function onEngineAction(action) {
+        if (engineWorking) return;
+        if (action === "uninstall" && !window.confirm(t("engineUninstallHint"))) return;
+        setNotice(null); setError(null);
+        commitSettingsOps(scope, [{ op: "set", path: ["engineAction"], value: action }]).then(function (ok) {
+          setSnapshot(scope.getSnapshot());
+          if (!ok) setError(t("notApplied"));
+        }).catch(function (e) {
+          setSnapshot(scope.getSnapshot());
+          setError(String(e && e.message || e));
+        });
+      }
+
+      return h("div", { className: "__moli_root" },
+        // Engine lifecycle group.
+        h("div", { className: "__moli_group" },
+          h("div", { className: "__moli_label" }, t("engineSection")),
+          h("div", { className: "__moli_engineRow" },
+            h("span", { className: "__moli_engineState" }, engineLabel),
+            engineVersion && engineState === "installed"
+              ? h("span", { className: "__moli_engineDetail" }, t("engineVersion").replace("{version}", engineVersion))
+              : null,
+          ),
+          engineState !== "installed" && !engineWorking
+            ? h("span", { className: "__moli_engineDetail" }, t("engineInstallHint"))
+            : engineState === "installed" && !engineWorking
+              ? h("span", { className: "__moli_engineDetail" }, t("engineUninstallHint"))
+              : null,
+          h("div", { className: "__moli_actions" },
+            engineState === "installed"
+              ? h("button", { className: "__moli_btn __moli_btnDanger", disabled: engineWorking, onClick: function () { onEngineAction("uninstall"); } }, t("engineActionUninstall"))
+              : h("button", { className: "__moli_btn __moli_btnPrimary", disabled: engineWorking, onClick: function () { onEngineAction("install"); } }, t("engineActionInstall")),
+          ),
+        ),
+        // Configuration fields group.
+        h("div", { className: "__moli_group" },
+          FIELDS.map(function (f) {
+            if (f.type === "select") {
+              return h("label", { key: f.key, className: "__moli_field" },
+                h("span", { className: "__moli_label" }, t(f.label)),
+                h("select", {
+                  className: "__moli_input",
+                  value: currentDraft[f.key],
+                  onChange: function (e) { setField(f, e.target.value); },
+                }, f.options.map(function (o) {
+                  // Option labels are the raw stored values ("true"/"false"),
+                  // never translated; only the field label and hint are locale-bound.
+                  return h("option", { key: o[0], value: o[0] }, o[1]);
+                })),
+                f.hint ? h("span", { className: "__moli_hint" }, t(f.hint)) : null,
+              );
+            }
+            return h("label", { key: f.key, className: "__moli_field" },
+              h("span", { className: "__moli_label" }, t(f.label)),
+              h("input", {
+                className: "__moli_input",
+                type: f.type === "number" ? "number" : "text",
+                min: f.min,
+                value: currentDraft[f.key],
+                placeholder: f.placeholder ? t(f.placeholder) : void 0,
+                onChange: function (e) { setField(f, e.target.value); },
+              }),
+              f.hint ? h("span", { className: "__moli_hint" }, t(f.hint)) : null,
+            );
+          }),
+          h("div", { className: "__moli_actions" },
+            h("button", { className: "__moli_btn __moli_btnPrimary", disabled: saving || !dirty, onClick: onSave }, t("save")),
+            notice ? h("span", { className: "__moli_status" }, notice) : null,
+            error ? h("span", { className: "__moli_error" }, error) : null,
+          ),
+        ),
+      );
+    }
+
+    var NS = "dsh-moli";
+
+    // Keep the section re-rendering when the active locale changes.
+    function useLocale(locale) {
+      var refresh = react.useState(0)[1];
+      react.useEffect(function () {
+        if (!locale || typeof locale.subscribe !== "function") return;
+        return locale.subscribe(function () { refresh(function (revision) { return revision + 1; }); });
+      }, [locale]);
+    }
+
+    function apply(ctx) {
+      var t = ctx.locale.bind(NS);
+      ctx.effect(function () { return ctx.locale.register(NS, { zh: zh, en: en }); }, "dsh-moli: dictionaries");
+      var scope = ctx.configForms.get("dsh-moli");
+      ctx.slots.inject("plugins.bundle.config", function () {
+        return ctx.slots.register({
+          name: "plugins.bundle.config",
+          key: "dsh-moli",
+          locale: NS
+        }, function (props) {
+          return h(MoliConfigSection, Object.assign({}, props, { scope: scope, t: t, locale: ctx.locale }));
+        });
+      });
+    }
+
+    exports.apply = apply;
+    exports.inject = ["slots", "locale", "configForms"];
+    return module.exports;
+  }
+});

package/index.js

@@ -1,19 +1,27 @@
 /** Host half of dsh-moli: expose the local `moli` headless browser as callable tools. */
-import { MANUAL_INSTALL, installMoli } from './lib/install.js';
-import { findMoli, moliCandidates, probe, runFetch } from './lib/moli.js';
+import { MANUAL_INSTALL, installMoli, uninstallMoli } from './lib/install.js';
+import { findMoli, moliCandidates, moliVersion, probe, runFetch } from './lib/moli.js';
 
 export const name = 'dsh-moli';
 export const inject = ['tools'];
 
 /**
- * This plugin deliberately imports nothing but `node:` builtins and its own
- * files. A profile plugin is loaded from its real path on disk (a `link:`
- * dependency stays a symlink target), so a bare specifier such as
- * `@deepseek-ai/schemastery` would resolve against the plugin directory
- * instead of the profile's `node_modules` and fail to load. The registry
- * validates parameters and results itself, so `defineTool` and a Schema-based
- * config are not needed; configuration is read defensively from the patch layer.
+ * `@deepseek-ai/schemastery` powers the live Config schema and therefore the
+ * settings namespace. A profile plugin is loaded from its real path on disk (a
+ * `link:` dependency stays a symlink target), so a bare specifier must resolve
+ * against the plugin's own `node_modules` chain — which does not exist when the
+ * plugin is installed as a `link:`/junction (the README's first install route).
+ * The import is therefore optional: without schemastery the settings form does
+ * not appear and the plugin degrades to plain patch-layer configuration, while
+ * `moli_fetch` / `moli_probe` keep registering — those are the plugin's reason
+ * to exist, and losing them would be worse than losing the form.
  */
+let z;
+try {
+  z = (await import('@deepseek-ai/schemastery')).default;
+} catch {
+  z = undefined;
+}
 
 /** Deployment configuration defaults; override via the plugin's `config` entry. */
 const DEFAULTS = {
@@ -27,6 +35,35 @@ const DEFAULTS = {
   insecureTls: true,
 };
 
+/**
+ * Live Config schema. Declaring it (and exporting it) makes DSH register the
+ * `dsh-moli` settings namespace, which the browser half's `plugins.bundle.config`
+ * form edits. `.volatile()` marks the whole object live so the namespace appears
+ * in the settings describe mirror and the form's writes are applied via the
+ * ConfigEditor / volatile HMR path.
+ *
+ * `undefined` when `@deepseek-ai/schemastery` cannot be resolved (a `link:`
+ * install) — then no settings namespace is registered and the engine lifecycle
+ * is skipped, but the tools still register.
+ */
+export const Config = z
+  ? z.object({
+    defaultTimeoutMs: z.number().default(DEFAULTS.defaultTimeoutMs),
+    maxChars: z.number().default(DEFAULTS.maxChars),
+    insecureTls: z.boolean().default(DEFAULTS.insecureTls),
+    proxy: z.string().default(''),
+    exePath: z.string().default(''),
+    // Engine lifecycle, driven by the settings form. The form writes an action
+    // (`install` / `uninstall`) and the Host executes it asynchronously, then
+    // reports the outcome back through `engineState` / `engineVersion` and resets
+    // `engineAction` to `none`. `engineState` is `installed`, `missing`, or a
+    // short error text.
+    engineAction: z.union([z.const('none'), z.const('install'), z.const('uninstall')]).default('none'),
+    engineState: z.string().default('unknown'),
+    engineVersion: z.string().default(''),
+  }).volatile()
+  : undefined;
+
 /**
  * Parameter schema of `moli_fetch`.
  *
@@ -77,6 +114,22 @@ const FETCH_PARAMETERS = {
       description: 'Readiness stage to wait for. Defaults to `done`.',
     },
     waitSelector: { type: 'string', description: 'Wait until this CSS selector matches.' },
+    waitScript: {
+      type: 'string',
+      description: 'Wait until this JavaScript expression is truthy; a function result is called as the predicate on each poll. More precise than a fixed delay when the page signals readiness in its own terms.',
+    },
+    waitResponseUrl: {
+      type: 'string',
+      description: 'Wait for a response whose original or final URL contains this substring. This is the reliable way to await an AJAX-built list: `wait: "networkidle"` plus a delay is a guess, whereas this waits for the request that actually carries the data.',
+    },
+    waitResponseJson: {
+      type: 'string',
+      description: 'Wait for a response whose JSON field equals a value, written as PATH=VALUE (for example "data.list.0.id=42"). The counterpart to waitResponseUrl when the condition is in the payload rather than the URL.',
+    },
+    failOnHttpError: {
+      type: 'boolean',
+      description: 'Treat a final main-document HTTP status of 400 or above as a failure. Without it an error page comes back as ordinary content and a 404 reads like a successful fetch; with it the result is ok:false and reports the status, while still carrying the rendered body so the error page can be read. Off by default, so existing calls keep their behaviour.',
+    },
     delayMs: { type: 'integer', description: 'Extra milliseconds to wait after readiness.' },
     timeoutMs: { type: 'integer', description: 'Total readiness deadline in milliseconds. Defaults to the plugin configuration.' },
     maxChars: { type: 'integer', description: 'Truncate inline text output to this many characters. Defaults to the plugin configuration.' },
@@ -125,6 +178,7 @@ const FETCH_OUTPUT_SCHEMA = {
     error: { type: 'string' },
     hint: { type: 'string' },
     status: { type: 'integer' },
+    httpError: { type: 'boolean' },
     sandboxTlsBlock: { type: 'boolean' },
     unreachable: { type: 'boolean' },
     possiblyUnreachable: { type: 'boolean' },
@@ -172,6 +226,14 @@ function renderFetch(_args, value) {
     if (value.unreachable === true) lines.push('Cause: the host did not answer; a local forward proxy is the usual fix on this network.');
     else if (value.possiblyUnreachable === true) lines.push('Cause: the host did not answer in time; it may be blocked, or the page may simply be slow.');
     if (typeof value.hint === 'string' && value.hint !== '') lines.push(`Next: ${value.hint}`);
+    // An HTTP error keeps its body under `failOnHttpError`. Reporting the failure
+    // without the body would throw away the error page, which is the part worth
+    // reading -- and for a binary dump the body is the file that was written.
+    if (value.kind === 'binary' && typeof value.path === 'string') {
+      lines.push(`The error page was still written to ${value.path} (${String(value.bytes)} bytes).`);
+    } else if (typeof value.content === 'string' && value.content !== '') {
+      lines.push('', 'The server\'s response body:', '', value.content);
+    }
     return [{ type: 'text', text: lines.join('\n') }];
   }
   if (value.kind === 'binary') {
@@ -240,7 +302,10 @@ function renderProbe(_args, value) {
  * @param config - deployment configuration for paths, timeout, and output size.
  */
 export function apply(ctx, config) {
-  const options = config ?? {};
+  // The Config schema is declared volatile, so DSH hands it as a live reference
+  // whose `.get()` reads the current values; a deployment that mounts an older
+  // loader without volatile wiring passes a plain object instead. Read either.
+  const options = typeof config?.get === 'function' ? config.get() : (config ?? {});
   // Mutable: a successful install resolves a path this process can use at once,
   // without waiting for a restart to re-run discovery.
   let cachedExe = findMoli(options.exePath);
@@ -359,5 +424,167 @@ export function apply(ctx, config) {
     },
   });
 
+  // ── engine lifecycle via the settings form ─────────────────────────────
+  // The browser half's `plugins.bundle.config` form drives install/uninstall
+  // through the `engineAction` field and reads the outcome from
+  // `engineState`/`engineVersion`. State is written back only when it changes,
+  // and a finished action always resets `engineAction` to `none`, so the
+  // resulting `settings/document-updated` re-entry lands in the plain sync
+  // branch instead of looping the action.
+  //
+  // Everything here depends on the settings namespace, which exists only when
+  // schemastery resolved (see the `Config` export): without it there is no form
+  // to drive the lifecycle, so the whole block is skipped and the plugin is
+  // pure tool registration.
+  if (Config) {
+  const NS = 'dsh-moli';
+  let engineBusy = false;
+  const currentConfig = () => (typeof config.get === 'function' ? config.get() : (config ?? {}));
+  // Write settings outside the current HMR transaction. `settings.update`
+  // routes through dsh-hmr's runExclusive, which rejects when it is called
+  // from inside an active transaction — the settings/document-updated event
+  // handler runs in one, so a direct update throws
+  // "HMR transactions cannot be nested" and the write-back is silently lost
+  // (the form then stays on "working…" forever). setImmediate defers the
+  // update until the event transaction has exited.
+  const writeSettings = (settings, patch) =>
+    new Promise((resolve, reject) => {
+      setImmediate(() => {
+        settings.update(NS, patch).then(resolve, reject);
+      });
+    });
+  const syncEngineState = async (settings, current) => {
+    const exe = findMoli(current.exePath);
+    const state = exe === undefined ? 'missing' : 'installed';
+    const version = exe === undefined ? '' : (moliVersion(exe) ?? '');
+    if (current.engineState === state && current.engineVersion === version) return;
+    try {
+      await writeSettings(settings, { engineState: state, engineVersion: version });
+    } catch (error) {
+      console.error(`[dsh-moli] engine-state sync failed: ${String(error?.message ?? error)}`);
+      ctx.logger?.warn?.('dsh-moli: engine-state sync failed', String(error?.message ?? error));
+    }
+  };
+  const runEngineAction = async (settings, current, action) => {
+    if (engineBusy) return;
+    engineBusy = true;
+    try {
+      if (action === 'install') {
+        const outcome = await installMoli({
+          exePath: current.exePath,
+          timeoutMs: 180000,
+          proxy: current.proxy,
+          locate: findMoli,
+          candidates: moliCandidates(current.exePath),
+        });
+        cachedExe = outcome.ok === true ? (outcome.exe ?? cachedExe) : cachedExe;
+        await writeSettings(settings, {
+          engineAction: 'none',
+          engineState: outcome.ok === true ? 'installed' : `install failed: ${String(outcome.error ?? 'unknown error').slice(0, 200)}`,
+          engineVersion: outcome.ok === true ? String(outcome.version ?? '') : '',
+        });
+      } else if (action === 'uninstall') {
+        const removed = uninstallMoli(current.exePath);
+        cachedExe = undefined;
+        await writeSettings(settings, {
+          engineAction: 'none',
+          engineState: removed === undefined ? 'uninstall failed: nothing to remove' : 'missing',
+          engineVersion: '',
+        });
+      }
+    } catch (error) {
+      // console (not ctx.logger) so the failure reaches the service journal
+      console.error(`[dsh-moli] engine action failed: ${String(error?.message ?? error)}`);
+      ctx.logger?.error?.('dsh-moli: engine action failed', String(error?.message ?? error));
+      try {
+        await writeSettings(settings, {
+          engineAction: 'none',
+          engineState: `action failed: ${String(error?.message ?? error).slice(0, 200)}`,
+        });
+      } catch (error2) {
+        console.error(`[dsh-moli] engine action failure report could not be written back: ${String(error2?.message ?? error2)}`);
+        ctx.logger?.error?.('dsh-moli: engine action failure report could not be written back', String(error2?.message ?? error2));
+      }
+    } finally {
+      engineBusy = false;
+    }
+  };
+  // Dispatch an engineAction if one is pending, otherwise sync state. Shared by
+  // the settings update handler and the boot-time initial sync, so an action
+  // whose `settings/document-updated` event was lost (a crash between the
+  // form's write and the handler) is still picked up on the next boot instead
+  // of leaving the form stuck on "processing".
+  // The event fires inside a dsh-hmr transaction. That transaction propagates
+  // through AsyncLocalStorage into anything the handler spawns — including
+  // setTimeout/setImmediate callbacks — so a deferred settings.update still
+  // nests and is rejected ("HMR transactions cannot be nested"). dsh-hmr
+  // itself escapes its own transaction with `executing.exit(...)` (watchConfig
+  // does this); running the dispatch through the same exit clears the ALS
+  // store so the write-back opens its own outermost transaction. The poller
+  // below stays as a defensive fallback (exit missing, or an event lost
+  // between the form's write and the handler).
+  const dispatchOutsideTransaction = (settings) => {
+    const hmr = ctx.get?.('hmr');
+    const run = () => {
+      const current = currentConfig();
+      const action = current.engineAction;
+      if (action === 'install' || action === 'uninstall') void runEngineAction(settings, current, action);
+      else void syncEngineState(settings, current);
+    };
+    if (hmr && typeof hmr.executing?.exit === 'function') {
+      hmr.executing.exit(run);
+    } else {
+      run();
+    }
+  };
+  // Actions are driven by an independent poller as a fallback, and by the
+  // transaction-escaped dispatch on the event path. A setInterval callback
+  // runs in the timer phase, outside any transaction, so the action and its
+  // write-back are safe there too.
+  let pollTimer = null;
+  let pendingCheck = false;
+  const pollCheck = () => {
+    const settings = ctx.get('settings');
+    if (!settings) return;
+    const current = currentConfig();
+    const action = current.engineAction;
+    if (action === 'install' || action === 'uninstall') {
+      void runEngineAction(settings, current, action);
+    } else {
+      void syncEngineState(settings, current);
+    }
+  };
+  ctx.on?.('settings/document-updated', (id) => {
+    if (id !== NS) return;
+    const settings = ctx.get('settings');
+    if (!settings) return;
+    pendingCheck = true;
+    dispatchOutsideTransaction(settings);
+  });
+  pollTimer = setInterval(() => {
+    if (pendingCheck) {
+      pendingCheck = false;
+      pollCheck();
+    }
+  }, 500);
+  pollTimer.unref?.();
+  // Initial state once settings is live. `ctx.get('settings')` may be null in a
+  // boot-time effect (the service mounts later), so retry briefly; the poller
+  // also picks up any pending engineAction written before the service settled.
+  let syncAttempts = 0;
+  const tryInitialSync = () => {
+    const settings = ctx.get('settings');
+    if (!settings) return false;
+    pollCheck();
+    return true;
+  };
+  if (!tryInitialSync()) {
+    const timer = setInterval(() => {
+      if (tryInitialSync() || ++syncAttempts >= 40) clearInterval(timer);
+    }, 250);
+    timer.unref?.();
+  }
+  }
+
   ctx.logger?.info?.(`dsh-moli: registered moli_fetch and moli_probe (${cachedExe ?? 'moli missing'})`);
 }

package/lib/install.js

@@ -36,10 +36,10 @@
  */
 import { spawn, spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
-import { closeSync, existsSync, mkdtempSync, openSync, readFileSync, rmSync, statSync } from 'node:fs';
+import { closeSync, existsSync, mkdtempSync, openSync, readFileSync, readdirSync, rmSync, statSync } from 'node:fs';
 import { createConnection } from 'node:net';
 import { tmpdir } from 'node:os';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
 import { findMoli } from './moli.js';
 
 /** Official installer for the latest release. */
@@ -673,7 +673,7 @@ export async function installMoli(options = {}) {
         return {
           ok: false,
           error: `installer checksum mismatch: expected ${expected}, got ${download.sha256}`,
-          sha256: download.sha256,
+          installerSha256: download.sha256,
           expectedSha256: expected,
           method: download.method,
           note: 'Refusing to execute the installer.',
@@ -759,3 +759,37 @@ export async function installMoli(options = {}) {
     rmSync(workDir, { recursive: true, force: true });
   }
 }
+
+/**
+ * Remove an installed Moli engine. Windows deletes the installer-owned
+ * `%LOCALAPPDATA%\Moli` tree; POSIX removes the located binary and prunes the
+ * install directories it sits in when they end up empty.
+ *
+ * @param override - explicit path from configuration, when set.
+ * @returns the removed path, or undefined when nothing was installed.
+ */
+export function uninstallMoli(override) {
+  const exe = findMoli(override);
+  if (exe === undefined) return undefined;
+  if (process.platform === 'win32') {
+    const root = process.env.LOCALAPPDATA ? join(process.env.LOCALAPPDATA, 'Moli') : undefined;
+    if (root !== undefined && existsSync(root)) {
+      rmSync(root, { recursive: true, force: true });
+      return root;
+    }
+    // No installer-owned tree: nothing to remove. Returning here keeps the
+    // uninstall from falling through to the POSIX branch and deleting whatever
+    // findMoli located — which could be a user-provided path or a test fixture.
+    return undefined;
+  }
+  rmSync(exe, { force: true });
+  const dir = dirname(exe);
+  for (const parent of [dir, dirname(dir)]) {
+    try {
+      if (existsSync(parent) && readdirSync(parent).length === 0) rmSync(parent, { force: true });
+    } catch {
+      // A non-empty or protected parent is fine; the binary is already gone.
+    }
+  }
+  return exe;
+}

package/lib/moli.js

@@ -31,6 +31,13 @@ const TEXT_DUMPS = new Set([undefined, 'html', 'markdown', 'json', 'semantic_tre
 /** Accepted `--wait` lifecycle stages. */
 const WAIT_STAGES = new Set(['domcontentloaded', 'load', 'networkidle', 'domstable', 'done']);
 
+/**
+ * The exit code the engine uses for "the final main-document status was >= 400".
+ * Its help states it for `--fail` and `--fail-with-body`; treating it specially is
+ * what lets an HTTP error be reported without discarding the body.
+ */
+const ENGINE_HTTP_ERROR_STATUS = 22;
+
 /** `scroll` keywords, mapped to what they mean in the page. */
 const SCROLL_TOKENS = {
   top: '0',
@@ -300,7 +307,18 @@ export function fetchOnce(options) {
  * @param args - validated tool arguments.
  * @returns the argv tail (everything after the executable).
  */
-function buildArgs(args) {
+/**
+ * Build the `moli fetch` argument vector for one call.
+ *
+ * Exported so the mapping from tool parameters to engine flags can be asserted
+ * directly. That matters more than it sounds: a parameter that silently fails to
+ * reach the engine is indistinguishable from a feature that does not work, and the
+ * only fast, deterministic way to tell them apart is to check the vector.
+ *
+ * @param args - tool arguments.
+ * @returns the argv tail (without the executable).
+ */
+export function buildArgs(args) {
   if (args.dump !== undefined && !TEXT_DUMPS.has(args.dump) && !BINARY_DUMPS.has(args.dump)) {
     throw new Error(`unsupported dump: ${String(args.dump)}`);
   }
@@ -320,6 +338,16 @@ function buildArgs(args) {
   if (evaluation !== undefined) argv.push('--eval', evaluation);
   if (args.wait !== undefined && args.wait !== '') argv.push('--wait', args.wait);
   if (args.waitSelector !== undefined && args.waitSelector !== '') argv.push('--wait-selector', args.waitSelector);
+  if (args.waitScript !== undefined && args.waitScript !== '') argv.push('--wait-script', args.waitScript);
+  // Response waits: the right way to await an AJAX list, where a fixed delay is a
+  // guess. The engine takes one of each, and a caller supplying several is asking
+  // for "any of these", which is the engine's own semantics for multiple waits.
+  if (args.waitResponseUrl !== undefined && args.waitResponseUrl !== '') argv.push('--wait-response-url', args.waitResponseUrl);
+  if (args.waitResponseJson !== undefined && args.waitResponseJson !== '') argv.push('--wait-response-json', args.waitResponseJson);
+  // The engine's own switch, but only when the caller asked for a failure to be
+  // surfaced: adding it unconditionally would turn every 404 into `ok: false` and
+  // change what existing calls do.
+  if (args.failOnHttpError === true) argv.push('--fail-with-body');
   if (args.delayMs !== undefined) argv.push('--delay-ms', String(args.delayMs));
   if (args.noJs === true) argv.push('--disable-js');
   if (args.noCss === true) argv.push('--disable-css');
@@ -413,6 +441,54 @@ export function runFetch(options) {
     };
   }
 
+  // The engine signals an HTTP error with exit code 22 and, under
+  // `--fail-with-body`, keeps whatever the output format produced. That is why the
+  // body is still here: the caller is told the fetch failed *and* gets to read what
+  // came back, which is what an error page is for.
+  //
+  // This branch is reached for binary dumps too -- a screenshot of an error page is
+  // still a screenshot -- so it must not decode stdout as text.
+  if (outcome.status === ENGINE_HTTP_ERROR_STATUS && bytes > 0) {
+    // The status is in the stderr reason. A JSON dump also carries it in the body,
+    // which is the fallback when the reason wording changes.
+    const reported = httpStatusFrom(stderr);
+    if (isBinary) {
+      const failure = ensureWritable(args.writeTo);
+      if (failure !== undefined) {
+        return { ok: false, url: args.url, httpError: true, error: failure, hint: 'Pass an absolute path in an existing directory.' };
+      }
+      writeFileSync(args.writeTo, outcome.stdout);
+      return {
+        ok: false,
+        url: args.url,
+        kind: 'binary',
+        dump: args.dump,
+        path: args.writeTo,
+        bytes,
+        httpError: true,
+        ...(reported === undefined ? {} : { status: reported }),
+        error: stderr.trim() === '' ? 'the server answered with an HTTP error status' : stderr.trim(),
+        hint: `The image the server returned was written to ${String(args.writeTo)}. Drop \`failOnHttpError\` to treat this as ordinary output.`,
+      };
+    }
+    const text = outcome.stdout.toString('utf8');
+    const status = reported
+      ?? (args.dump === 'json' && text.trimStart().startsWith('{') ? parseStatus(text) : undefined);
+    return {
+      ok: false,
+      url: args.url,
+      httpError: true,
+      ...(status === undefined ? {} : { status }),
+      error: stderr.trim() === ''
+        ? `the server answered with an HTTP error status${status === undefined ? '' : ` (${String(status)})`}`
+        : stderr.trim(),
+      content: text,
+      chars: text.length,
+      hint: 'The request reached a server and it refused. The content above is the error page as the engine rendered it, '
+        + 'so it is often worth reading. Drop `failOnHttpError` to treat this as ordinary content instead.',
+    };
+  }
+
   if (outcome.status !== 0) {
     const sandboxTls = isSandboxTlsFailure(stderr);
     // A blocked host fails at connect time ("Failed to connect" / RST) or, when
@@ -426,16 +502,24 @@ export function runFetch(options) {
     // through to the generic hint below used to tell the caller to re-check the
     // installation with moli_probe, which cannot possibly help.
     const evalFailure = args.eval !== undefined && /JavaScript evaluation failed/u.test(stderr);
+    // A binary dump that failed produced no file at all. Saying only "exited with
+    // status 1" leaves the caller to guess whether an image exists; the useful fact
+    // is that it does not, and that a text dump would have captured this page.
+    const binaryFailure = isBinary && httpStatusFrom(stderr) !== undefined;
     const hint = evalFailure
       ? 'The eval expression threw. Check that the page has reached the state you expect (`wait` or `waitSelector`), that the selector matches an element, and that the expression is valid JavaScript. The engine error names the type and position.'
-      : sandboxTls
-        ? 'The DSH file sandbox blocks Schannel client credentials, so moli cannot do TLS at low integrity. Retry the same call with sandbox_permissions "danger-full-access" (with a justification), use an http:// URL, or pass proxy to reach a local forward proxy.'
-        : possiblyUnreachable
-          ? 'The host did not answer in time. Reachability to some hosts varies on this network, so retrying may succeed; if a local forward proxy is available, setting the plugin config field `proxy` is the other option. A certificate problem would report a schannel error instead of a timeout.'
-          : 'Run moli_probe to confirm the install, then retry; use waitSelector or eval for a page that renders late.';
+      : binaryFailure
+        ? 'The engine could not render this page, so no file was written. An HTTP error still produces a body for a text dump (markdown, html or json), so ask for one of those if you need to see what the server returned.'
+        : sandboxTls
+          ? 'The DSH file sandbox blocks Schannel client credentials, so moli cannot do TLS at low integrity. Retry the same call with sandbox_permissions "danger-full-access" (with a justification), use an http:// URL, or pass proxy to reach a local forward proxy.'
+          : possiblyUnreachable
+            ? 'The host did not answer in time. Reachability to some hosts varies on this network, so retrying may succeed; if a local forward proxy is available, setting the plugin config field `proxy` is the other option. A certificate problem would report a schannel error instead of a timeout.'
+            : 'Run moli_probe to confirm the install, then retry; use waitSelector or eval for a page that renders late.';
+    const failureStatus = httpStatusFrom(stderr);
     return {
       ok: false,
       url: args.url,
+      ...(failureStatus === undefined ? {} : { status: failureStatus, httpError: true }),
       error: stderr === '' ? `moli exited with status ${String(outcome.status)} and no output` : stderr,
       sandboxTlsBlock: sandboxTls,
       unreachable,
@@ -450,6 +534,20 @@ export function runFetch(options) {
     if (failure !== undefined) {
       return { ok: false, url: args.url, error: failure, sandboxTlsBlock: false, hint: 'Pass an absolute path in an existing directory.' };
     }
+    // A binary dump produces nothing for an HTTP error: the engine exits 1 before
+    // rendering anything, unlike the text dumps which exit 22 with the body kept.
+    // Nothing is written, so say that rather than leaving an empty file behind.
+    if (outcome.status !== 0) {
+      const status = httpStatusFrom(stderr);
+      return {
+        ok: false,
+        url: args.url,
+        ...(status === undefined ? {} : { status }),
+        httpError: outcome.status === ENGINE_HTTP_ERROR_STATUS || status !== undefined,
+        error: stderr.trim() === '' ? `moli exited with status ${String(outcome.status)} before producing ${String(args.dump)} output` : stderr.trim(),
+        hint: 'The engine could not render this page, so no file was written. A text dump (markdown, html or json) still captures an HTTP error body; binary output does not.',
+      };
+    }
     writeFileSync(args.writeTo, outcome.stdout);
     return {
       ok: true,
@@ -532,6 +630,25 @@ export function runFetch(options) {
   };
 }
 
+/**
+ * Read the HTTP status out of the engine's stderr reason.
+ *
+ * The engine reports it there, in the form
+ *   `Reason: final main document returned HTTP status 404 at ...`
+ * for `--fail` and `--fail-with-body`, whatever the dump format. That makes stderr
+ * the reliable source: a JSON dump also carries the status in its body, but a
+ * markdown or HTML dump does not, and this branch has to name the status for those
+ * too. Matching narrowly keeps an unrelated number in the text from being read as a
+ * status.
+ *
+ * @param stderr - the engine's stderr text.
+ * @returns the numeric status, or undefined when it is not reported.
+ */
+function httpStatusFrom(stderr) {
+  const match = /HTTP status (\d{3})\b/u.exec(String(stderr));
+  return match === null ? undefined : Number(match[1]);
+}
+
 /**
  * Read the HTTP status out of a JSON dump without trusting its shape.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-moli",
-  "version": "1.1.13",
+  "version": "1.1.15",
   "type": "module",
   "description": "DeepSeek Harness tools for the local Moli headless browser: rendered fetches, markdown, semantic trees, screenshots, and PDFs.",
   "license": "MIT",
@@ -32,14 +32,19 @@
     "registry": "https://registry.npmjs.org",
     "access": "public"
   },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.4"
+  },
   "exports": {
     ".": "./index.js",
+    "./client": "./client.js",
     "./cordis.patch.yml": "./cordis.patch.yml",
     "./package.json": "./package.json"
   },
   "files": [
     "index.js",
     "lib",
+    "client.js",
     "cordis.patch.yml",
     "README.md",
     "README.zh.md",
@@ -48,6 +53,9 @@
   "dsh": {
     "bundle": {
       "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web"
     }
   }
 }