/horizon-device

name: horizon-device
description: Manage Horizon native VNC Device panels and drive isolated local desktops for simulators and native application tests through device_panel and the horizon-device CLI/MCP. Browser pages use horizon-browser.

Horizon native VNC and device control

Use this skill for Horizon VNC Device panels, simulators, and isolated native application tests. Browser pages use the `horizon-browser` skill and `browser_*` tools. Never drive a browser with device input.

Native VNC Device panel

Always observe interactive native tests live through a **Horizon native VNC Device panel in the user's current workspace**. Use a task-owned isolated desktop and private application state. Do not use noVNC or a browser viewer, or substitute screenshots or recordings for the live panel.

Use the public `device_panel` MCP tool for viewer lifecycle. Call `operation: "list"` to discover panels in the caller's workspace. Create a task-owned viewer with `operation: "create"` and the fixture's numeric loopback `endpoint` (IP and nonzero port); retain its returned `panel_id`. This requires a Horizon-launched agent and a supporting host. The tool does not provision a desktop or forward input. The source checkout's `scripts/device-smoke/README.md` describes the isolated fixture; launch it with `--native-view` and use its `vnc_address`, not a browser URL.

Creation returns immediately. Use `operation: "inspect"` and the returned id to verify `connection: "connected"`, `image_received`, `image_displayed` and an advancing `frame_sequence` while target output changes. `visible` is only a presentation setting; an image can be off canvas or clipped. Set `operation: "visibility", visible: true` for a hidden owned viewer, then verify actual presentation. Never claim that a separate isolated viewer is visible to the user merely because its screenshot is available.

`operation: "reconnect"` explicitly connects and acquires an unowned/restored viewer; do not take another owner's panel. Restored viewers stay stopped until reconnected. `operation: "close"` closes an owned viewer without terminating its target. On `host_timeout`, list before retrying a mutation because it may have completed. If the tool, supporting host or visible native viewer is unavailable, report the blocked lane. Do not fall back to noVNC, edit private runtime files, restart active sessions, or automate the developer's desktop.

Isolated desktop input

Drive the isolated target with explicitly configured device CLI/MCP tools: use `device_doctor`, then `device_screenshot`, then bounded `device_act` input with fresh geometry. Observe the result after each action. A `dispatched` receipt confirms input delivery, not application success. On stale geometry take another screenshot. On indeterminate input observe before deciding whether another action is appropriate; never replay blindly. The native Device panel is read-only.

The local CLI has the same contract: `horizon-device --target <private-target.json> doctor|screenshot|act|resize <JSON>`. For screenshots an optional output path writes a new private file instead of base64 JSON. Optional `--options JSON` (or `--options -` for stdin) accepts `region: {x,y,width,height}`, `output: {width,height}`, `format: png|jpeg`, and JPEG-only `quality: 1..100`. MCP screenshot accepts the same options directly. Omitting options preserves full-resolution PNG; JPEG defaults to quality 85. `act -` reads JSON from stdin. Use this to avoid putting entered text in shell history. The MCP server uses `--target <file> mcp` and stays bound to that configured target. Read `--help` if the executable/target was not supplied.

Action kinds: `click` (at, button), `drag` (from, to, duration_ms), `scroll` (at, vertical_notches, horizontal_notches), `type` (text), `key` (key, modifiers). Coordinates are original surface pixels. When a screenshot is cropped/scaled, map image pixels through `source_region` and `image_dimensions` before input: `origin + floor((pixel + 0.5) * source_size / image_size)` per axis. Keep the returned original geometry unchanged. Touch and accessibility are not implemented. Each `type` action accepts at most 256 Unicode scalars and 4096 UTF-8 bytes, without NUL. Text input is paced to let the application consume X11 key mappings; split longer text into bounded actions and verify the displayed result. Only control the explicitly authorized display; no implicit desktop fallback.

The caller owns the isolated display, application startup and cleanup. Independent fixtures need separate unused displays, private configuration/home, expiring targets, loopback VNC ports and owned process trees. Bind each agent to its exact target; do not share screenshot geometry across fixtures. Never control the developer's desktop, change production configuration, or stop a pre-existing application. When a target expires, stop; do not recreate it from a saved display number.

Finish the intended build, copy executables to a new task-owned directory, and record their hashes before launch. Keep build caches separate across source checkouts during qualification. Verify the running application's executable/hash against that frozen copy, following the actual child rather than a sandbox launcher such as `bwrap`. Close only the owned candidate normally when replacing it; a rebuild does not change a running process. Native View controls change local rendering, not target desktop geometry or VNC compression. Device screenshot crop/output options are separate controls.

For nested Device-panel tests, view the isolated Horizon containing that panel through a native panel in the user's workspace; keep each target and its geometry distinct.

For feature evidence, record directly from the task-owned isolated desktop using a recorder explicitly scoped to its display. Native panels have no video API; `browser_video` is for browser pages. Start before the flow, stop afterward and inspect decoded frames. If recording is