Feature request: discover and prompt agents across saved machines #3980

Feature request

Allow an agent or CLI command running on one Herdr machine to discover, inspect, address, and prompt agents managed by another saved SSH machine.

Current behavior

Herdr 0.9.0 lets a person manage Local and saved SSH machines from one client. The UI can switch to a remote machine, display its agents, and route interactive pane input to it.

Automation running inside a pane remains scoped to that pane's inherited Herdr session and socket, however. Selecting a remote machine in the UI does not retarget CLI commands, and workspace, pane, and agent identifiers are only unique within one server.

The primary missing capability is discovery: an agent or script on machine A cannot query Herdr on A for the agents available on saved machine B, including their stable target identity, status, session/workspace/pane, or whether they can currently accept a prompt. Without machine-qualified discovery, A cannot safely decide which B agent to invoke. It also cannot directly use herdr agent prompt to send a message to an agent on saved machine B.

The current workaround is to arrange separate SSH execution explicitly, for example:

ssh device-b 'herdr agent prompt reviewer "Please review the latest change"'

That makes every caller reproduce Herdr's machine resolution, SSH configuration, remote session selection, quoting, authentication, connection handling, and error reporting.

Desired behavior

Provide a supported, machine-qualified way for automation on one machine to discover and inspect agents on another connected/saved machine, then address one of the returned agents. The exact interface is open to maintainer direction. Illustrative shapes could be:

herdr agent list --machine <profile-id> --json
herdr agent status --machine <profile-id> [<agent>]
herdr agent prompt --machine <profile-id> <agent> <text>

or corresponding Socket API methods that return machine-qualified agent records and accept a target containing both the machine profile and the remote agent identity.

This would enable an orchestrating agent on machine A to delegate work to or request a response from an agent on machine B without requiring every integration to build its own SSH wrapper.

Expected semantics

• Machine identity should be explicit; selecting a machine in an unrelated UI client should not silently change automation targets.
• Prefer the stable machine profile ID over a display label or hostname.
• Let A enumerate B's agents and read, at minimum, each agent's machine-qualified identity, name/type, current status, session/workspace/pane location, and freshness/connectivity state.
• Discovery results should distinguish live remote state from cached state retained while B is disconnected; cached records must not authorize a prompt.
• The identifier returned by discovery should be directly usable as the target of status, wait, and prompt operations without the caller reconstructing it from display fields.
• Resolve agent/workspace/pane identifiers within the selected remote server, since those identifiers can collide across machines.
• Target the saved machine's configured remote session, including --remote-session profiles.
• Return a clear error when the machine is disconnected, requires interactive SSH authentication, the remote agent no longer exists, or the remote server lacks the required capability.
• Preserve the existing local-only behavior when no machine qualifier is supplied.
• Reuse Herdr's existing connection and trust boundaries where possible; do not expose a remote Herdr socket directly.

Why this is different from the 0.9.0 multi-machine UI

The 0.9.0 UI solves human navigation and interactive input across machines, and visually aggregates agent information. This request is for that remote agent information to be available programmatically to an agent/automation on A, with a safe path from discovery to agent-to-agent invocation across the same machine boundary.

Related context:

• feat: manage multiple ssh machines from one client #3670 added Local and saved SSH machines in one client.
• feat: support independent multi-client tab views #3526 added independent multi-client views.
• Feature request: fleet view — aggregate agent status across multiple remote servers #3493 discussed aggregating agent status across remote servers, but not cross-machine agent invocation.
• Remote sessions don't appear in agents section #1170 concerns detecting agents launched inside an ordinary SSH pane, rather than prompting an agent managed by another Herdr server.