dominus-cli 2.2.0 → 2.3.0

package/dist/mcp.js

@@ -1,20 +1,21 @@
 #!/usr/bin/env node
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import fs3 from 'fs';
-import path3 from 'path';
+import fs4 from 'fs';
+import path4 from 'path';
 import os from 'os';
+import { spawn } from 'child_process';
+import { fileURLToPath } from 'url';
 import { EventEmitter } from 'events';
-import { WebSocket, WebSocketServer } from 'ws';
+import { WebSocket } from 'ws';
 import { nanoid } from 'nanoid';
 import { z } from 'zod';
 import * as crypto from 'crypto';
-import { randomUUID } from 'crypto';
 
-var DOMINUS_DIR = path3.join(os.homedir(), ".dominus");
-var CONFIG_PATH = path3.join(DOMINUS_DIR, "config.json");
-path3.join(DOMINUS_DIR, "dominus.db");
-path3.join(DOMINUS_DIR, "rules.json");
+var DOMINUS_DIR = path4.join(os.homedir(), ".dominus");
+var CONFIG_PATH = path4.join(DOMINUS_DIR, "config.json");
+path4.join(DOMINUS_DIR, "dominus.db");
+path4.join(DOMINUS_DIR, "rules.json");
 var DEFAULTS = {
   provider: "openai",
   apiBaseUrl: "",
@@ -28,14 +29,14 @@ var DEFAULTS = {
   userName: "Developer"
 };
 function ensureDir() {
-  if (!fs3.existsSync(DOMINUS_DIR)) {
-    fs3.mkdirSync(DOMINUS_DIR, { recursive: true });
+  if (!fs4.existsSync(DOMINUS_DIR)) {
+    fs4.mkdirSync(DOMINUS_DIR, { recursive: true });
   }
 }
 function readJson(filePath, defaults) {
   try {
-    if (fs3.existsSync(filePath)) {
-      const raw = fs3.readFileSync(filePath, "utf-8");
+    if (fs4.existsSync(filePath)) {
+      const raw = fs4.readFileSync(filePath, "utf-8");
       return { ...defaults, ...JSON.parse(raw) };
     }
   } catch {
@@ -108,6 +109,14 @@ var CliMsg = {
   V2_READ_SCRIPT: "studio:v2:read_script",
   V2_UPDATE_SCRIPT: "studio:v2:update_script",
   V2_APPLY: "studio:v2:apply",
+  V2_CREATE_PARTS: "studio:v2:create_parts",
+  V2_CLONE_INSTANCES: "studio:v2:clone_instances",
+  V2_GROUP_INSTANCES: "studio:v2:group_instances",
+  V2_UNGROUP_INSTANCES: "studio:v2:ungroup_instances",
+  V2_TRANSFORM_INSTANCES: "studio:v2:transform_instances",
+  V2_CREATE_WELDS: "studio:v2:create_welds",
+  V2_QUERY_PARTS: "studio:v2:query_parts",
+  V2_SET_SELECTION: "studio:v2:set_selection",
   V2_DELETE: "studio:v2:delete",
   V2_BUILD_UI: "studio:v2:build_ui",
   V2_SNAPSHOT_UI: "studio:v2:snapshot_ui",
@@ -144,27 +153,21 @@ var wsMessageSchema = z.object({
 }).strict();
 var TOKEN_FILE = "bridge-token";
 function loadOrCreateBridgeToken() {
-  const tokenPath = path3.join(getDominusDir(), TOKEN_FILE);
+  const tokenPath = path4.join(getDominusDir(), TOKEN_FILE);
   try {
-    const existing = fs3.readFileSync(tokenPath, "utf8").trim();
+    const existing = fs4.readFileSync(tokenPath, "utf8").trim();
     if (existing.length >= 32) return existing;
   } catch {
   }
   const token = crypto.randomBytes(32).toString("base64url");
-  fs3.writeFileSync(tokenPath, `${token}
+  fs4.writeFileSync(tokenPath, `${token}
 `, { encoding: "utf8", mode: 384 });
   try {
-    fs3.chmodSync(tokenPath, 384);
+    fs4.chmodSync(tokenPath, 384);
   } catch {
   }
   return token;
 }
-function tokensEqual(actual, expected) {
-  if (typeof actual !== "string") return false;
-  const actualBuffer = Buffer.from(actual);
-  const expectedBuffer = Buffer.from(expected);
-  return actualBuffer.length === expectedBuffer.length && crypto.timingSafeEqual(actualBuffer, expectedBuffer);
-}
 
 // src/transport/ws-client.ts
 var DominusClient = class extends EventEmitter {
@@ -197,10 +200,14 @@ var DominusClient = class extends EventEmitter {
       }, this.connectTimeoutMs);
       ws.on("open", () => {
         this.ws = ws;
-        ws.send(serializeMessage(createMessage(ControllerMsg.HELLO, {
-          protocolVersion: DOMINUS_PROTOCOL_VERSION,
-          token: this.token
-        })));
+        ws.send(
+          serializeMessage(
+            createMessage(ControllerMsg.HELLO, {
+              protocolVersion: DOMINUS_PROTOCOL_VERSION,
+              token: this.token
+            })
+          )
+        );
       });
       ws.on("message", (raw) => {
         try {
@@ -341,7 +348,11 @@ var DominusClient = class extends EventEmitter {
   sendRequest(type, payload, timeoutMs = 15e3) {
     const target = this.resolveTargetInfo();
     if (!target || !this.activeConnectionId) {
-      return Promise.reject(new Error(this.connections.size > 1 ? "Multiple Studio sessions are connected. Call dominus_select_studio first." : "No authenticated Roblox Studio connection"));
+      return Promise.reject(
+        new Error(
+          this.connections.size > 1 ? "Multiple Studio sessions are connected. Call dominus_select_studio first." : "No authenticated Roblox Studio connection"
+        )
+      );
     }
     const request = createMessage(type, payload);
     const relay = createMessage(ControllerMsg.RELAY, {
@@ -370,10 +381,12 @@ var DominusClient = class extends EventEmitter {
   sendNotification(type, payload) {
     if (!this.activeConnectionId) return;
     const request = createMessage(type, payload);
-    this.sendMessage(createMessage(ControllerMsg.RELAY, {
-      connectionId: this.activeConnectionId,
-      request
-    }));
+    this.sendMessage(
+      createMessage(ControllerMsg.RELAY, {
+        connectionId: this.activeConnectionId,
+        request
+      })
+    );
   }
   isConnected() {
     return this.resolveTargetInfo() !== null;
@@ -412,9 +425,13 @@ var DominusClient = class extends EventEmitter {
       void this.setActiveConnectionId(null);
       return;
     }
-    const matches = [...this.connections.values()].filter((connection) => connection.placeId === placeId);
+    const matches = [...this.connections.values()].filter(
+      (connection) => connection.placeId === placeId
+    );
     if (matches.length !== 1) {
-      throw new Error(matches.length === 0 ? `Place ${placeId} is not connected` : `Place ${placeId} has multiple Studio sessions; select a connectionId instead`);
+      throw new Error(
+        matches.length === 0 ? `Place ${placeId} is not connected` : `Place ${placeId} has multiple Studio sessions; select a connectionId instead`
+      );
     }
     void this.setActiveConnectionId(matches[0].connectionId);
   }
@@ -475,413 +492,74 @@ async function isPortInUse(port) {
     });
   });
 }
-var HANDSHAKE_TIMEOUT_MS = 8e3;
-var RATE_WINDOW_MS = 1e4;
-var RATE_LIMIT = 250;
-var DominusServer = class extends EventEmitter {
-  wss = null;
-  studioClients = /* @__PURE__ */ new Map();
-  wsToConnectionId = /* @__PURE__ */ new Map();
-  controllers = /* @__PURE__ */ new Set();
-  socketRoles = /* @__PURE__ */ new Map();
-  pendingRequests = /* @__PURE__ */ new Map();
-  relayRequests = /* @__PURE__ */ new Map();
-  rateState = /* @__PURE__ */ new Map();
-  token;
-  host;
-  maxPayloadBytes;
-  handshakeTimeoutMs;
-  activeConnectionId = null;
-  port;
-  constructor(port = 18088, options = {}) {
-    super();
-    this.port = port;
-    this.token = options.token ?? loadOrCreateBridgeToken();
-    this.host = options.host ?? "127.0.0.1";
-    this.maxPayloadBytes = options.maxPayloadBytes ?? MAX_MESSAGE_BYTES;
-    this.handshakeTimeoutMs = options.handshakeTimeoutMs ?? HANDSHAKE_TIMEOUT_MS;
-  }
-  start(maxRetries = 0) {
-    return new Promise((resolve, reject) => {
-      const tryPort = (port, attempt) => {
-        const wss = new WebSocketServer({
-          port,
-          host: this.host,
-          maxPayload: this.maxPayloadBytes,
-          perMessageDeflate: false
-        });
-        wss.on("listening", () => {
-          this.wss = wss;
-          this.port = port;
-          wss.on("connection", (ws) => this.handleConnection(ws));
-          this.emit("server:started", { port, host: this.host });
-          resolve();
-        });
-        wss.on("error", (err) => {
-          if (err.code === "EADDRINUSE" && attempt < maxRetries) {
-            wss.close();
-            tryPort(port + 1, attempt + 1);
-            return;
-          }
-          this.emit("server:error", err);
-          reject(err);
-        });
-      };
-      tryPort(this.port, 0);
-    });
-  }
-  handleConnection(ws) {
-    this.socketRoles.set(ws, "unknown");
-    this.rateState.set(ws, { startedAt: Date.now(), count: 0 });
-    const handshakeTimer = setTimeout(() => {
-      if (this.socketRoles.get(ws) === "unknown") {
-        ws.close(1008, "Dominus handshake timed out");
-      }
-    }, this.handshakeTimeoutMs);
-    ws.on("message", (raw) => {
-      try {
-        if (!this.consumeRateBudget(ws) || rawByteLength(raw) > this.maxPayloadBytes) {
-          ws.close(1009, "Dominus message limit exceeded");
-          return;
-        }
-        const msg = parseMessage(raw.toString());
-        const role = this.socketRoles.get(ws) ?? "unknown";
-        if (role === "unknown") {
-          clearTimeout(handshakeTimer);
-          this.handleHandshake(ws, msg);
-        } else if (role === "controller") {
-          this.handleControllerMessage(ws, msg);
-        } else if (role === "studio") {
-          this.handleStudioMessage(ws, msg);
-        }
-      } catch (err) {
-        this.emit("server:error", err);
-        this.sendSafe(ws, createMessage(StudioMsg.AUTH_REJECTED, {
-          error: err instanceof Error ? err.message : String(err)
-        }));
-      }
-    });
-    ws.on("close", () => {
-      clearTimeout(handshakeTimer);
-      this.cleanupSocket(ws);
-    });
-    ws.on("error", (err) => this.emit("server:error", err));
-  }
-  consumeRateBudget(ws) {
-    const now = Date.now();
-    const state = this.rateState.get(ws) ?? { startedAt: now, count: 0 };
-    if (now - state.startedAt >= RATE_WINDOW_MS) {
-      state.startedAt = now;
-      state.count = 0;
-    }
-    state.count += 1;
-    this.rateState.set(ws, state);
-    return state.count <= RATE_LIMIT;
-  }
-  handleHandshake(ws, msg) {
-    if (msg.type === StudioMsg.HELLO) {
-      const hello = validateStudioHello(msg.payload);
-      if (tokensEqual(hello.token, this.token)) {
-        this.authorizeStudio(ws, hello, randomUUID());
-      } else {
-        this.sendSafe(ws, createMessage(StudioMsg.AUTH_REJECTED, {
-          error: "Studio plugin credentials are missing or stale. Run dominus-install-plugin and restart Studio."
-        }));
-        ws.close(1008, "Unauthorized Studio plugin");
-      }
-      return;
-    }
-    if (msg.type === ControllerMsg.HELLO) {
-      const payload = msg.payload;
-      if (payload.protocolVersion !== DOMINUS_PROTOCOL_VERSION || !tokensEqual(payload.token, this.token)) {
-        this.sendSafe(ws, createMessage(StudioMsg.AUTH_REJECTED, { error: "Invalid Dominus controller credentials" }));
-        ws.close(1008, "Unauthorized controller");
-        return;
-      }
-      this.socketRoles.set(ws, "controller");
-      this.controllers.add(ws);
-      this.sendSafe(ws, createMessage(ControllerMsg.WELCOME, {
-        protocolVersion: DOMINUS_PROTOCOL_VERSION,
-        port: this.port,
-        connections: this.listConnections(),
-        activeConnectionId: this.activeConnectionId
-      }));
-      return;
-    }
-    this.sendSafe(ws, createMessage(StudioMsg.AUTH_REJECTED, {
-      error: `Expected ${StudioMsg.HELLO} or ${ControllerMsg.HELLO}`
-    }));
-    ws.close(1008, "Invalid Dominus handshake");
-  }
-  authorizeStudio(ws, hello, connectionId) {
-    const connection = {
-      ws,
-      connectionId,
-      clientId: hello.clientId,
-      connectedAt: Date.now(),
-      studioVersion: hello.studioVersion,
-      placeId: hello.placeId ?? 0,
-      placeName: hello.placeName
-    };
-    this.studioClients.set(connectionId, connection);
-    this.wsToConnectionId.set(ws, connectionId);
-    this.socketRoles.set(ws, "studio");
-    if (!this.activeConnectionId || !this.studioClients.has(this.activeConnectionId)) {
-      this.activeConnectionId = connectionId;
-    }
-    this.sendSafe(ws, createMessage(StudioMsg.AUTHENTICATED, {
-      protocolVersion: DOMINUS_PROTOCOL_VERSION,
-      connectionId,
-      token: this.token
-    }));
-    const info = this.toPlaceInfo(connection);
-    this.emit("studio:connected", info);
-    this.broadcastToControllers(StudioMsg.CONNECTED, info);
-    this.broadcastTargetState();
-    return connection;
-  }
-  handleControllerMessage(controllerWs, msg) {
-    if (msg.type === ControllerMsg.RELAY) {
-      const payload = msg.payload;
-      const request = parseMessage(JSON.stringify(payload.request));
-      const target = this.resolveConnection(typeof payload.connectionId === "string" ? payload.connectionId : null);
-      if (!target) {
-        this.sendResponse(controllerWs, request.id, { error: this.getTargetError() });
-        return;
-      }
-      this.relayRequests.set(request.id, { controllerWs, targetWs: target.ws });
-      this.sendSafe(target.ws, request);
-      return;
-    }
-    if (msg.type === ControllerMsg.SET_ACTIVE_CONNECTION) {
-      const payload = msg.payload;
-      const connectionId = typeof payload.connectionId === "string" ? payload.connectionId : null;
-      if (connectionId && !this.studioClients.has(connectionId)) {
-        this.sendResponse(controllerWs, msg.id, { success: false, error: `Studio connection ${connectionId} is not connected` });
-        return;
-      }
-      this.sendResponse(controllerWs, msg.id, { success: true, connectionId });
-      return;
-    }
-    this.sendResponse(controllerWs, msg.id, { error: `Unsupported controller message: ${msg.type}` });
-  }
-  handleStudioMessage(ws, msg) {
-    if (msg.type === StudioMsg.RESPONSE) {
-      const relay = this.relayRequests.get(msg.id);
-      if (relay) {
-        if (relay.targetWs !== ws) {
-          this.emit("server:error", new Error(`Ignored relayed response ${msg.id} from the wrong Studio session`));
-          return;
-        }
-        this.sendSafe(relay.controllerWs, msg);
-        this.relayRequests.delete(msg.id);
-        return;
-      }
-      const pending = this.pendingRequests.get(msg.id);
-      if (pending) {
-        if (pending.targetWs !== ws) {
-          this.emit("server:error", new Error(`Ignored response ${msg.id} from the wrong Studio session`));
-          return;
-        }
-        clearTimeout(pending.timer);
-        this.pendingRequests.delete(msg.id);
-        pending.resolve(msg);
-      }
-      return;
-    }
-    this.emit(msg.type, msg.payload);
-    this.emit("message", msg);
+
+// src/transport/daemon-launcher.ts
+function resolveDaemonPath() {
+  const besideEntry = fileURLToPath(new URL("./bridge-daemon.js", import.meta.url));
+  if (fs4.existsSync(besideEntry)) return besideEntry;
+  const projectBuild = path4.resolve(
+    path4.dirname(fileURLToPath(import.meta.url)),
+    "../../dist/bridge-daemon.js"
+  );
+  if (fs4.existsSync(projectBuild)) return projectBuild;
+  throw new Error("Dominus bridge daemon is missing. Reinstall or rebuild dominus-cli.");
+}
+function launchBridgeDaemon(port, daemonPath = resolveDaemonPath()) {
+  const child = spawn(process.execPath, [daemonPath], {
+    detached: true,
+    env: { ...process.env, DOMINUS_BRIDGE_PORT: String(port) },
+    stdio: "ignore",
+    windowsHide: true
+  });
+  child.unref();
+}
+async function connectController(port, timeoutMs, token) {
+  const client = new DominusClient(port, { connectTimeoutMs: timeoutMs, token });
+  try {
+    await client.connect();
+    return client;
+  } catch (error) {
+    await client.stop().catch(() => void 0);
+    throw error;
   }
-  cleanupSocket(ws) {
-    const role = this.socketRoles.get(ws);
-    this.socketRoles.delete(ws);
-    this.rateState.delete(ws);
-    if (role === "controller") {
-      this.controllers.delete(ws);
-      for (const [id, relay] of this.relayRequests) {
-        if (relay.controllerWs === ws) this.relayRequests.delete(id);
-      }
-      return;
-    }
-    const connectionId = this.wsToConnectionId.get(ws);
-    if (!connectionId) return;
-    const connection = this.studioClients.get(connectionId);
-    this.wsToConnectionId.delete(ws);
-    this.studioClients.delete(connectionId);
-    for (const [id, pending] of this.pendingRequests) {
-      if (pending.targetWs === ws) {
-        clearTimeout(pending.timer);
-        pending.reject(new Error(`Studio disconnected (${connectionId})`));
-        this.pendingRequests.delete(id);
-      }
-    }
-    for (const [id, relay] of this.relayRequests) {
-      if (relay.targetWs === ws) {
-        this.sendResponse(relay.controllerWs, id, { error: `Studio disconnected (${connectionId})` });
-        this.relayRequests.delete(id);
-      }
-    }
-    if (this.activeConnectionId === connectionId) {
-      this.activeConnectionId = this.studioClients.size === 1 ? this.studioClients.keys().next().value ?? null : null;
-    }
-    const info = connection ? this.toPlaceInfo(connection) : { connectionId };
-    this.emit("studio:disconnected", info);
-    this.broadcastToControllers(StudioMsg.DISCONNECTED, info);
-    this.broadcastTargetState();
-  }
-  resolveConnection(connectionId = this.activeConnectionId) {
-    if (connectionId) {
-      const connection = this.studioClients.get(connectionId);
-      return connection?.ws.readyState === WebSocket.OPEN ? connection : null;
-    }
-    if (this.studioClients.size === 1) {
-      const connection = this.studioClients.values().next().value;
-      return connection?.ws.readyState === WebSocket.OPEN ? connection : null;
+}
+async function ensureBridgeDaemon(port, options = {}) {
+  const attempts = options.attempts ?? 30;
+  const connectTimeoutMs = options.connectTimeoutMs ?? 750;
+  const retryDelayMs = options.retryDelayMs ?? 100;
+  try {
+    return await connectController(port, connectTimeoutMs, options.token);
+  } catch (initialError) {
+    if (await isPortInUse(port)) {
+      throw new Error(
+        `Port ${port} is occupied by a process that is not this Dominus bridge: ${formatError(initialError)}`
+      );
     }
-    return null;
-  }
-  getTargetError() {
-    if (this.studioClients.size === 0) return "No authenticated Roblox Studio connection";
-    if (this.activeConnectionId) return `Studio connection ${this.activeConnectionId} is unavailable`;
-    return "Multiple Studio sessions are connected. Call dominus_select_studio with a connectionId.";
-  }
-  toPlaceInfo(connection) {
-    return {
-      placeId: connection.placeId ?? 0,
-      connectionId: connection.connectionId,
-      clientId: connection.clientId,
-      placeName: connection.placeName,
-      studioVersion: connection.studioVersion,
-      connectedAt: connection.connectedAt,
-      active: connection.connectionId === this.activeConnectionId
-    };
-  }
-  broadcastToControllers(type, payload) {
-    const message = createMessage(type, payload);
-    for (const controller of this.controllers) this.sendSafe(controller, message);
-  }
-  broadcastTargetState() {
-    this.broadcastToControllers(ControllerMsg.TARGET_STATE, {
-      connections: this.listConnections(),
-      defaultActiveConnectionId: this.activeConnectionId
-    });
-  }
-  sendResponse(ws, id, payload) {
-    this.sendSafe(ws, { id, type: StudioMsg.RESPONSE, payload, ts: Date.now() });
   }
-  sendSafe(ws, message) {
-    if (ws.readyState !== WebSocket.OPEN) return;
+  const launch = options.launch ?? ((targetPort) => launchBridgeDaemon(targetPort, options.daemonPath));
+  launch(port);
+  let lastError;
+  for (let attempt = 0; attempt < attempts; attempt += 1) {
+    await new Promise((resolve) => setTimeout(resolve, retryDelayMs));
     try {
-      ws.send(serializeMessage(message));
-    } catch (err) {
-      this.emit("server:error", err);
-    }
-  }
-  sendRequest(type, payload, timeoutMs = 15e3) {
-    return new Promise((resolve, reject) => {
-      const target = this.resolveConnection();
-      if (!target) {
-        reject(new Error(this.getTargetError()));
-        return;
-      }
-      const message = createMessage(type, payload);
-      const timer = setTimeout(() => {
-        this.pendingRequests.delete(message.id);
-        reject(new Error(`Studio request timed out: ${type}`));
-      }, timeoutMs);
-      this.pendingRequests.set(message.id, {
-        resolve,
-        reject,
-        timer,
-        targetWs: target.ws
-      });
-      this.sendSafe(target.ws, message);
-    });
-  }
-  sendNotification(type, payload) {
-    const target = this.resolveConnection();
-    if (target) this.sendSafe(target.ws, createMessage(type, payload));
-  }
-  isConnected() {
-    return this.resolveConnection() !== null;
-  }
-  getConnectionInfo() {
-    return this.resolveConnection();
-  }
-  listConnections() {
-    return [...this.studioClients.values()].filter(({ ws }) => ws.readyState === WebSocket.OPEN).map((connection) => this.toPlaceInfo(connection));
-  }
-  getActiveConnectionId() {
-    return this.activeConnectionId;
-  }
-  async setActiveConnectionId(connectionId) {
-    if (connectionId && !this.studioClients.has(connectionId)) {
-      throw new Error(`Studio connection ${connectionId} is not connected`);
-    }
-    this.activeConnectionId = connectionId;
-    this.broadcastTargetState();
-  }
-  getActivePlaceId() {
-    return this.resolveConnection()?.placeId ?? 0;
-  }
-  setActivePlaceId(placeId) {
-    if (placeId === 0) {
-      this.activeConnectionId = null;
-      return;
-    }
-    const matches = [...this.studioClients.values()].filter((connection) => connection.placeId === placeId);
-    if (matches.length !== 1) {
-      throw new Error(matches.length === 0 ? `Place ${placeId} is not connected` : `Place ${placeId} has multiple Studio sessions; select a connectionId instead`);
+      return await connectController(port, connectTimeoutMs, options.token);
+    } catch (error) {
+      lastError = error;
     }
-    this.activeConnectionId = matches[0].connectionId;
-  }
-  getPort() {
-    return this.port;
-  }
-  stop() {
-    return new Promise((resolve) => {
-      for (const pending of this.pendingRequests.values()) {
-        clearTimeout(pending.timer);
-        pending.reject(new Error("Dominus bridge is shutting down"));
-      }
-      this.pendingRequests.clear();
-      this.relayRequests.clear();
-      for (const ws of this.socketRoles.keys()) ws.close(1001, "Dominus bridge shutdown");
-      this.studioClients.clear();
-      this.controllers.clear();
-      this.socketRoles.clear();
-      this.wsToConnectionId.clear();
-      if (this.wss) this.wss.close(() => resolve());
-      else resolve();
-    });
   }
-};
-function validateStudioHello(payload) {
-  if (!payload || typeof payload !== "object") throw new Error("Invalid Studio hello payload");
-  const hello = payload;
-  if (hello.protocolVersion !== DOMINUS_PROTOCOL_VERSION) {
-    throw new Error(`Studio plugin protocol ${hello.protocolVersion ?? "unknown"} is incompatible; expected ${DOMINUS_PROTOCOL_VERSION}`);
-  }
-  if (typeof hello.clientId !== "string" || hello.clientId.length < 8 || hello.clientId.length > 128) {
-    throw new Error("Studio hello is missing a valid clientId");
-  }
-  if (typeof hello.studioVersion !== "string" || hello.studioVersion.length > 128) {
-    throw new Error("Studio hello is missing studioVersion");
-  }
-  if (hello.placeName && hello.placeName.length > 256) throw new Error("Studio placeName is too long");
-  return hello;
+  throw new Error(
+    `Dominus could not start its local Studio bridge on port ${port}: ${formatError(lastError)}`
+  );
 }
-function rawByteLength(raw) {
-  if (typeof raw === "string") return Buffer.byteLength(raw);
-  if (Array.isArray(raw)) return raw.reduce((total, item) => total + item.byteLength, 0);
-  return raw.byteLength;
+function formatError(error) {
+  return error instanceof Error ? error.message : String(error ?? "unknown error");
 }
 
 // src/mcp/instructions.ts
 var DOMINUS_MCP_INSTRUCTIONS = `Dominus 2 is a Roblox Studio engineering MCP server.
 
 Required workflow for Studio changes:
-1. Call dominus_status and select the intended Studio connection when more than one is open.
+1. Call dominus_status. If Studio is disconnected, ask the user to run dominus-install-plugin only when the Studio Output reports an authentication failure. Select the intended authenticated Studio connection when more than one window is open.
 2. Inspect the relevant tree, selection, instances, scripts, and Roblox API references before editing.
 3. Form a short plan with explicit acceptance checks.
 4. Use stable instance refs returned by Dominus. Prefer instanceId; retain pathSegments as fallback context.
@@ -891,11 +569,18 @@ Required workflow for Studio changes:
 
 For broad tasks with independent Studio branches, prefer run_parallel_task when the MCP client supports Sampling. Dominus partitions immediate child scopes, runs proposal-only workers concurrently, rejects unknown refs and overlapping writes, applies only the coordinator-approved atomic plan, and reads the result back. Use the normal workflow when Sampling is unavailable or the task is a simple edit.
 
+Building workflow:
+- Use studio_create_parts for multi-part structures instead of many generic create operations.
+- Use studio_clone_instances when an existing instance or model is the intended template. Clone rather than manually recreating descendants and properties.
+- Use studio_transform_instances for Models and BaseParts so model layouts move through PVInstance pivots.
+- Use studio_group_instances and studio_ungroup_instances to organize hierarchy, studio_create_welds for rigid assemblies, and studio_query_parts to inspect crowded 3D regions before editing.
+- Use studio_set_selection when surfacing completed objects to the Studio user.
+
 Safety rules:
 - Never invent instance IDs or Roblox API members.
 - Do not retry a failed write unchanged. Inspect the error and current state first.
 - Deletion is a separate destructive tool and requires explicit user intent.
-- studio_apply is transactional. Keep related edits together, but stay within its documented limits.
+- studio_apply is transactional and supports setProperties, create, clone, and move operations. Keep related edits together, but stay within its documented limits.
 - UI fidelity work must snapshot and inspect the result after building; verify fonts, UDim2 values, colors, strokes, and hierarchy.
 - Dominus intentionally has no arbitrary Luau execution tool.`;
 
@@ -962,6 +647,8 @@ function failure(error, data) {
     data
   });
 }
+
+// src/mcp/tools/shared.ts
 var instanceRefSchema = z.object({
   instanceId: z.string().uuid().optional(),
   pathSegments: z.array(z.string().min(1).max(256)).min(1).max(100).optional()
@@ -994,7 +681,245 @@ function ref(value) {
   return value;
 }
 
-// src/mcp/tools/connections.ts
+// src/mcp/tools/building.ts
+var finiteNumber = z.number().finite();
+var vector3Schema = z.object({ x: finiteNumber, y: finiteNumber, z: finiteNumber }).strict();
+var propertiesSchema = z.record(z.unknown()).refine(
+  (properties) => Object.keys(properties).length <= 100 && !Object.keys(properties).some((name) => ["Parent", "ClassName", "Source"].includes(name)),
+  "At most 100 properties are allowed; Parent, ClassName, and Source require dedicated operations"
+);
+var partSchema = z.object({
+  name: z.string().min(1).max(100),
+  className: z.enum([
+    "Part",
+    "WedgePart",
+    "CornerWedgePart",
+    "TrussPart",
+    "MeshPart",
+    "SpawnLocation",
+    "Seat",
+    "VehicleSeat"
+  ]).optional().default("Part"),
+  shape: z.enum(["Block", "Ball", "Cylinder", "Wedge", "CornerWedge"]).optional(),
+  position: vector3Schema.optional(),
+  orientation: vector3Schema.optional(),
+  size: vector3Schema.optional(),
+  color: z.string().min(1).max(100).optional(),
+  material: z.string().min(1).max(100).optional(),
+  transparency: z.number().min(0).max(1).optional(),
+  anchored: z.boolean().optional().default(true),
+  canCollide: z.boolean().optional(),
+  properties: propertiesSchema.optional()
+});
+var cloneRequestSchema = z.object({
+  target: instanceRefSchema,
+  parent: instanceRefSchema.optional(),
+  name: z.string().min(1).max(100).optional(),
+  count: z.number().int().min(1).max(50).optional().default(1),
+  offset: vector3Schema.optional(),
+  stepOffset: vector3Schema.optional(),
+  properties: propertiesSchema.optional()
+});
+var cframeSchema = z.array(finiteNumber).refine((value) => value.length === 3 || value.length === 12, "CFrame requires 3 or 12 numbers");
+var transformOperationSchema = z.object({
+  target: instanceRefSchema,
+  mode: z.enum(["absolute", "relative"]).optional().default("absolute"),
+  cframe: cframeSchema.optional(),
+  position: vector3Schema.optional(),
+  orientation: vector3Schema.optional(),
+  offset: vector3Schema.optional(),
+  rotationOffset: vector3Schema.optional(),
+  space: z.enum(["world", "local"]).optional().default("world")
+}).refine(
+  (value) => value.mode === "relative" ? Boolean(value.offset || value.rotationOffset) : Boolean(value.cframe || value.position || value.orientation),
+  "Absolute transforms require cframe, position, or orientation; relative transforms require offset or rotationOffset"
+);
+function registerBuildingTools(server, bridge) {
+  server.registerTool(
+    "studio_create_parts",
+    {
+      title: "Build Roblox Parts",
+      description: "Create up to 200 typed BaseParts in one undoable batch, optionally grouped under a new Model or Folder. Supports positions, orientations, sizes, colors, materials, shapes, and additional writable properties.",
+      inputSchema: {
+        parent: instanceRefSchema.optional(),
+        groupName: z.string().min(1).max(100).optional(),
+        groupClass: z.enum(["Model", "Folder"]).optional().default("Model"),
+        parts: z.array(partSchema).min(1).max(200)
+      },
+      outputSchema: toolOutputSchema,
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false
+      }
+    },
+    ({ parent, groupName, groupClass, parts }) => callStudio(bridge, CliMsg.V2_CREATE_PARTS, { parent, groupName, groupClass, parts }, 12e4)
+  );
+  server.registerTool(
+    "studio_clone_instances",
+    {
+      title: "Clone Roblox Instances",
+      description: "Deep-clone instances and descendants with Instance:Clone(), optionally rename, reparent, override root properties, and create repeated spatial copies using offsets. The entire request is undoable and rolls back on failure.",
+      inputSchema: { requests: z.array(cloneRequestSchema).min(1).max(100) },
+      outputSchema: toolOutputSchema,
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false
+      }
+    },
+    ({ requests }) => callStudio(bridge, CliMsg.V2_CLONE_INSTANCES, { requests }, 12e4)
+  );
+  server.registerTool(
+    "studio_group_instances",
+    {
+      title: "Group Roblox Instances",
+      description: "Create a Model or Folder and move up to 100 independent instances into it in one undoable operation.",
+      inputSchema: {
+        targets: z.array(instanceRefSchema).min(1).max(100),
+        name: z.string().min(1).max(100),
+        className: z.enum(["Model", "Folder"]).optional().default("Model"),
+        parent: instanceRefSchema.optional()
+      },
+      outputSchema: toolOutputSchema,
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false
+      }
+    },
+    ({ targets, name, className, parent }) => callStudio(bridge, CliMsg.V2_GROUP_INSTANCES, { targets, name, className, parent }, 6e4)
+  );
+  server.registerTool(
+    "studio_ungroup_instances",
+    {
+      title: "Ungroup Roblox Instances",
+      description: "Move every child out of up to 20 Models or Folders, then remove the empty containers in one undoable operation.",
+      inputSchema: {
+        targets: z.array(instanceRefSchema).min(1).max(20),
+        parent: instanceRefSchema.optional(),
+        confirm: z.literal(true)
+      },
+      outputSchema: toolOutputSchema,
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: false
+      }
+    },
+    ({ targets, parent, confirm }) => callStudio(bridge, CliMsg.V2_UNGROUP_INSTANCES, { targets, parent, confirm }, 6e4)
+  );
+  server.registerTool(
+    "studio_transform_instances",
+    {
+      title: "Transform Roblox Models and Parts",
+      description: "Move or rotate up to 100 Models and BaseParts through PVInstance:PivotTo. Supports exact absolute CFrames and world/local relative offsets without breaking model layouts.",
+      inputSchema: { operations: z.array(transformOperationSchema).min(1).max(100) },
+      outputSchema: toolOutputSchema,
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false
+      }
+    },
+    ({ operations }) => callStudio(bridge, CliMsg.V2_TRANSFORM_INSTANCES, { operations }, 6e4)
+  );
+  server.registerTool(
+    "studio_create_welds",
+    {
+      title: "Create Roblox Welds",
+      description: "Create up to 200 WeldConstraints between explicit BasePart refs in one undoable operation.",
+      inputSchema: {
+        welds: z.array(
+          z.object({
+            part0: instanceRefSchema,
+            part1: instanceRefSchema,
+            name: z.string().min(1).max(100).optional(),
+            parent: instanceRefSchema.optional()
+          })
+        ).min(1).max(200)
+      },
+      outputSchema: toolOutputSchema,
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false
+      }
+    },
+    ({ welds }) => callStudio(bridge, CliMsg.V2_CREATE_WELDS, { welds }, 6e4)
+  );
+  server.registerTool(
+    "studio_query_parts",
+    {
+      title: "Query Parts in 3D Space",
+      description: "Find BaseParts intersecting an oriented box or radius using WorldRoot spatial queries. Returns stable refs, positions, and sizes for inspection or later mutations.",
+      inputSchema: {
+        root: instanceRefSchema.optional(),
+        mode: z.enum(["box", "radius"]).optional().default("box"),
+        position: vector3Schema,
+        orientation: vector3Schema.optional(),
+        size: vector3Schema.optional(),
+        radius: z.number().finite().positive().optional(),
+        maxParts: z.number().int().min(1).max(500).optional().default(200),
+        filter: z.array(instanceRefSchema).max(100).optional(),
+        filterType: z.enum(["Include", "Exclude"]).optional().default("Exclude"),
+        respectCanCollide: z.boolean().optional().default(false)
+      },
+      outputSchema: toolOutputSchema,
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
+    ({
+      root,
+      mode,
+      position,
+      orientation,
+      size,
+      radius,
+      maxParts,
+      filter,
+      filterType,
+      respectCanCollide
+    }) => callStudio(bridge, CliMsg.V2_QUERY_PARTS, {
+      root,
+      mode,
+      position,
+      orientation,
+      size,
+      radius,
+      maxParts,
+      filter,
+      filterType,
+      respectCanCollide
+    })
+  );
+  server.registerTool(
+    "studio_set_selection",
+    {
+      title: "Set Roblox Studio Selection",
+      description: "Replace the current Studio selection with up to 200 stable instance refs. Pass an empty array to clear selection.",
+      inputSchema: { targets: z.array(instanceRefSchema).max(200) },
+      outputSchema: toolOutputSchema,
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
+    ({ targets }) => callStudio(bridge, CliMsg.V2_SET_SELECTION, { targets })
+  );
+}
 function registerConnectionTools(server, bridge) {
   server.registerTool(
     "dominus_status",
@@ -1164,10 +1089,10 @@ async function readReferenceYaml(name, kind, opts) {
   const folder = KIND_FOLDERS[kind];
   const fileName = `${name}.yaml`;
   if (localRoot) {
-    const localPath = path3.join(localRoot, folder, fileName);
-    if (fs3.existsSync(localPath)) {
+    const localPath = path4.join(localRoot, folder, fileName);
+    if (fs4.existsSync(localPath)) {
       return {
-        content: fs3.readFileSync(localPath, "utf-8"),
+        content: fs4.readFileSync(localPath, "utf-8"),
         sourceUrl: toCreatorDocsUrl(kind, name)
       };
     }
@@ -1187,11 +1112,11 @@ async function listReferenceEntries(opts) {
   if (localRoot) {
     const entries = [];
     for (const [kind, folder] of Object.entries(KIND_FOLDERS)) {
-      const dir = path3.join(localRoot, folder);
-      if (!fs3.existsSync(dir)) continue;
-      for (const file of fs3.readdirSync(dir)) {
+      const dir = path4.join(localRoot, folder);
+      if (!fs4.existsSync(dir)) continue;
+      for (const file of fs4.readdirSync(dir)) {
         if (!file.endsWith(".yaml")) continue;
-        const name = path3.basename(file, ".yaml");
+        const name = path4.basename(file, ".yaml");
         entries.push({ name, kind, score: 0, sourceUrl: toCreatorDocsUrl(kind, name) });
       }
     }
@@ -1204,7 +1129,7 @@ async function listReferenceEntries(opts) {
     const [folder, file] = rest.split("/");
     const kind = folderToKind(folder);
     if (!kind || !file) return [];
-    const name = path3.basename(file, ".yaml");
+    const name = path4.basename(file, ".yaml");
     return [{ name, kind, score: 0, sourceUrl: toCreatorDocsUrl(kind, name) }];
   });
 }
@@ -1224,19 +1149,19 @@ function resolveDocsRoot(explicitRoot) {
   const candidates = [
     explicitRoot,
     process.env.ROBLOX_CREATOR_DOCS_PATH,
-    path3.join(process.cwd(), ".tmp", "creator-docs")
+    path4.join(process.cwd(), ".tmp", "creator-docs")
   ].filter(Boolean);
   for (const candidate of candidates) {
     const normalized = normalizeDocsRoot(candidate);
-    if (normalized && fs3.existsSync(normalized)) return normalized;
+    if (normalized && fs4.existsSync(normalized)) return normalized;
   }
   return null;
 }
 function normalizeDocsRoot(root) {
-  const engineRoot = path3.join(root, "content", "en-us", "reference", "engine");
-  if (fs3.existsSync(engineRoot)) return engineRoot;
-  const directClasses = path3.join(root, "classes");
-  if (fs3.existsSync(directClasses)) return root;
+  const engineRoot = path4.join(root, "content", "en-us", "reference", "engine");
+  if (fs4.existsSync(engineRoot)) return engineRoot;
+  const directClasses = path4.join(root, "classes");
+  if (fs4.existsSync(directClasses)) return root;
   return null;
 }
 function normalizeLookupName(name) {
@@ -1522,7 +1447,7 @@ function registerDocsTools(server) {
     }
   );
 }
-var propertiesSchema = z.record(z.unknown()).refine(
+var propertiesSchema2 = z.record(z.unknown()).refine(
   (properties) => Object.keys(properties).length <= 100 && !Object.keys(properties).some((name) => ["Parent", "ClassName", "Source"].includes(name)),
   "At most 100 properties are allowed; Parent, ClassName, and Source require dedicated operations"
 );
@@ -1530,19 +1455,27 @@ var mutationOperationSchema = z.discriminatedUnion("op", [
   z.object({
     op: z.literal("setProperties"),
     target: instanceRefSchema,
-    properties: propertiesSchema
+    properties: propertiesSchema2
   }),
   z.object({
     op: z.literal("create"),
     parent: instanceRefSchema,
     className: z.string().min(1).max(100),
     name: z.string().min(1).max(256),
-    properties: propertiesSchema.optional()
+    properties: propertiesSchema2.optional()
   }),
   z.object({
     op: z.literal("move"),
     target: instanceRefSchema,
     parent: instanceRefSchema
+  }),
+  z.object({
+    op: z.literal("clone"),
+    target: instanceRefSchema,
+    parent: instanceRefSchema,
+    name: z.string().min(1).max(100),
+    offset: z.object({ x: z.number().finite(), y: z.number().finite(), z: z.number().finite() }).optional(),
+    properties: propertiesSchema2.optional()
   })
 ]);
 var workerProposalSchema = z.object({
@@ -1771,7 +1704,7 @@ async function runWorker(server, bridge, goal, assignment, constraints, taskType
         systemPrompt: [
           "You are a read-only Dominus worker. Inspect only the Studio evidence in the request.",
           "You cannot write to Studio. Return one strict JSON WorkerProposal and no Markdown.",
-          "Only propose setProperties, create, or move operations using exact instance refs copied from evidence.",
+          "Only propose setProperties, create, clone, or move operations using exact instance refs copied from evidence.",
           "Never invent instanceId values. Never propose delete, script edits, or arbitrary execution."
         ].join(" "),
         messages: [
@@ -1802,6 +1735,13 @@ async function runWorker(server, bridge, goal, assignment, constraints, taskType
                         op: "move",
                         target: { instanceId: "uuid", pathSegments: ["..."] },
                         parent: { instanceId: "uuid", pathSegments: ["..."] }
+                      },
+                      {
+                        op: "clone",
+                        target: { instanceId: "uuid", pathSegments: ["..."] },
+                        parent: { instanceId: "uuid", pathSegments: ["..."] },
+                        name: "CloneName",
+                        offset: { x: 0, y: 0, z: 0 }
                       }
                     ],
                     risks: ["string"],
@@ -1886,7 +1826,7 @@ function validateWorkerResults(results) {
 function validateOperations(assignment, operations) {
   const errors = [];
   for (const [index, operation] of operations.entries()) {
-    const refs = operation.op === "create" ? [operation.parent] : operation.op === "move" ? [operation.target, operation.parent] : [operation.target];
+    const refs = operation.op === "create" ? [operation.parent] : operation.op === "move" || operation.op === "clone" ? [operation.target, operation.parent] : [operation.target];
     for (const ref2 of refs) {
       if (!isKnownParallelRef(ref2, assignment.knownRefKeys)) {
         errors.push(`Operation ${index} references an instance absent from worker evidence`);
@@ -1905,7 +1845,7 @@ function rejectProposalConflicts(accepted) {
     const targets = item.proposal.operations.map(operationTarget);
     const conflict = claims.find(
       (claim) => targets.some(
-        (target) => target.path && claim.paths.some((path4) => parallelPathsOverlap(target.path, path4)) || claim.refKeys.includes(target.key)
+        (target) => target.path && claim.paths.some((path5) => parallelPathsOverlap(target.path, path5)) || claim.refKeys.includes(target.key)
       )
     );
     if (conflict) {
@@ -2032,12 +1972,14 @@ async function verifyPlan(bridge, rootRef, originalRoot, operations) {
   );
   const knownPaths = collectInstancePaths(originalRoot);
   const expectedCreates = operations.flatMap((operation) => {
-    if (operation.op !== "create") return [];
+    if (operation.op !== "create" && operation.op !== "clone") return [];
     const parentPath = resolveRefPath(operation.parent, knownPaths);
     return parentPath ? [pathKey([...parentPath, operation.name])] : [];
   });
-  const missingCreates = expectedCreates.filter((path4) => !paths.has(path4));
-  const inspectOperations = operations.filter((operation) => operation.op !== "create");
+  const missingCreates = expectedCreates.filter((path5) => !paths.has(path5));
+  const inspectOperations = operations.filter(
+    (operation) => operation.op !== "create" && operation.op !== "clone"
+  );
   const inspectFailures = [];
   const propertyMismatches = [];
   const moveMismatches = [];
@@ -2107,6 +2049,7 @@ function findRepairOperations(operations, verification, originalRoot) {
       const parentPath = resolveRefPath(operation.parent, knownPaths);
       return Boolean(parentPath && missingCreates.has(pathKey([...parentPath, operation.name])));
     }
+    if (operation.op === "clone") return false;
     if (operation.op === "setProperties") return mismatchedTargets.has(refLabel(operation.target));
     return mismatchedMoves.has(refLabel(operation.target));
   });
@@ -2176,7 +2119,7 @@ function isParallelRefWithinScopes(ref2, scopes) {
   return scopes.some((scope) => Boolean(ref2.instanceId && scope.instanceId === ref2.instanceId));
 }
 function operationTarget(operation) {
-  if (operation.op === "create") {
+  if (operation.op === "create" || operation.op === "clone") {
     const parentPath = operation.parent.pathSegments;
     return {
       key: `${refKey(operation.parent)}/create:${operation.name}`,
@@ -2204,8 +2147,8 @@ function resolveRefPath(ref2, known) {
   if (ref2.pathSegments) return ref2.pathSegments;
   return ref2.instanceId ? known.get(`id:${ref2.instanceId}`) : void 0;
 }
-function pathKey(path4) {
-  return path4.join("\0");
+function pathKey(path5) {
+  return path5.join("\0");
 }
 function parallelPathIsWithin(target, scope) {
   return target.length >= scope.length && scope.every((segment, index) => target[index] === segment);
@@ -2218,8 +2161,8 @@ function samePath(left, right) {
     left && right && left.length === right.length && left.every((part, index) => part === right[index])
   );
 }
-function parallelRootPathToSegments(path4) {
-  const trimmed = path4.trim();
+function parallelRootPathToSegments(path5) {
+  const trimmed = path5.trim();
   const bracketSegments = [...trimmed.matchAll(/\["((?:\\.|[^"])*)"\]/g)].map(
     (match) => JSON.parse(`"${match[1]}"`)
   );
@@ -2281,37 +2224,46 @@ function emit(server, type, data) {
 function toErrorMessage(error) {
   return error instanceof Error ? error.message : String(error);
 }
-var propertiesSchema2 = z.record(z.unknown()).refine(
+var propertiesSchema3 = z.record(z.unknown()).refine(
   (properties) => Object.keys(properties).length <= 100 && !Object.keys(properties).some((name) => ["Parent", "ClassName", "Source"].includes(name)),
   "At most 100 properties are allowed; Parent, ClassName, and Source require dedicated operations"
 );
 var setPropertiesOperation = z.object({
   op: z.literal("setProperties"),
   target: instanceRefSchema,
-  properties: propertiesSchema2
+  properties: propertiesSchema3
 });
 var createOperation = z.object({
   op: z.literal("create"),
   parent: instanceRefSchema,
   className: z.string().min(1).max(100),
   name: z.string().min(1).max(256),
-  properties: propertiesSchema2.optional()
+  properties: propertiesSchema3.optional()
 });
 var moveOperation = z.object({
   op: z.literal("move"),
   target: instanceRefSchema,
   parent: instanceRefSchema
 });
+var cloneOperation = z.object({
+  op: z.literal("clone"),
+  target: instanceRefSchema,
+  parent: instanceRefSchema.optional(),
+  name: z.string().min(1).max(100).optional(),
+  offset: z.object({ x: z.number().finite(), y: z.number().finite(), z: z.number().finite() }).optional(),
+  properties: propertiesSchema3.optional()
+});
 var mutationOperation = z.discriminatedUnion("op", [
   setPropertiesOperation,
   createOperation,
+  cloneOperation,
   moveOperation
 ]);
 var uiNodeSchema = z.lazy(
   () => z.object({
     ClassName: z.string().min(1).max(100),
     Name: z.string().min(1).max(256).optional(),
-    properties: propertiesSchema2.optional(),
+    properties: propertiesSchema3.optional(),
     Children: z.array(uiNodeSchema).max(1e3).optional()
   })
 );
@@ -2415,7 +2367,7 @@ function registerStudioTools(server, bridge) {
     "studio_apply",
     {
       title: "Apply Atomic Studio Mutations",
-      description: "Atomically set properties, create instances, and move instances. Any failed operation cancels and undoes the entire batch.",
+      description: "Atomically set properties, create instances, deep-clone instances, and move instances. Any failed operation cancels and undoes the entire batch.",
       inputSchema: { operations: z.array(mutationOperation).min(1).max(100) },
       outputSchema: toolOutputSchema,
       annotations: {
@@ -2556,7 +2508,7 @@ function registerStudioTools(server, bridge) {
 }
 
 // src/mcp/server.ts
-var VERSION = "2.2.0";
+var VERSION = "2.3.0";
 function createDominusMcpServer(bridge) {
   const server = new McpServer(
     {
@@ -2569,28 +2521,14 @@ function createDominusMcpServer(bridge) {
   );
   registerConnectionTools(server, bridge);
   registerStudioTools(server, bridge);
+  registerBuildingTools(server, bridge);
   registerParallelTaskTool(server, bridge);
   registerDocsTools(server);
   registerDominusResources(server, bridge);
   return server;
 }
 async function createStudioBridge(port) {
-  if (await isPortInUse(port)) {
-    const client = new DominusClient(port);
-    await client.connect();
-    return client;
-  }
-  const server = new DominusServer(port);
-  try {
-    await server.start();
-    return server;
-  } catch (err) {
-    const error = err;
-    if (error.code !== "EADDRINUSE") throw err;
-    const client = new DominusClient(port);
-    await client.connect();
-    return client;
-  }
+  return ensureBridgeDaemon(port);
 }
 async function startMcpServer() {
   const config = loadConfig();