moondesk 0.9.3 → 0.9.4

package/README.md

@@ -34,7 +34,7 @@ No reverse engineering. No API key. No separate agent service.
 - **Local file tools** — read, search, write, edit, and delete inside a workspace.
 - **Shell commands** — run short commands or start background jobs with polling, preserved output, and cancellation.
 - **Multiple workspaces** — serve several projects from one MoonDesk process, each with its own secret MCP URL.
-- **Browser control** — connect ChatGPT to supported Chromium browsers through `chrome-devtools-mcp`.
+- **Lazy browser control** — a stable `browser_command` + `view_page` surface backed by a pinned Chrome DevTools runtime. Selecting Browser/Both does not launch Chrome; the shared browser session starts only on first use.
 - **Read-only mode** — expose only safe local read tools when mutation is unnecessary.
 - **Cross-platform** — Windows, macOS, and Linux.
 - **Native binary distribution** — install with npm; MoonDesk downloads and verifies the matching release binary on first run.
@@ -44,7 +44,7 @@ No reverse engineering. No API key. No separate agent service.
 
 ### 1. Install
 
-Node.js 18 or newer is required.
+MoonDesk requires Node.js `^20.19.0 || ^22.12.0 || >=23`, matching the pinned browser runtime. Node 21 and Node 22.0-22.11 are not supported.
 
 ```bash
 npm install -g moondesk
@@ -121,7 +121,7 @@ Each workspace keeps its own file boundary, command jobs, retained output, histo
 
 Use `[w] Workspaces` to add, rename, inspect, copy, rotate, or remove projects. On Windows, `[b] Explorer` opens the native Explorer folder picker for adding a workspace; `[a] Path` remains available for manual path entry. Launching `moondesk` from another project while a host is already running can attach that directory to the existing host instead of starting another server.
 
-Browser control is shared by the host, so workspaces using browser mode control the same selected browser/DevTools bridge.
+Browser control is shared by the host. Workspaces using browser mode share one lazy **isolated agent browser** session that starts only on first use. It never attaches to or reuses your personal browser profile, cookies, or logged-in sessions.
 
 Because every workspace shares this host and public tunnel, stopping MoonDesk disconnects all active workspace connectors. Pressing `q` or `Ctrl+C` in the live dashboard therefore opens a shutdown confirmation instead of stopping the host immediately; `Enter` confirms and `Esc` keeps MoonDesk running.
 
@@ -146,9 +146,30 @@ In `multi-tools` mode MoonDesk exposes 12 local tools:
 
 Use `run_command` for short work. Use `start_command` + `poll_command` for builds, tests, package installs, dev servers, and other long-running commands. Polls long-wait by default and report elapsed, idle, and timeout timing so agents can avoid rapid blind polling.
 
-`read-only` mode exposes only the local guide/read tools.
+`read-only` mode removes local mutation/shell tools. In Browser/Both mode it still permits bounded browser inspection, while state-changing browser commands and browser file-output flags remain blocked.
 
-Browser mode can add DevTools tools depending on the selected browser and environment.
+Browser mode has a stable tool catalog instead of forwarding the full Chrome DevTools MCP schema:
+
+| Browser tool | Purpose |
+| --- | --- |
+| `browser_command` | Run one browser/DevTools CLI operation in the shared lazy session |
+| `view_page` | Attach the current rendered page directly to the model as bounded image content |
+
+For one-off actions, use `browser_command`. Navigate first, set the target viewport, then run `take_snapshot` before element interactions and use UIDs from the latest snapshot. Use `resize_page` for ordinary desktop window sizes. For exact tablet/mobile QA, use `emulate --viewport=390x844x1,mobile,touch` (or another target size); Chromium can clamp very narrow desktop windows, and viewport emulation can recreate the page context, so take a fresh snapshot afterward. For visual layout/rendering checks, use `view_page`; text/accessibility snapshots do not replace pixel inspection.
+
+The same `moondesk` CLI also has a `browser` subcommand for deterministic scripted flows in `Both` mode:
+
+```bash
+moondesk browser skill
+moondesk browser navigate_page --url=http://localhost:3000
+moondesk browser emulate --viewport=390x844x1,mobile,touch
+moondesk browser take_snapshot
+moondesk browser list_console_messages
+```
+
+The `browser` subcommand is handled by MoonDesk itself and acts as a lightweight authenticated localhost client to the **running MoonDesk host**. It does not launch a separate browser runtime, so separate shell commands, MCP `browser_command`, and MCP `view_page` all operate on the same host-owned agent-browser session. MoonDesk directly owns the pinned `chrome-devtools-mcp` stdio process tree and its isolated Chromium child instead of relying on the upstream detached CLI daemon. Each agent-browser session uses an isolated temporary profile, so personal cookies/logins are never inherited and browser state is discarded when that session ends. Sensitive network headers are redacted, CrUX URL lookups and usage statistics are disabled, local-file navigation is blocked, and a lost runtime is invalidated so the next browser operation starts a fresh isolated session without replaying the ambiguous failed action.
+
+The browser runtime is intentionally pinned to `chrome-devtools-mcp@1.7.0`. Version `1.8.0` changed required CLI argument shapes for commands MoonDesk currently invokes with the 1.7 contract, so upgrading the pin requires an explicit command-contract migration and the full browser regression matrix rather than a blind dependency bump.
 
 ## Workspace security
 
@@ -192,7 +213,7 @@ On macOS Terminal.app, MoonDesk can manage a dedicated terminal profile. Set `MO
 | Tunnel | ngrok |
 | MCP server | Custom implementation |
 | MCP protocol | `2025-11-25` |
-| Browser bridge | `chrome-devtools-mcp` |
+| Browser runtime | pinned `chrome-devtools-mcp@1.7.0` stdio child owned by MoonDesk, started lazily |
 | Distribution | npm + native binaries |
 
 ## Contributing

package/npm/install-binary.js

@@ -297,7 +297,7 @@ async function ensureBinary(options = {}) {
   const fetchImpl = options.fetchImpl ?? globalThis.fetch;
 
   if (typeof fetchImpl !== "function") {
-    throw new Error("MoonDesk requires Node.js 18 or newer so the native binary can be downloaded securely");
+    throw new Error("MoonDesk requires Node.js ^20.19.0 || ^22.12.0 || >=23 so the native binary can be downloaded securely");
   }
 
   const binaryPath = path.join(installDir, targetInfo.executableName);

package/npm/moondesk.js

@@ -21,6 +21,18 @@ const {
   writePostUpdateNotice,
 } = require("./update-manager");
 
+const SUPPORTED_NODE_RANGE = "^20.19.0 || ^22.12.0 || >=23";
+
+function isSupportedNodeVersion(version = process.versions.node) {
+  const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(String(version));
+  if (!match) return false;
+  const major = Number(match[1]);
+  const minor = Number(match[2]);
+  if (major === 20) return minor >= 19;
+  if (major === 22) return minor >= 12;
+  return major >= 23;
+}
+
 function cleanManagedUpdateEnv(source = process.env) {
   const env = { ...source };
   delete env.MOONDESK_NPM_MANAGED;
@@ -109,6 +121,13 @@ function nativeStartFailureHints(error, binaryPath, options = {}) {
 
 async function orchestrate(options = {}) {
   const logger = options.logger ?? console;
+  const nodeVersion = options.nodeVersion ?? process.versions.node;
+  if (!isSupportedNodeVersion(nodeVersion)) {
+    logger.error(
+      `MoonDesk requires Node.js ${SUPPORTED_NODE_RANGE} because the pinned browser runtime does not support Node.js ${nodeVersion}.`,
+    );
+    return { code: 1, signal: null };
+  }
   const originalArgs = options.args ?? process.argv.slice(2);
   const originalCwd = options.cwd ?? process.cwd();
   const baseEnv = cleanManagedUpdateEnv(options.env ?? process.env);
@@ -341,8 +360,10 @@ if (require.main === module) {
 }
 
 module.exports = {
+  SUPPORTED_NODE_RANGE,
   cleanManagedUpdateEnv,
   cleanupEphemeralUpdateFiles,
+  isSupportedNodeVersion,
   orchestrate,
   runNative,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moondesk",
-  "version": "0.9.3",
+  "version": "0.9.4",
   "description": "MoonDesk — use ChatGPT Chat as a local coding agent, by Shattermoon.",
   "author": "Shattermoon",
   "license": "MIT",
@@ -19,11 +19,12 @@
     "npm/moondesk.js",
     "npm/install-binary.js",
     "npm/update-manager.js",
+    "skills/browser/SKILL.md",
     "LICENSE",
     "README.md"
   ],
   "engines": {
-    "node": ">=18"
+    "node": "^20.19.0 || ^22.12.0 || >=23"
   },
   "publishConfig": {
     "access": "public",

package/skills/browser/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: browser
+description: Control MoonDesk's shared Chromium session without exposing the full Chrome DevTools MCP schema to the model.
+---
+
+# MoonDesk Browser
+
+Use MoonDesk's browser runtime for local web-app inspection, UI testing, console/network debugging, accessibility snapshots, performance checks, and scripted browser flows.
+
+## Interfaces
+
+- **MCP `browser_command`**: preferred for one browser action at a time and the only browser action primitive needed in Browser-only mode.
+- **MCP `view_page`**: preferred whenever appearance matters. It returns the current rendered page as model-visible pixels.
+- **`moondesk browser` CLI**: preferred in Both mode when several deterministic browser actions are easier to express as a shell script or loop. It calls the same MoonDesk native browser runtime, so it shares the same isolated agent-browser session as MCP without touching the user's personal browser profile.
+
+Do not invoke `npx chrome-devtools-mcp` directly. MoonDesk pins and manages the compatible Chrome DevTools runtime.
+
+## Core workflow
+
+1. Navigate or select the target page.
+2. Set the target viewport before taking interaction UIDs. Use `resize_page` for normal desktop window sizes; use `emulate --viewport=<width>x<height>x<dpr>[,mobile][,touch]` for exact tablet/mobile responsive testing because Chromium may clamp very narrow desktop windows.
+3. After navigation or viewport emulation, run `take_snapshot`. Those operations can recreate the page context, so older UIDs may be stale.
+4. Use snapshot UIDs with `click`, `fill`, `hover`, `drag`, `upload_file`, etc.
+5. Take another snapshot after a state-changing action when the page structure may have changed.
+6. Use `view_page` for visual judgment. Accessibility/text snapshots are structural evidence, not a substitute for seeing the rendered page.
+7. Inspect console/network/performance data when it helps the task; do not collect large traces by default.
+
+The browser starts lazily on the first operation. Normal commands reuse the existing session. If the owned browser runtime is lost or a dispatched operation exceeds its deadline, MoonDesk invalidates that runtime before allowing another browser operation; the next call starts a fresh isolated session. MoonDesk does not automatically replay an ambiguous state-changing action, so navigate/select the target page and take a fresh snapshot after session loss.
+
+## Local dev-server verification
+
+When an agent starts a local web server, browser verification is part of completing the task rather than a separate setup step:
+
+1. Wait until the server reports its localhost URL as ready.
+2. Navigate the shared agent browser to that URL.
+3. Set the viewport being tested, then take a fresh snapshot.
+4. Exercise the user-visible flow with snapshot UIDs.
+5. Inspect console/network output when debugging behavior.
+6. Use `view_page` to verify the actual rendered result; do not declare visual success from DOM text alone.
+7. Repeat at the relevant desktop/tablet/mobile viewport when the change is responsive.
+
+## Common CLI commands
+
+```text
+moondesk browser list_pages
+moondesk browser new_page https://example.com
+moondesk browser navigate_page --url=https://example.com
+moondesk browser take_snapshot
+moondesk browser click 1_23 --includeSnapshot
+moondesk browser fill 1_31 "hello"
+moondesk browser press_key Enter --includeSnapshot
+moondesk browser resize_page 1280 800
+moondesk browser emulate --viewport=390x844x1,mobile,touch
+moondesk browser take_snapshot
+moondesk browser list_console_messages
+moondesk browser list_network_requests
+moondesk browser evaluate_script "() => ({title: document.title, href: location.href})"
+```
+
+Use `moondesk browser <command> --help` when a command's positional arguments or flags are unclear.
+
+## Scripted flows
+
+For repetitive deterministic work in Both mode, keep the browser operations in one shell script instead of spending one MCP schema/tool call per action. Example:
+
+```powershell
+moondesk browser navigate_page --url=http://localhost:3000
+moondesk browser emulate --viewport=390x844x1,mobile,touch
+moondesk browser take_snapshot
+moondesk browser list_console_messages
+```
+
+Prefer the CLI for orchestration, but return to `view_page` whenever the task requires actual visual inspection.
+
+## Safety and lifecycle
+
+- Do not run browser lifecycle commands (`start`, `status`, `stop`) through MCP `browser_command` or `moondesk browser`; the running MoonDesk host owns that lifecycle.
+- `moondesk browser` is a lightweight localhost client to the running MoonDesk host. It does not own a separate browser process; independent shell commands share the same MoonDesk-owned agent-browser session as MCP.
+- ReadOnly mode permits inspection commands only; navigation, JavaScript execution, interaction, uploads, resizing, and other state-changing browser commands are blocked.
+- Treat `evaluate_script` as code execution in the currently selected page. Use it only when needed and keep the function narrowly scoped.
+- Browser file paths are local machine paths. Use verified workspace paths for uploads or file-producing commands.