hermes - 💡(How to fix) Fix feat: Maintain WebSocket/gateway connection on macOS when display sleeps

Description

On macOS, when the display turns off or the screen locks (lid closed on MacBook, display sleep, or lock screen), the message channel (WebSocket) between the Hermes Agent client and the gateway can disconnect. This causes the agent to go offline and miss messages until the user manually wakes the machine and the connection is re-established.

Expected Behavior

The Hermes Agent gateway connection should remain active and stable on macOS even when:

• The display enters sleep mode (power saving)
• The screen is locked
• The laptop lid is closed (clamshell mode)

The agent should continue to receive and process messages without interruption.

Proposed Solution

Options to consider:

1. Enable Power Management Assertions (macOS) — Use IOKit's IOPMAssertionCreateWithName to prevent system sleep while maintaining network connectivity (similar to how music players and video conferencing apps keep the system awake).

2. Use a keepalive mechanism — Implement a TCP keepalive or WebSocket ping/pong heartbeat that maintains the gateway connection even when the system is in a low-power display-off state.

3. Leverage macOS NoIdleSleep assertion — Similar to how caffeinate works, the agent could hold a power assertion that prevents sleep but allows the display to turn off (saving power while keeping the network stack alive).

4. Auto-reconnection logic — If disconnection is unavoidable, implement automatic reconnection with exponential backoff so the agent comes back online as soon as the machine is accessible.

Additional Context

• macOS has specific power management behavior that differs from Linux/Windows
• The caffeinate command (caffeinate -s) can prevent sleep, but a programmatic solution within the agent would be more robust
• This is particularly important for users who run Hermes Agent as a personal assistant on MacBooks