deepseek-computer-use 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# 更新记录
+
+## 0.2.0 (2026-10-26)
+
+- Add this plugin’s own update controls and independent preferences. Automatic installation stays off until explicitly enabled.
+- Confirm manual installs, preserve local sources and disabled state, pause for tasks or unsaved changes, and use native DSH recovery without forced restarts.
+- Require the public DSH 0.2.1-rc.3 update APIs; Suite components remain managed through Suite.
+
+## 0.1.2 — 2026-10-18
+
+- 适配真实 DeepSeek Harness：标准 JSON Schema 参数、模型可见的截图附件、审批审计，
+  以及会话独立的应用授权、helper 和观测缓存；修正截图缩放后的坐标换算。
+- 超时或取消后停止原生请求，确认旧 helper 退出后再返回失败。长文本输入可中途取消，
+  按键和鼠标按钮在退出路径释放；回合结束时主动关闭 helper 与覆盖层。
+- 输入或抓屏失败后清除观测，要求重新执行 `get_window_state`；截图 id 跨 helper 重启唯一。
+  更新时若旧 helper 正被占用，可将新版编译到独立路径。
+- 原生协议升级到 **2**。默认 helper 会自动重编译；使用自定义 `helperPath` 时需同步更新。
+- 增加 18 项参数、策略和进程生命周期回归，并在 DSH `0.2.1-rc.2`、
+  `0.2.1-alpha.5` 中验证真实截图、审批、输入、取消及回合清理。
+
+本版未验证音频录制、多应用长任务或与 Codex 的模型任务成功率对比。
+Codex SDK 和二进制未纳入分发，改进为独立实现。

package/README.md

@@ -1,16 +1,25 @@
 # deepseek-computer-use
 
+![deepseek-computer-use 大肥鱼桌面控制封面](https://raw.githubusercontent.com/STARDUSTLC666/deepseek-computer-use/main/assets/cover-whale-girl.png)
+
 [![npm](https://img.shields.io/npm/v/deepseek-computer-use.svg)](https://www.npmjs.com/package/deepseek-computer-use)
+[![Windows 10/11](https://img.shields.io/badge/platform-Windows%2010%2F11-0078D4.svg)](#安装)
+[![Node.js ≥18.17](https://img.shields.io/badge/node-%3E%3D18.17-339933.svg)](package.json)
+[![MIT License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
 > 社区插件，**非 DeepSeek 官方出品**。官方包在 `@deepseek-ai/*` scope 下。
 
-给 DeepSeek Harness 的 **Windows 桌面控制（Computer Use）** 插件。
+让 **DeepSeek Harness 操作 Windows 桌面软件**：查看窗口截图、读取界面控件、
+点击按钮、填写表单。适用于没有可用 API、需要直接操作图形界面的任务。
+
+提供 16 个工具，覆盖窗口发现、截图观测、鼠标键盘、控件操作和可选的系统音频录制。
+支持会话独立授权、敏感操作审批与审计；取消或回合结束时停止原生助手，
+操作失败后要求重新观察，减少结果不明时的重复操作。
+
+底层采用 **UI Automation + SendInput + Windows.Graphics.Capture**，
+工具语义参考 Codex window2，并针对 DSH 的会话、审批和截图附件机制适配。
 
-工具面对齐 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 抓屏**。
+欢迎使用，遇到问题或有改进建议，请提交 [issues](https://github.com/STARDUSTLC666/deepseek-computer-use/issues) 和 [PR](https://github.com/STARDUSTLC666/deepseek-computer-use/pulls)。
 
 零 npm 原生依赖、零 .NET 运行时依赖：helper 和覆盖层用系统自带的 `csc.exe` 现编，
 抓屏（WGC）和录音（WASAPI）是 net48 程序，Windows 10/11 自带运行时。
@@ -46,15 +55,51 @@ npm run build          # helper + overlay（csc），再尝试 dotnet 编 captur
 ## 自检
 
 ```bash
-npm test               # 13 项断言：注册、观测、点击、审批、硬拒绝、Esc 阻断
-npm run test:all       # 追加 helper 协议/音频 与插件级一致性测试
+npm test               # DSH 参数/策略回归 + 原生 WinForms 集成验证
+npm run test:contracts # 只运行参数与策略测试，不操作桌面
+npm run test:harness -- --dsh-root /path/to/node_modules/@deepseek-ai/dsh
+# test:harness 启动隔离的真实 DSH CLI/profile，验证附件、审批和原生操作。
+# npm run test:all 另含真实系统音频录制测试，按需运行。
+```
+
+## DeepSeek Harness 接入
+
+这是通过 DSH 的 `apply(ctx)` / `inject` / bundle patch 接入的独立插件。
+工具注册使用标准 JSON Schema，截图通过 `attachments` 保存并输出模型可见的 image block，
+应用授权与危险动作通过 `approval.request` 审批并写入会话审计。
+每个会话独立保存授权、helper、截图与元素快照；同一桌面的工具调用串行执行。
+DSH 附件存储缩小截图时，坐标会自动换算回原始抓屏像素。
+
+在需要使用的 DSH profile 中安装，例如 Git Bash 下：
+
+```bash
+dsh plugin --profile web add deepseek-computer-use
+dsh web --no-open
 ```
 
+开发时可将包名换成 `file:E:/deepseek/dsh-computer-use` 来加载本地源码。
+以下宿主适配和失败恢复改进包含在 0.1.2 及后续版本中，详见 [更新记录](CHANGELOG.md)。
+`test:harness` 不调用模型、不录音，只操作自己创建的测试窗口，结束后移除隔离 profile。
+
+中止与失败恢复：
+
+- 超时或取消会先通知当前原生请求停止；输入循环检查取消标记，并在 `finally` 释放按键/鼠标按钮。
+  helper 未在 500ms 内退出时会被终止；调用失败返回前确认旧进程已经退出。
+- DSH 的 `session/event` 出现 `turn/end` 时主动停止该会话的 helper 和覆盖层，不依赖下一次工具调用。
+- 输入或抓屏失败会清除已缓存的快照。后续输入返回 `fresh_observation_required`，
+  必须成功调用 `get_window_state` 后再决定动作；不会自动重复结果不明的输入。
+- 新 helper 使用不同的截图 id，防止重启前的截图编号误命中新缓存。
+  原生协议已升级为 2，自定义 `helperPath` 也需要匹配版本。
+
 ## 它解决什么问题
 
-DSH 本体没有鼠标键盘工具，只能跑命令、读写文件。需要"操作图形界面"时（点按钮、
-填表单、操作没有 API 的桌面软件），这个插件补上这一层，并且把每一步都变成**可观测、
-可审批、可验证**的动作。
+DSH 官方已有需要显式启用的实验性 Computer Use 方案，包括 Cua Driver MCP 与原生
+提供方；其上游 Cua Driver 也支持 Windows。详见 [官方计算机操作文档](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/subsystems/computer-use.zh.md)
+和 [Cua Driver 平台支持](https://github.com/trycua/cua/blob/main/docs/content/docs/reference/cua-driver/contracts.mdx)。
+
+本插件是另一套独立的 Windows 社区实现，提供 UI Automation、窗口截图、鼠标键盘、
+会话授权、审批审计和中断恢复，用于点击按钮、填写表单或操作没有 API 的桌面软件。
+它与官方方案有功能重合；本项目的验收结果不代表已与官方驱动做过效果或性能对比。
 
 ## 架构
 
@@ -73,7 +118,7 @@ DSH 宿主
 驱动层是接口（`IPlatformDriver`），今天是 `windows` 一个实现；macOS（AX + CGEvent）
 和 Linux（AT-SPI）可以照着补，插件层不用改。
 
-helper 常驻的原因：元素编号必须和"那一次观测"绑在同一个进程里，否则
+每个会话的 helper 常驻的原因：元素编号必须和"那一次观测"绑在同一个进程里，否则
 `click(element_index)` 无从解析。因此插件串行发请求、按 id 配对响应。
 
 ## 工具
@@ -139,6 +184,8 @@ Codex 用两层覆盖层告诉用户"AI 正在动你的电脑"，这里做的是
      `launch_app` 总是问
    - `always`：每次动作都问
    审批走 DSH 自己的 approval seam；**没有审批服务时直接拒绝**，绝不静默降级。
+   DSH 宿主的 `approval` 策略 `never` 表示拒绝需要审批的请求，与本插件配置项的
+   `approval: never`（跳过动作级询问）含义不同。应用授权仍由 `appConsent` 单独控制。
 3. **前台证明**：打字、按键、坐标点击、滚动必须先证明目标窗口真的拿到了前台，
    否则抛 `focus_failed` 并告诉你当前是谁占着前台。SendInput 会打到有焦点的窗口，
    这一步省不得。
@@ -171,17 +218,22 @@ cd "E:\path\to\dsh-computer-use"
     approval: sensitive            # never | sensitive | always
     allowApps: ["notepad", "chrome"]   # 空 = 不限制
     denyApps: []
-    defaultIncludeScreenshot: false    # 默认不抓图，省 token
+    defaultIncludeScreenshot: true     # 默认抓图；false 可显式关闭
     maxElements: 260
     snapshotTtlMs: 120000
     dryRun: false
     toolPrefix: ''                 # 填 'cu_' 可避免与其他插件的 click 重名
-    timeoutMs: 20000
+    timeoutMs: 10000
 ```
 
-## 契约对齐（对着 Codex 逐条核过）
+## 与 Codex Windows window2 的关系
 
-工具名与参数按 `@oai/sky` 的 window2 契约实现，不是"看着像"：
+工具以 `@oai/sky` 的 Windows window2 动作和观测语义为参照，底层也采用 UIA、SendInput、WGC。
+它是 DSH 的独立实现，不能据此认为具有相同的模型能力、成功率或全部运行时行为。
+
+DSH 接口有这些明确差异：`list_windows` / `list_apps` 分别返回 `{ windows, count }` /
+`{ apps, count }`；`window.app` 返回应用元数据对象，输入也接受字符串 app id 或只提供窗口 id；
+`get_window` 接收 `{ window: { id } }`；截图返回 DSH 附件引用和 image block，Codex 使用图片 URL。
 
 | 契约项 | Codex | 本插件 |
 |---|---|---|
@@ -194,22 +246,22 @@ cd "E:\path\to\dsh-computer-use"
 | 元素失效 | 编号只对产生它的观测有效 | 一致（TTL + helper 进程内缓存） |
 | 最小化窗口 | 不该给出无意义画面 | 本插件直接报 `window_minimized`（实测旧版会吐出 334×48 的假图） |
 | 键名 | X keysym + `Numpad_*` 别名 | 一致（`KP_0`/`Numpad_Add`/…） |
-| `list_apps` | `lastUsedDate`、`useCount` | `lastUsedDate` 有；`useCount` 无数据源，不编造 |
+| `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 阻断，保留应用授权） |
+| 回合边界 | 回合与 helper 生命周期关联 | DSH 回合结束事件主动停止旧 helper；新回合创建新 helper，并重新下发已获应用授权 |
 | 请求预算 | 普通 10s、`launch_app` 15s | 一致（`timeoutMs` / `launchTimeoutMs`） |
-| 回合结束停止输入 | `turn_ended` 钩子 | 读会话日志判断 open turn，`turn_ended` 拒绝注入 |
+| 回合结束停止输入 | `turn_ended` 钩子 | 主动停止正在执行的请求，排队中的旧回合请求也被拒绝 |
 
-## 明确没做的（不属于 Windows window2 面）
+## 能力边界
 
 - **`paste` / `select_text`**：属于 macOS 的 window 客户端（`target: "mac"`），Windows 上不存在。
-- **播客/音频录制**（`start_audio_recording`）：契约里是可选方法，未实现。
+- **系统音频录制**（`start_audio_recording`）：已实现 WASAPI 环回录音，默认关闭，需要构建 audio helper 并单独授权。
 - **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 互操作。
+- **区域裁剪截图**：当前抓整窗（长边封顶 2560），不能认为与 Codex 的 bounded screenshot 完全等价。
+- **Windows.Graphics.Capture**：构建 capture helper 后优先使用 WGC；不可用时回退到 PrintWindow / BitBlt，GPU 窗口的兼容性取决于实际使用的抓屏后端。
 
 ## 抓屏链路（对齐 Codex 的 WGC）
 
@@ -273,7 +325,7 @@ MIT。第三方商用前请自行做安全评审：这个插件能让模型操
 
 | 能力 | 实现 |
 |---|---|
-| 协议握手 | helper 提供 `hello` → `{ protocolVersion: 1, capabilities: [...] }`；bridge 首次连接校验，不匹配直接报 `protocol_mismatch` |
+| 协议握手 | helper 提供 `hello` → `{ protocolVersion: 2, 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" |
@@ -313,6 +365,12 @@ marker 文件按 **会话 + turn** 命名，避免旧会话的 Esc 标记误伤
 - `redactApps` 在**插件层**执行：直接调用 helper 的 RPC 不受它约束，别把 helper 单独暴露给非受信调用方。
 - 抢焦点类工具（如 ProcessLasso）会让 `type_text` 返回 `focus_failed`，这是设计行为——宁可不输入，也不打到别的窗口。
 
+## 插件更新
+
+需要 DSH 0.2.1-rc.3 或更新版本。每个插件在自己的页面或设置项提供检查、更新记录与确认安装入口，开关独立保存。自动检查默认开启；**自动安装默认关闭**，只有明确授权后，兼容的稳定补丁才会在空闲且没有未保存修改时安装。可单独关闭、推迟或忽略提醒；不会强制重启 DSH、升级 DSH 本体或替换本地源码安装。Suite 安装的组件会明确提示通过 Suite 整包更新。
+
+旧版用户先在官方插件管理中手动更新一次，之后才会获得此入口。发布到 npm 不会直接替换用户已经安装的版本。
+
 ## License
 
 MIT

package/lib/bridge.js

@@ -1,22 +1,14 @@
-/**
- * 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
- */
+/** Serialized native RPC, with cancellation that waits for the owned process to stop. */
 import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
 
-/** 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 MIN_PROTOCOL = 2;
 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);
@@ -28,197 +20,208 @@ export class HelperError extends Error {
 
 export class HelperBridge {
   #child = null;
+  #closed = new WeakMap();
+  #termination = new WeakMap();
+  #reasons = new WeakMap();
   #buffer = '';
   #pending = new Map();
   #seq = 0;
   #queue = Promise.resolve();
+  #stopping = Promise.resolve();
   #exe;
+  #args;
+  #cancelDirectory;
   #timeoutMs;
   #protocol = null;
-  #interruptedTurn = null;
+  #stoppedTurns = new Map();
   #lastTurn = null;
   #disposed = false;
   #log;
 
-  constructor({ exe, timeoutMs = 20000, log } = {}) {
+  constructor({ exe, args = [], cancelDirectory, timeoutMs = 20000, log } = {}) {
     if (typeof exe !== 'string' || exe.length === 0) throw new Error('HelperBridge requires an executable path');
     this.#exe = exe;
+    this.#args = args;
+    this.#cancelDirectory = cancelDirectory ?? path.join(os.tmpdir(), 'dsh-computer-use-requests');
     this.#timeoutMs = timeoutMs;
     this.#log = log;
   }
 
-  get running() {
-    return this.#child !== null && this.#child.exitCode === null && !this.#child.killed;
-  }
+  get running() { return this.#child !== null && this.#child.exitCode === null && this.#child.signalCode === null; }
+  get pid() { return this.running ? this.#child.pid : null; }
 
   #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 });
+    const child = spawn(this.#exe, this.#args, { stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true });
+    this.#child = child;
+    this.#buffer = '';
+    this.#protocol = null;
+    this.#closed.set(child, new Promise(resolve => child.once('close', resolve)));
     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.stdout.on('data', chunk => { if (this.#child === child) this.#onData(child, chunk); });
+    child.stderr.on('data', chunk => this.#log?.('[dsh-computer-use] helper: ' + String(chunk).trim().slice(0, 500)));
+    child.stdin.on('error', error => this.#stop(child, new HelperError('write_failed', error.message)));
+    child.on('error', error => {
+      this.#reasons.set(child, new HelperError('helper_start_failed', error.message));
     });
-    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));
+    child.on('close', (code, signal) => {
+      const escaped = code === 130;
+      if (escaped && this.#lastTurn !== null) this.#stoppedTurns.set(this.#lastTurn, new HelperError('turn_stopped', ESC_MESSAGE));
+      const error = this.#reasons.get(child) ?? new HelperError(escaped ? 'cancelled_by_user' : 'helper_exited',
+        escaped ? ESC_MESSAGE : 'the Computer Use helper exited (code ' + code + ', signal ' + signal + ')');
+      if (this.#child === child) {
+        this.#child = null;
+        this.#protocol = null;
+        this.#buffer = '';
       }
-      this.#pending.clear();
+      this.#rejectChild(child, error);
     });
-    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');
+  #rejectChild(child, error) {
+    for (const [id, entry] of this.#pending) {
+      if (entry.child !== child) continue;
+      this.#pending.delete(id);
+      entry.cleanup();
+      entry.reject(error);
+    }
+  }
+
+  #stop(child, error) {
+    const stopped = this.#terminate(child, error);
+    stopped.catch(failure => this.#rejectChild(child, failure));
+    return stopped;
+  }
+
+  #terminate(child, error) {
+    if (!child) return this.#stopping;
+    if (this.#termination.has(child)) return this.#termination.get(child);
+    this.#reasons.set(child, error);
+    for (const entry of this.#pending.values()) {
+      if (entry.child !== child) continue;
+      entry.stopping = true;
+      clearTimeout(entry.timer);
+      try { fs.writeFileSync(entry.cancelFile, error.code, 'utf8'); } catch { /* forced stop below remains available */ }
     }
+    const stop = (async () => {
+      const closed = this.#closed.get(child);
+      // Native input loops poll the marker and release held input in finally.
+      // The close frame is processed once that request unwinds.
+      try { child.stdin.write(JSON.stringify({ id: ++this.#seq, method: 'close', params: {} }) + '\n'); } catch { /* process already exited */ }
+      let ended = await Promise.race([closed.then(() => true), delay(500).then(() => false)]);
+      if (!ended) {
+        child.kill('SIGKILL');
+        ended = await Promise.race([closed.then(() => true), delay(2000).then(() => false)]);
+      }
+      if (!ended) {
+        this.#disposed = true;
+        throw new HelperError('helper_stop_failed', 'the Computer Use helper could not be stopped; no further Computer Use requests are allowed');
+      }
+    })();
+    this.#termination.set(child, stop);
+    this.#stopping = stop;
+    return stop;
   }
 
-  #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;
+  #onData(child, chunk) {
+    this.#buffer += chunk;
+    let newline;
+    while ((newline = this.#buffer.indexOf('\n')) >= 0) {
+      const line = this.#buffer.slice(0, newline).trim();
+      this.#buffer = this.#buffer.slice(newline + 1);
+      if (!line) continue;
+      let payload;
+      try { payload = JSON.parse(line); }
+      catch {
+        this.#stop(child, new HelperError('protocol_error', 'the Computer Use helper returned invalid JSON; take a fresh observation before retrying'));
+        return;
+      }
+      const entry = this.#pending.get(payload?.id);
+      if (!entry || entry.child !== child || entry.stopping) continue;
+      if (typeof payload.ok !== 'boolean') {
+        this.#stop(child, new HelperError('protocol_error', 'the Computer Use helper returned an invalid response'));
+        return;
+      }
+      const code = payload.error?.code;
+      if (!payload.ok && ['timeout', 'cancelled', 'cancelled_by_user', 'turn_stopped'].includes(code)) {
+        if (['cancelled_by_user', 'turn_stopped'].includes(code) && entry.turnToken !== undefined) {
+          this.#stoppedTurns.set(entry.turnToken, new HelperError('turn_stopped', ESC_MESSAGE));
+        }
+        this.#stop(child, new HelperError(code, payload.error.message));
+        continue;
+      }
+      this.#pending.delete(payload.id);
+      entry.cleanup();
+      if (payload.ok) entry.resolve(payload.result);
+      else entry.reject(new HelperError(code ?? 'helper_error', payload.error?.message ?? 'the helper request failed', payload.error));
     }
-    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;
+      await this.#stopping;
+      if (this.#disposed) throw new HelperError('disposed', 'the Computer Use bridge was disposed');
+      if (signal?.aborted) throw new HelperError('cancelled', 'the request was cancelled before it started');
+      if (turnToken !== undefined && this.#stoppedTurns.has(turnToken)) throw this.#stoppedTurns.get(turnToken);
+      if (turnToken !== undefined) this.#lastTurn = turnToken;
+      if (this.#protocol === null) {
+        const hello = await this.#call('hello', {}, { signal, timeoutMs: 5000, turnToken });
+        if (!Number.isInteger(hello?.protocolVersion) || hello.protocolVersion < MIN_PROTOCOL) {
+          const error = new HelperError('protocol_mismatch', 'the Computer Use helper must support cancellation protocol ' + MIN_PROTOCOL + '; rebuild the plugin helper');
+          await this.#terminate(this.#child, error);
+          throw error;
         }
-        throw error;
+        this.#protocol = hello.protocolVersion;
       }
+      if (turnToken !== undefined && this.#stoppedTurns.has(turnToken)) throw this.#stoppedTurns.get(turnToken);
+      return this.#call(method, params, { signal, timeoutMs, turnToken });
     };
     const next = this.#queue.then(run, run);
-    this.#queue = next.then(() => undefined, () => undefined);
+    this.#queue = next.catch(() => {});
     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 }) {
+  #call(method, params, { signal, timeoutMs, turnToken }) {
     if (signal?.aborted) return Promise.reject(new HelperError('cancelled', 'the request was cancelled before it started'));
     const child = this.#ensureChild();
+    fs.mkdirSync(this.#cancelDirectory, { recursive: true });
+    const cancelFile = path.join(this.#cancelDirectory, randomUUID() + '.flag');
     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 budget = timeoutMs ?? this.#timeoutMs;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => this.#stop(child, new HelperError('timeout',
+        'the Computer Use helper exceeded ' + budget + 'ms for ' + method + '; take a fresh observation before retrying')), budget);
       const onAbort = () => {
-        this.#pending.delete(id);
+        if (turnToken !== undefined) this.#stoppedTurns.set(turnToken, new HelperError('turn_stopped', 'Computer Use was cancelled in this turn; wait for a new turn'));
+        this.#stop(child, new HelperError('cancelled', 'the Computer Use request was cancelled and its helper stopped'));
+      };
+      const cleanup = () => {
         clearTimeout(timer);
-        reject(new HelperError('cancelled', 'the request was cancelled'));
+        signal?.removeEventListener('abort', onAbort);
+        try { fs.unlinkSync(cancelFile); } catch { /* no marker was needed */ }
       };
+      this.#pending.set(id, { child, cancelFile, timer, cleanup, resolve, reject, turnToken, stopping: false });
       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);
-        },
-      });
-
+      if (signal?.aborted) { onAbort(); return; }
       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));
-      }
+        child.stdin.write(JSON.stringify({ id, method, params: { ...params, ...(turnToken === undefined ? {} : { turnToken }), __budgetMs: budget, __cancelFile: cancelFile } }) + '\n', error => {
+          if (error) this.#stop(child, new HelperError('write_failed', error.message));
+        });
+      } catch (error) { this.#stop(child, new HelperError('write_failed', 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;
+  }
+
+  stopTurn(turnToken) {
+    const error = new HelperError('turn_ended', 'the requesting turn has ended; wait for a new turn and take a fresh observation');
+    this.#stoppedTurns.set(turnToken, error);
+    return this.#terminate(this.#child, error);
   }
 
   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?.();
-    }
+    return this.#terminate(this.#child, new HelperError('disposed', 'the Computer Use bridge was disposed'));
   }
 }

package/lib/build-helper.mjs

@@ -9,6 +9,7 @@
  * @module deepseek-computer-use/build-helper
  */
 import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -76,11 +77,24 @@ export function ensureHelper({ force = false, exe = HELPER_EXE, log } = {}) {
   }
 
   fs.mkdirSync(path.dirname(exe), { recursive: true });
-  const args = ['/nologo', '/target:exe', '/platform:anycpu', '/out:' + exe, ...SOURCES, ...refs];
   log?.('[dsh-computer-use] compiling helper with ' + compiler);
-  const output = execFileSync(compiler, args, { encoding: 'utf8', windowsHide: true });
-  if (!fs.existsSync(exe)) throw new Error('helper compilation produced no executable: ' + output);
-  return { exe, built: true };
+  const compile = output => execFileSync(compiler, ['/nologo', '/target:exe', '/platform:anycpu', '/out:' + output, ...SOURCES, ...refs], { encoding: 'utf8', windowsHide: true });
+  try {
+    compile(exe);
+    if (!fs.existsSync(exe)) throw new Error('helper compilation produced no executable');
+    return { exe, built: true };
+  } catch (error) {
+    // Windows locks a running exe. Compile alongside it during an update rather
+    // than stopping a helper owned by another DSH session.
+    if (!fs.existsSync(exe) || !String(error.stdout ?? '').includes('CS0016')) throw error;
+    const hash = createHash('sha256');
+    for (const source of SOURCES) hash.update(fs.readFileSync(source));
+    const cached = path.join(path.dirname(exe), path.basename(exe, '.exe') + '-' + hash.digest('hex').slice(0, 16) + '.exe');
+    if (isHelperFresh(cached)) return { exe: cached, built: false };
+    log?.('[dsh-computer-use] helper is in use; compiling alongside it');
+    compile(cached);
+    return { exe: cached, built: true };
+  }
 }
 
 /** The in-use indicator (breathing frame + virtual cursor) is a separate win-exe. */

package/lib/build.mjs

@@ -6,13 +6,13 @@
  *   capture  Windows.Graphics.Capture             (needs .NET SDK)
  *   audio    WASAPI loopback recorder             (needs .NET SDK)
  */
-import { ensureHelper, ensureOverlay, HELPER_EXE, OVERLAY_EXE } from './build-helper.mjs';
+import { ensureHelper, ensureOverlay, OVERLAY_EXE } from './build-helper.mjs';
 import { buildNative } from './build-native.mjs';
 
 const log = message => console.log(message);
 
 const helper = ensureHelper({ force: process.argv.includes('--force'), log });
-log('[dsh-computer-use] helper  ' + (helper.built ? 'built' : 'up to date') + ' -> ' + HELPER_EXE);
+log('[dsh-computer-use] helper  ' + (helper.built ? 'built' : 'up to date') + ' -> ' + helper.exe);
 
 const overlay = ensureOverlay({ force: process.argv.includes('--force'), log });
 log('[dsh-computer-use] overlay ' + (overlay.built ? 'built' : 'up to date') + ' -> ' + OVERLAY_EXE);