vmctl-guest-agent

The in-guest agentbox driven by the vmctl controllers (rvmctl / evmctl) over the host↔guest transport (virtio-serial / TCP / HTTP). Extracted from research-vm-controller/guest-agent/ with full history; consumed by the umbrella as a sibling submodule. Per-variant versioning + shared wire contract — see CHANGELOG.md for the variant/version map and follow-ups.

---

agentbox — the in-guest agent (research/15)

Lets the controller (and an AI via the guest_* MCP tools) operate inside a guest: run, files, registry, processes, screenshot, and GUI/input + installer choreography.

Pieces

• rvmc_agent.py — Python 3.4+ spine. JSON-RPC/MCP over the host-only virtio-serial port de.zkm.rvmc.agent.0 (--virtio), or TCP --port (Win9x fallback) / --stdio (test).
• rvmc-input.au3 — AutoIt "hands" (windows/keys/mouse/controls/installer wizard). Compile: Aut2Exe /in rvmc-input.au3 /out rvmc-input.exe /console.

Transport

The controller renders a <channel> into the domain XML binding a host unix socket at <state>/agent-sock/<domain>.sock ↔ the guest vioser port. Host-only by construction — the artwork and its network can't see it. rvmc/guest_bridge.py connects to that socket.

Bake into the WinXP base (then re-snapshot ready)

1. Install: Python 3.4 (XP ceiling), AutoIt 3.3.16.1 (tools-box winxp-autoit-3.3.16.1), qemu-guest-agent, the vioser driver (virtio-win 0.1.96).
2. Copy this folder to C:\rvmc\ (compile rvmc-input.exe there).
3. Autostart in the interactive session (NOT a service — session-0 can't see the desktop): HKLM\Software\Microsoft\Windows\CurrentVersion\Run → rvmc-agent = pythonw C:\rvmc\rvmc_agent.py --virtio de.zkm.rvmc.agent.0
   • enable autologon so the session exists at boot.
4. Snapshot as ready.

Bootstrap (first time, before the channel agent exists)

Push the files via the QEMU guest agent (guest_upload.py / guest_exec.py) into a freshly cloned XP, set the Run key + autologon, reboot, re-snapshot. (See research/15 §9.)

Mac OS 9 guest — MUST be strict Python 2.3 syntax (research/64)

The classic Mac OS 9 agent runs under MacPython 2.3.3 (Jack Jansen, the last classic-Mac Python). We use it precisely because its socket module is GUSI-over-Open-Transport — the interpreter provides the TCP transport that hand-rolled C (Retro68) could not bind (OTOpenEndpointPriv private-ABI fault, research/67 §5.1). The agent talks the same HTTP JSON-RPC contract as the Windows agent, on :9610 via hostfwd.

Hard limit for any agent writing/editing Mac OS 9 guest code: Python 2.3 ONLY. It is not 3.x and not even 2.4+. Things that silently SyntaxError/NameError on 2.3 and will burn an iteration if you forget:

• No conditional expression X if C else Y (added 2.5) — use a plain if/else.
• No with statement (2.5) — use try/finally.
• No set/frozenset/sorted()/reversed() builtins, no decorators (all 2.4) — use dict/.sort()/manual reverse.
• No stdlib json (2.6) — use the bundled minijson.py (encoder + decoder).
• No b"..." byte literals, no print(...) function — print is a statement in 2.x.
• Toolbox surface is Carbon.* (Qd/Qdoffs/Evt/File/Gestalt/AE), MacOS, findertools, aetools. Classic colon paths (Disk:Folder:file).

Bring-up note: under qemu TCG the guest mouse does not track (research/48), so drive the one-time MacPython VISE installer by keyboard (QMP) or a human click — the agent's own PostEvent mouse is what fixes pointer input afterwards.

Security

Reachable only down the host-only virtio pipe; no listener the artwork can reach. guest_* write/run/reg/kill/install tools are admin-scoped in the controller (auth.py).