dsh-acp-enhanced 0.5.2 → 0.6.0

package/README-zh.md

@@ -51,7 +51,9 @@ ACP 线上。
   状态机为进行中 → 完成/失败
 - **Zed 文件与终端**：`zed_read_text_file` / `zed_write_text_file` / `zed_terminal` 把
   文件编辑放进 Zed 的"编辑文件"区（diff + 接受/拒绝）、命令跑在 Zed 真实终端
-- **原生表单提问**：`ask_user_question` → `elicitation/create` 表单，选项即点即答
+- **原生表单提问**：`ask_user_question` → `elicitation/create` 表单，选项即点即答；
+  选项带描述展示，每个带选项的问题附一个"自定义答案"输入框——选项都不合适时可自由输入，
+  单选时自定义答案覆盖所选、多选时与所选并存（与 dsh 原生提问卡片语义一致）
 - **Plan 面板**：plan mode 开关 → Zed 底部"规划中"状态条
 
 ### 会话
@@ -212,6 +214,50 @@ dsh plugin --profile acp-enhanced add dsh-web-search-openrouter
 > LLM provider id（即上面 `DSH_ACP_PROVIDER` 填的那个）。web 插件按 id 精确匹配，
 > 填错时配置期不会报错，直到首次搜索才抛 `WEB_PROVIDER_CONFIGURED_MISSING`。
 
+### 管理 profile 的插件
+
+dsh-acp-enhanced 跑在**独立的 profile** 里——`acp-enhanced`（由上面的安装命令创建于
+`~/.dsh/profiles/acp-enhanced/`），与 `dsh web` 背后的 `web` profile 完全隔离，
+在这里增删改插件不会影响 web 侧的任何配置。
+
+profile 的插件树由三层组合而成，后层修补前层：
+
+1. **bundle 层**：profile `package.json` 的 `dsh.profile.bundles`——模板自带的
+   `@deepseek-ai/dsh-base` 在前，随后是每个声明了 `dsh.bundle` 的已安装包（如
+   `dsh-acp-enhanced`），按数组顺序排列。
+2. **用户层**：`~/.dsh/profiles/acp-enhanced/cordis.patch.yml`——按 id 定位的行配置
+   覆写、`disabled: true` 行禁用，以及 `insert` 挂载（无 `dsh.bundle` 的包——如上面
+   的 `dsh-web-search-openrouter`——就靠它装配）。
+3. **临时覆盖**：`dsh --profile acp-enhanced --patch extra.yml`。
+
+调整插件集：
+
+```sh
+dsh plugin --profile acp-enhanced add <package>     # 安装；声明 dsh.bundle 的包自动加入层栈
+dsh plugin --profile acp-enhanced remove <package>  # 卸载；自动退出层栈
+dsh plugin --profile acp-enhanced update [package]  # 更新一个/全部并 reconcile
+dsh --profile acp-enhanced --dump-config             # 查看组合后的完整树（标注每行来自哪一层）
+```
+
+`dsh plugin` 本质是在 profile 目录里转发 pnpm，并在每次运行后按安装状态 reconcile
+`dsh.profile.bundles`。两个值得知道的推论：
+
+- **靠从 `bundles` 里删条目来禁用 bundle 是禁不住的**——包仍是已安装依赖，下一次
+  `dsh plugin` 运行会原样加回来。想不禁载地禁用某一行，请在用户层按**行 id**（不是
+  包名，id 可在 `--dump-config` 输出里查）定位：
+
+  ```yaml
+  - id: mnemon
+    disabled: true
+  ```
+
+- **无 `dsh.bundle` 的包自身不会装配**——它只作为普通依赖安装（带一次性警告），需要
+  像上面的 `web-search-openrouter` 行那样在用户层 `insert` 挂载；要改已有行的配置，
+  用 `- id: <行>` + `config:` 覆写——patch 条目是整行替换、不做合并。
+
+改动在**下一个**进程生效：Zed 为每个 agent 线程拉起一个全新的
+`dsh --profile acp-enhanced`，编辑 profile 后新开 agent 线程（或重启 Zed）即可。
+
 ## 故障排查
 
 | 症状 | 处理 |

package/README.md

@@ -59,7 +59,10 @@ over the ACP wire.
   put file edits into Zed's "edited files" area (diff + accept/reject) and commands into a
   real Zed terminal
 - **Native form questions**: `ask_user_question` → `elicitation/create` form, click an
-  option, no typing
+  option — or type a custom answer when none of them fit: options render with their
+  descriptions, each option-backed question gets a free-text "Custom answer" field, and a
+  custom answer replaces the single selection / accompanies a multi-select (same semantics
+  as dsh's native question card)
 - **Plan panel**: plan mode toggle → "planning" status bar in Zed
 
 ### Sessions
@@ -151,6 +154,21 @@ Zed spawns agents with a minimal PATH, so use the shipped launcher
 > store it in `~/.dsh/.credentials.yaml` (`DEEPSEEK_API_KEY`) and the dsh credentials
 > service resolves it; the launcher also falls back to a running `dsh web` process's key.
 
+Debugging a stalled turn (is it the model request or the tool?):
+
+```jsonc
+"env": {
+  // ...existing vars...
+  "ACP_LOG": "/Users/you/.dsh/dsh-acp-enhanced.trace.jsonl"  // append-only JSONL event trace
+}
+```
+
+Each line is one session event with wall-clock `time` (ms epoch); a turn that appears to
+hang is attributable afterwards: a **model request stall** shows a long gap between
+`step/start` and the first `assistant/chunk`, while a **tool-execution stall** shows a
+long gap between `tool/call` and `tool/result` (the result line carries `elapsedMs`).
+`prompt/settled` lines cover the full user-message round trip (stopReason + elapsed).
+
 Optional: pin the panel's default config options (all still changeable in the panel):
 
 ```jsonc
@@ -233,6 +251,57 @@ dsh plugin --profile acp-enhanced add dsh-web-search-openrouter
 > exactly, so a wrong value produces no error at config time and only fails at the first
 > search with `WEB_PROVIDER_CONFIGURED_MISSING`.
 
+### Managing the profile's plugins
+
+dsh-acp-enhanced runs in its **own profile** — `acp-enhanced`, created at
+`~/.dsh/profiles/acp-enhanced/` by the install command above — fully separate from the
+`web` profile behind `dsh web`, so plugin changes here never affect your web setup.
+
+The profile composes its plugin tree from three sources, each layer patching the ones
+before it:
+
+1. **Bundle layers** — `dsh.profile.bundles` in the profile's `package.json`: the
+   template's `@deepseek-ai/dsh-base` first, then every installed package that declares
+   `dsh.bundle` (like `dsh-acp-enhanced`), in array order.
+2. **Your user layer** — `~/.dsh/profiles/acp-enhanced/cordis.patch.yml`: id-targeted
+   row config overrides, `disabled: true` row disables, and `insert` lists (how a
+   package without `dsh.bundle` — like `dsh-web-search-openrouter` above — gets
+   mounted).
+3. **Per-run overlays** — `dsh --profile acp-enhanced --patch extra.yml`.
+
+Adjust the set with:
+
+```sh
+dsh plugin --profile acp-enhanced add <package>     # install; a dsh.bundle package auto-joins the layer stack
+dsh plugin --profile acp-enhanced remove <package>  # uninstall; auto-leaves the stack
+dsh plugin --profile acp-enhanced update [package]  # update one/all, then reconcile
+dsh --profile acp-enhanced --dump-config             # inspect the composed tree (per-layer provenance)
+```
+
+`dsh plugin` is a thin pnpm forwarder (run inside the profile directory) that
+reconciles `dsh.profile.bundles` against the installed state after every run. Two
+consequences worth knowing:
+
+- **Disabling a bundle by deleting it from `bundles` does not stick** — the package is
+  still an installed dependency, and the next `dsh plugin` run appends it right back.
+  To disable a single row without uninstalling, target it in the user layer by its
+  **row id** (not the package name — find ids in the `--dump-config` output):
+
+  ```yaml
+  - id: mnemon
+    disabled: true
+  ```
+
+- **A package without `dsh.bundle` loads nothing by itself** — it installs as a plain
+  dependency (with a one-time warning) and needs your own `insert` entry in the user
+  layer, like the `web-search-openrouter` row above. To change an existing row's
+  config, override it with `- id: <row>` + `config:` — patch entries replace the
+  whole row config, they do not merge.
+
+Changes take effect in the **next** process: Zed spawns a fresh
+`dsh --profile acp-enhanced` for every agent thread, so open a new agent thread (or
+restart Zed) after editing the profile.
+
 ## Troubleshooting
 
 | Symptom | Fix |

package/lib/index.js

@@ -126,6 +126,13 @@ export const Config = Schema.object({
    *  default. The `DSH_ACP_PRESET` environment variable overrides this value
    *  when set. */
   preset: Schema.string().default(undefined),
+  /** Optional JSONL trace of session events with wall-clock timestamps and
+   *  tool call durations. After a stalled turn, the log discriminates a hung
+   *  model request (long gap between `step/start` and the first
+   *  `assistant/chunk`) from a hung tool call (long `tool/call` →
+   *  `tool/result` gap). The `ACP_LOG` environment variable overrides this
+   *  value; unset disables tracing. */
+  logFile: Schema.string().default(undefined),
 })
 
 /** Preserve invalid-parameter detail in the SDK wire error message. */
@@ -399,6 +406,17 @@ export function apply(ctx, config) {
   const commands = ctx.commands
   const skills = ctx.skills
   const logger = ctx.logger
+  /** Optional JSONL trace target: config option, overridable by `ACP_LOG`
+   *  (mirrors `ACP_DEBUG`, which remains stderr-only). Every event carries a
+   *  wall-clock `time` so a stalled turn can be attributed to the model
+   *  request vs the tool execution afterwards. */
+  const tracePath = process.env.ACP_LOG || config.logFile
+  const trace = (entry) => {
+    if (tracePath === undefined) return
+    writeFile(tracePath, `${JSON.stringify({ time: Date.now(), ...entry })}\n`, { flag: 'a' }).catch((error) => {
+      logger.warn(`acp-enhanced: trace write failed: ${String(error)}`)
+    })
+  }
   /** The user-questions service (mounted by dsh-base); absent in minimal deployments. */
   const userQuestions = ctx.get('userQuestions')
 
@@ -691,6 +709,17 @@ export function apply(ctx, config) {
     const record = sessions.get(session.header.id)
     if (record === undefined || record.agent.session !== session) return
     try {
+      if (tracePath !== undefined) {
+        const extra = event.type === 'tool/call'
+          ? { name: event.data.name }
+          : event.type === 'tool/result'
+            ? { name: event.data.name ?? event.data.message?.content?.[0]?.name,
+              elapsedMs: record.toolStats.lastCallAt === undefined ? undefined : Date.now() - record.toolStats.lastCallAt }
+            : event.type === 'turn/end'
+              ? { elapsedMs: record.turnStartedAt === undefined ? undefined : Date.now() - record.turnStartedAt }
+              : {}
+        trace({ event: event.type, turn: event.data?.turn, step: event.data?.step, ...extra })
+      }
       if (process.env.ACP_DEBUG) {
         const extra = event.type === 'turn/end' ? ` reason=${JSON.stringify(event.data.reason)}` : event.type === 'assistant/chunk' ? ` chunkType=${event.data.chunk.type}` : event.type === 'agent/inbox/spliced' ? ` hasPending=${record.agent.inbox?.hasPending}` : event.type === 'tool/call' ? ` name=${event.data.name}` : ''
         process.stderr.write(`[acp-debug] ${event.type} turn=${event.data?.turn} step=${event.data?.step}${extra}\n`)
@@ -1038,6 +1067,13 @@ export function apply(ctx, config) {
 
   /** Build the full config-option set for one session. */
   async function buildConfigOptions(record) {
+    // Test hook (unset in production): artificial latency proving the
+    // response-vs-broadcast ordering holds even when config-option assembly
+    // spans real event-loop turns (the cold-runner condition that raced the
+    // command broadcast past the session/new response on CI).
+    if (process.env.DSH_TEST_SLOW_CATALOG_MS !== undefined) {
+      await new Promise((resolve) => setTimeout(resolve, Number(process.env.DSH_TEST_SLOW_CATALOG_MS) || 0))
+    }
     const selected = record.selection.current
     const options = []
     const groups = await modelCatalog()
@@ -1451,21 +1487,48 @@ export function apply(ctx, config) {
           if (record === undefined) {
             throw new Error('ask_user_question is only usable inside a bridge-owned session')
           }
+          // Editor forms cannot mix a fixed option list with free text in one
+          // field, so every option-backed question gains a companion
+          // `<id>__custom` text field: the form equivalent of dsh's native
+          // "type your own answer" row, for when none of the offered options
+          // fit. Option-free questions are already free-text fields.
+          const usedKeys = new Set(request.questions.map((question) => question.id))
+          const customKeys = new Map()
           const properties = {}
           const required = []
           for (const question of request.questions) {
             required.push(question.id)
-            const labels = (question.options ?? []).map((option) => option.label)
-            if (question.multiSelect === true) {
-              properties[question.id] = {
-                type: 'array',
-                ...labels.length > 0 ? { items: { type: 'string', enum: labels } } : { items: { type: 'string' } },
-                description: question.question,
-              }
-            } else if (labels.length > 0) {
-              properties[question.id] = { type: 'string', enum: labels, description: question.question }
+            const options = question.options ?? []
+            // Titled options (const/title/description) instead of a bare enum
+            // so Zed renders each option's description under its label, like
+            // the native question card. A question without options becomes a
+            // plain text field: an optionless multi-select would otherwise
+            // render as an empty, unanswerable checkbox list.
+            const titled = options.map((option) => ({
+              const: option.label,
+              title: option.label,
+              ...option.description === undefined ? {} : { description: option.description },
+            }))
+            const heading = question.header === undefined ? {} : { title: question.header }
+            if (options.length === 0) {
+              properties[question.id] = { type: 'string', description: question.question, ...heading }
+            } else if (question.multiSelect === true) {
+              properties[question.id] = { type: 'array', items: { anyOf: titled }, description: question.question, ...heading }
             } else {
-              properties[question.id] = { type: 'string', description: question.question }
+              properties[question.id] = { type: 'string', oneOf: titled, description: question.question, ...heading }
+            }
+            if (options.length > 0) {
+              let customKey = `${question.id}__custom`
+              while (usedKeys.has(customKey)) customKey = `${customKey}_`
+              usedKeys.add(customKey)
+              customKeys.set(question.id, customKey)
+              properties[customKey] = {
+                type: 'string',
+                title: 'Custom answer',
+                description: question.multiSelect === true
+                  ? 'None of the options fit? Type your own answer; it is returned alongside your selections.'
+                  : 'None of the options fit? Type your own answer; it replaces the selection.',
+              }
             }
           }
           const response = await conn.unstable_createElicitation({
@@ -1481,10 +1544,28 @@ export function apply(ctx, config) {
           return {
             answers: request.questions.map((question) => {
               const value = content[question.id]
+              const customKey = customKeys.get(question.id)
+              if (customKey === undefined) {
+                // Option-free question: the typed text IS the answer, reported
+                // as the custom ("other") answer the way the native UI does.
+                const text = typeof value === 'string' ? value.trim() : ''
+                return { id: question.id, selected: [], ...text === '' ? {} : { custom: text } }
+              }
               const selected = Array.isArray(value)
                 ? value.filter((entry) => typeof entry === 'string')
                 : typeof value === 'string' ? [value] : []
-              return { id: question.id, selected }
+              const customRaw = content[customKey]
+              const custom = typeof customRaw === 'string' && customRaw.trim() !== '' ? customRaw.trim() : undefined
+              if (custom === undefined) {
+                return { id: question.id, selected }
+              }
+              // A custom answer replaces a single selection and accompanies a
+              // multi-select, matching the native question card.
+              return {
+                id: question.id,
+                selected: question.multiSelect === true ? selected : [],
+                custom,
+              }
             }),
           }
         },
@@ -1647,6 +1728,16 @@ export function apply(ctx, config) {
    * cannot route session notifications for it until the response arrives; an
    * `available_commands_update` queued before that response is dropped and
    * the slash menu stays empty ("Available commands: none").
+   *
+   * Ordering contract: arm this only as the handler's LAST statement, after
+   * every await. The SDK serializes all outgoing messages through one FIFO
+   * write queue and enqueues the handler's response synchronously in the
+   * microtask continuation of the handler's promise, which strictly
+   * precedes this setImmediate (check phase). Arming before a remaining
+   * macrotask await (e.g. the config-option catalog build) lets the
+   * immediate fire first, the broadcast overtakes the response, and
+   * clients drop it — observed on CI as the broadcast landing before the
+   * session/new response.
    */
   function publishCommandsAfterResponse(record) {
     setImmediate(() => {
@@ -1955,7 +2046,7 @@ export function apply(ctx, config) {
             // additionalDirectories: multi-root workspaces (Zed passes every
             // workspace root on session/new / session/load instead of showing
             // the "doesn't currently support multi-root workspaces" callout).
-            sessionCapabilities: { list: {}, delete: {}, additionalDirectories: {} },
+            sessionCapabilities: { list: {}, delete: {}, additionalDirectories: {}, close: {} },
             // Image support is a live capability: the harness advertises
             // `image: true` only when the composition mounted a working
             // attachment store (duck-typed, so dsh 0.1.1-rc.2+ with
@@ -2014,8 +2105,14 @@ export function apply(ctx, config) {
         record.additionalDirectories = additionalDirectories
         sessions.set(sessionId, record)
         await syncMcpServers(params.mcpServers, params.cwd)
-        publishCommandsAfterResponse(record)
         const permission = permissionPresets()
+        const configOptions = await buildConfigOptions(record)
+        // Arm strictly after the handler's last await (see
+        // publishCommandsAfterResponse): the SDK enqueues the response into
+        // its FIFO write queue in the microtask continuation of this
+        // handler's promise, which always precedes the immediate — so the
+        // broadcast can never overtake the response.
+        publishCommandsAfterResponse(record)
         return {
           sessionId,
           ...permission === undefined ? {} : {
@@ -2031,7 +2128,7 @@ export function apply(ctx, config) {
               }),
             },
           },
-          configOptions: await buildConfigOptions(record),
+          configOptions,
         }
       },
 
@@ -2042,9 +2139,15 @@ export function apply(ctx, config) {
         const sessionId = SessionId(params.sessionId)
         const live = sessions.get(sessionId)
         if (live !== undefined) {
-          // Already live on this connection: return its state without replay.
-          // The client's root list is authoritative for the loaded workspace.
+          // Already live on this connection. The client is re-loading the
+          // session because it dropped its local thread (that is the only
+          // reason a load arrives for a session the client already knows), so
+          // replay the history — without it the client renders a blank thread
+          // and Zed misreads the empty thread as a draft, permanently losing
+          // the session linkage in its sidebar. The client's root list is
+          // authoritative for the loaded workspace.
           live.additionalDirectories = additionalDirectories
+          await replayHistory(live)
           const permission = permissionPresets()
           return {
             ...permission === undefined ? {} : {
@@ -2091,8 +2194,12 @@ export function apply(ctx, config) {
         // Zed inserts the thread before the load RPC completes; replay the
         // conversation history as notifications so the thread renders.
         await replayHistory(record)
-        publishCommandsAfterResponse(record)
         const permission = permissionPresets()
+        const configOptions = await buildConfigOptions(record)
+        // Arm strictly after the handler's last await (see
+        // publishCommandsAfterResponse): the broadcast must land after the
+        // load response, never before it.
+        publishCommandsAfterResponse(record)
         return {
           ...permission === undefined ? {} : {
             modes: {
@@ -2107,7 +2214,7 @@ export function apply(ctx, config) {
               }),
             },
           },
-          configOptions: await buildConfigOptions(record),
+          configOptions,
         }
       },
 
@@ -2216,6 +2323,7 @@ export function apply(ctx, config) {
         }
         const message = createUserMessage({ content: blocks, source: { kind: 'user' } })
         if (process.env.ACP_DEBUG) process.stderr.write(`[acp-debug] followup queued, agent phase=${record.agent.phase?.kind} inboxPending=${record.agent.inbox?.hasPending}\n`)
+        const promptAt = Date.now()
         const stopReason = await new Promise((resolve, reject) => {
           const inflight = {
             resolve,
@@ -2243,13 +2351,19 @@ export function apply(ctx, config) {
             }
           })
         })
+        trace({ event: 'prompt/settled', stopReason, elapsedMs: Date.now() - promptAt })
         return { stopReason }
       },
 
       cancel(params) {
         const record = sessions.get(SessionId(params.sessionId))
         if (record === undefined) return Promise.resolve()
-        record.agent.cancel({ kind: 'user' })
+        // An Error reason, not a bare object: the harness surfaces an aborted
+        // tool's signal reason verbatim into the tool result the model reads,
+        // so a plain object would render as the useless "Error: [object
+        // Object]" and push the model off the tool that was merely
+        // interrupted by the user's stop.
+        record.agent.cancel(new Error('cancelled by user'))
         settlePrompt(record, 'cancelled')
         return Promise.resolve()
       },
@@ -2383,6 +2497,24 @@ export function apply(ctx, config) {
         return { sessions: out }
       },
 
+      async closeSession(params) {
+        assertOpen()
+        const sessionId = SessionId(params.sessionId)
+        const live = sessions.get(sessionId)
+        if (live === undefined) return {}
+        sessions.delete(sessionId)
+        // The client released its last handle on this session (its thread was
+        // dropped). Dispose the in-memory record so a later session/load fully
+        // resumes from the persisted session; keeping it "live" would serve an
+        // empty thread with no history replay on the next load.
+        try {
+          await live.dispose()
+        } catch (error) {
+          logger.warn(`acp-enhanced: failed to dispose closed session ${sessionId}: ${String(error)}`)
+        }
+        return {}
+      },
+
       async deleteSession(params) {
         assertOpen()
         const sessionId = SessionId(params.sessionId)
@@ -2432,7 +2564,7 @@ export function apply(ctx, config) {
     const records = [...sessions.values()]
     sessions.clear()
     for (const record of records) {
-      record.agent.cancel({ kind: 'user' })
+      record.agent.cancel(new Error('cancelled because the session closed'))
       settlePrompt(record, 'cancelled')
     }
     for (const { fiber } of mcpMounts.values()) {

package/lib/terminal-codec.js

@@ -23,10 +23,15 @@ import { isAbsolute, resolve } from 'node:path'
  * diff replaces the raw dump as the card body. Remaining local executors like
  * run_code stay 'other' and carry the command as a markdown code block,
  * keeping the raw sections available too.
+ *
+ * Read tools map to 'read' so the bridge can pair the kind with ACP
+ * `locations` (the clickable file chips via `toolCallLocationsFor`): the bare
+ * dsh tool name is exactly `read`, so it must match by itself — `read_text`
+ * and `fs_*read` only cover the long-form names.
  */
 export function toolKindFor(name) {
   if (name === 'bash' || name === 'pwsh' || name === 'zed_terminal') return 'execute'
-  if (/^fs_.*read|read_text|cat|show/.test(name)) return 'read'
+  if (/^fs_.*read|^read$|read_text|cat|show/.test(name)) return 'read'
   if (/search|find|grep/.test(name)) return 'search'
   if (/fetch|http/.test(name)) return 'fetch'
   if (/think/.test(name)) return 'think'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-acp-enhanced",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "Enhanced ACP server for DeepSeek Harness: block-level streaming, usage/stat telemetry (cache hit rate, token speed, input/output tokens, context length, turns, tool timing), model & reasoning-effort switching, and permission-preset control over the ACP wire (Zed-friendly)",
   "keywords": [
     "dsh",