@frontendxlab/opencode-computer-use 0.1.0 → 0.1.1

package/README.md

@@ -141,12 +141,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 +263,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,6 +16,11 @@ 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.
 

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,
@@ -548,6 +548,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 +562,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 +609,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 +646,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,14 +68,17 @@ 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:
@@ -110,13 +113,15 @@ 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
 

package/docs/llms.txt

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

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.1",
   "description": "A dual OpenCode and OpenCode2 plugin for local cross-platform desktop control.",
   "license": "MIT",
   "repository": {