moondesk 0.9.5 → 0.10.0

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.
-- **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.
+- **Headless agent browser by default** — a small `set_browser_presentation` + `browser_command` + `view_page` surface backed by a pinned Chrome DevTools runtime. Selecting Browser/Both does not launch Chrome; the shared isolated browser starts lazily on first use without opening a desktop window unless the user or agent switches it to visible mode.
 - **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.
@@ -65,7 +65,9 @@ Choose:
 - `Control Browser`
 - `Both`
 
-On first launch, MoonDesk asks for your **ngrok authtoken** and **static domain**. These are stored in `~/.moondesk/config.toml`.
+On first launch, MoonDesk asks for your **ngrok authtoken** and **static domain**. MoonDesk stores them in its config file (`%USERPROFILE%\.moondesk\config.toml` on Windows and `$HOME/.moondesk/config.toml` on macOS/Linux). You can update either value later from Settings; the authtoken editor is masked, Settings only shows whether a token is configured, and it also shows the exact active config path.
+
+When upgrading on Windows from a version that previously used a conflicting `HOME\.moondesk\config.toml`, the next MoonDesk host startup migrates that existing config once into the canonical `%USERPROFILE%` location. The migration preserves the complete workspace registry and connector identities; it does **not** clear or recreate users' workspaces. If another process creates the canonical config during that migration, the canonical file wins and the legacy source is retained instead of being overwritten or deleted. A migration marker beside the legacy location prevents a stale legacy config from being imported again later if Windows could not remove it or another old process recreates it.
 
 ### 3. Copy the workspace URL
 
@@ -121,7 +123,9 @@ 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. 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.
+When no saved workspace registry exists, MoonDesk creates workspace #1 from the directory it was launched in (or `WORKSPACE_ROOT`). After deleting/resetting the config, launching again from the same project can therefore show the same workspace name and root even though it is a freshly generated registration with a new secret. Startup logs state explicitly when this bootstrap path was used.
+
+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 runs **headless by default** at a deterministic 1280×800 initial viewport, so normal agent work does not open a Chrome window, while `view_page` and screenshots still inspect the browser's rendered pixels. Agents can still resize or emulate the target viewport for responsive QA. Press `[v]` in the live dashboard to switch between hidden/headless and visible presentation; the Browser status row shows the current mode and the toggle hint. In `multi-tools` mode an agent can also call `set_browser_presentation`, primarily when a login, CAPTCHA, permission prompt, or other step needs human input. If changing presentation would close a live session, the tool refuses the change and reports `confirmation_required`; the agent must get explicit user approval before retrying with `confirm_restart=true`. Changing presentation while the browser is running closes that temporary session first, so its tabs, cookies, storage, page state, and snapshot UIDs are discarded. Switching to visible starts a fresh empty visible browser immediately; if that headful launch fails, MoonDesk reverts the setting to headless so later agent browser work remains usable. A human-assisted visible session should stay visible while its entered state is still needed; switching back to headless closes that session and returns to lazy hidden startup on the next browser action. MoonDesk 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.
 
@@ -152,6 +156,7 @@ Browser mode has a stable tool catalog instead of forwarding the full Chrome Dev
 
 | Browser tool | Purpose |
 | --- | --- |
+| `set_browser_presentation` | In `multi-tools`, request headless or visible presentation; live-session changes require explicit restart confirmation |
 | `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 |
 
@@ -167,7 +172,7 @@ 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` 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. The browser starts headless by default; visible mode changes only Chromium presentation, not the browser tool surface or isolation model. 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.
 
@@ -192,7 +197,7 @@ Use:
 
 | Setting | Default / location |
 | --- | --- |
-| Config | `~/.moondesk/config.toml` |
+| Config | `%USERPROFILE%\.moondesk\config.toml` on Windows; `$HOME/.moondesk/config.toml` on macOS/Linux |
 | Port | `3200` |
 | Port override | `PORT` |
 | Initial workspace override | `WORKSPACE_ROOT` |
@@ -213,7 +218,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 runtime | pinned `chrome-devtools-mcp@1.7.0` stdio child owned by MoonDesk, started lazily |
+| Browser runtime | pinned `chrome-devtools-mcp@1.7.0` stdio child owned by MoonDesk, lazy + headless by default with opt-in visible presentation |
 | Distribution | npm + native binaries |
 
 ## Contributing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moondesk",
-  "version": "0.9.5",
+  "version": "0.10.0",
   "description": "MoonDesk — use ChatGPT Chat as a local coding agent, by Shattermoon.",
   "author": "Shattermoon",
   "license": "MIT",

package/skills/browser/SKILL.md

@@ -9,7 +9,8 @@ Use MoonDesk's browser runtime for local web-app inspection, UI testing, console
 
 ## Interfaces
 
-- **MCP `browser_command`**: preferred for one browser action at a time and the only browser action primitive needed in Browser-only mode.
+- **MCP `set_browser_presentation`**: available in `multi-tools` mode for the rare case where the agent needs the isolated browser to become visible for human input. Prefer headless; a live-session switch requires explicit user approval before retrying with `confirm_restart=true`.
+- **MCP `browser_command`**: preferred for one browser action at a time and the only page-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.
 
@@ -25,7 +26,7 @@ Do not invoke `npx chrome-devtools-mcp` directly. MoonDesk pins and manages the
 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.
+The browser starts lazily on the first operation and runs headless by default at a deterministic 1280x800 initial viewport, so normal agent work does not open a desktop Chromium window. Headless mode still supports snapshots, screenshots, `view_page`, console/network inspection, interaction, and responsive emulation. Resize or emulate the target viewport before responsive or pixel-sensitive QA. Users can switch the agent browser to visible presentation from MoonDesk's dashboard. In `multi-tools`, an agent may use `set_browser_presentation` when the user needs to see or manually interact with the isolated browser, such as a login, CAPTCHA, or permission prompt; do not switch merely for agent visual inspection because `view_page` already provides rendered pixels. Because presentation is chosen when Chromium starts, changing it while the browser is running closes the current isolated session and prior tabs, cookies/storage, page state, and snapshot UIDs are gone. The tool therefore returns `confirmation_required` without changing a live session unless the agent retries with `confirm_restart=true` after explicit user approval. Switching to visible starts a fresh empty visible session immediately; if that headful launch fails, MoonDesk reverts the setting to headless so later browser work remains usable. Keep a human-assisted session visible while its entered state is still needed. Switching back to headless closes the visible browser and the next browser action starts a fresh hidden session. Normal commands otherwise 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