dsh-acp-enhanced 0.6.0 → 0.7.0

package/README-zh.md

@@ -72,7 +72,9 @@ ACP 线上。
   （列表以等宽代码块排版，一眼全见），其余（`/compact` `/goal` `/permission`
   `/plan`…）直通 harness 命令注册表，全部**不经过模型 turn** 即时执行。所有
   userInvocable 技能也会作为命令广播，`/ask-matt`、`/code-review`、`/tdd` 等能被
-  编辑器放行到达桥，技能正文按 dsh-tool-skill 的用户调用方式注入消息
+  编辑器放行到达桥，技能正文按 dsh-tool-skill 的用户调用方式注入消息。斜杠命令
+  旁粘贴的图片会作为命令附件随行（例如 `/goal` 目标的参考截图），与 Web 端
+  composer 的提交方式一致
 
 ### MCP
 
@@ -185,34 +187,13 @@ node scripts/acp-client.mjs                    # 官方默认路由，无需 env
 DSH_ACP_PROVIDER=... DSH_ACP_MODEL=... node scripts/acp-client.mjs   # 自定义路由时再传
 ```
 
-### 可选：web_search 走同一个网关
+### Web 搜索
 
-若网关实现 OpenAI Responses 的 `web_search` 服务端工具，可把搜索也路由到网关（复用
-同一凭据）。装子包并给 profile 的 `cordis.patch.yml` 追加两段：
-
-```sh
-dsh plugin --profile acp-enhanced add dsh-web-search-openrouter
-```
-
-```yaml
-- id: web
-  config:
-    searchProvider: openai-responses   # 子包注册在 ctx.web 上的搜索 provider id（固定值）
-
-- insert:
-    - id: web-search-openrouter
-      name: 'dsh-web-search-openrouter'
-      config:
-        enabled: true
-        baseURL: http://<gateway-host>:<port>/v1
-        model: <your-model-id>
-        apiKeyEnv: <KEY_ENV_NAME>
-```
-
-> ⚠️ `searchProvider` 必须**精确等于** `openai-responses`——这是
-> `dsh-web-search-openrouter` 注册在 `ctx.web` 上的搜索 provider id，**不是**网关的
-> LLM provider id（即上面 `DSH_ACP_PROVIDER` 填的那个）。web 插件按 id 精确匹配，
-> 填错时配置期不会报错，直到首次搜索才抛 `WEB_PROVIDER_CONFIGURED_MISSING`。
+bridge 自身不携带、也不推荐任何搜索 provider：模型侧 `web_search` 工具走 `web`
+seam 的 `searchProvider`，往 profile 里挂任意 `ctx.web` provider 即可——带
+`dsh.bundle` 的包用 `dsh plugin --profile acp-enhanced add <package>` 安装，普通包
+走用户层 `insert` 挂载（见下节）。你的 dsh 部署里有哪些 provider 是 profile 层的
+事，与 bridge 无关。
 
 ### 管理 profile 的插件
 
@@ -226,8 +207,8 @@ profile 的插件树由三层组合而成，后层修补前层：
    `@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`——就靠它装配）。
+   覆写、`disabled: true` 行禁用，以及 `insert` 挂载（无 `dsh.bundle` 的包——如手工
+   挂载的自写 provider——就靠它装配）。
 3. **临时覆盖**：`dsh --profile acp-enhanced --patch extra.yml`。
 
 调整插件集：
@@ -252,18 +233,71 @@ dsh --profile acp-enhanced --dump-config             # 查看组合后的完整
   ```
 
 - **无 `dsh.bundle` 的包自身不会装配**——它只作为普通依赖安装（带一次性警告），需要
-  像上面的 `web-search-openrouter` 行那样在用户层 `insert` 挂载；要改已有行的配置，
-  用 `- id: <行>` + `config:` 覆写——patch 条目是整行替换、不做合并。
+   自己在用户层 `insert` 挂载；要改已有行的配置，用 `- id: <行>` + `config:` 覆写——
+   patch 条目是整行替换、不做合并。
 
 改动在**下一个**进程生效：Zed 为每个 agent 线程拉起一个全新的
 `dsh --profile acp-enhanced`，编辑 profile 后新开 agent 线程（或重启 Zed）即可。
 
+## 兼容性
+
+同一个桥可运行在 **0.1.0-rc.6** 至 **0.1.2-rc.1** 的每一代 harness 上。0.1.2 线重写了本桥消费的多个
+API，桥在运行期同时吸收各代——不分叉、不加版本开关：
+
+| API | ≤ 0.1.1-rc.2（旧代） | ≥ 0.1.2-alpha.2（projection 代） | 桥的做法 |
+|---|---|---|---|
+| 会话的运行中 preset | `resolveSessionPreset({header, events})` 导出 | 导出已移除；`agentPreset` session projection | 自行折叠事件日志（最后一个 `agent-preset/selected` 胜出、header 兜底）——两代语义一致 |
+| preset 解析失败 | `UnknownPresetError` / `PresetMountError` | `RemoteError`，错误码 `agent-preset/*` | `isPresetClientError`：RemoteError 按 `isDSHRemoteError` + `code` 鸭子类型识别；旧类按 `presetId` 结构识别（绝不跨副本 `instanceof`） |
+| `permissionPresets.current(x)` | `current(events)` | `current(session)`（经 `permissionState`） | `currentPermissionMode` 每次调用前探测服务实例 |
+| 会话事件日志读取 | 同步 `session.events` 数组 | `session.events` 已移除（0.1.2-rc.1）；改为 `snapshotEvents()` / `ownEvents()` / `eventAt()` | `sessionEventsOf`：有 `snapshotEvents()` 用之，否则用活数组 |
+| 注册表 `execute` 签名 | `execute(agent, line, signal)` | `execute(agent, line, images, signal)`（images 插在 line 与 signal 之间，0.1.1-rc.1 起） | `executeRegistryCommand` 按声明参数个数探测（`Remote` 装饰器不包裹方法） |
+| `userQuestions` 注册 | `registerProvider({ask})` | `user-questions/request` Cordis waterfall（0.1.2-alpha.2 起） | 探测服务实例；waterfall 监听只应答本桥会话、其余经 `next()` 传递 |
+
+两条不变量保证其安全性（openma 的 `deepseek-harness-acp` 适配器独立得出了同样结论）：**只值导入纯
+helper**（`createUserMessage`、`ReasoningEffortId`、`SessionId`、`defineTool`…… 外来副本功能等价）；**服务的代际问题按服务实例探测回答**——决定服务代际的是启动它的 CLI，不是本包的依赖范围。`dsh-agent-presets`
+按 *命名空间* 导入：0.1.2-alpha.1 删除了其命名导出，命名导入会在 ESM 链接期直接失败。
+
+从干净依赖树校验两代：
+
+```sh
+node scripts/compat-check.mjs   # 分别安装 0.1.0-rc.6 与 0.1.2-alpha.2+ 两套，逐一导入本桥
+```
+
+### 开发检出：仓库锁定 CLI + 独立 home
+
+启动器**从检出目录**（`link:` 安装）运行时，按以下顺序解析 dsh CLI：
+
+1. `$DSH_PATH` —— 显式指定的 dsh 二进制，或其 `node_modules/.bin/dsh` 内含 dsh 的目录
+2. 仓库锁定的 CLI —— `<repo>/node_modules/.bin/dsh`（本包的 `@deepseek-ai/dsh`
+   devDependency，当前 0.1.2-rc.1）
+3. 全局兜底 —— PATH / npx 缓存 / npm 前缀 里的 `dsh`（旧行为；未 `pnpm install` 的全新检出退化为它）
+
+命中 (1) 或 (2) 时，profile 在**独立 home**（`DSH_ACP_HOME`，默认 `~/.dsh-acp`）下启动：dsh
+每次启动都会把自身依赖闭包 heal 进 `$DSH_HOME/profiles/node_modules`——该目录被同 home 下所有
+profile 共享、内容随最后启动的 CLI 翻转——因此第二个 CLI 代际不得与运行中的 `dsh web`
+等共享 home。此路径永不触碰默认 home。harness 注入到子进程的 `DSH_HOME=$HOME/.dsh`
+（dsh 会向每个 agent/工具进程导出它）会被识别并覆盖而非沿用；只有指向默认 home 之外的
+`DSH_HOME` 才被尊重；确要将锁定 CLI 跑在默认 home 上，请显式设 `DSH_ACP_HOME=$HOME/.dsh`。
+
+一次性引导独立 home（建**不含** `dsh-mnemon` 的 profile——它不支持 0.1.2-alpha harness——并逐字移植旧
+profile 的用户层行、迁移凭据/设置、挂 0.1.2-alpha `standard` preset 所需的
+`subagent-model-selection-settings` 宿主服务、关闭 DeepSeek 插件清单上报）：
+
+```sh
+scripts/init-acp-home.sh            # 幂等；重跑不会覆盖你的文件
+```
+
+两代 harness 都把会话持久化在 `$DSH_HOME/sessions/<slug>/<id>/session.jsonl.zstd`，且新代可读旧代日志（已验证：历史回放与 preset 折叠跨代工作）。因此旧线程只需把会话历史拷到新 home——`scripts/init-acp-home.sh` 会打印这条命令（或加 `--copy-sessions`）；默认不拷贝，因为默认 home 的目录里还有全部 web profile 会话。
+
 ## 故障排查
 
 | 症状 | 处理 |
 |---|---|
 | `exec: dsh: not found`（status 127） | 用随附 `dsh-acp-zed.sh` 启动器（自定位 node/dsh） |
 | `no API key for provider route "xxx"` | 写入 `~/.dsh/.credentials.yaml`，或在 agent_servers 里设 `env.DEEPSEEK_API_KEY` |
+| `SyntaxError: ... 'PresetMountError'` | 你在 0.1.2-alpha 宿主上运行 0.7.0 之前的桥副本——升级本包 |
+| `modelSelectionSettings requires ... in the Host scope` | 0.1.2-alpha 宿主缺少 `subagent-model-selection-settings` 行——运行 `scripts/init-acp-home.sh`（或按脚本模板在用户层补 insert 行） |
+| 宿主升级后旧线程变空白 | 会话存放在 `$DSH_HOME/sessions/<slug>/`；把旧 home 的历史拷进独立 home（`scripts/init-acp-home.sh --copy-sessions`）即可继续 |
 | 无法切换模型 | 保存的 `reasoning_effort` 默认值（或会话当前 effort）被带到新模型上。0.3.6 起本桥按模型记住上次使用的强度（随 profile 持久化）：不被新模型支持的 effort 会被该模型记忆值替换——没有记忆则回退其默认值，再无默认则取第一个可选值，既不会切换失败也不会出现 "unknown"。另检查：是否选到了不可路由的"幽灵 provider"——本桥默认过滤（只广播 `config.provider` 的模型），确认 profile 的 provider 指向真实路由 |
 | 上下文用量不显示 | 选到了不可路由的"幽灵 provider"；本桥默认过滤（只广播 `config.provider` 的模型），确认 profile 的 provider 指向真实路由 |
 | 需要详细诊断 | `ACP_DEBUG=1 dsh --profile acp-enhanced`（stderr 生命周期 trace） |
@@ -271,6 +305,7 @@ dsh --profile acp-enhanced --dump-config             # 查看组合后的完整
 ## 开发
 
 ```sh
+node scripts/compat-check.mjs         # 跨代链接检查（0.1.0-rc.6 + 0.1.2-alpha.2+ 临时安装）
 node scripts/acp-client.mjs           # 端到端冒烟（需要 API key）
 node scripts/acp-client-tools.mjs     # 客户端工具测试（模拟 Zed 的 fs/terminal/elicitation/plan）
 node scripts/acp-mcp-test.mjs         # MCP 挂载测试（无模型调用）
@@ -279,8 +314,21 @@ node scripts/acp-resume-test.mjs      # 会话恢复测试
 node scripts/codec-image-test.mjs     # 图片编解码单元测试（无网络，假 store）
 node scripts/terminal-codec-test.mjs  # 终端卡片编解码单元测试（无网络）
 node scripts/acp-image-e2e.mjs        # 图片能力端到端（vision 模型段需 API key）
+scripts/init-acp-home.sh              # 引导/刷新独立 home（~/.dsh-acp）
 ```
 
+harness 包的 devDependency 与锁定的 `@deepseek-ai/dsh` CLI 声明相同的 range（如
+`^0.1.2-rc.1`），让仓库依赖树与全新 CLI 安装解析出同一个连贯家族——在此用精确 patch
+锁定、与 CLI 的 range 闭包混存会得到分裂闭包（同名包两个版本），profile 启动时报
+export-not-found。改这些锁定后务必整体重建 lockfile（`rm -rf node_modules pnpm-lock.yaml
+&& pnpm install`）：原地增量安装既会留下污染 profile heal 的残留 store 条目，还会保留
+lockfile 里的陈旧 peer 解析——从 0.1.2-alpha.2 原地升到 0.1.2-rc.1 时，rc.1 各包的
+snapshot 里仍挂着 `dsh-session-persistence@0.1.2-alpha.3`（旧代 peer），boot 与
+session/new 全部通过，直到第一个 turn 才以 `TypeError: Cannot read properties of
+undefined (reading 'length')`（PersistenceCoordinator）崩掉。`pnpm-workspace.yaml` 放行
+了 CLI 闭包的构建脚本（node-pty prebuild、koffi）——仓库 CLI 启动 profile 时它们就是
+运行时依赖。
+
 ## 已知限制
 
 不支持音频附件（不声明 audio 能力）、文本按块粒度流式、每会话同时一个 in-flight

package/README.md

@@ -85,7 +85,9 @@ over the ACP wire.
   through the harness command registry — all executed **without a model turn**. Every
   user-invocable skill is advertised as a command too, so `/ask-matt`, `/code-review`,
   `/tdd`, … reach the bridge instead of being rejected by the editor, and the skill's
-  instructions are injected into the message (dsh-tool-skill-style user invocation)
+  instructions are injected into the message (dsh-tool-skill-style user invocation).
+  Images pasted next to a slash line ride along as command attachments (e.g. reference
+  screenshots for a `/goal` objective), the same way the Web composer submits them
 
 ### MCP
 
@@ -220,36 +222,14 @@ node scripts/acp-client.mjs                    # official default route, no env;
 DSH_ACP_PROVIDER=... DSH_ACP_MODEL=... node scripts/acp-client.mjs   # only for a custom route
 ```
 
-### Optional: route web_search through the same gateway
+### Web search
 
-If the gateway implements the OpenAI Responses `web_search` server tool, you can route
-search through it too (reusing the same credential). Install the sub-package and append
-two blocks to the profile's `cordis.patch.yml`:
-
-```sh
-dsh plugin --profile acp-enhanced add dsh-web-search-openrouter
-```
-
-```yaml
-- id: web
-  config:
-    searchProvider: openai-responses   # the search provider id this sub-package registers on ctx.web (fixed value)
-
-- insert:
-    - id: web-search-openrouter
-      name: 'dsh-web-search-openrouter'
-      config:
-        enabled: true
-        baseURL: http://<gateway-host>:<port>/v1
-        model: <your-model-id>
-        apiKeyEnv: <KEY_ENV_NAME>
-```
-
-> ⚠️ `searchProvider` must be **exactly** `openai-responses` — the search provider id
-> `dsh-web-search-openrouter` registers on `ctx.web`. It is **not** your gateway's LLM
-> provider id (the one you put in `DSH_ACP_PROVIDER` above). The `web` plugin matches it
-> exactly, so a wrong value produces no error at config time and only fails at the first
-> search with `WEB_PROVIDER_CONFIGURED_MISSING`.
+The bridge ships no search provider and takes no position on which one you use: the
+model-facing `web_search` tool rides on the `web` seam's `searchProvider`, so mount any
+`ctx.web` provider into the profile — a package with `dsh.bundle` via
+`dsh plugin --profile acp-enhanced add <package>`, or a plain package via your user-layer
+`insert` rows (see below). Which provider exists in your dsh deployment is a profile
+concern, not a bridge one.
 
 ### Managing the profile's plugins
 
@@ -265,7 +245,7 @@ before it:
    `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
+   package without `dsh.bundle` — e.g. a hand-mounted custom provider — gets
    mounted).
 3. **Per-run overlays** — `dsh --profile acp-enhanced --patch extra.yml`.
 
@@ -294,20 +274,83 @@ consequences worth knowing:
 
 - **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.
+  layer. 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.
 
+## Compatibility
+
+One bridge binary runs against every harness generation from **0.1.0-rc.6** through
+**0.1.2-rc.1**. The 0.1.2 line rewrote three APIs this bridge consumes, and the
+bridge absorbs every generation at runtime — no fork, no version flag:
+
+| API | ≤ 0.1.1-rc.2 (legacy) | ≥ 0.1.2-alpha.2 (projection) | Bridge behavior |
+|---|---|---|---|
+| running preset of a session | `resolveSessionPreset({header, events})` export | export removed; `agentPreset` session projection | folds the log itself (last `agent-preset/selected` wins, header fallback) — identical semantics in both |
+| preset resolution failure | `UnknownPresetError` / `PresetMountError` | `RemoteError`, codes `agent-preset/*` | `isPresetClientError`: RemoteError duck-typed by `isDSHRemoteError` + `code`, legacy classes identified structurally by `presetId` (never cross-copy `instanceof`) |
+| `permissionPresets.current(x)` | `current(events)` | `current(session)` (via `permissionState`) | `currentPermissionMode` probes the service instance per call |
+| session event log reads | synchronous `session.events` array | `session.events` removed (0.1.2-rc.1); `snapshotEvents()` / `ownEvents()` / `eventAt()` | `sessionEventsOf` reads `snapshotEvents()` when present, the live array otherwise |
+| registry `execute` signature | `execute(agent, line, signal)` | `execute(agent, line, images, signal)` (images between line and signal, 0.1.1-rc.1+) | `executeRegistryCommand` probes the declared arity (the `Remote` decorator never wraps the method) |
+| `userQuestions` registration | `registerProvider({ask})` | `user-questions/request` Cordis waterfall (0.1.2-alpha.2+) | probes the service instance; waterfall listener answers bridge-owned requests and delegates via `next()` |
+
+Two invariants make this safe (same conclusions the openma `deepseek-harness-acp` adapter
+reached independently): **value-import pure helpers only** (`createUserMessage`,
+`ReasoningEffortId`, `SessionId`, `defineTool`, … — a foreign copy is functionally
+equivalent), and **service-generation questions are answered by probing the service
+instance**, because the booting CLI — not this package's dependency range — decides the
+service generation. `dsh-agent-presets` is imported as a *namespace*: 0.1.2-alpha.1
+removed its named exports, and a named import would fail at ESM link time.
+
+Check both generations from a clean tree:
+
+```sh
+node scripts/compat-check.mjs   # installs 0.1.0-rc.6 + 0.1.2-alpha.2+ sets, imports the bridge from each
+```
+
+### Dev checkout: repo-pinned CLI, isolated home
+
+When the launcher runs **from a checkout** (`link:` install), it resolves the dsh CLI in
+this order:
+
+1. `$DSH_PATH` — an explicit dsh binary, or a directory whose `node_modules/.bin/dsh` holds one
+2. the repo-pinned CLI — `<repo>/node_modules/.bin/dsh` (this package's `@deepseek-ai/dsh`
+   devDependency, currently 0.1.2-rc.1)
+3. global fallback — `dsh` on PATH / npx cache / npm prefix (the legacy behavior; a fresh
+   clone without `pnpm install` degrades to it)
+
+Whenever (1) or (2) wins, the profile boots under an **isolated home**
+(`DSH_ACP_HOME`, default `~/.dsh-acp`): dsh heals its whole dependency closure into
+`$DSH_HOME/profiles/node_modules` on every boot — a dir shared by every profile under that
+home whose content flips to whichever CLI booted last — so a second CLI generation must not
+share a home with e.g. a running `dsh web`. The default home is never touched by this path.
+Harness-injected `DSH_HOME=$HOME/.dsh` in the child environment (dsh exports it into every
+agent/tool process) is detected and overridden, not honored — only a `DSH_HOME` pointing
+away from the default home is respected; to force the pinned CLI onto the default home,
+set `DSH_ACP_HOME=$HOME/.dsh` deliberately.
+
+Bootstrap the isolated home once (profile without `dsh-mnemon` — it does not support the
+0.1.2-alpha harness — plus your old profile's user rows ported verbatim and credentials/settings
+migration, the `subagent-model-selection-settings` host service the 0.1.2-alpha `standard`
+preset requires, and the DeepSeek plugin-package inventory reporter disabled):
+
+```sh
+scripts/init-acp-home.sh            # idempotent; re-runs never clobber your files
+```
+
+Both harness generations persist sessions under `$DSH_HOME/sessions/<slug>/<id>/session.jsonl.zstd`, and the new generation reads old-generation logs (verified: history replay and the preset fold work cross-generation). Old threads therefore only need their session history copied to the new home — `scripts/init-acp-home.sh` prints the one-liner (or pass `--copy-sessions`); it copies nothing by default, because the default home's tree also holds every web-profile session.
+
 ## Troubleshooting
 
 | Symptom | Fix |
 |---|---|
 | `exec: dsh: not found` (status 127) | Use the shipped `dsh-acp-zed.sh` launcher (locates node/dsh itself) |
 | `no API key for provider route "xxx"` | Write `~/.dsh/.credentials.yaml`, or set `env.DEEPSEEK_API_KEY` on the agent_servers entry |
+| `SyntaxError: ... 'PresetMountError'` | You are running a pre-0.7.0 bridge copy against a 0.1.2-alpha host — update this package |
+| `modelSelectionSettings requires ... in the Host scope` | A 0.1.2-alpha host without the `subagent-model-selection-settings` row — run `scripts/init-acp-home.sh` (or add the insert row to your user layer, see the script) |
+| Old threads start empty after a host upgrade | The sessions live under `$DSH_HOME/sessions/<slug>/`; copy the old home's history to the isolated home (`scripts/init-acp-home.sh --copy-sessions`) and the new host resumes them |
 | Cannot switch models | The saved `reasoning_effort` default (or the session's current effort) is carried onto the new model. Since 0.3.6 the bridge remembers the last effort per model (per-profile JSON): an unsupported carried effort is replaced by that model's remembered effort, else its own default, else its first offered effort — never an "unknown" dropdown, never a failed switch. Also check: a "phantom provider" route was picked — this bridge filters them by default (only `config.provider`'s models are advertised), so point the profile's provider at a real route |
 | Context usage missing | A "phantom provider" route was picked; this bridge filters them by default (only `config.provider`'s models are advertised) — point the profile's provider at a real route |
 | Need detailed diagnostics | `ACP_DEBUG=1 dsh --profile acp-enhanced` (stderr lifecycle trace) |
@@ -315,16 +358,33 @@ restart Zed) after editing the profile.
 ## Development
 
 ```sh
+node scripts/compat-check.mjs         # cross-generation link check (0.1.0-rc.6 + 0.1.2-alpha.2+ scratch installs)
 node scripts/acp-client.mjs           # end-to-end smoke (needs an API key)
 node scripts/acp-client-tools.mjs     # client-tool tests (mocks Zed fs/terminal/elicitation/plan)
 node scripts/acp-mcp-test.mjs         # MCP mount test (no model calls)
 node scripts/acp-smoke-keyless.mjs    # keyless boot smoke (CI)
 node scripts/acp-resume-test.mjs      # session resume test
 node scripts/codec-image-test.mjs     # image-codec unit tests (no network, fake store)
-node scripts/terminal-codec-test.mjs  # terminal-card codec unit tests (no network)
+node scripts/terminal-codec-test.mjs   # terminal-card codec unit tests (no network)
 node scripts/acp-image-e2e.mjs        # image capability e2e (vision-model leg needs an API key)
+scripts/init-acp-home.sh              # bootstrap/refresh the isolated home (~/.dsh-acp)
 ```
 
+DevDependency pins for the harness packages use the same ranges the pinned
+`@deepseek-ai/dsh` CLI declares (e.g. `^0.1.2-rc.1`), so the repo's tree and a fresh
+CLI install resolve one coherent family — exact patch pins here mixed with the CLI's
+range-resolved closure produce a split closure (two versions of one name) that breaks
+profile boots with export-not-found errors. After changing those pins, regenerate the
+whole lockfile (`rm -rf node_modules pnpm-lock.yaml && pnpm install`): an incremental
+install both leaves stale store entries poisoning the profile heal AND retains stale
+lockfile peer resolutions — bumping 0.1.2-alpha.2 → 0.1.2-rc.1 in place left
+`dsh-session-persistence@0.1.2-alpha.3` (old-generation peers) wired into the rc.1
+packages' snapshots, which passes boot and session/new and only breaks the first turn
+with `TypeError: Cannot read properties of undefined (reading 'length')` from
+PersistenceCoordinator.
+`pnpm-workspace.yaml` approves the CLI closure's build scripts (node-pty prebuilds, koffi)
+— they are runtime requirements when the repo CLI boots the profile.
+
 ## Known limitations
 
 Audio attachments are not supported (audio capability is not advertised), text streams at

package/lib/codec.js

@@ -57,6 +57,44 @@ export function promptHasUnsupportedContent(prompt) {
   return prompt.some((block) => block.type !== 'text' && block.type !== 'resource_link')
 }
 
+/**
+ * Flatten an ACP prompt's text blocks to the line a composer submits: text
+ * blocks concatenate verbatim in wire order, while images and resource links
+ * are composer attachments, not input-box text. This is the line slash
+ * commands are parsed from — an image pasted next to a slash line must neither
+ * prefix it nor pollute its arguments (the Web composer's `matchEnter`
+ * contract: line text plus a separate images payload).
+ * @param prompt - ACP `session/prompt` content, in wire order.
+ * @returns the concatenated text-block content.
+ */
+export function acpPromptLineText(prompt) {
+  return (prompt ?? []).flatMap((block) => block?.type === 'text' && typeof block.text === 'string' ? [block.text] : []).join('')
+}
+
+/**
+ * Build the composer's image payload for a slash-command submission from an
+ * ACP prompt: one `{ data, mediaType, name? }` upload object per image block,
+ * in wire order — the registry `execute` images slot's exact shape (the
+ * composer serializes `{ type: 'image', mediaType, data, name }`, and the
+ * command service's `admitEncodedImages` reads `data`/`mediaType`/`name`).
+ * The service admits the payload into the attachment store itself; the store
+ * is content-addressed, so an image `convertPrompt` already saved resolves to
+ * the same reference and nothing is duplicated. An image whose media type is
+ * not a raster cannot reach a command (`convertPrompt` rejects it before
+ * dispatch), so a non-raster here is simply skipped.
+ * @param prompt - ACP `session/prompt` content, in wire order.
+ * @returns upload objects ready for `commands.execute`'s images slot.
+ */
+export function acpPromptCommandImages(prompt) {
+  return (prompt ?? []).flatMap((block) => {
+    if (block?.type !== 'image' || typeof block.data !== 'string' || block.data.length === 0) return []
+    const mediaType = canonicalImageMediaType(block.mimeType)
+    if (mediaType === undefined) return []
+    const name = imageName(block.uri)
+    return [{ data: block.data, mediaType, ...name === undefined ? {} : { name } }]
+  })
+}
+
 /** Raster media types the harness attachment seam admits (dsh-attachment). */
 const IMAGE_MEDIA_TYPES = new Set(['image/png', 'image/jpeg', 'image/webp', 'image/gif'])
 

package/lib/index.js

@@ -45,11 +45,21 @@ import Schema from '@deepseek-ai/schemastery'
 import { AgentSideConnection, ndJsonStream, PROTOCOL_VERSION, RequestError } from '@agentclientprotocol/sdk'
 import { createUserMessage, errorChain, ReasoningEffortId } from '@deepseek-ai/dsh-llm'
 import { installModelSelection } from '@deepseek-ai/dsh-agent'
-import { resolveSessionPreset, UnknownPresetError, PresetMountError } from '@deepseek-ai/dsh-agent-presets'
+// Version tolerance: every harness value this bridge imports is a pure helper
+// (no service identity), so a copy resolved from this package's own
+// node_modules is functionally equivalent to the host tree's even when the
+// booting CLI pins a different generation. dsh-agent-presets is the one
+// exception in kind, not in rule: 0.1.2-alpha.1 removed its named exports
+// (resolveSessionPreset, UnknownPresetError, PresetMountError), so a named
+// import would fail at ESM link time on that generation. It is imported as a
+// namespace instead; nothing is taken from it at link time (see
+// isPresetClientError, which uses the legacy classes only through guarded
+// property access).
+import * as agentPresetsModule from '@deepseek-ai/dsh-agent-presets'
 import { renderSkillContent } from '@deepseek-ai/dsh-skill'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import { SessionId } from '@deepseek-ai/dsh-session'
-import { attachmentIngestOf, convertPrompt, PromptImageError, sanitizeWireTitle, turnEndToStopReason, UnsupportedPromptContentError, usageTelemetry } from './codec.js'
+import { attachmentIngestOf, acpPromptCommandImages, acpPromptLineText, convertPrompt, PromptImageError, sanitizeWireTitle, turnEndToStopReason, UnsupportedPromptContentError, usageTelemetry } from './codec.js'
 import { isTerminalToolName, parseShellExitStatus, resultText, shellCallCwd, stripShellPrefix, toolKindFor } from './terminal-codec.js'
 
 /** Agent version advertised on the ACP wire — read from package.json so the
@@ -432,6 +442,34 @@ export function apply(ctx, config) {
   /** Resolve the permission-presets service, tolerating a lazy mount. */
   const permissionPresets = () => ctx.get('permissionPresets')
 
+  /**
+   * Read one session's committed events as an array, tolerant of both harness
+   * API generations: 0.1.2-rc.1 replaced the synchronous `session.events`
+   * getter with `snapshotEvents()` (a cached frozen snapshot, invalidated on
+   * every append — plus `ownEvents()`/`eventAt()`), while earlier generations
+   * expose the live log array directly.
+   */
+  const sessionEventsOf = (session) => (
+    typeof session.snapshotEvents === 'function' ? session.snapshotEvents() : session.events
+  )
+
+  /** The effective permission preset of one session, across harness
+   *  generations: 0.1.2-alpha resolves through the permissions session
+   *  projection (`current(session)`), while earlier generations fold the
+   *  event log (`current(events)`). Probed per service instance —
+   *  the booting CLI decides the service's generation, so this package's
+   *  dependency range is not evidence. The probe is `permissionState`, a
+   *  0.1.2-alpha method; passing the wrong argument shape to either
+   *  generation does not throw reliably (the projection path can silently
+   *  answer the default state), so the probe is load-bearing. The legacy
+   *  event-log argument goes through sessionEventsOf (0.1.2-rc.1 sessions
+   *  no longer expose a synchronous `events` array). */
+  const currentPermissionMode = (permission, session) => (
+    typeof permission.permissionState === 'function'
+      ? permission.current(session)
+      : permission.current(sessionEventsOf(session))
+  )
+
   /**
    * The terminal-output meta dialect the connected client renders, exactly as
    * codex-acp resolves it: Zed declares `_meta.terminal_output` support on
@@ -458,8 +496,41 @@ export function apply(ctx, config) {
   }
 
   /** The preset a session actually runs, read from its log: the last
-   *  `agent-preset/selected` event wins over the creation header. */
-  const runningPresetOf = (session) => resolveSessionPreset(session)
+   *  `agent-preset/selected` event wins over the creation header. Folded here
+   *  rather than resolved through dsh-agent-presets so the read is
+   *  generation-agnostic: the legacy `resolveSessionPreset` export and the
+   *  0.1.2-alpha `agentPreset` session projection define this exact fold —
+   *  the last selection event wins, the creation header is the fallback, and
+   *  a deployment that composes none yields `undefined`. */
+  const runningPresetOf = (session) => {
+    const events = sessionEventsOf(session)
+    for (let index = events.length - 1; index >= 0; index -= 1) {
+      const event = events[index]
+      if (event?.type === 'agent-preset/selected') return event.data.agentPreset
+    }
+    return session.header.agentPreset
+  }
+
+  /** Whether a preset-resolution failure is the caller's setup mistake (an
+   *  unknown or unmountable preset id) rather than a server fault; callers
+   *  map it to invalid params. Generation-tolerant across the dsh 0.1.x
+   *  line: 0.1.2-alpha throws RemoteError with a stable `agent-preset/*`
+   *  code — identified structurally (`isDSHRemoteError`), never instanceof,
+   *  because that class lives in the host tree; earlier generations throw
+   *  UnknownPresetError / PresetMountError, which both carry `presetId`.
+   *  instanceof against the namespace-imported classes stays as a last
+   *  resort for deployments where the roster service and this module
+   *  happened to resolve the same package copy. */
+  const isPresetClientError = (error) => {
+    if (!(error instanceof Error)) return false
+    if (error.isDSHRemoteError === true) {
+      return typeof error.code === 'string' && error.code.startsWith('agent-preset/')
+    }
+    if (error.presetId !== undefined) return true
+    const { UnknownPresetError, PresetMountError } = agentPresetsModule
+    return (UnknownPresetError !== undefined && error instanceof UnknownPresetError)
+      || (PresetMountError !== undefined && error instanceof PresetMountError)
+  }
 
   /** Whether one live session has produced anything yet. A preset swap is only
    *  legal while it is blank (dsh-agent-presets product rule): swapping tools
@@ -467,7 +538,7 @@ export function apply(ctx, config) {
    *  make. Checks both the live turn marker and persisted user messages, so the
    *  same rule holds for resumed sessions whose on-disk logs may not carry
    *  `turn/start`. */
-  const isBlankSession = (session) => !session.events.some((event) => (
+  const isBlankSession = (session) => !sessionEventsOf(session).some((event) => (
     event.type === 'turn/start' || event.type === 'user/message'
   ))
 
@@ -484,7 +555,7 @@ export function apply(ctx, config) {
    *
    * @param requested - preset id, or undefined for the roster default.
    * @returns `{ agentPreset, setup }`, or `{}` without a roster.
-   * @throws UnknownPresetError / PresetMountError (mapped by callers).
+   * @throws a roster resolution failure (isPresetClientError — mapped by callers).
    */
   async function composePreset(requested) {
     const presets = agentPresets()
@@ -510,7 +581,7 @@ export function apply(ctx, config) {
     try {
       const { meta, events } = await persistence.load(sessionId)
       return {
-        preset: resolveSessionPreset({ header: meta, events }),
+        preset: runningPresetOf({ header: meta, events }),
         blank: isBlankSession({ header: meta, events }),
       }
     } catch {
@@ -1132,7 +1203,7 @@ export function apply(ctx, config) {
         name: 'Permission preset',
         description: 'Sandbox mode and approval policy bundle for this session.',
         category: 'mode',
-        currentValue: permission.current(record.agent.session.events),
+        currentValue: currentPermissionMode(permission, record.agent.session),
         options: permission.names.map((presetName) => {
           const spec = permission.presets[presetName]
           return {
@@ -1480,96 +1551,116 @@ export function apply(ctx, config) {
           }
         },
       })))
-      // The UI provider that renders those questions as an editor form.
-      clientToolDisposers.push(userQuestions.registerProvider({
-        ask: async (request) => {
-          const record = ownedRecord(request.agent)
-          if (record === undefined) {
-            throw new Error('ask_user_question is only usable inside a bridge-owned session')
+      // The UI provider that renders those questions as an editor form. The
+      // registration seam differs per harness generation, so it is probed on
+      // the service instance (whose generation is the booting CLI's) rather
+      // than assumed from this package's imports — migration plan rule 2.1.3:
+      // ≤0.1.1-rc.2 exposes `userQuestions.registerProvider({ ask })` (one
+      // active provider); ≥0.1.2-alpha.2 removed that method and asks
+      // answerers to listen on the `user-questions/request` Cordis waterfall
+      // instead, claiming a request by returning an answer or delegating it
+      // via `next()`.
+      const answerQuestion = async (request) => {
+        const record = ownedRecord(request.agent)
+        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 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', oneOf: titled, description: question.question, ...heading }
           }
-          // 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 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', 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.',
-              }
+          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({
-            sessionId: record.agent.session.id,
-            mode: 'form',
-            message: request.questions.map((question) => question.question).join('\n'),
-            requestedSchema: { type: 'object', properties, required },
-          })
-          if (response.action !== 'accept') {
-            throw new Error(`the user ${response.action === 'decline' ? 'declined' : 'cancelled'} the question`)
-          }
-          const content = response.content ?? {}
-          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] : []
-              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,
-              }
-            }),
-          }
-        },
-      }))
+        }
+        const response = await conn.unstable_createElicitation({
+          sessionId: record.agent.session.id,
+          mode: 'form',
+          message: request.questions.map((question) => question.question).join('\n'),
+          requestedSchema: { type: 'object', properties, required },
+        })
+        if (response.action !== 'accept') {
+          throw new Error(`the user ${response.action === 'decline' ? 'declined' : 'cancelled'} the question`)
+        }
+        const content = response.content ?? {}
+        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] : []
+            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,
+            }
+          }),
+        }
+      }
+      if (typeof userQuestions.registerProvider === 'function') {
+        // Legacy generation (≤0.1.1-rc.2): one active provider on the service.
+        clientToolDisposers.push(userQuestions.registerProvider({ ask: answerQuestion }))
+      } else {
+        // Projection generation (≥0.1.2-alpha.2): answer the
+        // `user-questions/request` waterfall. A listener on the root context
+        // is untagged, so the scoped dispatch admits it for every agent; a
+        // request this bridge does not own is delegated to the next answerer
+        // (falling through to NO_PROVIDER when no one else claims it).
+        clientToolDisposers.push(ctx.on('user-questions/request', async (request, next) => {
+          if (ownedRecord(request.agent) === undefined) return next()
+          return answerQuestion(request)
+        }))
+      }
     }
   }
 
@@ -1824,6 +1915,32 @@ export function apply(ctx, config) {
     return `switched to agent preset ${preset.id}`
   }
 
+  /**
+   * Execute one registry slash command, tolerant of both harness API
+   * generations. dsh-commands 0.1.1-rc.1+ admits composer images between the
+   * line and the cancellation signal (`execute(agent, line, images, signal)`,
+   * images as `{ data, mediaType, name }` upload objects), while 0.1.0-rc.x
+   * took `(agent, line, signal)` and could not carry images. Calling the
+   * newer shape against the older service lands the signal in the images slot
+   * and leaves `signal` undefined (`signal.aborted` throws), and the reverse
+   * lands an array where the signal belongs — so the shapes must be probed,
+   * not guessed. The declared arity is a faithful probe: the `Remote`
+   * decorator only records a marker initializer and never wraps the method,
+   * so `execute.length` equals the declared parameter count (3 on 0.1.0-rc.x,
+   * 4 on 0.1.1-rc.1+). Images accompanying a slash line only reach the older
+   * generation when an attachment store is also mounted, which the 0.1.0-rc.x
+   * seam never provides (convertPrompt rejects them before dispatch) — so the
+   * legacy call needs no images handling.
+   */
+  function executeRegistryCommand(agent, line, prompt) {
+    const signal = new AbortController().signal
+    const execute = commands.execute
+    if (typeof execute.length === 'number' && execute.length >= 4) {
+      return execute.call(commands, agent, line, acpPromptCommandImages(prompt), signal)
+    }
+    return execute.call(commands, agent, line, signal)
+  }
+
   /** Refresh every client-visible surface a command may have mutated. */
   function refreshAfterCommand(record) {
     const permission = permissionPresets()
@@ -1832,7 +1949,7 @@ export function apply(ctx, config) {
         sessionId: record.agent.session.id,
         update: {
           sessionUpdate: 'current_mode_update',
-          currentModeId: permission.current(record.agent.session.events),
+          currentModeId: currentPermissionMode(permission, record.agent.session),
         },
       })
     }
@@ -1964,7 +2081,7 @@ export function apply(ctx, config) {
    * steps, usage, plan flips, …) is omitted.
    */
   async function replayHistory(record) {
-    const events = record.agent.session.events
+    const events = sessionEventsOf(record.agent.session)
     for (const event of events) {
       try {
         switch (event.type) {
@@ -2069,66 +2186,71 @@ export function apply(ctx, config) {
       },
 
       async newSession(params) {
-        assertOpen()
-        const additionalDirectories = normalizeSessionParams(params)
-        const sessionId = SessionId(randomUUID())
-        const requestedPreset = process.env.DSH_ACP_PRESET ?? config.preset
-        let composition
         try {
-          composition = await composePreset(requestedPreset)
-        } catch (error) {
-          // A bad DSH_ACP_PRESET / preset config is a client-side setup mistake,
-          // not a server fault: surface the roster's detail as invalid params.
-          const detail = error instanceof Error ? error.message : String(error)
-          if (error instanceof UnknownPresetError || error instanceof PresetMountError) {
-            throw invalidParams(detail)
+          assertOpen()
+          const additionalDirectories = normalizeSessionParams(params)
+          const sessionId = SessionId(randomUUID())
+          const requestedPreset = process.env.DSH_ACP_PRESET ?? config.preset
+          let composition
+          try {
+            composition = await composePreset(requestedPreset)
+          } catch (error) {
+            // A bad DSH_ACP_PRESET / preset config is a client-side setup mistake,
+            // not a server fault: surface the roster's detail as invalid params.
+            const detail = error instanceof Error ? error.message : String(error)
+            if (isPresetClientError(error)) {
+              throw invalidParams(detail)
+            }
+            throw error
           }
-          throw error
-        }
-        const handle = await agents.create({
-          sessionId,
-          meta: {
-            cwd: params.cwd,
-            ...composition.agentPreset === undefined ? {} : { agentPreset: composition.agentPreset },
-          },
-          agentOptions: {
-            ...config.provider === undefined ? {} : { provider: config.provider },
-            ...config.model === undefined ? {} : { model: config.model },
-          },
-          ...composition.setup === undefined ? {} : { setup: composition.setup },
-        })
-        if (closed) {
-          await handle.dispose()
-          throw internalError('connection closed during session/new')
-        }
-        const record = makeRecord(handle)
-        record.additionalDirectories = additionalDirectories
-        sessions.set(sessionId, record)
-        await syncMcpServers(params.mcpServers, params.cwd)
-        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 ? {} : {
-            modes: {
-              currentModeId: permission.current(handle.agent.session.events),
-              availableModes: permission.names.map((presetName) => {
-                const spec = permission.presets[presetName]
-                return {
-                  id: presetName,
-                  name: spec?.name ?? presetName,
-                  ...spec?.description === undefined ? {} : { description: spec.description },
-                }
-              }),
+          const handle = await agents.create({
+            sessionId,
+            meta: {
+              cwd: params.cwd,
+              ...composition.agentPreset === undefined ? {} : { agentPreset: composition.agentPreset },
             },
-          },
-          configOptions,
+            agentOptions: {
+              ...config.provider === undefined ? {} : { provider: config.provider },
+              ...config.model === undefined ? {} : { model: config.model },
+            },
+            ...composition.setup === undefined ? {} : { setup: composition.setup },
+          })
+          if (closed) {
+            await handle.dispose()
+            throw internalError('connection closed during session/new')
+          }
+          const record = makeRecord(handle)
+          record.additionalDirectories = additionalDirectories
+          sessions.set(sessionId, record)
+          await syncMcpServers(params.mcpServers, params.cwd)
+          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 ? {} : {
+              modes: {
+                currentModeId: currentPermissionMode(permission, handle.agent.session),
+                availableModes: permission.names.map((presetName) => {
+                  const spec = permission.presets[presetName]
+                  return {
+                    id: presetName,
+                    name: spec?.name ?? presetName,
+                    ...spec?.description === undefined ? {} : { description: spec.description },
+                  }
+                }),
+              },
+            },
+            configOptions,
+          }
+        } catch (error) {
+          if (process.env.ACP_DEBUG) process.stderr.write(`[acp-debug] newSession failed: ${error?.stack ?? String(error)}\n`)
+          throw error
         }
       },
 
@@ -2152,7 +2274,7 @@ export function apply(ctx, config) {
           return {
             ...permission === undefined ? {} : {
               modes: {
-                currentModeId: permission.current(live.agent.session.events),
+                currentModeId: currentPermissionMode(permission, live.agent.session),
                 availableModes: permission.names.map((presetName) => {
                   const spec = permission.presets[presetName]
                   return { id: presetName, name: spec?.name ?? presetName }
@@ -2170,7 +2292,7 @@ export function apply(ctx, config) {
           // Same mapping as session/new: a roster that cannot supply the
           // session's logged preset is reported as a client mistake.
           const detail = error instanceof Error ? error.message : String(error)
-          if (error instanceof UnknownPresetError || error instanceof PresetMountError) {
+          if (isPresetClientError(error)) {
             throw invalidParams(detail)
           }
           throw error
@@ -2203,7 +2325,7 @@ export function apply(ctx, config) {
         return {
           ...permission === undefined ? {} : {
             modes: {
-              currentModeId: permission.current(record.agent.session.events),
+              currentModeId: currentPermissionMode(permission, record.agent.session),
               availableModes: permission.names.map((presetName) => {
                 const spec = permission.presets[presetName]
                 return {
@@ -2260,8 +2382,13 @@ export function apply(ctx, config) {
         // permission/plan/…) runs through the harness command registry
         // without a model turn. An unresolved slash falls through — the
         // /skill-name gesture is claimed inside the agent's next step.
-        const trimmed = text.trim()
-        const commandMatch = trimmed.match(/^\/(\w[\w-]*)\b/)
+        // The command line is the prompt's text blocks, not the display
+        // text: pasted images are composer attachments riding alongside the
+        // line (forwarded to the registry as a separate images payload), and
+        // their `[image: …]` display placeholders must neither prefix the
+        // line (which would hide the slash) nor pollute its arguments.
+        const commandLine = acpPromptLineText(params.prompt).trim()
+        const commandMatch = commandLine.match(/^\/(\w[\w-]*)\b/)
         const respond = (reply) => {
           notify({
             sessionId: record.agent.session.id,
@@ -2275,17 +2402,17 @@ export function apply(ctx, config) {
         }
         if (commandMatch?.[1] === 'status') return respond(await statusText(record))
         if (commandMatch?.[1] === 'model') {
-          return respond(await modelCommandText(record, trimmed.slice(commandMatch[0].length).trim()))
+          return respond(await modelCommandText(record, commandLine.slice(commandMatch[0].length).trim()))
         }
         if (commandMatch?.[1] === 'preset') {
-          const reply = await presetCommandText(record, trimmed.slice(commandMatch[0].length).trim())
+          const reply = await presetCommandText(record, commandLine.slice(commandMatch[0].length).trim())
           refreshAfterCommand(record)
           return respond(reply)
         }
         if (commandMatch !== null && commandMatch[1] !== undefined) {
           let execution
           try {
-            execution = await commands.execute(record.agent, trimmed, new AbortController().signal)
+            execution = await executeRegistryCommand(record.agent, commandLine, params.prompt)
           } catch (error) {
             return respond(`⚠ /${commandMatch[1]} failed: ${error.message ?? String(error)}`)
           }
@@ -2432,7 +2559,7 @@ export function apply(ctx, config) {
               // unknown/broken preset id is a client mistake (invalid params),
               // while a composition that fails to mount is a server fault.
               const detail = error instanceof Error ? error.message : String(error)
-              if (error instanceof UnknownPresetError || error instanceof PresetMountError) {
+              if (isPresetClientError(error)) {
                 throw invalidParams(detail)
               }
               throw internalError(detail)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-acp-enhanced",
-  "version": "0.6.0",
+  "version": "0.7.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",
@@ -38,38 +38,39 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.1-rc.1",
-    "@deepseek-ai/cordis-plugin-include": "^1.0.6-rc.1",
-    "@deepseek-ai/cordis-plugin-loader": "^1.0.2-rc.1",
-    "@deepseek-ai/dsh-agent": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-agent-instructions": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-agent-presets": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-mcp-client": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-permission-presets": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-session": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-session-query": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-skill": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-user-approval": "^0.1.0-rc.6"
+    "@deepseek-ai/cordis": "^4.0.1-rc.1 || ^4.0.2",
+    "@deepseek-ai/cordis-plugin-include": "^1.0.6-rc.1 || ^1.0.7",
+    "@deepseek-ai/cordis-plugin-loader": "^1.0.2-rc.1 || ^1.0.3",
+    "@deepseek-ai/dsh-agent": "^0.1.0-rc.6 || ^0.1.1-rc.1 || ^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-agent-instructions": "^0.1.0-rc.6 || ^0.1.1-rc.1 || ^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-agent-presets": "^0.1.0-rc.6 || ^0.1.1-rc.1 || ^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6 || ^0.1.1-rc.1 || ^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-llm": "^0.1.0-rc.6 || ^0.1.1-rc.1 || ^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-mcp-client": "^0.1.0-rc.6 || ^0.1.1-rc.1 || ^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-permission-presets": "^0.1.0-rc.6 || ^0.1.1-rc.1 || ^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-session": "^0.1.0-rc.6 || ^0.1.1-rc.1 || ^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-session-query": "^0.1.0-rc.6 || ^0.1.1-rc.1 || ^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-skill": "^0.1.0-rc.6 || ^0.1.1-rc.1 || ^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6 || ^0.1.1-rc.1 || ^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-user-approval": "^0.1.0-rc.6 || ^0.1.1-rc.1 || ^0.1.2-alpha.2"
   },
   "devDependencies": {
-    "@deepseek-ai/cordis": "4.0.1-rc.4",
-    "@deepseek-ai/cordis-plugin-include": "1.0.6-rc.4",
-    "@deepseek-ai/cordis-plugin-loader": "1.0.2-rc.4",
-    "@deepseek-ai/dsh-agent": "0.1.0-rc.6",
-    "@deepseek-ai/dsh-agent-instructions": "0.1.0-rc.6",
-    "@deepseek-ai/dsh-agent-presets": "0.1.0-rc.6",
-    "@deepseek-ai/dsh-invariants": "0.1.0-rc.6",
-    "@deepseek-ai/dsh-llm": "0.1.0-rc.6",
-    "@deepseek-ai/dsh-mcp-client": "0.1.0-rc.6",
-    "@deepseek-ai/dsh-permission-presets": "0.1.0-rc.6",
-    "@deepseek-ai/dsh-session": "0.1.0-rc.6",
-    "@deepseek-ai/dsh-session-query": "0.1.0-rc.6",
-    "@deepseek-ai/dsh-skill": "0.1.0-rc.6",
-    "@deepseek-ai/dsh-tools": "0.1.0-rc.6",
-    "@deepseek-ai/dsh-user-approval": "0.1.0-rc.6"
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/cordis-plugin-include": "^1.0.7",
+    "@deepseek-ai/cordis-plugin-loader": "^1.0.3",
+    "@deepseek-ai/dsh": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-agent": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-agent-instructions": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-agent-presets": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-mcp-client": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-permission-presets": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-session": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-session-query": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-skill": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-tools": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-user-approval": "^0.1.2-rc.1"
   },
   "license": "MIT",
   "author": {

package/scripts/dsh-acp-zed.sh

@@ -4,15 +4,35 @@
 # Zed (a GUI app) spawns agent processes with a minimal PATH that usually does
 # NOT include node or dsh, so this wrapper locates both itself:
 #   - node: PATH, /opt/homebrew/bin, /usr/local/bin, ~/.nvm/versions/node/*
-#   - dsh:  PATH, the npx cache (~/.npm/_npx/*/node_modules/.bin), the global
-#           npm prefix bin dir, /opt/homebrew/bin, /usr/local/bin
 # and prepends the node dir to PATH so dsh's `#!/usr/bin/env node` shebang
 # resolves.
 #
+# dsh CLI resolution (ecosystem order, cf. the DSH_PATH convention):
+#   1. $DSH_PATH — an explicit dsh binary, or a directory whose
+#      node_modules/.bin/dsh holds one
+#   2. the repo-pinned CLI: <repo>/node_modules/.bin/dsh (this package's
+#      @deepseek-ai/dsh devDependency — the version the bridge tracks)
+#   3. global fallback: PATH, the npx cache (~/.npm/_npx/*/node_modules/.bin),
+#      the global npm prefix bin dir, /opt/homebrew/bin, /usr/local/bin
+#
+# Isolated DSH_HOME: dsh heals its whole dependency closure into
+# $DSH_HOME/profiles/node_modules on every boot — a dir shared by every
+# profile under that home, whose content flips to whichever CLI booted last.
+# A second CLI generation under one home would let a running profile (e.g.
+# `dsh web`) lazily resolve mismatched module versions mid-process. So
+# whenever (1) or (2) resolves the CLI, this launcher boots the profile under
+# its own home: DSH_HOME=${DSH_ACP_HOME:-$HOME/.dsh-acp} (exported only when
+# DSH_HOME is not already set). The default home and the global `dsh web`
+# stack stay untouched; the global fallback (3) keeps the default home and
+# the pre-existing profile there, so a fresh clone without `pnpm install`
+# degrades to the legacy behavior. Create the isolated-home profile once with
+# scripts/init-acp-home.sh.
+#
 # The profile resolves DEEPSEEK_API_KEY through the dsh credentials service
-# (~/.dsh/.credentials.yaml), so no environment plumbing is required; an
-# explicit DEEPSEEK_API_KEY from Zed's agent_servers.env wins, and a running
-# `dsh web` process is a final fallback source.
+# (~/.dsh/.credentials.yaml — copied into the isolated home by the same
+# script), so no environment plumbing is required; an explicit
+# DEEPSEEK_API_KEY from Zed's agent_servers.env wins, and a running `dsh web`
+# process is a final fallback source.
 #
 # stdout stays the ACP JSON-RPC wire; diagnostics go to stderr.
 set -u
@@ -33,24 +53,75 @@ if [ -n "${NODE_BIN}" ]; then
   export PATH="$(dirname "${NODE_BIN}"):${PATH}"
 fi
 
-DASH_BIN="$(command -v dsh 2>/dev/null || true)"
-if [ -z "${DASH_BIN}" ]; then
-  for candidate in \
-    "$HOME"/.npm/_npx/*/node_modules/.bin/dsh \
-    "$(npm prefix -g 2>/dev/null)/bin/dsh" \
-    /opt/homebrew/bin/dsh \
-    /usr/local/bin/dsh; do
-    if [ -x "${candidate}" ]; then
-      DASH_BIN="${candidate}"
-      break
-    fi
-  done
+# The repo root: resolve this script through symlinks (the profile links this
+# package from the repo) with pwd -P, so the pinned CLI is found even when
+# the launcher is reached via node_modules/.
+REPO_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd -P)"
+
+DASH_BIN=""
+DSH_SOURCE=""
+if [ -n "${DSH_PATH:-}" ]; then
+  # 1. Explicit override: a dsh binary, or a directory containing one under
+  # node_modules/.bin (e.g. a dsh checkout).
+  if [ -x "${DSH_PATH}" ]; then
+    DASH_BIN="${DSH_PATH}"
+  elif [ -x "${DSH_PATH}/node_modules/.bin/dsh" ]; then
+    DASH_BIN="${DSH_PATH}/node_modules/.bin/dsh"
+  else
+    echo "dsh-acp-zed: DSH_PATH is set but holds no dsh ('${DSH_PATH}')" >&2
+    exit 127
+  fi
+  DSH_SOURCE="dshpath"
+elif [ -x "${REPO_DIR}/node_modules/.bin/dsh" ]; then
+  # 2. Repo-pinned CLI (this package's devDependency).
+  DASH_BIN="${REPO_DIR}/node_modules/.bin/dsh"
+  DSH_SOURCE="repo"
+else
+  # 3. Global fallback (legacy resolution).
+  DASH_BIN="$(command -v dsh 2>/dev/null || true)"
+  if [ -z "${DASH_BIN}" ]; then
+    for candidate in \
+      "$HOME"/.npm/_npx/*/node_modules/.bin/dsh \
+      "$(npm prefix -g 2>/dev/null)/bin/dsh" \
+      /opt/homebrew/bin/dsh \
+      /usr/local/bin/dsh; do
+      if [ -x "${candidate}" ]; then
+        DASH_BIN="${candidate}"
+        break
+      fi
+    done
+  fi
+  DSH_SOURCE="global"
 fi
 if [ -z "${NODE_BIN}" ] || [ -z "${DASH_BIN}" ]; then
   echo "dsh-acp-zed: cannot locate node and/or dsh (node='${NODE_BIN}' dsh='${DASH_BIN}'); install them or set PATH" >&2
   exit 127
 fi
 
+# The isolated home applies whenever the CLI came from DSH_PATH or the repo
+# pin — never for the global fallback, which shares the default home with the
+# rest of the machine. An exported DSH_HOME is honored only when it points
+# AWAY from the default home: harness processes inject DSH_HOME=$HOME/.dsh
+# into every child (agents, tools), and honoring that inherited value here
+# would boot the pinned CLI against the shared default home — flipping its
+# module-fallback closure under a running profile. To force the pinned CLI
+# onto the default home deliberately, set DSH_ACP_HOME=$HOME/.dsh.
+ISOLATED_HOME=0
+if [ "${DSH_SOURCE}" != "global" ]; then
+  ISOLATED_HOME=1
+  if [ -z "${DSH_HOME:-}" ] || [ "${DSH_HOME}" = "$HOME/.dsh" ]; then
+    export DSH_HOME="${DSH_ACP_HOME:-$HOME/.dsh-acp}"
+  fi
+fi
+
+# Guard the isolated-home path: booting a profile without the bridge installed
+# would start an agent stack that never speaks ACP on stdio, which Zed reports
+# as an opaque hang. Point at the one-shot setup script instead.
+if [ "${ISOLATED_HOME}" = 1 ] && [ ! -d "${DSH_HOME}/profiles/acp-enhanced" ]; then
+  echo "dsh-acp-zed: profile 'acp-enhanced' missing under the isolated home '${DSH_HOME}'; bootstrap it once with: ${REPO_DIR}/scripts/init-acp-home.sh" >&2
+  exit 127
+fi
+
 if [ -z "${DEEPSEEK_API_KEY:-}" ]; then
   WEB_PID="$(pgrep -f 'dsh web' | head -n 1)"
   if [ -n "${WEB_PID}" ]; then
@@ -68,8 +139,12 @@ fi
 # on the profile root. The bridge persists small per-model state (the last
 # reasoning effort per model) next to the profile's own files.
 if [ -z "${DSH_ACP_PROFILE_DIR:-}" ]; then
-  ACP_LAUNCHER_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -L)"
-  export DSH_ACP_PROFILE_DIR="$(cd "${ACP_LAUNCHER_DIR}/../../.." && pwd -L)"
+  if [ "${ISOLATED_HOME}" = 1 ]; then
+    export DSH_ACP_PROFILE_DIR="${DSH_HOME}/profiles/acp-enhanced"
+  else
+    ACP_LAUNCHER_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -L)"
+    export DSH_ACP_PROFILE_DIR="$(cd "${ACP_LAUNCHER_DIR}/../../.." && pwd -L)"
+  fi
 fi
 
 exec "${DASH_BIN}" --profile acp-enhanced "$@"