@celljs/ta-computer-use 0.0.0-stage → 4.8.0

package/README.en.md

@@ -0,0 +1,37 @@
+# Cell - Ta Computer Use
+
+A built-in pi package for Ta (enabled by default, can be disabled in Web client Settings → Extensions): lets Ta use desktop applications on this machine via [Cua Driver](https://cua.ai/cua-driver) in the background. It lists apps and windows, reads window accessibility trees, performs clicks, types text, scrolls, and takes screenshots, without taking your mouse and keyboard. It's just one pi extension (`src/extension.ts` → `extension/index.mjs`), does not modify Ta's core, and pi can use it as well.
+
+[Ta Desktop](../../apps/ta-desktop/README.md) comes with Cua Driver (fixed version) and works out of the box. For the terminal Ta, use your own installation:
+
+```bash
+/bin/bash -c "$(curl -fsSL https://cua.ai/driver/install.sh)"   # macOS, Linux
+irm https://cua.ai/driver/install.ps1 | iex                    # Windows (PowerShell)
+```
+
+The `/computer-use` page shows which program is in use and checks what your system still needs (guiding you through setup like the first time); if nothing is installed, it shows the installation command.
+
+## How It Works
+
+- **Finding the program**: first checks the environment variable `TA_CUA_DRIVER` (set by Ta Desktop when starting ta serve, pointing to its bundled copy), then checks `PATH`, `~/.local/bin` (the default install location), and on macOS `/Applications/CuaDriver.app` and `~/Applications/CuaDriver.app`, in order. It only calls `stat`, never runs anything. If not found, it checks again before each message, so installing mid-session doesn't need a restart.
+- **Hint**: when found, adds a `<computer_use>` section to the system prompt: tool names are `tools.mcp__cua_driver__*`, suggests calling `describeNamespace("mcp__cua_driver")` first to see usage, plus platform limitations (macOS: don't prompt user again while waiting for permissions; Windows: can't operate windows running as administrator; Linux: needs desktop session and AT-SPI). Adds nothing if not found.
+- **On-demand startup**: the MCP server `cua-driver` (exposed in codemode) is not registered at session start. The first time a codemode script mentions `mcp__cua_driver` (per pi's `reachesTools`; scripts using tools must write it out), it registers with `pi.registerMcpServer` and waits for tools to appear (up to 5 seconds). Pi connects all registered MCP servers at session start, creating a `cua-driver mcp` process per session (~10–24 MB); on-demand registration means sessions not using desktop apps have no extra process.
+- **System requirements and permissions** (`src/cua-driver-access.ts`, checked once per process on first use, shared by concurrent calls):
+  - **macOS**: Cua Driver needs Accessibility (read and operate apps) and Screen Recording (screenshots), authorized to CuaDriver.app (`com.trycua.driver`, Cua's developer signature), not Ta. Check with `cua-driver call check_permissions` (~20 ms). When permissions are missing, CuaDriver.app shows a two-step guide; Ta posts a notification explaining which two toggles to enable, then checks every second. Once enabled, the call continues without retry. If the guide is dismissed, Ta opens the system settings page. Waits up to 3 minutes; the user can press "Stop" to cancel immediately. Without Accessibility, the call fails, and the model is told to ask the user to enable it; `/computer-use` can guide them again. Without only Screen Recording, the call continues (reading and operating work), with a one-time notification. The daemon returns `permissions_pending` for a few hundred ms after startup, so Ta silently waits up to 3 seconds to avoid false alarms.
+  - **Linux**: no permissions needed, but requires a graphical session (X11 or Wayland with XWayland), AT-SPI accessibility bus, and libX11 / libXi / libxkbcommon. Check with `cua-driver doctor --json` (~0.3 s). Without a graphical session (e.g., SSH) or missing libraries, the call fails and explains why plus install commands; AT-SPI warnings notify the user once and continue.
+  - **Windows**: no permissions needed; use `doctor` to check for desktop session. Windows running as administrator requires Ta to also run as administrator (UIPI), noted in the hint.
+  - When the system can't tell (your daemon hasn't started yet), the call is not blocked; it checks next time.
+- **Bundled Cua Driver on macOS** (`src/cua-driver-daemon.ts`): the MCP process only forwards; the actual daemon must launch as CuaDriver.app via LaunchServices for authorization to belong to it. Ta starts a daemon on its own socket (`~/Library/Caches/ta/cua-driver.sock`), and the MCP server is `cua-driver mcp --embedded --socket <it>`. Here's how:
+  - An app nested inside another app bundle is treated by macOS as part of the outer app (permissions attach to Ta and are lost on each build). So on first use, Ta clones it by version to `~/Library/Application Support/Ta/cua-driver/<version>/` (APFS clone, ~30 ms, no extra disk), launches from there, and deletes older version clones.
+  - LaunchServices picks variants by bundle id and might pick CuaDriver.app from another app (different version, forwarding reports incompatibility). So before launch, Ta registers this copy with `lsregister -f`, then verifies the actual running program's path after launch. If it doesn't match, Ta stops it and suggests `cua-driver doctor --fix`. An existing daemon on the socket (from another Ta process or left over) is checked the same way.
+  - The bundled copy disables Cua's product telemetry and update checks (`CUA_DRIVER_RS_TELEMETRY_ENABLED=0`, `CUA_DRIVER_RS_UPDATE_CHECK=0`); Ta's version updates handle upgrades. Your own installation keeps your settings.
+  - Before each use, the daemon is confirmed alive (one socket connect); if it crashed, it restarts. After 10 minutes idle, it exits (~60 MB), and the forwarder exits too; pi auto-reconnects on the next call. When the process that started it exits, it stops the daemon too.
+
+Measured (M4 Pro, fake model running `ta -p`, bundled Cua Driver 0.47.5, from Ta.app bundle): the first call is ~0.3 s slower (clone + daemon start). Each subsequent first call in a new process is within measurement error compared to not calling (~1.18 s vs ~1.20 s). Daemon startup ~150–250 ms, permission check ~20 ms, idle ~33–60 MB.
+
+## Limitations
+
+- If `mcp.json` already has a server named `cua-driver`, the file takes precedence. Cua Driver configured under another name (e.g., from `cua-driver connect` as `cua-computer-use`) won't be recognized, and tools appear twice (you can disable this extension).
+- When remote execution (`ta serve --exec`) is used, the MCP server runs in the execution environment, but the program is found on the ta serve machine. When paths differ on each side, it won't connect.
+- On macOS, if the user clicks "Quit and Reopen" in the permission guide (Screen Recording requirement), macOS restarts CuaDriver.app without Ta's arguments; Ta then restarts its daemon and stops the extra instance after permissions are granted.
+- Windows and Linux installer packages have not been verified on real machines; Linux's `doctor` output has been tested in containers.

package/README.md

@@ -1,3 +1,37 @@
-# Temporary Holding Version
+# Cell - Ta 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.
+Ta 自带的 pi 包（默认开启，可在 Web 客户端的 设置 → 扩展 关闭）：让 Ta 经 [Cua Driver](https://cua.ai/cua-driver) 在后台使用这台电脑上的桌面应用——列出应用和窗口、读取窗口的辅助功能树、点击、输入、滚动、截图，不抢用户的鼠标和键盘。只有一个 pi 扩展（`src/extension.ts` → `extension/index.mjs`），不改 Ta 的核心，pi 也能装。
+
+[Ta Desktop](../../apps/ta-desktop/README.md) 自带 Cua Driver（固定版本），装好就能用。终端里的 Ta 用用户自己装的那一份：
+
+```bash
+/bin/bash -c "$(curl -fsSL https://cua.ai/driver/install.sh)"   # macOS、Linux
+irm https://cua.ai/driver/install.ps1 | iex                    # Windows（PowerShell）
+```
+
+`/computer-use` 显示用的是哪个程序，并检查系统还缺什么（缺什么就像第一次使用时一样引导用户）；没装时给出安装命令。
+
+## 机制
+
+- **找程序**：先看环境变量 `TA_CUA_DRIVER`（Ta Desktop 给它启动的 ta serve 设置，指向自带的那份），再依次看 `PATH`、`~/.local/bin`（安装脚本的默认位置）、macOS 的 `/Applications/CuaDriver.app` 和 `~/Applications/CuaDriver.app`。只做 `stat`，不运行任何程序。没找到时每条消息前再找一次，会话中途装好也不用重启。
+- **提示**：找到时在系统提示里加一段 `<computer_use>`：工具名是 `tools.mcp__cua_driver__*`，先用 `describeNamespace("mcp__cua_driver")` 看用法，另加一句当前系统的限制（macOS：在等授权时不要再向用户要；Windows：以管理员身份运行的窗口操作不了；Linux：需要桌面会话和 AT-SPI）。没找到时什么都不加。
+- **按需启动**：MCP 服务器 `cua-driver`（codemode 暴露）不在会话开始时注册，第一次有 codemode 脚本点名 `mcp__cua_driver` 时（按 pi 的 `reachesTools`；搜索工具的脚本要在文字里写出它）才用 `pi.registerMcpServer` 注册，等工具出现（最多 5 秒）后这次调用就能用。pi 会在每个会话开始时连接所有已注册的服务器，提前注册就意味着每个会话多一个 `cua-driver mcp` 进程（约 10–24 MB）；按需注册后，不用桌面应用的会话没有任何额外进程。
+- **系统要求与授权**（`src/cua-driver-access.ts`，每个进程第一次使用时检查一次，同时到来的调用共用这一次检查）：
+  - **macOS**：Cua Driver 需要辅助功能（读取和操作应用）和屏幕录制（截图）两项授权，授权属于 CuaDriver.app（`com.trycua.driver`，Cua 的开发者签名），不属于 Ta。用 `cua-driver call check_permissions` 查询（约 20 ms）。缺授权时，CuaDriver.app 会自己弹出两步引导窗口；Ta 发一条通知说明要开哪两个开关，然后每秒查一次，开好后这次调用继续执行，不用重试。引导窗口被关掉时，Ta 直接打开系统设置的对应页面。最多等 3 分钟，用户按“停止”立即结束；没有辅助功能时，这次调用失败，失败原因会告诉模型去请用户开启，`/computer-use` 可以再走一遍引导。只缺屏幕录制时照常继续（不截图也能读取和操作），并提示一次。守护进程刚启动的几百毫秒里会先返回 `permissions_pending`，所以先静默等最多 3 秒，避免误报。
+  - **Linux**：不需要授权，但需要图形会话（X11，或带 XWayland 的 Wayland）、AT-SPI 辅助功能总线，以及 libX11 / libXi / libxkbcommon。用 `cua-driver doctor --json` 检查（约 0.3 s）：没有图形会话（例如通过 SSH）或缺库时，这次调用失败并说明原因和安装命令；AT-SPI 等警告通知用户一次，照常继续。
+  - **Windows**：不需要授权；同样用 `doctor` 检查桌面会话。以管理员身份运行的窗口需要 Ta 也以管理员身份运行（UIPI），这一点写在提示里。
+  - 系统说不清的时候（用户自己装的那份守护进程还没启动）不阻止调用，下一次再查。
+- **Ta Desktop 自带的那份，在 macOS 上**（`src/cua-driver-daemon.ts`）：MCP 进程只负责转发，真正干活的守护进程必须经 LaunchServices 作为 CuaDriver.app 启动，授权才算在它自己名下。Ta 在自己的 socket（`~/Library/Caches/ta/cua-driver.sock`）上启动一个守护进程，MCP 服务器是 `cua-driver mcp --embedded --socket <它>`。具体做法：
+  - 嵌在另一个 app 包里的 app，macOS 会算成外层 app 的一部分（授权会挂到 Ta 名下，每次构建都会丢）。所以第一次使用时，把它按版本克隆到 `~/Library/Application Support/Ta/cua-driver/<版本>/`（APFS 克隆，约 30 ms，不额外占磁盘），从那里启动，同时删掉旧版本的克隆。
+  - LaunchServices 按 bundle id 挑副本，可能挑中本机其他应用带的 CuaDriver.app（版本不同，转发会报不兼容）。所以启动前先用 `lsregister -f` 注册这份，启动后核对实际运行的程序路径；对不上就停掉，并提示 `cua-driver doctor --fix`。socket 上已有的守护进程（其他 Ta 进程或上次留下的）同样先核对一次。
+  - 自带的那份关闭 Cua 的产品遥测和更新检查（`CUA_DRIVER_RS_TELEMETRY_ENABLED=0`、`CUA_DRIVER_RS_UPDATE_CHECK=0`），由 Ta 的版本更新负责升级；用户自己装的那份保持用户自己的设置。
+  - 守护进程每次被用到前都会确认它还活着（一次 socket 连接），挂了就重启；10 分钟没用就退出（约 60 MB），转发进程随之退出，pi 在下一次调用时自动重连；启动它的进程退出时也会把它停掉。
+
+实测（M4 Pro，假模型跑 `ta -p`，自带 Cua Driver 0.47.5，用 Ta.app 打包产物里的那份）：第一次调用比不调用多约 0.3 s（克隆加守护进程启动）；之后每次新进程的首次调用，和不调用时的差别在测量误差内（约 1.18 s 对 1.20 s）。守护进程启动约 150–250 ms，授权查询约 20 ms，空闲时占约 33–60 MB。
+
+## 限制
+
+- `mcp.json` 里已有同名（`cua-driver`）服务器时以文件为准；以其他名字配置的 Cua Driver（例如 `cua-driver connect` 写的 `cua-computer-use`）不会被识别，工具会出现两份，可以关掉本扩展。
+- 远程执行（`ta serve --exec`）时 MCP 服务器在执行环境里启动，而程序是在 ta serve 所在的机器上找的，两边路径不同时连不上。
+- macOS 上，用户在引导窗口里点“退出并重新打开”（屏幕录制要求）后，macOS 会不带 Ta 的参数重新启动 CuaDriver.app；Ta 会重启自己的守护进程，并在授权完成后停掉这个多出来的实例。
+- Windows 和 Linux 的安装包没有在真机上验证过；Linux 的 `doctor` 输出在容器里验证过。

package/extension/index.mjs

@@ -0,0 +1,551 @@
+// src/extension.ts
+import { execFile as execFile3 } from "node:child_process";
+import { realpathSync } from "node:fs";
+import { join as join3 } from "node:path";
+
+// src/cua-driver.ts
+import { statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+var CuaDriver;
+((CuaDriver) => {
+  CuaDriver.SERVER = "cua-driver";
+  CuaDriver.NAMESPACE = "mcp__cua_driver";
+  CuaDriver.SECTION = "computer_use";
+  CuaDriver.BUNDLED_ENV = "TA_CUA_DRIVER";
+  function prompt(platform) {
+    return [
+      "Cua Driver lets you use the desktop apps of this computer in the background, without taking the user's pointer or keyboard: list apps and windows, read a window's accessibility tree, click, type, scroll and take screenshots.",
+      `Its tools are \`tools.${CuaDriver.NAMESPACE}__*\` in codemode scripts. It starts the first time a script names \`${CuaDriver.NAMESPACE}\`: begin with \`describeNamespace("${CuaDriver.NAMESPACE}")\` for its tools and how to use them.`,
+      "Use it only when a task needs a desktop app, not for files or commands.",
+      ...PLATFORM_NOTES[platform] ? [PLATFORM_NOTES[platform]] : []
+    ].join(`
+`);
+  }
+  CuaDriver.prompt = prompt;
+  const PLATFORM_NOTES = {
+    darwin: "If a call waits for the permissions of macOS, Ta has asked the user for them; do not ask again.",
+    win32: "Windows does not let it control the windows of apps run as administrator unless Ta runs as administrator too.",
+    linux: "It needs the desktop session of the user (X11, or Wayland with XWayland) and its accessibility bus (AT-SPI)."
+  };
+  CuaDriver.BUNDLED_ENV_VARS = { CUA_DRIVER_RS_TELEMETRY_ENABLED: "0", CUA_DRIVER_RS_UPDATE_CHECK: "0" };
+  CuaDriver.DESCRIPTION = "Use the desktop apps of this computer in the background (Cua Driver)";
+  CuaDriver.INSTALL = {
+    posix: '/bin/bash -c "$(curl -fsSL https://cua.ai/driver/install.sh)"',
+    win32: "irm https://cua.ai/driver/install.ps1 | iex"
+  };
+  function locate(host = currentHost()) {
+    if (host.bundled && host.isFile(host.bundled)) {
+      return { path: host.bundled, bundled: true };
+    }
+    const windows = host.platform === "win32";
+    const name = windows ? "cua-driver.exe" : "cua-driver";
+    const dirs = (host.path ?? "").split(windows ? ";" : ":").filter(Boolean);
+    const candidates = [...dirs.map((dir) => join(dir, name)), join(host.home, ".local", "bin", name)];
+    if (host.platform === "darwin") {
+      const app = "CuaDriver.app/Contents/MacOS/cua-driver";
+      candidates.push(join("/Applications", app), join(host.home, "Applications", app));
+    }
+    const own = candidates.find((candidate) => host.isFile(candidate));
+    return own ? { path: own, bundled: false } : undefined;
+  }
+  CuaDriver.locate = locate;
+  function appOf(program) {
+    const inside = "/Contents/MacOS/cua-driver";
+    const app = program.slice(0, -inside.length);
+    return program.endsWith(inside) && app.endsWith(".app") ? app : undefined;
+  }
+  CuaDriver.appOf = appOf;
+  function reaches(reach, input) {
+    if (reach === undefined) {
+      return false;
+    }
+    if (reach === "all") {
+      return JSON.stringify(input ?? null).includes(CuaDriver.NAMESPACE);
+    }
+    return reach.some((word) => word.includes(CuaDriver.NAMESPACE));
+  }
+  CuaDriver.reaches = reaches;
+  function status(program, platform) {
+    if (program) {
+      const which = program.bundled ? `the one that comes with Ta Desktop (${program.path})` : program.path;
+      return `Cua Driver: ${which}. Ta starts it the first time it uses a desktop app, and checks what the system needs then.`;
+    }
+    const install = platform === "win32" ? CuaDriver.INSTALL.win32 : CuaDriver.INSTALL.posix;
+    return `Ta uses desktop apps through Cua Driver, which is not installed. Install it with \`${install}\`, or use Ta Desktop, which comes with it; Ta finds it on the next message, with no restart.`;
+  }
+  CuaDriver.status = status;
+  function currentHost() {
+    return { platform: process.platform, path: process.env.PATH, home: homedir(), bundled: process.env[CuaDriver.BUNDLED_ENV], isFile };
+  }
+  function isFile(path) {
+    try {
+      return statSync(path).isFile();
+    } catch {
+      return false;
+    }
+  }
+})(CuaDriver ||= {});
+
+// src/cua-driver-access.ts
+import { execFile } from "node:child_process";
+var CHECK_TIMEOUT_MS = 5000;
+var DOCTOR_TIMEOUT_MS = 15000;
+var POLL_MS = 1000;
+var GRACE_MS = 3000;
+var GRACE_POLL_MS = 100;
+var WAIT_MS = 3 * 60 * 1000;
+var DESKTOP_PROBES = /display|x11|wayland|at-spi|accessib|session|desktop|automation|uia/i;
+var MISSING_LIBRARY = /error while loading shared libraries: (\S+?):/;
+function askMac(env = process.env) {
+  return /^zh/i.test(env.TA_LANGUAGE || env.LC_ALL || env.LANG || "") ? "Ta 正在请 macOS 允许 Cua Driver 使用这台 Mac：请在 Cua Driver 打开的窗口或“系统设置”里，打开“辅助功能”（用于点击和输入）和“屏幕录制”（用于查看窗口）中的 Cua Driver。开好后 Ta 会自动继续；点“停止”可放弃。" : "Ta is asking macOS to let Cua Driver use this Mac: turn Cua Driver on under Accessibility (to click and type) and Screen Recording (to see windows), in the window Cua Driver opened or in System Settings. Ta goes on by itself once you have; Stop gives up.";
+}
+var NO_ACCESSIBILITY = "Cua Driver has no Accessibility permission of macOS, which it needs to read and use apps: ask the user to turn Cua Driver on in System Settings → Privacy & Security → Accessibility (`/computer-use` in Ta opens it), then try again.";
+var NO_SCREEN_RECORDING = "Cua Driver has no Screen Recording permission of macOS: it reads and uses apps, but takes no screenshots. Turn it on in System Settings → Privacy & Security → Screen & System Audio Recording.";
+
+class CuaDriverAccess {
+  program;
+  options;
+  run;
+  constructor(program, options) {
+    this.program = program;
+    this.options = options;
+    this.run = options.run ?? runProgram;
+  }
+  check(notify, signal) {
+    return this.options.platform === "darwin" ? this.checkMac(notify, signal) : this.checkDesktop();
+  }
+  async permissions() {
+    const socket = this.options.socket ? ["--socket", this.options.socket] : [];
+    const result = await this.run(this.program, ["call", "check_permissions", '{"prompt":false}', ...socket], CHECK_TIMEOUT_MS, this.options.env);
+    return CuaDriverAccess.parsePermissions(result);
+  }
+  async checkMac(notify, signal) {
+    let state = await this.permissions();
+    const grace = Date.now() + (this.options.graceMs ?? GRACE_MS);
+    while (state?.pending && Date.now() < grace && !signal?.aborted) {
+      await sleep(GRACE_POLL_MS, signal);
+      state = await this.permissions();
+    }
+    if (!state || state.accessibility && state.screenRecording) {
+      return { ready: true, notes: [], known: state !== undefined };
+    }
+    notify(askMac());
+    if (!state.pending) {
+      this.options.openSettings?.(state.accessibility ? "Privacy_ScreenCapture" : "Privacy_Accessibility");
+    }
+    const deadline = Date.now() + (this.options.waitMs ?? WAIT_MS);
+    while (!signal?.aborted && Date.now() < deadline && !(state?.accessibility && (state.screenRecording || !state.pending))) {
+      await sleep(this.options.pollMs ?? POLL_MS, signal);
+      await this.options.beforeLook?.();
+      state = await this.permissions() ?? state;
+    }
+    if (state?.accessibility) {
+      return { ready: true, notes: state.screenRecording ? [] : [NO_SCREEN_RECORDING], known: true };
+    }
+    return { ready: false, reason: signal?.aborted ? "Stopped while waiting for the permissions of macOS." : NO_ACCESSIBILITY };
+  }
+  async checkDesktop() {
+    const result = await this.run(this.program, ["doctor", "--json"], DOCTOR_TIMEOUT_MS, this.options.env);
+    return CuaDriverAccess.parseDoctor(result, this.options.platform);
+  }
+}
+((CuaDriverAccess) => {
+  function parsePermissions(result) {
+    if (`${result.stdout}${result.stderr}`.includes("permissions_pending")) {
+      return { accessibility: false, screenRecording: false, pending: true };
+    }
+    try {
+      const answer = JSON.parse(result.stdout);
+      if (typeof answer.accessibility !== "boolean") {
+        return;
+      }
+      return { accessibility: answer.accessibility, screenRecording: answer.screen_recording === true, pending: false };
+    } catch {
+      return;
+    }
+  }
+  CuaDriverAccess.parsePermissions = parsePermissions;
+  function parseDoctor(result, platform) {
+    const library = MISSING_LIBRARY.exec(result.stderr)?.[1];
+    if (library) {
+      const install = platform === "linux" ? " On Debian or Ubuntu: `sudo apt install libx11-6 libxi6 libxkbcommon0 at-spi2-core`." : "";
+      return { ready: false, reason: `Cua Driver cannot start: the system has no ${library}.${install}` };
+    }
+    let probes;
+    try {
+      probes = JSON.parse(result.stdout).probes ?? [];
+    } catch {
+      return { ready: true, notes: [], known: true };
+    }
+    const text = (probe) => [`${probe.label}: ${probe.message}`, probe.detail].filter(Boolean).join(" — ");
+    const failed = probes.filter((probe) => probe.status === "error" || probe.status === "warn" && /display server/i.test(probe.label ?? ""));
+    if (failed.length > 0) {
+      return { ready: false, reason: `Cua Driver cannot use the desktop: ${failed.map(text).join("; ")}` };
+    }
+    const warned = probes.filter((probe) => probe.status === "warn" && DESKTOP_PROBES.test(probe.label ?? ""));
+    return { ready: true, notes: warned.map((probe) => `Cua Driver: ${text(probe)}`), known: true };
+  }
+  CuaDriverAccess.parseDoctor = parseDoctor;
+})(CuaDriverAccess ||= {});
+function runProgram(program, args, timeoutMs, env) {
+  return new Promise((resolve) => {
+    execFile(program, args, { timeout: timeoutMs, maxBuffer: 4 * 1024 * 1024, env: { ...process.env, ...env } }, (error, stdout, stderr) => {
+      const code = error ? typeof error.code === "number" ? error.code : -1 : 0;
+      resolve({ code, stdout: String(stdout), stderr: String(stderr) });
+    });
+  });
+}
+function sleep(ms, signal) {
+  return new Promise((resolve) => {
+    const timer = setTimeout(done, ms);
+    signal?.addEventListener("abort", done, { once: true });
+    function done() {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", done);
+      resolve();
+    }
+  });
+}
+
+// src/cua-driver-daemon.ts
+import { execFile as execFile2 } from "node:child_process";
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync } from "node:fs";
+import { connect } from "node:net";
+import { homedir as homedir2 } from "node:os";
+import { dirname, join as join2 } from "node:path";
+var START_TIMEOUT_MS = 1e4;
+var POLL_MS2 = 20;
+var IDLE_MS = 10 * 60 * 1000;
+
+class CuaDriverDaemon {
+  source;
+  options;
+  socket;
+  pidFile;
+  dir;
+  app;
+  starting;
+  launched = false;
+  verified = false;
+  idle;
+  launch;
+  constructor(source, options = {}) {
+    this.source = source;
+    this.options = options;
+    this.dir = options.dir ?? join2(homedir2(), "Library", "Caches", "ta");
+    this.app = CuaDriverDaemon.nested(source) ? join2(this.stageDir, CuaDriverDaemon.version(source), "CuaDriver.app") : source;
+    this.socket = join2(this.dir, "cua-driver.sock");
+    this.pidFile = join2(this.dir, "cua-driver.pid");
+    this.launch = options.launch ?? openApp;
+  }
+  async ensure() {
+    if (await this.alive() && (this.verified || await this.adopt())) {
+      this.touch();
+      return;
+    }
+    clearTimeout(this.idle);
+    this.starting ??= this.start().finally(() => {
+      this.starting = undefined;
+    });
+    await this.starting;
+    this.touch();
+  }
+  alive() {
+    if (!existsSync(this.socket)) {
+      return Promise.resolve(false);
+    }
+    return new Promise((resolve) => {
+      const socket = connect(this.socket);
+      socket.once("connect", () => {
+        socket.destroy();
+        resolve(true);
+      });
+      socket.on("error", () => resolve(false));
+    });
+  }
+  stop() {
+    clearTimeout(this.idle);
+    if (!this.launched) {
+      return;
+    }
+    this.launched = false;
+    const pid = this.pid();
+    if (pid) {
+      try {
+        process.kill(pid, "SIGTERM");
+      } catch {}
+    }
+  }
+  async reap() {
+    const program = this.program;
+    const own = this.pid();
+    const list = await new Promise((resolve) => execFile2("ps", ["-axo", "pid=,command="], (_error, stdout) => resolve(String(stdout ?? ""))));
+    for (const line of list.split(`
+`)) {
+      const [, pid, command] = /^\s*(\d+)\s+(.*)$/.exec(line) ?? [];
+      if (pid && Number(pid) !== own && command.startsWith(`${program} serve`) && !command.includes(this.socket)) {
+        try {
+          process.kill(Number(pid), "SIGTERM");
+        } catch {}
+      }
+    }
+  }
+  async adopt() {
+    const running = await this.identify();
+    if (!running || running.executable === this.program) {
+      this.verified = true;
+      return true;
+    }
+    try {
+      process.kill(running.pid, "SIGTERM");
+    } catch {}
+    return false;
+  }
+  identify() {
+    return new Promise((resolve) => execFile2(this.program, ["call", "check_permissions", '{"prompt":false}', "--socket", this.socket], { timeout: 5000, env: { ...process.env, ...this.options.env } }, (_error, stdout) => {
+      try {
+        const { source } = JSON.parse(String(stdout));
+        resolve(source?.executable && source.pid ? { executable: source.executable, pid: source.pid } : undefined);
+      } catch {
+        resolve(undefined);
+      }
+    }));
+  }
+  get program() {
+    return join2(this.app, "Contents", "MacOS", "cua-driver");
+  }
+  async verify() {
+    const pid = this.pid();
+    const command = pid ? await this.commandOf(pid) : undefined;
+    const program = this.program;
+    if (command === undefined || command.includes(`${program} serve`)) {
+      this.verified = true;
+      return;
+    }
+    this.stop();
+    throw new Error(`macOS started another copy of CuaDriver.app (${command.split(" serve")[0]}). Run \`${program} doctor --fix\`, which makes macOS forget the other copies, then try again.`);
+  }
+  commandOf(pid) {
+    return new Promise((resolve) => execFile2("ps", ["-o", "command=", "-p", String(pid)], (error, stdout) => resolve(error ? undefined : String(stdout).trim())));
+  }
+  touch() {
+    clearTimeout(this.idle);
+    this.idle = setTimeout(() => this.stop(), this.options.idleMs ?? IDLE_MS);
+    this.idle.unref?.();
+  }
+  pid() {
+    try {
+      return Number(readFileSync(this.pidFile, "utf8").trim()) || undefined;
+    } catch {
+      return;
+    }
+  }
+  get stageDir() {
+    return this.options.stageDir ?? join2(homedir2(), "Library", "Application Support", "Ta", "cua-driver");
+  }
+  async stage() {
+    if (this.app === this.source || existsSync(this.app)) {
+      return;
+    }
+    const versions = dirname(dirname(this.app));
+    const temp = `${dirname(this.app)}.part`;
+    rmSync(temp, { recursive: true, force: true });
+    mkdirSync(temp, { recursive: true });
+    await run("cp", ["-cR", this.source, temp]).catch(() => run("cp", ["-R", this.source, temp]));
+    rmSync(dirname(this.app), { recursive: true, force: true });
+    renameSync(temp, dirname(this.app));
+    for (const name of readdirSync(versions)) {
+      if (join2(versions, name) !== dirname(this.app)) {
+        rmSync(join2(versions, name), { recursive: true, force: true });
+      }
+    }
+  }
+  async start() {
+    await this.stage();
+    mkdirSync(this.dir, { recursive: true });
+    rmSync(this.socket, { force: true });
+    this.verified = false;
+    await this.launch(this.app, ["serve", "--socket", this.socket, "--pid-file", this.pidFile], this.options.env ?? {});
+    if (!this.launched) {
+      this.launched = true;
+      process.once("exit", () => this.stop());
+    }
+    const deadline = Date.now() + START_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+      if (await this.alive()) {
+        return this.verify();
+      }
+      await new Promise((resolve) => setTimeout(resolve, POLL_MS2));
+    }
+    throw new Error(`Cua Driver did not start in ${START_TIMEOUT_MS / 1000} s: run \`${join2(this.app, "Contents/MacOS/cua-driver")} doctor\`.`);
+  }
+}
+((CuaDriverDaemon) => {
+  function nested(app) {
+    return /\.app\//.test(dirname(app));
+  }
+  CuaDriverDaemon.nested = nested;
+  function version(app) {
+    try {
+      return /<key>CFBundleVersion<\/key>\s*<string>([^<]+)<\/string>/.exec(readFileSync(join2(app, "Contents", "Info.plist"), "utf8"))?.[1] ?? "current";
+    } catch {
+      return "current";
+    }
+  }
+  CuaDriverDaemon.version = version;
+})(CuaDriverDaemon ||= {});
+var LSREGISTER = "/System/Library/Frameworks/CoreServices.framework/Versions/A/Frameworks/LaunchServices.framework/Versions/A/Support/lsregister";
+async function openApp(app, args, env) {
+  await run(LSREGISTER, ["-f", app]).catch(() => {
+    return;
+  });
+  const vars = Object.entries(env).flatMap(([name, value]) => ["--env", `${name}=${value}`]);
+  await run("open", ["-g", "-n", "-a", app, ...vars, "--args", ...args]);
+}
+function run(program, args) {
+  return new Promise((resolve, reject) => execFile2(program, args, (error, stdout) => error ? reject(error) : resolve(String(stdout))));
+}
+
+// src/extension.ts
+var CONNECT_WAIT_MS = 5000;
+var POLL_MS3 = 15;
+var setups = new Map;
+function setupOf(found, platform) {
+  const program = { ...found, path: realPath(found.path) };
+  let setup = setups.get(program.path);
+  if (!setup) {
+    const env = program.bundled ? { ...CuaDriver.BUNDLED_ENV_VARS } : undefined;
+    const app = program.bundled && platform === "darwin" ? CuaDriver.appOf(program.path) : undefined;
+    const daemon = app ? new CuaDriverDaemon(app, { env }) : undefined;
+    const access = new CuaDriverAccess(daemon ? join3(daemon.app, "Contents", "MacOS", "cua-driver") : program.path, {
+      platform,
+      socket: daemon?.socket,
+      env,
+      beforeLook: daemon ? () => daemon.ensure() : undefined,
+      openSettings: (pane) => execFile3("open", [`x-apple.systempreferences:com.apple.preference.security?${pane}`], () => {
+        return;
+      })
+    });
+    const args = daemon ? ["mcp", "--embedded", "--socket", daemon.socket] : ["mcp"];
+    setup = { program, daemon, access, args, env, ready: false };
+    setups.set(program.path, setup);
+  }
+  return setup;
+}
+function realPath(path) {
+  try {
+    return realpathSync(path);
+  } catch {
+    return path;
+  }
+}
+var DEFAULTS = { locate: () => CuaDriver.locate(), platform: process.platform, setup: setupOf };
+function activate(pi, options = DEFAULTS) {
+  let setup;
+  let connected = false;
+  let connecting;
+  const prefix = `${CuaDriver.NAMESPACE}__`;
+  const ready = () => pi.getAllTools().some((tool) => tool.name.startsWith(prefix));
+  const found = () => {
+    if (!setup) {
+      const program = options.locate();
+      setup = program ? options.setup(program, options.platform) : undefined;
+    }
+    return setup;
+  };
+  const connect2 = async (driver, signal) => {
+    if (!pi.getMcpServers().some((server) => server.name === CuaDriver.SERVER)) {
+      pi.registerMcpServer(CuaDriver.SERVER, { command: driver.program.path, args: driver.args, env: driver.env, description: CuaDriver.DESCRIPTION });
+    }
+    const deadline = Date.now() + CONNECT_WAIT_MS;
+    while (!ready() && Date.now() < deadline && !signal?.aborted) {
+      await new Promise((resolve) => setTimeout(resolve, POLL_MS3));
+    }
+    connected = !signal?.aborted;
+  };
+  const check = async (driver, notify, signal) => {
+    driver.checking ??= driver.access.check(notify, signal).finally(() => {
+      driver.checking = undefined;
+    });
+    const result = await driver.checking;
+    if (!result.ready) {
+      return result.reason;
+    }
+    if (result.known && !driver.ready) {
+      driver.ready = true;
+      for (const note of result.notes) {
+        notify(note);
+      }
+      driver.daemon?.reap();
+    }
+    return;
+  };
+  pi.on("before_agent_start", (event) => {
+    const { sections } = event.systemPromptOptions;
+    if (found()) {
+      sections[CuaDriver.SECTION] = CuaDriver.prompt(options.platform);
+    } else {
+      delete sections[CuaDriver.SECTION];
+    }
+  });
+  pi.on("tool_call", async (event, ctx) => {
+    const driver = setup;
+    if (!driver) {
+      return;
+    }
+    if (driver.ready && connected && !driver.daemon) {
+      return;
+    }
+    const tool = pi.getAllTools().find((candidate) => candidate.name === event.toolName);
+    if (!CuaDriver.reaches(tool?.reachesTools?.(event.input), event.input)) {
+      return;
+    }
+    const notify = (message) => ctx.ui.notify(message, "warning");
+    try {
+      await driver.daemon?.ensure();
+      const reason = driver.daemon && !driver.ready ? await check(driver, notify, ctx.signal) : undefined;
+      if (reason) {
+        return { block: true, reason };
+      }
+      if (!connected) {
+        connecting ??= connect2(driver, ctx.signal).finally(() => {
+          connecting = undefined;
+        });
+        await connecting;
+      }
+      const after = !driver.daemon && !driver.ready ? await check(driver, notify, ctx.signal) : undefined;
+      return after ? { block: true, reason: after } : undefined;
+    } catch (error) {
+      return { block: true, reason: error.message };
+    }
+  });
+  pi.registerCommand("computer-use", {
+    description: "Whether Ta can use the desktop apps of this computer (Cua Driver), and what the system still needs",
+    handler: async (_args, ctx) => {
+      const program = options.locate();
+      ctx.ui.notify(CuaDriver.status(program, options.platform), program ? "info" : "warning");
+      if (!program) {
+        return;
+      }
+      const driver = options.setup(program, options.platform);
+      await driver.daemon?.ensure();
+      const result = await driver.access.check((message) => ctx.ui.notify(message, "warning"), ctx.signal);
+      if (!result.ready) {
+        ctx.ui.notify(result.reason, "warning");
+      } else if (result.known) {
+        driver.ready = true;
+        ctx.ui.notify(["Cua Driver has what it needs.", ...result.notes].join(`
+`), result.notes.length > 0 ? "warning" : "info");
+      }
+    }
+  });
+}
+function computerUse(pi) {
+  activate(pi);
+}
+export {
+  setupOf,
+  computerUse as default,
+  activate
+};