@frontendxlab/opencode-computer-use 0.1.3 → 0.1.5

package/docs/llms-full.txt

@@ -2,6 +2,7 @@ OpenCode Computer Use - full documentation summary
 Canonical site: https://opencode-computer-use.pages.dev/
 Repository: https://github.com/rashidtvmr/opencode-computer-use
 License: MIT
+Documentation updated: 2026-10-30
 
 1. What it is
 OpenCode Computer Use is a dual-generation OpenCode plugin that provides a
@@ -26,6 +27,17 @@ THIRD_PARTY_NOTICES.md in the repository.
   accessibility, screen capture, and input permissions are enforced there.
 The JavaScript VM is a capability guard, not a complete security boundary.
 
+Device scope: the controlled desktop is the signed-in desktop on the computer
+running the OpenCode server and its local native MCP child. A browser or
+attached terminal on a second laptop or phone does not switch that target.
+There is no built-in remote-device discovery, pairing service, or network
+transport. Install dependencies, configure the plugin, and grant desktop
+permissions separately on each target computer. Regenerate checkout paths
+with --source after moving them; do not copy node_modules between OS targets.
+Services, containers, WSL, and detached SSH sessions do not automatically
+inherit access to the host user's graphical desktop. A custom backend is an
+explicit compatible executable plus argv, not automatic remote-device support.
+
 3. Model workflow
 The js tool accepts code (required JavaScript source), timeout_ms (optional,
 capped at 300 seconds), and title (optional short action title).
@@ -34,7 +46,7 @@ Typical first call:
   var app = await cua.getApp(apps[0].id);
   await app.getAXState();
 Typical action and verification:
-  var save = await app.click(12);
+  await app.click(12);
   await app.getAXState();
 State and action rules: read getAXState() or getAXStateAndScreenshot()
 before acting on a new layout; element indexes belong to the most recent
@@ -47,10 +59,12 @@ decide anew; js_reset discards JavaScript bindings only, not native app
 state.
 
 4. API
-- cua.getState(options?): list current desktop apps with bounded output.
-- cua.listApps(options?): structured app records without emitting by
-  default.
-- cua.getApp(nameOrPid): bind an app and emit initial accessibility state.
+- cua.getState(options?): return permitted app inventory as { apps }; emits
+  inventory by default unless options.emit is false.
+- cua.listApps(options?): return permitted app records as an array; emits
+  inventory by default unless options.emit is false. Both inventory methods
+  apply appAccess rules before returning or emitting app records.
+- cua.getApp(nameOrID): bind an app and emit initial accessibility state.
 - app.getAXState(options?): fresh semantic accessibility tree.
 - app.getScreenshot(options?): local image bytes, optionally emitted.
 - app.getAXStateAndScreenshot(options?): combined state and image read.
@@ -81,16 +95,45 @@ the native MCP operations used by cua: initialize, tools/list, tools/call,
 and notifications.
 
 6. Install
+Documentation version: 0.1.5. Run npm view @frontendxlab/opencode-computer-use
+version to check the registry release. Use the checkout instructions
+for the changes documented here. Published-package commands use the
+registry release until a new version is published.
+
+Cloned repository (development dependency installation does not register it):
+  npm ci --ignore-scripts
+  node bin/opencode-computer-use-setup.js --local --v1 --source .
+  node bin/opencode-computer-use-permissions.js --strict
+  opencode mcp list
+Run these commands from the checkout. Use --v2 for OpenCode2 or --global to
+use the checkout from other projects. Setup resolves the source to an absolute
+entrypoint; moving the checkout requires rerunning setup.
+
 Published package:
   npm install @frontendxlab/opencode-computer-use
 The package postinstall step detects OpenCode 1 versus OpenCode2 and local
 versus global installation, edits JSONC without dropping comments, and is
-idempotent. If both generations are ambiguous it makes no change and prints
-manual instructions. Run it explicitly with npx opencode-computer-use-setup;
-use --local, --global, --v1, or --v2 to choose explicitly. If pnpm reports
+idempotent. Global setup also edits the current user's selected JSONC directly;
+it does not depend on an OpenCode plugin-add subcommand. If generation detection
+is ambiguous, automatic installation makes no change and prints manual
+instructions. Explicit manual failures return a nonzero exit status. From
+any directory, select the scoped package and generation explicitly:
+  npm exec --package=@frontendxlab/opencode-computer-use -- opencode-computer-use-setup --local --v1
+  npm exec --package=@frontendxlab/opencode-computer-use -- opencode-computer-use-setup --global --v1
+Use --v2 for OpenCode2 and --dry-run to preview. The shorthand npx
+opencode-computer-use-setup is only suitable when its binary is already
+available in the installed project; it does not name the scoped package for
+download. In a checkout use node bin/opencode-computer-use-setup.js instead.
+If pnpm reports
 ERR_PNPM_IGNORED_BUILDS, approve the package once with pnpm approve-builds
 @frontendxlab/opencode-computer-use, or run pnpm exec
-opencode-computer-use-setup manually. CI environments skip setup.
+opencode-computer-use-setup manually. CI environments skip setup. From v0.1.5, desktop onboarding runs during postinstall when lifecycle scripts are allowed.
+The installer invokes opencode-computer-use-permissions --install. macOS runs
+doctor and opens native Accessibility/Screen Recording onboarding when needed;
+the user must still approve protected TCC toggles. GNOME Linux best-effort
+enables toolkit accessibility before AT-SPI/session diagnostics. Windows checks
+UI Automation and the signed-in interactive desktop. Rerun manually with
+npm exec --package=@frontendxlab/opencode-computer-use -- opencode-computer-use-permissions --strict.
 OpenCode 1 (opencode.json or opencode.jsonc, plugin list):
   { "$schema": "https://opencode.ai/config.json",
     "plugin": [["@frontendxlab/opencode-computer-use", { "backend": "auto" }]] }
@@ -98,10 +141,11 @@ OpenCode2 V2 (plugins shape):
   { "$schema": "https://opencode.ai/config.json",
     "plugins": [{ "package": "@frontendxlab/opencode-computer-use",
       "options": { "backend": "auto" } }] }
-A local checkout can be used by replacing the package name with its absolute
-path. Do not configure the same package both as an explicit plugin and through
+For a checkout, prefer --source . so setup selects its actual entrypoint.
+Do not configure the same package both as an explicit plugin and through
 automatic plugin discovery. If Node is not on PATH, set OPENCODE_NODE to an
-absolute Node executable. Verify with: opencode mcp list.
+absolute Node executable. Restart the relevant OpenCode server/TUI after
+changing its configuration, then verify from the same project with opencode mcp list.
 
 7. Requirements and OS support
 Requirements: Node.js 18 or newer; OpenCode 1.18.29 or newer (V1) or
@@ -110,14 +154,40 @@ and Screen Recording permissions; Linux AT-SPI plus required input and
 capture services; Windows UI Automation in the interactive desktop session.
 The plugin cannot control lock screens, login screens, UAC secure desktops,
 or other OS-owned consent surfaces, and does not bypass permissions.
+Install-time desktop onboarding:
+- macOS 14+: postinstall runs doctor. If Accessibility or Screen Recording is
+  missing, Open Computer Use.app opens its onboarding and System Settings.
+  Manual panes: open x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility
+  and open x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture.
+  Apple still requires the user to approve the protected toggles.
+- Linux: postinstall checks the signed-in AT-SPI2/D-Bus desktop session. On
+  GNOME it best-effort runs: gsettings set org.gnome.desktop.interface
+  toolkit-accessibility true. Wayland capture/coordinate input is compositor-dependent.
+- Windows: there is no separate UI Automation permission toggle. Run in the
+  signed-in interactive desktop session, then verify with open-computer-use call list_apps.
+Rerun the helper with node bin/opencode-computer-use-permissions.js --strict
+from a checkout, or the scoped npm exec helper command above from elsewhere.
+Native open-computer-use commands below assume that CLI is on PATH; otherwise
+prefix them with npm exec --package=open-computer-use@0.3.5 --.
 Packaged native targets: darwin-arm64, darwin-x64, linux-arm64, linux-x64,
-win32-arm64, win32-x64. Validation status: Linux x64 read-only discovery,
-app listing, MCP registration, and persistent session passed local smoke
-tests; one Ubuntu/GNOME Wayland session exposed a Chrome pseudo-window with
-no actionable AT-SPI children and synthetic input did not change it (the
-adapter reports the native result honestly); macOS and Windows have not
-been live-tested in this environment and need on-host permission and
-desktop validation.
+win32-arm64, win32-x64. Android and iOS are not native targets. CI exercises
+the adapter with a fake native backend on Linux, macOS, and Windows without
+a graphical desktop. Packaged binaries and passing headless tests do not
+certify live accessibility, screenshots, focus, or input. Native smoke evidence
+on 2026-10-30: Ubuntu GNOME Wayland Linux x64, Node 26.13.0, OpenCode 1.19.3,
+and native 0.3.5 passed MCP registration, app inventory, persistent bindings,
+and reset checks. In a disposable GTK3 app, semantic app.click changed a
+counter from 0 to 1 and app.setValue changed an entry; fresh accessibility
+snapshots verified both changes. app.getScreenshot returned Screenshot
+unavailable. Keyboard and coordinate input were not validated. Other
+app/session combinations may expose incomplete trees; the GTK result does
+not certify every Linux app or capability. Observe fresh state after actions.
+macOS, Windows, and Linux arm64 native behavior still needs validation on
+real hosts using docs/NATIVE_VALIDATION.md. Permission checks alone are
+insufficient to certify every native capability.
+The --strict helper invokes the native doctor and reports command failures.
+The current Linux doctor prints session guidance; exit status zero does not
+prove that app discovery, accessibility, screenshots, or input will work.
 
 8. Safety
 High-privilege desktop-control surface. The js tool is marked conservatively
@@ -129,23 +199,67 @@ uploading, changing permissions). Do not expose the session to an untrusted
 model or run it unattended against password managers, banking, administrator,
 or other high-value applications. Screenshots, accessibility trees, and typed
 values can contain sensitive data and should stay local. Read SECURITY.md
-before high-risk use. Manual read-only checks before acting:
+before high-risk use. Manual permission and visibility checks before acting:
   open-computer-use doctor
   open-computer-use list-apps
 
 9. Troubleshooting (from the docs page)
-- cua_repl not listed: check the active generation config, restart the TUI or
-  background service after installation, run opencode mcp list, and avoid
-  double registration. For global OpenCode2, run opencode2 plugin add
-  @frontendxlab/opencode-computer-use if the package was installed before
-  automatic setup was available.
+- cua_repl not listed: cloning or installing development dependencies does
+  not register the package. Run the checkout setup sequence with --source .
+  above, or the scoped npm exec setup command for the published package.
+  Choose --local/--global and --v1/--v2 explicitly if needed. Check the
+  configuration path printed by setup, including OPENCODE_CONFIG overrides.
+  Restart the OpenCode server/TUI that uses that configuration and run
+  opencode mcp list from the same project. The plugin registers MCP tools,
+  not a slash command. An existing disabled or stale cua_repl entry is
+  preserved by default; inspect it. Avoid double registration.
+- Works on one device only: install and configure the package on each target
+  computer and grant that desktop's permissions. Attached clients still
+  control the server host. Local paths and graphical sessions are not
+  portable device connections; remote pairing/transport is not built in.
+- Windows PATH launcher error: standard npm global .cmd/.bat launchers are
+  resolved to the adjacent package's native executable without a shell.
+  Other launchers require the runtime installed locally or
+  OPEN_COMPUTER_USE_NATIVE_COMMAND set to the absolute open-computer-use.exe.
 - Node not found: set OPENCODE_NODE or fix server PATH.
-- Empty app list: run open-computer-use list-apps in the same graphical
-  session; confirm the app runs and desktop accessibility is available.
-- Screenshots unavailable: OS compositor or permission gap; bounded
+- macOS Accessibility missing: grant Accessibility to Open Computer Use.app,
+  not Terminal/OpenCode, restart the app-agent, then rerun doctor. Open the pane
+  with: open x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility.
+- macOS Screen Recording missing: grant Open Computer Use.app in Screen &
+  System Audio Recording, restart the app-agent, then rerun doctor. Open the
+  pane with: open x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture.
+- macOS stale permission state: first restart Open Computer Use and verify the
+  correct release app is approved. Last-resort resets are:
+  tccutil reset Accessibility com.ifuryst.opencomputeruse
+  tccutil reset ScreenCapture com.ifuryst.opencomputeruse
+  These reset consent and require the user to approve it again; they do not grant it.
+- macOS native binary will not start: verify sw_vers -productVersion; current
+  native macOS runtime requires macOS 14+ and permissions cannot fix an older OS.
+- Linux empty app list / AT-SPI unavailable: run from the logged-in graphical
+  desktop session, enable GNOME toolkit accessibility with
+  gsettings set org.gnome.desktop.interface toolkit-accessibility true, verify
+  D-Bus/session variables, then rerun open-computer-use call list_apps.
+- Linux Wayland screenshot black/omitted: compositor capture restriction; use
+  semantic accessibility state/actions or test the workflow in an X11 session
+  when reliable coordinate/screenshot automation is required.
+- Linux action reports success but nothing changes: fetch a fresh state and
+  prefer element-index AT-SPI actions/set-value/secondary actions. Coordinate
+  and key synthesis are best-effort under Wayland.
+- Linux Accessible.is_text/is_editable_text error: upgrade/reinstall the current
+  open-computer-use native runtime, which uses standard AT-SPI interfaces.
+- Windows empty app list: run inside the signed-in interactive desktop, not a
+  Windows service, session 0, detached SSH context, or unrelated user session.
+- Windows elevated target: UI Automation/input can be blocked by integrity
+  boundaries. Prefer a normal-user target; match integrity level only when the
+  explicit task truly requires elevation.
+- Windows UAC/lock/sign-in screen: intentionally unsupported secure-desktop/OS
+  surfaces; approve/dismiss manually and return to the normal desktop.
+- Windows app found but action does nothing: keep a visible non-minimized window,
+  refresh state, prefer semantic UIA actions, and verify the result after input.
+- Empty app list generally: run open-computer-use call list_apps in the same
+  graphical session; confirm the app is visible and desktop accessibility is available.
+- Screenshots unavailable generally: OS compositor or permission gap; bounded
   accessibility text may still work.
-- Linux input returns success but nothing changes: session type or missing
-  runtime prerequisite; observe again before retrying mutating actions.
 - Global pointer fallback rejected: expected safety gate.
 
 10. WebMCP preview
@@ -157,6 +271,7 @@ control, shell, network mutation, or credentials. WebMCP is experimental and
 should not be treated as stable browser support.
 
 11. Development
-npm install; npm test; npm run lint. Adapter tests use a fake native MCP
+npm ci --ignore-scripts; npm test; npm run lint. Register a development
+checkout explicitly with the setup --source . command above. Adapter tests use a fake native MCP
 server and need no real desktop. Live desktop validation must run
 separately per OS.

package/docs/llms.txt

@@ -11,6 +11,7 @@
 - [OS support](https://opencode-computer-use.pages.dev/#os)
 - [WebMCP preview](https://opencode-computer-use.pages.dev/#webmcp)
 - [Security](https://opencode-computer-use.pages.dev/#security)
+- [Troubleshooting](https://opencode-computer-use.pages.dev/#troubleshooting)
 - [FAQ](https://opencode-computer-use.pages.dev/#faq)
 
 ## Repo
@@ -21,12 +22,17 @@
 
 ## Key facts
 
+- Documentation version: 0.1.5. Check npm view @frontendxlab/opencode-computer-use version for the registry release. Checkout setup can load source changes before publication; scoped npm exec commands use the registry release.
 - MCP server name: cua_repl. Model-facing tools: js (persistent evaluation) and js_reset (clean session).
 - Async cua API: listApps, getApp, getState, getAXState, getScreenshot, getAXStateAndScreenshot, click, scroll, drag, typeText, pressKey, setValue, performSecondaryAction. Output helpers: nodeRepl.write, nodeRepl.emitImage.
 - WebMCP preview: the docs page registers only read-only search_docs, get_install_config, and get_api_reference tools when document.modelContext is available. It is progressive enhancement, not stable browser support.
 - Safety profiles: safetyMode=read-only blocks mutating CUA methods and changes js annotations; appAccess supports exact-name and ID allow/deny rules.
 - Reliability: app bindings and output are bounded; native timeouts send cancellation; shutdown sends a best-effort turn-ended notification.
 - No arbitrary shell escape. No run_shell in the model-facing API. Restricted VM blocks require, process, fetch, filesystem, dynamic import, and code generation.
-- Published package: @frontendxlab/opencode-computer-use. Its postinstall setup detects OpenCode generation and local/global scope, preserves JSONC, and prints manual instructions when ambiguous. Explicit setup: npx opencode-computer-use-setup --local|--global --v1|--v2.
+- Published package: @frontendxlab/opencode-computer-use. Its postinstall setup detects OpenCode generation and local/global scope and preserves JSONC; global setup edits JSONC directly. Ambiguous automatic setup leaves configuration unchanged; explicit manual failures return nonzero. From any directory: npm exec --package=@frontendxlab/opencode-computer-use -- opencode-computer-use-setup --local --v1. Select --global or --v2 as appropriate. A bare npx helper name only works when the binary is already available; it does not identify this scoped package for download.
+- Cloned repository: npm ci --ignore-scripts, then node bin/opencode-computer-use-setup.js --local --v1 --source . and node bin/opencode-computer-use-permissions.js --strict. Use --v2 for OpenCode2 or --global for other projects. Dependency installation alone does not register a development checkout. Restart OpenCode after setup and check opencode mcp list.
+- Desktop onboarding runs in postinstall when lifecycle scripts are allowed: macOS doctor/onboarding, best-effort GNOME accessibility enablement, and Windows interactive-session diagnostics. Outside a checkout: npm exec --package=@frontendxlab/opencode-computer-use -- opencode-computer-use-permissions --strict.
+- Device scope: the controlled desktop belongs to the OpenCode/MCP server's computer. Attaching a browser or terminal from another device does not change that target. Each computer needs its own dependencies, configuration, permissions, and interactive desktop session; automatic remote-device pairing and network transport are not built in.
 - Requirements: Node.js 18 or newer, OpenCode 1.18.29 or newer (V1) or OpenCode2 V2, plus a signed-in graphical desktop session with OS accessibility and capture permissions.
-- Native runtimes packaged for darwin-arm64, darwin-x64, linux-arm64, linux-x64, win32-arm64, win32-x64. Live smoke tests passed on Linux x64 only; macOS and Windows need on-host validation.
+- Native runtimes packaged for darwin-arm64, darwin-x64, linux-arm64, linux-x64, win32-arm64, win32-x64. Android/iOS are not native targets. CI tests the adapter against a fake native backend; it does not certify desktop input or capture. macOS, Windows, and Linux arm64 require native validation on real hosts.
+- Native smoke evidence on 2026-10-30: Ubuntu GNOME Wayland Linux x64, Node 26.13.0, OpenCode 1.19.3, native 0.3.5. MCP registration, app inventory, persistent bindings/reset, and semantic click/setValue in a disposable GTK3 app passed with fresh accessibility-state verification. Screenshot capture returned unavailable. Keyboard/coordinate input was not validated; other apps and Wayland capabilities need separate checks.

package/docs/sitemap.xml

@@ -2,7 +2,7 @@
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
   <url>
     <loc>https://opencode-computer-use.pages.dev/</loc>
-    <lastmod>2026-09-25</lastmod>
+    <lastmod>2026-09-27</lastmod>
     <changefreq>weekly</changefreq>
     <priority>1.0</priority>
   </url>

package/docs/webmcp.js

@@ -64,7 +64,7 @@
     for (var index = 0; index < entries.length; index += 1) {
       var label = entries[index].querySelector("strong");
       if (!label) continue;
-      var documented = String(label.textContent || "").trim().toLowerCase();
+      var documented = String(label.textContent || "").split("(")[0].trim().toLowerCase();
       var method = documented.split(".").pop();
       if (documented === requested || documented.endsWith("." + requested) || (requested.indexOf(".") === -1 && method === requested)) {
         return result(plainText(entries[index], 2000));
@@ -92,7 +92,7 @@
     {
       name: "get_install_config",
       title: "Get installation configuration",
-      description: "Return the documented OpenCode installation configuration for one generation.",
+      description: "Return the published-package OpenCode configuration for one generation. For a cloned repository, use the documented setup --source command instead. The local MCP server controls the OpenCode server host's desktop; this configuration does not pair remote devices.",
       inputSchema: {
         type: "object",
         properties: {

package/lib/backend.js

@@ -1,6 +1,6 @@
 import { constants, accessSync, existsSync, statSync } from "node:fs";
 import { createRequire } from "node:module";
-import { delimiter, dirname, join } from "node:path";
+import { dirname, join } from "node:path";
 import process from "node:process";
 import { normalizeOptions, optionsFromEnvironment } from "./options.js";
 
@@ -15,6 +15,8 @@ const PLATFORM_PATHS = {
   "win32-x64": ["dist", "windows", "amd64", "open-computer-use.exe"],
 };
 
+const SUPPORTED_TARGETS = Object.freeze(Object.keys(PLATFORM_PATHS));
+
 function isExecutable(path) {
   try {
     accessSync(path, constants.X_OK);
@@ -24,14 +26,22 @@ function isExecutable(path) {
   }
 }
 
-function commandOnPath(name, environment = process.env) {
-  const pathValue = environment.PATH;
+function environmentValue(environment, name, platform) {
+  if (platform !== "win32") return environment[name];
+  // Windows environment names are case-insensitive. Match Node's sorted-key
+  // choice when a supplied object contains more than one spelling of a name.
+  const key = Object.keys(environment).sort().find((key) => key.toUpperCase() === name.toUpperCase());
+  return key === undefined ? undefined : environment[key];
+}
+
+export function commandOnPath(name, environment = process.env, platform = process.platform) {
+  const pathValue = environmentValue(environment, "PATH", platform);
   if (!pathValue) return undefined;
   const extensions =
-    process.platform === "win32"
-      ? (environment.PATHEXT || ".EXE;.CMD;.BAT;.COM").split(";")
+    platform === "win32"
+      ? (environmentValue(environment, "PATHEXT", platform) || ".EXE;.CMD;.BAT;.COM").split(";")
       : [""];
-  for (const directory of pathValue.split(delimiter)) {
+  for (const directory of pathValue.split(platform === "win32" ? ";" : ":")) {
     if (!directory) continue;
     for (const extension of extensions) {
       const candidate = join(directory, `${name}${extension}`);
@@ -41,6 +51,21 @@ function commandOnPath(name, environment = process.env) {
   return undefined;
 }
 
+export function resolvePathExecutable(command, platform = process.platform, arch = process.arch) {
+  if (platform !== "win32" || !/\.(?:cmd|bat)$/i.test(command)) return command;
+  // npm's global Windows shim cannot be spawned with shell:false. Resolve the
+  // known package's native executable beside that shim instead of invoking a
+  // command shell or interpreting arbitrary shim contents.
+  const relative = PLATFORM_PATHS[`${platform}-${arch}`];
+  if (relative) {
+    const executable = join(dirname(command), "node_modules", "open-computer-use", ...relative);
+    if (isExecutable(executable)) return executable;
+  }
+  throw new Error(
+    "The Windows open-computer-use PATH entry is a .cmd/.bat launcher without an adjacent native runtime. Install open-computer-use@0.3.5 in this package or set OPEN_COMPUTER_USE_NATIVE_COMMAND to the absolute open-computer-use.exe path. Shell launchers are not executed.",
+  );
+}
+
 function packageRoot() {
   try {
     return dirname(require.resolve("open-computer-use/package.json"));
@@ -79,6 +104,11 @@ function nativeCommand(environment) {
 
   const root = packageRoot();
   const relative = PLATFORM_PATHS[`${process.platform}-${process.arch}`];
+  if (!relative) {
+    throw new Error(
+      `Open Computer Use does not provide a native runtime for ${process.platform}-${process.arch}. Supported targets: ${SUPPORTED_TARGETS.join(", ")}. Configure backend 'custom' or OPEN_COMPUTER_USE_NATIVE_COMMAND if you provide a compatible runtime yourself.`,
+    );
+  }
   if (root && relative) {
     const executable = join(root, ...relative);
     if (isExecutable(executable)) {
@@ -98,7 +128,7 @@ function nativeCommand(environment) {
     return {
       name: "open-computer-use",
       source: "PATH:open-computer-use",
-      command: fromPath,
+      command: resolvePathExecutable(fromPath),
       args: ["mcp"],
       platform: process.platform,
       arch: process.arch,
@@ -106,7 +136,7 @@ function nativeCommand(environment) {
   }
 
   throw new Error(
-    "Open Computer Use native runtime is not installed. Install open-computer-use or set OPEN_COMPUTER_USE_NATIVE_COMMAND.",
+    `Open Computer Use native runtime for ${process.platform}-${process.arch} is not installed or executable. Install open-computer-use@0.3.5, ensure its install scripts were allowed, or set OPEN_COMPUTER_USE_NATIVE_COMMAND.`,
   );
 }
 
@@ -132,7 +162,7 @@ export function resolveBackend(input = {}, environment = process.env) {
   return nativeCommand(environment);
 }
 
-export function backendEnvironment(environment = process.env) {
+export function backendEnvironment(environment = process.env, platform = process.platform) {
   const allowed = new Set([
     "PATH",
     "HOME",
@@ -182,9 +212,15 @@ export function backendEnvironment(environment = process.env) {
     "COMPUTER_USE_LINUX_SCREENSHOT_BACKEND",
   ]);
 
-  return Object.fromEntries(
-    Object.entries(environment).filter(
-      ([key, value]) => allowed.has(key) && typeof value === "string",
-    ),
-  );
+  const normalizeName = platform === "win32" ? (name) => name.toUpperCase() : (name) => name;
+  const allowedNames = new Set([...allowed].map(normalizeName));
+  const seen = new Set();
+  const keys = Object.keys(environment);
+  if (platform === "win32") keys.sort();
+  return Object.fromEntries(keys.flatMap((key) => {
+    const name = normalizeName(key);
+    if (!allowedNames.has(name) || seen.has(name) || typeof environment[key] !== "string") return [];
+    seen.add(name);
+    return [[key, environment[key]]];
+  }));
 }

package/lib/json-line-peer.mjs

@@ -37,6 +37,9 @@ export class JsonLinePeer extends EventEmitter {
     this.child.stderr.setEncoding("utf8");
     this.child.stdout.on("data", (chunk) => this.#onData(chunk));
     this.child.stderr.on("data", (chunk) => { this.stderr = (this.stderr + chunk).slice(-8192); });
+    for (const stream of [this.child.stdin, this.child.stdout, this.child.stderr]) {
+      stream.on("error", (error) => this.#close(error, true));
+    }
     this.child.once("error", (error) => this.#close(error, true));
     this.child.once("exit", (code, signal) => {
       this.exited = true;

package/lib/sandbox.mjs

@@ -1,4 +1,5 @@
 import { runInContext } from "node:vm";
+import { parse } from "acorn";
 
 const MAX_FRAME_BYTES = 32 * 1024 * 1024;
 const MAX_APP_BINDINGS = 128;
@@ -219,8 +220,45 @@ export function hardenSandboxContext(context) {
 }
 
 export function assertSandboxCode(code) {
-  if (/(^|[^A-Za-z0-9_$])import([^A-Za-z0-9_$]|$)/u.test(code)) {
-    throw new Error("dynamic imports are disabled in the CUA sandbox");
+  const options = {
+    ecmaVersion: "latest",
+    allowAwaitOutsideFunction: true,
+    allowReturnOutsideFunction: true,
+    allowImportExportEverywhere: true,
+  };
+  let ast;
+  try {
+    ast = parse(code, { ...options, sourceType: "script" });
+  } catch (scriptError) {
+    try {
+      // Module grammar also covers top-level resource declarations. The REPL
+      // remains responsible for whether otherwise-safe syntax can execute.
+      ast = parse(code, { ...options, sourceType: "module" });
+    } catch {
+      try {
+        // Like Node's REPL, accept an object literal entered as one expression.
+        ast = parse(`(${code}\n)`, { ...options, sourceType: "script" });
+      } catch {
+        throw scriptError;
+      }
+    }
+  }
+  const nodes = [ast];
+  while (nodes.length > 0) {
+    const node = nodes.pop();
+    if (node.type === "ImportExpression" || node.type === "ImportDeclaration"
+      || (node.type === "MetaProperty" && node.meta?.name === "import")) {
+      throw new Error("dynamic imports are disabled in the CUA sandbox");
+    }
+    for (const value of Object.values(node)) {
+      if (Array.isArray(value)) {
+        for (const child of value) {
+          if (child && typeof child.type === "string") nodes.push(child);
+        }
+      } else if (value && typeof value.type === "string") {
+        nodes.push(value);
+      }
+    }
   }
 }
 
@@ -294,6 +332,9 @@ export function createSandboxBridge(
     return accessPolicy.default === "allow";
   };
   const assertNamedAppAllowed = async (name) => {
+    if (accessPolicy.default === "deny" && accessPolicy.allow.size === 0) {
+      throw new Error(`app access denied by policy: ${name}`);
+    }
     if (accessPolicy.allow.size === 0 && accessPolicy.deny.size === 0) return;
     const apps = await api.listApps({ emit: false });
     const matches = Array.isArray(apps) ? apps.filter((app) => appNameMatches(app, name)) : [];
@@ -313,9 +354,15 @@ export function createSandboxBridge(
       if (!isActive()) throw new Error("CUA calls are only available while js is executing");
       if (method === "getState") {
         const state = await api.getState({ emit: false });
-        return encodeSandboxResult({ apps: filterApps(state.apps) });
+        const apps = filterApps(state.apps);
+        if (args[0]?.emit !== false) activeOutput().write(apps, "cua.state");
+        return encodeSandboxResult({ apps });
+      }
+      if (method === "listApps") {
+        const apps = filterApps(await api.listApps({ emit: false }));
+        if (args[0]?.emit !== false) activeOutput().write(apps, "cua.state");
+        return encodeSandboxResult(apps);
       }
-      if (method === "listApps") return encodeSandboxResult(filterApps(await api.listApps({ emit: false })));
       if (method === "getApp") {
         const app = args[0];
         if (typeof app !== "string" || !app.trim()) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontendxlab/opencode-computer-use",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "A dual OpenCode and OpenCode2 plugin for local cross-platform desktop control.",
   "license": "MIT",
   "repository": {
@@ -29,27 +29,29 @@
   },
   "bin": {
     "opencode-computer-use-repl": "bin/opencode-computer-use-repl.js",
-    "opencode-computer-use-setup": "bin/opencode-computer-use-setup.js"
+    "opencode-computer-use-setup": "bin/opencode-computer-use-setup.js",
+    "opencode-computer-use-permissions": "bin/opencode-computer-use-permissions.js"
   },
   "files": [
     "bin/",
     "lib/",
     "docs/",
     "index.js",
+    "CHANGELOG.md",
     "README.md",
     "SECURITY.md",
     "LICENSE",
     "THIRD_PARTY_NOTICES.md"
   ],
   "engines": {
-    "node": ">=18",
-    "opencode": ">=0.0.0-beta-18684"
+    "node": ">=18"
   },
   "scripts": {
-    "postinstall": "node bin/opencode-computer-use-setup.js --auto",
-    "lint": "node --check index.js && node --check bin/opencode-computer-use-repl.js && node --check bin/opencode-computer-use-setup.js && node --check lib/backend.js && node --check lib/json-line-peer.mjs && node --check lib/options.js && node --check lib/output.mjs && node --check lib/repl.mjs && node --check lib/repl-kernel.mjs && node --check lib/sandbox.mjs",
-    "test": "node --test",
-    "prepack": "node --check index.js && node --check bin/opencode-computer-use-repl.js && node --check bin/opencode-computer-use-setup.js && node -e \"JSON.parse(require('fs').readFileSync('package.json','utf8'))\"",
+    "postinstall": "node bin/opencode-computer-use-setup.js --auto && node bin/opencode-computer-use-permissions.js --install",
+    "lint": "node --check index.js && node --check bin/opencode-computer-use-repl.js && node --check bin/opencode-computer-use-setup.js && node --check bin/opencode-computer-use-permissions.js && node --check lib/backend.js && node --check lib/json-line-peer.mjs && node --check lib/options.js && node --check lib/output.mjs && node --check lib/repl.mjs && node --check lib/repl-kernel.mjs && node --check lib/sandbox.mjs",
+    "test": "node --test test/run.mjs",
+    "test:opencode": "node test/opencode-smoke.mjs",
+    "prepack": "node --check index.js && node --check bin/opencode-computer-use-repl.js && node --check bin/opencode-computer-use-setup.js && node --check bin/opencode-computer-use-permissions.js && node -e \"JSON.parse(require('fs').readFileSync('package.json','utf8'))\"",
     "prepublishOnly": "npm run lint && npm test"
   },
   "optionalDependencies": {
@@ -57,6 +59,7 @@
   },
   "sideEffects": false,
   "dependencies": {
+    "acorn": "^8.19.0",
     "jsonc-parser": "^3.3.1"
   }
 }