dsh-hitl 0.1.2 → 0.2.1

package/README.md

@@ -1,4 +1,4 @@
-# dsh-hitl · Human-in-the-loop for any tool
+# dsh-hitl · Human-in-the-loop for DeepSeek Harness
 
 [![npm version](https://img.shields.io/npm/v/dsh-hitl)](https://www.npmjs.com/package/dsh-hitl) [![license](https://img.shields.io/npm/l/dsh-hitl)](LICENSE) [![Website](https://img.shields.io/badge/Website-4c566a)](https://yunpengdon.github.io/dsh-hitl-landing/)
 
@@ -99,17 +99,19 @@ export function apply(ctx) {
 }
 ```
 
-> **Always pass `owner` (the third argument).** Mounts are state owned by the `hitl` plugin, not by yours. Without an owner, the disposer `protect()` returns is the only way to unbind — and "return a function from `apply`" is **not** a lifetime: it was measured that the mount outlives the unloaded plugin row, leaving that tool blocked forever. With `ctx`, `hitl` registers an effect on your plugin's context and the mount is released when your plugin unloads. The equivalent explicit form is to wrap it in your own effect: `ctx.effect(() => ctx.hitl.protect('bash', {...}), 'my-plugin: hitl mount')`. If a mount does linger, look at `ctx.hitl.list()` and clear it with `ctx.hitl.unprotect('bash')`, or toggle the `hitl` row off and on in the plugins page (which rebuilds the plugin's state).
+> **`owner` decides whose account this mount's revocation is filed under.** It is the calling plugin's Cordis context — normally the `ctx` your `apply` received: pass it and `hitl` files the mount's release on the calling plugin's fiber, so the mount is removed automatically when that plugin is unloaded, disabled, or reloaded. The mount itself is state owned by the `hitl` plugin, not by yours — so without an owner the disposer `protect()` returns is the only way to unbind, and "return a function from `apply`" is **not** a lifetime: it was measured that the mount outlives the unloaded plugin row, leaving that tool blocked forever. The equivalent explicit form is to wrap it in your own effect: `ctx.effect(() => ctx.hitl.protect('bash', {...}), 'my-plugin: hitl mount')`. If a mount does linger, look at `ctx.hitl.list()` and clear it with `ctx.hitl.unprotect('bash')`, or toggle the `hitl` row off and on in the plugins page (which rebuilds the plugin's state).
 
 ### 2.3 Service API
 
 | Member | Purpose |
 |---|---|
-| `protect(matcher, options?, owner?)` | Mount one tool; pass the caller's ctx as `owner` for automatic unbinding; returns a disposer |
+| `protect(matcher, options?, owner?)` | Mount one tool; returns a disposer. Pass the caller's own ctx as `owner` to file this mount's unbinding under that plugin's lifetime: the mount is removed automatically when the caller is unloaded, disabled, or reloaded. Omit it and the mount outlives its caller |
 | `unprotect(matcher)` | Remove the mounts a matcher describes; returns how many were removed |
 | `list()` | Every current mount (diagnostics) |
 | `pending()` | Every request currently waiting for a human (diagnostics) |
 
+> `owner` is optional in the signature because there is a second entry point: the rows in `config.protect` belong to the `hitl` plugin itself (they are cleared when that row unloads) and need no owner. On the `ctx.hitl.protect()` API, however, it is required in practice — omitting it is not a legal simplification but a trap.
+
 `matcher`: a tool name / a glob string containing `*` / a `RegExp` / an array of those / `(exec) => boolean`.
 When one tool is mounted several times, **the most recent mount wins** (the config row registers first and plugins later — so a plugin can override the config).
 
@@ -146,6 +148,7 @@ Without `fields`, the proposal is **every parameter of this call**:
 | `whenUnavailable` | `reject` \| `wait` | `reject` | Behaviour with no browser connected: `reject` = fail-closed; `wait` = wait indefinitely, so **pair it with a `countdown`** or that call hangs until its Session ends (the host warns at mount time); see §7.1 |
 | `enabled` | boolean \| `(exec) => boolean` | `true` | Turn a mount off temporarily / make it conditional |
 | `maxFieldChars` | number | `20000` | Per-field render cap; longer values are truncated with a note |
+| `resolveTimeoutMs` | number | `5000` | Bound on resolving one **computed** field; a timeout or a throw fails that field alone, never the call |
 
 ### FieldSpec
 
@@ -154,6 +157,7 @@ Without `fields`, the proposal is **every parameter of this call**:
   render: 'markdown',        // markdown | text | diff | json | hidden
   editable: true,            // overrides the default editability
   labels: ['irreversible'],  // field-level labels
+  value: 'fixed copy',       // this field's text: a literal, or (exec) => string | Promise<string>
   diff: { before: 'old_string', after: 'new_string', path: 'file_path' } }   // used when render: 'diff'
 ```
 
@@ -161,6 +165,31 @@ Without `fields`, the proposal is **every parameter of this call**:
 - When `fields` is given, **only** the listed fields are shown (parameters you leave out never reach the panel).
 - Config rows may shorten a spec to a bare string: `fields: ['command', { param: 'cwd', title: 'Working directory' }]`.
 
+### Computed fields: putting what the arguments do not carry on the card
+
+`diff.before` / `diff.after` / `diff.path` normally name a **parameter** (the host reads `args[name]`). Like a field's `value`, any of them may instead be a **function**: the host calls it with the pending `exec` before the card opens and uses what it returns as the text.
+
+```js
+ctx.hitl.protect('update_index', {
+  title: 'Update the knowledge-tree index',
+  fields: [
+    { param: 'content', title: 'New index text', render: 'markdown' },
+    { param: 'index', title: 'What changes in the index file', render: 'diff', editable: false,
+      // `before` reads the old index from disk, `after` derives the new file text —
+      // neither of them is one of the call's parameters
+      diff: { path: 'index.md',
+              before: async exec => readIndexFile(exec),
+              after: exec => `# Knowledge tree index\n\n${exec.arguments.content}` } },
+  ],
+})
+```
+
+- A string `diff.path` that is **not** a parameter name is used as a literal path: the file a call is about to change is often not one of its arguments.
+- Resolvers may be async; one field's resolution is bounded by `resolveTimeoutMs` (5s by default).
+- **A failed resolution never blocks the decision**: a throw or a timeout turns *that field* into one `⚠️ …could not be resolved…` line, the card still opens, and the human still decides. If the resolution machinery itself breaks, the proposal degrades to the raw arguments instead of denying the call.
+- The wire format and the browser half are unchanged: both sides of a diff always travelled in the frame; the panel just renders them.
+- Each side of a diff is cut past `maxDiffLines` (2000 lines) with a note, so a whole-file diff cannot become an unbounded frame.
+
 ### The three endings of a countdown
 
 `countdown.action` decides what the host does when the countdown reaches zero:
@@ -385,28 +414,28 @@ Reply: `{ ok: true, accepted: true, held?, expiresAt? }` or
 
 ```text
 dsh-hitl/
-├── index.js                639   host half: service + gate + countdown/hold + SSE & decision routes + token injection
+├── index.js                666   host half: service + gate + countdown/hold + SSE & decision routes + token injection
 ├── client.js              1918   browser half: decision panel + frame-level notice (self-contained classic script, no imports)
 ├── lib/                          the host half's pure logic: no Cordis, no DOM, testable on its own
-│   ├── protocol.js         182   frame and uplink validation, limits, error codes (the single source of the protocol)
-│   ├── resolve.js          311   matcher compilation (name/glob/RegExp/predicate), option normalization and diagnostics
-│   ├── fields.js           244   default proposal derivation, diff pairing, decision → model-visible text
+│   ├── protocol.js         195   frame and uplink validation, limits, error codes (the single source of the protocol)
+│   ├── resolve.js          363   matcher compilation (name/glob/RegExp/predicate), option normalization and diagnostics
+│   ├── fields.js           449   default proposal derivation, diff pairing, computed-field resolution, decision → model-visible text
 │   └── pending.js          217   the pending-decision state machine (injectable clock): countdown, hold, settle-once
 ├── locale/                       the plugin list's name and description (shape must be {"meta":{...}}, see §6.3)
 │   ├── en.json               6
 │   └── zh.json               6
 ├── docs/                         screenshot sources, deliberately NOT shipped: the README links the landing page instead
-├── tests/                        zero-dependency Node tests, 153 cases in total
+├── tests/                        zero-dependency Node tests, 167 cases in total
 │   ├── client.test.js      818   (65) the browser half's pure helpers + store / connection / seat
-│   ├── fields.test.js      269   (26) proposal derivation and decision text
+│   ├── fields.test.js      387   (37) proposal derivation, computed fields and decision text
 │   ├── pending.test.js     240   (18) the state machine (injected clock, no real waiting)
-│   ├── resolve.test.js     181   (19) matchers and option normalization
+│   ├── resolve.test.js     224   (22) matchers and option normalization
 │   ├── protocol.test.js    117   (16) frame and uplink validation
 │   ├── docs.test.js        121   (5) the two READMEs, the landing-page link, and the numbers in this very table
 │   └── manifest.test.js     77   (4) package metadata and the locale resource shape
 ├── .github/workflows/release.yml     tag-triggered publish via npm trusted publishing (OIDC)
 ├── package.json             68   manifest: exports / dsh.bundle.patch / dsh.client / icon
-├── cordis.patch.yml         17   the bundle's configuration layer (inserts the row with id `hitl`)
+├── cordis.patch.yml         18   the bundle's configuration layer (inserts the row with id `hitl`)
 ├── icon.svg                  6   the plugin list icon
 ├── LICENSE                       MIT
 ├── README.md                     this document
@@ -436,7 +465,7 @@ dsh-hitl/
 
 ```sh
 node --check index.js client.js lib/*.js     # syntax
-npm test                                     # 153 zero-dependency cases: pure functions, state machines, the channel
+npm test                                     # 167 zero-dependency cases: pure functions, state machines, the channel
 npm run check                                # both of the above (syntax + the whole suite)
 ```
 

package/README.zh.md

@@ -105,10 +105,12 @@ export function apply(ctx) {
 }
 ```
 
-> **一定要带 `owner`（第三个参数）**：挂载是记在 `hitl` 插件里的状态，不是你的插件状态。
-> 不传 owner 时，`protect()` 返回的 disposer 就是唯一的解绑手段——而"从 `apply` 里 return 一个函数"
+> **`owner` 决定这次挂载的"撤销权"记在谁账上。** 它是调用方插件的 Cordis 上下文，通常就是你
+> `apply` 收到的 `ctx`：传了它，`hitl` 会把这次挂载的解绑登记在调用方插件的 fiber 上，
+> 该插件被卸载 / 禁用 / 重载时，挂载自动移除。
+> 挂载本身是记在 `hitl` 插件里的状态，不是你的插件状态——所以不传 owner 时，`protect()` 返回的
+> disposer 就是唯一的解绑手段，而"从 `apply` 里 return 一个函数"
 > **不算生命周期**：实测过，插件行被卸载后挂载仍然生效，那个工具会被永久拦下去。
-> 传了 `ctx` 之后，`hitl` 会在你的插件上下文上注册一个 effect，插件卸载即自动解绑。
 > 另一种等价写法是把它包进你自己的 effect：
 > `ctx.effect(() => ctx.hitl.protect('bash', {...}), 'my-plugin: hitl mount')`。
 > 万一留下了残留挂载，用 `ctx.hitl.list()` 看一眼，`ctx.hitl.unprotect('bash')` 清掉；
@@ -118,11 +120,15 @@ export function apply(ctx) {
 
 | 成员 | 说明 |
 |---|---|
-| `protect(matcher, options?, owner?)` | 挂载一个工具；`owner` 传调用方 ctx 即可自动解绑；返回 disposer |
+| `protect(matcher, options?, owner?)` | 挂载一个工具，返回 disposer。`owner` 需传入调用方自己的 ctx，用于把这次挂载的解绑登记到调用方插件的生命周期上：调用方被卸载 / 禁用 / 重载时自动移除；不传则挂载会活过调用方 |
 | `unprotect(matcher)` | 按 matcher 描述移除挂载，返回移除数量 |
 | `list()` | 当前所有挂载（诊断用） |
 | `pending()` | 当前所有等待人类决策的请求（诊断用） |
 
+> 签名上 `owner` 是可选的，因为还有另一条入口：`config.protect` 那些行天然归 `hitl` 自己管
+> （它们随 `hitl` 这一行卸载而清空），不需要 owner。但用 `ctx.hitl.protect()` 这个 API 时，
+> 它就是必需的——不传不是"一种合法的简化"，而是一个坑。
+
 `matcher`：工具名 / 含 `*` 的通配串 / `RegExp` / 上面几者的数组 / `(exec) => boolean`。
 同一个工具被挂载多次时，**后挂载的覆盖先挂载的**（配置行先注册，插件后注册，所以插件可以覆盖配置）。
 
@@ -159,6 +165,7 @@ export function apply(ctx) {
 | `whenUnavailable` | `reject` \| `wait` | `reject` | 没有任何浏览器连接时的行为：`reject` = fail-closed；`wait` = 一直等，**务必配 `countdown`**，否则那次调用会挂到会话结束（挂载时宿主会给 `dsh-hitl:` 警告），见 §7.1 |
 | `enabled` | boolean \| `(exec) => boolean` | `true` | 临时关闭 / 条件挂载 |
 | `maxFieldChars` | number | `20000` | 单字段渲染上限，超出会截断并提示 |
+| `resolveTimeoutMs` | number | `5000` | 单个**计算字段**的解析上限；超时或抛错只让那个字段显示失败，不阻断这次调用 |
 
 ### FieldSpec
 
@@ -167,6 +174,7 @@ export function apply(ctx) {
   render: 'markdown',        // markdown | text | diff | json | hidden
   editable: true,            // 覆盖默认可编辑性
   labels: ['不可撤销'],       // 字段级标签
+  value: '固定文案',          // 该字段的文本：字面量，或 (exec) => string | Promise<string>
   diff: { before: 'old_string', after: 'new_string', path: 'file_path' } }   // render: 'diff' 时用
 ```
 
@@ -174,6 +182,30 @@ export function apply(ctx) {
 - `fields` 给定时**只显示**列出的字段（未列出的参数不会出现在面板里）。
 - 配置行里可以简写成字符串：`fields: ['command', { param: 'cwd', title: '工作目录' }]`。
 
+### 计算字段：把参数之外的东西放进卡里
+
+`diff.before` / `diff.after` / `diff.path` 平时填的是**参数名**（宿主取 `args[名字]`）。它们与字段的 `value` 一样，也可以填**函数**：宿主在弹卡前用这次调用的 `exec` 调它，把返回值当作文本。
+
+```js
+ctx.hitl.protect('update_index', {
+  title: '更新知识树索引',
+  fields: [
+    { param: 'content', title: '新索引正文', render: 'markdown' },
+    { param: 'index', title: '索引文件的变化', render: 'diff', editable: false,
+      // before 读磁盘上的旧索引，after 由新正文推出来——两者都不在参数里
+      diff: { path: 'index.md',
+              before: async exec => readIndexFile(exec),
+              after: exec => `# 知识树索引\n\n${exec.arguments.content}` } },
+  ],
+})
+```
+
+- 字符串形式的 `diff.path` 若**不是**某个参数名，就当作字面路径使用：被改的文件常常不是这次调用的参数。
+- 函数可以是 async；每个字段的解析上限是 `resolveTimeoutMs`（默认 5s）。
+- **解析失败不阻断**：函数抛错或超时，只会把**那个字段**变成一行 `⚠️ 无法解析该字段：…`，卡照常弹出、人照常决策。整个解析过程坏掉时，提案退回到"参数原样"，而不是拒绝调用。
+- wire 格式与浏览器半都没有变化：diff 的两侧本来就在帧里，前端只是照常渲染。
+- diff 的每一侧超过 `maxDiffLines`（2000 行）会被截断并标注，避免整文件 diff 变成无上限的一帧。
+
 ### 倒计时的三种结局
 
 `countdown.action` 决定倒计时归零后宿主怎么判：
@@ -448,28 +480,28 @@ Error: HITL: no human decision arrived within 75s, so tool "glob" did not run. T
 
 ```text
 dsh-hitl/
-├── index.js                639   宿主半：服务 + 门禁 + 倒计时/持握 + SSE/决策路由 + 令牌注入
+├── index.js                666   宿主半：服务 + 门禁 + 倒计时/持握 + SSE/决策路由 + 令牌注入
 ├── client.js              1918   浏览器半：决策面板 + 帧级浮层（自包含 classic script，无 import）
 ├── lib/                          宿主半的纯逻辑：不碰 Cordis、不碰 DOM，可单独跑测试
-│   ├── protocol.js         182   帧与上行校验、上限、错误码（协议规范的唯一出处）
-│   ├── resolve.js          311   matcher 编译（名字/通配/RegExp/谓词）、挂载选项归一化与诊断
-│   ├── fields.js           244   默认提案推导、diff 配对、决策 → 模型可见文本
+│   ├── protocol.js         195   帧与上行校验、上限、错误码（协议规范的唯一出处）
+│   ├── resolve.js          363   matcher 编译（名字/通配/RegExp/谓词）、挂载选项归一化与诊断
+│   ├── fields.js           449   默认提案推导、diff 配对、计算字段解析、决策 → 模型可见文本
 │   └── pending.js          217   待决策状态机（可注入时钟）：倒计时、持握、恰好一次的结算
 ├── locale/                       插件列表里的名字与简介（形状必须是 {"meta":{...}}，见 §6.3）
 │   ├── en.json               6
 │   └── zh.json               6
 ├── docs/                         截图源文件，**故意不进 npm 包**：README 改为链接 landing page
-├── tests/                        零依赖 Node 测试，共 153 个用例
+├── tests/                        零依赖 Node 测试，共 167 个用例
 │   ├── client.test.js      818   （65）浏览器半的纯函数 + store / connection / seat
-│   ├── fields.test.js      269   （26）提案推导与决策文本
+│   ├── fields.test.js      387   （37）提案推导、计算字段与决策文本
 │   ├── pending.test.js     240   （18）状态机（注入时钟，无真实等待）
-│   ├── resolve.test.js     181   （19）matcher 与选项归一化
+│   ├── resolve.test.js     224   （22）matcher 与选项归一化
 │   ├── protocol.test.js    117   （16）帧与上行校验
 │   ├── docs.test.js        121   （5）两份 README、landing page 链接，以及上面这张表里的每个数字
 │   └── manifest.test.js     77   （4）包元数据与 locale 资源形状
 ├── .github/workflows/release.yml     tag-triggered publish via npm trusted publishing (OIDC)
 ├── package.json             68   清单：exports / dsh.bundle.patch / dsh.client / icon
-├── cordis.patch.yml         17   bundle 的配置层（插入 id 为 hitl 的那一行）
+├── cordis.patch.yml         18   bundle 的配置层（插入 id 为 hitl 的那一行）
 ├── icon.svg                  6   插件列表图标
 ├── LICENSE                       MIT
 ├── README.md                     本文档（英文版）
@@ -505,7 +537,7 @@ dsh-hitl/
 
 ```sh
 node --check index.js client.js lib/*.js     # 语法
-npm test                                     # 153 个纯函数/状态机/通道用例，零依赖
+npm test                                     # 167 个纯函数/状态机/通道用例，零依赖
 npm run check                                # 上面两步合起来（语法 + 全部用例）
 ```
 

package/cordis.patch.yml

@@ -2,10 +2,11 @@
 #
 # The row's `config.protect` list mounts HITL on tools without writing code:
 # each entry is { tool, ...hitlOptions } and mirrors ctx.hitl.protect(tool, options).
-# Plugins mount through the `hitl` service instead:
+# Plugins mount through the `hitl` service instead — note the third argument:
+# the callback's own ctx, so the mount is released when your plugin unloads.
 #
 #   ctx.inject(['hitl'], (ctx) => {
-#     ctx.hitl.protect('bash', { countdown: { seconds: 30, action: 'reject' } })
+#     ctx.hitl.protect('bash', { countdown: { seconds: 30, action: 'reject' } }, ctx)
 #   })
 #
 # A patch replaces the whole `config` of a row it overrides, so keep every key

package/index.js

@@ -21,7 +21,9 @@ import {
   DEFAULT_ENDPOINT, ERROR_CODES, GLOBAL_KEY, LIMITS, OUTCOMES, errorBody, frameHoldAck,
   framePing, frameRequest, frameSettled, frameSnapshot, okBody, parseUplink, sseChunk,
 } from './lib/protocol.js'
-import { buildRequest, capReason, describeDecision, isRevision, revisionContext } from './lib/fields.js'
+import {
+  buildRequest, capReason, describeDecision, hasComputed, isRevision, resolveFields, revisionContext,
+} from './lib/fields.js'
 import { DEFAULT_HOLD_GRACE_MS, createPendingRegistry } from './lib/pending.js'
 import { matchMount, mountApplies, normalizeMount, normalizeProtectList } from './lib/resolve.js'
 
@@ -234,6 +236,8 @@ export function apply(ctx, config = {}) {
       rejectFeedback: mount.options.reject.feedback,
       modify: mount.options.modify.mode,
       whenUnavailable: mount.options.whenUnavailable,
+      /** Whether this mount's proposal needs the host to compute a field. */
+      computed: hasComputed(mount.options),
     })),
     /** Every decision still waiting for a human, oldest first. */
     pending: () => registry.list().map(request => ({
@@ -315,6 +319,23 @@ export function apply(ctx, config = {}) {
     }
   }
 
+  /**
+   * Collect a mount's computed fields for one call.
+   *
+   * If the resolution itself breaks, the proposal degrades to the call's own
+   * arguments: a panel of raw parameters is still a decision the human can make,
+   * while a denied call is not. A resolver that fails on its own degrades inside
+   * `resolveFields` instead, into one field that says so.
+   */
+  async function resolutionFor(exec, mount) {
+    try {
+      return await resolveFields(exec, mount, { timeoutMs: mount.options.resolveTimeoutMs, warn })
+    } catch (error) {
+      warn(`the computed fields of tool ${JSON.stringify(exec.name)} could not be resolved: ${String(error)}`)
+      return undefined
+    }
+  }
+
   async function gate(exec, next) {
     let mount
     try {
@@ -335,7 +356,13 @@ export function apply(ctx, config = {}) {
     }
     const id = `hitl:${String(exec.callId ?? randomUUID())}`
     try {
-      const request = buildRequest({ execution: exec, mount, sessionId, id })
+      const request = buildRequest({
+        execution: exec,
+        mount,
+        sessionId,
+        id,
+        resolution: await resolutionFor(exec, mount),
+      })
       const settlement = await waitForDecision(id, request, mount, exec)
       return toPreToolDecision(exec, request, mount, settlement)
     } catch (error) {

package/lib/fields.js

@@ -6,6 +6,11 @@
  * Defaults follow the plugin's core promise: with no configuration at all, the
  * proposal is the call's own parameters — one field per parameter, titled by the
  * parameter's key, rendered as an editable markdown box.
+ *
+ * A mount that must show something the arguments do not carry — the file a call
+ * is about to overwrite, the node it is about to delete — declares it as a
+ * function; `resolveFields` runs those before the request is built. The browser
+ * half stays a pure renderer of the wire shape and needs no change for them.
  */
 
 import { LIMITS, truncate } from './protocol.js'
@@ -14,6 +19,9 @@ import { defaultEditable } from './resolve.js'
 /** Model-facing prefix every reason this plugin produces starts with. */
 export const REASON_PREFIX = 'HITL'
 
+/** Default bound on one computed field, used when the mount sets no `resolveTimeoutMs`. */
+export const RESOLVE_TIMEOUT_MS = LIMITS.resolveTimeoutMs
+
 /** Render a parameter value as proposal text. */
 export function renderValue(value) {
   if (typeof value === 'string') return value
@@ -36,6 +44,25 @@ export function inferRender() {
   return 'markdown'
 }
 
+/** Whether a value is computed from the pending call instead of read from an argument. */
+export function isResolver(value) {
+  return typeof value === 'function'
+}
+
+/**
+ * The diff option that applies to one field: the field's own, else the mount's.
+ *
+ * Shared by the renderer and the resolver on purpose: a field must never be
+ * resolved as a diff and then rendered as something else, or the other way
+ * round.
+ */
+function diffOptionOf(spec, mount) {
+  const requested = spec.diff ?? mount.options.diff
+  return typeof requested === 'object' && requested !== null && !Array.isArray(requested)
+    ? requested
+    : undefined
+}
+
 function schemaOf(execution) {
   const parameters = execution.schema?.parameters
   return typeof parameters === 'object' && parameters !== null ? parameters : undefined
@@ -66,10 +93,12 @@ export function defaultFieldSpecs(execution) {
 }
 
 function diffSpec(spec, mount, execution) {
-  const requested = spec.diff ?? mount.options.diff
-  if (requested === undefined || requested === null || typeof requested !== 'object') return undefined
+  const requested = diffOptionOf(spec, mount)
+  if (requested === undefined) return undefined
   const before = requested.before
   const after = requested.after
+  // Function sides are computed before the request is built (see
+  // `resolveFields`); this path only pairs two arguments.
   if (typeof before !== 'string' || typeof after !== 'string') return undefined
   const args = argumentsOf(execution)
   if (args === undefined) return undefined
@@ -80,16 +109,161 @@ function diffSpec(spec, mount, execution) {
   }
 }
 
+// ── computed fields ─────────────────────────────────────────────────────────
+
+/**
+ * Await one resolver with a bound.
+ *
+ * A resolver is caller-supplied code, so it can hang; the gate must not hang
+ * with it. The losing side of the race keeps running — a promise cannot be
+ * cancelled — but nothing awaits it, and the timer is unref'd so a pending
+ * timeout never holds the process open on its own.
+ */
+async function callResolver(resolver, execution, timeoutMs, label) {
+  let timer
+  try {
+    return await Promise.race([
+      Promise.resolve().then(() => resolver(execution)),
+      new Promise((_resolve, reject) => {
+        timer = setTimeout(() => { reject(new Error(`${label} timed out after ${timeoutMs}ms`)) }, timeoutMs)
+        if (typeof timer?.unref === 'function') timer.unref()
+      }),
+    ])
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+/** Render whatever a resolver returned as field text. */
+function renderComputed(value) {
+  return value === undefined || value === null ? '' : renderValue(value)
+}
+
+/**
+ * Read one diff side: a resolver computes it, a string names the argument that
+ * carries it. `path` may also be a literal, because the file a call is about to
+ * change is often not one of the call's parameters.
+ */
+async function readDiffSide(declared, key, execution, timeoutMs) {
+  if (isResolver(declared)) {
+    return renderComputed(await callResolver(declared, execution, timeoutMs, `diff.${key}`))
+  }
+  const args = argumentsOf(execution)
+  const carried = args === undefined ? undefined : args[declared]
+  if (carried === undefined && key === 'path') return declared
+  return renderValue(carried)
+}
+
+/**
+ * Resolve the computed parts of one field spec.
+ * @param spec - the field spec.
+ * @param mount - the matched mount, for a mount-level diff.
+ * @param execution - the pending call.
+ * @param settings - `{ timeoutMs, warn }`.
+ * @returns `{ kind: 'text' | 'diff' | 'error', ... }`, or undefined when the spec computes nothing.
+ */
+async function resolveSpec(spec, mount, execution, settings) {
+  const requested = diffOptionOf(spec, mount)
+  const value = isResolver(spec.value) ? spec.value : undefined
+  const sides = requested === undefined
+    ? []
+    : ['path', 'before', 'after'].filter(key => isResolver(requested[key]))
+  if (value === undefined && sides.length === 0) return undefined
+  try {
+    if (sides.length === 0) {
+      const computed = await callResolver(value, execution, settings.timeoutMs, 'fields[].value')
+      return { kind: 'text', text: renderComputed(computed) }
+    }
+    const [path, oldText, newText] = await Promise.all([
+      readDiffSide(requested.path, 'path', execution, settings.timeoutMs),
+      readDiffSide(requested.before, 'before', execution, settings.timeoutMs),
+      readDiffSide(requested.after, 'after', execution, settings.timeoutMs),
+    ])
+    return { kind: 'diff', diff: { path, oldText, newText } }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    settings.warn(`a computed field could not be resolved (${message}); the panel shows the failure instead`)
+    // Degrade to a visible field, never to a blocked gate: the human can still
+    // decide on the call itself, and every other field still renders.
+    return { kind: 'error', message: `⚠️ 无法解析该字段：${message}` }
+  }
+}
+
+/**
+ * Resolve every computed field of one mount against the pending call.
+ *
+ * Only specs that declare a resolver are resolved, so a mount made of plain
+ * argument fields pays nothing and keeps its proposal unchanged.
+ *
+ * @param execution - the pending call.
+ * @param mount - the matched mount.
+ * @param options - `{ timeoutMs, warn }`; defaults to `RESOLVE_TIMEOUT_MS` and silence.
+ * @returns `{ fields: Map<spec, result>, mountDiff? }`, to hand to `buildRequest`.
+ */
+export async function resolveFields(execution, mount, options = {}) {
+  const timeoutMs = Number.isSafeInteger(options.timeoutMs) && options.timeoutMs > 0
+    ? options.timeoutMs
+    : RESOLVE_TIMEOUT_MS
+  const settings = {
+    timeoutMs,
+    warn: typeof options.warn === 'function' ? options.warn : () => {},
+  }
+  const fields = new Map()
+  if (mount.options.fields !== undefined) {
+    for (const spec of mount.options.fields) {
+      const resolved = await resolveSpec(spec, mount, execution, settings)
+      if (resolved !== undefined) fields.set(spec, resolved)
+    }
+  }
+  // Without an explicit field list, `buildFields` derives one field per
+  // parameter and appends the mount's diff as a field of its own; that diff
+  // computes on its own too.
+  const mountDiff = mount.options.fields === undefined
+    ? await resolveSpec({ param: 'diff' }, mount, execution, settings)
+    : undefined
+  return { fields, mountDiff }
+}
+
+/** Whether a mount asks the host to compute any part of its proposal. */
+export function hasComputed(options) {
+  const computed = requested => requested !== undefined && requested !== null
+    && ['path', 'before', 'after'].some(key => isResolver(requested[key]))
+  if (computed(options.diff)) return true
+  return (options.fields ?? []).some(spec => isResolver(spec.value) || computed(spec.diff))
+}
+
+/** Bound one side of a diff by lines, marking what was cut. */
+function boundDiffSide(text) {
+  const lines = text.split('\n')
+  if (lines.length <= LIMITS.maxDiffLines) return text
+  return [
+    ...lines.slice(0, LIMITS.maxDiffLines),
+    `… [已截断，另有 ${lines.length - LIMITS.maxDiffLines} 行未显示]`,
+  ].join('\n')
+}
+
+/** Bound both sides of one diff, so a whole-file diff cannot become an unbounded frame. */
+function boundDiff(diff) {
+  return { ...diff, oldText: boundDiffSide(diff.oldText), newText: boundDiffSide(diff.newText) }
+}
+
+/** Label of the field a mount-level `diff` produces when its sides are computed. */
+function diffPairLabel(requested) {
+  const side = entry => (typeof entry === 'string' ? entry : 'computed')
+  return `${side(requested.before)}→${side(requested.after)}`
+}
+
 /**
  * Build the wire fields of one request.
  * @param execution - the pending tool execution.
  * @param mount - the matched mount.
+ * @param resolution - optional `resolveFields` result for this call.
  * @returns an ordered field array, values already rendered and truncated.
  */
-export function buildFields(execution, mount) {
+export function buildFields(execution, mount, resolution) {
   const options = mount.options
   const args = argumentsOf(execution)
-  const mountDiff = options.diff === undefined || options.diff === null ? undefined : options.diff
+  const mountDiff = diffOptionOf({}, mount)
   // A mount-level diff pairs two parameters, so those parameters must not also
   // appear as their own fields in the defaulted list.
   const paired = options.fields === undefined && mountDiff !== undefined
@@ -106,18 +280,33 @@ export function buildFields(execution, mount) {
     const raw = param === '(arguments)' && args === undefined
       ? execution.arguments
       : (args === undefined ? undefined : args[param])
-    const render = spec.render ?? (diffSpec(spec, mount, execution) === undefined ? inferRender(raw) : 'diff')
-    const diff = render === 'diff' ? diffSpec(spec, mount, execution) : undefined
+    const computed = resolution === undefined || resolution.fields === undefined
+      ? undefined
+      : resolution.fields.get(spec)
+    const computedDiff = computed !== undefined && computed.kind === 'diff' ? computed.diff : undefined
+    const render = computed !== undefined && computed.kind === 'error'
+      ? 'text'
+      : computedDiff !== undefined
+        ? 'diff'
+        : spec.render ?? (diffSpec(spec, mount, execution) === undefined ? inferRender(raw) : 'diff')
+    const diff = computedDiff ?? (render === 'diff' ? diffSpec(spec, mount, execution) : undefined)
     const title = spec.title
       ?? (typeof schema?.title === 'string' ? schema.title : undefined)
       ?? param
     const description = spec.description
       ?? (typeof schema?.description === 'string' ? schema.description : undefined)
     const editable = spec.editable ?? defaultEditable(render)
+    // A literal `value` replaces the parameter text; a function `value` was
+    // already turned into `computed` before this ran.
+    const declared = typeof spec.value === 'string' ? spec.value : undefined
     // A hidden field carries no value: it exists only to stay out of the panel.
-    const value = diff === undefined && render !== 'hidden'
-      ? truncate(renderValue(raw), options.maxFieldChars)
-      : { text: '', truncated: false }
+    const value = computed !== undefined && computed.kind === 'error'
+      ? { text: computed.message, truncated: false }
+      : (computed !== undefined && computed.kind === 'text' && diff === undefined && render !== 'hidden'
+        ? truncate(computed.text, options.maxFieldChars)
+        : (diff === undefined && render !== 'hidden'
+          ? truncate(declared ?? renderValue(raw), options.maxFieldChars)
+          : { text: '', truncated: false }))
     fields.push({
       param,
       title,
@@ -125,20 +314,36 @@ export function buildFields(execution, mount) {
       render,
       editable: render === 'diff' || render === 'hidden' ? false : editable,
       labels: spec.labels ?? [],
-      ...(diff === undefined ? { value: value.text, truncated: value.truncated } : { diff }),
+      ...(diff === undefined ? { value: value.text, truncated: value.truncated } : { diff: boundDiff(diff) }),
     })
   }
   if (options.fields === undefined && mountDiff !== undefined) {
-    const diff = diffSpec({ diff: mountDiff }, mount, execution)
-    if (diff !== undefined) {
+    const computed = resolution === undefined ? undefined : resolution.mountDiff
+    const title = typeof options.diff.title === 'string' ? options.diff.title : 'diff'
+    if (computed !== undefined && computed.kind === 'error') {
       fields.push({
-        param: `${options.diff.before}→${options.diff.after}`,
-        title: typeof options.diff.title === 'string' ? options.diff.title : 'diff',
-        render: 'diff',
+        param: 'diff',
+        title,
+        render: 'text',
         editable: false,
         labels: [],
-        diff,
+        value: computed.message,
+        truncated: false,
       })
+    } else {
+      const diff = computed !== undefined && computed.kind === 'diff'
+        ? computed.diff
+        : diffSpec({ diff: mountDiff }, mount, execution)
+      if (diff !== undefined) {
+        fields.push({
+          param: diffPairLabel(options.diff),
+          title,
+          render: 'diff',
+          editable: false,
+          labels: [],
+          diff: boundDiff(diff),
+        })
+      }
     }
   }
   if (fields.length === 0) {
@@ -149,12 +354,12 @@ export function buildFields(execution, mount) {
 
 /**
  * Build one complete wire request.
- * @param input - `{ execution, mount, sessionId, id, now }`.
+ * @param input - `{ execution, mount, sessionId, id, now, resolution }`.
  * @returns the request object broadcast to browsers.
  */
-export function buildRequest({ execution, mount, sessionId, id, now = Date.now() }) {
+export function buildRequest({ execution, mount, sessionId, id, now = Date.now(), resolution }) {
   const options = mount.options
-  const fields = buildFields(execution, mount)
+  const fields = buildFields(execution, mount, resolution)
   const countdown = options.countdown === null ? null : {
     remainingMs: options.countdown.seconds * 1000,
     action: options.countdown.action,

package/lib/protocol.js

@@ -30,6 +30,19 @@ export const LIMITS = {
   maxFieldChars: 20000,
   /** Longest decision text folded into one model-facing message. */
   maxDecisionChars: 8000,
+  /**
+   * Lines kept per side of one diff. Deliberately far above what a reader
+   * compares by eye: it exists so a computed diff of a whole file cannot become
+   * an unbounded SSE frame, not to shorten small ones. The browser half stops
+   * aligning side by side past 2000 lines of its own, so a cut here is the only
+   * one worth announcing.
+   */
+  maxDiffLines: 2000,
+  /**
+   * Default bound on one computed field's resolver. Caller-supplied code can
+   * hang, and the gate must not hang with it.
+   */
+  resolveTimeoutMs: 5000,
 }
 
 /** Failure vocabulary shared by the HTTP replies and the panel's error state. */

package/lib/resolve.js

@@ -42,6 +42,7 @@ export const DEFAULT_OPTIONS = {
   whenUnavailable: 'reject',
   enabled: true,
   maxFieldChars: LIMITS.maxFieldChars,
+  resolveTimeoutMs: LIMITS.resolveTimeoutMs,
 }
 
 /**
@@ -150,6 +151,45 @@ function normalizeButtons(value, report) {
   return buttons
 }
 
+/** One side of a diff: the name of a parameter, or a function computing the text. */
+function isDiffSource(value) {
+  return typeof value === 'string' || typeof value === 'function'
+}
+
+/**
+ * Check one `diff` option, at field or mount level.
+ *
+ * A malformed diff is reported and dropped rather than kept: keeping it would
+ * only make the field silently render as a markdown box instead of the diff the
+ * mount asked for, which is the harder failure to notice.
+ *
+ * @param value - the raw `diff` value.
+ * @param report - diagnostics sink.
+ * @param label - where the value came from, for the warning text.
+ * @returns the normalized diff, or undefined.
+ */
+function normalizeDiff(value, report, label) {
+  if (value === undefined || value === null) return undefined
+  if (typeof value !== 'object' || Array.isArray(value)) {
+    report(`${label} must be an object like { before, after }`)
+    return undefined
+  }
+  if (!isDiffSource(value.before) || !isDiffSource(value.after)) {
+    report(`${label}.before and ${label}.after must each be a parameter name or a function of the call`)
+    return undefined
+  }
+  if (value.path !== undefined && !isDiffSource(value.path)) {
+    report(`${label}.path must be a parameter name, a literal path, or a function of the call`)
+    return undefined
+  }
+  return {
+    before: value.before,
+    after: value.after,
+    ...(value.path === undefined ? {} : { path: value.path }),
+    ...(typeof value.title === 'string' ? { title: value.title } : {}),
+  }
+}
+
 function normalizeField(entry, report, index) {
   if (typeof entry === 'string') return { param: entry }
   if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
@@ -164,6 +204,13 @@ function normalizeField(entry, report, index) {
     report(`fields[${index}].render must be one of ${RENDER_MODES.join(', ')}`)
     return undefined
   }
+  // `value` overrides where the field's text comes from: a literal, or a
+  // function of the pending call that the host resolves before the panel opens.
+  if (entry.value !== undefined && typeof entry.value !== 'string' && typeof entry.value !== 'function') {
+    report(`fields[${index}].value must be a literal string or a function of the call`)
+    return undefined
+  }
+  const diff = normalizeDiff(entry.diff, report, `fields[${index}].diff`)
   return {
     param: entry.param,
     ...(typeof entry.title === 'string' ? { title: entry.title } : {}),
@@ -171,7 +218,8 @@ function normalizeField(entry, report, index) {
     ...(entry.render === undefined ? {} : { render: entry.render }),
     ...(entry.editable === undefined ? {} : { editable: entry.editable === true }),
     ...(Array.isArray(entry.labels) ? { labels: entry.labels.filter(label => typeof label === 'string') } : {}),
-    ...(entry.diff === undefined ? {} : { diff: entry.diff }),
+    ...(entry.value === undefined ? {} : { value: entry.value }),
+    ...(diff === undefined ? {} : { diff }),
   }
 }
 
@@ -213,6 +261,9 @@ export function normalizeMount(input, source) {
   const maxFieldChars = Number.isSafeInteger(input.maxFieldChars) && input.maxFieldChars > 0
     ? input.maxFieldChars
     : DEFAULT_OPTIONS.maxFieldChars
+  const resolveTimeoutMs = Number.isSafeInteger(input.resolveTimeoutMs) && input.resolveTimeoutMs > 0
+    ? input.resolveTimeoutMs
+    : DEFAULT_OPTIONS.resolveTimeoutMs
   const labels = Array.isArray(input.labels)
     ? input.labels.filter(label => typeof label === 'string' && label !== '')
     : []
@@ -236,13 +287,14 @@ export function normalizeMount(input, source) {
       labels,
       buttons: normalizeButtons(input.buttons, report),
       fields,
-      diff: input.diff,
+      diff: normalizeDiff(input.diff, report, 'diff'),
       countdown,
       reject: normalizeReject(input.reject, report),
       modify: normalizeModify(input.modify, report),
       whenUnavailable: unavailable,
       enabled: input.enabled === undefined ? true : input.enabled,
       maxFieldChars,
+      resolveTimeoutMs,
     },
   }
   return { ok: true, mount, warnings }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-hitl",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "description": "Human-in-the-loop gate for DSH tool calls: mount any tool behind an approve / modify / reject decision card in the DSH Web UI, with an optional countdown.",
   "keywords": [
     "dsh",

package/tests/fields.test.js

@@ -3,8 +3,9 @@ import { describe, it } from 'node:test'
 
 import {
   REASON_PREFIX, buildFields, buildRequest, capReason, defaultFieldSpecs, describeDecision,
-  inferRender, isRevision, renderValue, revisionContext, revisionText,
+  hasComputed, inferRender, isRevision, renderValue, resolveFields, revisionContext, revisionText,
 } from '../lib/fields.js'
+import { LIMITS } from '../lib/protocol.js'
 import { normalizeMount } from '../lib/resolve.js'
 
 /** Normalize one mount through the same path the host half uses. */
@@ -267,3 +268,120 @@ describe('fields: decisions back to the model', () => {
     assert.equal(capped.includes('已截断'), true)
   })
 })
+
+describe('fields: computed fields', () => {
+  const call = executionOf({ path: 'notes.md', content: 'new text' })
+
+  it('takes a literal or a function as a field value', async () => {
+    const mount = mountOf({
+      fields: [
+        { param: 'content', title: '正文', render: 'markdown', editable: false, value: execution => `读到 ${execution.arguments.path}` },
+        { param: 'note', render: 'text', editable: false, value: '固定文案' },
+        { param: 'path', render: 'text', editable: false },
+      ],
+    })
+    const fields = buildFields(call, mount, await resolveFields(call, mount))
+    assert.equal(fields[0].value, '读到 notes.md')
+    assert.equal(fields[0].editable, false)
+    assert.equal(fields[1].value, '固定文案')
+    // A field without a resolver keeps reading its own argument.
+    assert.equal(fields[2].value, 'notes.md')
+  })
+
+  it('awaits an async resolver and renders a non-string result', async () => {
+    const mount = mountOf({
+      fields: [
+        { param: 'a', render: 'text', editable: false, value: async () => 'awaited' },
+        { param: 'b', render: 'text', editable: false, value: () => ({ lines: 2 }) },
+      ],
+    })
+    const fields = buildFields(call, mount, await resolveFields(call, mount))
+    assert.equal(fields[0].value, 'awaited')
+    assert.equal(fields[1].value, '{\n  "lines": 2\n}')
+  })
+
+  it('renders a computed diff against a literal path', async () => {
+    const mount = mountOf({
+      fields: [{
+        param: 'index', title: '索引变化', render: 'diff', editable: false,
+        diff: { path: 'index.md', before: async () => 'old line', after: 'content' },
+      }],
+    })
+    const [field] = buildFields(call, mount, await resolveFields(call, mount))
+    assert.equal(field.render, 'diff')
+    assert.equal(field.editable, false)
+    assert.deepEqual(field.diff, { path: 'index.md', oldText: 'old line', newText: 'new text' })
+  })
+
+  it('resolves a mount-level diff that carries no field list', async () => {
+    const mount = mountOf({ diff: { path: () => 'tree.md', before: async () => 'a', after: () => 'b' } })
+    const fields = buildFields(call, mount, await resolveFields(call, mount))
+    assert.deepEqual(fields.map(field => field.param), ['path', 'content', 'computed→computed'])
+    assert.deepEqual(fields[2].diff, { path: 'tree.md', oldText: 'a', newText: 'b' })
+  })
+
+  it('shows a failing resolver in its own field instead of blocking the gate', async () => {
+    const mount = mountOf({
+      fields: [
+        { param: 'path', render: 'text', editable: false },
+        { param: 'ghost', render: 'markdown', editable: false, value: () => { throw new Error('磁盘不可读') } },
+      ],
+    })
+    const warnings = []
+    const fields = buildFields(call, mount, await resolveFields(call, mount, { warn: message => warnings.push(message) }))
+    assert.equal(fields[0].value, 'notes.md')
+    assert.equal(fields[1].render, 'text')
+    assert.equal(fields[1].editable, false)
+    assert.equal(fields[1].value.includes('磁盘不可读'), true)
+    assert.equal(warnings.length, 1)
+  })
+
+  it('bounds a hanging resolver with the mount timeout', async () => {
+    const mount = mountOf({ resolveTimeoutMs: 20, fields: [{ param: 'slow', value: () => new Promise(() => {}) }] })
+    const resolution = await resolveFields(call, mount, { timeoutMs: mount.options.resolveTimeoutMs })
+    const [field] = buildFields(call, mount, resolution)
+    assert.equal(field.value.includes('timed out after 20ms'), true)
+  })
+
+  it('truncates a computed value at maxFieldChars', async () => {
+    const mount = mountOf({ maxFieldChars: 4, fields: [{ param: 'long', value: () => 'abcdefgh' }] })
+    const [field] = buildFields(call, mount, await resolveFields(call, mount))
+    assert.equal(field.truncated, true)
+    assert.match(field.value, /已截断，共 8 字/)
+  })
+
+  it('bounds each side of a computed diff by lines', async () => {
+    const long = Array.from({ length: LIMITS.maxDiffLines + 2 }, (_entry, index) => `L${index}`).join('\n')
+    const mount = mountOf({
+      fields: [{ param: 'big', render: 'diff', editable: false, diff: { before: () => '', after: () => long } }],
+    })
+    const [field] = buildFields(call, mount, await resolveFields(call, mount))
+    assert.equal(field.diff.newText.split('\n').length, LIMITS.maxDiffLines + 1)
+    assert.match(field.diff.newText, /已截断，另有 2 行未显示/)
+  })
+
+  it('leaves a mount without resolvers exactly as it was', async () => {
+    const mount = mountOf({ fields: [{ param: 'content', render: 'markdown' }] })
+    const resolution = await resolveFields(call, mount)
+    assert.equal(resolution.fields.size, 0)
+    assert.equal(resolution.mountDiff, undefined)
+    assert.deepEqual(buildFields(call, mount, resolution), buildFields(call, mount))
+  })
+
+  it('reports which mounts compute a field', () => {
+    assert.equal(hasComputed(mountOf({}).options), false)
+    assert.equal(hasComputed(mountOf({ fields: [{ param: 'a', value: () => 'x' }] }).options), true)
+    assert.equal(hasComputed(mountOf({ diff: { before: 'old', after: () => 'x' } }).options), true)
+    assert.equal(hasComputed(mountOf({ fields: [{ param: 'a', diff: { before: 'old', after: () => 'x' } }] }).options), true)
+  })
+
+  it('carries a resolved diff through buildRequest', async () => {
+    const mount = mountOf({
+      fields: [{ param: 'index', title: '索引变化', render: 'diff', editable: false, diff: { path: 'index.md', before: () => 'old', after: 'content' } }],
+    })
+    const request = buildRequest({
+      execution: call, mount, sessionId: 's1', id: 'r1', now: 0, resolution: await resolveFields(call, mount),
+    })
+    assert.deepEqual(request.fields[0].diff, { path: 'index.md', oldText: 'old', newText: 'new text' })
+  })
+})

package/tests/resolve.test.js

@@ -61,6 +61,7 @@ describe('resolve: normalizeMount', () => {
       whenUnavailable: 'reject',
       enabled: true,
       maxFieldChars: DEFAULT_OPTIONS.maxFieldChars,
+      resolveTimeoutMs: DEFAULT_OPTIONS.resolveTimeoutMs,
     })
   })
 
@@ -111,6 +112,48 @@ describe('resolve: normalizeMount', () => {
     assert.match(warnings[0], /fields\[2\]\.render/)
   })
 
+  it('keeps a literal or computed field value and drops an unusable one', () => {
+    const read = () => 'value'
+    const { mount, warnings } = normalizeMount({
+      tool: 'edit',
+      fields: [
+        { param: 'note', value: '固定文案' },
+        { param: 'computed', value: read },
+        { param: 'content', value: undefined, diff: { path: 'file_path', before: read, after: 'new_string' } },
+      ],
+    }, 'src')
+    assert.equal(mount.options.fields[0].value, '固定文案')
+    assert.equal(mount.options.fields[1].value, read)
+    assert.deepEqual(Object.keys(mount.options.fields[2].diff), ['before', 'after', 'path'])
+    assert.equal(mount.options.fields[2].diff.before, read)
+    assert.equal(warnings.length, 0)
+
+    const bad = normalizeMount({ tool: 'edit', fields: [{ param: 'x', value: 7 }] }, 'src')
+    assert.deepEqual(bad.mount.options.fields, [])
+    assert.equal(bad.warnings.length, 1)
+    assert.match(bad.warnings[0], /fields\[0\]\.value/)
+  })
+
+  it('drops a malformed diff instead of letting the field render as markdown', () => {
+    const bad = normalizeMount({ tool: 'edit', diff: { before: 'old_string' } }, 'src')
+    assert.equal(bad.mount.options.diff, undefined)
+    assert.equal(bad.warnings.length, 1)
+    assert.match(bad.warnings[0], /^src: diff\.before and diff\.after/)
+
+    const fieldLevel = normalizeMount({
+      tool: 'edit', fields: [{ param: 'x', diff: { before: 'a', after: 'b', path: 7 } }],
+    }, 'src')
+    assert.equal('diff' in fieldLevel.mount.options.fields[0], false)
+    assert.equal(fieldLevel.warnings.length, 1)
+    assert.match(fieldLevel.warnings[0], /fields\[0\]\.diff\.path/)
+  })
+
+  it('bounds a computed field with resolveTimeoutMs, defaulting from the protocol', () => {
+    assert.equal(normalizeMount({ tool: 'bash' }, 'src').mount.options.resolveTimeoutMs, DEFAULT_OPTIONS.resolveTimeoutMs)
+    assert.equal(normalizeMount({ tool: 'bash', resolveTimeoutMs: 250 }, 'src').mount.options.resolveTimeoutMs, 250)
+    assert.equal(normalizeMount({ tool: 'bash', resolveTimeoutMs: 0 }, 'src').mount.options.resolveTimeoutMs, DEFAULT_OPTIONS.resolveTimeoutMs)
+  })
+
   it('reports a bad layout, unavailable policy, and modify mode', () => {
     const { mount, warnings } = normalizeMount({
       tool: 'bash', layout: 'grid', whenUnavailable: 'maybe', modify: { mode: 'ignore' }, maxFieldChars: -1, labels: ['ok', 3],