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