@minicor/mcp-server 4.7.0 → 4.8.0

package/dist/tools/vm.js

@@ -1,20 +1,54 @@
 import { z } from "zod";
-import { ok, text, json, NOT_CONNECTED_VM } from "../helpers.js";
-import { ldsConnection, setLdsConnection, ldsAuth, getCachedVm, getWorkspaceRegion } from "../state.js";
+import { ok, text, json, DIRECT_VM_TOOLS_DISABLED_HOSTED, } from "../helpers.js";
 import * as lds from "../lds-client.js";
 import { generateInspectScript } from "../inspect-scripts.js";
+import { fetchVmCredentials, fetchVmCredentialsSoft, resolveVmTarget, vmTargetParams, } from "../vm-target.js";
 import { registerVmDiscovery } from "./discovery.js";
 const regionParam = z
     .enum(["us", "ca"])
     .optional()
     .describe("Region (us or ca). Auto-detected from workspace if omitted.");
-function requireVM() {
-    if (!ldsConnection)
-        return text(NOT_CONNECTED_VM);
-    return null;
-}
-export function register(deps) {
-    const { server } = deps;
+const targetUserParam = z
+    .string()
+    .optional()
+    .describe("Windows account whose session runs this (broker/multi-session VMs only — REQUIRED there, MDS never picks a user). Omit on standalone VMs. vm_list_sessions shows the registered users.");
+/** A robot-user catalog entry as accepted by the VM service (MDSRegisteredUserInput). */
+const mdsRegisteredUserSchema = z.object({
+    username: z.string().describe("Local Windows account name"),
+    password: z
+        .string()
+        .optional()
+        .describe("Raw RDP password — write-only. The VM service exchanges it for a Secret Manager reference on save; it is never stored and never echoed back. Supply this or secretRef."),
+    secretRef: z
+        .string()
+        .optional()
+        .describe("Existing Google Secret Manager reference for the RDP password"),
+    resolution: z
+        .string()
+        .optional()
+        .describe("Per-user session resolution override, e.g. '1920x1080'"),
+});
+/** @param directVmTools false on the hosted stateless server — tools stay registered but point to a local install. */
+export function register(deps, directVmTools = true) {
+    const { server, state } = deps;
+    function requireDirect() {
+        if (!directVmTools)
+            return text(DIRECT_VM_TOOLS_DISABLED_HOSTED);
+        return null;
+    }
+    async function requireTarget(args) {
+        const disabled = requireDirect();
+        if (disabled)
+            return { ok: false, res: disabled };
+        const resolved = await resolveVmTarget(deps, args);
+        if (!resolved.ok)
+            return { ok: false, res: text(resolved.message) };
+        return { ok: true, target: resolved.target };
+    }
+    function refreshStoredMode(target, mode) {
+        if (state.ldsConnection?.url === target.url)
+            state.ldsConnection.mode = mode;
+    }
     // ── VM discovery ─────────────────────────────────────────────
     registerVmDiscovery(deps);
     // ── VM deployment ──────────────────────────────────────────
@@ -25,11 +59,23 @@ export function register(deps) {
         region: regionParam,
         location: z.enum(["us", "canada", "europe"]).default("us").describe("Geography — auto-selects best region by quota"),
         vmSize: z.string().default("Standard_D2s_v3").describe("Azure VM size"),
-        vmNamePrefix: z.string().optional().describe("Custom name prefix (max 15 chars, auto-generated if omitted)"),
+        vmNamePrefix: z
+            .string()
+            .describe("VM name prefix — REQUIRED by the VM service (max 15 chars, truncated if longer; a uniqueness suffix is appended)"),
         enableRecording: z.boolean().default(true),
-    }, async ({ workspaceId, region, location, vmSize, vmNamePrefix, enableRecording }) => {
+        rdpWidth: z.number().optional().describe("Preferred RDP desktop width"),
+        rdpHeight: z.number().optional().describe("Preferred RDP desktop height"),
+        mdsKeeperEnabled: z
+            .boolean()
+            .default(true)
+            .describe("Whether MDS signs robot users in automatically (multi-session keeper)"),
+        mdsRegisteredUsers: z
+            .array(mdsRegisteredUserSchema)
+            .optional()
+            .describe("Robot user catalog to seed at creation (multi-session VMs). Passwords are exchanged for Secret Manager references and never stored."),
+    }, async ({ workspaceId, region, location, vmSize, vmNamePrefix, enableRecording, rdpWidth, rdpHeight, mdsKeeperEnabled, mdsRegisteredUsers }) => {
         try {
-            const wsRegion = region ?? getWorkspaceRegion(workspaceId);
+            const wsRegion = region ?? state.getWorkspaceRegion(workspaceId);
             const authToken = deps.getAuthToken?.(wsRegion);
             if (!authToken)
                 return text("No auth token available. Please re-authenticate.");
@@ -44,12 +90,17 @@ export function register(deps) {
                     workspace_id: String(workspaceId),
                     location,
                     vm_size: vmSize,
-                    vm_name_prefix: vmNamePrefix || undefined,
+                    vm_name_prefix: vmNamePrefix,
                     exposed_ports: [1016, 3389],
                     enable_recording: enableRecording,
                     enable_queue_and_lock: false,
-                    install_laminar_service: false,
                     windows_version: "2022-datacenter",
+                    ...(rdpWidth != null ? { rdp_width: rdpWidth } : {}),
+                    ...(rdpHeight != null ? { rdp_height: rdpHeight } : {}),
+                    mds_keeper_enabled: mdsKeeperEnabled,
+                    ...(mdsRegisteredUsers?.length
+                        ? { mds_registered_users: mdsRegisteredUsers }
+                        : {}),
                 }),
             });
             if (!res.ok) {
@@ -57,11 +108,13 @@ export function register(deps) {
                 return text(`VM deployment failed (HTTP ${res.status}): ${errBody}`);
             }
             const result = await res.json();
+            // Deploy response nests the admin logon under `credentials`.
             return ok({
                 message: "VM deployment started. It takes ~5-10 minutes.",
                 vm_name: result.vm_name,
-                username: result.username,
-                password: result.password,
+                status: result.status,
+                username: result.credentials?.username,
+                password: result.credentials?.password,
                 next_steps: [
                     "Poll vm_list to check when deployment_status becomes 'deployed'",
                     "Once deployed, use install_mds_on_vm to install MDS",
@@ -74,53 +127,113 @@ export function register(deps) {
         }
     });
     // ── Connection management ─────────────────────────────────
-    server.tool("vm_connect", "Connect to a VM. Provide vmId (from vm_list) to auto-fill credentials, or provide url directly. Must be called before any other vm_* tool.", {
+    server.tool("vm_connect", "Connect to a VM. Provide vmId (from vm_list) to auto-fill credentials, or provide url directly. Discovers the MDS mode from /health: on a multi-session (broker) VM, execute/screenshot calls additionally need targetUser. The connection is remembered only by servers that outlive one call (stdio/embedded) — on the hosted server, pass vmId + workspaceId to each vm_* tool instead.", {
         vmId: z.number().optional().describe("VM ID from vm_list — auto-fills url, apiKey, serviceId"),
+        workspaceId: z
+            .number()
+            .optional()
+            .describe("Workspace that owns the VM. With vmId, resolves the VM straight from the VM service — no prior vm_list needed."),
         url: z.string().optional().describe("MDS base URL (Cloudflare Tunnel) — use this OR vmId"),
         apiKey: z.string().optional().describe("MDS API key (not needed with vmId)"),
         serviceId: z.string().optional().describe("MDS service ID (not needed with vmId)"),
-    }, async ({ vmId, url, apiKey, serviceId }) => {
+        region: regionParam,
+    }, async ({ vmId, workspaceId, url, apiKey, serviceId, region }) => {
+        const disabled = requireDirect();
+        if (disabled)
+            return disabled;
         let connectUrl = url;
         let connectApiKey = apiKey;
         let connectServiceId = serviceId;
         let vmName;
         if (vmId) {
-            const vm = getCachedVm(vmId);
-            if (!vm) {
-                return text("VM not found in cache. Run vm_list first to discover available VMs.");
+            const vm = state.getCachedVm(vmId);
+            if (vm) {
+                if (!vm.tunnel_url) {
+                    return text(`VM "${vm.vm_name}" has no tunnel URL — it may not be running.`);
+                }
+                connectUrl = vm.tunnel_url;
+                connectApiKey = vm.api_key ?? undefined;
+                connectServiceId = vm.service_id ?? undefined;
+                vmName = vm.vm_name;
+                // Redacted list (newer VM service): resolve the MDS credentials via
+                // the per-VM credentials endpoint instead of failing auth later.
+                if (!connectApiKey && vm.workspace_id) {
+                    const wsId = Number(vm.workspace_id);
+                    const creds = await fetchVmCredentialsSoft(deps, vm.workspace_id, vmId, region ??
+                        (Number.isNaN(wsId) ? undefined : state.getWorkspaceRegion(wsId)));
+                    connectApiKey = creds.apiKey;
+                    connectServiceId = connectServiceId ?? creds.serviceId;
+                }
+            }
+            else if (workspaceId !== undefined) {
+                const wsRegion = region ?? state.getWorkspaceRegion(workspaceId);
+                const resolved = await fetchVmCredentials(deps, workspaceId, vmId, wsRegion);
+                if (!resolved.ok)
+                    return text(resolved.message);
+                if (!resolved.creds.tunnelUrl) {
+                    return text(`VM ${vmId} has no tunnel URL — MDS may not be installed or running. Check vm_list, or get_install_status if an install is in flight.`);
+                }
+                connectUrl = resolved.creds.tunnelUrl;
+                connectApiKey = resolved.creds.apiKey;
+                connectServiceId = resolved.creds.serviceId;
+                vmName = resolved.creds.vmName;
             }
-            if (!vm.tunnel_url) {
-                return text(`VM "${vm.vm_name}" has no tunnel URL — it may not be running.`);
+            else {
+                return text("VM not found in cache. Run vm_list first to discover available VMs, or pass workspaceId alongside vmId to resolve it directly.");
             }
-            connectUrl = vm.tunnel_url;
-            connectApiKey = vm.api_key;
-            connectServiceId = vm.service_id;
-            vmName = vm.vm_name;
         }
         if (!connectUrl) {
             return text("Provide either vmId (from vm_list) or url to connect.");
         }
         try {
             const health = await lds.health(connectUrl);
-            setLdsConnection({
+            const mode = lds.modeFromHealth(health);
+            state.setLdsConnection({
                 url: connectUrl,
                 apiKey: connectApiKey,
                 serviceId: connectServiceId,
                 vmId,
                 vmName,
+                mode,
             });
+            const brokerMode = mode === "broker";
+            let registeredUsers;
+            if (brokerMode) {
+                try {
+                    const status = await lds.status(connectUrl, state.ldsAuth());
+                    registeredUsers = status.users.map((u) => u.user);
+                }
+                catch {
+                    /* surface users lazily via vm_list_sessions instead */
+                }
+            }
             return ok({
                 connected: true,
                 url: connectUrl,
                 vmId,
                 vmName,
+                mode,
                 authenticated: !!(connectApiKey && connectServiceId),
                 service: health,
+                ...(registeredUsers ? { registeredUsers } : {}),
                 next_steps: [
-                    "Take vm_screenshot to see the current desktop state",
-                    "Use vm_inspect_ui mode 'window_list' to see running apps",
-                    "Use the build-rpa-workflow prompt for guided automation building",
-                    "Run Python scripts via vm_execute_script (CDP for browsers, uiautomation for desktop)",
+                    ...(brokerMode
+                        ? [
+                            "This VM is a multi-session broker: EVERY vm_execute_script / vm_screenshot / debug_rpa_step call must include targetUser (MDS never picks a user itself)",
+                            "Use vm_list_sessions to see registered users and their session/agent state, then ask the user which account to target",
+                            "Use vm_start_session / vm_stop_session to manage user sessions",
+                        ]
+                        : [
+                            "Take vm_screenshot to see the current desktop state",
+                            "Use vm_inspect_ui mode 'window_list' to see running apps",
+                            "Use the build-rpa-workflow prompt for guided automation building",
+                            "Run Python scripts via vm_execute_script (CDP for browsers, uiautomation for desktop)",
+                        ]),
+                    ...(vmId !== undefined
+                        ? [
+                            `Pass vmId ${vmId}${workspaceId !== undefined ? ` + workspaceId ${workspaceId}` : " + workspaceId"} on each vm_* call to target this VM without depending on the connection persisting (required on the hosted server)`,
+                        ]
+                        : []),
                 ],
                 automation_approaches: {
                     browser: "CDP via Python websocket to Chrome on port 9222 → vm_execute_script",
@@ -134,20 +247,31 @@ export function register(deps) {
         }
     });
     server.tool("vm_disconnect", "Disconnect from the current VM", {}, async () => {
-        setLdsConnection(null);
+        const disabled = requireDirect();
+        if (disabled)
+            return disabled;
+        state.setLdsConnection(null);
         return text("Disconnected from VM.");
     });
-    server.tool("vm_status", "Check health/status of the connected VM", {}, async () => {
-        const err = requireVM();
-        if (err)
-            return err;
+    server.tool("vm_status", "Check health/status of a VM, including its MDS mode (standalone or broker)", {
+        ...vmTargetParams,
+        region: regionParam,
+    }, async ({ vmId, workspaceId, region }) => {
+        const t = await requireTarget({ vmId, workspaceId, region: region });
+        if (!t.ok)
+            return t.res;
+        const { target } = t;
         try {
-            const health = await lds.health(ldsConnection.url);
+            const health = await lds.health(target.url);
+            const mode = lds.modeFromHealth(health);
+            // Keep the stored mode fresh across MDS restarts.
+            refreshStoredMode(target, mode);
             return ok({
                 connected: true,
-                url: ldsConnection.url,
-                vmId: ldsConnection.vmId,
-                vmName: ldsConnection.vmName,
+                url: target.url,
+                vmId: target.vmId,
+                vmName: target.vmName,
+                mode,
                 ...health,
             });
         }
@@ -156,12 +280,17 @@ export function register(deps) {
         }
     });
     // ── Screenshot ────────────────────────────────────────────
-    server.tool("vm_screenshot", "Take a full-screen screenshot of the connected VM. Use for verifying actions worked and seeing the current desktop/browser state. For reading small text, prefer vm_screenshot_region.", {}, async () => {
-        const err = requireVM();
-        if (err)
-            return err;
+    server.tool("vm_screenshot", "Take a full-screen screenshot of the VM. Use for verifying actions worked and seeing the current desktop/browser state. For reading small text, prefer vm_screenshot_region. On a broker VM, pass targetUser to capture that user's session desktop.", {
+        targetUser: targetUserParam,
+        ...vmTargetParams,
+        region: regionParam,
+    }, async ({ targetUser, vmId, workspaceId, region }) => {
+        const t = await requireTarget({ vmId, workspaceId, region: region });
+        if (!t.ok)
+            return t.res;
+        const { target } = t;
         try {
-            const res = await lds.screenshot(ldsConnection.url, ldsAuth());
+            const res = await lds.screenshot(target.url, target.auth, targetUser);
             const { width, height, size_bytes, capture_duration_ms, timestamp } = res.metadata;
             return {
                 content: [
@@ -192,10 +321,17 @@ export function register(deps) {
         y: z.number().describe("Top Y coordinate"),
         width: z.number().describe("Region width in pixels"),
         height: z.number().describe("Region height in pixels"),
-    }, async ({ x, y, width, height }) => {
-        const err = requireVM();
-        if (err)
-            return err;
+        targetUser: targetUserParam,
+        ...vmTargetParams,
+        region: z
+            .enum(["us", "ca"])
+            .optional()
+            .describe("Minicor region (us or ca) the workspace lives in — NOT the screen region. Auto-detected from workspace if omitted."),
+    }, async ({ x, y, width, height, targetUser, vmId, workspaceId, region }) => {
+        const t = await requireTarget({ vmId, workspaceId, region: region });
+        if (!t.ok)
+            return t.res;
+        const { target } = t;
         const x2 = x + width;
         const y2 = y + height;
         const script = `
@@ -209,7 +345,7 @@ b64 = base64.b64encode(buf.getvalue()).decode("utf-8")
 print(json.dumps({"image": b64, "width": img.width, "height": img.height}))
 `.trim();
         try {
-            const res = await lds.execute(ldsConnection.url, script, undefined, ldsAuth());
+            const res = await lds.execute(target.url, script, { targetUser }, target.auth);
             if (!res.success) {
                 return text(`Region screenshot failed: ${res.stderr || "unknown error"}`);
             }
@@ -237,16 +373,20 @@ print(json.dumps({"image": b64, "width": img.width, "height": img.height}))
         }
     });
     // ── Script execution ──────────────────────────────────────
-    server.tool("vm_execute_script", "Execute a Python script on the VM. This is the primary tool for ALL automation: CDP websocket for browser control, uiautomation/pyautogui for desktop apps, requests/httpx for API calls. Returns stdout, stderr, exit code, and timing.", {
+    server.tool("vm_execute_script", "Execute a Python script on the VM. This is the primary tool for ALL automation: CDP websocket for browser control, uiautomation/pyautogui for desktop apps, requests/httpx for API calls. Returns stdout, stderr, exit code, and timing. On a broker VM, targetUser is required — MDS routes the script to that user's session.", {
         script: z.string().describe("Python script to execute"),
         executionId: z.string().optional().describe("Execution ID for tracking"),
         flowId: z.string().optional().describe("Flow ID for tracking"),
-    }, async ({ script, executionId, flowId }) => {
-        const err = requireVM();
-        if (err)
-            return err;
+        targetUser: targetUserParam,
+        ...vmTargetParams,
+        region: regionParam,
+    }, async ({ script, executionId, flowId, targetUser, vmId, workspaceId, region }) => {
+        const t = await requireTarget({ vmId, workspaceId, region: region });
+        if (!t.ok)
+            return t.res;
+        const { target } = t;
         try {
-            const res = await lds.execute(ldsConnection.url, script, { executionId, flowId }, ldsAuth());
+            const res = await lds.execute(target.url, script, { executionId, flowId, targetUser }, target.auth);
             return ok({
                 success: res.success,
                 exitCode: res.exitCode,
@@ -256,39 +396,241 @@ print(json.dumps({"image": b64, "width": img.width, "height": img.height}))
                 skipped: res.skipped,
                 stopped: res.stopped,
                 resultData: res.resultData,
+                // Broker attribution (absent on standalone).
+                ...(res.targetUser !== undefined ? { targetUser: res.targetUser } : {}),
             });
         }
         catch (e) {
             return text(`Execution failed: ${e.message}`);
         }
     });
-    // ── Execution status / control ────────────────────────────
-    server.tool("vm_execution_status", "Get current execution status on the VM (active script, progress, queue)", {}, async () => {
-        const err = requireVM();
-        if (err)
-            return err;
+    // ── Execution status ──────────────────────────────────────
+    // vm_execution_control is gone (MDS removed /execute/control); do not re-add.
+    server.tool("vm_execution_status", "Get current execution status on the VM (active script, progress, queue). On a broker VM the plain call returns the router-wide status for every user; pass targetUser (and optionally executionId) to read one user's live execution progress instead.", {
+        targetUser: targetUserParam,
+        executionId: z
+            .string()
+            .optional()
+            .describe("Look up progress for a specific executionId (with or without targetUser)"),
+        ...vmTargetParams,
+        region: regionParam,
+    }, async ({ targetUser, executionId, vmId, workspaceId, region }) => {
+        const t = await requireTarget({ vmId, workspaceId, region: region });
+        if (!t.ok)
+            return t.res;
+        const { target } = t;
         try {
-            const status = await lds.executionStatus(ldsConnection.url, ldsAuth());
+            // A targeted lookup routes to /execute/progress, which brokers
+            // forward to that user's agent; the untargeted call stays on
+            // /execute/status (router-wide on brokers, slots on standalone).
+            if (targetUser || executionId) {
+                const progress = await lds.executionProgress(target.url, target.auth, {
+                    targetUser,
+                    executionId,
+                });
+                return ok(progress);
+            }
+            const status = await lds.executionStatus(target.url, target.auth);
             return ok(status);
         }
         catch (e) {
             return text(`Failed to get execution status: ${e.message}`);
         }
     });
-    server.tool("vm_execution_control", "Control script execution on the VM (pause, resume, stop, skip)", {
-        command: z
-            .enum(["pause", "resume", "stop", "skip"])
-            .describe("Control command"),
-    }, async ({ command }) => {
-        const err = requireVM();
-        if (err)
-            return err;
+    // ── User sessions (multi-session / broker VMs) ─────────────
+    server.tool("vm_list_sessions", "List the registered users on a multi-session (broker) VM with their session and agent state (GET /status). Use this to pick a targetUser for vm_execute_script / vm_screenshot, or to show the user which accounts are available. Requires API-key auth (target by vmId + workspaceId, or connect with vmId or apiKey+serviceId).", {
+        ...vmTargetParams,
+        region: regionParam,
+    }, async ({ vmId, workspaceId, region }) => {
+        const t = await requireTarget({ vmId, workspaceId, region: region });
+        if (!t.ok)
+            return t.res;
+        const { target } = t;
+        try {
+            // /status only exists on brokers; probe mode so a standalone 404 reads clearly.
+            const mode = await lds.discoverMode(target.url);
+            refreshStoredMode(target, mode);
+            if (mode !== "broker") {
+                return text(`This VM runs MDS in '${mode}' mode — per-user sessions only exist on multi-session (broker) VMs. Standalone tools work without targetUser.`);
+            }
+            const status = await lds.status(target.url, target.auth);
+            return ok({
+                mode,
+                broker: status.broker,
+                users: status.users,
+                queues: status.queues,
+                hint: "Pass one of these users as targetUser to vm_execute_script / vm_screenshot / debug_rpa_step. State 'active' means a live agent; 'stopped'/'provisioned' users need vm_start_session (or any job) first.",
+            });
+        }
+        catch (e) {
+            return text(`Failed to list sessions: ${e.message}`);
+        }
+    });
+    server.tool("vm_start_session", "Start (or reconnect) a registered user's session on the connected broker VM (POST /sessions/{user}/start). Blocks until the session is up and its agent is registered. Fails with a typed error when the session keeper is disabled (session_start_disabled) or the user is not registered.", {
+        user: z.string().describe("Registered Windows account name (see vm_list_sessions)"),
+        ...vmTargetParams,
+        region: regionParam,
+    }, async ({ user, vmId, workspaceId, region }) => {
+        const t = await requireTarget({ vmId, workspaceId, region: region });
+        if (!t.ok)
+            return t.res;
+        try {
+            const result = await lds.sessionStart(t.target.url, user, t.target.auth);
+            return ok({
+                ...result,
+                hint: `Session for '${user}' is up — target it with targetUser='${user}'.`,
+            });
+        }
+        catch (e) {
+            return text(`Failed to start session for '${user}': ${e.message}`);
+        }
+    });
+    server.tool("vm_stop_session", "Disconnect a registered user's session on the connected broker VM (POST /sessions/{user}/stop). The user STAYS logged in but the session goes dark and stays dark until an explicit start or a new job re-arms it; browser jobs keep working, desktop jobs are refused while dark. The keeper-host user cannot be stopped through MDS.", {
+        user: z.string().describe("Registered Windows account name (see vm_list_sessions)"),
+        ...vmTargetParams,
+        region: regionParam,
+    }, async ({ user, vmId, workspaceId, region }) => {
+        const t = await requireTarget({ vmId, workspaceId, region: region });
+        if (!t.ok)
+            return t.res;
         try {
-            const result = await lds.executionControl(ldsConnection.url, command, ldsAuth());
+            const result = await lds.sessionStop(t.target.url, user, t.target.auth);
             return ok(result);
         }
         catch (e) {
-            return text(`Execution control failed: ${e.message}`);
+            return text(`Failed to stop session for '${user}': ${e.message}`);
+        }
+    });
+    // ── MDS configuration & service control (VM service, bearer) ──
+    server.tool("vm_get_mds_config", "Read a VM's MDS multi-session configuration and observed state from the VM service: registered robot users (with secretRef), keeper_enabled, session_resolution, live sessions, agent status, and restart/apply tracking. Workspace OWNER/ADMIN only (the service returns 403 otherwise). No VM connection needed — addresses the VM by workspaceId + vmId.", {
+        workspaceId: z.number().describe("Workspace ID"),
+        vmId: z.number().describe("VM ID from vm_list"),
+        region: regionParam,
+    }, async ({ workspaceId, vmId, region }) => {
+        try {
+            const wsRegion = region ?? state.getWorkspaceRegion(workspaceId);
+            const authToken = deps.getAuthToken?.(wsRegion);
+            if (!authToken)
+                return text("No auth token available. Please re-authenticate.");
+            const res = await fetch(`${deps.getVmServiceBase()}/workspaces/${workspaceId}/vms/${vmId}/mds-config`, { headers: { "Authorization": `Bearer ${authToken}` } });
+            if (!res.ok) {
+                const errBody = await res.text().catch(() => "");
+                if (res.status === 403) {
+                    return text(`MDS config is restricted to workspace OWNER/ADMIN (HTTP 403): ${errBody}`);
+                }
+                return text(`Failed to get MDS config (HTTP ${res.status}): ${errBody}`);
+            }
+            return ok(await res.json());
+        }
+        catch (e) {
+            return text(`Failed to get MDS config: ${e.message}`);
+        }
+    });
+    server.tool("vm_update_mds_config", "Replace a VM's MDS multi-session configuration via the VM service. registeredUsers is a FULL REPLACE of the robot-user catalog — read vm_get_mds_config first and resend every user you want to keep (existing users keep working when you resend their secretRef unchanged). New or rotated users may carry a raw password: it is exchanged for a Secret Manager reference before saving and never stored or echoed back. Saving ALWAYS queues the MDS restart that applies the config (on broker VMs only the MinicorBroker task restarts — agents and robot sessions keep running); the edit stays 'pending' until the VM next fetches its config. Workspace OWNER/ADMIN only.", {
+        workspaceId: z.number().describe("Workspace ID"),
+        vmId: z.number().describe("VM ID from vm_list"),
+        registeredUsers: z
+            .array(mdsRegisteredUserSchema)
+            .describe("The complete robot-user catalog (full replace — omitted users are removed). Each entry needs secretRef or a write-only password."),
+        keeperEnabled: z
+            .boolean()
+            .describe("Whether MDS signs robot users in automatically (gates vm_start_session and on-demand logons)"),
+        sessionResolution: z
+            .string()
+            .optional()
+            .describe("VM-level session resolution 'WxH' (e.g. '1920x1080'); omit to keep the stored value"),
+        region: regionParam,
+    }, async ({ workspaceId, vmId, registeredUsers, keeperEnabled, sessionResolution, region }) => {
+        try {
+            const wsRegion = region ?? state.getWorkspaceRegion(workspaceId);
+            const authToken = deps.getAuthToken?.(wsRegion);
+            if (!authToken)
+                return text("No auth token available. Please re-authenticate.");
+            const res = await fetch(`${deps.getVmServiceBase()}/workspaces/${workspaceId}/vms/${vmId}/mds-config`, {
+                method: "PUT",
+                headers: {
+                    "Content-Type": "application/json",
+                    "Authorization": `Bearer ${authToken}`,
+                },
+                body: JSON.stringify({
+                    registered_users: registeredUsers,
+                    keeper_enabled: keeperEnabled,
+                    ...(sessionResolution !== undefined
+                        ? { session_resolution: sessionResolution }
+                        : {}),
+                }),
+            });
+            if (!res.ok) {
+                const errBody = await res.text().catch(() => "");
+                if (res.status === 403) {
+                    return text(`MDS config is restricted to workspace OWNER/ADMIN (HTTP 403): ${errBody}`);
+                }
+                if (res.status === 502) {
+                    return text(`Password exchange failed — the stored config is untouched (HTTP 502): ${errBody}`);
+                }
+                return text(`Failed to update MDS config (HTTP ${res.status}): ${errBody}`);
+            }
+            const config = await res.json();
+            return ok({
+                ...config,
+                hint: "Saved. The MDS restart that applies this config is queued; restart_status/config_applied above track it. Check vm_get_mds_config (or vm_list_sessions once connected) to confirm the VM picked it up.",
+            });
+        }
+        catch (e) {
+            return text(`Failed to update MDS config: ${e.message}`);
+        }
+    });
+    server.tool("vm_service_control", "Control the Minicor Desktop Service on a workspace VM through the VM service (no VM connection needed). The service routes on the VM's observed install: on broker/multi-session VMs 'restart' queues a MinicorBroker-only restart applied on the next heartbeat (agents and robot sessions keep running; this also applies pending MDS config) and other actions come back manual_required; legacy standalone installs get the full start/stop/restart/redeploy flows via Azure Run Command.", {
+        workspaceId: z.number().describe("Workspace ID"),
+        vmId: z.number().describe("VM ID from vm_list"),
+        action: z
+            .enum(["start", "stop", "restart", "status", "redeploy"])
+            .describe("Service action — 'restart' is the only remote action on broker VMs"),
+        serviceVersion: z
+            .string()
+            .optional()
+            .describe("Specific MDS version to deploy (redeploy only)"),
+        enableRecording: z.boolean().optional().describe("Recording flag (redeploy only)"),
+        enableQueueAndLock: z.boolean().optional().describe("Queue-and-lock flag (redeploy only)"),
+        region: regionParam,
+    }, async ({ workspaceId, vmId, action, serviceVersion, enableRecording, enableQueueAndLock, region }) => {
+        try {
+            const wsRegion = region ?? state.getWorkspaceRegion(workspaceId);
+            const authToken = deps.getAuthToken?.(wsRegion);
+            if (!authToken)
+                return text("No auth token available. Please re-authenticate.");
+            const redeployBody = action === "redeploy" &&
+                (serviceVersion !== undefined ||
+                    enableRecording !== undefined ||
+                    enableQueueAndLock !== undefined)
+                ? {
+                    ...(serviceVersion !== undefined
+                        ? { laminar_service_version: serviceVersion }
+                        : {}),
+                    ...(enableRecording !== undefined
+                        ? { enable_recording: enableRecording }
+                        : {}),
+                    ...(enableQueueAndLock !== undefined
+                        ? { enable_queue_and_lock: enableQueueAndLock }
+                        : {}),
+                }
+                : undefined;
+            const res = await fetch(`${deps.getVmServiceBase()}/workspaces/${workspaceId}/vms/${vmId}/service/${action}`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    "Authorization": `Bearer ${authToken}`,
+                },
+                ...(redeployBody ? { body: JSON.stringify(redeployBody) } : {}),
+            });
+            if (!res.ok) {
+                const errBody = await res.text().catch(() => "");
+                return text(`Service ${action} failed (HTTP ${res.status}): ${errBody}`);
+            }
+            return ok(await res.json());
+        }
+        catch (e) {
+            return text(`Service ${action} failed: ${e.message}`);
         }
     });
     // ── UI inspection ─────────────────────────────────────────
@@ -316,10 +658,14 @@ print(json.dumps({"image": b64, "width": img.width, "height": img.height}))
             .number()
             .optional()
             .describe("Max tree depth (for element_tree, default 3)"),
-    }, async ({ mode, x, y, windowTitle, framework, depth }) => {
-        const err = requireVM();
-        if (err)
-            return err;
+        targetUser: targetUserParam,
+        ...vmTargetParams,
+        region: regionParam,
+    }, async ({ mode, x, y, windowTitle, framework, depth, targetUser, vmId, workspaceId, region }) => {
+        const t = await requireTarget({ vmId, workspaceId, region: region });
+        if (!t.ok)
+            return t.res;
+        const { target } = t;
         const script = generateInspectScript({
             mode,
             x,
@@ -329,7 +675,7 @@ print(json.dumps({"image": b64, "width": img.width, "height": img.height}))
             depth,
         });
         try {
-            const res = await lds.execute(ldsConnection.url, script, undefined, ldsAuth());
+            const res = await lds.execute(target.url, script, { targetUser }, target.auth);
             if (!res.success) {
                 return text(`UI inspection failed (exit ${res.exitCode}): ${res.stderr || res.stdout}`);
             }
@@ -345,10 +691,15 @@ print(json.dumps({"image": b64, "width": img.width, "height": img.height}))
         }
     });
     // ── Clipboard ─────────────────────────────────────────────
-    server.tool("vm_read_clipboard", "Read the current clipboard contents from the VM", {}, async () => {
-        const err = requireVM();
-        if (err)
-            return err;
+    server.tool("vm_read_clipboard", "Read the current clipboard contents from the VM", {
+        targetUser: targetUserParam,
+        ...vmTargetParams,
+        region: regionParam,
+    }, async ({ targetUser, vmId, workspaceId, region }) => {
+        const t = await requireTarget({ vmId, workspaceId, region: region });
+        if (!t.ok)
+            return t.res;
+        const { target } = t;
         const script = `
 import json
 
@@ -370,7 +721,7 @@ except ImportError:
 print(json.dumps({"clipboard": clipboard_text}))
 `.trim();
         try {
-            const res = await lds.execute(ldsConnection.url, script, undefined, ldsAuth());
+            const res = await lds.execute(target.url, script, { targetUser }, target.auth);
             if (!res.success) {
                 return text(`Clipboard read failed: ${res.stderr || "unknown error"}`);
             }
@@ -386,28 +737,63 @@ print(json.dumps({"clipboard": clipboard_text}))
         }
     });
     // ── MDS Installation ───────────────────────────────────────
+    /**
+     * Refuse legacy standalone management actions on broker VMs (live /health
+     * probe). Deliberately fails open when MDS is unreachable — being down is
+     * the normal reason to (re)install or (re)start.
+     */
+    async function refuseLegacyStandaloneAction(tunnelUrl, action, consequence) {
+        if (!tunnelUrl)
+            return null;
+        let mode;
+        try {
+            mode = await lds.discoverMode(tunnelUrl);
+        }
+        catch {
+            return null; // MDS down/unreachable — proceed with the legacy action
+        }
+        if (mode === "broker") {
+            return text(`Refusing ${action}: this VM runs MDS in broker (multi-session) mode, and ${action} is a legacy standalone action — ${consequence} ` +
+                `Use the mode-aware restart instead: vm_service_control with action 'restart' restarts only the MinicorBroker scheduled task (agents keep running and re-register), and saving the VM's MDS configuration (vm_update_mds_config) triggers that same restart. ` +
+                `See vm_list_sessions for the broker's current users/agents.`);
+        }
+        return null;
+    }
     const INSTALL_SCRIPT_URL = "https://www.minicor.com/installs/desktop-service/ps1";
     /** Escape for single-quoted PowerShell strings (only ' needs doubling). */
     const psEscape = (s) => s.replace(/'/g, "''");
     server.tool("get_mds_install_command", "Generate a pre-filled PowerShell one-liner to install Minicor Desktop Service on a VM. " +
         "Returns a command the user can paste into an elevated PowerShell window on the target machine.", {
         vmId: z.number().optional().describe("VM ID from vm_list — auto-fills serviceId and apiKey"),
+        workspaceId: z
+            .number()
+            .optional()
+            .describe("Workspace that owns the VM. With vmId, resolves credentials straight from the VM service — no prior vm_list needed."),
         serviceId: z.string().optional().describe("MDS service ID (manual override)"),
         apiKey: z.string().optional().describe("MDS API key (manual override)"),
         enableRecording: z.boolean().default(true),
         resolution: z.string().default("1280x720"),
         installerUrl: z.string().optional().describe("Override installer URL (e.g. ngrok URL for testing)"),
-    }, async ({ vmId, serviceId, apiKey, enableRecording, resolution, installerUrl }) => {
+        region: regionParam,
+    }, async ({ vmId, workspaceId, serviceId, apiKey, enableRecording, resolution, installerUrl, region }) => {
         let sid = serviceId;
         let key = apiKey;
         if (vmId) {
-            const vm = getCachedVm(vmId);
+            const vm = state.getCachedVm(vmId);
             if (vm) {
-                sid = sid || vm.service_id;
-                key = key || vm.api_key;
+                sid = sid || (vm.service_id ?? undefined);
+                key = key || (vm.api_key ?? undefined);
+            }
+            else if (workspaceId !== undefined) {
+                const wsRegion = region ?? state.getWorkspaceRegion(workspaceId);
+                const resolved = await fetchVmCredentials(deps, workspaceId, vmId, wsRegion);
+                if (!resolved.ok)
+                    return text(resolved.message);
+                sid = sid || resolved.creds.serviceId;
+                key = key || resolved.creds.apiKey;
             }
             else {
-                return text("VM not found in cache. Run vm_list first to discover available VMs.");
+                return text("VM not found in cache. Run vm_list first to discover available VMs, or pass workspaceId alongside vmId to resolve it directly.");
             }
         }
         const envVars = [];
@@ -441,28 +827,28 @@ print(json.dumps({"clipboard": clipboard_text}))
         resolution: z.string().default("1280x720"),
         installerUrl: z.string().optional().describe("Override installer URL (e.g. ngrok URL for testing)"),
     }, async ({ workspaceId, vmId, region, enableRecording, resolution, installerUrl }, extra) => {
-        const vm = getCachedVm(vmId);
-        if (!vm) {
-            return text("VM not found in cache. Run vm_list first to discover available VMs.");
+        const disabled = requireDirect();
+        if (disabled)
+            return disabled;
+        const wsRegion = region ?? state.getWorkspaceRegion(workspaceId);
+        const vm = state.getCachedVm(vmId);
+        // Resolved up front so the mode probe below still has a tunnel URL.
+        const coldCreds = vm
+            ? undefined
+            : await fetchVmCredentialsSoft(deps, workspaceId, vmId, wsRegion);
+        if (coldCreds && !coldCreds.tunnelUrl && !coldCreds.apiKey) {
+            return text(`VM ${vmId} not found: it is not in the vm_list cache, and the VM service could not resolve it in workspace ${workspaceId}.`);
         }
+        const refusal = await refuseLegacyStandaloneAction(vm?.tunnel_url ?? coldCreds?.tunnelUrl, "install_mds_on_vm", "the standalone installer replaces the broker/agent scheduled-task topology (a manual /MULTISESSION=1 install is the broker path).");
+        if (refusal)
+            return refusal;
         const scriptUrl = installerUrl || INSTALL_SCRIPT_URL;
-        const key = vm.api_key;
-        const wsRegion = region ?? getWorkspaceRegion(workspaceId);
-        // Fetch VM credentials for auto-logon (ensures active desktop session for RPA)
-        let autoLogonUser = "";
-        let autoLogonPass = "";
-        try {
-            const authToken = deps.getAuthToken?.(wsRegion);
-            if (authToken) {
-                const credRes = await fetch(`${deps.getVmServiceBase()}/workspaces/${workspaceId}/vms/${vmId}/credentials`, { headers: { "Authorization": `Bearer ${authToken}` } });
-                if (credRes.ok) {
-                    const creds = await credRes.json();
-                    autoLogonUser = creds.admin_username || "";
-                    autoLogonPass = creds.admin_password || "";
-                }
-            }
-        }
-        catch { /* credentials fetch failed, skip auto-logon */ }
+        // Fetch VM credentials for auto-logon (ensures active desktop session
+        // for RPA) and as the API-key fallback when the list was redacted.
+        const creds = coldCreds ?? (await fetchVmCredentialsSoft(deps, workspaceId, vmId, wsRegion));
+        const key = vm?.api_key ?? creds.apiKey;
+        const autoLogonUser = creds.adminUsername ?? "";
+        const autoLogonPass = creds.adminPassword ?? "";
         // Use single quotes for values that may contain special chars (&, !, }, etc.)
         const psEscape = (s) => s.replace(/'/g, "''"); // only ' needs escaping in single-quoted PS strings
         const envVars = [
@@ -560,7 +946,7 @@ print(json.dumps({"clipboard": clipboard_text}))
         region: regionParam,
     }, async ({ workspaceId, vmId, region }) => {
         try {
-            const wsRegion = region ?? getWorkspaceRegion(workspaceId);
+            const wsRegion = region ?? state.getWorkspaceRegion(workspaceId);
             const vmServiceUrl = deps.getVmServiceBase();
             const authToken = deps.getAuthToken?.(wsRegion);
             if (!authToken)
@@ -631,16 +1017,27 @@ print(json.dumps({"clipboard": clipboard_text}))
     // ── Start MDS after install ────────────────────────────────
     server.tool("start_mds_on_vm", "Start Minicor Desktop Service on an Azure VM via Azure Run Command. " +
         "Use after install_mds_on_vm when MDS installed but health check failed (Session 0 issue). " +
-        "Creates a one-shot scheduled task to launch MDS in the interactive desktop session.", {
+        "Creates a one-shot scheduled task to launch MDS in the interactive desktop session. " +
+        "STANDALONE VMs ONLY — refused when the VM's live /health.mode is broker (use the mode-aware restart there).", {
         workspaceId: z.number().describe("Workspace ID"),
         vmId: z.number().describe("VM ID from vm_list"),
         region: regionParam,
     }, async ({ workspaceId, vmId, region }) => {
-        const vm = getCachedVm(vmId);
-        if (!vm) {
-            return text("VM not found in cache. Run vm_list first.");
+        const disabled = requireDirect();
+        if (disabled)
+            return disabled;
+        const wsRegion = region ?? state.getWorkspaceRegion(workspaceId);
+        const vm = state.getCachedVm(vmId);
+        // Resolved up front so the mode probe below still has a tunnel URL.
+        const coldCreds = vm
+            ? undefined
+            : await fetchVmCredentialsSoft(deps, workspaceId, vmId, wsRegion);
+        if (coldCreds && !coldCreds.tunnelUrl && !coldCreds.apiKey) {
+            return text(`VM ${vmId} not found: it is not in the vm_list cache, and the VM service could not resolve it in workspace ${workspaceId}.`);
         }
-        const wsRegion = region ?? getWorkspaceRegion(workspaceId);
+        const refusal = await refuseLegacyStandaloneAction(vm?.tunnel_url ?? coldCreds?.tunnelUrl, "start_mds_on_vm", "it force-kills the running MDS process and relaunches the standalone entry point, which would take down the broker and its agents mid-flight.");
+        if (refusal)
+            return refusal;
         // PowerShell script that starts MDS in the interactive session
         // Uses WMI to find the logged-on user (more reliable than `query session`)
         const startScript = `