1#!/usr/bin/env python3
2"""Computer operations in a logged-in Unix desktop, over stdin/stdout."""
3import base64
4import fcntl
5import json
6import hashlib
7import shutil
8import stat
9import uuid
10import os
11from pathlib import Path
12import selectors
13import signal
14import subprocess
15import sys
16import tempfile
17import time
18
19GUI = "/usr/local/bin/agent-gui"
20MAC = sys.platform == "darwin"
21
22
23def process_identity(pid):
24 if not MAC:
25 return Path('/proc/' + str(pid) + '/stat').read_text().rsplit(')',1)[1].split()[19]
26 return subprocess.check_output(['ps','-p',str(pid),'-o','lstart='],text=True).strip().replace(':','-')
27
28
29def process_operation(request):
30 identity = request.get('id','')
31 if not MAC:
32 import re
33 if not re.fullmatch('snowglobe-computer-[0-9a-f]{32}',identity) or request.get('operation') not in ('status','stop'):
34 raise ValueError('Use the process ID returned by computer_spawn.')
35 if request['operation']=='stop':
36 subprocess.run(['systemctl','--user','stop',identity],check=True,timeout=15)
37 return {'stopping':True}
38 result=subprocess.run(['systemctl','--user','show',identity,'-p','ActiveState','-p','MainPID'],capture_output=True,text=True,timeout=5)
39 state=dict(line.split('=',1) for line in result.stdout.splitlines() if '=' in line)
40 return {'running':state.get('ActiveState')=='active','pid':int(state.get('MainPID','0'))}
41 pid_text,separator,started = identity.partition(':')
42 if not separator or not pid_text.isdigit() or int(pid_text) <= 1 or request.get('operation') not in ('status','stop'):
43 raise ValueError('Use the process ID returned by computer_spawn.')
44 pid=int(pid_text)
45 try:
46 current = process_identity(pid)
47 except (OSError,subprocess.SubprocessError):
48 return {'running':False}
49 if not current or current != started:
50 return {'running':False}
51 if request['operation']=='stop':
52 if os.getpgid(pid) != pid:
53 raise ValueError('The process is not an isolated computer task.')
54 os.killpg(pid,signal.SIGTERM)
55 return {'stopping':True}
56 return {'running':True,'pid':pid}
57
58
59def file_operation(request):
60 path = request.get('path')
61 if not isinstance(path,str) or not path.startswith('/') or '\x00' in path or len(path)>4096:
62 raise ValueError('Use an absolute guest file path.')
63 path=Path(path)
64 operation=request.get('operation')
65 if operation in ('stat','list'):
66 info=path.stat()
67 result={'path':str(path),'size':info.st_size,'directory':stat.S_ISDIR(info.st_mode),'modified':info.st_mtime}
68 if operation=='list':
69 entries=[]
70 with os.scandir(path) as iterator:
71 for entry in iterator:
72 if len(entries)==1000:
73 result['truncated']=True; break
74 entries.append({'name':entry.name,'directory':entry.is_dir(follow_symlinks=False)})
75 result['entries']=entries
76 return result
77 if operation=='mkdir':
78 path.mkdir(parents=True,exist_ok=True); return {'path':str(path)}
79 if operation=='read':
80 offset,length=request.get('offset',0),request.get('length',65536)
81 if type(offset) is not int or offset<0 or type(length) is not int or not 1<=length<=65536:
82 raise ValueError('Read at most 64 KiB at a time from a nonnegative offset.')
83 with path.open('rb') as incoming:
84 if not stat.S_ISREG(os.fstat(incoming.fileno()).st_mode):
85 raise ValueError('Choose a regular guest file.')
86 incoming.seek(offset);data=incoming.read(length)
87 return {'data':base64.b64encode(data).decode(),'bytes':len(data)}
88 if operation=='write':
89 data=base64.b64decode(request.get('data',''),validate=True)
90 offset=request.get('offset',0)
91 if len(data)>65536 or type(offset) is not int or not 0<=offset<=64*2**20:
92 raise ValueError('The transfer chunk exceeds its limit.')
93 flags=os.O_WRONLY|os.O_NOFOLLOW|(os.O_CREAT|os.O_EXCL if offset==0 else 0)
94 with os.fdopen(os.open(path,flags,0o600),'r+b') as outgoing:
95 if not stat.S_ISREG(os.fstat(outgoing.fileno()).st_mode) or os.fstat(outgoing.fileno()).st_size!=offset:
96 raise ValueError('The transfer offset changed. Start a new upload.')
97 outgoing.seek(offset);outgoing.write(data)
98 return {'bytes':len(data)}
99 if operation=='commit':
100 destination=request.get('destination')
101 if not isinstance(destination,str) or not destination.startswith('/') or '\x00' in destination:
102 raise ValueError('Use an absolute guest destination path.')
103 if request.get('overwrite',False): os.replace(path,destination)
104 else:
105 os.link(path,destination);path.unlink()
106 return {'path':destination}
107 if operation=='remove':
108 path.unlink();return {'removed':True}
109 raise ValueError('Choose a supported file operation.')
110
111
112def linux_ui(request):
113 try:
114 import gi
115 gi.require_version('Atspi','2.0')
116 from gi.repository import Atspi, GLib
117 except (ImportError,ValueError):
118 raise ValueError('Install the AT-SPI Python bindings in this guest, then retry.') from None
119 Atspi.set_timeout(1500,3000)
120 desktop=Atspi.get_desktop(0)
121 if request['action']=='input':
122 for item in request['actions']:
123 if item['type']!='text': raise ValueError('Use the VM console for pointer and key actions.')
124 pending=[desktop]
125 focused=None
126 deadline=time.monotonic()+8
127 visited=0
128 while pending and visited<1500 and time.monotonic()<deadline:
129 node=pending.pop()
130 visited+=1
131 try:
132 if node.get_state_set().contains(Atspi.StateType.FOCUSED) and 'EditableText' in node.get_interfaces():
133 focused=node
134 break
135 pending.extend(node.get_child_at_index(i) for i in range(min(node.get_child_count(),1500-visited)))
136 except (GLib.Error,AttributeError):
137 continue
138 if focused is not None:
139 try:
140 position=Atspi.Text.get_caret_offset(focused)
141 if Atspi.Text.get_n_selections(focused):
142 selection=Atspi.Text.get_selection(focused,0)
143 position=selection.start_offset
144 if not Atspi.EditableText.delete_text(focused,position,selection.end_offset):
145 raise ValueError('The application refused to replace the selected text.')
146 value=item['text']
147 if not Atspi.EditableText.insert_text(focused,position,value,len(value.encode())):
148 raise ValueError('The application refused text input.')
149 Atspi.Text.set_caret_offset(focused,position+len(value))
150 except GLib.Error:
151 raise ValueError('The text field is unavailable. Focus it again, then retry.') from None
152 elif os.environ.get('XDG_SESSION_TYPE')!='wayland' and not os.environ.get('WAYLAND_DISPLAY'):
153 if not Atspi.generate_keyboard_event(0,item['text'],Atspi.KeySynthType.STRING):
154 raise ValueError('This desktop refused text input. Use a UI set_value action or a guest script.')
155 else:
156 raise ValueError('Focus an editable text field, or use a guest script to enter this text.')
157 return {'completed':len(request['actions'])}
158 if request['action']=='ui_action':
159 target=request.get('target',{})
160 node=desktop
161 try:
162 for index in target['path']: node=node.get_child_at_index(index)
163 if node.get_process_id()!=target['pid'] or process_identity(target['pid'])!=target['started'] or node.get_role_name()!=target['role'] or (node.get_name() or '')[:512]!=target['name']:
164 raise ValueError('The UI element changed. Read a fresh tree.')
165 operation=request['operation']
166 if operation=='focus': success=node.get_component_iface().grab_focus()
167 elif operation=='set_value': success=Atspi.EditableText.set_text_contents(node,request.get('value',''))
168 else:
169 actions=node.get_action_iface()
170 indices=[i for i in range(actions.get_n_actions()) if actions.get_action_name(i)==operation]
171 if not indices: raise ValueError('Choose an action reported by computer_ui.')
172 success=actions.do_action(indices[0])
173 if not success: raise ValueError('The application refused the UI action. Read a fresh tree.')
174 return {'completed':True}
175 except (KeyError,AttributeError,TypeError,GLib.Error):
176 raise ValueError('The UI element is unavailable. Read a fresh tree.') from None
177 nodes=[]
178 deadline=time.monotonic()+8
179 def walk(node,path,depth):
180 if len(nodes)>=1500 or depth>20 or time.monotonic()>deadline: return
181 try:
182 pid=node.get_process_id()
183 if len(path)==1 and request.get('pid') and pid!=request['pid']: return
184 name=node.get_name() or ''
185 role=node.get_role_name()
186 entry={'target':{'path':path,'pid':pid,'started':process_identity(pid) if pid else '', 'role':role,'name':name[:512]},'role':role,'name':name[:512]}
187 states=node.get_state_set()
188 entry['focused']=states.contains(Atspi.StateType.FOCUSED)
189 entry['enabled']=states.contains(Atspi.StateType.ENABLED)
190 entry['actions']=[]
191 interfaces=node.get_interfaces()
192 if 'Component' in interfaces:
193 if os.environ.get('XDG_SESSION_TYPE')!='wayland' and not os.environ.get('WAYLAND_DISPLAY'):
194 bounds=node.get_component_iface().get_extents(Atspi.CoordType.SCREEN)
195 entry['bounds']=[bounds.x,bounds.y,bounds.width,bounds.height]
196 if states.contains(Atspi.StateType.FOCUSABLE): entry['actions'].append('focus')
197 if 'Action' in interfaces:
198 action=node.get_action_iface()
199 entry['actions'] += [action.get_action_name(i) for i in range(min(action.get_n_actions(),32))]
200 if 'Text' in interfaces:
201 entry['value']=Atspi.Text.get_text(node,0,min(Atspi.Text.get_character_count(node),1024))
202 if 'EditableText' in interfaces: entry['actions'].append('set_value')
203 nodes.append(entry)
204 for index in range(min(node.get_child_count(),1500)):
205 if len(nodes)>=1500 or time.monotonic()>deadline: break
206 child=node.get_child_at_index(index)
207 if child: walk(child,path+[index],depth+1)
208 except Exception:
209 return
210 walk(desktop,[],0)
211 return {'nodes':nodes,'truncated':len(nodes)>=1500 or time.monotonic()>deadline}
212
213
214def execute(request):
215 if not isinstance(request, dict):
216 raise ValueError("Send a computer operation.")
217 action = request.get("action")
218 fields = {"status": {"action"}, "shot": {"action"}, "ui": {"action", "pid"},
219 "ui_action": {"action", "target", "operation", "value", "screenshot"},
220 "input": {"action", "actions", "screenshot"}, "spawn": {"action", "script", "runtime"},
221 "process": {"action", "id", "operation"},
222 "file": {"action", "operation", "path", "offset", "data", "length", "destination", "overwrite"},
223 "exec": {"action", "script", "runtime", "timeout_ms", "screenshot"}}
224 if not isinstance(action, str) or action not in fields or set(request) - fields[action]:
225 raise ValueError("Use the fields listed for this computer operation.")
226 if action == "file":
227 return file_operation(request)
228 if action in ("input", "ui_action"):
229 if MAC:
230 result = subprocess.run([GUI, "input" if action == "input" else "action"],
231 input=json.dumps(request).encode(), capture_output=True, timeout=30)
232 reply = json.loads(result.stdout)
233 if result.returncode:
234 raise ValueError(reply.get("error", "The desktop action failed. Read the UI again."))
235 if request.get("screenshot"):
236 reply.update(execute({"action":"shot"}))
237 return reply
238 return linux_ui(request)
239 if action == "process":
240 return process_operation(request)
241 if action == "ui" and (request.get("pid") is not None and (type(request["pid"]) is not int or request["pid"] <= 0)):
242 raise ValueError("Choose a positive application PID, or omit it for the active app.")
243 if action in ("exec", "spawn"):
244 if not isinstance(request.get("script"), str) or not 1 <= len(request["script"].encode()) <= 65536:
245 raise ValueError("Provide a script of at most 64 KiB.")
246 runtime = request.get("runtime", "default")
247 runtime = ("zsh" if MAC else "bash") if runtime == "default" else runtime
248 shell = shutil.which(runtime) if runtime in ("bash", "zsh") else None
249 if not shell:
250 raise ValueError("Choose a runtime reported by computer_status.")
251 if action == "spawn":
252 if not MAC:
253 unit="snowglobe-computer-"+uuid.uuid4().hex
254 subprocess.run(["systemd-run","--user","--quiet","--collect","--service-type=exec","--unit="+unit,
255 shell,"-c",request["script"]],check=True,timeout=10)
256 pid=subprocess.run(["systemctl","--user","show",unit,"-p","MainPID","--value"],capture_output=True,text=True,timeout=5).stdout.strip()
257 return {"id":unit,"pid":int(pid) if pid.isdigit() else None}
258 process = subprocess.Popen([shell,"-c",request["script"]], stdin=subprocess.DEVNULL,
259 stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, start_new_session=True)
260 return {"id": str(process.pid) + ":" + process_identity(process.pid), "pid":process.pid}
261 if action == "exec":
262 if type(request.get("timeout_ms")) is not int or not 1 <= request["timeout_ms"] <= 180000:
263 raise ValueError("Choose a timeout between 1 and 180000 milliseconds.")
264 if type(request.get("screenshot")) is not bool:
265 raise ValueError("Choose whether to return a screenshot.")
266 if action == "status":
267 permissions = {}
268 if MAC:
269 result = subprocess.run([GUI, "status"], capture_output=True, timeout=10, check=True)
270 permissions = json.loads(result.stdout)
271 else:
272 try:
273 import gi
274 gi.require_version("Atspi", "2.0")
275 from gi.repository import Atspi
276 permissions["accessibility"] = Atspi.get_desktop(0) is not None
277 except (ImportError, ValueError):
278 permissions["accessibility"] = False
279 return {"permissions": permissions, "hostname": os.uname().nodename,
280 "platform": "macos" if MAC else "linux", "runtimes": [r for r in ("zsh","bash") if shutil.which(r)],
281 "capabilities": ["shot","input","exec","spawn","process","file"] + (["ui","ui_action"] if permissions.get("accessibility") else []),
282 "max_timeout_ms": 180000, "coordinate_units":"screenshot_pixels"}
283 if action == "ui":
284 if not MAC:
285 return linux_ui(request)
286 args = [GUI, "tree"] + ([] if request.get("pid") is None else [str(request["pid"])])
287 result = subprocess.run(args, capture_output=True, timeout=15, check=True)
288 if len(result.stdout) > 2 * 1024 * 1024:
289 raise ValueError("The UI tree is too large. Select an application PID.")
290 return {"tree": json.loads(result.stdout)}
291 with tempfile.TemporaryDirectory(prefix="snowglobe-computer-") as directory:
292 reply = {}
293 if action == "exec":
294 script = Path(directory) / "script"
295 script.write_text(request["script"])
296 with script.open("rb") as source, selectors.DefaultSelector() as selector:
297 process = subprocess.Popen([shell, "-s"], stdin=source,
298 stdout=subprocess.PIPE, stderr=subprocess.PIPE, start_new_session=True)
299 streams = {"stdout": bytearray(), "stderr": bytearray()}
300 truncated = []
301 for name in streams:
302 stream = getattr(process, name)
303 os.set_blocking(stream.fileno(), False)
304 selector.register(stream, selectors.EVENT_READ, name)
305 deadline = time.monotonic() + request["timeout_ms"] / 1000
306 try:
307 while True:
308 if time.monotonic() >= deadline:
309 reply["timed_out"] = True
310 break
311 events = selector.select(min(.1, max(0, deadline - time.monotonic())))
312 for key, _ in events:
313 data = os.read(key.fd, 65536)
314 if not data:
315 selector.unregister(key.fileobj)
316 continue
317 output = streams[key.data]
318 remaining = 65536 - len(output)
319 output.extend(data[:remaining])
320 if len(data) > remaining and key.data not in truncated:
321 truncated.append(key.data)
322 if process.poll() is not None and not selector.get_map():
323 break
324 finally:
325 if process.poll() is None or reply.get("timed_out"):
326 if MAC:
327 try:
328 cleanup = subprocess.run(["/usr/bin/sudo", "-n", "/bin/kill", "-KILL", "--", "-" + str(process.pid)],
329 stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, timeout=5)
330 if cleanup.returncode:
331 reply["cleanup_error"] = "Privileged cleanup failed. Check for remaining child processes."
332 except (OSError, subprocess.SubprocessError):
333 reply["cleanup_error"] = "Privileged cleanup failed. Check for remaining child processes."
334 try:
335 os.killpg(process.pid, signal.SIGKILL)
336 except (ProcessLookupError, PermissionError):
337 pass
338 process.wait()
339 process.stdout.close()
340 process.stderr.close()
341 reply.update(exit=process.returncode, **{k: bytes(v).decode("utf-8", "replace") for k, v in streams.items()})
342 if truncated:
343 reply["truncated"] = truncated
344 if MAC and (action == "shot" or request.get("screenshot")):
345 shot = Path(directory) / "screen.png"
346 try:
347 result = subprocess.run([GUI, "screenshot", str(shot)], capture_output=True, timeout=15, check=True)
348 if shot.stat().st_size > 8 * 1024 * 1024:
349 reply["capture_error"] = "The screenshot exceeds 8 MiB. Reduce the guest display resolution."
350 else:
351 reply.update(json.loads(result.stdout))
352 reply.pop("path", None)
353 reply["png"] = base64.b64encode(shot.read_bytes()).decode("ascii")
354 except subprocess.TimeoutExpired:
355 reply["capture_error"] = "Screen capture timed out. Check the guest's screen recording permission."
356 except (OSError, ValueError, subprocess.SubprocessError):
357 reply["capture_error"] = "Screen capture failed. Check the guest's screen recording permission."
358 return reply
359
360
361def main():
362 raw = sys.stdin.buffer.read(524289)
363 if len(raw) > 524288:
364 raise ValueError("The computer request is too large.")
365 request = json.loads(raw)
366 lock_path = Path.home() / ("Library/Caches/net.paperclover.computer.lock" if MAC else ".cache/snowglobe-computer.lock")
367 lock_path.parent.mkdir(parents=True, exist_ok=True)
368 descriptor = os.open(lock_path, os.O_CREAT | os.O_RDWR | os.O_NOFOLLOW, 0o600)
369 with os.fdopen(descriptor, "w") as lock:
370 fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB)
371 return execute(request)
372
373
374if __name__ == "__main__":
375 try:
376 print(json.dumps(main(), ensure_ascii=True))
377 except BlockingIOError:
378 print(json.dumps({"error": "Another computer operation is running. Wait for it to finish.", "status": 409}))
379 except ValueError as error:
380 print(json.dumps({"error": str(error)}))
381 except (OSError, subprocess.SubprocessError):
382 print(json.dumps({"error": "The guest operation failed. Check its arguments, permissions, and connection."}))