block / block/buzz

Remote clients should show when a Desktop agent host is unreachable

Open
#5,902 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Rust
Stars
32.7k
Forks
4.3k
Avg merge
1d 13h
Merged PRs (30d)
253

Description

## Problem

When every agent hosted by one Buzz Desktop becomes unreachable, a person using another Desktop or mobile client receives no host-level explanation. Messages appear to send normally, but the agents do not answer, so the failure is indistinguishable from slow work or a conversational problem.

This occurred while using a remote client away from the host Mac: shortly after the host entered its screensaver/lock-screen state, all locally hosted agents stopped answering. That incident is consistent with the open macOS display-sleep report in #4159, but the remote client should surface the outage regardless of whether the cause is display suspension, system sleep, power loss, app exit, or network loss.

The existing offline-mention issue #1743 and open PR #2296 address a single explicit mention to an offline agent. They do not tell the user that the common Desktop host for several agents is unreachable.

## Proposed behavior

- Model the Desktop host's reachability separately from each agent's conversational presence and lifecycle state.
- When the host heartbeat expires, show a persistent status on remote Desktop and mobile clients such as `Agent host unreachable — agents on this computer are offline`.
- Include the host's owner-defined name, last-seen time, affected agents, and a concise recovery note.
- Warn before or immediately after sending to an affected agent, while preserving the original message for catch-up or retry.
- Clear the warning automatically when the host reconnects and make the recovered state visible.
- Do not label the cause as lock screen, sleep, power, app exit, or network failure unless Buzz has evidence for that cause.
- Avoid false positives during brief reconnects by using the platform's presence/heartbeat tolerance and an explicit `unknown` or `reconnecting` state where appropriate.

## Acceptance criteria

- A remote Desktop or mobile client shows a host-level unreachable state when the common Desktop host for managed agents misses its heartbeat beyond the defined tolerance.
- The state lists the affected agents and the host's last-seen time.
- Sending or mentioning an affected agent produces a clear warning rather than silent waiting.
- The UI distinguishes host unreachable, individual agent stopped/offline, and unknown/reconnecting.
- Reconnection clears the warning without requiring an app restart.
- The behavior covers display suspension, system sleep, app exit/crash, power loss, and network loss without asserting an unverified cause.
- Host status does not expose private network addresses, device identifiers, credentials, or other sensitive diagnostics to unauthorized community members.

## Related

- #4159 — agents stop responding while the macOS display is asleep
- #1743 — offline agent mentions fail silently
- #2296 — relay notice for explicit mentions to offline bots
- #5396 — proposed agent lifecycle events

Contributor guide

Open the contributing guide

Research direction

Start by reading the related issues #4159, #1743, #2296, and #5396 to understand existing sleep, offline-mention, relay, and lifecycle behavior. Trace the current presence and heartbeat handling across remote Desktop and mobile clients, then verify the acceptance criteria for host state, affected agents, warnings, recovery, and privacy.

Written by the indexing model from the issue text.

Assessment

Tech stack
macos, rust
Domain
desktop-dev, distributed-systems, mobile-dev, networking
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.