Kvm Pilot

Identify the device and the system behind it (read-only). Returns ``host``/``driver`` plus the driver's ``info`` block: model, vendor, firmware and hardware detail as the device reports them (a PiKVM/GLKVM describes the appliance; a BMC describes itself and the managed system). Use it to confirm what you are talking to. It says nothing about whether the device is safe to act on (``healthcheck``), what it can do (``capabilities``), or the host's power (``power_state``).

Inventory the KVM's virtual-media (MSD) storage (read-only). Check this BEFORE asking the operator to download or upload an ISO — the image may already be on the device (#127). Returns stored images, the selected image, and attach state (``online``). ``host_visible_as`` (when known, #78) is the device name the TARGET's boot menu shows for truly presented media — match it to pick the right boot entry and to confirm the medium is really inserted. Details: `doctrine` topic 'interfaces'.

Return the device/host event log as text (read-only). ``seek`` is seconds of lookback (0 = the whole buffer). This is the go-to diagnostic when video/streamer/encoder or power behaviour looks wrong: the text log names a fault (e.g. a stuck encoder behind a ``snapshot`` 503) that a screenshot cannot. Tail-follow is intentionally not exposed — it blocks over the server's synchronous transport.

Mount an ISO as virtual media on the host. GATED act (media effect gate); reversible. ``source`` is a local path or an ``http(s)://`` URL; ``usb=true`` attaches as a USB flash drive instead of a CD-ROM. Needs ``KVM_PILOT_MCP_ALLOW_MEDIA`` + per-invocation approval. Mounting bumps the frame generation, so a mouse click planned against the pre-mount screen is invalidated.

Move the mouse (and optionally click) on the host. DESTRUCTIVE (HID input). A **click** must carry the ``observed_frame_ref`` it was planned against (from a prior ``snapshot``); it is refused — re-``snapshot`` and retry — if the host rebooted/swapped media since, the observation is older than ``KVM_PILOT_MCP_FRAME_MAX_AGE`` (60s default, #141), or the ref wasn't issued by this server. Move-only (``button`` omitted) needs no ref. ``coord_space``: ``percent`` (0.0-1.0, default — survives resolution changes), ``pixel``, or ``raw`` kvmd. Gated by ``KVM_PILOT_MCP_ALLOW_HID`` + per-invocation appro…

Change host power state. DESTRUCTIVE. Gated by the power effect gate + per-invocation approval (elicitation, or ``confirm=true`` under standing policy); denials come back through the same path with a typed ``outcome`` (#234). The result carries an honest effect report (#168): ``verified`` is true/false when the driver has a trustworthy power signal (Redfish PowerState, a wired ATX LED), and ``null`` — with the reason and what to do instead — when it doesn't. A power action also invalidates prior ``snapshot`` frame refs (generation bump), so a stale mouse click can't land on the post-reboot sc…

Report whether the managed host is powered on (read-only). Returns ``powered_on`` (bool) plus, on PiKVM-family devices, ``atx`` (the power/HDD LEDs and button states); BMC/AMT drivers answer from the controller's power state. The cheap check after ``power``/``wake`` when their ``verified`` came back null, and before deciding whether a dark ``snapshot`` means off or asleep. Changes nothing: to change power use ``power``, to wake a sleeping host use ``wake``.

Press and release one key on the managed host's console. DESTRUCTIVE (HID). For a single non-text key: ``Enter`` to submit, ``Escape``, ``F2``/``F12`` at POST, arrows and ``Tab`` in firmware menus. For a chord use ``send_shortcut``; for words use ``type_text``; for Ctrl+Alt+Del use ``ctrl_alt_delete`` (power gate). Nothing echoes back — ``snapshot`` after. Same gating as ``type_text``: ``KVM_PILOT_MCP_ALLOW_HID`` + per-invocation approval. Returns the typed act outcome (receipt, or the denial reason).

Send a key chord — comma-separated kvmd key codes, e.g. ``ControlLeft,AltLeft,Delete`` or ``ControlLeft,AltLeft,F2``. DESTRUCTIVE. Gated by **effect**, not transport: a reboot/power chord (Ctrl+Alt+Del, Magic SysRq) is classified ``power_soft``/``power_hard`` and needs ``KVM_PILOT_MCP_ALLOW_POWER``; an ordinary session chord is ``hid_control`` and needs ``KVM_PILOT_MCP_ALLOW_HID`` — so a reboot can't slip through the HID gate.

Report this server's current operating posture (read-only; offline, no device I/O — answers even when the device is down). Call this after a context compaction, when resuming a long flow, or before planning act calls: it names the target, dry-run/read-only state, which effect gates are open (by class name only — opening one is operator-only, out of band), the approval posture, any live standing approvals (#192) with their scope and time left, the recent act journal, and the last ``wait_for_state`` result for the target. All journal/wait state is in-memory: a server restart empties it (and voi…

Set the next-boot (or persistent) boot device via BootSourceOverride. CONFIG MUTATION. Gated by the config effect gate + per-invocation approval; denials come back through the same path with a typed ``outcome`` (#234). ``none`` clears the override; ``once=false`` makes it persistent; ``uefi=false`` selects legacy BIOS mode where the target exposes it. A target the BMC doesn't advertise fails fast (call ``boot_options`` first to see ``allowable``).

Capture the current KVM screen (read-only). Returns ``[json_text, image]``: the JSON carries a ``frame_ref`` (``host:generation:hash``) — pass it back to the ``mouse`` tool as ``observed_frame_ref`` so an absolute click can be refused if the host rebooted or swapped media since you looked. It also carries the live ``signal`` state (online/resolution/fps/format, #143) and ``unchanged_since_last_snapshot`` (#141): a byte-identical frame when the screen should have changed means the pixels are stale/cached — do NOT trust them as ground truth; check ``signal`` and ``logs`` instead.

Scan a CIDR for hosts with an open SSH port. RISKY — opt-in. An active network scan: noisy, and only acceptable on networks the user owns or is authorized to probe. Use it ONLY to help find a target whose address the user doesn't know, after they confirm the range — never by default. ``confirm=true`` is required to acknowledge the scan.

Run a command on the managed host's OS over SSH. DESTRUCTIVE / in-band. Gated by its own SSH effect gate (never the HID gate) + per-invocation approval, with typed same-path denials (#234). ``host`` overrides the profile/env ``ssh_host`` at runtime (e.g. a discovered install-time DHCP address).

Is the managed host's OS reachable over SSH? (read-only, in-band). Targets the host *behind* the KVM (its own ``ssh_host`` / `KVM_PILOT_SSH_HOST`), a different machine from the KVM appliance. Use this to prefer remote recovery before asking a user to physically intervene. ``host`` overrides the profile/env ``ssh_host`` at runtime — e.g. an install-time DHCP address the profile can't know until the target boots.

What has actually been exercised on real hardware, per device+firmware+capability (read-only, offline — no device call). Aggregated from the test-run ledger shipped in the package (the same data behind the wiki Hardware-Compatibility page), with each combo's derived maturity level (#98) joined from the shipped firmware registry. This is EVIDENCE, not a guarantee: a capability listed in ``never_exercised`` (or a combo with no row at all) is unverified on that hardware — treat it as mock-only/alpha maturity and confirm destructive steps with the user. ``status`` is "fail" when every recorded li…

Type a string on the managed host's console over the HID keyboard. DESTRUCTIVE. For printable text (commands, installer fields, passwords); nothing echoes back and no Enter is appended — ``press_key('Enter')`` to submit. Keys that aren't text go through ``press_key``; chords through ``send_shortcut``. Keystrokes land wherever the host's focus is: ``snapshot`` first to confirm the screen, and after to see the effect. Needs ``KVM_PILOT_MCP_ALLOW_HID`` + per-invocation approval (elicitation, or ``confirm=true`` under standing policy). Returns the typed act outcome (receipt, or the denial reason)…

Wait (bounded) until the screen reaches a boot/run phase (read-only). Server-side twin of CLI `watch`: polls cheap power/signal/boot-progress gates, then server-side vision, until `phase` (a `classify_screen` token; unknown tokens fail fast with the valid list) is observed. `timeout` is seconds, capped server-side at 300 — chain calls for longer waits. Success returns phase/confidence plus a `frame_ref` to pass to `mouse` as `observed_frame_ref`; a timeout returns `reached=false` with the last observed state (never a hang, never a raised error). With no server-side vision credentials only che…

Send a Wake-on-LAN magic packet to power the host on. POWER (soft). Gated by the power effect gate + per-invocation approval (typed same-path denials, #234). ``mac`` defaults to the profile's ``mac``; ``broadcast`` to its ``wol_broadcast``. No KVM driver is contacted — WoL is a broadcast sent from the server's own host onto the target's L2 segment.