dsh-hitl 0.1.1 → 0.2.0

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,9 +261,23 @@ 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 !== '')
     : []
+  const countdown = normalizeCountdown(input.countdown, report)
+  const unavailable = WHEN_UNAVAILABLE.includes(whenUnavailable)
+    ? whenUnavailable
+    : DEFAULT_OPTIONS.whenUnavailable
+  // `wait` is fail-open by design: with no browser attached the call sits there
+  // until something ends it. Without a countdown, "something" means the session
+  // or the plugin, so an unattended run blocks an agent for as long as it lives.
+  // Say so at mount time rather than letting the first unattended run discover it.
+  if (unavailable === 'wait' && countdown === null) {
+    report('whenUnavailable: wait without a countdown blocks an unattended call until its session ends; pair it with countdown.seconds or use the fail-closed default')
+  }
   const mount = {
     describe: matcher.describe,
     test: matcher.test,
@@ -225,15 +287,14 @@ export function normalizeMount(input, source) {
       labels,
       buttons: normalizeButtons(input.buttons, report),
       fields,
-      diff: input.diff,
-      countdown: normalizeCountdown(input.countdown, report),
+      diff: normalizeDiff(input.diff, report, 'diff'),
+      countdown,
       reject: normalizeReject(input.reject, report),
       modify: normalizeModify(input.modify, report),
-      whenUnavailable: WHEN_UNAVAILABLE.includes(whenUnavailable)
-        ? whenUnavailable
-        : DEFAULT_OPTIONS.whenUnavailable,
+      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.1",
+  "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",
@@ -39,7 +39,6 @@
     "lib",
     "tests",
     "locale",
-    "docs",
     "icon.svg",
     "cordis.patch.yml",
     "README.md",

package/tests/docs.test.js

@@ -15,6 +15,8 @@ import { fileURLToPath } from 'node:url'
  */
 const root = join(dirname(fileURLToPath(import.meta.url)), '..')
 
+const LANDING_PAGE = 'https://yunpengdon.github.io/dsh-hitl-landing/'
+
 /** The English README is the package's front page; the Chinese one is its twin. */
 const READMES = [
   { language: 'en', file: 'README.md', other: 'README.zh.md', suffix: '-en' },
@@ -62,21 +64,22 @@ describe('docs: the English and Chinese READMEs', () => {
     }
   })
 
-  it('shows every screenshot, and only its own language', () => {
-    const referenced = new Set()
-    const available = new Set(readdirSync(join(root, 'docs')))
+  it('sends the reader to the landing page instead of shipping screenshots', () => {
+    // The four screenshots used to be the bulk of the published tarball. They
+    // live on the landing page now (its own repository carries them, in both
+    // languages), so the READMEs must link it and must not reference a local
+    // copy — and the package must not carry one either.
+    const manifest = JSON.parse(read('package.json'))
+    assert.equal(manifest.files.includes('docs'), false, 'screenshots must stay out of the tarball')
     for (const readme of READMES) {
-      const images = [...read(readme.file).matchAll(/!\[[^\]]*\]\((docs\/[^)]+)\)/g)].map(match => match[1])
-      assert.equal(images.length, 4, `${readme.file} must place all four screenshots`)
-      for (const image of images) {
-        const name = image.slice('docs/'.length)
-        assert.equal(available.has(name), true, `${readme.file} references a missing screenshot: ${image}`)
-        assert.equal(name.endsWith(`${readme.suffix}.png`), true, `${readme.file} must use its ${readme.suffix} screenshots`)
-        referenced.add(name)
-      }
-    }
-    for (const name of available) {
-      assert.equal(referenced.has(name), true, `docs/${name} is shipped but never shown`)
+      const text = read(readme.file)
+      assert.equal(text.includes(LANDING_PAGE), true, `${readme.file} must link the landing page`)
+      assert.equal(
+        /!\[[^\]]*\]\(docs\//.test(text), false,
+        `${readme.file} must not embed a local screenshot`,
+      )
+      const header = text.split('\n').slice(0, 8).join('\n')
+      assert.equal(header.includes(LANDING_PAGE), true, `${readme.file} must offer the tour near the top`)
     }
   })
 
@@ -108,9 +111,11 @@ describe('docs: the English and Chinese READMEs', () => {
     }
   })
 
-  it('keeps the screenshot folder shipped', () => {
+  it('publishes both READMEs and keeps the screenshot sources in the repository only', () => {
     const manifest = JSON.parse(read('package.json'))
-    assert.equal(manifest.files.includes('docs'), true, '`docs` must be published with the screenshots')
     assert.equal(manifest.files.includes('README.zh.md'), true, 'the Chinese README must be published too')
+    // The landing page's own repository carries the screenshots, so a second
+    // copy inside the package would only double the download for every install.
+    assert.equal(manifest.files.includes('docs'), false, 'screenshot sources must stay out of the tarball')
   })
 })

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' })
+  })
+})