@forsion/tangu-computer-use 0.6.0 → 0.6.1

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # 更新日志
 
+## 0.6.1 — 2026-10-02
+
+- 修复：在 Forsion 里停用再启用 Computer Use 插件（引擎不重启的热插拔）时，每次启用都会多挂一组进程退出监听，开关拨多了会报 `MaxListenersExceededWarning`，退出时收尾也会重复执行。现在停用会摘掉这组监听，再启用也只挂一组。
+- `types/tangu-agent.d.ts` 同步到引擎当前的插件 API（`requiresPlugins` 与生命周期）。
+- 新增 `npm run check:exit-listeners`（已并入 `npm run check`）。
+
+Turning the Computer Use plugin off and on again in Forsion, without restarting the engine, no longer adds another set of process exit listeners each time. Repeated toggling used to trigger `MaxListenersExceededWarning` and run the cleanup several times on exit. Deactivating the plugin now removes its listeners, and enabling it again adds a single set. `types/tangu-agent.d.ts` now matches the engine's current plugin API (`requiresPlugins` and the lifecycle). New `npm run check:exit-listeners`, included in `npm run check`.
+
 ## 0.6.0 — 2026-09-27
 
 - 新增「电脑历史」采集（macOS，协议 13）：Forsion 桌面端开启该功能后，helper 通过新的 `recordSubscribe` 订阅，把前台 App 切换、窗口标题、浏览器网址（去掉查询串）、焦点输入框里新打的字、点击的控件名和 ⌘ / ⌃ 快捷键推给桌面端。只需要「辅助功能」授权，不截图、不录原始按键。helper 自己不落盘，保存、保留期、清除、暂停都由桌面端负责；最后一个订阅者断开后，所有观察者随即拆除。

package/manifest.json

@@ -2,7 +2,7 @@
   "id": "tangu-computer-use",
   "name": "电脑操作",
   "nameEn": "Computer Use",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "apiVersion": 1,
   "minAppVersion": "2.11.2",
   "description": "让 agent 观察并操作桌面应用:看屏幕、点按、输入、滚动(macOS / Windows / Linux)。捆绑包内含引擎侧的 12 个工具、配套技能,以及一个「被操控的窗口」实时画面视图 —— agent 动手时,被操控的那个窗口会亮起边缘光效,画面同步出现在 Agent Desk 上。",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forsion/tangu-computer-use",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Tangu engine plugin: let agents observe and control macOS, Windows, and Linux desktop apps. Fork of injaneity/pi-computer-use (MIT).",
   "type": "module",
   "license": "MIT",
@@ -54,7 +54,7 @@
     "check:platform": "node scripts/platform-contract.check.mjs",
     "check:blindclick": "node scripts/blind-click.check.mjs",
     "check:liveview": "node scripts/live-view.check.mjs",
-    "check": "npm run check:platform && npm run check:no-foreground && npm run check:helper-path && npm run check:highlight && npm run check:permissions && npm run check:plugin && npm run check:helper-refresh && npm run check:installer && npm run check:cli-exit && npm run check:recorder-logic",
+    "check": "npm run check:platform && npm run check:no-foreground && npm run check:helper-path && npm run check:highlight && npm run check:permissions && npm run check:plugin && npm run check:helper-refresh && npm run check:installer && npm run check:cli-exit && npm run check:recorder-logic && npm run check:exit-listeners",
     "build:native": "node scripts/build-native.mjs",
     "build:windows": "node scripts/build-native.mjs --platform windows",
     "build:linux": "node scripts/build-native.mjs --platform linux",
@@ -65,6 +65,7 @@
     "check:helper-signal": "node scripts/helper-signal.check.mjs",
     "check:installer": "node scripts/keychain-free-install.check.mjs",
     "check:cli-exit": "node scripts/cli-exit.check.mjs",
+    "check:exit-listeners": "node scripts/exit-listeners.check.mjs",
     "check:recorder-logic": "node scripts/recorder-logic.check.mjs",
     "check:recorder": "node scripts/recorder.check.mjs"
   },

package/prebuilt/macos/arm64/tangu-computer-use.app.json

@@ -1,10 +1,10 @@
 {
   "bundleId": "com.forsion.tangu-computer-use",
-  "version": "0.6.0",
-  "archiveSha256": "2888e7908a0f5cb3d9e2ae9dd26d4c53737d7cf0550eb7d1afccf58a773fda0a",
+  "version": "0.6.1",
+  "archiveSha256": "2be40b9a3e4f631149e20386407f7d5fecd43629e74bb72ec0b9a7bbae8fa111",
   "files": {
-    "Contents/MacOS/bridge": "1fac72ce2c0491c6191a877bc7ec373d17c0bc371d3ffe67cd27b11739eb94ef",
-    "Contents/Info.plist": "69122c51686853486a2453f8ac3ade5167f4a05b8614f235186aadbe1431b398",
+    "Contents/MacOS/bridge": "7536d08e0c6f7af89546b8c99c0880138f09e7bfda8cc774095d36a325a4a568",
+    "Contents/Info.plist": "2709584b447ddc4c49681e787e1c13a87050d4247a3c477a2d91098b846535a3",
     "Contents/_CodeSignature/CodeResources": "6686de10a28a2fe11b36cbb86dcbacc827cfc4ea116b4dabf1845e5aee629e9b"
   }
 }

package/prebuilt/macos/x64/tangu-computer-use.app.json

@@ -1,10 +1,10 @@
 {
   "bundleId": "com.forsion.tangu-computer-use",
-  "version": "0.6.0",
-  "archiveSha256": "aa25102c14e4777326ede78a71aa9bc4e452b4da1255c2849b5c248173708a52",
+  "version": "0.6.1",
+  "archiveSha256": "170dbcf0a0eb20b69096f0857bbd2cdbfd83d5f6cbcee36c9843481eca7ecf1e",
   "files": {
-    "Contents/MacOS/bridge": "8c09d6c17e70f329c7958cff4db15c1308bc97e73b42844f33c31de0ebf48318",
-    "Contents/Info.plist": "69122c51686853486a2453f8ac3ade5167f4a05b8614f235186aadbe1431b398",
+    "Contents/MacOS/bridge": "075e7c756e3ca0c093383bb7ccfe5d69f96d3e07ecd1a974ab40c9c1a6bec55e",
+    "Contents/Info.plist": "2709584b447ddc4c49681e787e1c13a87050d4247a3c477a2d91098b846535a3",
     "Contents/_CodeSignature/CodeResources": "6686de10a28a2fe11b36cbb86dcbacc827cfc4ea116b4dabf1845e5aee629e9b"
   }
 }

package/scripts/exit-listeners.check.mjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+// 插件热插拔下的进程退出监听。宿主停用插件时调 deactivate(),再启用会在**同一个模块对象**上再调 activate(ctx);
+// 同 id 升级则 import 一份新模块(新一代)。钉住 src/index.ts 挂的 exit / SIGTERM / SIGINT 监听:
+//   同一模块连续 activate 每个事件只多 1 个;deactivate 回到基线(照旧收口一次);再启用又是 1 个;
+//   新一代自带一份,旧一代 deactivate 只摘自己的。
+// 照 cli-exit.check.mjs 的办法从源码现打一份 bundle,tools / setup / vendor/bridge 换成桩:
+// 只测 activate / deactivate 的接线,不起 helper、不装任何东西。
+import assert from 'node:assert/strict';
+import { build } from 'esbuild';
+import { mkdtempSync, rmSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const EVENTS = ['exit', 'SIGTERM', 'SIGINT'];
+const FIXTURES = {
+  './tools.ts': `export const PLUGIN_ID = 'computer-use'; export const buildToolProvider = () => ({ tools: () => [] });`,
+  './setup.ts': `export async function cliMain() { return 0; }`,
+  './vendor/bridge.ts': `export async function shutdownComputerUseSession() { globalThis.__cuShutdowns = (globalThis.__cuShutdowns ?? 0) + 1; }`,
+};
+
+const temp = mkdtempSync(path.join(os.tmpdir(), 'cu-exit-listeners-'));
+try {
+  const bundle = path.join(temp, 'plugin.mjs');
+  await build({ entryPoints: [path.join(root, 'src/index.ts')], outfile: bundle, bundle: true, platform: 'node', format: 'esm',
+    plugins: [{ name: 'lifecycle-fixture', setup(b) {
+      b.onResolve({ filter: /^\.\/(tools|setup|vendor\/bridge)\.ts$/ }, (args) => ({ path: args.path, namespace: 'fixture' }));
+      b.onLoad({ filter: /.*/, namespace: 'fixture' }, (args) => ({ contents: FIXTURES[args.path] }));
+    } }], logLevel: 'silent' });
+
+  const base = Object.fromEntries(EVENTS.map((ev) => [ev, process.listenerCount(ev)]));
+  const expectListeners = (extra, label) => {
+    for (const ev of EVENTS) assert.equal(process.listenerCount(ev), base[ev] + extra, `${label}: '${ev}' listeners`);
+    console.log(`PASS ${label}`);
+  };
+  const ctx = { registerPlugin() {}, registerCommand() {}, log() {}, sdk: { pluginStore: {} } };
+  // 带不同 query 再 import 一次 = 一份全新的模块对象,模拟同 id 升级换代。
+  const load = async (generation) => (await import(`${pathToFileURL(bundle).href}?generation=${generation}`)).default;
+
+  const gen1 = await load(1);
+  gen1.activate(ctx);
+  gen1.activate(ctx);
+  expectListeners(1, 'activating the same module twice leaves one listener per event');
+  gen1.deactivate();
+  expectListeners(0, 'deactivate removes them');
+  assert.equal(globalThis.__cuShutdowns, 1, 'deactivate still shuts the session down once');
+  gen1.activate(ctx);
+  expectListeners(1, 're-enabling after deactivate registers them again');
+
+  const gen2 = await load(2);
+  assert.notEqual(gen2, gen1, 'the second import must be a fresh module object');
+  gen2.activate(ctx);
+  expectListeners(2, 'a new generation registers its own listeners');
+  gen1.deactivate();
+  expectListeners(1, "the old generation's deactivate leaves the new generation's listeners");
+  gen2.deactivate();
+  expectListeners(0, 'the new generation deactivates back to the baseline');
+} finally {
+  rmSync(temp, { recursive: true, force: true });
+}

package/src/index.ts

@@ -11,6 +11,14 @@ import { SETTINGS } from './settings.ts';
 import { cliMain } from './setup.ts';
 import { shutdownComputerUseSession } from './vendor/bridge.ts';
 
+// helper 惰性启动后常驻;进程退出时收口(无 pi 的 session_shutdown 钩子)。
+// stop 放模块级、引用唯一:宿主热插拔时会在同一个模块对象上反复 activate / deactivate(启动时每个插件先 activate、
+// 未启用的随即 deactivate;停用后再启用;activate 抛错也补调一次 deactivate)。每次 activate 新建 stop 的话 deactivate
+// 摘不掉,每拨一次开关叠一组监听 → MaxListenersExceededWarning、退出时 shutdown 跑 N 遍。
+// 同 id 升级 import 的是新一代模块,自带一个 stop:各代只摘自己的,互不干扰。
+const EXIT_EVENTS = ['exit', 'SIGTERM', 'SIGINT'] as const;
+const stop = (): void => { void shutdownComputerUseSession(); };
+
 const plugin: TanguPlugin = {
   activate(ctx) {
     ctx.registerPlugin({
@@ -47,15 +55,17 @@ const plugin: TanguPlugin = {
       ctx.registerCommand({ name: 'computer-use', summary: 'Computer Use: setup / doctor / stop', run: cliMain });
     }
 
-    // helper 惰性启动后常驻;进程退出时收口(无 pi 的 session_shutdown 钩子)。
-    const stop = (): void => { void shutdownComputerUseSession(); };
-    process.once('exit', stop);
-    process.once('SIGTERM', stop);
-    process.once('SIGINT', stop);
+    // 先摘再挂:同一模块对象上再 activate(停用后再启用、抛错后再次激活)也只挂一组。
+    for (const ev of EXIT_EVENTS) {
+      process.off(ev, stop);
+      process.once(ev, stop);
+    }
 
     ctx.log('computer-use plugin registered');
   },
   deactivate() {
+    // 只摘本模块自己的 stop(新一代模块与宿主的监听不动),helper 照旧收口。
+    for (const ev of EXIT_EVENTS) process.off(ev, stop);
     void shutdownComputerUseSession();
   },
 };

package/tangu-plugins/computer-use/dist/index.js

@@ -5191,9 +5191,9 @@ function waitFor(work, signal) {
         fn();
       }
     };
-    const stop = (why) => () => settle(() => reject(new Error(`${why}; the installer may still finish in the background`)));
-    const timer = setTimeout(stop("helper setup is taking longer than expected"), SETUP_TIMEOUT_MS);
-    const onAbort = stop("helper setup wait was interrupted");
+    const stop2 = (why) => () => settle(() => reject(new Error(`${why}; the installer may still finish in the background`)));
+    const timer = setTimeout(stop2("helper setup is taking longer than expected"), SETUP_TIMEOUT_MS);
+    const onAbort = stop2("helper setup wait was interrupted");
     signal?.addEventListener("abort", onAbort, { once: true });
     work.then((v) => settle(() => resolve(v)), (e) => settle(() => reject(e instanceof Error ? e : new Error(String(e)))));
   });
@@ -5626,6 +5626,10 @@ async function doctor() {
 }
 
 // src/index.ts
+var EXIT_EVENTS = ["exit", "SIGTERM", "SIGINT"];
+var stop = () => {
+  void shutdownComputerUseSession();
+};
 var plugin = {
   activate(ctx) {
     ctx.registerPlugin({
@@ -5654,15 +5658,14 @@ var plugin = {
     if (typeof ctx.registerCommand === "function") {
       ctx.registerCommand({ name: "computer-use", summary: "Computer Use: setup / doctor / stop", run: cliMain });
     }
-    const stop = () => {
-      void shutdownComputerUseSession();
-    };
-    process.once("exit", stop);
-    process.once("SIGTERM", stop);
-    process.once("SIGINT", stop);
+    for (const ev of EXIT_EVENTS) {
+      process.off(ev, stop);
+      process.once(ev, stop);
+    }
     ctx.log("computer-use plugin registered");
   },
   deactivate() {
+    for (const ev of EXIT_EVENTS) process.off(ev, stop);
     void shutdownComputerUseSession();
   }
 };

package/tangu-plugins/computer-use/tangu-plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "computer-use",
   "name": "Computer Use",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "apiVersion": 1,
   "entry": "dist/index.js",
   "commands": ["computer-use"],

package/types/tangu-agent.d.ts

@@ -35,6 +35,44 @@ export interface ToolContext {
    *  缺省(未装配此闸)时工具应优雅降级,不要假定一定可用。 */
   collectImage?: (img: { url: string; name?: string }) => void;
   displayFile?: (item: { name: string; mime?: string; path?: string; dataUrl?: string }) => void;
+  /** 发起端(手机)自报的客户端能力,如 'phone.intents'(run 内冻结)。契约 tangu-agent/docs/phone-control.md §2。 */
+  clientCapabilities?: readonly string[];
+  /** 让发起端原生层执行一个动作:发 `client_cmd` → 原生 claim → 执行 → 回执。闭包已绑定本 run,只在
+   *  clientCapabilities 非空时存在(缺省时工具应优雅降级),且**只给声明了 `clientCapability` 的工具**:
+   *  没声明的工具(以及任何工具的 isEnabledFor)拿到 undefined;声明了的只能发自己能力的 ns
+   *  ('phone.intents' → 'phone'),别的 ns 立即 {ok:false, code:'undeclared'}、什么都不发。
+   *  `opts.signal` 传 ctx.signal;run 级中止总会一并监听。
+   *  ⚠️ 若工具声明了 capabilities.defaultTimeoutMs,它必须 ≥ claimMs + execMs —— 否则工具先被判超时,
+   *  手机那边却可能在稍后照样执行。 */
+  requestClientAction?: (req: ClientActionRequest, opts?: ClientActionOptions) => Promise<ClientActionResult>;
+}
+
+/** 客户端动作。ns 必须命中本 run 已声明的 `<ns>.*` 能力(否则立即 {ok:false, code:'undeclared'});op 由原生 verb 表解释。 */
+export interface ClientActionRequest {
+  ns: string;
+  op: string;
+  args?: Record<string, unknown>;
+}
+
+/** claimMs:等原生 claim(缺省 15s,钳 3–30s);execMs:claim 之后等结果(缺省 20s,钳 5–120s)。 */
+export interface ClientActionOptions {
+  claimMs?: number;
+  execMs?: number;
+  signal?: AbortSignal;
+}
+
+/** 原生回执(已消毒)或引擎自产的失败。code 恒匹配 /^[a-z_]{1,32}$/:原生码见契约 §3.4,
+ *  引擎自产 undeclared / not_picked_up(没接,什么都没发生)/ no_report(接了没回,可能发生了)/
+ *  aborted(没接就被中止,什么都没发生)/ aborted_claimed(接了之后被中止,可能发生了)。 */
+export interface ClientActionResult {
+  ok: boolean;
+  code?: string;
+  error?: string;
+  text?: string;
+  image?: string;
+  app?: string;
+  handoff?: boolean;
+  verified?: boolean;
 }
 
 export interface ToolCapabilities {
@@ -58,6 +96,16 @@ export interface ToolDef {
   mode?: 'sandbox' | 'host' | 'both';
   capabilities?: ToolCapabilities;
   isEnabledFor?(profile: AppProfile, ctx: ToolContext): boolean;
+  /** 按需装载:true = 定义默认不进工具面,系统提示「Additional Tools」目录里只留一行,模型经 load_tools 解锁。 */
+  deferred?: boolean;
+  /** 同组连坐解锁:解锁组内任一即整组解锁。 */
+  deferGroup?: string;
+  /** 目录行文案(英文一句话,带典型触发意图;缺省取 description 首行截断)。 */
+  deferHint?: string;
+  /** 客户端能力(如 'phone.intents'):本工具经 ctx.requestClientAction 让发起端原生层执行。声明后由核心中央闸
+   *  default-deny(手机端发起 + 本 run 声明了该能力 + 非子代理 / 计划 / 通道 / 讨论),且工具名必须以 `<ns>_` 开头
+   *  ('phone.intents' → phone_*),否则永不可见。chat 预设按能力放行,内置与插件等价。 */
+  clientCapability?: string;
 }
 
 export interface ToolProvider {
@@ -135,8 +183,19 @@ export interface TanguPluginContext {
   activity: { append(event: string, detail?: Record<string, unknown>): void };
 }
 
+/**
+ * 生命周期:启动时每个插件都 activate 一次,未启用 / 前置没齐的随即 deactivate 休眠(仍列在设置页)。
+ * 停用、卸载、原地升级、前置消失时宿主调 `deactivate()`(限时 5s),再撤掉本次激活注册的一切(工具、命令、路由;meta 留着休眠)。
+ * 再启用会在**同一个模块对象**上再调一次 `activate(ctx)`:别依赖模块级「只做一次」的状态,activate 里起的定时器 /
+ * 子进程 / 监听都要在 deactivate 里收掉。activate 抛错则本次激活作废(回滚 + 调一次 deactivate 收尾),插件休眠不自动重试。
+ */
 export interface TanguPlugin {
-  manifest?: { id: string; name: string; version: string; apiVersion: number; entry: string; commands?: string[]; description?: string };
+  manifest?: {
+    id: string; name: string; version: string; apiVersion: number; entry: string; commands?: string[]; description?: string;
+    /** 前置插件:`"id"` 或 `{ id, minVersion? }`。前置已启用且在跑(版本 ≥ minVersion)时本插件才激活;否则休眠,就位后自动激活。 */
+    requiresPlugins?: Array<string | { id: string; minVersion?: string }>;
+  };
   activate(ctx: TanguPluginContext): void | Promise<void>;
+  /** 停用 / 卸载 / 原地升级时调用(限时 5s):停掉 activate 里起的后台工作。启动期那次早于引擎装配完成,只做自身收尾。 */
   deactivate?(): void | Promise<void>;
 }