feat(web): add hover command for hover-gated UI (#1783)

Add a first-class `hover <x y|@ref|selector> [--settle]` verb, admitted on
web only, that moves the pointer without pressing via the agent-browser
backend (mouse move). It rides the existing targeted-touch pipeline
(ref/selector/coordinate resolution, occlusion/off-screen guards, settle
observation, response builder, recording) through a new optional
Interactor/backend `hover` op that only the web provider implements.

Touch platforms have no hover state: capabilities advertise it on web
only and iOS/Android/Linux reject it at admission with a --platform web
hint; longpress stays the mobile hold-gesture verb.

Closes #1783

Author: thymikee

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## Unreleased
 
+- New `hover <x y|@ref|selector>` command for `--platform web` (#1783). It moves the pointer over the target without pressing, so hover-gated UI — a message row's `...` toolbar, a menu that opens on pointer enter — becomes reachable through agent-device the way it already was through the underlying `agent-browser` backend (`mouse move`). It is a member of the targeted-touch family: same `@ref`/selector/coordinate targeting, occlusion and off-screen guards, and `--settle` (the settled diff carries the revealed controls with fresh refs, e.g. `+ @e4 [button] "Delete"`), but no `--verify`, since hover reveals rather than activates. `hover @ref` publishes as a portable selector line in recorded scripts, and the Node client exposes `interactions.hover`. Hover is a pointer state that touch platforms do not have, so `capabilities` advertises it on web only and iOS/Android/Linux reject it during admission with `UNSUPPORTED_OPERATION` and a hint naming `--platform web`; `longpress` remains the mobile hold-gesture verb.
 - Internal: session recording is now derived from the script-publication lifecycle instead of being stored beside it. `SessionState.recordSession` is removed; `isRecordingPublication` answers the question from the aggregate (ordinary authoring records only while ARMED, a repair transaction records for its whole lifetime). The stored flag was a second source of truth that handler surfaces set directly, which is how #1533's aborted-recording drift arose — no surface can now arm recording without moving the lifecycle that authorizes it, and the script writer's publication gate is answered entirely by the aggregate. Behavior-preserving: the derivation reproduces what the flag held at every transition.
 - Fixed: a script recording aborted by a second `open` is no longer published by a later bare `close` (#1533). `open <app> --save-script` followed by a second successful `open` terminates the recording and warns "Script publication was aborted…", and `close --save-script` correctly refuses it with "Retry with plain close; it will tear down the session without writing." But when that second `open` itself carried `--save-script`, the flag re-armed recording behind the terminal status, and a bare `close` then wrote the full session log to disk — publishing a recording the caller had been told was aborted, and breaking the promise the refusal makes. An aborted authoring lifecycle is now terminal by construction: `--save-script` arms nothing on any surface that handles it — the re-open builder, the close finalizer, and the recorded-action ingress — and the script writer refuses the lifecycle from every path that reaches it (bare `close`, teardown, idle-reap, active publication). This also stops an aborted session from paying recording-time costs it can never publish: a re-opened aborted recording no longer keeps the direct iOS selector fast paths for `click` and `get` disabled. Armed recordings, published recordings, and every repair transaction are unaffected.
 - `agent-device mcp` now serves the stateless MCP `2026-07-28` revision alongside the handshake-based revisions it already spoke, as the spec's "dual-era server". Modern clients probe `server/discover`, which advertises the supported revisions, the tools capability, and server identity; their requests declare a protocol version in `_meta`, and their results carry `resultType: "complete"` plus `_meta["io.modelcontextprotocol/serverInfo"]`. `tools/list` and `server/discover` now return the `ttlMs`/`cacheScope` cache hints, so a client can cache the 55-tool, ~223KB tool list for an hour instead of re-fetching it on every start; the list was already emitted in a deterministic (sorted) order, which is the other half of what makes it cacheable. Each revision is answered on its own wire contract: a request declaring `2025-11-25` or `2025-06-18` through modern framing still gets the legacy result shape, and `initialize` never agrees to `2026-07-28`, which has no handshake to establish. A declared revision this server does not implement is rejected with `UnsupportedProtocolVersionError` (`-32022`) naming the ones it does, rather than being served under a version the client did not ask for, and modern framing that omits its required `protocolVersion`/`clientCapabilities` metadata — or supplies a `clientInfo` that is not a valid `Implementation` — is rejected as invalid params. `initialize` and `ping` were removed in `2026-07-28`, so a modern-framed call to either is answered `-32601` rather than served inside a `resultType: "complete"` envelope. Responses to legacy clients are unchanged byte-for-byte — `initialize` and `ping` are still served, and no cache, `resultType`, or `_meta` field is added to their results. Nothing here affects the CLI, Node, or daemon surfaces: the stdio transport, the tool set, and every tool's input/output schema are untouched.

packages/ad-script/src/internal/script-utils.ts

@@ -44,8 +44,10 @@ export function isClickLikeCommand(command: string): command is 'click' | 'press
   return command === 'click' || command === 'press';
 }
 
-export function isTouchTargetCommand(command: string): command is 'click' | 'press' | 'longpress' {
-  return isClickLikeCommand(command) || command === 'longpress';
+export function isTouchTargetCommand(
+  command: string,
+): command is 'click' | 'press' | 'longpress' | 'hover' {
+  return isClickLikeCommand(command) || command === 'longpress' || command === 'hover';
 }
 
 function isTypingCommand(command: string): command is 'type' | 'fill' {

packages/ad-script/src/internal/script.ts

@@ -463,10 +463,11 @@ function parseReplayScriptLine(line: string): SessionAction | null {
     return action;
   }
 
-  // wait @ref [timeout] and longpress @ref [durationMs] flow through this
-  // generic branch: strip recorded generation pins like the branches above.
+  // wait @ref [timeout], longpress @ref [durationMs], and hover @ref flow
+  // through this generic branch: strip recorded generation pins like the
+  // branches above.
   action.positionals =
-    command === 'wait' || command === 'longpress'
+    command === 'wait' || command === 'longpress' || command === 'hover'
       ? args.map((token) => stripRecordedRefGeneration(token))
       : args;
   return action;

packages/contracts/src/client-gesture.ts

@@ -64,6 +64,11 @@ export type LongPressOptions = DeviceCommandBaseOptions &
     durationMs?: number;
   };
 
+export type HoverOptions = DeviceCommandBaseOptions &
+  SelectorSnapshotCommandOptions &
+  InteractionTarget &
+  SettleCommandOptions;
+
 export type SwipeOptions = DeviceCommandBaseOptions & {
   from: { x: number; y: number };
   to: { x: number; y: number };

packages/contracts/src/facades/client.ts

@@ -47,6 +47,7 @@ export type {
   FillOptions,
   FlingOptions,
   FocusOptions,
+  HoverOptions,
   LongPressOptions,
   PanOptions,
   PinchOptions,

packages/contracts/src/facades/interaction.ts

@@ -85,6 +85,8 @@ export type {
   FillCommandResponseData,
   FillCommandResult,
   FindCommandResponseData,
+  HoverCommandResponseData,
+  HoverCommandResult,
   InteractionEvidence,
   InteractionTarget,
   LongPressCommandResponseData,

packages/contracts/src/interaction-guarantees.ts

@@ -199,7 +199,7 @@ const RUNTIME_TREE_SHARED_GUARANTEES = {
 export const INTERACTION_DISPATCH_PATHS: Record<InteractionPathId, InteractionPathContract> = {
   'runtime-selector': {
     description: 'Daemon tree capture, selector chain resolution, guarded coordinate tap.',
-    commands: ['press', 'click', 'fill', 'longpress'],
+    commands: ['press', 'click', 'fill', 'longpress', 'hover'],
     guarantees: {
       ...RUNTIME_TREE_SHARED_GUARANTEES,
       disambiguation: {
@@ -221,7 +221,7 @@ export const INTERACTION_DISPATCH_PATHS: Record<InteractionPathId, InteractionPa
   'runtime-ref': {
     description:
       'Session snapshot ref lookup, guarded coordinate tap. #1654: when the caller already resolved the node (a mutating `find`), the lookup is replaced by that node and every guarantee below is enforced against it — the guards are unchanged, only the lookup is skipped.',
-    commands: ['press', 'click', 'fill', 'longpress'],
+    commands: ['press', 'click', 'fill', 'longpress', 'hover'],
     guarantees: {
       ...RUNTIME_TREE_SHARED_GUARANTEES,
       disambiguation: {
@@ -428,7 +428,7 @@ export const INTERACTION_DISPATCH_PATHS: Record<InteractionPathId, InteractionPa
   },
   coordinate: {
     description: 'Raw x/y tap. Semantics are intentionally minimal.',
-    commands: ['press', 'click', 'fill', 'longpress'],
+    commands: ['press', 'click', 'fill', 'longpress', 'hover'],
     guarantees: {
       disambiguation: {
         kind: 'inapplicable',

packages/contracts/src/interaction.ts

@@ -371,6 +371,15 @@ export type LongPressCommandResponseData =
   | (TouchResponseRef & TouchLongPressExtras)
   | (TouchResponseSelector & TouchLongPressExtras);
 
+type TouchHoverExtras = {
+  gesture: 'hover';
+};
+
+export type HoverCommandResponseData =
+  | (TouchResponsePoint & TouchHoverExtras)
+  | (TouchResponseRef & TouchHoverExtras)
+  | (TouchResponseSelector & TouchHoverExtras);
+
 /**
  * Internal runtime result for press/click. The daemon response layer turns
  * this into `PressCommandResponseData` via `buildInteractionResponseData`.
@@ -408,6 +417,17 @@ export type LongPressCommandResult = ResolvedInteractionTarget & {
   settle?: SettleObservation;
 };
 
+/**
+ * Internal runtime result for hover. The daemon response layer turns this
+ * into `HoverCommandResponseData` via `buildInteractionResponseData`.
+ */
+export type HoverCommandResult = ResolvedInteractionTarget & {
+  backendResult?: Record<string, unknown>;
+  message?: string;
+  warning?: string;
+  settle?: SettleObservation;
+};
+
 /**
  * Daemon response data for the `find` command. Read-only actions (`exists`,
  * `wait`, `get_text`, `get_attrs`) may issue a pinnable ref with

packages/contracts/src/interactor-types.ts

@@ -195,6 +195,12 @@ export type Interactor = {
   tapElementSelector?(selector: ElementSelectorTapOptions): Promise<Record<string, unknown> | void>;
   doubleTap(x: number, y: number): Promise<Record<string, unknown> | void>;
   longPress(x: number, y: number, durationMs?: number): Promise<Record<string, unknown> | void>;
+  /**
+   * Move the pointer to a point without pressing. Only pointer-driven
+   * platforms (web today) implement it; touch platforms have no hover state
+   * and leave it undefined, which the `hover` command reports as unsupported.
+   */
+  hover?(x: number, y: number): Promise<Record<string, unknown> | void>;
   focus(x: number, y: number): Promise<Record<string, unknown> | void>;
   type(text: string, delayMs?: number): Promise<TypeTextBackendResult | void>;
   fillElementSelector?(

skills/agent-device/SKILL.md

@@ -13,7 +13,7 @@ agent-device open <app> --foreground
 
 That starts the session and returns the initial interactive snapshot with `@refs`.
 
-Loop: act with `press|click|fill|longpress <target> ... --settle`, `scroll <direction> --settle`, or `back --settle`; continue from the printed diff, verify the named expectation (`wait text "..."`, `is`, `get`, or `find`), then run `agent-device close`.
+Loop: act with `press|click|fill|longpress <target> ... --settle`, `hover <target> --settle` (web only, reveals hover-gated UI), `scroll <direction> --settle`, or `back --settle`; continue from the printed diff, verify the named expectation (`wait text "..."`, `is`, `get`, or `find`), then run `agent-device close`.
 
 Copy refs byte-for-byte: `@e12`, `@e12~s4` — keep the `@` and any `~sN`. Prefer current refs, then `id`/`label`/`role` selectors; coordinates are a last resort. If snapshot reports sparse/AX-unavailable, its refs and selectors are invalid: run `agent-device screenshot`, inspect the image, use coordinates, then retry `snapshot -i` after navigating. Otherwise run `snapshot -i` only when the diff lacks the next target.