Skip to content

Latest commit

 

History

History
279 lines (241 loc) · 21.1 KB

SYSTEM-MAP.md

File metadata and controls

279 lines (241 loc) · 21.1 KB

System Map

This map answers two questions: “which program should do this?” and “where should a change live?” It describes current ownership, not a deployment requirement that every component always be present.

The accepted consolidation direction is recorded in repository-consolidation-and-publication.md. The platform testbeds listed below have completed their explicit cutovers, so their public implementation lives under machine-control; private deployment inventory remains in dotfiles, and any focused external repository is legacy or generated one-way.

Coordination and inventory

Component Current role Does not own
~/code/yepanywhere Agent provider sessions, user supervision, relay transport, peer identity/grants, and proposed cross-host delegation VM/device implementation details; generic hypervisor or desktop drivers
~/code/dotfiles/testbeds Private concrete testbed inventory, controller availability, portable discovery, and locators for controller-local credential files; link to each current authoritative guide Credential values, public lifecycle implementation, UI control, recovery, product assertions
Consuming application repository Builds, fixtures, test intent, application-specific assertions, and cross-platform campaign logic Machine provisioning and generic control transport

Machine Control owns exact-resource target-use arbitration. A coordinator may supply claimant/session metadata and manage renewal around active work, but the claim contract does not name or require that coordinator. Private inventory selects claim policy and state placement without becoming the live arbiter.

Proposal: access admission and pause extends MC-owned arbitration with waiting, temporary availability and shared controller-desktop reservations. Native/controller UI presents notices and operator controls; YA consumes state for agent supervision. This adds no second VM lease authority and moves no private inventory ownership.

YepAnywhere's delegation direction is documented in cross-host-delegation.md. Delegation creates a normal worker session on a YA peer; it does not turn YA into a raw proxy for every testbed CLI.

Target-controller implementation boundary

Current, unreleased desktop adoption: runtime/ owns ordinary Desktop and Browser surface consent, waiting/task admission, countdown, pauses, cooldown and ownership. It also owns exact profile selection, request/reference fencing and CDP stream lifetime. The Windows desktop resident runs it as a privately bundled Node child through inherited framed pipes. C# authenticates peers and operator decisions, observes native input/session facts, executes OS effects, retains protected guards and audit/artifact storage, and projects those facts into the child. The deterministic reference target executes the same policy with modeled effects. The unreleased Mac adapter now uses this policy with bounded ordinary, streamed-CDP and protected packaged acceptance. The Linux adapter now uses the same policy and passes native handoff/profile and sealed-package gates, including lock/restart and restored Off/claim release. Its native read-only activity observer belongs to Machine Control and exposes active-console-bound health/activity facts only. It has no input or command API; ordinary desktop effects retain AT-SPI/portal and never fall back to the appliance root input broker. Integrated Linux qualification is tracked in Tactical 155. The Python CLI/client remains the common agent-facing facade; this introduces no YA coordinator, private inventory owner or public approval endpoint.

Tactical 152 records the accepted original Browser slice. Tactical 153 owns the subsequent unified permission/handoff model, completed broad review and bounded Windows qualification. Ordinary and locked Browser, matching-companion startup and enrolled Desktop acceptance have passed on the bounded unsigned Windows ARM64 candidate. Native provider/credential/cover/relock proof is separate from shared-policy conformance. Each adopted adapter removes its replaced ordinary policy engine and fails closed if the shared child is unavailable. Any separate appliance/protected provider retains its explicit capability and authority boundary; it is not an ordinary desktop fallback.

Decision: Runtime and presentation keeps Machine Control's runtime authority independent of its settings, native notice and tray presentation. Personal, minimal and appliance presentation are modes of one package, not new coordinators or authorization providers. The unreleased Mac, Windows and Linux implementations share this design while retaining their platform-native providers and process placement. Runtime and presentation owns current direction; Tactical 113 records combined-source ARM64 qualification and its release limits.

Repository Current role Does not own
machine-control Cross-platform architecture/research, the target-selecting common client and contracts, owned resident facades/provider boundaries, Windows service/session implementation, fixtures, conformance corpus, and post-cutover public platform/testbed implementation Pre-cutover external testbed implementation, private deployment inventory, YA delegation, or product assertions

Current: The Windows-first runtime establishes the implementation boundary between authenticated local/remote callers, a Medium interactive-session companion, replaceable providers, and a typed LocalSystem protected route. Its physical x64 evidence covers ordinary system-shell control, UAC secure desktop, elevated applications, lock, logout, and Windows boot recovery. The dual-boot testbed must explicitly reselect Windows after one-shot EFI BootNext; a generic reboot otherwise returns to its default OS.

Current: One common client now selects and validates the Windows, macOS, and Linux testbed adapters, while each adapter retains its own lifecycle, workspace/storage policy, and guest transport. The three residents pass one guarded common semantic, effect, capture, artifact, and local/outside parity workflow. Workspace callers request persistent, isolated, or candidate intent; the owning adapter chooses and reports the actual provider mechanism and binds cleanup to a private exact-identity receipt. This is a shared contract and entry experience, not one universal resident or hypervisor implementation. ChromeOS and device providers remain the next families to receive more common facade coverage. Their target-specific lifecycle and recovery already live in their authoritative platform directories here; broader facade coverage must not flatten their platform semantics into one generic implementation.

Desktop VM testbeds

Current: the Mac desktop owns an experimental default-off covered locked-use profile. Its existing native executable launches a separate signed cover/input guardian, and its optional root authorization broker owns the deadline, restart marker, and failure relock. The unreleased recovery repair installs a root-owned, signed, non-setuid lock-only copy under PrivilegedHelperTools. The broker enters the original console's GUI bootstrap through fixed launchctl arguments; that copy drops to the console user, re-execs its fixed path and verifies the console again before requesting lock. The broker's own IOKit observation determines completion. This is a Machine Control provider placement detail, not a new delegation or arbitrary privileged-command surface. Permissions owns native SMAppService registration and typed helper preparation; System Settings owns service approval and authentication. Settings only changes the prepared local preference. The calling agent/integration owns a live bounded task connection and explicit completion. This adds no YA coordination or dotfiles inventory ownership and does not reuse exposed appliance unlock as a workstation fallback.

Current: The optional Windows workstation host is another deployment of Machine Control's shared ordinary providers. It runs under the interactive user; the existing appliance broker remains a separate privileged deployment profile. YepAnywhere consumes the installed desktop app's authenticated Python CLI, with default-off eligible session advertisement and media presentation. MC owns installation, updates, native access and resident lifecycle. YA's former workstation installer, grants, deferred tool and private process job are retired; it does not stop the independent desktop on session close or crash. The headless workstation profile and protected appliance remain independently available. The desktop's optional UAC helper is a separate administrator-installed LocalSystem service with a protected payload. The Medium desktop resident owns grants and live admission; the helper verifies that resident and calls back for each request's authority before effects. Permissions owns setup/removal, Settings owns per-run opt-in, and neither surface inherits the appliance's protected authority. The unreleased desktop locked-use integration reuses that protected payload with a separate controller grant. The Medium resident owns consent and task admission; the controller owns key and one-shot credential custody; an independent SYSTEM guardian owns failure relock for the bound console session. That Windows guardian now also owns the opaque single-display cover and physical-input interception. Windows uses its own Win32/DWM presentation mechanism; the Mac guardian remains a separate native implementation. Both profiles bind cleanup to the task's initial lock state. Consumer acceptance and its limits live in YA's topic; historical headless native acceptance remains in Tactical 036.

Current: Optional workstation unlock has an independent privileged service, administrator-owned grants and an elevated consent flow. Machine Control owns that installation and enforcement; YepAnywhere owns controller key/credential custody and product integration. The appliance broker is not its authorization fallback. See Windows protected unlock and Tactical 037.

Repository Administration/inner control Outer control
platforms/windows Authoritative UTM/macOS and libvirt/Linux lifecycle/workspace policy, minimized doctor, PowerShell/SSH administration, and bounded access to the Windows resident UTM or headless QEMU screenshot and input remain explicit recovery routes
platforms/macos Tart lifecycle and COW workspaces, the macOS resident, and the explicit existing-session unlock helper. The Intel KVM profile owns claimed Quickemu and libvirt lifecycle, libvirt workspaces, and pinned guest SSH Tart for Tart guests. QMP and loopback VNC for Intel KVM bootstrap and recovery
platforms/linux Authoritative UTM/macOS and libvirt/Linux lifecycle/workspace policy, minimized doctor, guest/session execution, and bounded access to the Linux resident UTM or headless QEMU screenshot and input remain explicit recovery routes

These repositories implement the right broad ordering: lifecycle and administration, then resident semantic/capture/input control, with outer pixels/input named only for bootstrap and recovery. Their guarded doctor and common conformance paths now enforce that ordinary control does not reach the outer route merely because it is convenient.

The opt-in Windows VirtualBox adapter owns native host identity, claims, lifecycle and pinned SSH for experimental Windows/Linux candidates. Guest residents and credential verifiers remain in their existing platform/runtime owners. Creation/bootstrap is not yet an adopted common factory, and promotion/workspace derivation remains unqualified.

Physical and device testbeds

Repository Current role Important boundary
platforms/chromeos Root SSH, browser CDP, Chrome desktop accessibility, screenshots, and device-native input on a designated developer-mode Chromebook Update-sensitive and guest-resident; not an independent physical recovery path
hardware-kvm-testbed Planned HDMI capture and USB HID for externally controlled physical hardware Pixel/HID only; intended as outer recovery and independent observation, currently in bring-up
platforms/ios Explicit physical-iPhone selection, signing lifetime, typed common iOS operations, CoreDevice lifecycle/crash reports, Agent Device semantic XCTest, libimobiledevice system logs, screenshots, input, leases, and recovery The agent runs on the Mac; a stock iPhone cannot host a general YA worker
platforms/android Explicit physical-handheld selection, common readiness, ADB administration/deployment/capture/input, and guarded one-shot PIN unlock Phone keyguard policy is not inherited by Quest or every ADB derivative
platforms/quest Explicit ADB target selection, device state, deployment, leases, and recovery for Quest Protected headset/account surfaces remain human gates
platforms/steamdeck Direct device administration and session-aware deployment/control Physical recovery capability depends on available hardware and session state
Android-family shared ADB provider Executable discovery, enumeration, exact transport, shell, battery, and wake parsing reused by Android and Quest Device-profile lifecycle, protected operations, semantics, and safety policy

Research and candidate providers

Component Use it for Do not make it
Research corpus Provider architecture/license/evidence dossiers and per-platform option comparisons Exact experiment log, source-pin store, decision topic, or implementation
machine-control-spike Exact Cua pins, conformance evidence, macOS/Windows behavior, and security findings The current architecture hub or production implementation
Cua Driver Spike-supported provisional normal-user desktop core; exact-window semantics/capture, explicit delivery/effects, sessions, and strong fixtures Cross-host coordinator, testbed lifecycle owner, protected-control trust foundation, or owner of the common contract
Open Computer Use Compact agent-neutral Computer Use CLI/MCP across Windows, macOS, and Linux; first common-provider comparison candidate Proven session/result/remote core or exact-window equivalent without conformance evidence
WinApp Adopted WinVM UIA route, Windows comparison provider, and possible gap-filling adapter Cross-platform core, effect oracle, or protected desktop provider
Touchpoint Small cross-platform AX/UIA/AT-SPI/CDP facade and exact-window identity reference Proven occlusion-independent capture or Wayland-input solution without target validation
Agent Device Current iOS XCTest provider and a source of compact agent-oriented snapshot/action/recovery behavior Exact-window macOS control, native Windows control, or the overall desktop/control fabric
libimobiledevice Narrow adopted physical-iOS os_trace_relay provider behind bounded transactional system-log artifacts Replacement for CoreDevice/XCTest, general device shell, or duplicate owner of app/crash/file operations
Peekaboo Deep macOS reference for exact-window capture, background action routing, transient system surfaces, and native fixture design Cross-platform provider or protected-control boundary
kwin-mcp Linux/KWin reference for isolated target-native Wayland sessions, AT-SPI, compositor capture, and libei input Proven universal Linux desktop or exact-window facade
YepAnywhere Device Bridge Human remote viewing and fast pixel/input backends, especially its iOS Simulator work Semantic agent control or the cross-platform orchestration contract
RustDesk and similar remote desktop projects AGPL-licensed reference architecture for session services, desktop switching, capture, and input A wholesale trust boundary imported into the agent-facing system

Detailed claims and evidence levels live in the provider index and platform index. Cross-provider decisions live in provider-landscape.md. Being listed here does not mean a provider has passed on every advertised platform.

Ownership rule

When adding a capability:

  1. Put target-specific lifecycle, bootstrap, and recovery in the authoritative platform/testbed source: the external repository before its consolidation cutover and its platform directory here afterward.
  2. Put reusable resident semantic behavior and provider adapters here; keep a target-specific native runner in its authoritative platform/testbed source when it is not a reusable machine-control component.
  3. Put cross-provider capability vocabulary and conformance expectations here beside the implementation they govern.
  4. Put worker creation, peer authorization, observation, and supervision in YepAnywhere coordination.
  5. Put exact-target usage arbitration in Machine Control; let any coordinator consume that generic claim surface.
  6. Put product-specific assertions in the consuming application repository.

Do not add the same operation independently to all five layers. Choose one owner and expose it through adapters.

Desktop product and release infrastructure

Machine Control owns the optional Tauri desktop operator application, its native resident/providers, grant enforcement, product updater key/configuration, and artifact acceptance. Desktop Release Kit owns the shared update contract and release validation reference; simple-app-update-server owns metadata routing over GitHub Releases. The Machine Control website owns the public desktop download page and resolves versioned installer links from the desktop release family; it does not implement the updater protocol. Dotfiles owns private signing credential locators and service deployment. YepAnywhere connects as a consumer rather than owning a second copy of the desktop application's grant UI or updater.

The Mac desktop embeds the Swift resident in its native process. Windows owns a distinct ordinary-user desktop companion and inherited operator transport, with grants enforced inside that companion. Its process job owns resident/ provider children while explicitly excluding user-launched applications. The headless workstation package and protected appliance remain separate profiles. Windows desktop owns the standalone workstream.

Linux owns an ordinary-user companion, inherited operator channel, native GTK approval process, and a distinct desktop socket. It reuses AT-SPI semantics while portal consent owns capture/input; root appliance input stays separate. Linux desktop owns the workstream, and the shared release family owns its eventual packages.

Native command authentication

Current: Machine Control owns the Mac mc-sudo/mc-sudo-askpass pair, its desktop packaging, local dialog and system-sudo authentication route. YepAnywhere owns opt-in discovery, publisher verification and agent launch instructions. This command route does not extend resident grants or the Windows protected broker. See native sudo.

Installed CLI consumers

Current: desktop-app consumers use MC's bundled Python CLI and instructions. MC owns product installation, updates, resident lifecycle and native access; YA owns verified launch discovery, eligibility, optional adaptation and presentation. YA's old Windows component is retired after accepted installed native/browser, model, media and lifecycle checks. Session advertisement grants no access and closing YA does not revoke MC grants; native Stop, expiry and MC restart do. Installed agent CLI and YA Tactical 142 own the implementation and migration gates.