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.

Files changed (141) hide show
  1. package/LICENSE +21 -21
  2. package/README.md +144 -107
  3. package/THIRD_PARTY_NOTICES.md +32 -27
  4. package/bin/vamp-mcp.mjs +37 -37
  5. package/notices/mcp-virtualbox-LICENSE +21 -21
  6. package/notices/mcp-virtualbox-PROVENANCE.json +37 -37
  7. package/package.json +51 -17
  8. package/runtime/backends/common/Test-Environment.ps1 +7 -6
  9. package/runtime/backends/common/guest-install.json +58 -0
  10. package/runtime/backends/common/guest_install.py +57 -0
  11. package/runtime/backends/common/host-support.cjs +16 -0
  12. package/runtime/backends/common/packer.cjs +16 -0
  13. package/runtime/backends/hyperv/scripts/Manage-Desktop.ps1 +40 -67
  14. package/runtime/backends/hyperv/scripts/Send-InstallerBoot.ps1 +25 -0
  15. package/runtime/backends/kvm/debian-preseed.cfg +35 -35
  16. package/runtime/backends/library/registry.py +77 -77
  17. package/runtime/backends/library/replay.py +154 -154
  18. package/runtime/backends/packer/answer_media.py +16 -0
  19. package/runtime/backends/packer/deploy-hyperv.ps1 +10 -0
  20. package/runtime/backends/packer/drivers.py +49 -0
  21. package/runtime/backends/packer/hyperv-network.ps1 +10 -0
  22. package/runtime/backends/packer/images.py +75 -0
  23. package/runtime/backends/packer/osinfo.py +113 -0
  24. package/runtime/backends/packer/policy.json +15 -0
  25. package/runtime/backends/packer/runner.py +224 -0
  26. package/runtime/backends/packer/templates.py +118 -0
  27. package/runtime/backends/packer/toolchain.py +80 -0
  28. package/runtime/backends/remote_ssh/server.mjs +321 -94
  29. package/runtime/backends/virtualbox/desktop.cjs +37 -0
  30. package/runtime/backends/virtualbox/display.py +101 -101
  31. package/runtime/backends/virtualbox/history.py +139 -139
  32. package/runtime/backends/virtualbox/mouse_click.py +15 -15
  33. package/runtime/backends/virtualbox/mouse_move.py +18 -18
  34. package/runtime/backends/virtualbox/profiles.json +46 -46
  35. package/runtime/backends/virtualbox/provision.py +238 -184
  36. package/runtime/backends/virtualbox/recording_listener.py +29 -29
  37. package/runtime/backends/virtualbox/recordings.py +39 -39
  38. package/runtime/backends/virtualbox/requirements.txt +7 -7
  39. package/runtime/backends/virtualbox/rpas/debian_first_boot/manifest.json +1 -1
  40. package/runtime/backends/virtualbox/rpas/debian_first_boot/run.robot +13 -13
  41. package/runtime/backends/virtualbox/rpas/debian_first_boot/workflow.py +75 -75
  42. package/runtime/backends/virtualbox/rpas/observe/manifest.json +7 -7
  43. package/runtime/backends/virtualbox/rpas/observe/run.robot +13 -13
  44. package/runtime/backends/virtualbox/rpas/observe/workflow.py +14 -14
  45. package/runtime/backends/virtualbox/server.mjs +440 -63
  46. package/runtime/backends/virtualbox/setup_windows_sdk.py +58 -58
  47. package/runtime/backends/virtualbox/shares.py +68 -68
  48. package/runtime/backends/virtualbox/snapshots.py +53 -53
  49. package/runtime/backends/virtualbox/transfers.py +89 -89
  50. package/runtime/backends/virtualbox/vnc.py +61 -61
  51. package/runtime/guest_keys.py +13 -13
  52. package/runtime/guest_setup/http/debian-preseed.cfg +39 -0
  53. package/runtime/guest_setup/http/postdeb.sh +94 -0
  54. package/runtime/guest_setup/http/postwin.ps1 +53 -0
  55. package/runtime/guest_setup/http/setup-all.ps1 +25 -0
  56. package/runtime/guest_setup/http/setup-win.cmd +7 -0
  57. package/runtime/guest_setup/http/setup.ps1 +44 -0
  58. package/runtime/guest_setup/http/setup.sh +50 -0
  59. package/runtime/guest_setup/kvm/setup-debian.sh +73 -0
  60. package/runtime/guest_setup/kvm/setup-windows.ps1 +52 -0
  61. package/runtime/guest_setup/recorder/README.txt +12 -8
  62. package/runtime/guest_setup/recorder/RECORDER-LICENSE +674 -674
  63. package/runtime/guest_setup/recorder/RECORDING-GUIDE.txt +31 -31
  64. package/runtime/guest_setup/recorder/apply-display.py +41 -41
  65. package/runtime/guest_setup/recorder/configure-debian-mirrors.py +62 -62
  66. package/runtime/guest_setup/recorder/configure-gdm.py +23 -0
  67. package/runtime/guest_setup/recorder/configure-session.ps1 +14 -0
  68. package/runtime/guest_setup/recorder/gnome-display.py +60 -60
  69. package/runtime/guest_setup/recorder/install-display-startup.py +67 -39
  70. package/runtime/guest_setup/recorder/install-hypervisor-drivers.ps1 +34 -0
  71. package/runtime/guest_setup/recorder/install-resolution-shortcut.ps1 +36 -0
  72. package/runtime/guest_setup/recorder/postwin.cmd +10 -10
  73. package/runtime/guest_setup/recorder/prepare-recording.py +30 -30
  74. package/runtime/guest_setup/recorder/recorder.zip +0 -0
  75. package/runtime/guest_setup/recorder/requirements-recorder.txt +2 -2
  76. package/runtime/guest_setup/recorder/session-policy.py +22 -0
  77. package/runtime/guest_setup/recorder/set-resolution-registry.ps1 +40 -0
  78. package/runtime/guest_setup/recorder/setup-user.py +53 -35
  79. package/runtime/guest_setup/recorder/setup-win.cmd +4 -11
  80. package/runtime/guest_setup/recorder/setup.ps1 +112 -30
  81. package/runtime/guest_setup/recorder/setup.sh +19 -1
  82. package/runtime/guest_setup/recorder/vamp-recorder.py +148 -148
  83. package/runtime/guest_setup/recorder/verify-recorder.py +4 -4
  84. package/runtime/guest_setup/recorder/windows-display.py +76 -76
  85. package/runtime/guest_setup/requirements.txt +2 -0
  86. package/runtime/guest_setup/setup-all.ps1 +35 -0
  87. package/runtime/guest_setup/setup-all.sh +22 -0
  88. package/runtime/guest_setup/vault/Install-VCRuntime.ps1 +26 -0
  89. package/runtime/guest_setup/vault/setup-guest-vault.ps1 +148 -0
  90. package/runtime/guest_setup/vault/setup-guest-vault.sh +75 -0
  91. package/runtime/recording_converter.py +230 -230
  92. package/runtime/requirements-mcp.txt +11 -11
  93. package/runtime/rpas/README.md +161 -161
  94. package/runtime/rpas/captcha_handoff/manifest.json +27 -27
  95. package/runtime/rpas/captcha_handoff/run.robot +16 -16
  96. package/runtime/rpas/captcha_handoff/workflow.py +11 -11
  97. package/runtime/rpas/common.resource +26 -26
  98. package/runtime/rpas/debian_update/manifest.json +27 -27
  99. package/runtime/rpas/debian_update/run.robot +17 -17
  100. package/runtime/rpas/debian_update/workflow.py +13 -13
  101. package/runtime/rpas/desktop_control/manifest.json +26 -26
  102. package/runtime/rpas/desktop_control/run.robot +27 -27
  103. package/runtime/rpas/desktop_control/workflow.py +51 -51
  104. package/runtime/rpas/firefox_launch/manifest.json +27 -27
  105. package/runtime/rpas/firefox_launch/run.robot +15 -15
  106. package/runtime/rpas/firefox_launch/workflow.py +25 -25
  107. package/runtime/rpas/firefox_naver/manifest.json +27 -27
  108. package/runtime/rpas/firefox_naver/run.robot +21 -21
  109. package/runtime/rpas/firefox_naver/workflow.py +28 -28
  110. package/runtime/rpas/kvm_validation/README.md +11 -11
  111. package/runtime/rpas/kvm_validation/manifest.json +28 -28
  112. package/runtime/rpas/kvm_validation/run.robot +30 -30
  113. package/runtime/rpas/kvm_validation/workflow.py +91 -91
  114. package/runtime/rpas/manifest.schema.json +105 -105
  115. package/runtime/rpas/naver_login/login.robot +25 -25
  116. package/runtime/rpas/naver_login/manifest.json +33 -33
  117. package/runtime/rpas/naver_login/run.robot +20 -20
  118. package/runtime/rpas/naver_login/workflow.py +32 -32
  119. package/runtime/rpas/windows_naver_recorded/README.md +24 -24
  120. package/runtime/rpas/windows_naver_recorded/conversion.json +25 -25
  121. package/runtime/rpas/windows_naver_recorded/manifest.json +28 -28
  122. package/runtime/rpas/windows_naver_recorded/run.robot +37 -37
  123. package/runtime/rpas/windows_naver_recorded/workflow.py +32 -32
  124. package/runtime/scripts/build_recorder_media.py +39 -39
  125. package/runtime/scripts/macos/setup-host.sh +126 -0
  126. package/runtime/scripts/remote_host_setup.sh +7 -4
  127. package/runtime/scripts/script_server.py +571 -0
  128. package/runtime/skills/vamp-rpa-ui-checks/SKILL.md +26 -0
  129. package/runtime/skills/vamp-rpa-ui-checks/agents/openai.yaml +4 -0
  130. package/runtime/skills/vamp-rpa-ui-checks/references/display.md +12 -0
  131. package/runtime/skills/vamp-rpa-ui-checks/references/user-guide.md +51 -0
  132. package/runtime/skills/vamp-ui-cleanup/SKILL.md +15 -0
  133. package/runtime/skills/vamp-ui-cleanup/agents/openai.yaml +4 -0
  134. package/runtime/skills/vamp-ui-validation/SKILL.md +27 -0
  135. package/runtime/skills/vamp-ui-validation/agents/openai.yaml +4 -0
  136. package/runtime/third_party/mcp-virtualbox/scripts/mouse_click.py +65 -65
  137. package/runtime/third_party/pyautogui-recorder/LICENSE +674 -674
  138. package/runtime/third_party/pyautogui-recorder/PROVENANCE.json +16 -16
  139. package/runtime/third_party/pyautogui-recorder/PyAutoGuiRecorder.py +169 -169
  140. package/runtime/third_party/pyautogui-recorder/README.md +53 -53
  141. 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,4 @@
1
+ interface:
2
+ display_name: "VAMP RPA UI Checks"
3
+ short_description: "Define reliable RPA locators and outcome checks"
4
+ default_prompt: "Use $vamp-rpa-ui-checks to define reusable locators and independent success checks for this RPA."
@@ -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.