@frontendxlab/opencode-computer-use 0.1.0 → 0.1.2

package/README.md

@@ -75,7 +75,7 @@ capabilities remain OS and session dependent.
 
 - Node.js 18 or newer.
 - OpenCode 1.18.29 or newer for the hybrid V1 entrypoint.
-- OpenCode2 V2 for the `setup(ctx)` entrypoint.
+- OpenCode2 V2 beta 19271 or newer for the `setup(ctx)` entrypoint.
 - A signed-in graphical desktop session.
 - macOS Accessibility and Screen Recording permissions.
 - Linux AT-SPI and the input/capture services required by the native runtime.
@@ -91,8 +91,40 @@ local MCP server named `cua_repl` by default.
 
 ```sh
 npm install @frontendxlab/opencode-computer-use
+# or
+pnpm install @frontendxlab/opencode-computer-use
 ```
 
+The package `postinstall` step detects the installed OpenCode generation and
+whether the install is local or global. It safely updates `opencode.json` or
+`opencode.jsonc`, preserves comments and existing settings, and is idempotent.
+When both generations are installed, it uses an existing `plugin` or `plugins`
+configuration to disambiguate. If that is not possible, it makes no change and
+prints both manual configuration formats.
+
+You can run setup explicitly at any time:
+
+```sh
+npx opencode-computer-use-setup
+npx opencode-computer-use-setup --local --v2
+npx opencode-computer-use-setup --global --v1
+```
+
+Use `--dry-run` to inspect the action without changing files. Set
+`OPENCODE_COMPUTER_USE_SKIP_SETUP=1` to disable the postinstall hook. Restart
+OpenCode after a successful setup so the plugin is loaded.
+
+Recent pnpm releases may require explicit approval before running lifecycle
+scripts from dependencies. If pnpm reports `ERR_PNPM_IGNORED_BUILDS`, approve
+this package once and rerun the install:
+
+```sh
+pnpm approve-builds @frontendxlab/opencode-computer-use
+pnpm install
+```
+
+If scripts are intentionally disabled, run `pnpm exec opencode-computer-use-setup` manually instead.
+
 A local checkout can be loaded by replacing the package name with its absolute
 path.
 
@@ -141,12 +173,33 @@ automatic plugin discovery. That loads the session twice.
 | `command` | none | Required for `custom`; a native MCP executable followed by argv. |
 | `serverName` | `cua_repl` | MCP server name. |
 | `override` | `false` | Replace an existing MCP server with the same name. |
+| `safetyMode` | `full` | `full` or `read-only`; read-only blocks click, drag, key, scroll, text, value, and secondary actions. |
+| `appAccess` | allow all | Optional `default`, `allow`, and `deny` rules matched against app names and IDs. |
 | `timeoutMs` | `30000` | Default and maximum JavaScript evaluation timeout. |
 | `disabled` | `false` | Register the server disabled. |
 | `maxTextChars` | `200000` | Aggregate text budget for one tool result. |
 | `maxImageBytes` | `2097152` | Aggregate image payload budget for one tool result. |
 | `allowGlobalPointerFallbacks` | `false` | Explicitly allow native global pointer fallback for coordinate clicks and drags. |
 
+For a deny-by-default desktop policy, configure the adapter explicitly:
+
+```json
+{
+  "safetyMode": "read-only",
+  "appAccess": {
+    "default": "deny",
+    "allow": ["com.apple.TextEdit", "Text"],
+    "deny": ["com.apple.Safari"]
+  }
+}
+```
+
+App rules are exact, case-insensitive matches against app names and IDs. They
+are defense in depth and do not replace macOS Accessibility and Screen Recording,
+Linux AT-SPI, Windows UIA, or OpenCode approval settings. The read-only mode
+also changes the MCP annotations for `js` so hosts can apply their normal
+read-only approval policy.
+
 The proxy reads corresponding `OPENCODE_COMPUTER_USE_*` environment variables
 when launched directly.
 
@@ -242,6 +295,11 @@ the model-facing session. The native
 `run_shell` operation is not part of the Codex-style `cua` API. Do not add an
 arbitrary shell escape to the JavaScript session.
 
+The adapter bounds persistent app bindings and output items, sends a native
+cancellation notification when a request times out, and sends a best-effort
+`notifications/turn-ended` message during shutdown. These are reliability and
+cleanup safeguards, not a replacement for host approvals.
+
 ## Documentation WebMCP preview
 
 The Cloudflare Pages documentation includes a progressive, read-only WebMCP

package/SECURITY.md

@@ -16,8 +16,17 @@ sandbox.
   imports, code generation, and dynamic host objects are unavailable in the
   model-facing context.
 - Native calls are serialized through the persistent session.
+- `safetyMode: "read-only"` blocks mutating CUA methods before native execution.
+- `appAccess` can deny apps by exact name or ID before native access.
+- App bindings, output items, text, images, and native frames are bounded.
+- Native timeouts send a cancellation notification; shutdown sends a best-effort
+  turn-ended notification.
 - Desktop environment variables are allowlisted.
 - Screenshot and text results remain local MCP content.
+- The postinstall setup only adds this package to OpenCode's plugin list, keeps
+  JSONC comments, creates a `.bak` before replacement, and never edits a
+  conflicting or malformed configuration. Ambiguous setup is non-destructive
+  and prints manual instructions.
 
 ## Operator responsibilities
 

package/THIRD_PARTY_NOTICES.md

@@ -14,6 +14,10 @@ The persistent JavaScript session adapter in `lib/repl.mjs`,
 The native runtime is installed separately as the optional dependency
 `open-computer-use@0.3.5`, which is distributed under the same MIT license.
 
+The automatic setup command uses `jsonc-parser@3.3.1`, copyright Microsoft
+Corporation and contributors, under the MIT license. It is used only to make
+targeted edits to OpenCode JSONC configuration files.
+
 The adapter was changed to resolve the optional runtime package, use a
 minimal desktop environment allowlist, expose the session through the
 OpenCode plugin entrypoint, and run model code in a restricted VM context.

package/bin/opencode-computer-use-setup.js

@@ -0,0 +1,467 @@
+#!/usr/bin/env node
+
+import { copyFileSync, existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { delimiter, dirname, join, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { applyEdits, modify, parse, parseTree } from "jsonc-parser";
+
+const PACKAGE_NAME = "@frontendxlab/opencode-computer-use";
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const DEFAULT_V1_OPTIONS = { backend: "auto" };
+
+export const FALLBACK_INSTRUCTIONS = `
+Automatic OpenCode setup could not safely choose a configuration.
+
+For OpenCode 1, add this to opencode.json or opencode.jsonc:
+
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    ["@frontendxlab/opencode-computer-use", { "backend": "auto" }]
+  ]
+}
+
+For OpenCode2 V2, add this to opencode.json or opencode.jsonc:
+
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugins": [
+    {
+      "package": "@frontendxlab/opencode-computer-use",
+      "options": { "backend": "auto" }
+    }
+  ]
+}
+
+For global OpenCode2 V2 setup, run:
+
+opencode2 plugin add @frontendxlab/opencode-computer-use
+
+After changing configuration, restart OpenCode:
+
+opencode service restart
+opencode2 service restart
+`.trim();
+
+function print(text, stream = "stdout") {
+  process[stream].write(`${text}\n`);
+}
+
+function parseArguments(argv) {
+  const result = {
+    scope: "auto",
+    flavor: "auto",
+    dryRun: false,
+    help: false,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (argument === "--global" || argument === "-g") {
+      result.scope = "global";
+    } else if (argument === "--local" || argument === "--project") {
+      result.scope = "local";
+    } else if (argument === "--v1") {
+      result.flavor = "v1";
+    } else if (argument === "--v2") {
+      result.flavor = "v2";
+    } else if (argument === "--opencode-version") {
+      const value = argv[++index];
+      if (value !== "1" && value !== "2") {
+        throw new Error("--opencode-version must be 1 or 2");
+      }
+      result.flavor = value === "1" ? "v1" : "v2";
+    } else if (argument === "--dry-run") {
+      result.dryRun = true;
+    } else if (argument === "--help" || argument === "-h") {
+      result.help = true;
+    } else if (argument === "--auto") {
+      continue;
+    } else {
+      throw new Error(`Unknown setup option: ${argument}`);
+    }
+  }
+
+  return result;
+}
+
+function usage() {
+  return `Usage: opencode-computer-use-setup [options]
+
+Options:
+  --auto                 Detect OpenCode generation and scope (default)
+  --local, --project     Configure the current project
+  --global               Configure the current user's global config
+  --v1                   Configure the OpenCode 1 plugin format
+  --v2                   Configure the OpenCode2 V2 plugin format
+  --opencode-version 1|2 Select the OpenCode generation explicitly
+  --dry-run              Show the action without changing files
+  --help, -h             Show this help
+`;
+}
+
+function executableCandidates(command, env = process.env) {
+  const pathValue = env.PATH || "";
+  const directories = pathValue.split(delimiter).filter(Boolean);
+  if (process.platform === "win32") {
+    const extensions = (env.PATHEXT || ".EXE;.CMD;.BAT").split(";").filter(Boolean);
+    return directories.flatMap((directory) => [
+      join(directory, command),
+      ...extensions.map((extension) => join(directory, `${command}${extension.toLowerCase()}`)),
+      ...extensions.map((extension) => join(directory, `${command}${extension}`)),
+    ]);
+  }
+  return directories.map((directory) => join(directory, command));
+}
+
+function isExecutableFile(path) {
+  try {
+    return statSync(path).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function resolveCommand(command, env = process.env) {
+  return executableCandidates(command, env).find(isExecutableFile) || command;
+}
+
+function probeCommand(command, env = process.env) {
+  const executable = resolveCommand(command, env);
+  const result = spawnSync(executable, ["--version"], {
+    encoding: "utf8",
+    env,
+    shell: false,
+    windowsHide: true,
+    timeout: 10_000,
+  });
+  if (result.error || result.status !== 0) {
+    return {
+      command,
+      available: false,
+      version: null,
+      output: `${result.stdout || ""}${result.stderr || ""}`.trim(),
+    };
+  }
+  const output = `${result.stdout || ""}\n${result.stderr || ""}`.trim();
+  const match = output.match(/(?:opencode2?|opencode)\s+v?(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)/iu);
+  return {
+    command,
+    available: true,
+    version: match?.[1] || output.split(/\r?\n/u)[0] || "unknown",
+    output,
+  };
+}
+
+export function detectOpenCode(env = process.env) {
+  return {
+    v1: probeCommand("opencode", env),
+    v2: probeCommand("opencode2", env),
+  };
+}
+
+function packageKey(entry) {
+  if (typeof entry === "string") return entry;
+  if (Array.isArray(entry) && typeof entry[0] === "string") return entry[0];
+  if (entry && typeof entry === "object" && typeof entry.package === "string") return entry.package;
+  return undefined;
+}
+
+function hasPackage(entries) {
+  return Array.isArray(entries) && entries.some((entry) => packageKey(entry) === PACKAGE_NAME);
+}
+
+function configFlavor(text) {
+  const root = parseTree(text);
+  if (!root || root.type !== "object") return null;
+  const names = (root.children || [])
+    .filter((child) => child.type === "property")
+    .map((property) => property.children?.[0]?.value)
+    .filter((name) => name === "plugin" || name === "plugins");
+  const hasV1 = names.includes("plugin");
+  const hasV2 = names.includes("plugins");
+  if (hasV1 && hasV2) return "ambiguous";
+  if (hasV1) return "v1";
+  if (hasV2) return "v2";
+  return null;
+}
+
+function existingConfigFiles(root, scope, env = process.env) {
+  const bases = scope === "global"
+    ? [globalConfigDir(env)]
+    : [root, join(root, ".opencode")];
+  const files = [];
+  for (const base of bases) {
+    for (const name of ["opencode.jsonc", "opencode.json"]) {
+      const file = join(base, name);
+      if (existsSync(file) && !files.includes(file)) files.push(file);
+    }
+  }
+  return files;
+}
+
+export function configFiles(root, scope, env = process.env) {
+  return existingConfigFiles(root, scope, env);
+}
+
+export function globalConfigDir(env = process.env) {
+  if (env.OPENCODE_CONFIG_DIR) return resolve(env.OPENCODE_CONFIG_DIR);
+  if (env.XDG_CONFIG_HOME) return join(resolve(env.XDG_CONFIG_HOME), "opencode");
+  const home = env.HOME || env.USERPROFILE || homedir();
+  return join(resolve(home), ".config", "opencode");
+}
+
+export function detectConfigFlavor(root, scope, env = process.env) {
+  const files = existingConfigFiles(root, scope, env);
+  let detected = null;
+  for (const file of files) {
+    let text;
+    try {
+      text = readFileSync(file, "utf8");
+    } catch {
+      continue;
+    }
+    const flavor = configFlavor(text);
+    if (flavor && detected && flavor !== detected) return "ambiguous";
+    if (flavor) detected = flavor;
+  }
+  return detected;
+}
+
+export function inferScope(requested, env = process.env) {
+  if (requested === "local" || requested === "global") return requested;
+  const globalFlag = env.npm_config_global ?? env.NPM_CONFIG_GLOBAL;
+  if (globalFlag === "true" || globalFlag === true || globalFlag === "1") return "global";
+  return "local";
+}
+
+function defaultConfigFile(root, scope, env) {
+  const configDir = scope === "global" ? globalConfigDir(env) : root;
+  return join(configDir, "opencode.json");
+}
+
+function addEntry(entries, flavor) {
+  if (hasPackage(entries)) return { entries, changed: false };
+  const entry = flavor === "v1"
+    ? [PACKAGE_NAME, { ...DEFAULT_V1_OPTIONS }]
+    : PACKAGE_NAME;
+  return { entries: [...entries, entry], changed: true };
+}
+
+function newConfig(flavor) {
+  const key = flavor === "v1" ? "plugin" : "plugins";
+  const entry = flavor === "v1"
+    ? [[PACKAGE_NAME, { ...DEFAULT_V1_OPTIONS }]]
+    : [PACKAGE_NAME];
+  return {
+    $schema: "https://opencode.ai/config.json",
+    [key]: entry,
+  };
+}
+
+export function updateConfigText(text, flavor) {
+  const parsed = parse(text);
+  if (text.trim() && (parsed === undefined || parsed === null || typeof parsed !== "object" || Array.isArray(parsed))) {
+    throw new Error("configuration is not a JSON or JSONC object");
+  }
+  const data = parsed && typeof parsed === "object" ? parsed : {};
+  if (data.plugin !== undefined && data.plugins !== undefined) {
+    throw new Error("configuration contains both plugin and plugins fields");
+  }
+  const key = flavor === "v1" ? "plugin" : "plugins";
+  const current = data[key];
+  if (current !== undefined && !Array.isArray(current)) {
+    throw new Error(`configuration field "${key}" is not an array`);
+  }
+  const result = addEntry(current || [], flavor);
+  if (!result.changed) return { text, changed: false };
+  const edits = modify(text, [key], result.entries, {
+    formattingOptions: {
+      insertSpaces: true,
+      tabSize: 2,
+      eol: text.includes("\r\n") ? "\r\n" : "\n",
+    },
+  });
+  return { text: applyEdits(text, edits), changed: true };
+}
+
+function writeConfig(file, content, dryRun) {
+  if (dryRun) return;
+  mkdirSync(dirname(file), { recursive: true });
+  if (existsSync(file)) {
+    copyFileSync(file, `${file}.bak`);
+  }
+  const temporary = `${file}.tmp-${process.pid}`;
+  writeFileSync(temporary, content, "utf8");
+  if (process.platform === "win32" && existsSync(file)) rmSync(file, { force: true });
+  renameSync(temporary, file);
+}
+
+function packageAlreadyConfigured(root, scope, env) {
+  for (const file of existingConfigFiles(root, scope, env)) {
+    try {
+      const data = parse(readFileSync(file, "utf8"));
+      const key = data?.plugins !== undefined ? "plugins" : data?.plugin !== undefined ? "plugin" : undefined;
+      if (key && hasPackage(data[key])) return file;
+    } catch {
+      continue;
+    }
+  }
+  return undefined;
+}
+
+function runPluginCli(flavor, scope, root, env) {
+  const command = flavor === "v1" ? "opencode" : "opencode2";
+  const args = ["plugin", "add", PACKAGE_NAME];
+  if (flavor === "v1" && scope === "global") args.push("--global");
+  const result = spawnSync(resolveCommand(command, env), args, {
+    cwd: root,
+    encoding: "utf8",
+    env,
+    shell: process.platform === "win32",
+    windowsHide: true,
+    timeout: 120_000,
+  });
+  if (result.error || result.status !== 0) {
+    const detail = `${result.stdout || ""}${result.stderr || ""}`.trim().slice(0, 500);
+    throw new Error(`${command} plugin add failed${detail ? `: ${detail}` : ""}`);
+  }
+}
+
+function configForSetup(root, scope, flavor, env, dryRun) {
+  const files = existingConfigFiles(root, scope, env);
+  if (files.length > 0) {
+    const flavors = files.map((file) => {
+      try {
+        return configFlavor(readFileSync(file, "utf8"));
+      } catch {
+        return null;
+      }
+    });
+    if (flavors.includes("ambiguous")) {
+      throw new Error("configuration contains both plugin and plugins fields");
+    }
+    if (new Set(flavors.filter(Boolean)).size > 1) {
+      throw new Error("multiple conflicting OpenCode configuration files were found");
+    }
+  }
+  const file = files[0] || defaultConfigFile(root, scope, env);
+  if (!existsSync(file)) {
+    const content = JSON.stringify(newConfig(flavor), null, 2) + "\n";
+    writeConfig(file, content, dryRun);
+    return { file, changed: true };
+  }
+  const result = updateConfigText(readFileSync(file, "utf8"), flavor);
+  writeConfig(file, result.text, dryRun);
+  return { file, changed: result.changed };
+}
+
+function chooseFlavor(requested, detection, config) {
+  if (config === "ambiguous") {
+    throw new Error("configuration contains both plugin and plugins fields");
+  }
+  if (requested !== "auto") {
+    if (config && config !== requested) {
+      throw new Error(`selected ${requested} conflicts with the existing ${config} configuration`);
+    }
+    return requested;
+  }
+  if (detection.v1.available && detection.v2.available) {
+    if (config === "v1" || config === "v2") return config;
+    throw new Error("both OpenCode 1 and OpenCode2 are installed, and the configuration is ambiguous");
+  }
+  if (detection.v1.available) return "v1";
+  if (detection.v2.available) return "v2";
+  throw new Error("neither opencode nor opencode2 was found");
+}
+
+function chooseRoot(scope, env) {
+  if (scope === "global") return process.cwd();
+  const initial = env.INIT_CWD || process.cwd();
+  return resolve(initial);
+}
+
+export async function setup(options = {}, env = process.env, io = print) {
+  const requestedScope = options.scope || "auto";
+  const requestedFlavor = options.flavor || "auto";
+  const scope = inferScope(requestedScope, env);
+  const root = chooseRoot(scope, env);
+  const detection = detectOpenCode(env);
+  const config = detectConfigFlavor(root, scope, env);
+  const flavor = chooseFlavor(requestedFlavor, detection, config);
+  const dryRun = Boolean(options.dryRun);
+  let result;
+  if (scope === "global" && !dryRun) {
+    const existing = packageAlreadyConfigured(root, scope, env);
+    if (existing) {
+      result = { file: existing, changed: false };
+    } else {
+      runPluginCli(flavor, scope, root, env);
+      const configured = packageAlreadyConfigured(root, scope, env);
+      if (!configured) throw new Error(`${flavor.toUpperCase()} plugin command did not register the package`);
+      result = { file: configured, changed: true };
+    }
+  } else {
+    result = configForSetup(root, scope, flavor, env, dryRun);
+  }
+  io(
+    `OpenCode Computer Use setup ${result.changed ? "configured" : "already configured"} for ${flavor.toUpperCase()} (${scope}).`,
+  );
+  if (result.changed) io(`Configuration: ${result.file}`);
+  return { ...result, scope, flavor, detection };
+}
+
+export function printHelp() {
+  print(usage());
+}
+
+function isDevelopmentInstall(env) {
+  const initial = env.INIT_CWD ? resolve(env.INIT_CWD) : undefined;
+  return env.npm_lifecycle_event === "postinstall" && initial === PACKAGE_ROOT;
+}
+
+export async function main(argv = process.argv.slice(2), env = process.env, io = print) {
+  if (isDevelopmentInstall(env)) {
+    io("OpenCode Computer Use setup skipped for a package-development install.");
+    return 0;
+  }
+  if (env.OPENCODE_COMPUTER_USE_SKIP_SETUP === "1") {
+    io("OpenCode Computer Use setup skipped by OPENCODE_COMPUTER_USE_SKIP_SETUP.");
+    return 0;
+  }
+  let options;
+  try {
+    options = parseArguments(argv);
+  } catch (error) {
+    io(`[opencode-computer-use] ${error instanceof Error ? error.message : String(error)}`, "stderr");
+    io(usage(), "stderr");
+    return 2;
+  }
+  if (options.help) {
+    printHelp();
+    return 0;
+  }
+  return setup(options, env, io)
+    .then(() => 0)
+    .catch((error) => {
+      io(`[opencode-computer-use] Automatic setup was not changed: ${error instanceof Error ? error.message : String(error)}`, "stderr");
+      io(FALLBACK_INSTRUCTIONS, "stderr");
+      return 0;
+    });
+}
+
+function sameFile(left, right) {
+  try {
+    return realpathSync(left) === realpathSync(right);
+  } catch {
+    return resolve(left) === resolve(right);
+  }
+}
+
+const invokedPath = process.argv[1] ? resolve(process.argv[1]) : "";
+const scriptPath = fileURLToPath(import.meta.url);
+if (invokedPath && sameFile(invokedPath, scriptPath)) {
+  process.exitCode = await main();
+}

package/docs/index.html

@@ -61,7 +61,7 @@
           "name": "OpenCode Computer Use",
           "description": "A dual-generation OpenCode plugin for local desktop control through a persistent cua_repl JavaScript session.",
           "url": "https://opencode-computer-use.pages.dev/",
-          "softwareVersion": "0.1.0",
+          "softwareVersion": "0.1.1",
           "datePublished": "2026-09-25",
           "dateModified": "2026-09-25",
           "isAccessibleForFree": true,
@@ -456,7 +456,10 @@
 cd opencode-computer-use
 npm install</code></pre><button class="copy" type="button" data-copy="#clone">Copy</button></div>
           <p>For a published-package install, use:</p>
-          <div class="code"><pre><code id="npm-install">npm install @frontendxlab/opencode-computer-use</code></pre><button class="copy" type="button" data-copy="#npm-install">Copy</button></div>
+          <div class="code"><pre><code id="npm-install">npm install @frontendxlab/opencode-computer-use
+# pnpm install @frontendxlab/opencode-computer-use also works</code></pre><button class="copy" type="button" data-copy="#npm-install">Copy</button></div>
+          <p>The package postinstall step detects OpenCode 1 versus OpenCode2 and local versus global installation. It edits JSONC without discarding comments, avoids duplicate entries, and prints both manual formats when the choice is ambiguous. Run it explicitly with <code>npx opencode-computer-use-setup</code>, or add <code>--local</code>, <code>--global</code>, <code>--v1</code>, or <code>--v2</code> when you want to choose explicitly.</p>
+          <p>Recent pnpm releases can require explicit lifecycle-script approval. If pnpm reports <code>ERR_PNPM_IGNORED_BUILDS</code>, run <code>pnpm approve-builds @frontendxlab/opencode-computer-use</code> once, then rerun <code>pnpm install</code>. If scripts are disabled, run <code>pnpm exec opencode-computer-use-setup</code> manually.</p>
           <div class="tabs" role="tablist" aria-label="OpenCode generation">
             <button role="tab" id="tab-v1" aria-controls="panel-v1" aria-selected="true">OpenCode 1</button>
             <button role="tab" id="tab-v2" aria-controls="panel-v2" aria-selected="false" tabindex="-1">OpenCode2</button>
@@ -548,6 +551,12 @@ await chrome.getAXState({ textLimit: 12000 });</code></pre><button class="copy"
           <div class="code"><pre><code id="options-json">{
   "backend": "auto",
   "serverName": "cua_repl",
+  "safetyMode": "full",
+  "appAccess": {
+    "default": "allow",
+    "allow": [],
+    "deny": []
+  },
   "timeoutMs": 30000,
   "maxTextChars": 200000,
   "maxImageBytes": 2097152,
@@ -556,6 +565,8 @@ await chrome.getAXState({ textLimit: 12000 });</code></pre><button class="copy"
           <ul class="cards">
             <li><strong>backend</strong><span><code>auto</code>, <code>native</code>, or a fixed <code>custom</code> command.</span></li>
             <li><strong>serverName</strong><span>Rename the generated MCP server when a project needs isolation.</span></li>
+            <li><strong>safetyMode</strong><span><code>full</code> or <code>read-only</code>. Read-only blocks mutating CUA methods and changes MCP annotations.</span></li>
+            <li><strong>appAccess</strong><span>Optional exact-name and ID allow or deny rules, evaluated before native access.</span></li>
             <li><strong>timeoutMs</strong><span>Bounds JavaScript evaluation. A timeout resets the worker session.</span></li>
             <li><strong>maxTextChars</strong><span>Aggregate text budget for one tool result.</span></li>
             <li><strong>maxImageBytes</strong><span>Aggregate image budget for one tool result.</span></li>
@@ -601,7 +612,10 @@ nodeRepl.write(state);</code></pre><button class="copy" type="button" data-copy=
             <li><strong>No arbitrary shell</strong><span>The model-facing API does not expose <code>run_shell</code> or a host command escape.</span></li>
             <li><strong>Restricted VM</strong><span>Filesystem, process, fetch, dynamic import, code generation, and host built-ins are blocked.</span></li>
             <li><strong>Worker isolation</strong><span>CPU-bound JavaScript can be terminated without wedging the MCP server.</span></li>
-            <li><strong>Bounded transport</strong><span>Input frames, output text, images, content items, and native responses are bounded.</span></li>
+            <li><strong>Read-only mode</strong><span>An opt-in safety profile blocks clicks, keys, text, scroll, drags, and secondary actions before native execution.</span></li>
+            <li><strong>App policy</strong><span>Exact-name and ID allow or deny rules provide adapter-level defense in depth.</span></li>
+            <li><strong>Bounded transport</strong><span>Input frames, output text, images, content items, app bindings, and native responses are bounded.</span></li>
+            <li><strong>Lifecycle cleanup</strong><span>Timeouts send native cancellation, and shutdown sends a best-effort turn-ended notification.</span></li>
             <li><strong>Approval preserving</strong><span>Consequential actions still pass through OpenCode and OS permission boundaries.</span></li>
             <li><strong>Safe defaults</strong><span>Global pointer fallback is disabled until explicitly enabled.</span></li>
           </ul>
@@ -635,7 +649,7 @@ nodeRepl.write(state);</code></pre><button class="copy" type="button" data-copy=
         <strong>Surface map</strong>
         <p>Plugin: <code>opencode-computer-use</code><br>MCP: <code>cua_repl</code><br>Tools: <code>js</code>, <code>js_reset</code></p>
         <strong>Default policy</strong>
-        <p>Local stdio only. Global pointer fallback off. Native OS permissions enforced.</p>
+        <p>Local stdio only. Global pointer fallback off. Native OS permissions enforced. Read-only and app policies are available as adapter defense in depth.</p>
         <strong>Updated</strong>
         <p>Published September 25, 2026. Updated September 25, 2026.</p>
         <strong>WebMCP</strong>

package/docs/llms-full.txt

@@ -68,18 +68,29 @@ state.
 5. Options
 backend (default auto: auto, native, or custom); command (required for
 custom: fixed native MCP executable plus argv, no shell syntax); serverName
-(default cua_repl); override (default false); timeoutMs (default 30000);
-disabled (default false); maxTextChars (default 200000); maxImageBytes
-(default 2097152); allowGlobalPointerFallbacks (default false, off because
-it moves the real pointer and changes focus; enable only for an explicit
-desktop automation test where that input is intended). The proxy also reads
-matching OPENCODE_COMPUTER_USE_* environment variables. Custom commands
-must implement the native MCP operations used by cua: initialize,
-tools/list, tools/call, and notifications.
+(default cua_repl); override (default false); safetyMode (default full, or
+read-only to block mutating CUA methods and advertise read-only annotations);
+appAccess (default allow all, with optional exact-name and ID allow/deny
+rules); timeoutMs (default 30000); disabled (default false); maxTextChars
+(default 200000); maxImageBytes (default 2097152);
+allowGlobalPointerFallbacks (default false, off because it moves the real
+pointer and changes focus; enable only for an explicit desktop automation
+test where that input is intended). The proxy also reads matching
+OPENCODE_COMPUTER_USE_* environment variables. Custom commands must implement
+the native MCP operations used by cua: initialize, tools/list, tools/call,
+and notifications.
 
 6. Install
 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
+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.
 OpenCode 1 (opencode.json or opencode.jsonc, plugin list):
   { "$schema": "https://opencode.ai/config.json",
     "plugin": [["@frontendxlab/opencode-computer-use", { "backend": "auto" }]] }
@@ -110,19 +121,24 @@ desktop validation.
 
 8. Safety
 High-privilege desktop-control surface. The js tool is marked conservatively
-as mutating. Keep OpenCode approval prompts enabled for consequential
-actions (sending, deleting, purchasing, 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:
+as mutating in full mode and read-only in read-only mode. The adapter also
+bounds app bindings, sends native cancellation on timeouts, and sends a
+best-effort turn-ended notification during shutdown. Keep OpenCode approval
+prompts enabled for consequential actions (sending, deleting, purchasing,
+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:
   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,
-  run opencode mcp list, avoid double registration.
+- 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.
 - 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.

package/docs/llms.txt

@@ -24,7 +24,9 @@
 - 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.
+- 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.
 - 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.

package/lib/json-line-peer.mjs

@@ -28,6 +28,7 @@ export class JsonLinePeer extends EventEmitter {
     this.pending = new Map();
     this.buffer = "";
     this.stderr = "";
+    this.closeError = null;
     this.closed = false;
     this.exited = false;
     this.terminationStarted = false;
@@ -93,6 +94,7 @@ export class JsonLinePeer extends EventEmitter {
   #close(error, terminate = false) {
     if (!this.closed) {
       this.closed = true;
+      this.closeError = error;
       for (const pending of this.pending.values()) {
         clearTimeout(pending.timer);
         pending.reject(error);
@@ -100,7 +102,7 @@ export class JsonLinePeer extends EventEmitter {
       this.pending.clear();
       this.emit("close", error);
     }
-    if (terminate) void this.#terminateChild();
+    if (terminate) void this.#terminateChild(false);
   }
 
   #killChild(force) {
@@ -135,26 +137,44 @@ export class JsonLinePeer extends EventEmitter {
     }
   }
 
-  #terminateChild() {
+  #terminateChild(graceful = true) {
     if (this.terminationStarted) return this.exitPromise;
     this.terminationStarted = true;
     try { this.child.stdin.end(); } catch {}
-    this.#killChild(false);
-    const timer = setTimeout(() => this.#killChild(true), 1_000);
-    timer.unref();
-    return this.exitPromise.finally(() => clearTimeout(timer));
+    if (!graceful) this.#killChild(false);
+    const gracefulTimer = graceful ? setTimeout(() => this.#killChild(false), 100) : undefined;
+    const forceTimer = setTimeout(() => this.#killChild(true), 1_000);
+    gracefulTimer?.unref();
+    forceTimer.unref();
+    return this.exitPromise.finally(() => {
+      if (gracefulTimer) clearTimeout(gracefulTimer);
+      clearTimeout(forceTimer);
+    });
   }
 
   request(method, params = {}, timeoutMs = DEFAULT_TIMEOUT_MS) {
-    if (this.closed) return Promise.reject(new Error("native MCP is closed"));
+    if (this.closed) {
+      const detail = this.closeError ? `: ${safeNativeErrorMessage(this.closeError)}` : "";
+      return Promise.reject(new Error(`native MCP is closed${detail}; restart the MCP server before trying again`));
+    }
     const id = this.nextId++;
     return new Promise((resolve, reject) => {
-      const timer = timeoutMs > 0
-        ? setTimeout(() => { this.pending.delete(String(id)); reject(new Error(`native MCP ${method} timed out after ${timeoutMs} ms`)); }, timeoutMs)
-        : undefined;
+      const cancelTimedOutRequest = () => {
+        const key = String(id);
+        if (!this.pending.has(key)) return;
+        this.pending.delete(key);
+        try {
+          this.notify("notifications/cancelled", { requestId: id, reason: "timeout" });
+        } catch {
+          // The native process may already be closing; the timeout remains authoritative.
+        }
+        reject(new Error(`native MCP ${method} timed out after ${timeoutMs} ms; the native action may still be settling`));
+      };
+      const timer = timeoutMs > 0 ? setTimeout(cancelTimedOutRequest, timeoutMs) : undefined;
       this.pending.set(String(id), { resolve, reject, timer });
       this.child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", id, method, params })}\n`, (error) => {
         if (!error) return;
+        if (!this.pending.has(String(id))) return;
         if (timer) clearTimeout(timer);
         this.pending.delete(String(id));
         reject(error);
@@ -163,7 +183,33 @@ export class JsonLinePeer extends EventEmitter {
   }
 
   notify(method, params = {}) {
-    if (!this.closed) this.child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", method, params })}\n`);
+    if (this.closed) return false;
+    try {
+      this.child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", method, params })}\n`);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async notifyAsync(method, params = {}, timeoutMs = 250) {
+    if (this.closed) return false;
+    return new Promise((resolve) => {
+      let settled = false;
+      let timer;
+      const finish = (delivered) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        resolve(delivered);
+      };
+      timer = setTimeout(() => finish(false), timeoutMs);
+      try {
+        this.child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", method, params })}\n`, (error) => finish(!error));
+      } catch {
+        finish(false);
+      }
+    });
   }
 
   async initialize() {

package/lib/options.js

@@ -1,5 +1,8 @@
 const BACKENDS = new Set(["auto", "native", "custom"]);
+const SAFETY_MODES = new Set(["full", "read-only"]);
 const DEFAULT_SERVER_NAME = "cua_repl";
+const MAX_APP_RULES = 256;
+const MAX_APP_RULE_LENGTH = 256;
 
 function isRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -24,6 +27,36 @@ function commandOption(value) {
   return [...value];
 }
 
+function appRuleList(value, name) {
+  if (value === undefined) return [];
+  if (!Array.isArray(value) || value.length > MAX_APP_RULES) {
+    throw new Error(`${name} must be an array with at most ${MAX_APP_RULES} entries`);
+  }
+  const rules = [];
+  for (const item of value) {
+    if (typeof item !== "string" || !item.trim() || item.length > MAX_APP_RULE_LENGTH) {
+      throw new Error(`${name} entries must be non-empty strings no longer than ${MAX_APP_RULE_LENGTH} characters`);
+    }
+    const rule = item.trim();
+    if (!rules.includes(rule)) rules.push(rule);
+  }
+  return rules;
+}
+
+function appAccessOption(value) {
+  if (value === undefined) return { default: "allow", allow: [], deny: [] };
+  if (!isRecord(value)) throw new Error("appAccess must be an object");
+  const defaultAccess = value.default === undefined ? "allow" : value.default;
+  if (typeof defaultAccess !== "string" || !["allow", "deny"].includes(defaultAccess.trim())) {
+    throw new Error("appAccess.default must be allow or deny");
+  }
+  return {
+    default: defaultAccess.trim(),
+    allow: appRuleList(value.allow, "appAccess.allow"),
+    deny: appRuleList(value.deny, "appAccess.deny"),
+  };
+}
+
 function serverNameOption(value) {
   const name = stringOption(value, DEFAULT_SERVER_NAME);
   if (!/^[A-Za-z0-9_-]{1,64}$/.test(name)) {
@@ -43,6 +76,10 @@ export function normalizeOptions(input = {}) {
   if (backend === "custom" && !command) {
     throw new Error("backend 'custom' requires a non-empty command array");
   }
+  const safetyMode = stringOption(raw.safetyMode, "full");
+  if (!SAFETY_MODES.has(safetyMode)) {
+    throw new Error(`safetyMode must be one of: ${[...SAFETY_MODES].join(", ")}`);
+  }
 
   return {
     backend,
@@ -51,6 +88,8 @@ export function normalizeOptions(input = {}) {
     allowGlobalPointerFallbacks: booleanOption(raw.allowGlobalPointerFallbacks, false),
     override: booleanOption(raw.override, false),
     serverName: serverNameOption(raw.serverName),
+    safetyMode,
+    appAccess: appAccessOption(raw.appAccess),
     timeoutMs: boundedNumber(raw.timeoutMs, 30_000, 1_000, 300_000),
     maxTextChars: boundedNumber(raw.maxTextChars, 200_000, 1_000, 2_000_000),
     maxImageBytes: boundedNumber(raw.maxImageBytes, 2 * 1024 * 1024, 16_384, 16 * 1024 * 1024),
@@ -62,6 +101,8 @@ export function optionsToEnvironment(options) {
   const environment = {
     OPENCODE_COMPUTER_USE_BACKEND: normalized.backend,
     OPENCODE_COMPUTER_USE_SERVER_NAME: normalized.serverName,
+    OPENCODE_COMPUTER_USE_SAFETY_MODE: normalized.safetyMode,
+    OPENCODE_COMPUTER_USE_APP_ACCESS: JSON.stringify(normalized.appAccess),
     OPENCODE_COMPUTER_USE_TIMEOUT_MS: String(normalized.timeoutMs),
     OPENCODE_COMPUTER_USE_MAX_TEXT_CHARS: String(normalized.maxTextChars),
     OPENCODE_COMPUTER_USE_MAX_IMAGE_BYTES: String(normalized.maxImageBytes),
@@ -88,11 +129,22 @@ export function optionsFromEnvironment(environment = process.env) {
     }
   }
 
+  let appAccess;
+  if (environment.OPENCODE_COMPUTER_USE_APP_ACCESS) {
+    try {
+      appAccess = JSON.parse(environment.OPENCODE_COMPUTER_USE_APP_ACCESS);
+    } catch {
+      throw new Error("OPENCODE_COMPUTER_USE_APP_ACCESS must be valid JSON");
+    }
+  }
+
   return normalizeOptions({
     backend: environment.OPENCODE_COMPUTER_USE_BACKEND,
     command,
     allowGlobalPointerFallbacks: environment.OPEN_COMPUTER_USE_ALLOW_GLOBAL_POINTER_FALLBACKS === "1",
     serverName: environment.OPENCODE_COMPUTER_USE_SERVER_NAME,
+    safetyMode: environment.OPENCODE_COMPUTER_USE_SAFETY_MODE,
+    appAccess,
     timeoutMs: Number(environment.OPENCODE_COMPUTER_USE_TIMEOUT_MS),
     maxTextChars: Number(environment.OPENCODE_COMPUTER_USE_MAX_TEXT_CHARS),
     maxImageBytes: Number(environment.OPENCODE_COMPUTER_USE_MAX_IMAGE_BYTES),
@@ -105,6 +157,8 @@ export const defaults = Object.freeze({
   allowGlobalPointerFallbacks: false,
   override: false,
   serverName: DEFAULT_SERVER_NAME,
+  safetyMode: "full",
+  appAccess: { default: "allow", allow: [], deny: [] },
   timeoutMs: 30_000,
   maxTextChars: 200_000,
   maxImageBytes: 2 * 1024 * 1024,

package/lib/repl-kernel.mjs

@@ -14,7 +14,12 @@ const native = {
     });
   },
 };
-const session = new PersistentJavaScriptSession({ native, limits: workerData });
+const session = new PersistentJavaScriptSession({
+  native,
+  limits: workerData,
+  safetyMode: workerData.safetyMode,
+  appAccess: workerData.appAccess,
+});
 
 parentPort.on("message", async message => {
   if (message.type === "native_response") {

package/lib/repl.mjs

@@ -30,8 +30,11 @@ const SERVER_INSTRUCTIONS = `UI automation through a persistent JavaScript REPL
 
 On the first call after startup or js_reset, bind the requested app with await cua.getApp("Example App"), or call await cua.getState() only when an app inventory is actually needed. App bindings persist across js calls. Batch deterministic actions and the resulting getAXState() in one js call, then verify the returned UI state. Use nodeRepl.write(value) for additional text and await nodeRepl.emitImage(image) for additional images. Ask the user before destructive or externally visible actions such as sending, deleting, or purchasing.`;
 
-function jsDescription(timeoutMs = DEFAULT_TIMEOUT_MS) {
-  return `Run JavaScript in a persistent Node.js REPL with top-level await and an initialized asynchronous cua API for Open Computer Use. Use this for all desktop interactions. Bind an app with let app = await cua.getApp("Example App"); then call await app.click(...), await app.typeText(...), and await app.getAXState(). Top-level bindings persist until js_reset, so prefer top-level var for names that may be assigned again. Batch deterministic actions and the resulting state read in one call to reduce round trips. Use nodeRepl.write(value) for extra text and await nodeRepl.emitImage(image) for extra images. If timeout_ms is omitted, execution times out after ${timeoutMs} ms.`;
+function jsDescription(timeoutMs = DEFAULT_TIMEOUT_MS, safetyMode = "full") {
+  const safetyNote = safetyMode === "read-only"
+    ? " This session is read-only; mutating CUA methods are disabled."
+    : "";
+  return `Run JavaScript in a persistent Node.js REPL with top-level await and an initialized asynchronous cua API for Open Computer Use. Use this for all desktop interactions. Bind an app with let app = await cua.getApp("Example App"); then call await app.click(...), await app.typeText(...), and await app.getAXState(). Top-level bindings persist until js_reset, so prefer top-level var for names that may be assigned again. Batch deterministic actions and the resulting state read in one call to reduce round trips. Use nodeRepl.write(value) for extra text and await nodeRepl.emitImage(image) for extra images. If timeout_ms is omitted, execution times out after ${timeoutMs} ms.${safetyNote}`;
 }
 
 const RESET_DESCRIPTION = `Reset the persistent Open Computer Use JavaScript session and discard all bindings created by prior js calls. The next js call starts with a freshly initialized cua API. This does not close native apps or erase their state.`;
@@ -217,9 +220,11 @@ export function createCuaApi(native, activeOutput, assertActive = () => {}) {
 
 
 export class PersistentJavaScriptSession {
-  constructor({ native, limits = {} }) {
+  constructor({ native, limits = {}, safetyMode = "full", appAccess = {} }) {
     this.native = native;
     this.limits = outputLimits(limits);
+    this.safetyMode = safetyMode;
+    this.appAccess = appAccess;
     this.active = null;
     this.reset();
   }
@@ -295,6 +300,7 @@ export class PersistentJavaScriptSession {
       isActive,
       schedule,
       cancel,
+      { safetyMode: this.safetyMode, appAccess: this.appAccess },
     );
     this.nodeRepl = this.context.nodeRepl;
     this.cua = this.context.cua;
@@ -341,9 +347,12 @@ export class PersistentJavaScriptSession {
 // loop can be terminated without hanging the MCP transport. Native tool calls
 // are brokered back to the parent and still execute serially in the native MCP.
 export class WorkerJavaScriptSession {
-  constructor({ native, limits = {} }) {
+  constructor({ native, limits = {}, safetyMode = "full", appAccess = {} }) {
     this.native = native;
     this.limits = outputLimits(limits);
+    this.safetyMode = safetyMode;
+    this.appAccess = appAccess;
+    this.workerData = { ...this.limits, safetyMode: this.safetyMode, appAccess: this.appAccess };
     this.nextId = 1;
     this.activeRequestId = null;
     this.pending = new Map();
@@ -354,7 +363,7 @@ export class WorkerJavaScriptSession {
   #start() {
     const worker = new Worker(new URL("./repl-kernel.mjs", import.meta.url), {
       execArgv: ["--experimental-repl-await"],
-      workerData: this.limits,
+      workerData: this.workerData,
     });
     this.worker = worker;
     worker.on("message", message => void this.#onMessage(worker, message));
@@ -491,11 +500,18 @@ export async function runServer({ command, args }) {
   let shuttingDown;
   let stopping = false;
   const send = (message) => process.stdout.write(`${JSON.stringify(message)}\n`);
-  const shutdown = () => {
+  const shutdown = (reason = "server_shutdown") => {
     if (shuttingDown) return shuttingDown;
     stopping = true;
     const closeSession = session ? session.close() : Promise.resolve();
-    shuttingDown = closeSession.catch(() => {}).finally(() => native.close());
+    shuttingDown = closeSession.catch(() => {}).then(async () => {
+      try {
+        await native.notifyAsync("notifications/turn-ended", { reason });
+      } catch {
+        // The native process may already be closing; local cleanup still continues.
+      }
+      return native.close().catch(() => {});
+    });
     return shuttingDown;
   };
   const enqueue = (line) => {
@@ -505,7 +521,7 @@ export async function runServer({ command, args }) {
   const rejectOversizedInput = () => {
     buffer = "";
     send({ jsonrpc: "2.0", id: null, error: { code: -32600, message: "Request frame exceeded the input size limit" } });
-    void shutdown();
+    void shutdown("input_limit");
   };
   const onInput = (chunk) => {
     if (stopping) return;
@@ -527,15 +543,20 @@ export async function runServer({ command, args }) {
 
   try {
     await native.initialize();
-    session = new WorkerJavaScriptSession({ native, limits: options });
+    session = new WorkerJavaScriptSession({
+      native,
+      limits: options,
+      safetyMode: options.safetyMode,
+      appAccess: options.appAccess,
+    });
     process.stdin.setEncoding("utf8");
     process.stdin.on("data", onInput);
     process.stdin.on("error", error => {
       console.error(safeErrorMessage(error));
-      void shutdown();
+      void shutdown("stdin_error");
     });
   } catch (error) {
-    await shutdown();
+    await shutdown("startup_error");
     throw error;
   }
 
@@ -565,7 +586,7 @@ export async function runServer({ command, args }) {
         });
       }
       if (method === "ping") return send({ jsonrpc: "2.0", id, result: {} });
-      if (method === "tools/list") return send({ jsonrpc: "2.0", id, result: { tools: toolDefinitions(options.timeoutMs) } });
+      if (method === "tools/list") return send({ jsonrpc: "2.0", id, result: { tools: toolDefinitions(options.timeoutMs, options) } });
       if (method === "tools/call") {
         if (!isJsonRecord(params) || typeof params.name !== "string") throw new Error("tools/call requires a tool name");
         if (params.arguments !== undefined && !isJsonRecord(params.arguments)) throw new Error("tools/call arguments must be an object");
@@ -582,7 +603,12 @@ export async function runServer({ command, args }) {
           if (typeof code !== "string" || code.length > MAX_CODE_CHARS) {
             throw new Error(`js code must be a string no longer than ${MAX_CODE_CHARS} characters`);
           }
+          const title = params.arguments?.title;
+          if (title !== undefined && (typeof title !== "string" || !title.trim() || title.length > 80)) {
+            throw new Error("js title must be a non-empty string no longer than 80 characters");
+          }
           const result = boundToolResult(await session.run(code, timeoutMs), options);
+          if (title) result._meta = { ...(result._meta || {}), title: title.trim() };
           return send({ jsonrpc: "2.0", id, result });
         }
         throw new Error(`Unsupported tool: ${params.name}`);
@@ -595,17 +621,20 @@ export async function runServer({ command, args }) {
 
   const shutdownSignals = process.platform === "win32" ? ["SIGINT", "SIGTERM"] : ["SIGINT", "SIGTERM", "SIGHUP"];
   for (const signal of shutdownSignals) {
-    process.on(signal, () => { void shutdown().finally(() => process.exit(0)); });
+    process.on(signal, () => { void shutdown("signal").finally(() => process.exit(0)); });
   }
-  process.stdin.on("end", () => { void requestQueue.finally(shutdown); });
+  process.stdin.on("end", () => { void requestQueue.finally(() => shutdown("stdin_closed")); });
 }
 
-export function toolDefinitions(defaultTimeoutMs = DEFAULT_TIMEOUT_MS) {
+export function toolDefinitions(defaultTimeoutMs = DEFAULT_TIMEOUT_MS, { safetyMode = "full" } = {}) {
   const requestedTimeout = Number.isFinite(defaultTimeoutMs) ? defaultTimeoutMs : DEFAULT_TIMEOUT_MS;
   const timeoutMs = Math.min(Math.max(requestedTimeout, 1_000), MAX_TIMEOUT_MS);
-  const annotations = { destructiveHint: true, openWorldHint: true, readOnlyHint: false };
+  const readOnly = safetyMode === "read-only";
+  const annotations = readOnly
+    ? { destructiveHint: false, openWorldHint: false, readOnlyHint: true }
+    : { destructiveHint: true, openWorldHint: true, readOnlyHint: false };
   return [
-    { name: "js", description: jsDescription(timeoutMs), annotations, inputSchema: { type: "object", additionalProperties: false, properties: { code: { type: "string", minLength: 1, maxLength: MAX_CODE_CHARS, description: "JavaScript source to execute with top-level await and the initialized cua API." }, timeout_ms: { type: "integer", minimum: 1, maximum: MAX_TIMEOUT_MS, description: `Optional timeout in milliseconds. Defaults to ${timeoutMs} and is capped at 300000.` }, title: { type: "string", minLength: 1, maxLength: 80, description: "Short user-facing description of what this code is doing." } }, required: ["code"] } },
+    { name: "js", description: jsDescription(timeoutMs, safetyMode), annotations, inputSchema: { type: "object", additionalProperties: false, properties: { code: { type: "string", minLength: 1, maxLength: MAX_CODE_CHARS, description: "JavaScript source to execute with top-level await and the initialized cua API." }, timeout_ms: { type: "integer", minimum: 1, maximum: MAX_TIMEOUT_MS, description: `Optional timeout in milliseconds. Defaults to ${timeoutMs} and is capped at 300000.` }, title: { type: "string", minLength: 1, maxLength: 80, description: "Short user-facing description of what this code is doing." } }, required: ["code"] } },
     { name: "js_reset", description: RESET_DESCRIPTION, annotations: { destructiveHint: false, openWorldHint: false, readOnlyHint: true, idempotentHint: true }, inputSchema: { type: "object", additionalProperties: false, properties: {} } },
   ];
 }

package/lib/sandbox.mjs

@@ -1,6 +1,44 @@
 import { runInContext } from "node:vm";
 
 const MAX_FRAME_BYTES = 32 * 1024 * 1024;
+const MAX_APP_BINDINGS = 128;
+const MUTATING_APP_METHODS = new Set([
+  "click",
+  "drag",
+  "pressKey",
+  "scroll",
+  "setValue",
+  "typeText",
+  "performSecondaryAction",
+]);
+
+function normalizedAppAccess(value) {
+  const policy = value && typeof value === "object" ? value : {};
+  const defaultAccess = policy.default === "deny" ? "deny" : "allow";
+  const normalizeRules = (rules) => Array.isArray(rules)
+    ? rules.filter((rule) => typeof rule === "string" && rule.trim()).map((rule) => rule.trim().toLowerCase())
+    : [];
+  return {
+    default: defaultAccess,
+    allow: new Set(normalizeRules(policy.allow)),
+    deny: new Set(normalizeRules(policy.deny)),
+  };
+}
+
+function appMatches(app, rules) {
+  if (!app || typeof app !== "object") return false;
+  return [app.id, app.bundleId, app.name, app.displayName]
+    .filter((value) => typeof value === "string" && value.trim())
+    .some((value) => rules.has(value.trim().toLowerCase()));
+}
+
+function appNameMatches(app, name) {
+  if (!app || typeof app !== "object") return false;
+  const expected = String(name).trim().toLowerCase();
+  return [app.id, app.bundleId, app.name, app.displayName]
+    .filter((value) => typeof value === "string" && value.trim())
+    .some((value) => value.trim().toLowerCase() === expected);
+}
 
 const SANDBOX_FACTORY_SOURCE = String.raw`
 ((dispatch, write, emitImage, schedule, cancel) => {
@@ -237,22 +275,56 @@ function encodeSandboxResult(value) {
   return payload;
 }
 
-export function createSandboxBridge(api, context, activeOutput, isActive, schedule, cancel) {
+export function createSandboxBridge(
+  api,
+  context,
+  activeOutput,
+  isActive,
+  schedule,
+  cancel,
+  { safetyMode = "full", appAccess = {} } = {},
+) {
   const bindings = new Map();
+  const accessPolicy = normalizedAppAccess(appAccess);
   let nextBinding = 1;
+  const isReadOnly = safetyMode === "read-only";
+  const appIsAllowed = (app) => {
+    if (appMatches(app, accessPolicy.deny)) return false;
+    if (accessPolicy.allow.size > 0) return appMatches(app, accessPolicy.allow);
+    return accessPolicy.default === "allow";
+  };
+  const assertNamedAppAllowed = async (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)) : [];
+    if (matches.length > 0) {
+      if (matches.some((app) => !appIsAllowed(app))) {
+        throw new Error(`app access denied by policy: ${name}`);
+      }
+      return;
+    }
+    if (!appIsAllowed({ id: name, displayName: name })) {
+      throw new Error(`app access denied by policy: ${name}`);
+    }
+  };
+  const filterApps = (apps) => Array.isArray(apps) ? apps.filter(appIsAllowed) : [];
   const dispatch = async (method, args) => {
     try {
       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: state.apps });
+        return encodeSandboxResult({ apps: filterApps(state.apps) });
       }
-      if (method === "listApps") return encodeSandboxResult(await api.listApps({ emit: false }));
+      if (method === "listApps") return encodeSandboxResult(filterApps(await api.listApps({ emit: false })));
       if (method === "getApp") {
         const app = args[0];
         if (typeof app !== "string" || !app.trim()) {
           throw new Error("cua.getApp expects a non-empty app name or bundle ID");
         }
+        await assertNamedAppAllowed(app);
+        if (bindings.size >= MAX_APP_BINDINGS) {
+          throw new Error(`CUA app binding limit reached (${MAX_APP_BINDINGS}); call js_reset`);
+        }
         const binding = await api.getApp(app);
         const token = `app-${nextBinding++}`;
         bindings.set(token, binding);
@@ -263,10 +335,14 @@ export function createSandboxBridge(api, context, activeOutput, isActive, schedu
         return encodeSandboxResult(undefined);
       }
       if (method.startsWith("app:")) {
+        const methodName = method.slice(4);
+        if (isReadOnly && MUTATING_APP_METHODS.has(methodName)) {
+          throw new Error(`mutating CUA method disabled in read-only safety mode: ${methodName}`);
+        }
         const [token, ...callArgs] = args;
         const binding = bindings.get(token);
         if (!binding) throw new Error("unknown CUA app binding");
-        const result = await binding[method.slice(4)](...callArgs);
+        const result = await binding[methodName](...callArgs);
         return encodeSandboxResult(result);
       }
       throw new Error(`unknown sandbox method: ${method}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontendxlab/opencode-computer-use",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "A dual OpenCode and OpenCode2 plugin for local cross-platform desktop control.",
   "license": "MIT",
   "repository": {
@@ -28,7 +28,8 @@
     "./server": "./index.js"
   },
   "bin": {
-    "opencode-computer-use-repl": "bin/opencode-computer-use-repl.js"
+    "opencode-computer-use-repl": "bin/opencode-computer-use-repl.js",
+    "opencode-computer-use-setup": "bin/opencode-computer-use-setup.js"
   },
   "files": [
     "bin/",
@@ -42,16 +43,20 @@
   ],
   "engines": {
     "node": ">=18",
-    "opencode": ">=1.18.29"
+    "opencode": ">=0.0.0-beta-18684"
   },
   "scripts": {
-    "lint": "node --check index.js && node --check bin/opencode-computer-use-repl.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",
+    "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 -e \"JSON.parse(require('fs').readFileSync('package.json','utf8'))\"",
+    "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'))\"",
     "prepublishOnly": "npm run lint && npm test"
   },
   "optionalDependencies": {
     "open-computer-use": "0.3.5"
   },
-  "sideEffects": false
+  "sideEffects": false,
+  "dependencies": {
+    "jsonc-parser": "^3.3.1"
+  }
 }