deepseek-computer-use 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 STARDUSTLC666
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,303 @@
-# Temporary Holding Version
+# deepseek-computer-use
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> 社区插件，**非 DeepSeek 官方出品**。官方包在 `@deepseek-ai/*` scope 下。
+
+给 DeepSeek Harness 的 **Windows 桌面控制（Computer Use）** 插件。
+
+工具面对齐 Codex 的 window2 API（`list_apps` / `list_windows` / `get_window` /
+`launch_app` / `get_window_state` / `click` / `press_key` / `type_text` / `scroll` /
+`set_value` / `drag` / `perform_secondary_action` / `activate_window` /
+`start_audio_recording` / `stop_audio_recording` / `computer_use_health`），底层是
+Windows 原生三件套：**UI Automation 观测 + SendInput 注入 + Windows.Graphics.Capture 抓屏**。
+
+零 npm 原生依赖、零 .NET 运行时依赖：helper 和覆盖层用系统自带的 `csc.exe` 现编，
+抓屏（WGC）和录音（WASAPI）是 net48 程序，Windows 10/11 自带运行时。
+
+## 安装
+
+要求：**Windows 10/11**、**Node ≥ 18.17**。其余都是系统组件（.NET Framework 4.8、
+UI Automation、WGC）。
+
+```bash
+# 发布到 npm 之后
+npm install --save deepseek-computer-use
+
+# 现在还只能用 GitHub 源
+npm install --save github:STARDUSTLC666/deepseek-computer-use
+```
+
+然后在本机 profile 的 `cordis.patch.yml` 里启用（详见本文件末尾的配置示例）：
+
+```yaml
+- insert:
+    - id: deepseek-computer-use
+      name: 'deepseek-computer-use'
+```
+
+首次调用任意 Computer Use 工具时会自动编译 helper 与覆盖层（约 1 秒）。
+想要抓屏/录音这两项可选能力，再跑一次：
+
+```bash
+npm run build          # helper + overlay（csc），再尝试 dotnet 编 capture/audio
+```
+
+没有 .NET SDK 也能用：抓屏自动退回 PrintWindow，录音会明确报 `audio_missing`。
+
+## 自检
+
+```bash
+npm test               # 13 项断言：注册、观测、点击、审批、硬拒绝、Esc 阻断
+npm run test:all       # 追加 helper 协议/音频 与插件级一致性测试
+```
+
+## 它解决什么问题
+
+DSH 本体没有鼠标键盘工具，只能跑命令、读写文件。需要"操作图形界面"时（点按钮、
+填表单、操作没有 API 的桌面软件），这个插件补上这一层，并且把每一步都变成**可观测、
+可审批、可验证**的动作。
+
+## 架构
+
+```text
+DSH 宿主
+  └─ lib/index.js        apply(ctx) → 注册 16 个工具；图片走 attachments；审批走 approval
+       ├─ lib/tools.js   工具定义（Codex window2 语义）
+       ├─ lib/safety.js  白名单/黑名单 + 危险动作审批门
+       └─ lib/bridge.js  常驻进程 + 串行 JSON-lines RPC + 超时/取消
+            └─ native/bin/dsh-computer-use-helper.exe   （用系统 csc.exe 现编）
+                 ├─ native/Driver.cs   IPlatformDriver 契约 + WindowsDriver（UIA / SendInput / PrintWindow）
+                 ├─ native/Json.cs     零依赖 JSON 解析与序列化
+                 └─ native/Program.cs  stdio 分发
+```
+
+驱动层是接口（`IPlatformDriver`），今天是 `windows` 一个实现；macOS（AX + CGEvent）
+和 Linux（AT-SPI）可以照着补，插件层不用改。
+
+helper 常驻的原因：元素编号必须和"那一次观测"绑在同一个进程里，否则
+`click(element_index)` 无从解析。因此插件串行发请求、按 id 配对响应。
+
+## 工具
+
+| 工具 | 作用 |
+|---|---|
+| `list_apps` | 列出当前有可操作窗口的应用及其窗口 |
+| `list_windows` | 列出可见窗口：id / 标题 / 所属应用 / z 序 / 边框 |
+| `get_window` | 按 id 重新读取窗口（换绑、刷新边框） |
+| `launch_app` | 启动应用（可带参数），默认需要审批 |
+| `get_window_state` | 观测：带编号的无障碍树 +（可选）窗口截图 |
+| `click` | 按元素编号（优先走 Invoke，抗遮挡）或窗口相对坐标点击 |
+| `press_key` | 单键或组合键，X keysym 风格：`Control_L+s`、`Return` |
+| `type_text` | 注入 Unicode 文本（与键盘布局无关，中文安全） |
+| `scroll` | 在坐标或元素处滚动 |
+| `drag` | 窗口内拖拽 |
+| `set_value` | 用 Value 模式直接改值，比"点击+全选+输入"更稳更省 |
+| `perform_secondary_action` | Invoke / Expand / Collapse / Toggle / Select / Scroll Up… |
+| `activate_window` | 把窗口提到前台 |
+| `start_audio_recording` | 开始录制系统音频（WASAPI 环回），需 `audio: true` |
+| `stop_audio_recording` | 停止录音并返回 WAV 路径与字节数 |
+| `computer_use_health` | 自检：helper、编译器、策略、窗口数 |
+
+## 使用中指示器（对齐 Codex 的两个 overlay）
+
+Codex 用两层覆盖层告诉用户"AI 正在动你的电脑"，这里做的是同一套：
+
+**Display Overlay — 呼吸细边**
+- 一圈 **1.4px 的强调色细线** + 3 层递减光环，圆角 18px；只占屏幕最外圈，不压内容
+- 亮度按约 3.2 秒周期呼吸（内线 alpha 170→240、光环 26→46）
+- 4 条边 + 4 个圆角 = 8 个细长分层窗口，每帧位图几 KB
+- 底部居中一枚自动宽度玻璃胶囊：脉冲圆点 + `DSH 正在使用您的电脑` +
+  `Esc` 键帽 + `取消`，停在任务栏上方留白
+
+**Cursor Overlay — 虚拟光标 + 系统光标抑制**
+- 覆盖层存在期间常驻一个带描边和投影的白色指针，启动时落在真实指针位置，
+  之后 0.35 缓动滑向每个动作点；背后一层极淡的强调色光晕
+- 默认抑制真实系统光标，退出/Esc/超时用 `SPI_SETCURSORS` 恢复；
+  helper 强杀覆盖层时也会兜底恢复一次
+
+**DPI 关键点**：覆盖层进程必须 Per-Monitor-V2 感知，否则在 150% 缩放屏上
+系统会把 1707×1067 的逻辑画面放大到 2560×1600，描边变糊、位置偏移 1.5 倍。
+
+**Esc 是按 turn 生效的**：首次触发报 `cancelled_by_user`，同一 turn 内后续调用直接
+`turn_stopped`，新 turn 才恢复。
+
+## 安全模型
+
+1. **可达性**：`allowApps` / `denyApps` 决定这个插件能不能碰某个应用；空数组 = 不限制。
+2. **确认**：`approval` 三档
+   - `never`：从不询问（自担风险）
+   - `sensitive`（默认）：目标元素标签命中危险词（delete/删除/卸载/支付/提交/安装…）才问；
+     `launch_app` 总是问
+   - `always`：每次动作都问
+   审批走 DSH 自己的 approval seam；**没有审批服务时直接拒绝**，绝不静默降级。
+3. **前台证明**：打字、按键、坐标点击、滚动必须先证明目标窗口真的拿到了前台，
+   否则抛 `focus_failed` 并告诉你当前是谁占着前台。SendInput 会打到有焦点的窗口，
+   这一步省不得。
+4. **快照 TTL**：元素编号默认 120 秒过期，过期必须重新观测，避免"拿旧编号点新界面"。
+5. **`dryRun`**：只回放动作不注入，用于集成演练。
+
+## 安装
+
+```powershell
+# 1. 放进 DSH 的 profile
+cd "E:\path\to\dsh-computer-use"
+# 方式 A：本地目录挂载（把本目录链进 profile 的 node_modules）
+# 方式 B：npm pack 后用宿主插件管理器安装
+```
+
+插件通过 `package.json` 的 `dsh.bundle.patch` 声明自己：
+
+```json
+{ "dsh": { "bundle": { "patch": "./cordis.patch.yml" } } }
+```
+
+`cordis.patch.yml` 负责往宿主配置里插插件行。装好后重启宿主，让模型调
+`computer_use_health` 自检；第一次调用会自动编译 helper（约 1-2 秒）。
+
+## 配置
+
+```yaml
+- id: deepseek-computer-use
+  config:
+    approval: sensitive            # never | sensitive | always
+    allowApps: ["notepad", "chrome"]   # 空 = 不限制
+    denyApps: []
+    defaultIncludeScreenshot: false    # 默认不抓图，省 token
+    maxElements: 260
+    snapshotTtlMs: 120000
+    dryRun: false
+    toolPrefix: ''                 # 填 'cu_' 可避免与其他插件的 click 重名
+    timeoutMs: 20000
+```
+
+## 契约对齐（对着 Codex 逐条核过）
+
+工具名与参数按 `@oai/sky` 的 window2 契约实现，不是"看着像"：
+
+| 契约项 | Codex | 本插件 |
+|---|---|---|
+| `get_window_state` 默认 | 截图 ON、accessibility `null` | 一致（`include_text:true` 才出树） |
+| 返回形态 | `{ window, screenshots[], accessibility }` | 一致；`screenshots` 是数组，含窗口 + 关联瞬态 UI（菜单/tooltip），每项带 `id`/`zIndex`/`originX`/`originY`/尺寸 |
+| 坐标寻址 | `click`/`scroll`/`drag` 收 `screenshotId` | 一致；坐标系绑定那张截图，过期报 `stale_screenshot` |
+| `scroll` | `x`,`y` 必填，无 `element_index` | 一致（缺 x/y 直接拒） |
+| accessibility 结构化字段 | `tree`/`focused_element`/`selected_text`/`selected_elements`/`document_text` | 全部实现 |
+| 观测节奏 | 动作后自动等约 1s 再抓 | 一致（`settleMs`，默认 1000） |
+| 元素失效 | 编号只对产生它的观测有效 | 一致（TTL + helper 进程内缓存） |
+| 最小化窗口 | 不该给出无意义画面 | 本插件直接报 `window_minimized`（实测旧版会吐出 334×48 的假图） |
+| 键名 | X keysym + `Numpad_*` 别名 | 一致（`KP_0`/`Numpad_Add`/…） |
+| `list_apps` | `lastUsedDate`、`useCount` | `lastUsedDate` 有；`useCount` 无数据源，不编造 |
+| `launch_app` | app id / `.exe` 路径（含 UWP） | exe 路径、AUMID（`shell:AppsFolder\\…`）、shell URI |
+| Win/Meta 键 | 硬拒绝 | 硬拒绝（插件层 + helper 层双保险） |
+| 终端/Run/密码管理器/安全软件/认证对话框/宿主自身 | 硬拒绝 | 硬拒绝（不可被审批覆盖） |
+| 按应用授权 | "Computer Use was not approved to use <app>" | 每会话每应用一次审批（`appConsent: session`），批准后下发 `approve_app`，**由 helper 强制**：未批准的应用直接 `app_not_approved` |
+| 回合边界 | 新 turn 时向 helper 发 `end_turn`，清元素快照 | 一致：token 变化即 `end_turn`（清快照/截图区/Esc 阻断，保留应用授权） |
+| 请求预算 | 普通 10s、`launch_app` 15s | 一致（`timeoutMs` / `launchTimeoutMs`） |
+| 回合结束停止输入 | `turn_ended` 钩子 | 读会话日志判断 open turn，`turn_ended` 拒绝注入 |
+
+## 明确没做的（不属于 Windows window2 面）
+
+- **`paste` / `select_text`**：属于 macOS 的 window 客户端（`target: "mac"`），Windows 上不存在。
+- **播客/音频录制**（`start_audio_recording`）：契约里是可选方法，未实现。
+- **full-desktop 面**（`clipboard_read/write`、`key_down/up`、`move`、`drag_handle`、`get_screenshot`）：那是 `target: "linux"` 的 API。
+- **区域裁剪截图**：Codex 是"bounded screenshot"，我们截整窗（长边封顶 2560）。token 成本略高，语义一致。
+- **Windows.Graphics.Capture**：Codex 用 WGC；我们用 `PrintWindow(PW_RENDERFULLCONTENT)`，遮挡可用、最小化拒绝，不需要 D3D 互操作。
+
+## 抓屏链路（对齐 Codex 的 WGC）
+
+按顺序尝试，前一级成功就不走下一级：
+
+1. **Windows.Graphics.Capture**（`native/bin/capture/dsh-cu-capture.exe`，**.NET Framework 4.8** + SharpDX）
+   —— 抓窗口的合成层，遮挡可用、GPU/直合成界面正常、无 DPI 黑边。
+   **不依赖 .NET 8 运行时**（Framework 4.8 是 Windows 自带组件），载荷仅 0.68MB
+2. **PrintWindow(PW_RENDERFULLCONTENT)** —— 无 .NET 8 运行时的机器上的兜底
+3. **屏幕 BitBlt** —— 前两者失败或返回黑图时
+
+WGC 走 .NET Framework 4.8（Windows 10/11 自带），**用户不需要安装任何运行时**。
+万一抓取失败仍会自动降级到第 2 级。
+覆盖层是独立窗口，WGC 按窗口抓取时天然不会被拍进去——和 Codex 的
+"exclude display overlay from captures" 等效。
+
+## 已知限制
+
+- **只有 Windows 驱动**。macOS / Linux 只有接口（`IPlatformDriver`），没有实现。
+- **前台焦点是硬约束**。前台被置顶工具（如 Process Lasso）或提权窗口占住时，
+  `type_text`/`press_key`/坐标点击/`scroll` 会被拒绝并报出占用者。
+  语义动作（`set_value`、Invoke 点击、Expand）不需要前台，照常工作。
+- **Electron/Chromium 无障碍树很薄**，网页内容要走截图 + 坐标。
+- **不绕过 UIPI**：目标窗口权限更高时注入会被系统拦。
+- **DPI 虚拟化已处理**：老式/无 DPI 感知的程序按 96 DPI 渲染，窗口物理尺寸被 DWM 放大，
+  `PrintWindow` 返回的是未缩放画面（此前会带黑边）。现在抓屏会裁掉黑边，并记录
+  「物理像素 / 截图像素」比例（实测某 WinForms 程序为 1.46×），坐标动作按该比例换算，
+  所以**截图坐标点哪就点哪**。
+- **`useCount`、应用使用历史**没有可靠本机数据源，宁缺不编。
+
+## 测试
+
+```powershell
+node test/integration.mjs
+```
+
+固定装置是一个独立的 WinForms 可执行文件（`test/bin/dsh-cu-fixture.exe`，一个文本框 +
+一个名为 "Delete all" 的按钮；特意不用 shell 托管——shell 窗口本身被硬拒绝）。覆盖：
+14 个工具注册、截图数组与 origin/zIndex、`accessibility:null` 语义、`set_value`、
+`type_text`、危险按钮触发审批、`dryRun` 不落地、`denyApps` 拒绝、Win 键硬拒绝、
+`scroll` 契约。
+
+## 许可
+
+MIT。第三方商用前请自行做安全评审：这个插件能让模型操作你的桌面。
+
+
+## 原生载荷（native/bin）
+
+| 文件 | 用途 | 大小 |
+|---|---|---|
+| `dsh-computer-use-helper.exe` | UIA / SendInput / 抓屏调度 / 音频调度 | ~50KB |
+| `dsh-cu-overlay.exe` | 鲸鱼娘 + 虚拟光标覆盖层 | ~30KB |
+| `capture/` | WGC 抓屏（.NET Framework 4.8 + SharpDX） | 0.68MB |
+| `audio/` | WASAPI 环回录音（NAudio） | 0.60MB |
+| **合计** | | **~1.4MB** |
+
+全部基于 Windows 自带的 .NET Framework 4.8，**用户零安装**。
+
+## 与 Codex window2 的细节对齐（第二轮）
+
+| 能力 | 实现 |
+|---|---|
+| 协议握手 | helper 提供 `hello` → `{ protocolVersion: 1, capabilities: [...] }`；bridge 首次连接校验，不匹配直接报 `protocol_mismatch` |
+| 每请求预算 | 客户端把预算随请求下发（`__budgetMs`，对应 Codex 的 `x-oai-cua-request-budget-ms`），helper 用它收缩抓屏等待 |
+| 坐标越界 | `point_outside_screenshot`，文案同 Codex（"is outside screenshot bounds … Take a fresh screenshot before retrying"） |
+| 截图失效 | `stale_screenshot` 带同一句 "Take a fresh screenshot before retrying" |
+| 优雅关闭 | `close` RPC → helper 落盘后退出 0；插件 dispose 时先发 close 再兜底 kill |
+| Esc 语义 | 覆盖层退出码 **130** → helper 写入 `%LOCALAPPDATA%\dsh-computer-use\interrupts\<会话>-<turn>.flag` 并自身退出 130；同 turn 后续调用 `turn_stopped`，新 turn 放行 |
+| 音频授权 | 独立于应用授权的一次性确认（Codex: `computer-audio` / "Allow Computer Use to record computer audio?"） |
+| 音频返回 | `{ filepath, bytes: base64 WAV, data_url }`，统一 **24 kHz 立体声 16-bit** |
+| 音频上限 | 单次录音 ≤ 300 000 ms（Codex 同值），不足 500 ms 自动抬到 500 |
+| App 字段 | `isRunning` + `lastUsedDate`（进程启动时间）；`useCount` 无数据来源，按 Codex 的可选字段处理，不伪造 |
+
+marker 文件按 **会话 + turn** 命名，避免旧会话的 Esc 标记误伤新会话。
+
+
+## 配置示例
+
+```yaml
+- insert:
+    - id: deepseek-computer-use
+      name: 'deepseek-computer-use'
+      config:
+        approval: sensitive     # never | sensitive | always
+        appConsent: session     # 每个应用问一次；never 表示不问
+        audio: false            # 开启 WASAPI 环回录音（start/stop_audio_recording）
+        redactApps: []          # 这些应用的截图永不出机器，例如 ["1password", "银行"]
+        defaultIncludeScreenshot: true
+        toolPrefix: ''          # 例如 cu_ 可避免和其他插件的 click 重名
+```
+
+## 已知边界
+
+- 只支持 Windows；驱动层是接口（`IPlatformDriver`），macOS / Linux 可照着补。
+- Codex window2 没有的接口（`paste` / `clipboard_*` / `key_down` / `move`）这里也没有。
+- `App.useCount` 没有数据来源，按可选字段留空，不伪造。
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,28 @@
+# deepseek-computer-use —— Windows 桌面控制（Computer Use）插件。
+#
+# 安装即向宿主注册 16 个工具：list_apps / list_windows / get_window / launch_app /
+# get_window_state / click / press_key / type_text / scroll / set_value / drag /
+# perform_secondary_action / activate_window / start_audio_recording /
+# stop_audio_recording / computer_use_health。
+#
+# 首次加载会在 native/bin 下用系统自带 csc.exe 编译 helper（无需 .NET SDK、
+# 无 npm 原生依赖）。全部配置项都有安全默认值，空配置即可启动：
+#
+#   - id: deepseek-computer-use
+#     config:
+#       approval: sensitive        # never | sensitive | always
+#       allowApps: []              # 空 = 不限制；可用 exe 路径子串或进程名
+#       denyApps: []
+#       defaultIncludeScreenshot: true   # Codex parity: capture unless told otherwise
+#       settleMs: 1000                   # wait for the UI to settle before the next capture
+#       appConsent: session              # ask once per app (never = skip)
+#       maxElements: 260
+#       snapshotTtlMs: 120000
+#       dryRun: false
+#       toolPrefix: ''             # 例如 cu_ 可避免与其他插件的 click 重名
+#       audio: false             # 开启 WASAPI 环回录音（start/stop_audio_recording）
+#       redactApps: []           # 这些应用的截图永不出机器，例如 ["1password"]
+- insert:
+    - id: deepseek-computer-use
+      name: 'deepseek-computer-use'
+      config: {}

package/lib/bridge.js

@@ -0,0 +1,224 @@
+/**
+ * Lifecycle and framing for the native helper process.
+ *
+ * One long-lived helper owns the UI Automation element cache, so element
+ * indexes returned by get_window_state stay resolvable by click/set_value.
+ * Requests are serialized: UI Automation calls are not reentrant and a
+ * desynchronized element cache is worse than waiting a few milliseconds.
+ *
+ * @module deepseek-computer-use/bridge
+ */
+import { spawn } from 'node:child_process';
+
+/** Protocol version this plugin speaks; the helper reports its own in `hello`. */
+const MIN_PROTOCOL = 1;
+
+/** Codex's wording, reused verbatim so the model reacts the same way. */
+const ESC_MESSAGE = 'Computer Use was stopped by the user with the physical Escape key. Stop your work, do not call further Computer Use tools in this turn, and send a final message noting that the user stopped Computer Use.';
+
+/** An error raised by the helper, carrying its machine-readable code. */
+export class HelperError extends Error {
+  constructor(code, message, details) {
+    super(message);
+    this.name = 'HelperError';
+    this.code = code;
+    this.details = details;
+  }
+}
+
+export class HelperBridge {
+  #child = null;
+  #buffer = '';
+  #pending = new Map();
+  #seq = 0;
+  #queue = Promise.resolve();
+  #exe;
+  #timeoutMs;
+  #protocol = null;
+  #interruptedTurn = null;
+  #lastTurn = null;
+  #disposed = false;
+  #log;
+
+  constructor({ exe, timeoutMs = 20000, log } = {}) {
+    if (typeof exe !== 'string' || exe.length === 0) throw new Error('HelperBridge requires an executable path');
+    this.#exe = exe;
+    this.#timeoutMs = timeoutMs;
+    this.#log = log;
+  }
+
+  get running() {
+    return this.#child !== null && this.#child.exitCode === null && !this.#child.killed;
+  }
+
+  #ensureChild() {
+    if (this.#disposed) throw new HelperError('disposed', 'the Computer Use bridge was disposed');
+    if (this.running) return this.#child;
+    const child = spawn(this.#exe, [], { stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true });
+    child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
+    child.stdout.on('data', chunk => this.#onData(chunk));
+    child.stderr.on('data', chunk => {
+      const text = String(chunk).trim();
+      if (text.length > 0) this.#log?.('[dsh-computer-use] helper stderr: ' + text);
+    });
+    child.on('exit', (code, signal) => {
+      this.#child = null;
+      this.#protocol = null;
+      // Codex's helper exits 130 when the user presses Esc; the transport turns that
+      // into the interrupt error so the model stops instead of retrying.
+      const interrupted = code === 130;
+      if (interrupted && this.#lastTurn !== null) this.#interruptedTurn = this.#lastTurn;
+      const reason = interrupted
+        ? ESC_MESSAGE
+        : 'the Computer Use helper exited (code ' + code + ', signal ' + signal + ')';
+      for (const [, entry] of this.#pending) {
+        clearTimeout(entry.timer);
+        entry.reject(new HelperError(interrupted ? 'cancelled_by_user' : 'helper_exited', reason));
+      }
+      this.#pending.clear();
+    });
+    child.on('error', error => {
+      this.#log?.('[dsh-computer-use] helper spawn error: ' + error.message);
+    });
+    this.#child = child;
+    return child;
+  }
+
+  #onData(chunk) {
+    this.#buffer += chunk;
+    let index = this.#buffer.indexOf('\n');
+    while (index >= 0) {
+      const line = this.#buffer.slice(0, index).trim();
+      this.#buffer = this.#buffer.slice(index + 1);
+      if (line.length > 0) this.#settle(line);
+      index = this.#buffer.indexOf('\n');
+    }
+  }
+
+  #settle(line) {
+    let payload;
+    try {
+      payload = JSON.parse(line);
+    } catch {
+      this.#log?.('[dsh-computer-use] helper produced non-JSON output: ' + line.slice(0, 200));
+      return;
+    }
+    const entry = this.#pending.get(payload.id);
+    if (entry === undefined) return;
+    this.#pending.delete(payload.id);
+    clearTimeout(entry.timer);
+    if (payload.ok === true) entry.resolve(payload.result);
+    else entry.reject(new HelperError(payload.error?.code ?? 'helper_error', payload.error?.message ?? 'the helper reported an unknown failure', payload.error));
+  }
+
+  /**
+   * Send one request. Calls are serialized through the queue; a caller that
+   * never gets an answer fails on the timeout rather than hanging the turn.
+   */
+  request(method, params = {}, { signal, timeoutMs, turnToken } = {}) {
+    const wire = turnToken === undefined ? params : { ...params, turnToken };
+    if (turnToken !== undefined) this.#lastTurn = turnToken;
+    const run = async () => {
+      // Codex stops issuing input for the rest of a turn once the user hits Esc.
+      // The helper persists the same fact, but failing here keeps the error
+      // immediate even while a fresh helper process is spinning up.
+      if (turnToken !== undefined && this.#interruptedTurn === turnToken) {
+        throw new HelperError('turn_stopped', ESC_MESSAGE);
+      }
+      await this.#ensureProtocol(signal);
+      try {
+        return await this.#call(method, wire, { signal, timeoutMs });
+      } catch (error) {
+        if ((error?.code === 'cancelled_by_user' || error?.code === 'turn_stopped') && turnToken !== undefined) {
+          this.#interruptedTurn = turnToken;
+        }
+        throw error;
+      }
+    };
+    const next = this.#queue.then(run, run);
+    this.#queue = next.then(() => undefined, () => undefined);
+    return next;
+  }
+
+  /**
+   * The helper reports `protocolVersion` from `hello`. Codex exposes the same fact as
+   * `window_protocol_version`; checking it up front turns a silent mismatch into one
+   * clear error instead of a stream of malformed-stream failures.
+   */
+  async #ensureProtocol(signal) {
+    if (this.#protocol !== null) return;
+    const hello = await this.#call('hello', {}, { signal, timeoutMs: 5000 });
+    const version = Number(hello?.protocolVersion);
+    if (!Number.isFinite(version) || version < MIN_PROTOCOL) {
+      throw new HelperError('protocol_mismatch',
+        'the Computer Use helper speaks protocol ' + (hello?.protocolVersion ?? 'unknown') +
+        ', this plugin needs ' + MIN_PROTOCOL + ' or newer. Reinstall deepseek-computer-use so the helper and the plugin match.');
+    }
+    this.#protocol = version;
+  }
+
+  #call(method, params, { signal, timeoutMs }) {
+    if (signal?.aborted) return Promise.reject(new HelperError('cancelled', 'the request was cancelled before it started'));
+    const child = this.#ensureChild();
+    const id = ++this.#seq;
+    const budgetMs = Number.isFinite(timeoutMs) ? timeoutMs : this.#timeoutMs;
+    // Codex ships the budget with every call as x-oai-cua-request-budget-ms so the
+    // helper can bound its own waits; the same deadline travels here.
+    const payload = JSON.stringify({ id, method, params: { ...params, __budgetMs: budgetMs } });
+
+    const raw = new Promise((resolve, reject) => {
+      const budget = Number.isFinite(timeoutMs) ? timeoutMs : this.#timeoutMs;
+      const timer = setTimeout(() => {
+        this.#pending.delete(id);
+        reject(new HelperError('timeout', 'the Computer Use helper did not answer ' + method + ' within ' + budget + 'ms'));
+      }, budget);
+      timer.unref?.();
+
+      const onAbort = () => {
+        this.#pending.delete(id);
+        clearTimeout(timer);
+        reject(new HelperError('cancelled', 'the request was cancelled'));
+      };
+      signal?.addEventListener('abort', onAbort, { once: true });
+
+      this.#pending.set(id, {
+        timer,
+        resolve: value => {
+          signal?.removeEventListener('abort', onAbort);
+          resolve(value);
+        },
+        reject: error => {
+          signal?.removeEventListener('abort', onAbort);
+          reject(error);
+        },
+      });
+
+      try {
+        child.stdin.write(payload + '\n');
+      } catch (error) {
+        this.#pending.delete(id);
+        clearTimeout(timer);
+        reject(new HelperError('write_failed', 'cannot talk to the Computer Use helper: ' + error.message));
+      }
+    });
+    // The caller always handles this promise; the extra branch only stops Node from
+    // treating a momentarily unobserved rejection as a fatal unhandled one.
+    raw.catch(() => { /* observed by the caller; this branch only silences Node */ });
+    return raw;
+  }
+
+  dispose() {
+    this.#disposed = true;
+    const child = this.#child;
+    this.#child = null;
+    if (child !== null) {
+      // Codex closes the helper with a close RPC before tearing the process down.
+      try {
+        child.stdin.write(JSON.stringify({ id: ++this.#seq, method: 'close', params: {} }) + '\n');
+      } catch { /* already gone */ }
+      try { child.stdin.end(); } catch { /* already gone */ }
+      setTimeout(() => { try { child.kill(); } catch { /* already gone */ } }, 150).unref?.();
+    }
+  }
+}