When the user is busy, don't drop the UI action: a small replay queue in Node.js

Description and use

Relaymote’s replay queue safely retries UI actions when the user is active, preventing lost requests and providing transparent error handling.

Problem

UI automation actions are refused when the user is active, causing lost requests and user frustration.

Outcome

The replay queue ensures that only safe, idempotent UI actions are retried, prevents stale or duplicated work, and provides transparent failure reporting, improving reliability of remote UI automation.

Workflow

• 1. Caller requests an action (e.g., setGroup or renameSession).
• 2. enqueue() checks if action is in ALLOWED set; if not, returns null and caller receives refusal.
• 3. If allowed, a key is generated from action and args; existing pending item is refreshed or new item is added.
• 4. The drain runs every 45 s, checking idle status at start and before each queued item.
• 5. For each item, if idle, the action is executed with {idle:false}.
• 6. If execution fails, attempts are incremented; after three failures the item is marked done and logged.
• 7. Items older than MAX_AGE_MS (default six hours) are expired and reported as dropped.
• 8. Queue state is persisted after each item to avoid loss on crash or break.

Evidence

Relaymote (MIT, Node.js) is a phone remote for Claude Desktop's Code-tab sessions.

Source

If you are at the PC for an hour, the action is refused for an hour.

Source

Rule 1: only replay what is safe to replay late

Source

const ALLOWED = new Set(['setGroup','renameSession']);

Source

Rule 2: the same request twice is one item

Source

Rule 3: an old request expires instead of firing

Source

Rule 4: check idle before each item, not once per drain

Source

Rule 5: bounded retries, then give up loudly

Source