vcorp-chrome 1.8.1 → 2.2.0

package/src/lib/desktop.js

@@ -0,0 +1,171 @@
+// 本机桌面执行器 —— 把 desktop 工具的一次调用变成一次 agent-desktop 子进程调用。
+//
+// agent-desktop 是无状态 CLI：每条命令一个进程、输出一个 JSON 信封（见它的 docs/json-output.md）。
+// 这一层做四件事：找到二进制；每条命令先过 extension/desktop-policy.js；
+// 记住每份快照属于哪个应用、哪个窗口（之后的 ref 命令对着它判）；把信封渲染成给模型看的短文本。
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import {
+  checkDesktop, checkObserved, recordOf, filterWindows, checkSteps, snapshotIdOf,
+} from '../../extension/desktop-policy.js';
+import { renderEnvelope } from '../../extension/desktop-render.js';
+
+const require = createRequire(import.meta.url);
+
+// npm 包 agent-desktop 自带各平台的二进制（bin/agent-desktop-<平台>-<架构>[.exe]）。
+// 直接调平台二进制，不经它的 JS 启动器：少起一个 node 进程，每条命令省一两百毫秒。
+export function findBinary() {
+  if (process.env.AGENT_DESKTOP_BIN) return process.env.AGENT_DESKTOP_BIN;
+  const name = `agent-desktop-${process.platform === 'win32' ? 'win32' : process.platform}-${process.arch}${process.platform === 'win32' ? '.exe' : ''}`;
+  try {
+    const dir = path.dirname(require.resolve('agent-desktop/package.json'));
+    const p = path.join(dir, 'bin', name);
+    if (fs.existsSync(p)) return p;
+  } catch { /* 没装这个依赖，退到 PATH */ }
+  return process.platform === 'win32' ? 'agent-desktop.exe' : 'agent-desktop';
+}
+
+const OUT_MAX = 8 * 1024 * 1024;
+
+// 跑一次，返回信封。不经 shell：参数数组原样交给进程，没有拼接、没有转义问题。
+export function runAgentDesktop(argv, { bin = findBinary(), timeoutMs = 30000 } = {}) {
+  return new Promise((resolve) => {
+    let out = '';
+    let errText = '';
+    let done = false;
+    const finish = (env) => { if (!done) { done = true; clearTimeout(timer); resolve(env); } };
+    let child;
+    try {
+      child = spawn(bin, argv, { windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] });
+    } catch (e) {
+      finish(fail('DESKTOP_UNAVAILABLE', `起不来 agent-desktop（${bin}）：${e.message}`));
+      return;
+    }
+    const timer = setTimeout(() => {
+      child.kill();
+      finish(fail('TIMEOUT', `agent-desktop ${Math.round(timeoutMs / 1000)}s 没有回音，结果不明。先 snapshot 看现状，别直接重做。`, 'unknown'));
+    }, timeoutMs);
+    child.stdout.on('data', (b) => { if (out.length < OUT_MAX) out += b; });
+    child.stderr.on('data', (b) => { if (errText.length < 4000) errText += b; });
+    child.on('error', (e) => finish(fail('DESKTOP_UNAVAILABLE',
+      e.code === 'ENOENT' ? '这台电脑上没有 agent-desktop。运行 npx vcorp-chrome doctor 看怎么装。' : e.message)));
+    child.on('close', () => {
+      const line = out.trim().split('\n').filter(Boolean).at(-1) || '';
+      try { finish(JSON.parse(line)); } catch {
+        finish(fail('INTERNAL', `agent-desktop 的输出不是 JSON：${(line || errText).slice(0, 300)}`, 'unknown'));
+      }
+    });
+  });
+}
+
+function fail(code, message, delivery = 'not_delivered') {
+  return { ok: false, error: { code, message, disposition: { delivery, retry: delivery === 'not_delivered' ? 'safe' : 'unknown' } } };
+}
+
+// ---------- 会话 ----------
+
+const SNAPS_MAX = 64;
+
+// 一个 vcorp 会话（一个 MCP server 进程）一个实例。快照户口只活在内存里：
+// 进程没了户口也没了，那时 ref 命令会被要求重新 snapshot——宁可多拍一次，也不认来路不明的 ref。
+export class DesktopSession {
+  constructor({ session, channel = 'local', bin = findBinary(), run = runAgentDesktop } = {}) {
+    this.session = String(session || 'vcorp').replace(/[^\w-]/g, '-').slice(0, 64);
+    this.channel = channel;
+    this.bin = bin;
+    this.runner = run;
+    this.snaps = new Map();
+    this.windows = new Map();
+  }
+
+  remember(rec) {
+    this.snaps.delete(rec.id);
+    this.snaps.set(rec.id, rec);
+    while (this.snaps.size > SNAPS_MAX) this.snaps.delete(this.snaps.keys().next().value);
+  }
+
+  async refreshWindows() {
+    const env = await this.runner(['list-windows'], { bin: this.bin, timeoutMs: 15000 });
+    if (env?.ok && Array.isArray(env.data)) {
+      for (const w of env.data) this.windows.set(w.id, { app: w.app_name, title: w.title || '' });
+    }
+    return env;
+  }
+
+  ctx() {
+    return {
+      channel: this.channel,
+      session: this.session,
+      lookup: (id) => this.snaps.get(id) || null,
+      windows: (id) => this.windows.get(id) || null,
+    };
+  }
+
+  // 一条命令。返回 { text, image?, env, sensitive }。策略不过直接抛（code 在 e.code 上）。
+  async run(params, { timeoutMs = 30000, allowSensitive = true } = {}) {
+    if (params?.steps !== undefined) return this.steps(params.steps, { timeoutMs });
+    if (params?.window && !this.windows.has(String(params.window))) await this.refreshWindows();
+    const chk = checkDesktop(params, this.ctx());
+    if (chk.sensitive === 'pay') {
+      throw Object.assign(new Error(`「${chk.target?.name}」像是要花钱的按钮。桌面能力不代做付款，请用户亲手点。`), { code: 'PAY_REFUSED' });
+    }
+    if (chk.sensitive && !allowSensitive) {
+      throw Object.assign(new Error(`「${chk.target?.name}」是发送/删除一类的动作，批处理不代做。单独调用一次 desktop ${chk.cmd}。`), { code: 'NEEDS_SINGLE_CALL' });
+    }
+    let shot = null;
+    if (chk.cmd === 'screenshot') {
+      shot = path.join(os.tmpdir(), `vcorp-desktop-${process.pid}-${Date.now()}.png`);
+      chk.argv.push(shot);
+    }
+    const env = await this.runner(chk.argv, { bin: this.bin, timeoutMs });
+
+    if (env?.ok && (chk.cmd === 'snapshot' || chk.cmd === 'find')) {
+      const rec = recordOf(env.data);
+      if (rec && !rec.app) rec.app = chk.app;
+      if (rec && !rec.window && env.data.window) rec.window = env.data.window;
+      if (chk.cmd === 'snapshot') checkObserved(rec);
+      if (rec) {
+        const prev = chk.cmd === 'find' ? this.snaps.get(rec.id) : null;
+        this.remember(prev ? { ...prev, refs: { ...prev.refs, ...rec.refs } } : rec);
+      }
+    }
+    if (env?.ok && chk.cmd === 'list-windows') {
+      for (const w of env.data || []) this.windows.set(w.id, { app: w.app_name, title: w.title || '' });
+      env.data = filterWindows(env.data, this.channel);
+    }
+    let image = null;
+    if (shot) {
+      try { image = fs.readFileSync(shot).toString('base64'); } catch { /* 截图失败时信封里有原因 */ }
+      fs.rmSync(shot, { force: true });
+    }
+    return { text: renderEnvelope(chk.cmd, env, { target: chk.target }), image, env, cmd: chk.cmd, app: chk.app, sensitive: chk.sensitive };
+  }
+
+  // 一串步骤：每步过同一套检查，任何一步失败或碰到敏感动作就停，讲清做到哪、为什么停
+  async steps(list, { timeoutMs = 30000 } = {}) {
+    checkSteps(list);
+    const out = [];
+    for (let i = 0; i < list.length; i++) {
+      const st = list[i];
+      let r;
+      try {
+        r = await this.run(st, { timeoutMs, allowSensitive: false });
+      } catch (e) {
+        out.push(`⏸ 第 ${i + 1}/${list.length} 步 ${st.cmd}：${e.message}`);
+        out.push(`剩下 ${list.length - i - 1} 步没做。`);
+        return { text: out.join('\n'), stopped: true };
+      }
+      out.push(`— ${i + 1}/${list.length} ${st.cmd}\n${r.text}`);
+      if (!r.env?.ok) {
+        out.push(`⏸ 停在第 ${i + 1} 步，剩下 ${list.length - i - 1} 步没做。`);
+        return { text: out.join('\n'), stopped: true };
+      }
+    }
+    return { text: out.join('\n\n') };
+  }
+}
+
+export { snapshotIdOf };

package/src/lib/native-install.js

@@ -0,0 +1,139 @@
+// 原生消息宿主的安装 / 卸载 / 体检（npx vcorp-chrome desktop install|uninstall|status）。
+//
+// Chrome 找宿主靠一份清单：Windows 在注册表 HKCU 下登记清单路径，macOS / Linux 把清单放进
+// 浏览器约定的目录。清单的 path 指向一个启动脚本，脚本用装它时的那个 node 跑 native-host/host.js。
+// allowed_origins 只写本扩展：扩展 id 由 manifest.json 里的 key 算出来，不手抄。
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { spawn, execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { HOME, ensureHome } from './paths.js';
+
+export const HOST_NAME = 'ai.vcorp.desktop';
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+const HOST_JS = path.join(ROOT, 'native-host', 'host.js');
+const DIR = path.join(HOME, 'desktop-host');
+const MANIFEST = path.join(DIR, `${HOST_NAME}.json`);
+
+// Chrome 的扩展 id：公钥 DER 的 sha256 前 16 字节，每个十六进制位 0-f 映射成 a-p
+export function extensionId(manifestKey) {
+  const hex = crypto.createHash('sha256').update(Buffer.from(manifestKey, 'base64')).digest('hex').slice(0, 32);
+  return [...hex].map((c) => String.fromCharCode(97 + parseInt(c, 16))).join('');
+}
+
+function ourExtensionId() {
+  const mf = JSON.parse(fs.readFileSync(path.join(ROOT, 'extension', 'manifest.json'), 'utf8'));
+  return extensionId(mf.key);
+}
+
+const REG_KEYS = [
+  `HKCU\\Software\\Google\\Chrome\\NativeMessagingHosts\\${HOST_NAME}`,
+  `HKCU\\Software\\Microsoft\\Edge\\NativeMessagingHosts\\${HOST_NAME}`,
+];
+
+function manifestDirs() {
+  const h = os.homedir();
+  if (process.platform === 'darwin') {
+    const base = path.join(h, 'Library', 'Application Support');
+    return ['Google/Chrome', 'Chromium', 'Microsoft Edge', 'BraveSoftware/Brave-Browser'].map((b) => path.join(base, b, 'NativeMessagingHosts'));
+  }
+  return ['google-chrome', 'chromium', 'microsoft-edge', 'BraveSoftware/Brave-Browser'].map((b) => path.join(h, '.config', b, 'NativeMessagingHosts'));
+}
+
+export function install() {
+  ensureHome();
+  fs.mkdirSync(DIR, { recursive: true });
+  const win = process.platform === 'win32';
+  const launcher = path.join(DIR, win ? 'vcorp-desktop-host.cmd' : 'vcorp-desktop-host');
+  fs.writeFileSync(launcher, win
+    ? `@echo off\r\n"${process.execPath}" "${HOST_JS}" %*\r\n`
+    : `#!/bin/sh\nexec "${process.execPath}" "${HOST_JS}" "$@"\n`);
+  if (!win) fs.chmodSync(launcher, 0o755);
+  const id = ourExtensionId();
+  fs.writeFileSync(MANIFEST, JSON.stringify({
+    name: HOST_NAME,
+    description: 'vcorp-chrome desktop host',
+    path: launcher,
+    type: 'stdio',
+    allowed_origins: [`chrome-extension://${id}/`],
+  }, null, 2));
+  const placed = [];
+  if (win) {
+    for (const key of REG_KEYS) {
+      execFileSync('reg', ['add', key, '/ve', '/t', 'REG_SZ', '/d', MANIFEST, '/f'], { stdio: 'ignore', windowsHide: true });
+      placed.push(key);
+    }
+  } else {
+    for (const dir of manifestDirs()) {
+      if (!fs.existsSync(path.dirname(dir))) continue;   // 没装这个浏览器
+      fs.mkdirSync(dir, { recursive: true });
+      fs.copyFileSync(MANIFEST, path.join(dir, `${HOST_NAME}.json`));
+      placed.push(dir);
+    }
+  }
+  return { id, launcher, manifest: MANIFEST, placed };
+}
+
+export function uninstall() {
+  const removed = [];
+  if (process.platform === 'win32') {
+    for (const key of REG_KEYS) {
+      try { execFileSync('reg', ['delete', key, '/f'], { stdio: 'ignore', windowsHide: true }); removed.push(key); } catch { /* 本来就没登记 */ }
+    }
+  } else {
+    for (const dir of manifestDirs()) {
+      const f = path.join(dir, `${HOST_NAME}.json`);
+      if (fs.existsSync(f)) { fs.rmSync(f); removed.push(f); }
+    }
+  }
+  fs.rmSync(DIR, { recursive: true, force: true });
+  return { removed };
+}
+
+// 按 Chrome 的方式跟宿主说一句话：起启动脚本、写一条带长度前缀的消息、读一条回包
+export function talk(msg, { launcher, timeoutMs = 20000 } = {}) {
+  return new Promise((resolve, reject) => {
+    const win = process.platform === 'win32';
+    const child = win
+      ? spawn('cmd.exe', ['/d', '/c', launcher, `chrome-extension://${ourExtensionId()}/`], { windowsHide: true })
+      : spawn(launcher, [`chrome-extension://${ourExtensionId()}/`]);
+    const chunks = [];
+    const timer = setTimeout(() => { child.kill(); reject(new Error(`宿主 ${timeoutMs / 1000}s 没有回包`)); }, timeoutMs);
+    child.stdout.on('data', (b) => chunks.push(b));
+    child.on('error', (e) => { clearTimeout(timer); reject(e); });
+    child.on('close', () => {
+      clearTimeout(timer);
+      const buf = Buffer.concat(chunks);
+      if (buf.length < 4) return reject(new Error('宿主没有回包'));
+      resolve(JSON.parse(buf.subarray(4, 4 + buf.readUInt32LE(0)).toString('utf8')));
+    });
+    const body = Buffer.from(JSON.stringify(msg), 'utf8');
+    const len = Buffer.alloc(4);
+    len.writeUInt32LE(body.length, 0);
+    child.stdin.end(Buffer.concat([len, body]));
+  });
+}
+
+export async function status() {
+  const lines = [];
+  let launcher = '';
+  if (!fs.existsSync(MANIFEST)) return { installed: false, lines: ['没有安装：运行 npx vcorp-chrome desktop install'] };
+  const mf = JSON.parse(fs.readFileSync(MANIFEST, 'utf8'));
+  launcher = mf.path;
+  lines.push(`清单 ${MANIFEST}`);
+  if (process.platform === 'win32') {
+    for (const key of REG_KEYS) {
+      let ok = false;
+      try { ok = execFileSync('reg', ['query', key, '/ve'], { encoding: 'utf8', windowsHide: true }).includes(MANIFEST); } catch { /* 没登记 */ }
+      lines.push(`${ok ? '✅' : '❌'} ${key}`);
+    }
+  }
+  if (!fs.existsSync(HOST_JS)) lines.push(`❌ 启动脚本指向的 ${HOST_JS} 不在了（npx 缓存被清过？）：重新运行 desktop install`);
+  const hello = await talk({ op: 'hello' }, { launcher });
+  lines.push(hello.ready
+    ? `✅ 宿主应答 · 设备 ${hello.device.id} · agent-desktop 可用`
+    : `❌ 宿主应答了，但 agent-desktop 用不了：[${hello.error?.code}] ${hello.error?.message}`);
+  return { installed: true, ready: !!hello.ready, device: hello.device, lines };
+}

package/src/lib/paths.js

@@ -11,8 +11,43 @@ export const AUDIT_FILE = path.join(HOME, 'audit.jsonl');
 export const ALLOWLIST_FILE = path.join(HOME, 'allowlist.json');
 export const LOG_FILE = path.join(HOME, 'bridge.log');
 
+export const MACHINE_FILE = path.join(HOME, 'machine.json');
+
+// 桌面完全模式的开关。只在这台电脑上用 `vcorp-chrome desktop full on|off` 改，
+// 原生宿主每条命令现读一次——服务器、网页、扩展都写不到这个文件。
+export const FULL_FILE = path.join(HOME, 'desktop-full.json');
+
+export function fullMode() {
+  try { return JSON.parse(fs.readFileSync(FULL_FILE, 'utf8')).on === true; } catch { return false; }
+}
+
+export function setFullMode(on) {
+  ensureHome();
+  if (!on) { fs.rmSync(FULL_FILE, { force: true }); return false; }
+  fs.writeFileSync(FULL_FILE, JSON.stringify({ on: true, at: new Date().toISOString() }, null, 2), { mode: 0o600 });
+  return true;
+}
+
 export const DEFAULT_PORT = 8899;
 
+// 这台电脑（这个系统用户）的身份。本机 MCP 和原生宿主（native-host/）读同一个文件，
+// 所以同一台电脑上的桌面设备在两条通道里是同一个设备号。第一次用时生成，之后不变。
+export function machineId() {
+  try {
+    const id = JSON.parse(fs.readFileSync(MACHINE_FILE, 'utf8')).machineId;
+    if (/^m_[0-9a-f]{16}$/.test(id)) return id;
+  } catch { /* 还没有，下面生成 */ }
+  ensureHome();
+  const id = `m_${crypto.randomBytes(8).toString('hex')}`;
+  const tmp = `${MACHINE_FILE}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify({ machineId: id, createdAt: new Date().toISOString() }, null, 2), { mode: 0o600 });
+  try { fs.linkSync(tmp, MACHINE_FILE); } catch { /* 别的进程抢先写好了，用它的 */ }
+  fs.rmSync(tmp, { force: true });
+  return JSON.parse(fs.readFileSync(MACHINE_FILE, 'utf8')).machineId;
+}
+
+export const desktopDeviceId = (machine) => `desktop-${machine}`;
+
 export function ensureHome() {
   fs.mkdirSync(HOME, { recursive: true, mode: 0o700 });
   return HOME;

package/src/lib/rpc.js

@@ -100,6 +100,7 @@ export class BridgeClient {
           this.extensionVersion = msg.extensionVersion;
           this.versionMismatch = !!msg.versionMismatch;
           this.extensionProtocol = msg.extensionProtocol;
+          this.bridgeDevices = !!msg.devices;
           ws.onmessage = (e2) => this.#dispatch(JSON.parse(e2.data));
           ws.onclose = () => { this.ws = null; this.#failAll('桥连接已断开'); };
           ws.onerror = () => {};
@@ -144,7 +145,11 @@ export class BridgeClient {
   }
 
   // 桥侧已有 30s 超时兜底；这里的 35s 只防「桥自己也没了」的情况
-  async call(cmd, params = {}, { tabId, timeoutMs = 35000 } = {}) {
+  // device：指定投给哪一个浏览器设备（devices 列出的 id）。不给就由桥挑有窗口、最近活跃的那个。
+  async call(cmd, params = {}, { tabId, timeoutMs = 35000, device } = {}) {
+    if ((device || cmd === 'devices') && this.ws && !this.bridgeDevices) {
+      throw Object.assign(new Error('在跑的桥是旧版本，不认识设备：指定 device 的命令会被它投给默认的 Chrome。所有会话都退出、桥自动重启之后再用。'), { code: 'BRIDGE_OLD' });
+    }
     if (!this.ws) await this.connect();
     const id = 'c' + ++this.seq;
     return new Promise((resolve, reject) => {
@@ -154,7 +159,7 @@ export class BridgeClient {
       }, timeoutMs);
       this.waiting.set(id, { resolve, reject, timer });
       // 桥侧也要知道这条命令能等多久，否则它按默认 30s 就把慢命令判死了
-      this.ws.send(JSON.stringify({ type: 'cmd', id, cmd, params, tabId, timeout: timeoutMs - 3000 }));
+      this.ws.send(JSON.stringify({ type: 'cmd', id, cmd, params, tabId, timeout: timeoutMs - 3000, ...(device ? { to: { device } } : {}) }));
     });
   }
 }

package/src/mcp-server.js

@@ -12,8 +12,12 @@ import { resolveHost } from './lib/host.js';
 import { flatCount } from '../extension/script.js';
 import { LOADS } from '../extension/loads/index.js';
 import { getLearnings, saveLearnings, saveDraft, adoptDraft } from './lib/learnings.js';
-import { audit } from './lib/paths.js';
+import { audit, machineId, desktopDeviceId } from './lib/paths.js';
+import { DesktopSession, findBinary } from './lib/desktop.js';
+import { redact } from './bridge.js';
+import { describeDevices } from '../extension/device.js';
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { VERSION } from './lib/version.js';
 import { compat, compatNote } from '../extension/compat.js';
@@ -208,6 +212,7 @@ const TOOLS = [
         tabId: TAB,
         label: { type: 'string', description: 'With new/select: what this tab is for ("CRM import — batch 2"). Shown in list, page panel, and to the user.' },
         focus: { type: 'boolean', description: 'Also bring the tab to the foreground. Interrupts the user — off by default.' },
+        device: { type: 'string', description: 'With 2+ Chromes: id from devices. That tabId then sticks to it.' },
       },
       required: ['action'],
     },
@@ -500,6 +505,39 @@ const TOOLS = [
       },
     },
   },
+  {
+    name: 'desktop',
+    description:
+      'Native apps and OS dialogs (the file picker a page opens) via the accessibility tree. '
+      + 'list-windows → snapshot {app|window} → act on the FULL ref "@s…:eN" → read the effect line. '
+      + 'Browser windows are refused (use browser tools). headed:true = real mouse/keys. '
+      + 'steps:[{cmd,…}] (≤20) stops on failure or send/delete.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        cmd: {
+          type: 'string',
+          enum: ['list-apps', 'list-windows', 'snapshot', 'find', 'get', 'screenshot', 'wait', 'click', 'double-click',
+            'right-click', 'type', 'set-value', 'clear', 'focus', 'select', 'toggle', 'check', 'uncheck', 'expand',
+            'collapse', 'scroll', 'scroll-to', 'press', 'launch', 'focus-window', 'clipboard-set', 'clipboard-get',
+            'list-notifications', 'notification-action'],
+        },
+        app: { type: 'string' }, window: { type: 'string' }, ref: { type: 'string' },
+        root: { type: 'string' }, skeleton: { type: 'boolean' }, all: { type: 'boolean' },
+        text: { type: 'string' }, value: { type: 'string' }, keys: { type: 'string', description: 'press: "ctrl+s"' },
+        role: { type: 'string' }, name: { type: 'string' }, nth: { type: 'number' }, property: { type: 'string' },
+        direction: { type: 'string' }, amount: { type: 'number' },
+        ms: { type: 'number' }, windowTitle: { type: 'string' }, timeout: { type: 'number' },
+        index: { type: 'number' }, action: { type: 'string' }, headed: { type: 'boolean' },
+        steps: { type: 'array', items: { type: 'object' } },
+      },
+    },
+  },
+  {
+    name: 'devices',
+    description: 'Devices this session can drive: each connected Chrome and this computer\'s desktop.',
+    inputSchema: { type: 'object', properties: {} },
+  },
   {
     name: 'reload',
     description:
@@ -552,7 +590,7 @@ warning change target or approach, never repeat the same call.
 
 A STEP NEEDS A HUMAN (captcha, QR login, OTP, payment)? Call \`ask\` — never retry or work
 around. Never let a download put a dialog on their screen: see the \`download\` tool for the
-required order. OS file dialogs are beyond any extension.`;
+required order. Native apps and OS file dialogs: \`desktop\`.`;
 
 // 页面来的文本全部走这里。边界标记 + 降权说明，both 是给模型看的。
 function wrapUntrusted(body, meta = '') {
@@ -573,6 +611,9 @@ export async function startMcpServer({ client = 'unknown' } = {}) {
 
   server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
 
+  let desk = null;
+  const tabDevice = new Map();
+
   // 宿主身份：--client 只是兜底，真名以 initialize 里宿主自报的 clientInfo 为准
   // （见 src/lib/host.js）。握手一定先于第一条工具调用，所以在那时认一次就够。
   let host = null;
@@ -585,7 +626,7 @@ export async function startMcpServer({ client = 'unknown' } = {}) {
     return host;
   };
 
-  server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  server.setRequestHandler(CallToolRequestSchema, busy(async (req) => {
     const { name, arguments: args = {} } = req.params;
     identify();
     try {
@@ -598,12 +639,51 @@ export async function startMcpServer({ client = 'unknown' } = {}) {
         return { content: [{ type: 'text', text }] };
       }
 
+      // desktop 也不经过桥：本机直接起 agent-desktop 子进程。审计照记，设备号写本机桌面
+      if (name === 'desktop') {
+        desk ??= new DesktopSession({ session: `vc-${bridge.sessionId}` });
+        const t0 = Date.now();
+        const id = `desktop:${t0}`;
+        const cmd = `desktop.${args.steps !== undefined ? 'steps' : args.cmd}`;
+        audit({ ev: 'cmd', id, cmd, client: bridge.client, sid: bridge.sessionId, device: desktopDeviceId(machineId()), params: redact(args) });
+        let r;
+        try {
+          r = await desk.run(args, { timeoutMs: args.steps ? 120000 : Math.min(Math.max((Number(args.timeout) || 0) + 10000, 30000), 600000) });
+        } catch (e) {
+          audit({ ev: 'res', id, cmd, ok: false, ms: Date.now() - t0, error: e.code || 'INTERNAL' });
+          throw e;
+        }
+        const ok = r.env ? !!r.env.ok : !r.stopped;
+        audit({ ev: 'res', id, cmd, ok, ms: Date.now() - t0, error: ok ? undefined : r.env?.error?.code, effect: r.env?.data?.disposition?.delivery });
+        if (r.image) return { content: [{ type: 'image', data: r.image, mimeType: 'image/png' }] };
+        return { content: [{ type: 'text', text: wrapUntrusted(r.text, 'source="desktop"') }], isError: !ok || undefined };
+      }
+
+      if (name === 'devices') {
+        const machine = machineId();
+        const list = [{ id: desktopDeviceId(machine), kind: 'desktop', name: `${os.hostname()} 桌面`, machine, online: true,
+          caps: { platform: process.platform } }];
+        let browserNote = '';
+        try {
+          if (!bridge.ws) await bridge.connect();
+          const d = await bridge.call('devices', {}, { timeoutMs: 8000 });
+          list.unshift(...d.devices.map((x) => (x.primary ? { ...x, name: `${x.name}（默认）` } : x)));
+        } catch (e) {
+          browserNote = `\n浏览器设备查不到：[${e.code || 'INTERNAL'}] ${e.message}`;
+        }
+        return { content: [{ type: 'text', text: describeDevices(list) + browserNote }] };
+      }
+
       if (!bridge.ws) await bridge.connect();
 
+      // 指定设备：tabs 带 device 时记住新开/选中的 tabId 属于哪台，之后同一 tabId 自动跟过去
+      const device = args.device || (args.tabId != null ? tabDevice.get(args.tabId) : undefined);
+      if (args.device !== undefined) delete args.device;
+
       // 翻页在这一侧循环：审计里 fetch→fetch 相邻 386 次，agent 在一页一个回合地
       // 手动翻。扩展只管发单次请求，翻页的循环、落盘、停机判定都不该经过模型。
       if (name === 'fetch' && args.pages && !args.binary) {
-        return { content: [{ type: 'text', text: await fetchPages(bridge, args) }] };
+        return { content: [{ type: 'text', text: await fetchPages(bridge, args, device) }] };
       }
 
       // upload：先把**路径**交给扩展，让它用 CDP 的 DOM.setFileInputFiles 让浏览器
@@ -617,7 +697,7 @@ export async function startMcpServer({ client = 'unknown' } = {}) {
         const base = { path: args.path, name: path.basename(args.path), type: mime, bytes: st.size, selector: args.selector, dropSelector: args.dropSelector };
         // 上传本身可能很慢（本机→浏览器只是投喂，但页面自己的上传要时间），给足预算
         const timeoutMs = Math.max(60000, Math.round(st.size / (1024 * 1024)) * 1000);
-        let out = args.dropSelector ? null : await bridge.call('upload', base, { tabId: args.tabId, timeoutMs });
+        let out = args.dropSelector ? null : await bridge.call('upload', base, { tabId: args.tabId, timeoutMs, device });
         if (!out || out.needBytes) {
           // 走拖放：这条必须有文件字节。超过 DROP_MAX 就明确报错，不要拿桥去撞——
           // 桥一断，当前 agent 会话就再也连不回来了，比报错难查得多。
@@ -629,7 +709,7 @@ export async function startMcpServer({ client = 'unknown' } = {}) {
               `先压小，或改用页面上真实存在的 file input（给 selector）。`);
           }
           out = await bridge.call('upload', { ...base, base64: fs.readFileSync(args.path).toString('base64') },
-            { tabId: args.tabId, timeoutMs });
+            { tabId: args.tabId, timeoutMs, device });
         }
         return { content: [{ type: 'text', text: out.text }] };
       }
@@ -670,7 +750,11 @@ export async function startMcpServer({ client = 'unknown' } = {}) {
         // 无人值守（cron、服务器）没有人可问。开关放在 MCP 这一侧读环境变量，
         // 扩展只管照做——扩展不该知道自己跑在什么场景里。
         name === 'ask' ? { ...args, disabled: process.env.HUASHU_CHROME_ASK === 'off' } : args,
-        { tabId: args.tabId, timeoutMs: budgetOf(name, args, askMs) });
+        { tabId: args.tabId, timeoutMs: budgetOf(name, args, askMs), device });
+      if (device && name === 'tabs') {
+        const tid = data?.tabId ?? (args.action === 'select' ? args.tabId : undefined);
+        if (tid != null) tabDevice.set(tid, device);
+      }
 
       // 浏览器只能下到 Downloads 里；下完再挪到 agent 要的位置，对它保持透明
       if (name === 'download' && args.savePath && data.path) {
@@ -721,7 +805,7 @@ export async function startMcpServer({ client = 'unknown' } = {}) {
     } catch (e) {
       return { content: [{ type: 'text', text: hint(e) + mismatchNote(true) }], isError: true };
     }
-  });
+  }));
 
   // 扩展和本地端版本对不上时在回执里说一次——回执是唯一一定有人读的通道。
   // 分级见 extension/compat.js：补丁号差异静默；本地端旧了提一次怎么升级；
@@ -738,16 +822,51 @@ export async function startMcpServer({ client = 'unknown' } = {}) {
   }
 
   await server.connect(new StdioServerTransport());
+  watchIdle();
   return server;
 }
 
+// 闲置自退。
+//
+// 本该是宿主的事：会话结束就关掉 stdin，我们读到 EOF 自然就退了（实测成立）。
+// 可 Goose 桌面版每开一个会话起一个 mcp、会话结束却从不关管道——11-2 查到
+// 一个 goose serve 下面挂着 34 个，最老的一周前，合计约 2 GB。宿主不收，只能自己收。
+//
+// 判据是「stdin 上多久没来过任何东西」，且手上没有在跑的工具调用。默认 4 小时：
+// 一个真在用的会话很少静默这么久；万一真是，宿主下一次调用会看到连接已断，
+// 代价是重开一次会话，远小于无限期地攒进程。HUASHU_CHROME_MCP_IDLE_MIN=0 关掉。
+let inflight = 0;
+let lastActive = Date.now();
+const busy = (fn) => async (...a) => {
+  inflight++;
+  try { return await fn(...a); } finally { inflight--; lastActive = Date.now(); }
+};
+
+export function idleLimitMs(env = process.env) {
+  const raw = env.HUASHU_CHROME_MCP_IDLE_MIN;
+  const min = raw == null || raw === '' ? 240 : Number(raw);
+  return Number.isFinite(min) && min > 0 ? min * 60000 : 0;
+}
+
+function watchIdle() {
+  const limit = idleLimitMs();
+  if (!limit) return;
+  process.stdin.on('data', () => { lastActive = Date.now(); });
+  const tick = setInterval(() => {
+    if (inflight || Date.now() - lastActive < limit) return;
+    console.error(`[vcorp-chrome] ${Math.round(limit / 60000)} 分钟没有任何请求，宿主大概已经不用这个进程了，自行退出`);
+    process.exit(0);
+  }, Math.min(60000, Math.max(limit / 4, 50)));
+  tick.unref();   // 吊着进程的该是 stdin，不是这个检查
+}
+
 // 自动翻页。页码型：改一个 query 参数递增；游标型：从上一页响应里按路径取下一个游标。
 // 停机判据都是确定性的：非 2xx、空体、和上一页一模一样、游标为空或没变、跑满 max。
 // 落盘是每页一行 JSON（url/status/body），body 能解析成 JSON 就存解析后的。
 const pathGet = (obj, p) => String(p || '').split('.').filter(Boolean).reduce((o, k) => (o == null ? undefined : o[k]), obj);
 const EMPTY_BODY = /^\s*(\[\s*\]|\{\s*\}|null)?\s*$/;
 
-export async function fetchPages(bridge, args) {
+export async function fetchPages(bridge, args, device) {
   const pg = args.pages || {};
   if (!pg.param && !pg.cursorParam) throw Object.assign(new Error('pages 需要 param（页码参数名）或 cursorParam（游标参数名）'), { code: 'INTERNAL' });
   const max = Math.min(Math.max(Number(pg.max) || 10, 1), 50);
@@ -762,7 +881,7 @@ export async function fetchPages(bridge, args) {
     const url = new URL(base);
     if (pg.param) url.searchParams.set(pg.param, String(n));
     if (pg.cursorParam && cursor) url.searchParams.set(pg.cursorParam, cursor);
-    const data = await bridge.call('fetch', { url: url.toString(), init: args.init, maxBody: args.maxBody || 2000000, via: args.via }, { tabId: args.tabId });
+    const data = await bridge.call('fetch', { url: url.toString(), init: args.init, maxBody: args.maxBody || 2000000, via: args.via }, { tabId: args.tabId, device });
     const m = /^(\d+)\n\n([\s\S]*)$/.exec(data?.text || '');
     const status = Number(m?.[1] || 0), body = m?.[2] ?? '';
     if (!(status >= 200 && status < 300)) { stop = `第 ${i + 1} 页返回 ${status}，停下`; break; }
@@ -822,6 +941,12 @@ function hint(e) {
       + '在「高保真模式」那一栏点「开启」——只需一次。',
     L2_BUSY: '真实输入事件用不了（多半是用户自己开着 DevTools，一个标签页只允许一个调试器）。'
       + '已经用普通事件完成了；如果结果不对，让用户关掉 DevTools 再试。',
+    DEVICE_OFFLINE: '指定的设备不在线。devices 看现在有哪些，换一台或请用户把它打开。',
+    AMBIGUOUS_DEVICE: '有不止一台设备能做这件事。从候选里挑一个，用 device 指定。',
+    DESKTOP_DENIED: '这条桌面命令被安全规则拦下（原因见上）。浏览器窗口用浏览器工具；别换个写法绕。',
+    DESKTOP_UNAVAILABLE: '这台电脑上的桌面能力没装好。运行 npx vcorp-chrome doctor 看缺什么。',
+    PAY_REFUSED: '付款类按钮只能由用户亲手点。用 ask 把要付的东西说清楚，请用户自己完成。',
+    NEEDS_SINGLE_CALL: '发送/删除一类的动作不在批处理里做。先确认目标没错，再单独调用一次。',
   };
   return `[${e.code || 'INTERNAL'}] ${e.message}` + (map[e.code] ? `\n→ ${map[e.code]}` : '');
 }