dsh-hitl 0.1.2 → 0.2.0

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/)
 
@@ -146,6 +146,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 +155,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 +163,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,22 +412,22 @@ 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
@@ -436,7 +463,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

@@ -159,6 +159,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 +168,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 +176,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,22 +474,22 @@ 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 资源形状
@@ -505,7 +531,7 @@ dsh-hitl/
 
 ```sh
 node --check index.js client.js lib/*.js     # 语法
-npm test                                     # 153 个纯函数/状态机/通道用例，零依赖
+npm test                                     # 167 个纯函数/状态机/通道用例，零依赖
 npm run check                                # 上面两步合起来（语法 + 全部用例）
 ```
 

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.0",
   "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],