dominus-cli 2.3.0 → 2.4.1

package/dist/mcp.js

@@ -74,6 +74,7 @@ var ControllerMsg = {
   WELCOME: "controller:welcome",
   RELAY: "controller:relay",
   TARGET_STATE: "controller:target_state",
+  GET_TARGET_STATE: "controller:get_target_state",
   SET_ACTIVE_CONNECTION: "controller:set_active_connection"
 };
 var CliMsg = {
@@ -117,6 +118,11 @@ var CliMsg = {
   V2_CREATE_WELDS: "studio:v2:create_welds",
   V2_QUERY_PARTS: "studio:v2:query_parts",
   V2_SET_SELECTION: "studio:v2:set_selection",
+  V2_GET_METADATA: "studio:v2:get_metadata",
+  V2_SET_ATTRIBUTES: "studio:v2:set_attributes",
+  V2_UPDATE_TAGS: "studio:v2:update_tags",
+  V2_LIST_CALLABLE_METHODS: "studio:v2:list_callable_methods",
+  V2_INVOKE_METHODS: "studio:v2:invoke_methods",
   V2_DELETE: "studio:v2:delete",
   V2_BUILD_UI: "studio:v2:build_ui",
   V2_SNAPSHOT_UI: "studio:v2:snapshot_ui",
@@ -175,16 +181,45 @@ var DominusClient = class extends EventEmitter {
   port;
   token;
   connectTimeoutMs;
+  autoReconnect;
+  reconnectDelayMs;
+  maxReconnectDelayMs;
   connections = /* @__PURE__ */ new Map();
   activeConnectionId = null;
+  connectPromise = null;
+  reconnectTimer = null;
+  nextReconnectDelayMs;
+  hasAuthenticated = false;
+  stopping = false;
   pendingRequests = /* @__PURE__ */ new Map();
   constructor(port = 18088, options = {}) {
     super();
     this.port = port;
     this.token = options.token ?? loadOrCreateBridgeToken();
     this.connectTimeoutMs = options.connectTimeoutMs ?? 8e3;
+    this.autoReconnect = options.autoReconnect ?? true;
+    this.reconnectDelayMs = options.reconnectDelayMs ?? 250;
+    this.maxReconnectDelayMs = options.maxReconnectDelayMs ?? 5e3;
+    this.nextReconnectDelayMs = this.reconnectDelayMs;
   }
   connect() {
+    if (this.ws?.readyState === WebSocket.OPEN) return Promise.resolve();
+    if (this.connectPromise) return this.connectPromise;
+    this.stopping = false;
+    this.clearReconnectTimer();
+    const attempt = this.openConnection();
+    this.connectPromise = attempt;
+    void attempt.then(
+      () => {
+        if (this.connectPromise === attempt) this.connectPromise = null;
+      },
+      () => {
+        if (this.connectPromise === attempt) this.connectPromise = null;
+      }
+    );
+    return attempt;
+  }
+  openConnection() {
     return new Promise((resolve, reject) => {
       const ws = new WebSocket(`ws://127.0.0.1:${this.port}`, {
         perMessageDeflate: false,
@@ -216,6 +251,8 @@ var DominusClient = class extends EventEmitter {
             settled = true;
             clearTimeout(timer);
             this.applyWelcome(msg.payload);
+            this.hasAuthenticated = true;
+            this.nextReconnectDelayMs = this.reconnectDelayMs;
             this.emit("server:started", { port: this.port, relay: true });
             resolve();
             return;
@@ -235,15 +272,21 @@ var DominusClient = class extends EventEmitter {
       });
       ws.on("close", () => {
         clearTimeout(timer);
-        this.ws = null;
-        this.connections.clear();
-        this.activeConnectionId = null;
+        const wasCurrentSocket = this.ws === ws;
+        if (wasCurrentSocket) {
+          this.ws = null;
+          this.connections.clear();
+          this.activeConnectionId = null;
+        }
         if (!settled) {
           settled = true;
           reject(new Error("Dominus bridge closed before authentication completed"));
         }
-        this.rejectPending(new Error("Dominus relay connection lost"));
-        this.emit("studio:disconnected");
+        if (wasCurrentSocket) {
+          this.rejectPending(new Error("Dominus relay connection lost"));
+          this.emit("studio:disconnected");
+          this.scheduleReconnect();
+        }
       });
       ws.on("error", (err) => {
         if (!settled) {
@@ -255,6 +298,26 @@ var DominusClient = class extends EventEmitter {
       });
     });
   }
+  scheduleReconnect() {
+    if (!this.autoReconnect || !this.hasAuthenticated || this.stopping || this.reconnectTimer || this.ws?.readyState === WebSocket.OPEN) {
+      return;
+    }
+    const delayMs = this.nextReconnectDelayMs;
+    this.nextReconnectDelayMs = Math.min(delayMs * 2, this.maxReconnectDelayMs);
+    const timer = setTimeout(() => {
+      if (this.reconnectTimer !== timer) return;
+      this.reconnectTimer = null;
+      if (this.stopping) return;
+      void this.connect().catch(() => this.scheduleReconnect());
+    }, delayMs);
+    timer.unref?.();
+    this.reconnectTimer = timer;
+  }
+  clearReconnectTimer() {
+    if (!this.reconnectTimer) return;
+    clearTimeout(this.reconnectTimer);
+    this.reconnectTimer = null;
+  }
   applyWelcome(payload) {
     const welcome = payload;
     this.replaceConnections(welcome.connections ?? []);
@@ -407,10 +470,28 @@ var DominusClient = class extends EventEmitter {
       active: connection.connectionId === this.activeConnectionId
     }));
   }
+  async refreshConnections() {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) await this.connect();
+    const result = await this.sendControlRequest(ControllerMsg.GET_TARGET_STATE, {});
+    this.replaceConnections(result.connections ?? []);
+    if (this.activeConnectionId && !this.connections.has(this.activeConnectionId)) {
+      this.activeConnectionId = null;
+    }
+    if (!this.activeConnectionId && result.defaultActiveConnectionId && this.connections.has(result.defaultActiveConnectionId)) {
+      this.activeConnectionId = result.defaultActiveConnectionId;
+    }
+    if (!this.activeConnectionId && this.connections.size === 1) {
+      this.activeConnectionId = this.connections.keys().next().value ?? null;
+    }
+    return this.listConnections();
+  }
   getActiveConnectionId() {
     return this.activeConnectionId;
   }
   async setActiveConnectionId(connectionId) {
+    if (connectionId && !this.connections.has(connectionId)) {
+      await this.refreshConnections();
+    }
     if (connectionId && !this.connections.has(connectionId)) {
       throw new Error(`Studio connection ${connectionId} is not connected`);
     }
@@ -444,6 +525,9 @@ var DominusClient = class extends EventEmitter {
     return this.port;
   }
   stop() {
+    this.stopping = true;
+    this.hasAuthenticated = false;
+    this.clearReconnectTimer();
     this.rejectPending(new Error("Dominus client is shutting down"));
     return new Promise((resolve) => {
       if (!this.ws) {
@@ -572,6 +656,8 @@ For broad tasks with independent Studio branches, prefer run_parallel_task when
 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_get_metadata, studio_set_attributes, and studio_update_tags for saved Instance metadata. Do not create runtime bootstrap scripts or attribute mirrors when direct tags or attributes satisfy the task.
+- Use studio_list_callable_methods before studio_invoke_methods when a task needs an Instance method not covered by a dedicated tool. Dedicated tools remain preferred for common writes.
 - 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.
@@ -580,7 +666,7 @@ 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 and supports setProperties, create, clone, and move operations. Keep related edits together, but stay within its documented limits.
+- studio_apply is transactional and supports setProperties, setAttributes, updateTags, 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.`;
 
@@ -594,23 +680,26 @@ function registerDominusResources(server, bridge) {
       description: "Current authenticated Roblox Studio sessions and selected target.",
       mimeType: "application/json"
     },
-    async (uri) => ({
-      contents: [
-        {
-          uri: uri.href,
-          mimeType: "application/json",
-          text: JSON.stringify(
-            {
-              protocolVersion: 2,
-              activeConnectionId: bridge.getActiveConnectionId(),
-              connections: bridge.listConnections()
-            },
-            null,
-            2
-          )
-        }
-      ]
-    })
+    async (uri) => {
+      const connections = bridge.refreshConnections ? await bridge.refreshConnections() : bridge.listConnections();
+      return {
+        contents: [
+          {
+            uri: uri.href,
+            mimeType: "application/json",
+            text: JSON.stringify(
+              {
+                protocolVersion: 2,
+                activeConnectionId: bridge.getActiveConnectionId(),
+                connections
+              },
+              null,
+              2
+            )
+          }
+        ]
+      };
+    }
   );
   server.registerPrompt(
     "dominus-workflow",
@@ -937,11 +1026,12 @@ function registerConnectionTools(server, bridge) {
     },
     async () => {
       try {
+        const connections = bridge.refreshConnections ? await bridge.refreshConnections() : bridge.listConnections();
         return success({
           protocolVersion: 2,
           port: bridge.getPort(),
           activeConnectionId: bridge.getActiveConnectionId(),
-          connections: bridge.listConnections()
+          connections
         });
       } catch (err) {
         return failure(err);
@@ -1447,6 +1537,260 @@ function registerDocsTools(server) {
     }
   );
 }
+var finiteNumber2 = z.number().finite();
+var vector2Value = z.object({ x: finiteNumber2, y: finiteNumber2 }).strict();
+var vector3Value = z.object({ x: finiteNumber2, y: finiteNumber2, z: finiteNumber2 }).strict();
+var color3Object = z.object({ r: finiteNumber2, g: finiteNumber2, b: finiteNumber2 }).strict();
+var color3Value = z.union([
+  z.string().min(1).max(100),
+  color3Object,
+  z.tuple([finiteNumber2, finiteNumber2, finiteNumber2])
+]);
+var cframeValue = z.array(finiteNumber2).refine((value) => value.length === 3 || value.length === 12, "CFrame requires 3 or 12 numbers");
+var numberSequenceKeypoint = z.union([
+  z.tuple([finiteNumber2, finiteNumber2]),
+  z.tuple([finiteNumber2, finiteNumber2, finiteNumber2])
+]);
+var colorSequenceKeypoint = z.tuple([finiteNumber2, color3Value]);
+var typedString = z.object({ type: z.literal("string"), value: z.string() }).strict();
+var typedBoolean = z.object({ type: z.literal("boolean"), value: z.boolean() }).strict();
+var typedNumber = z.object({ type: z.literal("number"), value: finiteNumber2 }).strict();
+var typedUDim = z.object({
+  type: z.literal("UDim"),
+  value: z.union([
+    z.object({ scale: finiteNumber2, offset: finiteNumber2 }).strict(),
+    z.tuple([finiteNumber2, finiteNumber2])
+  ])
+}).strict();
+var typedUDim2 = z.object({
+  type: z.literal("UDim2"),
+  value: z.union([
+    z.object({
+      xScale: finiteNumber2,
+      xOffset: finiteNumber2,
+      yScale: finiteNumber2,
+      yOffset: finiteNumber2
+    }).strict(),
+    z.tuple([finiteNumber2, finiteNumber2, finiteNumber2, finiteNumber2])
+  ])
+}).strict();
+var typedBrickColor = z.object({ type: z.literal("BrickColor"), value: z.string().min(1).max(100) }).strict();
+var typedColor3 = z.object({ type: z.literal("Color3"), value: color3Value }).strict();
+var typedVector2 = z.object({
+  type: z.literal("Vector2"),
+  value: z.union([vector2Value, z.tuple([finiteNumber2, finiteNumber2])])
+}).strict();
+var typedVector3 = z.object({
+  type: z.literal("Vector3"),
+  value: z.union([vector3Value, z.tuple([finiteNumber2, finiteNumber2, finiteNumber2])])
+}).strict();
+var typedCFrame = z.object({ type: z.literal("CFrame"), value: cframeValue }).strict();
+var typedNumberSequence = z.object({
+  type: z.literal("NumberSequence"),
+  value: z.union([finiteNumber2, z.array(numberSequenceKeypoint).min(1).max(100)])
+}).strict();
+var typedColorSequence = z.object({
+  type: z.literal("ColorSequence"),
+  value: z.union([color3Value, z.array(colorSequenceKeypoint).min(1).max(100)])
+}).strict();
+var typedNumberRange = z.object({
+  type: z.literal("NumberRange"),
+  value: z.union([finiteNumber2, z.tuple([finiteNumber2, finiteNumber2])])
+}).strict();
+var typedRect = z.object({
+  type: z.literal("Rect"),
+  value: z.tuple([finiteNumber2, finiteNumber2, finiteNumber2, finiteNumber2])
+}).strict();
+var typedFont = z.object({
+  type: z.literal("Font"),
+  value: z.union([
+    z.object({
+      family: z.string().min(1).max(500),
+      weight: z.string().min(1).max(100).optional(),
+      style: z.string().min(1).max(100).optional()
+    }).strict(),
+    z.object({
+      Family: z.string().min(1).max(500),
+      Weight: z.string().min(1).max(100).optional(),
+      Style: z.string().min(1).max(100).optional()
+    }).strict()
+  ])
+}).strict();
+var attributeValueSchema = z.discriminatedUnion("type", [
+  typedString,
+  typedBoolean,
+  typedNumber,
+  typedUDim,
+  typedUDim2,
+  typedBrickColor,
+  typedColor3,
+  typedVector2,
+  typedVector3,
+  typedCFrame,
+  typedNumberSequence,
+  typedColorSequence,
+  typedNumberRange,
+  typedRect,
+  typedFont
+]);
+var methodArgumentSchema = z.discriminatedUnion("type", [
+  z.object({ type: z.literal("nil") }).strict(),
+  typedString,
+  typedBoolean,
+  typedNumber,
+  typedUDim,
+  typedUDim2,
+  typedBrickColor,
+  typedColor3,
+  typedVector2,
+  typedVector3,
+  typedCFrame,
+  typedNumberSequence,
+  typedColorSequence,
+  typedNumberRange,
+  typedRect,
+  typedFont,
+  z.object({ type: z.literal("Instance"), value: instanceRefSchema }).strict()
+]);
+var callableMethodSchema = z.enum([
+  "GetAttribute",
+  "GetAttributes",
+  "GetTags",
+  "HasTag",
+  "GetFullName",
+  "IsA",
+  "IsAncestorOf",
+  "IsDescendantOf",
+  "FindFirstChild",
+  "FindFirstChildOfClass",
+  "FindFirstChildWhichIsA",
+  "FindFirstAncestor",
+  "FindFirstAncestorOfClass",
+  "FindFirstAncestorWhichIsA",
+  "GetChildren",
+  "GetDescendants",
+  "GetPivot",
+  "GetScale",
+  "GetBoundingBox",
+  "AddTag",
+  "RemoveTag",
+  "SetAttribute",
+  "PivotTo",
+  "ScaleTo"
+]);
+var attributeUpdateSchema = z.object({
+  target: instanceRefSchema,
+  set: z.array(
+    z.object({
+      name: z.string().min(1).max(100),
+      value: attributeValueSchema
+    })
+  ).max(100).optional().default([]),
+  remove: z.array(z.string().min(1).max(100)).max(100).optional().default([])
+});
+var tagUpdateSchema = z.object({
+  target: instanceRefSchema,
+  add: z.array(z.string().min(1).max(100)).max(100).optional().default([]),
+  remove: z.array(z.string().min(1).max(100)).max(100).optional().default([])
+});
+function registerMetadataTools(server, bridge) {
+  server.registerTool(
+    "studio_get_metadata",
+    {
+      title: "Get Roblox Tags and Attributes",
+      description: "Read persistent Instance tags and typed attributes for up to 100 instances. Use this instead of runtime bootstrap scripts or attribute mirrors when inspecting saved Studio metadata.",
+      inputSchema: {
+        targets: z.array(instanceRefSchema).min(1).max(100)
+      },
+      outputSchema: toolOutputSchema,
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
+    ({ targets }) => callStudio(bridge, CliMsg.V2_GET_METADATA, { targets })
+  );
+  server.registerTool(
+    "studio_set_attributes",
+    {
+      title: "Set Roblox Attributes",
+      description: "Set or remove persistent typed Instance attributes in one undoable batch. Values are explicitly typed and saved with the place; no Play-mode bootstrap is required.",
+      inputSchema: {
+        operations: z.array(attributeUpdateSchema).min(1).max(100)
+      },
+      outputSchema: toolOutputSchema,
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
+    ({ operations }) => callStudio(bridge, CliMsg.V2_SET_ATTRIBUTES, { operations }, 6e4)
+  );
+  server.registerTool(
+    "studio_update_tags",
+    {
+      title: "Update Roblox Tags",
+      description: "Add or remove persistent Instance tags in one undoable batch using Instance:AddTag and RemoveTag. Tags are saved directly in Studio and replicate normally.",
+      inputSchema: {
+        operations: z.array(tagUpdateSchema).min(1).max(100)
+      },
+      outputSchema: toolOutputSchema,
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
+    ({ operations }) => callStudio(bridge, CliMsg.V2_UPDATE_TAGS, { operations }, 6e4)
+  );
+  server.registerTool(
+    "studio_list_callable_methods",
+    {
+      title: "List Safe Instance Methods",
+      description: "List the guarded Instance methods Dominus can invoke on a specific target, including required classes, argument types, and whether each method reads or writes Studio state.",
+      inputSchema: {
+        target: instanceRefSchema
+      },
+      outputSchema: toolOutputSchema,
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
+    ({ target }) => callStudio(bridge, CliMsg.V2_LIST_CALLABLE_METHODS, { target })
+  );
+  server.registerTool(
+    "studio_invoke_methods",
+    {
+      title: "Invoke Safe Instance Methods",
+      description: "Invoke a bounded allowlist of typed Instance methods. Supports hierarchy queries, metadata methods, GetPivot/GetBoundingBox/GetScale, and undoable AddTag/RemoveTag/SetAttribute/PivotTo/ScaleTo writes. Arbitrary, destructive, yielding, network, and signal methods are blocked in the Studio plugin.",
+      inputSchema: {
+        calls: z.array(
+          z.object({
+            target: instanceRefSchema,
+            method: callableMethodSchema,
+            arguments: z.array(methodArgumentSchema).max(10).optional().default([])
+          })
+        ).min(1).max(50)
+      },
+      outputSchema: toolOutputSchema,
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false
+      }
+    },
+    ({ calls }) => callStudio(bridge, CliMsg.V2_INVOKE_METHODS, { calls }, 6e4)
+  );
+}
 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"
@@ -1476,7 +1820,9 @@ var mutationOperationSchema = z.discriminatedUnion("op", [
     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()
-  })
+  }),
+  attributeUpdateSchema.extend({ op: z.literal("setAttributes") }),
+  tagUpdateSchema.extend({ op: z.literal("updateTags") })
 ]);
 var workerProposalSchema = z.object({
   workerId: z.string().min(1).max(64),
@@ -1704,7 +2050,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, clone, or move operations using exact instance refs copied from evidence.",
+          "Only propose setProperties, setAttributes, updateTags, 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: [
@@ -1742,6 +2088,18 @@ async function runWorker(server, bridge, goal, assignment, constraints, taskType
                         parent: { instanceId: "uuid", pathSegments: ["..."] },
                         name: "CloneName",
                         offset: { x: 0, y: 0, z: 0 }
+                      },
+                      {
+                        op: "setAttributes",
+                        target: { instanceId: "uuid", pathSegments: ["..."] },
+                        set: [{ name: "PlotId", value: { type: "number", value: 1 } }],
+                        remove: []
+                      },
+                      {
+                        op: "updateTags",
+                        target: { instanceId: "uuid", pathSegments: ["..."] },
+                        add: ["Plot"],
+                        remove: []
                       }
                     ],
                     risks: ["string"],
@@ -1978,11 +2336,12 @@ async function verifyPlan(bridge, rootRef, originalRoot, operations) {
   });
   const missingCreates = expectedCreates.filter((path5) => !paths.has(path5));
   const inspectOperations = operations.filter(
-    (operation) => operation.op !== "create" && operation.op !== "clone"
+    (operation) => operation.op === "setProperties" || operation.op === "move"
   );
   const inspectFailures = [];
   const propertyMismatches = [];
   const moveMismatches = [];
+  const metadataMismatches = [];
   for (let offset = 0; offset < inspectOperations.length; offset += 20) {
     const batch = inspectOperations.slice(offset, offset + 20);
     const targets = batch.map((operation) => operation.target);
@@ -2027,8 +2386,77 @@ async function verifyPlan(bridge, rootRef, originalRoot, operations) {
       }
     });
   }
+  const metadataOperations = operations.filter(
+    (operation) => operation.op === "setAttributes" || operation.op === "updateTags"
+  );
+  for (let offset = 0; offset < metadataOperations.length; offset += 100) {
+    const batch = metadataOperations.slice(offset, offset + 100);
+    const metadata = await requestStudio(bridge, CliMsg.V2_GET_METADATA, {
+      targets: batch.map((operation) => operation.target)
+    });
+    const results = Array.isArray(metadata.results) ? metadata.results : [];
+    batch.forEach((operation, index) => {
+      const result = results[index];
+      const targetLabel = refLabel(operation.target);
+      if (!result) {
+        inspectFailures.push(`${targetLabel}: missing metadata inspection result`);
+        return;
+      }
+      if (operation.op === "setAttributes") {
+        const attributes = Array.isArray(result.attributes) ? result.attributes : [];
+        const actual = new Map(attributes.map((entry) => [String(entry.name), entry.value]));
+        for (const item of operation.set) {
+          const actualValue = actual.get(item.name);
+          if (!actual.has(item.name) || !valuesEquivalent(item.value, actualValue)) {
+            metadataMismatches.push({
+              target: targetLabel,
+              kind: "attribute",
+              name: item.name,
+              expected: item.value,
+              actual: actualValue
+            });
+          }
+        }
+        for (const name of operation.remove) {
+          if (actual.has(name)) {
+            metadataMismatches.push({
+              target: targetLabel,
+              kind: "attribute",
+              name,
+              expected: "absent",
+              actual: actual.get(name)
+            });
+          }
+        }
+      } else {
+        const tags = new Set(Array.isArray(result.tags) ? result.tags.map(String) : []);
+        for (const name of operation.add) {
+          if (!tags.has(name)) {
+            metadataMismatches.push({
+              target: targetLabel,
+              kind: "tag",
+              name,
+              expected: true,
+              actual: false
+            });
+          }
+        }
+        for (const name of operation.remove) {
+          if (tags.has(name)) {
+            metadataMismatches.push({
+              target: targetLabel,
+              kind: "tag",
+              name,
+              expected: false,
+              actual: true
+            });
+          }
+        }
+      }
+    });
+  }
   return {
-    passed: !tree.truncated && missingCreates.length === 0 && propertyMismatches.length === 0 && moveMismatches.length === 0 && inspectFailures.length === 0,
+    passed: !tree.truncated && missingCreates.length === 0 && propertyMismatches.length === 0 && moveMismatches.length === 0 && metadataMismatches.length === 0 && inspectFailures.length === 0,
     treeNodeCount: tree.nodeCount,
     treeTruncated: tree.truncated,
     expectedCreates: expectedCreates.length,
@@ -2036,6 +2464,7 @@ async function verifyPlan(bridge, rootRef, originalRoot, operations) {
     missingCreates,
     propertyMismatches,
     moveMismatches,
+    metadataMismatches,
     inspectFailures
   };
 }
@@ -2044,6 +2473,7 @@ function findRepairOperations(operations, verification, originalRoot) {
   const missingCreates = new Set(verification.missingCreates);
   const mismatchedTargets = new Set(verification.propertyMismatches.map((item) => item.target));
   const mismatchedMoves = new Set(verification.moveMismatches.map((item) => item.target));
+  const mismatchedMetadata = new Set(verification.metadataMismatches.map((item) => item.target));
   return operations.filter((operation) => {
     if (operation.op === "create") {
       const parentPath = resolveRefPath(operation.parent, knownPaths);
@@ -2051,6 +2481,9 @@ function findRepairOperations(operations, verification, originalRoot) {
     }
     if (operation.op === "clone") return false;
     if (operation.op === "setProperties") return mismatchedTargets.has(refLabel(operation.target));
+    if (operation.op === "setAttributes" || operation.op === "updateTags") {
+      return mismatchedMetadata.has(refLabel(operation.target));
+    }
     return mismatchedMoves.has(refLabel(operation.target));
   });
 }
@@ -2253,11 +2686,15 @@ var cloneOperation = z.object({
   offset: z.object({ x: z.number().finite(), y: z.number().finite(), z: z.number().finite() }).optional(),
   properties: propertiesSchema3.optional()
 });
+var setAttributesOperation = attributeUpdateSchema.extend({ op: z.literal("setAttributes") });
+var updateTagsOperation = tagUpdateSchema.extend({ op: z.literal("updateTags") });
 var mutationOperation = z.discriminatedUnion("op", [
   setPropertiesOperation,
   createOperation,
   cloneOperation,
-  moveOperation
+  moveOperation,
+  setAttributesOperation,
+  updateTagsOperation
 ]);
 var uiNodeSchema = z.lazy(
   () => z.object({
@@ -2367,7 +2804,7 @@ function registerStudioTools(server, bridge) {
     "studio_apply",
     {
       title: "Apply Atomic Studio Mutations",
-      description: "Atomically set properties, create instances, deep-clone instances, and move instances. Any failed operation cancels and undoes the entire batch.",
+      description: "Atomically set properties or typed attributes, update tags, 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: {
@@ -2493,7 +2930,7 @@ function registerStudioTools(server, bridge) {
     "studio_get_reflection",
     {
       title: "Read Live Roblox Reflection",
-      description: "Read current ReflectionService fields for a class in the connected Studio, including Type, Display category, and permission metadata.",
+      description: "Read current ReflectionService fields for a class in the connected Studio, including Type, Display category, and permission metadata. Reflection discovers APIs but does not grant call permission; use studio_list_callable_methods for that.",
       inputSchema: { className: z.string().min(1).max(100) },
       outputSchema: toolOutputSchema,
       annotations: {
@@ -2508,7 +2945,7 @@ function registerStudioTools(server, bridge) {
 }
 
 // src/mcp/server.ts
-var VERSION = "2.3.0";
+var VERSION = "2.4.0";
 function createDominusMcpServer(bridge) {
   const server = new McpServer(
     {
@@ -2522,6 +2959,7 @@ function createDominusMcpServer(bridge) {
   registerConnectionTools(server, bridge);
   registerStudioTools(server, bridge);
   registerBuildingTools(server, bridge);
+  registerMetadataTools(server, bridge);
   registerParallelTaskTool(server, bridge);
   registerDocsTools(server);
   registerDominusResources(server, bridge);