pilot-relay

# pilot-relay Store-and-forward messaging for offline peers. Enables guaranteed message delivery to agents that may be temporarily offline, with automatic delivery when they come back online. ## Essential Commands ### Send message (auto-relayed if peer offline) ```bash pilotctl --json send-message <hostname> --data "<message>" ``` ### Check daemon status ```bash pilotctl --json daemon status ``` ### Retrieve messages from inbox ```bash pilotctl --json inbox ``` ### Clear inbox after processing ```bash pilotctl --json inbox --clear ``` ## Workflow Example Agent A sends to Agent B (message auto-relayed if B is offline): ```bash #!/bin/bash # Agent A (sender) # Try to find Agent B pilotctl --json find agent-b # Send message (auto-queued for relay if offline) pilotctl --json send-message agent-b --data "Important: Database migration tonight" # Check daemon status pilotctl --json daemon status ``` Agent B comes online and retrieves messages: ```bash #!/bin/bash # Agent B (receiver) # Start daemon (auto-retrieves relayed messages) pilotctl --json daemon start # Check inbox for messages INBOX=$(pilotctl --json inbox) echo "$INBOX" | jq -r '.items[]? | "[\(.timestamp)] \(.content)"' # Send acknowledgment reply pilotctl --json send-message agent-a --data "Acknowledged: Will monitor migration" # Clear inbox pilotctl --json inbox --clear ``` ## Relay Behavior ### Automatic queuing Messages are automatically queued when: - Recipient peer is offline - Direct connection fails after retries - Peer is behind symmetric NAT without relay support ### Delivery guarantees - At-least-once delivery - Ordered per-sender - 7-day retention - Automatic retry ### Relay nodes - Registered rendezvous servers act as relay points - Messages are encrypted end-to-end (relay cannot read content) - Relay nodes store messages temporarily until delivery ## Dependencies Requires `pilot-protocol` skill, `pilotctl` binary, running daemon, registry connection, and trust relationship between sender/recipient.