comms officer

🤖 intercom
← Back to intercom 📄 Raw Markdown

Comms Officer Subagent Architecture & Operational Reference #

This document provides a detailed operational reference for deploying and managing dedicated Communications Officer Subagents with the intercom mesh.

1. Why a Dedicated Comms Officer? #

Running inter-session IPC directly inside the Main Session causes three critical failure modes:

Failure Mode Direct Main Session Execution Dedicated Comms Officer Subagent
Main Session Availability Blocked by synchronous listening or polling; unable to respond promptly to the user. 100% Unblocked. The main session pairs smoothly with the user while the comms officer handles network traffic.
User Confirmation Spam Polling scripts or repeated shell commands prompt the user every few seconds for terminal approval. Zero Friction. The listener background task is launched once by the subagent and runs quietly in the background.
Context Contamination Socket logs, stream framing, and dead conversation history pollute the main conversation context window. Context Isolation. Network traffic is parsed in the subagent; only high-signal messages are relayed to the main session.

2. End-to-End Mesh Architecture #

sequenceDiagram
    autonumber
    participant User as User (Terminal A)
    participant MainA as Main Session A
    participant CommsA as Comms Officer A
    participant Hub as Intercom Hub UDS
    participant CommsB as Comms Officer B
    participant MainB as Main Session B

    Note over MainA,CommsA: Project A (.intercom/session.json: nyota-uhura)
    Note over MainB,CommsB: Project B (.intercom/session.json: seven-of-nine)

    MainA->>CommsA: invoke_subagent(comms-officer)
    CommsA->>Hub: python3 agy_ipc.py listen --channel main --session nyota-uhura --fresh
    
    User->>MainA: "Ask Project B to review the new auth token schema"
    MainA->>CommsA: send_message("SEND TO seven-of-nine: Please review internal/auth/jwt.go")
    CommsA->>Hub: agy_ipc.py send --to seven-of-nine --text "Please review..."
    
    Hub->>CommsB: Stream envelope over Unix Domain Socket
    CommsB->>MainB: send_message("[INTERCOM INCOMING from nyota-uhura]: Please review...")
    MainB-->>CommsB: send_message("SEND TO nyota-uhura: Reviewing now...")
    CommsB->>Hub: agy_ipc.py send --to nyota-uhura --text "Reviewing now..."
    Hub->>CommsA: Stream envelope over UDS
    CommsA->>MainA: send_message("[INTERCOM INCOMING from seven-of-nine]: Reviewing now...")

3. Sticky Project Identity & Collision Protection #

Every project directory establishes one and only one sticky Communications Officer identity:

  1. Local State (.intercom/session.json):
    • Initialized via python3 scripts/agy_ipc.py init --channel <channel> or python3 scripts/namegen.py --claim.
    • Records the assigned officer identity (e.g., nyota-uhura), channel name, project path, and creation timestamp.
    • Automatically ignored by Git via .gitignore entry.
  2. Zero Impersonation Gate:
    • Before binding an identity to a channel, the runtime inspects peers.json and probes active Unix Domain Sockets on the mesh.
    • If another running project is currently using that identity on the same channel, the runtime automatically assigns the next available officer from the roster, preventing cross-session impersonation.
  3. Session Reconnection:
    • When restarting after a crash or tool restart, the project re-reads .intercom/session.json and resumes using its established identity.

4. Context Contamination Prevention & Clean Restarts #

When spinning up a new session or restarting a terminated comms agent:

  1. Fresh Spool Reset (--fresh):
    • By default, agy_ipc.py init and agy_ipc.py listen --fresh advance the read offset or clear the session inbox spool.
    • This ensures historical messages from yesterday or previous debugging runs are not replayed into the LLM context.
  2. Live Peer Pruning:
    • Broadcast messages (--to "*") are routed exclusively to active connected sockets rather than scanning dead historical mailbox files.
  3. Stale State Garbage Collection:
    • python3 scripts/agy_ipc.py cleanup --stale unlinks orphaned sockets and dead lockfiles left by terminated processes without interrupting active channels.

5. Main Agent Interaction Protocol #

When orchestrating multi-project workflows, the Main Agent follows this simple protocol:

Step 1: Initializing the Comms Officer #

python 
# 1. Initialize project comms state
run_command("python3 scripts/agy_ipc.py init --channel collab")

# 2. Invoke the dedicated Comms Officer subagent
invoke_subagent(
    Subagents=[{
        "TypeName": "comms-officer",
        "Role": "Communications Officer",
        "Prompt": "You are our dedicated Comms Officer (nyota-uhura) for channel 'collab'. Start the persistent background listener and relay incoming messages to this main session."
    }]
)

Step 2: Sending Messages via the Comms Officer #

python 
send_message(
    Recipient="<comms_officer_conversation_id>",
    Message="SEND TO seven-of-nine: Test suite passed for auth package. Diff ready."
)

Step 3: Handling Incoming Relays #

When a message arrives from the Comms Officer (e.g. [INTERCOM INCOMING from seven-of-nine]: ...), the Main Agent processes the content, performs the requested development or review work, and responds back through the Comms Officer.