@dipoleml/dcode-cli 1.2.2 → 1.2.4

package/dist/packages/dcode-cua-plugin/scripts/resolve-pnpm-invocation.mjs

@@ -0,0 +1,26 @@
+/**
+ * 解析"怎么调用 pnpm"这一个决策，独立成模块只为可测：bump 脚本本体是 top-level await，
+ * import 它就会真的执行一次 bump，没法在单测里覆盖这段逻辑。
+ */
+
+/**
+ * @param {{ npmExecpath?: string | undefined, platform: string }} input
+ * @returns {{ command: string, args: string[], options: { shell?: true } }}
+ */
+export function resolvePnpmInvocation(input) {
+  const { npmExecpath, platform } = input;
+  const args = ["install", "--prefer-offline"];
+  // 首选让当前 Node 直接跑 pnpm 的 JS 入口：不经 shell、不碰 `.cmd`，三平台同一条码路。
+  // pnpm 运行 package script 时会注入 npm_execpath。
+  const entry = typeof npmExecpath === "string" ? npmExecpath.trim() : "";
+  if (entry) {
+    return { command: process.execPath, args: [entry, ...args], options: {} };
+  }
+  // 回落。Windows 上 pnpm 是 `pnpm.cmd`：execFile 不走 shell 时不补 PATHEXT（ENOENT），
+  // 而 Node 自 18.20/20.12 起（CVE-2024-27980）又禁止不带 shell spawn `.cmd`（EINVAL）。
+  // 两条都堵死，所以这里只能借 shell；参数是硬编码字面量，没有拼接也没有外部输入。
+  if (platform === "win32") {
+    return { command: "pnpm", args, options: { shell: true } };
+  }
+  return { command: "pnpm", args, options: {} };
+}

package/dist/packages/dcode-cua-plugin/scripts/sync-cache.mjs

@@ -0,0 +1,116 @@
+// Sync the built dev plugin into the CLI's plugin cache so the running dcode CLI
+// (which loads plugins from ~/.dcode/cli/plugins/cache/..., NOT from this repo)
+// picks up skill / MCP / manifest changes without a manual copy.
+//
+// This closes the last hop of the sync chain:
+//   dcode-cua repo  --sync:skill/sync:mcp-->  dev plugin (here)  --sync:cache-->  CLI cache
+//
+// The cache dir name (e.g. 0.1.31) is just an install-time cache key; copying newer
+// content (plugin.json says 0.2.0) on top of it is tolerated by the CLI and is exactly
+// what makes a dev skill/MCP edit go live. Run after `pnpm sync:skill` (+ `pnpm build`
+// when the MCP wrapper or skill changed).
+//
+// Usage:
+//   node scripts/sync-cache.mjs            # auto-resolve cache path from marketplace.json
+//   node scripts/sync-cache.mjs <cacheDir> # explicit cache dir
+import { cp, mkdir, readFile, readdir, stat } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { homedir } from "node:os";
+import { stageSharpIntoBundledAgents } from "../../../../../packages/desktop/scripts/sharp-package-assets.mjs";
+import { stageKoffiIntoBundledAgents } from "../../../../../packages/desktop/scripts/koffi-package-assets.mjs";
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+const devPlugin = packageRoot;
+// Build artifacts that constitute an installed plugin in the cache.
+const ENTRIES = [
+  "skills",
+  "docs",
+  "scripts/computer-use-client.mjs",
+  ".dcode-plugin",
+  "package.json",
+  // CUA screenshot/zoom 的 sharp native closure 属于 CUA plugin 自身；同步开发缓存时
+  // 不能只复制 skill/docs，否则下一次 cache seed 会再次丢失原生依赖。
+  "node_modules",
+];
+
+/**
+ * Resolve the CLI cache dir for dcode-cua. Prefer the cachePath declared in the
+ * dcode-plugins-official marketplace.json; fall back to the single version dir under
+ * the cache root. Throws if neither yields an existing dir (plugin not installed).
+ */
+async function resolveCacheDir() {
+  if (process.argv[2]) return resolve(process.argv[2]);
+  const marketplace = join(
+    homedir(),
+    ".dcode/cli/plugins/marketplaces/dcode-plugins-official/marketplace.json",
+  );
+  try {
+    const text = await readFile(marketplace, "utf8");
+    const parsed = JSON.parse(text);
+    const entry = (parsed.plugins ?? parsed.items ?? []).find(
+      (p) => p?.name === "computer-use" && p?.cachePath,
+    );
+    if (entry?.cachePath && existsSync(entry.cachePath)) return entry.cachePath;
+  } catch {
+    // marketplace.json missing/unreadable — fall through to glob.
+  }
+  const cacheRoot = join(homedir(), ".dcode/cli/plugins/cache/dcode-plugins-official/computer-use");
+  if (existsSync(cacheRoot)) {
+    const dirs = await readdir(cacheRoot);
+    if (dirs.length === 1) return join(cacheRoot, dirs[0]);
+    if (dirs.length > 1) {
+      // Pick the newest by mtime — the most recently installed version.
+      let newest = null;
+      for (const d of dirs) {
+        const s = await stat(join(cacheRoot, d));
+        if (!newest || s.mtimeMs > newest.mtimeMs) newest = { d, mtimeMs: s.mtimeMs };
+      }
+      if (newest) return join(cacheRoot, newest.d);
+    }
+  }
+  throw new Error(
+    `Could not resolve the dcode-cua CLI cache dir. The plugin does not appear to be ` +
+      `installed — run it once from the dcode UI/TUI to install, then re-run sync:cache. ` +
+      `(looked in marketplace.json and ${cacheRoot})`,
+  );
+}
+
+const cacheDir = await resolveCacheDir();
+await mkdir(cacheDir, { recursive: true });
+
+const copied = [];
+for (const entry of ENTRIES) {
+  const src = join(devPlugin, entry);
+  if (!existsSync(src)) continue; // e.g. dist/ before first build
+  const dest = join(cacheDir, entry);
+  // cp with recursive + force replacement; file/dir both handled.
+  await cp(pathToFileURL(src), pathToFileURL(dest), { recursive: true, force: true });
+  copied.push(entry);
+}
+
+// Bug 根因：开发态 CLI 实际从 ~/.dcode/cli/plugins/cache 启动 MCP，
+// 只同步 dist 会让 externalized sharp 仍从一个隔离目录解析，导致 screenshot/zoom
+// 在源码和 Helper 都正确时依旧报 MODULE_NOT_FOUND。与产品打包共用同一个 staging
+// 函数，把当前平台的 JS/native 运行时放在插件自身 node_modules，避免两条链路漂移。
+stageSharpIntoBundledAgents({
+  desktopPackageRoot: resolve(packageRoot, "../../../../packages/desktop"),
+  glmDir: cacheDir,
+  targetPlatform: { os: process.platform, arch: process.arch },
+});
+copied.push("node_modules/sharp runtime");
+stageKoffiIntoBundledAgents({
+  koffiPackageRoot: resolve(packageRoot, "../adapters"),
+  glmDir: cacheDir,
+  targetPlatform: { os: process.platform, arch: process.arch },
+});
+copied.push("node_modules/koffi runtime");
+
+console.log(`sync:cache → ${cacheDir}`);
+console.log(`  copied: ${copied.join(", ") || "(nothing)"}`);
+console.log(
+  `  note: the cache dir name is an install-time key and may lag the plugin.json ` +
+    `version inside — that is expected and does not affect loading.`,
+);

package/dist/packages/dcode-cua-plugin/scripts/sync-skill-from-dcode-cua.mjs

@@ -0,0 +1,115 @@
+import { createHash } from "node:crypto";
+import { execFile as execFileCallback } from "node:child_process";
+import { copyFile, mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const workspacePath = resolve(packageRoot, "../../../../pnpm-workspace.yaml");
+const execFile = promisify(execFileCallback);
+const defaultRepositoryRoot = resolve(packageRoot, "../../../../../dcode-cua");
+const repositoryRoot = resolve(
+  process.argv[2] ?? process.env.DCODE_CUA_REPO ?? defaultRepositoryRoot,
+);
+const sourceSkill = resolve(repositoryRoot, "plugin/skills/computer-use/SKILL.md");
+const sourceManifest = resolve(repositoryRoot, "plugin/.dcode-plugin/plugin.json");
+const targetSkill = resolve(packageRoot, "skills/computer-use/SKILL.md");
+const provenancePath = resolve(packageRoot, "upstream.json");
+// 修复：bundled wrapper 的 plugin.json / package.json 之前各自维护 0.1.0，
+// 与实际 dcode-cua MCP server 版本割裂（UI 展示、缓存路径、marketplace 条目都对不上）。
+// 这里把上游 manifest 的 version 作为单一真相源，回写到 bundled wrapper，避免再次漂移。
+const bundledManifestPath = resolve(packageRoot, ".dcode-plugin", "plugin.json");
+const bundledPackageJsonPath = resolve(packageRoot, "package.json");
+
+const [skillBytes, manifestText, workspaceText, revision, sourceStatus] = await Promise.all([
+  readFile(sourceSkill),
+  readFile(sourceManifest, "utf8"),
+  readFile(workspacePath, "utf8"),
+  execFile("git", ["-C", repositoryRoot, "rev-parse", "HEAD"], {
+    encoding: "utf8",
+  }),
+  execFile(
+    "git",
+    [
+      "-C",
+      repositoryRoot,
+      "status",
+      "--porcelain",
+      "--untracked-files=all",
+      "--",
+      "plugin/skills/computer-use/SKILL.md",
+      "plugin/.dcode-plugin/plugin.json",
+    ],
+    { encoding: "utf8" },
+  ),
+]);
+const upstreamCommit = revision.stdout.trim();
+// 不记录本地 worktree 的临时分支名；不可变 commit 同时是可重放的 ref。
+const upstreamRef = upstreamCommit;
+const pins = [
+  ...workspaceText.matchAll(
+    /^\s+"@dcode\/dcode-cua":\s+"git\+https:\/\/dev\.aminer\.cn\/codegeex\/dcode-cua\.git#([0-9a-f]{40})"\s*$/gmu,
+  ),
+].map((match) => match[1]);
+if (pins.length !== 1) {
+  throw new Error("The canonical dcode-cua catalog entry must pin one full producer commit");
+}
+if (!/^[0-9a-f]{40}$/u.test(upstreamCommit) || upstreamCommit !== pins[0]) {
+  throw new Error(
+    `Refusing to sync Skill from ${upstreamCommit || "unknown"}; catalog pins ${pins[0]}`,
+  );
+}
+if (!/^(?!.*\.\.)(?!\/)(?!.*\/$)[A-Za-z0-9._/-]+$/u.test(upstreamRef)) {
+  throw new Error(`Refusing to record invalid producer ref ${upstreamRef || "HEAD"}`);
+}
+if (sourceStatus.stdout.trim() !== "") {
+  throw new Error("Refusing to sync Skill or plugin manifest from uncommitted producer content");
+}
+const manifest = JSON.parse(manifestText);
+if (manifest.name !== "computer-use" || typeof manifest.version !== "string") {
+  throw new Error(`Invalid computer-use plugin manifest at ${sourceManifest}`);
+}
+
+/**
+ * Patch a JSON file's top-level `version` field in place, preserving key order and
+ * 2-space indentation + trailing newline. Only rewrites when the value actually changes,
+ * so a no-op sync leaves the working tree clean.
+ */
+async function syncVersionField(filePath, version) {
+  const text = await readFile(filePath, "utf8");
+  const parsed = JSON.parse(text);
+  if (parsed.version === version) return false;
+  parsed.version = version;
+  await writeFile(filePath, `${JSON.stringify(parsed, null, 2)}\n`);
+  return true;
+}
+
+// 重命名后目标目录可能尚不存在（skills/<name>/），copyFile 不会自动建目录，先确保它存在。
+await mkdir(dirname(targetSkill), { recursive: true });
+await copyFile(sourceSkill, targetSkill);
+await writeFile(
+  provenancePath,
+  `${JSON.stringify(
+    {
+      repository: "https://dev.aminer.cn/codegeex/dcode-cua.git",
+      ref: upstreamRef,
+      commit: upstreamCommit,
+      skillPath: "plugin/skills/computer-use/SKILL.md",
+      skillSha256: createHash("sha256").update(skillBytes).digest("hex"),
+    },
+    null,
+    2,
+  )}\n`,
+);
+
+const manifestUpdated = await syncVersionField(bundledManifestPath, manifest.version);
+const packageJsonUpdated = await syncVersionField(bundledPackageJsonPath, manifest.version);
+
+console.log(`Synced computer-use skill from dcode-cua ${manifest.version}`);
+if (manifestUpdated || packageJsonUpdated) {
+  console.log(
+    `Aligned bundled wrapper version to ${manifest.version} ` +
+      `(plugin.json${manifestUpdated ? " updated" : ""}, package.json${packageJsonUpdated ? " updated" : ""})`,
+  );
+}

package/dist/packages/dcode-cua-plugin/skills/computer-use/SKILL.md

@@ -0,0 +1,306 @@
+---
+name: computer-use
+description: "Use when a task needs a native desktop app's own UI or the OS. For anything inside a web page, use Browser Use. Main agent only."
+---
+
+# Computer Use
+
+Read or operate the UI of native apps on the user's computer.
+
+- Prefer a dedicated connector, API, CLI or skill when one can complete the task.
+- For browser and web tasks, use Browser Use instead.
+- Do not use AppleScript, `osascript`, JXA, System Events, shell commands, or any
+  other UI-automation technology unless the user explicitly asks for that
+  technology.
+- Main agent only. Never delegate Computer Use to a subagent.
+
+## Bootstrap every call
+
+Each `mcp__node_repl__js` call runs in a fresh Worker. Globals, imports, module
+cache and any binding are gone by the next call, so `const app` does not survive
+the end of the cell. The UI state does survive, so re-binding in the next cell is
+cheap.
+
+Put the bootstrap and the actions in the **same** cell, bootstrap first:
+
+```js
+const root =
+  process.env.DCODE_CUA_PLUGIN_ROOT ??
+  process.env.DCODE_PLUGIN_ROOT ??
+  process.env.CLAUDE_PLUGIN_ROOT;
+const { join } = await import("node:path");
+const { pathToFileURL } = await import("node:url");
+const { setupComputerUseRuntime } = await import(
+  pathToFileURL(join(root, "scripts", "computer-use-client.mjs")).href,
+);
+await setupComputerUseRuntime({ globals: globalThis });
+```
+
+## Accessibility first
+
+Accessibility is the primary action path. It is semantic, precise, works on a
+background app and does not steal the user's focus.
+
+1. Observe, then search the returned tree for the target by its role, name,
+   title, value or other visible identity.
+2. When a matching element exists, act on it by **index**. For a control that
+   advertises a semantic action, `performSecondaryAction` is also correct.
+3. For a settable element prefer `setValue` over typing or pasting. Reach for
+   `paste` only when the target is not settable or the content is rich text.
+4. Keyboard input is the fallback: use `pressKey` only when no element expresses
+   the operation, or the user asked for keyboard interaction. Coordinates are the
+   last fallback, for canvas, games and Electron content accessibility cannot see.
+
+Do not replace an available element action with a keyboard shortcut just because
+the shortcut is shorter. Do not run both the accessibility and visual paths for
+the same action.
+
+**Observation works on a background app, screenshots included** — on any
+display, including windows at negative coordinates.
+`has_image: false` means the call did not ask for pixels (`getAXState`), never
+that capture failed.
+
+Success means the API accepted an action, not that the app acted. Typing into a
+web-content editor can be accepted and change nothing, so re-observe to confirm
+the text landed.
+
+## API
+
+```typescript
+type Vec2 = [x: number, y: number];
+type ObservationOptions = { emit?: boolean };
+type StateOptions = ObservationOptions & { disableDiffing?: boolean };
+type StateAndScreenshot = { state: string; screenshot?: Uint8Array };
+type Direction = "up" | "down" | "left" | "right" | "u" | "d" | "l" | "r";
+type MouseButton = "left" | "right" | "middle" | "l" | "r" | "m";
+type SelectionType = "text" | "cursor_before" | "cursor_after";
+type Strategy = "auto" | "a11y" | "event";
+
+type ClickOptions = {
+  mouseButton?: MouseButton;
+  clickCount?: number;
+  modifiers?: string;
+  strategy?: Strategy;
+};
+type SelectTextOptions = { prefix?: string; suffix?: string; selectionType?: SelectionType };
+type PasteOptions = { format?: "text" | "md" | "html" };
+type PressKeyOptions = { holdSeconds?: number; strategy?: Strategy };
+
+interface Target {
+  getAXState(options?: StateOptions): Promise<string>;
+  getScreenshot(options?: ObservationOptions): Promise<Uint8Array>;
+  getAXStateAndScreenshot(options?: StateOptions): Promise<StateAndScreenshot>;
+  elements(): Promise<{ index: number; kind: string; title: string | null; value: string | null; actions: string[] }[]>;
+
+  paste(text: string, options?: PasteOptions): Promise<void>;
+  click(target: number | Vec2, options?: ClickOptions): Promise<void>;
+  drag(from: number | Vec2, to: number | Vec2, options?: { modifiers?: string }): Promise<void>;
+  pressKey(key: string, options?: PressKeyOptions): Promise<void>;
+  scroll(target: number | Vec2, direction: Direction, pages?: number): Promise<void>;
+  selectText(elementIndex: number, text: string, options?: SelectTextOptions): Promise<void>;
+  setValue(elementIndex: number, value: string): Promise<void>;
+  typeText(text: string): Promise<void>;
+  performSecondaryAction(elementIndex: number, action: string): Promise<void>;
+}
+
+interface App extends Target {}
+
+type AppRef = { name?: string; bundle_id?: string; pid?: number; window_id?: number };
+type AppInfo = { pid: number; name: string | null; bundle_id: string | null; active: boolean };
+type State = { apps: AppInfo[] };
+
+declare const agent: {
+  computerUse: {
+    getState(options?: ObservationOptions): Promise<State>;
+    getApp(target: string | AppRef): Promise<App>;
+    listApps(options?: ObservationOptions): Promise<AppInfo[]>;
+    computer: Record<string, (args: object) => Promise<unknown>>;
+
+    requestAccess(capabilities?: string[]): Promise<Record<string, unknown>>;
+    stop(reason?: string): Promise<void>;
+  };
+};
+```
+
+The full reference is `agent.documentation.get("computer-use")`, fetched on demand;
+read it only for an argument shape or response field this page does not give.
+
+## The loop
+
+Observe once, act, then observe again before deciding the next step.
+
+`agent.computerUse.getApp(...)` binds an app and shows nothing; call `getAXState`
+when you need to see its state. Binding also launches it if not running; there is
+no separate launch tool. Its argument is a display name or a bundle identifier —
+the same strings `listApps()` returns — or an `AppRef`.
+
+When the user names an application, copy it character-for-character into the app
+identifier. Do not translate, localize, normalize, shorten, or remove a suffix:
+`{"name":"网易云音乐app"}` is not `{"name":"网易云音乐"}`; `{"name":"日历"}` is not
+`{"name":"Calendar"}`. A rewritten name resolves to a different app or to nothing,
+and the failure reads "app not found". If the exact string does not resolve, call
+`agent.computerUse.listApps()` once and pick the matching identifier.
+
+Batch related actions and a single closing observation into one cell:
+
+```js
+const app = await agent.computerUse.getApp("Notes");
+await app.click(box);
+await app.typeText("hello");
+await app.pressKey("Return");
+await app.getAXState();
+```
+
+An element index addresses that app's latest observation, so several actions may
+reuse one index without re-observing between them — click an index, then type into
+it, in the same cell. Observing renumbers the tree, so take indices from the newest
+one. A vanished element fails closed with `ELEMENT_UNAVAILABLE`.
+
+The tree comes back as a diff only against a tree this cell already showed you,
+listing the elements that were removed, added or changed; unchanged rows are
+omitted and their indices stay valid. The first tree after binding, and the first
+after `getScreenshot` or `elements()`, are always complete. Pass
+`{ disableDiffing: true }` for a full tree at any point. If a standalone
+observation reports no change, do not immediately repeat it without an
+intervening action.
+
+A large tree is trimmed by priority (ancestors kept), the header says so, and
+indices then skip numbers. `app.elements()` returns every element with its index,
+trimmed ones included — filter it in JS, never guess an index.
+
+A capture is scoped to one window: without a `window_id` the main/key window is
+re-resolved every observation, so a modal that just opened becomes the captured
+window. When an action fails or the tree reads like another part of the app, check
+the observation's `window` — a dialog shows up there. Read it, then act on it, or
+dismiss it (Escape or its own cancel) and observe again. A missing element is not
+proof the action worked. Pin one with `getApp({pid, window_id})`; `list_windows`
+has the id.
+
+## Output
+
+Observations display themselves: `getAXState`, `getScreenshot`,
+`getAXStateAndScreenshot`, `getState` and `listApps` emit their own result.
+Never pass their return value to `nodeRepl.write(...)` or
+`nodeRepl.emitImage(...)`: a second raster in one result breaks the one-raster
+rule and the frame is removed entirely, so you end up with no picture at all.
+Pass `{ emit: false }` to suppress the display and still receive the value.
+
+Action methods display nothing.
+
+## Coordinates
+
+Choose `x` and `y` only by looking at the current returned raster, with
+`0 <= x < width` and `0 <= y < height` for that raster. Submit those integers
+unchanged; CUA binds the current raster internally and owns every transform from
+the returned raster to native dispatch. Element and window bounds are diagnostic
+global screen points and must never be copied into a coordinate. When visual
+fallback begins, discard coordinate-like numbers from earlier text or
+accessibility results.
+
+Act on the current raster when the target is clear; if it is too small or ambiguous,
+re-observe rather than guessing at geometry.
+
+A pointer action accepted with no change usually means the app acted where the real
+pointer sits: repeating it will not help — use an element index or the keyboard.
+
+A coordinate refusal may name an unexpected owner, or say the frame is stale — the
+window moved, resized or was replaced. Observe again for a current raster, or act on
+an element index, which does not depend on window geometry. Never move, resize or
+close a window to make a coordinate land.
+
+## Keyboard
+
+`pressKey` takes a key or a `+`-separated chord and accepts both short names and
+X keysym style: `"a"`, `"Return"`, `"Tab"`, `"Control_L+a"`, `"super+c"`, `"Up"`.
+macOS uses `cmd`; Linux and Windows use `ctrl`. Use `{ holdSeconds }` to hold a
+key or chord for a duration rather than simulating repeated presses.
+
+Bind keyboard input to an app or element; never send it unbound. `paste` is for
+rich text, or a target `setValue` cannot set — not for plain text a settable
+element accepts.
+
+`performSecondaryAction` accepts only an action the element advertises in the
+current tree. Do not guess an action name.
+
+At most one element is `focused` — the one holding keyboard focus; absent means
+undetermined.
+
+`selectText` locates text inside an editable element. Use `prefix`/`suffix` to
+disambiguate repeated matches and `selectionType` to place the cursor instead of
+selecting. An ambiguous match is refused rather than resolved to the first hit.
+
+## Waiting
+
+Observations wait for the UI to settle before capturing. Do not pause or delay
+before reading state — no `setTimeout`, no polling loop.
+
+## Errors and stopping
+
+Actions resolve to `undefined` on success and throw `ComputerUseError` otherwise:
+
+- `code` — `PERMISSION_DENIED`, `NOT_AUTHORIZED`, `APP_NOT_FOUND`,
+  `AMBIGUOUS_APP`, `LAUNCH_FAILED`, `INVALID_APP`, `ELEMENT_UNAVAILABLE`,
+  `STALE_STATE`, `NOT_SETTABLE`, `NOT_SELECTABLE`, `ACTION_UNAVAILABLE`,
+  `FOREGROUND_REQUIRED`, `CONTROLLER_BUSY`, `CONTROL_STOPPED`, `SCREEN_LOCKED`,
+  `HELPER_UNAVAILABLE`, `VERSION_MISMATCH`, `TIMEOUT`,
+  `STRUCTURED_STATE_UNAVAILABLE`, `INTERNAL`.
+- `actionSent` — whether the action may already have reached the app. Retry a
+  non-idempotent action only when this is `false`; otherwise observe first and
+  decide from what you see.
+- `retry` — `"reobserve"`, `"retry"` or `"never"`.
+
+`CONTROLLER_BUSY` means another live DCode Computer Use session owns input. It is
+never retryable: report the owner from the error and ask the user to close that
+session.
+
+Stop immediately after `agent.computerUse.stop()`, a kill switch, a permission
+refusal, or a non-retryable error. Do not switch to a different UI-automation
+technology after an access refusal.
+
+Persist until the request is actually complete. Attempting an action is not
+completion: verify the returned state visibly shows the result. If it is unchanged
+or only intermediate, try another approach. Respond only when the requested state
+is visibly present, or explain a concrete blocker you cannot resolve.
+
+## Tool surface
+
+`agent.computerUse.computer.<tool>(args)` is the low-level surface. Prefer the
+bound-object API above; reach for a tool only for what the API does not
+express — window enumeration, key repeat, or reading state back in the same
+call. Arguments are strict: an undeclared key is refused. Each tool takes **one**
+arguments object — the names below are its keys, not positional parameters:
+`get_app_state({ app_ref: { bundle_id: "com.apple.Notes" }, include_screenshot: true })`.
+
+Name an app as the OS lists it (Windows: the Start-menu name, not a window title).
+Nothing takes the user's focus, except on Windows: launching a non-packaged app
+does, and `include_screenshot=true` un-minimizes — a minimized tree is fully
+usable, so keep the default.
+
+```
+list_apps({})
+list_windows({app_ref})
+get_app_state({app_ref, include_screenshot?=false, disable_diffing?=false})
+
+left_click({target, mouse_button?="left", click_count?=1, modifiers?="",
+           strategy?, app_ref?, return_state?})
+left_click_drag({from_target, to, modifiers?="", app_ref?, return_state?})
+scroll({target, scroll_direction, scroll_amount, strategy?, app_ref?,
+       return_state?})
+
+type({text, target?, app_ref?, strategy?, return_state?})
+set_value({target, value, strategy?, app_ref?, return_state?})
+select_text({target, text_range?, app_ref?, return_state?})
+key({text, repeat?, hold_seconds?, app_ref?, strategy?, return_state?})
+paste({text, format?="text", app_ref?, return_state?})
+perform_action({target, action, app_ref?, return_state?})
+
+request_access({capabilities?})
+stop_computer_control({reason?})
+```
+
+Argument shapes: `app_ref` / `app` is an `AppRef`, but a bare string here is
+read as a bundle id, so pass `{name: "Notes"}` for a display name.
+`scroll_direction` is `up|down|left|right`, `scroll_amount` is pages, `strategy`
+is `auto|a11y|event`, and `return_state` is `compact|full|none` to return the app
+state in the same call. For `target`, `text_range`, `modifiers` and the response
+shapes, see `nodeRepl.write(await agent.documentation.get("computer-use"))`.

package/dist/packages/node-repl-host/dist/mcp/server.js

@@ -52622,14 +52622,14 @@ function rewriteDynamicImportsForRepl(code) {
 function nodeEnd(node2) {
   const end = node2.end ?? node2.range?.[1];
   if (end === void 0) {
-    throw new Error("instrument \u9700\u8981\u8282\u70B9 end\uFF08parseReplCode \u5E94\u5E26 ranges:true\uFF09");
+    throw new Error("instrument requires a node end (parseReplCode must be called with ranges:true)");
   }
   return end;
 }
 function nodeStart(node2) {
   const start = node2.start ?? node2.range?.[0];
   if (start === void 0) {
-    throw new Error("instrument \u9700\u8981\u8282\u70B9 start\uFF08parseReplCode \u5E94\u5E26 ranges:true\uFF09");
+    throw new Error("instrument requires a node start (parseReplCode must be called with ranges:true)");
   }
   return start;
 }
@@ -52991,7 +52991,7 @@ var NodeReplSession = class {
     if (this.disposed) {
       return {
         logs: "",
-        error: { name: "DisposedError", message: "REPL session \u5DF2\u91CA\u653E" }
+        error: { name: "DisposedError", message: "REPL session is disposed" }
       };
     }
     let buffer = "";

package/dist/packages/node-repl-host/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dcode/node-repl-host",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Shared node_repl MCP host. Owns the JS execution surface and the domain bridges (Browser Use, Computer Use) that ride on it; the official plugins contribute only their own skills, docs and runtime assets.",
   "type": "module",
   "exports": {