dominus-cli 2.1.1 → 2.2.1

package/CHANGELOG.md

@@ -1,6 +1,49 @@
 # Changelog
 
-## 2.1.1 (2026-07-13)
+## 2.2.1 (2026-07-13)
+
+### Stable Studio bridge architecture
+
+- Moved WebSocket ownership out of individual MCP stdio processes and into one
+  detached local bridge daemon. MCP hosts now act as controllers, so closing or
+  restarting one agent no longer disconnects Studio or other agents.
+- Added race-safe bridge startup and reuse. Concurrent MCP launches converge on
+  the same loopback bridge instead of creating separate connection state.
+- The plugin installer now starts the bridge automatically and provisions the
+  user-specific 256-bit credential into the local plugin. Manual connection IDs
+  and six-digit pairing codes are no longer part of setup or recovery.
+- Built the plugin root with `RunContext.Plugin` and added an entry-point guard.
+  Starting a Play test can no longer launch duplicate Client and Server Dominus
+  sessions from one Studio window.
+- Added regressions for plugin run context, seamless credential provisioning,
+  unauthorized plugin rejection, and bridge survival across MCP controller exits.
+
+## 2.2.0 (2026-07-13)
+
+### MCP-native multi-agent coordinator
+
+- Added `run_parallel_task` to the published MCP server. It uses the MCP client's
+  model through standard Sampling, so Dominus still requires no AI provider key.
+- Added deterministic path-based task partitioning. UI and generic roots are split
+  by immediate child branches and distributed across one to five workers.
+- Workers run concurrently and receive bounded hierarchy plus live typed property
+  evidence for only their owned scopes. Workers are proposal-only and never receive
+  Studio mutation tools.
+- Added strict worker proposal and coordinator decision schemas. Existing instance
+  refs must exactly match supplied ID/path pairs, and every mutation must remain
+  inside the worker's owned branches.
+- Added ancestor/descendant conflict detection and coordinator-only operation
+  ordering. The coordinator may select complete validated proposals but cannot
+  invent, rewrite, or partially accept worker operations.
+- Final writes use one atomic `studio_apply` batch. Dominus then reads the root and
+  affected properties back, checks creates and moves, and performs at most one
+  bounded repair pass before reporting verification evidence.
+- Parallel planning refuses truncated hierarchy evidence, and generic property
+  mutations can no longer bypass revision checks by writing script `Source`.
+- Added summary-level MCP logging events for worker starts/completions, proposal
+  decisions, application, and verification without exposing full model traces.
+- Clients without Sampling receive a clear capability response and keep the normal
+  single-agent inspect-plan-apply-verify workflow.
 
 ### Studio connection reliability
 
@@ -16,8 +59,8 @@
   rejected by resolving names against the live Enum type's items.
 - Removed the stale binary `.rbxm` build artifact. The package and installer now
   use the single canonical `.rbxmx` plugin build.
-- Corrected documentation to describe the 16-tool MCP catalog and optional Studio
-  restart behavior.
+- Corrected documentation for the 17-tool MCP catalog, canonical plugin format,
+  and optional Studio restart behavior.
 
 ## 2.1.0 (2026-07-12)
 
@@ -101,95 +144,95 @@ Dominus has been rewritten as an MCP-first Roblox Studio engineering server.
   `instanceId` and/or `pathSegments`.
 - Script updates require `expectedRevision` from `studio_read_script`.
 - Existing UI is not replaced unless `replaceExisting: true` is supplied.
-
-## 0.5.5 (2026-04-23)
-
-### New MCP Tools (30 total, up from 24)
-
-- **`move_instance`** — Reparent an instance preserving all descendants. Sets ChangeHistoryService waypoint.
-- **`bulk_set_properties`** — Set properties on multiple instances in one call. Explicit paths or className filter mode.
-- **`find_replace_scripts`** — Find and replace across all scripts with optional Lua pattern matching and dry run preview.
-- **`undo`** — Undo last action (ChangeHistoryService). Like Ctrl+Z.
-- **`redo`** — Redo last undone action. Like Ctrl+Y.
-
-### Improvements
-
-- **`get_properties` now supports compact mode** — Same filtering as `get_descendants_properties`. Strips read-only, nil, deprecated, and default-valued properties by default. The previous version returned all ~50 properties per instance even though most were noise.
-- **Fixed code injection in `clone_instance`, `group_instances`, `build_multiple`** — Instance names and paths with special characters (quotes, backslashes) no longer break generated Luau code.
-- **`build_multiple` now supports `rgb()` colors and `canCollide`** — Previously only handled `#hex` and BrickColor names; `rgb(255,0,0)` would silently fail.
-- **Better tool descriptions** — More specific descriptions help AI models pick the right tool. `get_properties` disambiguates vs `serialize_ui` and `get_descendants_properties`.
-- **Shared `luaStr()` and `resolvePath()` helpers** — Centralized safe string generation for all code-gen tools.
-
-## 0.5.4 (2026-04-23)
-
-### Fixes
-
-- **Rebuilt plugin** — 0.5.3 shipped a stale `Dominus.rbxm` missing the compact property filtering and protocol changes. This release includes the correctly built plugin.
-
-## 0.5.3 (2026-04-23)
-
-### Improvements
-
-- **Compact `get_descendants_properties`** — Now strips read-only, nil, deprecated, and default-valued properties by default, reducing response size by ~80%. Pass `compact: false` for the full dump.
-- **`serialize_ui` exposed as MCP tool** — Was previously only in the internal tool registry. Now available to all MCP clients (Copilot, Cursor, Claude, etc.) for converting existing Roblox UI into clean JSON trees.
-- **UI → Roact/React conversion guidance** — System prompt and internal memory now teach the agent the full workflow: `serialize_ui` → JSON tree → Roact/React component with correct type mappings (UDim2, Color3, Vector2, enums, FontFace).
-- **Smarter tool selection** — Agent now prefers `serialize_ui` over `get_descendants_properties` for UI conversion tasks, avoiding context bloat.
-
-## 0.2.1 (2026-02-24)
-
-### New
-
-- **Auto-update checker** — On startup, Dominus checks npm for newer versions
-  and prints an upgrade notice. Cached for 4 hours, non-blocking, never throws.
-
-### Bug Fixes
-
-- **MCP server crashes on EADDRINUSE** — `dominus mcp` would crash if port 18088
-  was already held by a running `dominus start` (or another MCP instance). The MCP
-  server now checks for an existing listener and connects as a relay client instead
-  of trying to bind the same port.
-
-### New MCP Tools (22 total, up from 14)
-
-- **`get_class_info`** — Look up the full schema of any Roblox class via
-  ReflectionService (properties, methods, events with types).
-- **`create_ui`** — Create an entire UI tree in one call with a declarative JSON
-  spec. Auto-coerces UDim2, Color3, Font, and enums. ~10x faster than `run_code`.
-- **`create_part`** — One-call Part creation with position, size, color, material,
-  shape, transparency, anchored, and collision settings.
-- **`clone_instance`** — Clone an instance with optional rename, reparent, and
-  position offset.
-- **`group_instances`** — Group multiple instances into a Model or Folder.
-- **`build_multiple`** — Batch-create many parts/instances in a single round-trip.
-- **`execute_run_test`** — Enter Run mode via `StudioTestService:ExecuteRunModeAsync()`
-  with pass-through args and result capture.
-- **`execute_play_test`** — Enter Play mode via `StudioTestService:ExecutePlayModeAsync()`
-  for full client-server simulation tests.
-
-### New CLI Features
-
-- **`dominus mcp-install`** — Auto-install MCP config into Cursor, VS Code,
-  Claude Desktop, Windsurf, and Claude Code with one command.
-- **`dominus mcp-setup`** — Print manual MCP configuration instructions.
-- **Relay client architecture** — `dominus start` can now connect as a relay
-  client to an existing MCP-owned WebSocket server, allowing the TUI and MCP
-  to coexist on the same port.
-
-### Plugin Improvements
-
-- Enhanced `Properties.lua` with broader property type support.
-- Improved `Reflection.lua` for richer class metadata.
-- Updated `TestRunner.lua` with Run/Play mode test support.
-- New `UIBuilder.lua` module for server-side declarative UI construction.
-
-### Other Changes
-
-- Multi-provider AI config improvements (OpenRouter, xAI, Gemini, custom).
-- TUI setup wizard for first-run API key and provider configuration.
-- Improved system prompt with builder-tool awareness.
-- WebSocket server now supports controller relay connections.
-
-## 0.1.0 (2026-02-23)
-
-- Initial release — 14 MCP tools, TUI agent, persistent memory, Roblox Studio
-  WebSocket bridge.
+
+## 0.5.5 (2026-04-23)
+
+### New MCP Tools (30 total, up from 24)
+
+- **`move_instance`** — Reparent an instance preserving all descendants. Sets ChangeHistoryService waypoint.
+- **`bulk_set_properties`** — Set properties on multiple instances in one call. Explicit paths or className filter mode.
+- **`find_replace_scripts`** — Find and replace across all scripts with optional Lua pattern matching and dry run preview.
+- **`undo`** — Undo last action (ChangeHistoryService). Like Ctrl+Z.
+- **`redo`** — Redo last undone action. Like Ctrl+Y.
+
+### Improvements
+
+- **`get_properties` now supports compact mode** — Same filtering as `get_descendants_properties`. Strips read-only, nil, deprecated, and default-valued properties by default. The previous version returned all ~50 properties per instance even though most were noise.
+- **Fixed code injection in `clone_instance`, `group_instances`, `build_multiple`** — Instance names and paths with special characters (quotes, backslashes) no longer break generated Luau code.
+- **`build_multiple` now supports `rgb()` colors and `canCollide`** — Previously only handled `#hex` and BrickColor names; `rgb(255,0,0)` would silently fail.
+- **Better tool descriptions** — More specific descriptions help AI models pick the right tool. `get_properties` disambiguates vs `serialize_ui` and `get_descendants_properties`.
+- **Shared `luaStr()` and `resolvePath()` helpers** — Centralized safe string generation for all code-gen tools.
+
+## 0.5.4 (2026-04-23)
+
+### Fixes
+
+- **Rebuilt plugin** — 0.5.3 shipped a stale `Dominus.rbxm` missing the compact property filtering and protocol changes. This release includes the correctly built plugin.
+
+## 0.5.3 (2026-04-23)
+
+### Improvements
+
+- **Compact `get_descendants_properties`** — Now strips read-only, nil, deprecated, and default-valued properties by default, reducing response size by ~80%. Pass `compact: false` for the full dump.
+- **`serialize_ui` exposed as MCP tool** — Was previously only in the internal tool registry. Now available to all MCP clients (Copilot, Cursor, Claude, etc.) for converting existing Roblox UI into clean JSON trees.
+- **UI → Roact/React conversion guidance** — System prompt and internal memory now teach the agent the full workflow: `serialize_ui` → JSON tree → Roact/React component with correct type mappings (UDim2, Color3, Vector2, enums, FontFace).
+- **Smarter tool selection** — Agent now prefers `serialize_ui` over `get_descendants_properties` for UI conversion tasks, avoiding context bloat.
+
+## 0.2.1 (2026-02-24)
+
+### New
+
+- **Auto-update checker** — On startup, Dominus checks npm for newer versions
+  and prints an upgrade notice. Cached for 4 hours, non-blocking, never throws.
+
+### Bug Fixes
+
+- **MCP server crashes on EADDRINUSE** — `dominus mcp` would crash if port 18088
+  was already held by a running `dominus start` (or another MCP instance). The MCP
+  server now checks for an existing listener and connects as a relay client instead
+  of trying to bind the same port.
+
+### New MCP Tools (22 total, up from 14)
+
+- **`get_class_info`** — Look up the full schema of any Roblox class via
+  ReflectionService (properties, methods, events with types).
+- **`create_ui`** — Create an entire UI tree in one call with a declarative JSON
+  spec. Auto-coerces UDim2, Color3, Font, and enums. ~10x faster than `run_code`.
+- **`create_part`** — One-call Part creation with position, size, color, material,
+  shape, transparency, anchored, and collision settings.
+- **`clone_instance`** — Clone an instance with optional rename, reparent, and
+  position offset.
+- **`group_instances`** — Group multiple instances into a Model or Folder.
+- **`build_multiple`** — Batch-create many parts/instances in a single round-trip.
+- **`execute_run_test`** — Enter Run mode via `StudioTestService:ExecuteRunModeAsync()`
+  with pass-through args and result capture.
+- **`execute_play_test`** — Enter Play mode via `StudioTestService:ExecutePlayModeAsync()`
+  for full client-server simulation tests.
+
+### New CLI Features
+
+- **`dominus mcp-install`** — Auto-install MCP config into Cursor, VS Code,
+  Claude Desktop, Windsurf, and Claude Code with one command.
+- **`dominus mcp-setup`** — Print manual MCP configuration instructions.
+- **Relay client architecture** — `dominus start` can now connect as a relay
+  client to an existing MCP-owned WebSocket server, allowing the TUI and MCP
+  to coexist on the same port.
+
+### Plugin Improvements
+
+- Enhanced `Properties.lua` with broader property type support.
+- Improved `Reflection.lua` for richer class metadata.
+- Updated `TestRunner.lua` with Run/Play mode test support.
+- New `UIBuilder.lua` module for server-side declarative UI construction.
+
+### Other Changes
+
+- Multi-provider AI config improvements (OpenRouter, xAI, Gemini, custom).
+- TUI setup wizard for first-run API key and provider configuration.
+- Improved system prompt with builder-tool awareness.
+- WebSocket server now supports controller relay connections.
+
+## 0.1.0 (2026-02-23)
+
+- Initial release — 14 MCP tools, TUI agent, persistent memory, Roblox Studio
+  WebSocket bridge.

package/README.md

@@ -8,12 +8,17 @@ Luau execution.
 ## What changed
 
 - MCP-only product: the old Ink chat CLI is no longer published.
-- 16 focused tools with input/output schemas, structured results, and risk hints.
+- 17 focused tools with input/output schemas, structured results, and risk hints.
+- MCP-native parallel coordination uses the host's model through Sampling, with
+  proposal-only workers and coordinator-owned Studio writes.
 - Stable instance refs survive dots in names, renames, reparenting, and duplicate
   sibling names for the life of the Studio session.
 - Script writes require a revision from `studio_read_script`.
 - Mutation batches and UI replacement are undoable and roll back on failure.
-- The installer provisions a private bridge token into the local Studio plugin.
+- The installer provisions a local bridge credential automatically; users never
+  copy connection IDs or pairing codes.
+- A single background bridge keeps Studio connected while MCP hosts and agents
+  start, stop, or run in parallel.
 - Multiple Studio windows are selected by unique connection ID, not place ID.
 - Roblox Creator Docs API lookup is built in.
 
@@ -63,7 +68,7 @@ For a version-pinned configuration that does not require a global install:
   "mcpServers": {
     "dominus": {
       "command": "npx",
-      "args": ["-y", "-p", "dominus-cli@2.1.1", "dominus-mcp"]
+      "args": ["-y", "-p", "dominus-cli@2.2.1", "dominus-mcp"]
     }
   }
 }
@@ -73,9 +78,13 @@ Restart the MCP client after changing its configuration.
 
 ## First connection
 
-1. Run `dominus-install-plugin`; restart Roblox Studio only if it does not reload.
-2. Start the MCP client so `dominus-mcp` is running.
-3. Open Roblox Studio. The plugin connects and authenticates automatically.
+1. Run `dominus-install-plugin`; it installs the personalized plugin and starts
+   the local Studio bridge in the background.
+2. Open Roblox Studio and start the MCP client. Dominus authenticates
+   automatically with no connection ID or pairing code.
+
+If the local credential is replaced or lost, run `dominus-install-plugin` again.
+Studio normally reloads it without a restart.
 
 If several Studio windows are open, call `dominus_select_studio` with the exact
 connection ID before editing. Two windows on the same place ID remain distinct.
@@ -94,6 +103,13 @@ For UI fidelity work, use `studio_snapshot_ui` after `studio_build_ui` and compa
 fonts, UDim2 values, colors, strokes, and hierarchy rather than relying on a
 successful write response alone.
 
+For broad tasks with independent branches, use `run_parallel_task`. Dominus
+partitions immediate child scopes, supplies each worker with hierarchy and typed
+property evidence, runs up to five Sampling workers concurrently, validates their
+proposals, and applies only the coordinator-approved atomic plan. Workers never
+receive direct write access. Clients without Sampling continue to use the normal
+single-agent workflow.
+
 ## Tool catalog
 
 Connection tools:
@@ -101,6 +117,10 @@ Connection tools:
 - `dominus_status`
 - `dominus_select_studio`
 
+Parallel coordination:
+
+- `run_parallel_task`
+
 Studio inspection:
 
 - `studio_get_tree`
@@ -126,12 +146,13 @@ Roblox documentation:
 
 ## Security model
 
-The MCP transport is stdio. The separate Studio WebSocket bridge binds only to
-`127.0.0.1`, limits messages to one MiB, rate-limits sockets, times out incomplete
-handshakes, and authenticates both Studio plugins and relay controllers. The local
-installer injects a user-specific token into the plugin, so no manual pairing flow
-is needed. The plugin only accepts an explicit command allowlist and contains no
-`loadstring` executor.
+The MCP transport is stdio. A single background Studio WebSocket bridge binds
+only to `127.0.0.1`, limits messages to one MiB, rate-limits sockets, times out
+incomplete handshakes, and authenticates both Studio plugins and MCP controllers.
+The distributed plugin contains only a credential placeholder;
+`dominus-install-plugin` writes the user-specific token into the local copy. The
+plugin only accepts an explicit command allowlist and contains no `loadstring`
+executor.
 
 The bridge token protects against accidental or opportunistic access by unrelated
 local processes. Like other user-level credentials, it cannot protect against a