protocol

Intercom Protocol & Framing Specification #

This document details the low-level wire protocol, framing mechanics, sticky project identity model, mailbox persistence, and leader election state machine for the Intercom inter-session communication mesh.

1. Message Envelope Specification #

All communications across the Intercom mesh use JSON Lines (NDJSON) framing. Every message exchanged over Unix Domain Sockets or persisted to disk conforms to the standard envelope schema:

{
  "id": "msg_a1b2c3d4e5f6",
  "type": "chat",
  "from_session": "nyota-uhura",
  "to_session": "seven-of-nine",
  "channel": "collab",
  "reply_to": null,
  "payload": {
    "text": "Unit test suite completed with 0 failures.",
    "diff": "--- a/auth.go\n+++ b/auth.go\n@@ -10,2 +10,2 @@"
  },
  "timestamp": "2026-08-26T15:30:00.000000+00:00"
}

Envelope Fields #

2. Transport Framing & Socket Lifecycle #

Socket Endpoint #

Each channel maintains an isolated Unix Domain Socket located at:

${AGY_IPC_DIR:-/tmp/agy-ipc}/<channel_name>/hub.sock

Connection Flow & Collision Avoidance #

sequenceDiagram
    autonumber
    participant ClientA as Session A (Client)
    participant Hub as Intercom Hub Daemon
    participant ClientB as Session B (Client)

    ClientA->>Hub: Connect to hub.sock
    ClientA->>Hub: {"type":"register","from_session":"nyota-uhura",...}\n
    Note over Hub: Verify nyota-uhura is not actively open on another socket
    Hub-->>ClientA: {"type":"welcome","to_session":"nyota-uhura","payload":{"peers":[...]}}\n
    
    ClientA->>Hub: {"type":"chat","from_session":"nyota-uhura","to_session":"seven-of-nine",...}\n
    Hub->>ClientB: Forward envelope to active socket\n
    Hub->>ClientB: Append envelope to inbox_seven-of-nine.ndjson

1. Connection Establishment: Client opens a stream connection to hub.sock.
2. Registration & Collision Check: Client transmits a register or announce envelope. If another active socket is already connected under the same session_id, the Hub rejects the duplicate connection with an error envelope (SESSION_COLLISION).
3. Welcome Ack: Hub responds with a welcome envelope enumerating active peers and updates peers.json.
4. Message Routing:
   • Direct Message: Delivered immediately to the target client socket if connected; spooled into inbox_<to_session>.ndjson.
   • Broadcast: Delivered to all currently connected active client sockets (except sender) and spooled into their respective inbox files. Broadcasts never route to dead historical inboxes.

3. Persistent Mailbox Spooling & Offset Tracking #

To guarantee zero message loss when a subagent is busy executing long-running tool calls, Intercom maintains persistent disk spools:

Filesystem Layout #

/tmp/agy-ipc/<channel>/
├── hub.sock                  # Active Unix Domain Socket (mode 0700)
├── hub.lock                  # Kernel advisory flock file for leader election
├── peers.json                # Live registry of connected session IDs
├── inbox_nyota-uhura.ndjson  # Append-only message log for Session A
├── offset_nyota-uhura.json   # Read pointer byte offset for Session A
├── inbox_seven-of-nine.ndjson
└── offset_seven-of-nine.json

Advisory Locking (fcntl.flock) #

• Write Operations: Hub and clients acquire fcntl.LOCK_EX before appending to inbox_<session>.ndjson.
• Read Operations: Polling/listening clients acquire fcntl.LOCK_SH while reading lines from the last known byte offset.
• Offset Persistence: Upon reading new messages, the client records {"offset": <bytes_read>, "updated_at": <epoch_timestamp>} in offset_<session>.json.
• Fresh Session Reset (--fresh): When initializing a new session or running listen --fresh, reset_inbox() or seek_to_end() clears the backlog so old conversations never contaminate the context of a restarted agent.

4. Leader Election & Daemon Auto-Spawning #

Intercom operates completely serverless without requiring a pre-existing background service:

1. Socket Probe: When any command (send, poll, listen, init) runs, ensure_daemon_running() attempts a zero-byte probe connection to hub.sock.
2. Auto-Spawn: If the socket is missing or refused, the process forks a background daemon via subprocess.Popen(..., start_new_session=True).
3. Kernel Mutex (hub.lock): The daemon attempts to acquire an exclusive non-blocking lock (fcntl.LOCK_EX | fcntl.LOCK_NB) on hub.lock.
   • Leader: First process acquires the lock, unlinks any stale socket, and binds hub.sock.
   • Follower: Concurrent processes fail to acquire the lock and exit cleanly (sys.exit(0)), falling back to client mode.
4. Stale Recovery: If the host crashes without unlinking hub.sock, subsequent client probes detect ConnectionRefusedError, unlink the dead socket, and safely elect a new Hub leader.