vamp-mcp 0.1.9 → 0.2.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Potentially problematic release.
This version of vamp-mcp might be problematic. Click here for more details.
- package/LICENSE +21 -21
- package/README.md +144 -107
- package/THIRD_PARTY_NOTICES.md +32 -27
- package/bin/vamp-mcp.mjs +37 -37
- package/notices/mcp-virtualbox-LICENSE +21 -21
- package/notices/mcp-virtualbox-PROVENANCE.json +37 -37
- package/package.json +51 -17
- package/runtime/backends/common/Test-Environment.ps1 +7 -6
- package/runtime/backends/common/guest-install.json +58 -0
- package/runtime/backends/common/guest_install.py +57 -0
- package/runtime/backends/common/host-support.cjs +16 -0
- package/runtime/backends/common/packer.cjs +16 -0
- package/runtime/backends/hyperv/scripts/Manage-Desktop.ps1 +40 -67
- package/runtime/backends/hyperv/scripts/Send-InstallerBoot.ps1 +25 -0
- package/runtime/backends/kvm/debian-preseed.cfg +35 -35
- package/runtime/backends/library/registry.py +77 -77
- package/runtime/backends/library/replay.py +154 -154
- package/runtime/backends/packer/answer_media.py +16 -0
- package/runtime/backends/packer/deploy-hyperv.ps1 +10 -0
- package/runtime/backends/packer/drivers.py +49 -0
- package/runtime/backends/packer/hyperv-network.ps1 +10 -0
- package/runtime/backends/packer/images.py +75 -0
- package/runtime/backends/packer/osinfo.py +113 -0
- package/runtime/backends/packer/policy.json +15 -0
- package/runtime/backends/packer/runner.py +224 -0
- package/runtime/backends/packer/templates.py +118 -0
- package/runtime/backends/packer/toolchain.py +80 -0
- package/runtime/backends/remote_ssh/server.mjs +321 -94
- package/runtime/backends/virtualbox/desktop.cjs +37 -0
- package/runtime/backends/virtualbox/display.py +101 -101
- package/runtime/backends/virtualbox/history.py +139 -139
- package/runtime/backends/virtualbox/mouse_click.py +15 -15
- package/runtime/backends/virtualbox/mouse_move.py +18 -18
- package/runtime/backends/virtualbox/profiles.json +46 -46
- package/runtime/backends/virtualbox/provision.py +238 -184
- package/runtime/backends/virtualbox/recording_listener.py +29 -29
- package/runtime/backends/virtualbox/recordings.py +39 -39
- package/runtime/backends/virtualbox/requirements.txt +7 -7
- package/runtime/backends/virtualbox/rpas/debian_first_boot/manifest.json +1 -1
- package/runtime/backends/virtualbox/rpas/debian_first_boot/run.robot +13 -13
- package/runtime/backends/virtualbox/rpas/debian_first_boot/workflow.py +75 -75
- package/runtime/backends/virtualbox/rpas/observe/manifest.json +7 -7
- package/runtime/backends/virtualbox/rpas/observe/run.robot +13 -13
- package/runtime/backends/virtualbox/rpas/observe/workflow.py +14 -14
- package/runtime/backends/virtualbox/server.mjs +440 -63
- package/runtime/backends/virtualbox/setup_windows_sdk.py +58 -58
- package/runtime/backends/virtualbox/shares.py +68 -68
- package/runtime/backends/virtualbox/snapshots.py +53 -53
- package/runtime/backends/virtualbox/transfers.py +89 -89
- package/runtime/backends/virtualbox/vnc.py +61 -61
- package/runtime/guest_keys.py +13 -13
- package/runtime/guest_setup/http/debian-preseed.cfg +39 -0
- package/runtime/guest_setup/http/postdeb.sh +94 -0
- package/runtime/guest_setup/http/postwin.ps1 +53 -0
- package/runtime/guest_setup/http/setup-all.ps1 +25 -0
- package/runtime/guest_setup/http/setup-win.cmd +7 -0
- package/runtime/guest_setup/http/setup.ps1 +44 -0
- package/runtime/guest_setup/http/setup.sh +50 -0
- package/runtime/guest_setup/kvm/setup-debian.sh +73 -0
- package/runtime/guest_setup/kvm/setup-windows.ps1 +52 -0
- package/runtime/guest_setup/recorder/README.txt +12 -8
- package/runtime/guest_setup/recorder/RECORDER-LICENSE +674 -674
- package/runtime/guest_setup/recorder/RECORDING-GUIDE.txt +31 -31
- package/runtime/guest_setup/recorder/apply-display.py +41 -41
- package/runtime/guest_setup/recorder/configure-debian-mirrors.py +62 -62
- package/runtime/guest_setup/recorder/configure-gdm.py +23 -0
- package/runtime/guest_setup/recorder/configure-session.ps1 +14 -0
- package/runtime/guest_setup/recorder/gnome-display.py +60 -60
- package/runtime/guest_setup/recorder/install-display-startup.py +67 -39
- package/runtime/guest_setup/recorder/install-hypervisor-drivers.ps1 +34 -0
- package/runtime/guest_setup/recorder/install-resolution-shortcut.ps1 +36 -0
- package/runtime/guest_setup/recorder/postwin.cmd +10 -10
- package/runtime/guest_setup/recorder/prepare-recording.py +30 -30
- package/runtime/guest_setup/recorder/recorder.zip +0 -0
- package/runtime/guest_setup/recorder/requirements-recorder.txt +2 -2
- package/runtime/guest_setup/recorder/session-policy.py +22 -0
- package/runtime/guest_setup/recorder/set-resolution-registry.ps1 +40 -0
- package/runtime/guest_setup/recorder/setup-user.py +53 -35
- package/runtime/guest_setup/recorder/setup-win.cmd +4 -11
- package/runtime/guest_setup/recorder/setup.ps1 +112 -30
- package/runtime/guest_setup/recorder/setup.sh +19 -1
- package/runtime/guest_setup/recorder/vamp-recorder.py +148 -148
- package/runtime/guest_setup/recorder/verify-recorder.py +4 -4
- package/runtime/guest_setup/recorder/windows-display.py +76 -76
- package/runtime/guest_setup/requirements.txt +2 -0
- package/runtime/guest_setup/setup-all.ps1 +35 -0
- package/runtime/guest_setup/setup-all.sh +22 -0
- package/runtime/guest_setup/vault/Install-VCRuntime.ps1 +26 -0
- package/runtime/guest_setup/vault/setup-guest-vault.ps1 +148 -0
- package/runtime/guest_setup/vault/setup-guest-vault.sh +75 -0
- package/runtime/recording_converter.py +230 -230
- package/runtime/requirements-mcp.txt +11 -11
- package/runtime/rpas/README.md +161 -161
- package/runtime/rpas/captcha_handoff/manifest.json +27 -27
- package/runtime/rpas/captcha_handoff/run.robot +16 -16
- package/runtime/rpas/captcha_handoff/workflow.py +11 -11
- package/runtime/rpas/common.resource +26 -26
- package/runtime/rpas/debian_update/manifest.json +27 -27
- package/runtime/rpas/debian_update/run.robot +17 -17
- package/runtime/rpas/debian_update/workflow.py +13 -13
- package/runtime/rpas/desktop_control/manifest.json +26 -26
- package/runtime/rpas/desktop_control/run.robot +27 -27
- package/runtime/rpas/desktop_control/workflow.py +51 -51
- package/runtime/rpas/firefox_launch/manifest.json +27 -27
- package/runtime/rpas/firefox_launch/run.robot +15 -15
- package/runtime/rpas/firefox_launch/workflow.py +25 -25
- package/runtime/rpas/firefox_naver/manifest.json +27 -27
- package/runtime/rpas/firefox_naver/run.robot +21 -21
- package/runtime/rpas/firefox_naver/workflow.py +28 -28
- package/runtime/rpas/kvm_validation/README.md +11 -11
- package/runtime/rpas/kvm_validation/manifest.json +28 -28
- package/runtime/rpas/kvm_validation/run.robot +30 -30
- package/runtime/rpas/kvm_validation/workflow.py +91 -91
- package/runtime/rpas/manifest.schema.json +105 -105
- package/runtime/rpas/naver_login/login.robot +25 -25
- package/runtime/rpas/naver_login/manifest.json +33 -33
- package/runtime/rpas/naver_login/run.robot +20 -20
- package/runtime/rpas/naver_login/workflow.py +32 -32
- package/runtime/rpas/windows_naver_recorded/README.md +24 -24
- package/runtime/rpas/windows_naver_recorded/conversion.json +25 -25
- package/runtime/rpas/windows_naver_recorded/manifest.json +28 -28
- package/runtime/rpas/windows_naver_recorded/run.robot +37 -37
- package/runtime/rpas/windows_naver_recorded/workflow.py +32 -32
- package/runtime/scripts/build_recorder_media.py +39 -39
- package/runtime/scripts/macos/setup-host.sh +126 -0
- package/runtime/scripts/remote_host_setup.sh +7 -4
- package/runtime/scripts/script_server.py +571 -0
- package/runtime/skills/vamp-rpa-ui-checks/SKILL.md +26 -0
- package/runtime/skills/vamp-rpa-ui-checks/agents/openai.yaml +4 -0
- package/runtime/skills/vamp-rpa-ui-checks/references/display.md +12 -0
- package/runtime/skills/vamp-rpa-ui-checks/references/user-guide.md +51 -0
- package/runtime/skills/vamp-ui-cleanup/SKILL.md +15 -0
- package/runtime/skills/vamp-ui-cleanup/agents/openai.yaml +4 -0
- package/runtime/skills/vamp-ui-validation/SKILL.md +27 -0
- package/runtime/skills/vamp-ui-validation/agents/openai.yaml +4 -0
- package/runtime/third_party/mcp-virtualbox/scripts/mouse_click.py +65 -65
- package/runtime/third_party/pyautogui-recorder/LICENSE +674 -674
- package/runtime/third_party/pyautogui-recorder/PROVENANCE.json +16 -16
- package/runtime/third_party/pyautogui-recorder/PyAutoGuiRecorder.py +169 -169
- package/runtime/third_party/pyautogui-recorder/README.md +53 -53
- package/runtime/scripts/build_debian_installer.py +0 -48
|
@@ -0,0 +1,571 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
"""Serve the VAMP guest setup folder over HTTP so a guest installs it with wget or curl.
|
|
3
|
+
|
|
4
|
+
The VAMP host code no longer rewrites ISO images with xorriso. Guest setup
|
|
5
|
+
scripts, the recorder bundle and the vault helpers are staged into one folder
|
|
6
|
+
and served by Python's standard library on the fixed port 8421, which is not a
|
|
7
|
+
well-known port and is unlikely to collide with another service.
|
|
8
|
+
|
|
9
|
+
VirtualBox NAT and QEMU user networking both expose the host to the guest as
|
|
10
|
+
10.0.2.2; libvirt's default NAT network exposes it as 192.168.122.1.
|
|
11
|
+
|
|
12
|
+
python3 scripts/script_server.py start # stage + start, print JSON
|
|
13
|
+
python3 scripts/script_server.py status
|
|
14
|
+
python3 scripts/script_server.py stop
|
|
15
|
+
|
|
16
|
+
Guests then run:
|
|
17
|
+
|
|
18
|
+
wget -qO- http://10.0.2.2:8421/setup.sh | sh
|
|
19
|
+
powershell -ExecutionPolicy Bypass -Command "irm http://10.0.2.2:8421/setup.ps1 | iex"
|
|
20
|
+
|
|
21
|
+
The server only serves the staged setup folder (no directory listing, no
|
|
22
|
+
dotfiles) and stops itself after --ttl seconds (default 1800) unless stopped
|
|
23
|
+
sooner.
|
|
24
|
+
"""
|
|
25
|
+
from __future__ import annotations
|
|
26
|
+
import argparse
|
|
27
|
+
import hashlib
|
|
28
|
+
import json
|
|
29
|
+
import os
|
|
30
|
+
import shutil
|
|
31
|
+
import signal
|
|
32
|
+
import socket
|
|
33
|
+
import subprocess
|
|
34
|
+
import sys
|
|
35
|
+
import tarfile
|
|
36
|
+
import tempfile
|
|
37
|
+
import threading
|
|
38
|
+
import time
|
|
39
|
+
import urllib.error
|
|
40
|
+
import urllib.request
|
|
41
|
+
import zipfile
|
|
42
|
+
from http.server import SimpleHTTPRequestHandler, ThreadingHTTPServer
|
|
43
|
+
from pathlib import Path
|
|
44
|
+
|
|
45
|
+
ROOT = Path(__file__).resolve().parents[1]
|
|
46
|
+
sys.path.insert(0,str(ROOT/'backends/common'))
|
|
47
|
+
from guest_install import PROFILE
|
|
48
|
+
SCRIPT_SERVER_PORT = PROFILE['script_server_port']
|
|
49
|
+
DEFAULT_BIND = '0.0.0.0'
|
|
50
|
+
DEFAULT_TTL = 1800
|
|
51
|
+
SERVICE = 'vamp-script-server'
|
|
52
|
+
GUEST_HOSTS = {
|
|
53
|
+
'virtualbox_nat': '10.0.2.2',
|
|
54
|
+
'kvm_user_network': '10.0.2.2',
|
|
55
|
+
'kvm_default_network': '192.168.122.1',
|
|
56
|
+
}
|
|
57
|
+
SKIP = shutil.ignore_patterns('__pycache__', '*.pyc', '.git')
|
|
58
|
+
# The recorder bundle is committed to the repository so a clean checkout, a
|
|
59
|
+
# published package or a remote host can stage guest setup without the local
|
|
60
|
+
# third_party recorder sources. This URL is the last resort when neither the
|
|
61
|
+
# sources nor the committed bundle are present.
|
|
62
|
+
RECORDER_ZIP_URL = os.environ.get(
|
|
63
|
+
'VAMP_RECORDER_ZIP_URL',
|
|
64
|
+
'https://raw.githubusercontent.com/wayfarer6/vamp-mcp/main/guest_setup/recorder/recorder.zip',
|
|
65
|
+
)
|
|
66
|
+
RECORDER_ENTRY = 'PyAutoGuiRecorder.py'
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
def state_directory() -> Path:
|
|
70
|
+
if os.environ.get('VAMP_SCRIPT_SERVER_DIR'):
|
|
71
|
+
return Path(os.environ['VAMP_SCRIPT_SERVER_DIR']).expanduser()
|
|
72
|
+
if os.environ.get('VAMP_DATA_DIR'):
|
|
73
|
+
return Path(os.environ['VAMP_DATA_DIR']).expanduser() / 'script-server'
|
|
74
|
+
return Path.home() / '.vamp' / 'script-server'
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
def _copy_tree(source: Path, destination: Path) -> None:
|
|
78
|
+
shutil.copytree(source, destination, ignore=SKIP, dirs_exist_ok=True)
|
|
79
|
+
|
|
80
|
+
|
|
81
|
+
def _add_tree(archive: tarfile.TarFile, root: Path, name: str) -> None:
|
|
82
|
+
for path in sorted(root.rglob('*')):
|
|
83
|
+
if '__pycache__' in path.parts or path.suffix == '.pyc':
|
|
84
|
+
continue
|
|
85
|
+
archive.add(path, arcname=str(Path(name) / path.relative_to(root)))
|
|
86
|
+
|
|
87
|
+
|
|
88
|
+
def _zip_tree(archive: zipfile.ZipFile, root: Path, name: str) -> None:
|
|
89
|
+
for path in sorted(root.rglob('*')):
|
|
90
|
+
if '__pycache__' in path.parts or path.suffix == '.pyc':
|
|
91
|
+
continue
|
|
92
|
+
archive.write(path, str(Path(name) / path.relative_to(root)))
|
|
93
|
+
|
|
94
|
+
|
|
95
|
+
def digest(path: Path) -> str:
|
|
96
|
+
with path.open('rb') as handle:
|
|
97
|
+
return hashlib.file_digest(handle, 'sha256').hexdigest()
|
|
98
|
+
|
|
99
|
+
|
|
100
|
+
def _recorder_zip_usable(path: Path) -> bool:
|
|
101
|
+
"""True when path is a zip that carries the recorder program itself."""
|
|
102
|
+
try:
|
|
103
|
+
with zipfile.ZipFile(path) as archive:
|
|
104
|
+
return RECORDER_ENTRY in {Path(name).name for name in archive.namelist()}
|
|
105
|
+
except (OSError, zipfile.BadZipFile):
|
|
106
|
+
return False
|
|
107
|
+
|
|
108
|
+
|
|
109
|
+
def download_recorder_zip(destination: Path, url: str = RECORDER_ZIP_URL, timeout: int = 30) -> Path:
|
|
110
|
+
"""Fetch the committed recorder bundle when no local copy exists."""
|
|
111
|
+
destination.parent.mkdir(parents=True, exist_ok=True)
|
|
112
|
+
request = urllib.request.Request(url, headers={'User-Agent': 'vamp-script-server'})
|
|
113
|
+
with urllib.request.urlopen(request, timeout=timeout) as response:
|
|
114
|
+
payload = response.read()
|
|
115
|
+
if not payload.startswith(b'PK'):
|
|
116
|
+
raise RuntimeError(f'{url} did not return a zip archive')
|
|
117
|
+
destination.write_bytes(payload)
|
|
118
|
+
if not _recorder_zip_usable(destination):
|
|
119
|
+
destination.unlink(missing_ok=True)
|
|
120
|
+
raise RuntimeError(f'{url} is not a usable recorder bundle (no {RECORDER_ENTRY})')
|
|
121
|
+
return destination
|
|
122
|
+
|
|
123
|
+
|
|
124
|
+
def ensure_recorder_zip(folder: Path, recorder_source: Path | None = None) -> Path:
|
|
125
|
+
"""Keep recorder.zip beside the recorder setup.
|
|
126
|
+
|
|
127
|
+
Order: rebuild from the packaged recorder sources, reuse the bundle that
|
|
128
|
+
ships in the repository, then download it from the project's GitHub URL.
|
|
129
|
+
"""
|
|
130
|
+
recorder_zip = folder / 'recorder.zip'
|
|
131
|
+
if recorder_source and recorder_source.is_dir():
|
|
132
|
+
folder.mkdir(parents=True, exist_ok=True)
|
|
133
|
+
with zipfile.ZipFile(recorder_zip, 'w', zipfile.ZIP_DEFLATED) as archive:
|
|
134
|
+
for path in sorted(recorder_source.rglob('*')):
|
|
135
|
+
if path.is_file() and '__pycache__' not in path.parts and path.suffix != '.pyc':
|
|
136
|
+
archive.write(path, str(path.relative_to(recorder_source)))
|
|
137
|
+
return recorder_zip
|
|
138
|
+
if _recorder_zip_usable(recorder_zip):
|
|
139
|
+
return recorder_zip
|
|
140
|
+
return download_recorder_zip(recorder_zip)
|
|
141
|
+
|
|
142
|
+
|
|
143
|
+
def stage(source: Path | None = None, destination: Path | None = None,
|
|
144
|
+
port: int = SCRIPT_SERVER_PORT) -> dict:
|
|
145
|
+
"""Build the served folder: HTTP bootstraps at the root plus the setup trees."""
|
|
146
|
+
source = Path(source or ROOT / 'guest_setup').expanduser().resolve()
|
|
147
|
+
if not (source / 'recorder' / 'setup.sh').is_file():
|
|
148
|
+
raise FileNotFoundError(f'Guest setup source is incomplete: {source}')
|
|
149
|
+
destination = Path(destination or state_directory() / 'stage').expanduser().resolve()
|
|
150
|
+
if destination.exists():
|
|
151
|
+
shutil.rmtree(destination)
|
|
152
|
+
destination.mkdir(parents=True)
|
|
153
|
+
|
|
154
|
+
http = source / 'http'
|
|
155
|
+
for name in ('setup.sh', 'postdeb.sh', 'debian-preseed.cfg'):
|
|
156
|
+
shutil.copy2(http / name, destination / name)
|
|
157
|
+
(destination / name).chmod(0o755)
|
|
158
|
+
for name in ('setup.ps1', 'setup-all.ps1', 'setup-win.cmd', 'postwin.ps1'):
|
|
159
|
+
shutil.copy2(http / name, destination / name)
|
|
160
|
+
for name in ('setup-all.sh', 'setup-all.ps1'):
|
|
161
|
+
candidate = source / name
|
|
162
|
+
if candidate.is_file():
|
|
163
|
+
shutil.copy2(candidate, destination / name)
|
|
164
|
+
for name in ('recorder', 'vault', 'kvm'):
|
|
165
|
+
if (source / name).is_dir():
|
|
166
|
+
_copy_tree(source / name, destination / name)
|
|
167
|
+
|
|
168
|
+
# Guest setups expect recorder.zip beside setup.sh: rebuild it from the
|
|
169
|
+
# packaged recorder sources, otherwise keep the bundle committed in the
|
|
170
|
+
# repository, otherwise download it so a clean environment still works.
|
|
171
|
+
recorder_source = source.parent / 'third_party' / 'pyautogui-recorder'
|
|
172
|
+
try:
|
|
173
|
+
ensure_recorder_zip(destination / 'recorder', recorder_source)
|
|
174
|
+
except (OSError, RuntimeError, urllib.error.URLError) as error:
|
|
175
|
+
# A missing recorder only disables the recording tool, so keep serving
|
|
176
|
+
# the rest of guest setup and say plainly what is missing.
|
|
177
|
+
print(f'vamp: recorder bundle unavailable: {error}', file=sys.stderr)
|
|
178
|
+
|
|
179
|
+
# Optional verified VeraCrypt CLI payload for the vault setup.
|
|
180
|
+
cli_source = source.parent / 'artifacts' / 'kvm-setup' / 'bin'
|
|
181
|
+
if (cli_source / 'SHA256SUMS').is_file() and (cli_source / 'veracrypt.tar.gz').is_file():
|
|
182
|
+
(destination / 'cli').mkdir(exist_ok=True)
|
|
183
|
+
for name in ('SHA256SUMS', 'veracrypt.tar.gz'):
|
|
184
|
+
shutil.copy2(cli_source / name, destination / 'cli' / name)
|
|
185
|
+
|
|
186
|
+
# Host checkout line endings must never leak into a Linux guest shell.
|
|
187
|
+
# Normalize before creating either archive, including nested recorder scripts.
|
|
188
|
+
for shell in destination.rglob('*.sh'):
|
|
189
|
+
shell.write_bytes(shell.read_bytes().replace(b'\r\n', b'\n'))
|
|
190
|
+
|
|
191
|
+
tar_path = destination / 'vamp-guest-setup.tar.gz'
|
|
192
|
+
with tarfile.open(tar_path, 'w:gz') as archive:
|
|
193
|
+
for name in ('recorder', 'vault', 'kvm'):
|
|
194
|
+
if (destination / name).is_dir():
|
|
195
|
+
_add_tree(archive, destination / name, name)
|
|
196
|
+
if (destination / 'cli').is_dir():
|
|
197
|
+
_add_tree(archive, destination / 'cli', 'cli')
|
|
198
|
+
for name in ('setup-all.sh', 'setup-all.ps1'):
|
|
199
|
+
if (destination / name).is_file():
|
|
200
|
+
archive.add(destination / name, arcname=name)
|
|
201
|
+
|
|
202
|
+
zip_path = destination / 'vamp-guest-setup.zip'
|
|
203
|
+
with zipfile.ZipFile(zip_path, 'w', zipfile.ZIP_DEFLATED) as archive:
|
|
204
|
+
for name in ('recorder', 'vault', 'kvm'):
|
|
205
|
+
if (destination / name).is_dir():
|
|
206
|
+
_zip_tree(archive, destination / name, name)
|
|
207
|
+
if (destination / 'cli').is_dir():
|
|
208
|
+
_zip_tree(archive, destination / 'cli', 'cli')
|
|
209
|
+
for name in ('setup-all.sh', 'setup-all.ps1'):
|
|
210
|
+
if (destination / name).is_file():
|
|
211
|
+
archive.write(destination / name, name)
|
|
212
|
+
|
|
213
|
+
commands = guest_commands(port)
|
|
214
|
+
manifest = {
|
|
215
|
+
'service': SERVICE,
|
|
216
|
+
'version': 1,
|
|
217
|
+
'port': port,
|
|
218
|
+
'guest_hosts': GUEST_HOSTS,
|
|
219
|
+
'bundles': {
|
|
220
|
+
'tar_gz': {'name': tar_path.name, 'sha256': digest(tar_path), 'bytes': tar_path.stat().st_size},
|
|
221
|
+
'zip': {'name': zip_path.name, 'sha256': digest(zip_path), 'bytes': zip_path.stat().st_size},
|
|
222
|
+
},
|
|
223
|
+
'commands': commands,
|
|
224
|
+
'note': 'Guest setup is downloaded, not installed: verify the guest after running it.',
|
|
225
|
+
}
|
|
226
|
+
(destination / 'vamp-setup.json').write_text(json.dumps(manifest, indent=2) + '\n')
|
|
227
|
+
files = sorted(
|
|
228
|
+
str(path.relative_to(destination)).replace(os.sep, '/')
|
|
229
|
+
for path in destination.rglob('*') if path.is_file()
|
|
230
|
+
)
|
|
231
|
+
return {'status': 'staged', 'directory': str(destination), 'files': files, 'manifest': manifest}
|
|
232
|
+
|
|
233
|
+
|
|
234
|
+
def guest_commands(port: int = SCRIPT_SERVER_PORT, host: str = '10.0.2.2') -> dict:
|
|
235
|
+
base = f'http://{host}:{port}'
|
|
236
|
+
return {
|
|
237
|
+
'base_url': base,
|
|
238
|
+
'debian_recorder': f'wget -qO- {base}/setup.sh | sh',
|
|
239
|
+
'debian_recorder_curl': f'curl -fsSL {base}/setup.sh | sh',
|
|
240
|
+
'debian_all': f'wget -qO- {base}/setup.sh | sh -s -- --all',
|
|
241
|
+
'windows_recorder': f'powershell -ExecutionPolicy Bypass -Command "irm {base}/setup.ps1 | iex"',
|
|
242
|
+
'windows_cmd': f'curl.exe -fsSL {base}/setup-win.cmd -o %TEMP%\\setup-win.cmd && %TEMP%\\setup-win.cmd',
|
|
243
|
+
}
|
|
244
|
+
|
|
245
|
+
|
|
246
|
+
class ScriptRequestHandler(SimpleHTTPRequestHandler):
|
|
247
|
+
"""Serve only the staged setup folder; no listings, no dotfiles, no caching."""
|
|
248
|
+
server_version = 'VAMPScriptServer/1.0'
|
|
249
|
+
extensions_map = {
|
|
250
|
+
**SimpleHTTPRequestHandler.extensions_map,
|
|
251
|
+
'.sh': 'text/plain; charset=utf-8',
|
|
252
|
+
'.ps1': 'text/plain; charset=utf-8',
|
|
253
|
+
'.cmd': 'text/plain; charset=utf-8',
|
|
254
|
+
'.json': 'application/json',
|
|
255
|
+
'.gz': 'application/gzip',
|
|
256
|
+
'.zip': 'application/zip',
|
|
257
|
+
}
|
|
258
|
+
|
|
259
|
+
def end_headers(self) -> None:
|
|
260
|
+
self.send_header('Cache-Control', 'no-store')
|
|
261
|
+
self.send_header('X-Content-Type-Options', 'nosniff')
|
|
262
|
+
super().end_headers()
|
|
263
|
+
|
|
264
|
+
def list_directory(self, path): # noqa: D401 - stdlib hook
|
|
265
|
+
self.send_error(404, 'Directory listing is disabled')
|
|
266
|
+
return None
|
|
267
|
+
|
|
268
|
+
def translate_path(self, path: str) -> str:
|
|
269
|
+
resolved = super().translate_path(path)
|
|
270
|
+
root = Path(self.directory).resolve()
|
|
271
|
+
candidate = Path(resolved).resolve()
|
|
272
|
+
if root not in candidate.parents and candidate != root:
|
|
273
|
+
return str(root / '__forbidden__')
|
|
274
|
+
if any(part.startswith('.') for part in candidate.relative_to(root).parts):
|
|
275
|
+
return str(root / '__forbidden__')
|
|
276
|
+
return str(candidate)
|
|
277
|
+
|
|
278
|
+
def do_GET(self) -> None: # noqa: N802 - stdlib name
|
|
279
|
+
if self.path.split('?', 1)[0] == '/healthz':
|
|
280
|
+
payload = json.dumps({
|
|
281
|
+
'status': 'ok',
|
|
282
|
+
'service': SERVICE,
|
|
283
|
+
'port': self.server.server_address[1],
|
|
284
|
+
'directory': str(self.server.stage_directory),
|
|
285
|
+
'started_at': self.server.started_at,
|
|
286
|
+
'ttl_seconds': self.server.ttl,
|
|
287
|
+
'lease_supported': True,
|
|
288
|
+
}).encode()
|
|
289
|
+
self.send_response(200)
|
|
290
|
+
self.send_header('Content-Type', 'application/json')
|
|
291
|
+
self.send_header('Content-Length', str(len(payload)))
|
|
292
|
+
self.end_headers()
|
|
293
|
+
self.wfile.write(payload)
|
|
294
|
+
return
|
|
295
|
+
if self.path.split('?', 1)[0] == '/':
|
|
296
|
+
self.path = '/vamp-setup.json'
|
|
297
|
+
super().do_GET()
|
|
298
|
+
|
|
299
|
+
def log_message(self, format: str, *args) -> None: # noqa: A002 - stdlib name
|
|
300
|
+
sys.stderr.write(f'{time.strftime("%Y-%m-%d %H:%M:%S")} {self.address_string()} {format % args}\n')
|
|
301
|
+
|
|
302
|
+
|
|
303
|
+
def make_server(directory: Path, port: int = SCRIPT_SERVER_PORT, bind: str = DEFAULT_BIND,
|
|
304
|
+
ttl: int = DEFAULT_TTL) -> ThreadingHTTPServer:
|
|
305
|
+
handler = lambda *args, **kwargs: ScriptRequestHandler(*args, directory=str(directory), **kwargs) # noqa: E731
|
|
306
|
+
server = ThreadingHTTPServer((bind, port), handler)
|
|
307
|
+
server.stage_directory = Path(directory)
|
|
308
|
+
server.started_at = time.strftime('%Y-%m-%dT%H:%M:%S%z')
|
|
309
|
+
server.ttl = ttl
|
|
310
|
+
return server
|
|
311
|
+
|
|
312
|
+
|
|
313
|
+
def serve(directory: Path, port: int, bind: str, ttl: int) -> int:
|
|
314
|
+
try:
|
|
315
|
+
server = make_server(directory, port, bind, ttl)
|
|
316
|
+
except OSError as error:
|
|
317
|
+
sys.stderr.write(f'Cannot listen on {bind}:{port}: {error}\n')
|
|
318
|
+
return 2
|
|
319
|
+
stopping = threading.Event()
|
|
320
|
+
|
|
321
|
+
def stop(*_args) -> None:
|
|
322
|
+
if stopping.is_set():
|
|
323
|
+
return
|
|
324
|
+
stopping.set()
|
|
325
|
+
threading.Thread(target=server.shutdown, daemon=True).start()
|
|
326
|
+
|
|
327
|
+
signal.signal(signal.SIGTERM, stop)
|
|
328
|
+
signal.signal(signal.SIGINT, stop)
|
|
329
|
+
if ttl > 0:
|
|
330
|
+
def expire_when_idle():
|
|
331
|
+
while not stopping.wait(1):
|
|
332
|
+
try:
|
|
333
|
+
deadline=float(_lease_file(port).read_text())
|
|
334
|
+
except (OSError,ValueError):
|
|
335
|
+
continue
|
|
336
|
+
if deadline and time.time() >= deadline:
|
|
337
|
+
stop()
|
|
338
|
+
threading.Thread(target=expire_when_idle,daemon=True).start()
|
|
339
|
+
sys.stderr.write(json.dumps({
|
|
340
|
+
'status': 'serving', 'service': SERVICE, 'port': server.server_address[1],
|
|
341
|
+
'bind': bind, 'directory': str(directory), 'ttl_seconds': ttl,
|
|
342
|
+
}) + '\n')
|
|
343
|
+
sys.stderr.flush()
|
|
344
|
+
try:
|
|
345
|
+
server.serve_forever(poll_interval=0.5)
|
|
346
|
+
finally:
|
|
347
|
+
server.server_close()
|
|
348
|
+
return 0
|
|
349
|
+
|
|
350
|
+
|
|
351
|
+
def _pid_file(port: int = SCRIPT_SERVER_PORT) -> Path:
|
|
352
|
+
return state_directory() / f'{port}.pid'
|
|
353
|
+
|
|
354
|
+
|
|
355
|
+
def _lease_file(port: int) -> Path:
|
|
356
|
+
return state_directory() / f'{port}.lease'
|
|
357
|
+
|
|
358
|
+
|
|
359
|
+
def renew_lease(port: int, ttl: int, reset: bool = False) -> float:
|
|
360
|
+
"""A new installation extends a shared server instead of inheriting its age."""
|
|
361
|
+
file=_lease_file(port)
|
|
362
|
+
deadline=time.time()+ttl if ttl>0 else 0
|
|
363
|
+
if not reset and file.is_file():
|
|
364
|
+
try:
|
|
365
|
+
previous=float(file.read_text())
|
|
366
|
+
deadline=0 if previous==0 else max(previous,deadline) if deadline else 0
|
|
367
|
+
except ValueError:
|
|
368
|
+
pass
|
|
369
|
+
file.parent.mkdir(parents=True,exist_ok=True)
|
|
370
|
+
temporary=file.with_suffix('.lease.tmp')
|
|
371
|
+
temporary.write_text(str(deadline))
|
|
372
|
+
temporary.replace(file)
|
|
373
|
+
return deadline
|
|
374
|
+
|
|
375
|
+
|
|
376
|
+
def _log_file(port: int = SCRIPT_SERVER_PORT) -> Path:
|
|
377
|
+
return state_directory() / f'{port}.log'
|
|
378
|
+
|
|
379
|
+
|
|
380
|
+
def _health(port: int) -> dict | None:
|
|
381
|
+
url = f'http://127.0.0.1:{port}/healthz'
|
|
382
|
+
try:
|
|
383
|
+
with urllib.request.urlopen(url, timeout=1.5) as response:
|
|
384
|
+
payload = json.loads(response.read())
|
|
385
|
+
except (urllib.error.URLError, OSError, ValueError):
|
|
386
|
+
return None
|
|
387
|
+
if isinstance(payload, dict) and payload.get('service') == SERVICE:
|
|
388
|
+
return payload
|
|
389
|
+
return {'status': 'foreign', 'service': payload.get('service') if isinstance(payload, dict) else None}
|
|
390
|
+
|
|
391
|
+
|
|
392
|
+
def status(port: int = SCRIPT_SERVER_PORT) -> dict:
|
|
393
|
+
pid_path = _pid_file(port)
|
|
394
|
+
record: dict = {}
|
|
395
|
+
if pid_path.is_file():
|
|
396
|
+
try:
|
|
397
|
+
record = json.loads(pid_path.read_text())
|
|
398
|
+
except ValueError:
|
|
399
|
+
record = {}
|
|
400
|
+
health = _health(port)
|
|
401
|
+
if health and health.get('status') == 'ok':
|
|
402
|
+
return {'status': 'running', 'port': port, 'url': f'http://127.0.0.1:{port}',
|
|
403
|
+
'guest_urls': {name: f'http://{host}:{port}' for name, host in GUEST_HOSTS.items()},
|
|
404
|
+
'directory': health.get('directory'), 'started_at': health.get('started_at'),
|
|
405
|
+
'ttl_seconds': health.get('ttl_seconds'), 'pid': record.get('pid'),
|
|
406
|
+
'lease_supported': health.get('lease_supported',False),
|
|
407
|
+
'log': str(_log_file(port))}
|
|
408
|
+
if health and health.get('status') == 'foreign':
|
|
409
|
+
return {'status': 'port_in_use', 'port': port,
|
|
410
|
+
'error': f'Port {port} is already used by another service. Stop it before starting the VAMP script server.'}
|
|
411
|
+
if record.get('pid') and _alive(int(record['pid'])):
|
|
412
|
+
return {'status': 'starting', 'port': port, 'pid': record.get('pid'),
|
|
413
|
+
'log': str(_log_file(port))}
|
|
414
|
+
return {'status': 'stopped', 'port': port}
|
|
415
|
+
|
|
416
|
+
|
|
417
|
+
def _alive(pid: int) -> bool:
|
|
418
|
+
if os.name == 'posix':
|
|
419
|
+
try:
|
|
420
|
+
os.kill(pid, 0)
|
|
421
|
+
except OSError:
|
|
422
|
+
return False
|
|
423
|
+
return True
|
|
424
|
+
# os.kill(pid, 0) terminates a process on Windows, so query the handle instead.
|
|
425
|
+
try:
|
|
426
|
+
import ctypes
|
|
427
|
+
handle = ctypes.windll.kernel32.OpenProcess(0x1000, False, pid) # PROCESS_QUERY_LIMITED_INFORMATION
|
|
428
|
+
if not handle:
|
|
429
|
+
return False
|
|
430
|
+
ctypes.windll.kernel32.CloseHandle(handle)
|
|
431
|
+
return True
|
|
432
|
+
except Exception:
|
|
433
|
+
return True
|
|
434
|
+
|
|
435
|
+
|
|
436
|
+
def _terminate(pid: int) -> None:
|
|
437
|
+
if os.name == 'posix':
|
|
438
|
+
try:
|
|
439
|
+
os.kill(pid, signal.SIGTERM)
|
|
440
|
+
except OSError:
|
|
441
|
+
pass
|
|
442
|
+
return
|
|
443
|
+
subprocess.run(['taskkill', '/PID', str(pid), '/T', '/F'], capture_output=True, timeout=15)
|
|
444
|
+
|
|
445
|
+
|
|
446
|
+
def _wait_health(port: int, seconds: float = 10.0) -> dict | None:
|
|
447
|
+
deadline = time.time() + seconds
|
|
448
|
+
while time.time() < deadline:
|
|
449
|
+
health = _health(port)
|
|
450
|
+
if health and health.get('status') == 'ok':
|
|
451
|
+
return health
|
|
452
|
+
time.sleep(0.2)
|
|
453
|
+
return None
|
|
454
|
+
|
|
455
|
+
|
|
456
|
+
def start(source: Path | None = None, port: int = SCRIPT_SERVER_PORT, bind: str = DEFAULT_BIND,
|
|
457
|
+
ttl: int = DEFAULT_TTL) -> dict:
|
|
458
|
+
current = status(port)
|
|
459
|
+
if current['status'] == 'running':
|
|
460
|
+
if current.get('lease_supported'):
|
|
461
|
+
renew_lease(port,ttl)
|
|
462
|
+
# Refresh upgraded/normalized payloads without deleting files currently
|
|
463
|
+
# being downloaded. Publish each staged file atomically.
|
|
464
|
+
if current.get('directory'):
|
|
465
|
+
with tempfile.TemporaryDirectory(prefix='vamp-stage-') as temporary:
|
|
466
|
+
staged=stage(source,Path(temporary)/'stage',port=port)
|
|
467
|
+
staged_root=Path(staged['directory'])
|
|
468
|
+
live=Path(current['directory'])
|
|
469
|
+
for file in staged_root.rglob('*'):
|
|
470
|
+
if file.is_file():
|
|
471
|
+
target=live/file.relative_to(staged_root)
|
|
472
|
+
target.parent.mkdir(parents=True,exist_ok=True)
|
|
473
|
+
pending=target.with_name(target.name+'.pending')
|
|
474
|
+
shutil.copy2(file,pending)
|
|
475
|
+
os.replace(pending,target)
|
|
476
|
+
return {**current, 'reused': True}
|
|
477
|
+
if current['status'] == 'port_in_use':
|
|
478
|
+
return current
|
|
479
|
+
staged = stage(source, port=port)
|
|
480
|
+
state = state_directory()
|
|
481
|
+
state.mkdir(parents=True, exist_ok=True)
|
|
482
|
+
directory = Path(staged['directory'])
|
|
483
|
+
renew_lease(port,ttl,reset=True)
|
|
484
|
+
log_path = _log_file(port)
|
|
485
|
+
detach = {'start_new_session': True} if os.name == 'posix' else {
|
|
486
|
+
'creationflags': getattr(subprocess, 'DETACHED_PROCESS', 0) | getattr(subprocess, 'CREATE_NEW_PROCESS_GROUP', 0)}
|
|
487
|
+
with log_path.open('ab') as log:
|
|
488
|
+
process = subprocess.Popen(
|
|
489
|
+
[sys.executable, str(Path(__file__).resolve()), 'serve',
|
|
490
|
+
'--directory', str(directory), '--port', str(port), '--bind', bind, '--ttl', str(ttl)],
|
|
491
|
+
stdout=log, stderr=log, stdin=subprocess.DEVNULL, **detach,
|
|
492
|
+
)
|
|
493
|
+
health = _wait_health(port)
|
|
494
|
+
if not health:
|
|
495
|
+
return {'status': 'failed', 'port': port,
|
|
496
|
+
'error': f'The script server did not answer on port {port}. Read {log_path}.'}
|
|
497
|
+
record = {'pid': process.pid, 'port': port, 'bind': bind, 'directory': str(directory),
|
|
498
|
+
'started_at': health.get('started_at'), 'ttl_seconds': ttl}
|
|
499
|
+
_pid_file(port).write_text(json.dumps(record, indent=2) + '\n')
|
|
500
|
+
return {'status': 'running', 'port': port, 'pid': process.pid, 'bind': bind,
|
|
501
|
+
'directory': str(directory), 'started_at': health.get('started_at'), 'ttl_seconds': ttl,
|
|
502
|
+
'url': f'http://127.0.0.1:{port}',
|
|
503
|
+
'guest_urls': {name: f'http://{host}:{port}' for name, host in GUEST_HOSTS.items()},
|
|
504
|
+
'commands': guest_commands(port), 'manifest': str(directory / 'vamp-setup.json'),
|
|
505
|
+
'log': str(log_path)}
|
|
506
|
+
|
|
507
|
+
|
|
508
|
+
def stop(port: int = SCRIPT_SERVER_PORT) -> dict:
|
|
509
|
+
pid_path = _pid_file(port)
|
|
510
|
+
record: dict = {}
|
|
511
|
+
if pid_path.is_file():
|
|
512
|
+
try:
|
|
513
|
+
record = json.loads(pid_path.read_text())
|
|
514
|
+
except ValueError:
|
|
515
|
+
record = {}
|
|
516
|
+
pid = record.get('pid')
|
|
517
|
+
if not pid:
|
|
518
|
+
if status(port)['status'] == 'running':
|
|
519
|
+
return {'status': 'running', 'port': port,
|
|
520
|
+
'error': 'A script server answers on this port but its pid file is missing. Stop it from the terminal that started it.'}
|
|
521
|
+
return {'status': 'stopped', 'port': port}
|
|
522
|
+
pid = int(pid)
|
|
523
|
+
_terminate(pid)
|
|
524
|
+
deadline = time.time() + 6
|
|
525
|
+
while time.time() < deadline and _alive(pid):
|
|
526
|
+
time.sleep(0.2)
|
|
527
|
+
if _alive(pid) and os.name == 'posix':
|
|
528
|
+
try:
|
|
529
|
+
os.kill(pid, signal.SIGKILL)
|
|
530
|
+
except OSError:
|
|
531
|
+
pass
|
|
532
|
+
pid_path.unlink(missing_ok=True)
|
|
533
|
+
return {'status': 'stopped', 'port': port, 'pid': pid}
|
|
534
|
+
|
|
535
|
+
|
|
536
|
+
def free_port() -> int:
|
|
537
|
+
with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as probe:
|
|
538
|
+
probe.bind(('127.0.0.1', 0))
|
|
539
|
+
return probe.getsockname()[1]
|
|
540
|
+
|
|
541
|
+
|
|
542
|
+
def main(argv: list[str] | None = None) -> int:
|
|
543
|
+
parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
|
|
544
|
+
parser.add_argument('command', choices=('serve', 'stage', 'start', 'stop', 'status'))
|
|
545
|
+
parser.add_argument('--port', type=int, default=SCRIPT_SERVER_PORT,
|
|
546
|
+
help=f'HTTP port; VAMP uses {SCRIPT_SERVER_PORT} (default)')
|
|
547
|
+
parser.add_argument('--bind', default=DEFAULT_BIND, help=f'Bind address (default {DEFAULT_BIND})')
|
|
548
|
+
parser.add_argument('--directory', help='Guest setup source folder (default: <repo>/guest_setup)')
|
|
549
|
+
parser.add_argument('--ttl', type=int, default=DEFAULT_TTL, help='Seconds before the server stops itself (0 = no limit)')
|
|
550
|
+
parser.add_argument('--json', action='store_true', help='Print one JSON document on stdout')
|
|
551
|
+
args = parser.parse_args(argv)
|
|
552
|
+
source = Path(args.directory) if args.directory else None
|
|
553
|
+
|
|
554
|
+
if args.command == 'serve':
|
|
555
|
+
if not args.directory:
|
|
556
|
+
parser.error('serve needs --directory (run "start" to stage and launch)')
|
|
557
|
+
return serve(Path(args.directory), args.port, args.bind, args.ttl)
|
|
558
|
+
if args.command == 'stage':
|
|
559
|
+
result = stage(source, port=args.port)
|
|
560
|
+
elif args.command == 'start':
|
|
561
|
+
result = start(source, args.port, args.bind, args.ttl)
|
|
562
|
+
elif args.command == 'stop':
|
|
563
|
+
result = stop(args.port)
|
|
564
|
+
else:
|
|
565
|
+
result = status(args.port)
|
|
566
|
+
print(json.dumps(result, indent=2))
|
|
567
|
+
return 0 if result.get('status') not in ('failed', 'port_in_use') else 1
|
|
568
|
+
|
|
569
|
+
|
|
570
|
+
if __name__ == '__main__':
|
|
571
|
+
sys.exit(main())
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: vamp-rpa-ui-checks
|
|
3
|
+
description: Define reusable UI locators and outcome checks for VAMP Robot/Python RPAs. Use for screen automation reliability, host versus guest coordinates and compact validation evidence.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# VAMP RPA UI checks
|
|
7
|
+
|
|
8
|
+
Read rpa-reuse and the relevant virtualbox-rpa, hyperv-rpa or spice-vm-rpa skill before driving a guest. Reuse a reviewed package that matches the VM, input contract and expected application state.
|
|
9
|
+
|
|
10
|
+
## Define the contract
|
|
11
|
+
|
|
12
|
+
Read [display preflight](references/display.md). Verify 1920×1080 and 100% guest scaling before coordinate-based work; if different, adjust the guest and verify fresh evidence before continuing, subject to the user's current authorization and pause state.
|
|
13
|
+
|
|
14
|
+
Record the VM UUID, host platform, hypervisor, application, expected starting state, guest resolution and display scaling. State whether coordinates belong to the host window, viewport or guest framebuffer. Recalibrate when resolution, scaling, crop or window placement changes; never silently mix coordinate spaces.
|
|
15
|
+
|
|
16
|
+
Prefer semantic locators for host webviews and native accessibility controls. For guest screenshots, use the existing backend's OCR/YOLO pipeline and localized anchors. Limit searches to the relevant region and require an unambiguous match before clicking. Keep language recognition multilingual even when product explanations are English.
|
|
17
|
+
|
|
18
|
+
## Execute and verify
|
|
19
|
+
|
|
20
|
+
Use bounded waits for observable state changes. After each consequential action, check an independent outcome such as a dialog closing, expected page appearing, file existing or completion marker being written. A click, typed command or successful tool return proves delivery only.
|
|
21
|
+
|
|
22
|
+
When installation must run automatically, observe its result without manually starting the installer. Separate diagnostics from setup. On ambiguous state, capture targeted evidence and stop dependent input; use the repair skill for a failed saved RPA. Respect user pauses immediately and do not create snapshots unless requested.
|
|
23
|
+
|
|
24
|
+
## Save reusable evidence
|
|
25
|
+
|
|
26
|
+
Store locator intent, timing bounds, coordinate mapping, expected outcome and failure condition with the RPA. Return compact status and artifact paths. Export only targeted failure crops or OCR excerpts when needed. Exclude passwords, tokens and private session data from recordings and shared skills. Report completed_unverified distinctly from verified success.
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
# AI display preflight
|
|
2
|
+
|
|
3
|
+
Before recording, replaying or calculating guest coordinates, inspect the target VM's actual framebuffer. Require **1920×1080** with guest scaling **100%** for VAMP's standard recordings. A scaled screenshot or resized viewer does not verify the framebuffer.
|
|
4
|
+
|
|
5
|
+
If the resolution differs, adjust the guest to 1920×1080 using the authorized backend and guest display settings, then capture fresh evidence and verify the result before continuing. This requirement does not override a user's pause or authorize unrelated VM changes. If a driver installation, UAC approval or restart is required, identify the blocker and use the existing authorization rules.
|
|
6
|
+
|
|
7
|
+
- Linux GNOME: Settings → Displays → 1920×1080, Scale 100%, Apply. For Xorg only, inspect `xrandr --query` and select an available 1920x1080 mode. Use GNOME Settings on Wayland. Do not blindly force a missing mode.
|
|
8
|
+
- Windows: Settings → System → Display → Display resolution 1920×1080, Scale 100%. If unavailable, finish guest display driver/VirtualBox Guest Additions setup; verify again after any required reboot.
|
|
9
|
+
- VirtualBox: `vm_configure_display` can request the mode; require `observed_resolution: [1920,1080]` and `resolution_verified: true`. Independently verify guest scaling. Turn off guest auto-resize; scaled viewing does not change the target pixels.
|
|
10
|
+
- Other backends: inspect the native guest screenshot and session display configuration. Do not assume a VirtualBox tool works on Hyper-V or KVM.
|
|
11
|
+
|
|
12
|
+
Never reuse stale coordinates after a display change. If the target cannot be met, report the actual dimensions and block dependent coordinate replay rather than claiming success. Use the VSIX's **1920×1080 guide** for user-facing Linux and Windows instructions.
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
# Guest display: 1920×1080
|
|
2
|
+
|
|
3
|
+
**Before recording or replaying an RPA, set the VM's display to 1920×1080 at 100% scaling.** Change the guest display, not your host monitor. Resizing or zooming the viewer does not establish the guest resolution. Finish guest setup first and keep the VM awake and unlocked during setup and automation.
|
|
4
|
+
|
|
5
|
+
## Reset shortcuts installed by guest setup
|
|
6
|
+
|
|
7
|
+
- **Windows Desktop:** double-click `Set-Resolution-1920x1080.cmd`. It opens the companion PowerShell script and applies Full HD. Press any key to close its result window.
|
|
8
|
+
- **Debian home folder:** open a terminal in the logged-in guest and run `~/set-resolution-1920x1080.sh`.
|
|
9
|
+
|
|
10
|
+
Run these inside the VM when the display drifts. They reuse the same display helper as the per-login hook, apply 1920x1080 and report the observed result. They do not resize the host screen. If the guest driver rejects Full HD, the script reports that failure; finish the guest display driver setup first. All shortcut instructions and messages are in English.
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
## Linux VM — Debian / Ubuntu GNOME
|
|
14
|
+
|
|
15
|
+
1. Inside the guest, open **Settings → Displays**.
|
|
16
|
+
2. Select the guest display, choose **1920 × 1080**, and set **Scale** to **100%**.
|
|
17
|
+
3. Apply the settings and keep the changes. Recheck after login or reconnecting the viewer.
|
|
18
|
+
|
|
19
|
+
If you use **GNOME on Xorg**, you can list available modes and select an existing Full HD mode in the guest terminal:
|
|
20
|
+
|
|
21
|
+
```sh
|
|
22
|
+
xrandr --query
|
|
23
|
+
display=$(xrandr --query | awk '/ connected/{print $1; exit}')
|
|
24
|
+
xrandr --output "$display" --mode 1920x1080
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
Run this as the logged-in desktop user, not on the host. `xrandr` is an Xorg tool; in a Wayland session use Settings → Displays. If 1920×1080 is missing, finish the display driver/Guest Additions setup and reboot when installation is complete. Do not force an unavailable mode. In GNOME, the login screen's session menu may offer **GNOME on Xorg** if installed.
|
|
28
|
+
|
|
29
|
+
For VirtualBox, keep **Auto-resize Guest Display** off after setting the target resolution. Use **View → Scaled Mode** to fit the viewer without changing guest pixels. On KVM, check the guest display driver and configured virtual video device if the mode is unavailable.
|
|
30
|
+
|
|
31
|
+
## Windows VM — Windows 11
|
|
32
|
+
|
|
33
|
+
1. Inside the guest, open **Start → Settings → System → Display**.
|
|
34
|
+
2. Under **Scale & layout**, choose **Display resolution: 1920 × 1080** and **Scale: 100%**.
|
|
35
|
+
3. Keep the changes. If Windows requests a sign-out, finish setup before signing out, then verify the settings again.
|
|
36
|
+
|
|
37
|
+
If the resolution is missing or disabled in VirtualBox, finish guest setup, choose **Devices → Insert Guest Additions CD image**, open the CD inside Windows and run **VBoxWindowsAdditions.exe**. Approve the guest UAC prompt and reboot after installation. Then select 1920×1080 and 100% again. Leave **Auto-resize Guest Display** off; **Scaled Mode** changes only the viewer presentation.
|
|
38
|
+
|
|
39
|
+
Hyper-V basic sessions can expose fewer display modes. Use supported guest display drivers or an Enhanced Session when available, set the session display to 1920×1080, and recheck the effective guest resolution after reconnecting. The VAMP Hyper-V embedded viewer is not implemented.
|
|
40
|
+
|
|
41
|
+
## Verify before automation
|
|
42
|
+
|
|
43
|
+
Check the actual guest screen dimensions, not a resized preview. For VirtualBox, `vm_screen_info` / a native screenshot can report the framebuffer size. `vm_configure_display` requests Full HD and returns `observed_resolution` and `resolution_verified`; a sent hint is not proof of a changed resolution. Verify 100% scaling separately inside the guest.
|
|
44
|
+
|
|
45
|
+
An RPA recorded at another resolution needs recalibration or a matching recording. If the guest cannot reach 1920×1080, report the observed resolution and resolve the display driver/session issue before coordinate-based replay.
|
|
46
|
+
|
|
47
|
+
References: [GNOME display settings](https://teams.pages.gitlab.gnome.org/websites/help.gnome.org/gnome-help/look-resolution.html), [Microsoft display resolution and layout](https://support.microsoft.com/en-us/windows/hardware/display-graphics/change-your-screen-resolution-and-layout-in-windows).
|
|
48
|
+
|
|
49
|
+
Windows guest setup and display-reset scripts request administrator PowerShell when needed. Approve the UAC prompt. The elevated process runs `Set-ExecutionPolicy -Scope Process -ExecutionPolicy Unrestricted -Force` before the script. MCP and VSIX share the same Ctrl+Shift+Enter / UAC Left+Enter bootstrap. Script execution policy changes apply to that process.
|
|
50
|
+
|
|
51
|
+
Windows setup finishes with an elevated direct registry update to 1920x1080 (`PrimSurfSize.cx/cy` and `ActiveSize.cx/cy`) for the guest display configurations, on VirtualBox, KVM and Hyper-V. The Desktop reset script performs the same update before applying the display mode. Previous registry values are backed up under `%ProgramData%\VAMP\display-registry\backups`. A compatible guest display driver is still required.
|