HyperHand 0.3.0

Breaking: the MCP tool surface is redesigned for AI callers. Tool names, parameters and result formats change without aliases, and the guest protocol moves to a new generation: the host refuses older agents with agent_outdated until vm_update_agent is run.

Migration from 0.2.0

1. Host. Install the new release over the old one with hyperhand.exe install (one UAC prompt).

2. Guest agents. Run vm_update_agent on every VM. Until then every agent call to an old agent is refused with agent_outdated (fields agent_protocol, host_protocol, next call vm_update_agent); vm_status, vm_doctor and vm_update_agent keep working on it, and vm_update_agent replaces a 0.2.0 agent in place. If the agent does not answer, use vm_install_agent. A VM restored from an older checkpoint brings back the old agent and needs vm_update_agent again.

3. Every call names its VM. Pass vm (a name from vm_list) on every tool except vm_list; there is no default VM. vm_end_turn may omit vm only to end the whole task.

4. Results and errors are JSON. Parse the single JSON text item of each result (an observation's PNG image comes before it) instead of ok, handle: N, name<TAB>state or exit_code: text. An error is an isError result whose text is {"error", "reason", "next", ...}; follow next.

5. Replace removed tools and parameters:

   0.2.0	Now
   vm_screenshot (source, region, coordinate metadata)	vm_observe (handle or pid, max_size); actions take image pixels with its observation_id
   vm_controls	vm_observe with controls: true (indexed text tree), or vm_find_controls for one control
   vm_focus_window	nothing: actions activate their target (activate, default true)
   window, title, exact on any tool, title-selected waits	handle (from vm_windows, vm_find_controls, vm_observe, vm_launch or an action result) or pid; vm_wait window and control kinds with handle/pid, automation_id, control_name or observation_id and index
   vm_type mode (clipboard paste)	vm_type always types key events; vm_clipboard_set then vm_key ctrl+v to paste
   vm_click double	count: 2
   vm_scroll delta	delta_y (and delta_x)
   vm_drag x1, y1, x2, y2	from: {x, y}, to: {x, y}
   vm_checkpoint name	label and keep; select checkpoints by the returned id
   GUI programs started with vm_exec	vm_launch (vm_exec waits for the command to finish)

6. Scripts. scripts/restart-tray.ps1 and scripts/dev-install.ps1 are gone: development installs use go run ./cmd/hyperhand dev-install. Scripts without an MCP client can use client/hyperhand_client.py; pass one task_id per piece of work so that ownership and observations carry over between calls.

Removed

• scripts/restart-tray.ps1, which installed a build with a UAC prompt. Development installs use go run ./cmd/hyperhand dev-install (no UAC, through the preauthorized HyperHand Dev Install task registered once with scripts/dev-install-setup.ps1).
• vm_screenshot: replaced by vm_observe. There is no source, region or coordinate metadata to apply; actions take image pixels of an observation.
• vm_controls: replaced by vm_observe with controls: true, which returns the tree as indexed text instead of JSON nodes.
• vm_focus_window: actions activate their target window themselves (activate, default true).
• Legacy title-selected window waits; the new UI conditions use HWND/PID or observation/control identity instead.
• Title selectors: the window, title and exact parameters of every tool. Windows are selected by handle (from vm_windows, vm_find_controls, vm_observe, vm_launch or an action result) or pid only.
• vm_type mode: the clipboard paste path is gone; text is injected as Unicode key events, with the Hyper-V keyboard for ASCII text when the agent is not available.
• vm_click double (use count), vm_scroll delta (use delta_y), vm_drag x1/y1/x2/y2 (use from/to), vm_checkpoint name (use label and keep).
• Free-text results: ok, handle: N lines, name<TAB>state lists and exit_code: blocks.
• Guest op screenshot: all screenshots are taken on the host.

Changed

• vm_shutdown that times out because a program blocks shutdown now says what the guest may look like: Windows may already be signing the user out, with the agent gone and the desktop ignoring input. The error carries vm and state and a next naming vm_observe, raw input, and vm_turn_off or vm_restore as the only way out of a stuck guest, instead of the generic failed advice. The tool description advises saving or closing such programs first, or using vm_save.
• vm_exec with admin: true whose timeout_ms passes before elevation completes (an unanswered UAC prompt) now fails with elevation_timeout (the command did not run; next says how to elevate without a prompt or answer it from the host) instead of returning timed_out: true with empty output, which looked like a command that ran too long. The guest protocol changes: run vm_update_agent on every VM.
• Documentation: README.md is rewritten for human readers (what HyperHand is for, quick start with example requests, limitations, privacy); the tool list moves to the user guide, and building, testing, development installs and releasing move to the new docs/building.md.
• New icon for hyperhand.exe, its tray icon, the settings window and hyperhand-agent.exe: a white monitor outline on a blue rounded square, replacing the gripper icon.
• Success results that need a follow-up call carry next: a vm_push mirror plan (status: "planned") says that nothing was written yet and names the apply call (phase: "apply", its plan_id, the same paths, force and task_id, before expires_at); a background vm_exec names the vm_job call with its job_id. Callers had stopped after the plan, believing the mirror done.
• Breaking: vm is required on every tool except vm_list; there is no default VM any more ("the only running VM, or the only VM if none is running"). With several VMs on a host, a call meant for a VM that was off silently reached another one, including vm_restore, vm_shutdown, vm_turn_off and vm_exec. A call without vm is refused before anything runs with invalid_argument, reason vm is required: there is no default VM, next listing the VM names and field vms; the input schemas mark vm as required. vm_end_turn may still omit vm to end the whole task (only the task's own waits, temporary checkpoints and ownership), but all_temp: true requires vm (reason vm is required with all_temp: ...) instead of deleting temporary checkpoints on every VM.
  • Migration: pass vm (a name from vm_list) on every call; pass vm with every vm_end_turn that uses all_temp: true; Stop hooks that call vm_end_turn without vm (such as the examples in docs/hooks/) keep working.
• Observed controls can be re-located using their previous screen bounds as a read-only hint. The guest verifies the exact runtime ID and control-view ancestry to the requested window before accepting a hit; covered, moved or mismatched hints fall back to the existing traversal. Actions and wait conditions still read current values and state, and scoped reads retain password-subtree protection.
• Semantic actions return readable post-action state and verify Toggle, Expand, Collapse, Select and ScrollIntoView outcomes. An immediate read is followed by up to 250 ms of read-only polling when needed; actions are never replayed. Unknown outcomes, password values and unobservable Invoke effects stay verified: null.
• Every result is one JSON object in a single text item (vm_observe and actions with an after-action screenshot put a PNG image item before it). Every error is an isError result whose text is {"error": <code>, "reason", "next", "run_id", ...fields}; next names the call that makes progress. Codes: invalid_argument, stale_observation, stale_element, session_unusable, activate_failed, target_disabled, covered, integrity_mismatch, target_not_responding, unsupported_pattern, partial_input, agent_required, agent_outdated, ambiguous_target, no_window, no_checkpoint, failed.
• Tools carry MCP annotations: read-only (vm_list, vm_status, vm_checkpoints, vm_pull, vm_clipboard_get, vm_wait, vm_windows, vm_find_controls, vm_observe, vm_doctor), destructive (vm_shutdown, vm_turn_off, vm_restore, vm_checkpoint_delete, vm_push, vm_update_agent, vm_end_turn) and idempotent hints; openWorldHint is false.
• vm_windows returns {windows, foreground, focused_control, session}; each window gains group_root (the root of its owner chain within the process, at most 8 links) and integrity (low, medium, high, system); focused_control is the UI Automation focused element with window, name, control_type, automation_id, class_name, runtime_id, rect; session is the agent's session state.
• Actions (vm_click, vm_drag, vm_scroll, vm_set_value, vm_invoke, vm_type, vm_key) take observation_id with image pixels or a control index; the host maps pixels to the screen, re-finds controls by runtime ID and refuses an observation whose window moved, resized, minimized or closed (stale_observation). The check chain before input is: session, freshness, target, activation, enabled, hit (covered), integrity, each with its code and next. Actions default to activate: true and to observe_after: screenshot (none for vm_type and vm_key; controls, both; settle_ms default 300, max 5000), returning the receiving window and an after observation with a new ...

HyperHand 0.2.0

Added

• vm_type supports mode: keys through guest Unicode SendInput, preserving the clipboard, limiting text to 16384 UTF-8 bytes and rechecking the selected foreground window between characters. vm_type and vm_key accept optional window selectors; vm_key also accepts an ordered sequence of up to 256 combinations. Partial input is reported without automatic retry.
• vm_screenshot supports a region crop and max_size downscaling, with JSON dimensions, crop origin, actual per-axis scales, VM identity and source/session coordinate metadata. Unknown or non-console agent captures are not marked compatible with console input.
• Read-only vm_controls returns a bounded UI Automation control-view tree for a selected window. A separate helper has a 10-second timeout; password names and subtrees are not read.
• vm_focus_window, window-relative vm_click and window conditions in vm_wait share window selection by handle, PID and case-insensitive title, with optional exact full-title matching. A PID can select a window alone or restrict a title or handle match.
• vm_wait conditions window_exists, window_gone and window_foreground, polled by the host without holding the agent connection between checks. Successful appearance and foreground waits return the window's handle and title; disappearing includes windows that become hidden or cloaked. These use the existing agent list_windows operation without a guest protocol change.
• Dedicated HyperHandService Windows service under NT SERVICE\HyperHandService, with Hyper-V rights assigned to the service account and an access-controlled local named pipe for specific VM operations and the guest socket tunnel.
• Host tray restart action: restarts the ordinary tray/MCP process without restarting the service or any VM; in-progress requests are interrupted.
• vm_start waits until the desktop is usable: the guest agent answers (up to 90 seconds) and the session is unlocked. A session Windows locked after signing in is unlocked with the password stored for the VM; otherwise the error says why the desktop is not usable.
• vm_status reports a VM's power state, the agent, the session lock state, a non-console session, an open UAC prompt and whether an unlock password is stored.
• vm_unlock unlocks a locked session with the stored password. The password is typed once, only after the agent confirms the session is locked, is the console session, shows the sign-in screen with keyboard input on its secure desktop and has no UAC prompt open.
• Host settings window, opened by clicking the tray icon or from its Settings... menu item: the MCP endpoint and port (the port can be changed and is saved per user; -port still overrides it), the service status and a Virtual machines list with the Hyper-V VMs and their state, with Set unlock password... and Clear unlock password per VM (stored in Windows Credential Manager for the current user).
• Open console per VM in the settings window opens Virtual Machine Connection without a UAC prompt, or brings an already open one to the front; Open console when started opens it whenever vm_start starts that VM. install registers the on-demand HyperHand Console task for this, which runs vmconnect.exe with the installing user's highest privileges; uninstall removes it.
• Agent op session_state.
• vm_focus_window and vm_click with a window name the locked session as the reason when they fail on a locked guest.
• vm_windows lists the guest's visible top-level windows with handle, title, class, process, position, enabled, foreground, owner and modal state.
• vm_focus_window accepts a window handle and returns the focused window's handle.
• vm_click accepts window or handle: coordinates are then relative to that window, and the click is refused unless it is the enabled foreground window and the point is inside it, on screen and not covered by another window.

Changed

• vm_status reports busy when this host already has an agent request in progress, without queueing its probe behind that request. Connection and response failures leave the guest state unknown rather than claiming the agent is offline.
• vm_screenshot now returns JSON metadata instead of the former <width>x<height> text item. Cropped and scaled coordinates must be mapped before console input; old agents can still supply images but cannot establish coordinate compatibility.
• Breaking: vm_focus_window now rejects multiple matching windows instead of focusing the first match. All focus requests require an agent supporting list_windows; older agents must be updated, with no fallback to title-only focus. Window clicks and waits also reject ambiguous selection, including disappearance waits.
• Breaking: vm_stop is replaced by vm_shutdown, which shuts the guest down normally through the Hyper-V shutdown integration service and waits up to 3 minutes until the VM is off (failing, without turning it off, when a program blocks shutdown), and vm_turn_off, which turns the VM off immediately as vm_stop did.
• Host tray menu text is in English.
• hyperhand.exe, its tray icon and the settings window use a new gripper icon, from the executable's resources at the system's small and large icon sizes. hyperhand-agent.exe and its tray icon use it too.
• The guest agent tray uses the same notification icon code as the host instead of fyne.io/systray, so it also survives a taskbar that is not ready at logon; a left click opens its menu as before.
• hyperhand-agent.exe uninstall no longer starts a PowerShell helper to delete the folder it runs from after it exits: it moves its own executable to %TEMP% and deletes the folder at once.
• Normal host tray startup no longer requests elevation. Installation, updates and uninstallation still require administrator approval.
• hyperhand.exe install installs both executables under %ProgramFiles%\HyperHand, records the owner under %ProgramData%\HyperHand, and migrates the HyperHand logon task from highest privileges to least privilege. Repeating install updates the installation.
• Host file transfers use the ordinary tray user's permissions. The local MCP endpoint remains unauthenticated; the broker pipe ACL is not MCP authentication.
• scripts/restart-tray.ps1 now invokes installation/update of the built executables instead of terminating every process named hyperhand.exe.
• install and uninstall no longer run an embedded PowerShell script: the elevated hyperhand.exe does the work itself through the service control manager, Task Scheduler, local group and security APIs. Uninstalling from the installed hyperhand.exe leaves %ProgramData%\HyperHand\uninstall-cleanup.exe until the next restart.

Fixed

• Window click checks, focus changes, keyboard sequences and clipboard writes share the input lock, so another MCP input operation cannot invalidate a queued click check or replace text between clipboard setup and paste.
• Elevated command cleanup could hang when an early launcher failure raced a pending named-pipe accept, even after the request deadline. Pin go-winio to Microsoft's listener shutdown fix, which preserves the close signal; the fix is not yet in a tagged release. A repeated early-failure regression test covers this path.
• Reinstalling could stop with "Access is denied" after stopping the service, leaving the service stopped and no tray: setup tried to end the service's process, which runs as the service account. It now waits for that process to exit.
• The host tray icon no longer stays an empty placeholder without menu when the tray starts at logon before the taskbar is ready. The tray now uses its own notification icon code instead of fyne.io/systray: a failed add is retried every 5 seconds and whenever the taskbar is created, and every add carries the icon, tooltip and callback message and selects version 4 behaviour.
• VM start and stop wait up to 45 seconds for asynchronous Hyper-V jobs and report failures or timeouts without automatically resending the operation.
• vm_focus_window no longer puts ribbon programs such as AutoCAD into key-tip mode. When the window did not come to the front at once, the agent simulated an Alt press, which arrived after the switch in the focused window; it now injects a zero-distance mouse move instead.

HyperHand 0.1.2

Fixed

• Command cancellation and timeouts terminate descendants even after the original shell has exited, while successful commands can still launch background applications.
• Elevated commands include UAC consent in their timeout, cancel without a second elevation prompt, and reject workers that arrive after the request expires.
• Elevated CMD commands preserve UTF-8 text, Unicode filenames, percent expansion and exit codes.
• Requests cancelled while waiting for another agent call return promptly without disturbing the active connection.
• Saved and paused Hyper-V machines display the correct state.

HyperHand 0.1.1

Added

• hyperhand.exe uninstall: relaunches itself elevated if needed, stops the tray, deletes the HyperHand scheduled task, the Hyper-V socket service registration and %LOCALAPPDATA%\HyperHand, and shows what was removed. The exe and its folder are kept.
• hyperhand-agent.exe uninstall: without administrator rights, stops the running agent and deletes the HyperHandAgent Run value, %LOCALAPPDATA%\HyperHand and C:\Users\Public\HyperHand, and shows what was removed.

Fixed

• File transfers use unique temporary files so existing files named <destination>.hhpart are preserved, including when a transfer fails.
• Uploads return an error promptly when the guest disk is full, without blocking subsequent agent requests.
• Commands no longer block the agent when completion and cancellation occur together.
• Guest uninstallation waits for the uninstall process to exit before deleting its executable, including when the result dialog stays open.

HyperHand 0.1.0

Initial release.

Added

• Host tray program hyperhand.exe serving MCP over Streamable HTTP at http://127.0.0.1:8770/mcp; -port selects another port. Relaunches itself elevated, runs as a single instance, and logs to %LOCALAPPDATA%\HyperHand\hyperhand.log.
• hyperhand.exe install: registers a scheduled task that starts the exe from its current location at logon with highest privileges, and starts it.
• Registration of the HyperHand Hyper-V socket service on the host at startup.
• VM control through Hyper-V WMI, without a guest agent: vm_list, vm_start, vm_stop, vm_screenshot (PNG at the guest resolution), vm_click, vm_drag, vm_scroll, vm_key.
• Checkpoints: vm_checkpoints, vm_checkpoint, vm_restore (exact name; starts the VM after restoring unless start is false).
• Optional vm argument on every tool; defaults to the only running VM, or the only VM if none is running.
• Guest agent hyperhand-agent.exe: tray app in the user's session that serves host requests over a Hyper-V socket; install subcommand copies it to %LOCALAPPDATA%\HyperHand and starts it at logon through the HKCU Run key, without administrator rights.
• vm_install_agent: copies the agent into the guest with Copy-VMFile (enabling the Guest Service Interface if needed), runs its installer through the keyboard, and waits for it to answer.
• vm_update_agent: replaces the running agent with the build next to hyperhand.exe and waits for it to restart.
• vm_exec: runs a PowerShell or cmd command as the logged-on user with a timeout and returns exit code, stdout and stderr; admin: true runs it elevated.
• vm_push and vm_pull: copy files or directories recursively between host and guest, streamed through .hhpart temporary files; vm_push skips files whose SHA-256 matches the guest copy unless force is true.
• vm_type: pastes text through the guest clipboard when the agent is available, so an IME cannot alter it; falls back to keyboard input for ASCII text.
• vm_clipboard_get, vm_clipboard_set, vm_focus_window, vm_wait (process exit, process running, file exists), and vm_screenshot with source: agent.
• scripts/restart-tray.ps1: swaps in a rebuilt build\hyperhand.exe.new and restarts the tray.
• Release builds through GitHub Actions: pushing a vX.Y.Z tag runs the tests, builds hyperhand.exe and hyperhand-agent.exe for Windows amd64, and publishes hyperhand-X.Y.Z-windows-amd64.zip on a GitHub Release with the version's changelog section as notes.
• Version stamped at build time (-X hyperhand/internal/proto.Version); reported by the MCP server and the agent ping, dev for builds without it.