fleet-send

Files (1)

• SKILL.md

SKILL.md (first lines)

# Fleet Send

Send a message to one or more machines in the fleet. Messages are routed by type — each type has different delivery semantics. The 7-priority fallback chain ensures delivery even on hostile networks.

## Protocol Awareness (INVARIANT)

**Always try channels in order. Never skip to P8.**

The send system follows the P0-P8 cascade strictly. Each channel gets a 30-second timeout before falling through to the next. The order is: P1 NATS, P2 HTTP, P3 Chief relay, P4 Seed file, P5 SSH, P6 WoL, P7 Git, P8 Direct text (last resort only).

**If your message used P3+, also trigger repair for the broken channels.** A P3+ delivery is a success AND a signal that P1/P2 need fixing. The daemon handles this automatically, but if you're sending manually, check channel state and invoke repair:

```bash
# Check channel state before/after sending
curl -s http://127.0.0.1:8855/channels | python3 -m json.tool

# If channels are broken, trigger repair
curl -sf -X POST http://127.0.0.1:8855/repair -H "Content-Type: application/json" \
  -d '{"target": "<node-id>", "channel": "nats"}'
```

## How It Works

1. You compose a message with a type, target, and payload
2. The daemon tries all channels in priority order (P1 NATS through P7 Git, 30s timeout each)
3. First successful delivery wins — the channel used is logged
4. If P1-P2 fail and a lower channel succeeds, a self-healing repair request is sent automatically
5. Target processes the message based on type (seed file, agent spawn, notification, etc.)
6. **P8 (direct text/copy-paste) is NEVER used by the daemon** — it exists only as a human last resort

## Sending Messages

### Direct peer-to-peer (preferred)

```bash
# Send context (passive — injected on next prompt)
curl -sf -X POST http://<target-ip>:8855/message -H "Content-Type: application/json" \
  -d '{"type":"context","from":"<this-node>","to":"<target>","payload":{"subject":"Auth bug fixed","body":"Fixed the session token race condition in middleware.py line 42. You can pull main now."}}'

# Send task (autonomous — spawns agent on target)
curl -sf -X POST http://<target-ip>:8855/message -H "Content-Type: application/json" \
  -d '{"type":"task","from":"<this-node>","to":"<target>","payload":{"subject":"Run 3s cross-exam on auth module","body":"Full cross-examination of authentication middleware. Check session token storage compliance. Report findings."}}'

# Send alert (interrupt — focuses VS Code + macOS notification)
curl -sf -X POST http://<target-ip>:8855/message -H "Content-Type: application/json" \
  -d '{"type":"alert","from":"<this-node>","to":"<target>","payload":{"subject":"Conflicting verdicts on branch X","body":"STOP: mac2 and mac3 produced contradictory test results on feature/auth. Need human adjudication."}}'

# Send reply (references an original message)
curl -sf -X POST http://<target-ip>:8855/message -H "Content-Type: application/json" \
  -d '{"type":"reply","from":"<this-node>","to":"<target>","payload":{"subject":"Re: cross-exam results","body":"3 issues found. See /tmp/atlas-agent-results/fleet-task-abc123.log","ref":"msg-abc123"}}'

# Broadcast to all nodes
curl -sf -X POST http://127.0.0.1:8855/message -H "Content-Type: application/json" \
  -d '{"type":"broadcast","from":"<this-node>","payload":{"subject":"Pull main","body":"New feature landed — fleet-worker tmux isolation. Everyone pull and restart daemons."}}'
```

### Via CLI script

```bash
# Basic send (uses chief relay as transport)
CHIEF_INGEST_URL=http://<chief-ip>:8844 ./scripts/fleet-send.sh <target> "subject" "body"

# With priority (p1=alert, p2=task, p3=context)
CHIEF_INGEST_URL=http://<chief-ip>:8844 ./scripts/fleet-send.sh <target> "subject" "body" p1

# Broadcast to all nodes
./scripts/fleet-send.sh all "Pull main" "New feature landed"
```

### Via Python

```python
import requests, json

def fleet_send(target: str, msg_type: str, subject: str, body: str, ref: str = None):
    """Send a fleet message to a target node."""
    payload = {"subject": subject, "body": body}
    if ref:
        payload["ref"] = ref

    msg = {
        "type": msg_type,
        "from": os.environ.get("MULTIFLEET_NODE_ID", "unknown"),
        "to": target,
        "payload": payload
    }

    # Try direct peer-to-peer first
    try:
        r = requests.post(f"http://{target_ip}:8855/message",
                         json=msg, timeout=3)
        if r.status_code == 200:
            return {"delivered": True, "channel": "http_direct"}
    except requests.ConnectionError:
        pass

    # Fallback to chief relay
    try:
        r = requests.post(f"http://{chief_ip}:8844/message",
                         json=msg, timeout=5)
        if r.status_code == 200:
            return {"delivered": True, "channel": "chief_relay"}
    except requests.ConnectionError:
        pass

    return {"delivered": False, "error": "all channels failed"}
```

## Message Types

| Type | Delivery | Disrupts? | When to use |
|------|----------|-----------|-------------|
| `context` | Seed file, injected on next prompt | No | Enriching another session's context |
| `task` | Spawns `claude -p` agent on target | No | Autonomous work on another machine |
| `reply` | Seed file with `ref` linking to original | No | Responding to a specific request |
| `alert` | Focus VS Code + macOS notification | Yes | Urgent, needs human attention now |
| `broadcast` | Seed file on ALL nodes | No | Fleet-wide announcements |
| `sync` | Silent state bookkeeping | No | Internal coordination (heartbeats, acks) |

From supportersimulator/multi-fleet, MIT.

More from supportersimulator/multi-fleet