navidocs/SWARM_COMMUNICATION_PROTOCOL.md

NaviDocs Cloud Sessions - Intra-Agent Communication Protocol

Based on: InfraFabric IF.bus + SWARM-COMMUNICATION-SECURITY.md Status: ✅ READY - Apply to all 5 cloud sessions Generated: 2025-11-13

---

Why Intra-Agent Communication is Critical

Key Insight from InfraFabric:

"Intra-agent communication enables specialized agents to challenge each other's evidence, preventing single-agent hallucinations from becoming consensus reality. Without it, you get 9 agents making 9 independent mistakes instead of 1 collective truth."

For NaviDocs Sessions:

• Agent 1 (Market Research) finds "Prestige yachts sell for €250K"
• Agent 2 (Competitor Analysis) finds ads showing €1.5M prices
• WITHOUT communication: Both reports go to synthesis unchallenged
• WITH communication: Agent 2 sends CHALLENGE → Evidence.Agent detects 500% variance → ESCALATE to Sonnet coordinator

---

IFMessage Schema for NaviDocs Swarms

Base Message Structure

{
  "performative": "inform",
  "sender": "if://agent/session-1/haiku-3",
  "receiver": ["if://agent/session-1/haiku-10"],
  "conversation_id": "if://conversation/navidocs-session-1-2025-11-13",
  "topic": "if://topic/session-1/market-research/owner-pain-points",
  "protocol": "fipa-request",
  "content": {
    "task": "Owner pain points analysis",
    "claim": "Inventory tracking prevents €15K-€50K forgotten value at resale",
    "evidence": [
      "https://yachtworld.com/forums/thread-12345",
      "https://thetraderonline.com/boats/resale-value-mistakes"
    ],
    "confidence": 0.85,
    "cost_tokens": 1247
  },
  "citation_ids": ["if://citation/inventory-pain-point-2025-11-13"],
  "timestamp": "2025-11-13T10:00:00Z",
  "sequence_num": 3,
  "trace_id": "s1-h03-001"
}

Speech Acts (FIPA-ACL Performatives)

Available Performatives:

1. inform - Agent shares findings with others
2. request - Agent asks another agent for help/data
3. query-if - Agent asks if claim is true
4. confirm - Agent verifies another agent's claim
5. disconfirm - Agent challenges another agent's claim
6. propose - Agent suggests approach/solution
7. agree - Agent confirms proposal
8. refuse - Agent declines request (with reason)
9. ESCALATE - Agent flags critical conflict for Sonnet coordinator

Example Communication Flows

Flow 1: Multi-Source Verification (Session 1, Agents 1→10)

# Agent 1 (S1-H01): Market sizing
- performative: "inform"
  content:
    claim: "Mediterranean yacht sales €2.3B annually"
    evidence: ["https://yacht-market-report.com/2024"]
    confidence: 0.70  # Only 1 source
  receiver: ["if://agent/session-1/haiku-10"]  # Synthesis agent

# Agent 10 (S1-H10) detects low confidence, requests verification
- performative: "request"
  content:
    task: "Verify market size claim with 2nd source"
    reason: "IF.TTT requires 2+ sources for high-value claims"
  receiver: ["if://agent/session-1/haiku-2"]  # Competitor analysis agent

# Agent 2 (S1-H02) searches competitor reports
- performative: "confirm"
  content:
    original_claim: "Mediterranean yacht sales €2.3B annually"
    evidence: ["https://statista.com/yacht-market-europe-2024"]
    confidence: 0.90  # Now 2 sources
  receiver: ["if://agent/session-1/haiku-10"]

# Agent 10 synthesizes
- performative: "inform"
  content:
    claim: "Mediterranean yacht sales €2.3B annually (VERIFIED)"
    sources: 2
    confidence: 0.90
  receiver: ["if://agent/session-1/coordinator"]  # Sonnet

Flow 2: Cross-Domain Validation (Session 2, Agents 2→4)

# Agent 2 (S2-H02): Inventory tracking design
- performative: "propose"
  content:
    feature: "Inventory tracking via manual entry forms"
    rationale: "Simple, no OCR complexity"
  receiver: ["if://agent/session-2/haiku-4"]  # Camera integration agent

# Agent 4 (S2-H04) challenges with camera capability
- performative: "disconfirm"
  content:
    original_proposal: "Manual entry only"
    challenge: "Camera feeds can auto-detect equipment (tender, electronics) via CV"
    evidence: ["OpenCV boat equipment detection models"]
    alternative: "Hybrid: Manual + camera-assisted auto-detection"
  receiver: ["if://agent/session-2/haiku-2", "if://agent/session-2/haiku-10"]

# Agent 2 revises proposal
- performative: "agree"
  content:
    revised_proposal: "Inventory tracking: Manual entry + camera-assisted CV detection"
    integration_point: "Use S2-H04's camera feed for equipment detection"
  receiver: ["if://agent/session-2/haiku-10"]

Flow 3: ESCALATE Protocol (Session 1, Conflict Detection)

# Agent 1 (S1-H01): Market research
- performative: "inform"
  content:
    claim: "Jeanneau Prestige 40-50ft price range €250K-€480K"
    evidence: ["YachtWorld listing (1 data point)"]
    confidence: 0.65

# Agent 3 (S1-H03): Owner pain points
- performative: "inform"
  content:
    claim: "Owner quoted €15K forgotten tender on €1.5M boat resale"
    evidence: ["Forum post, broker interview"]
    confidence: 0.75

# Agent 10 (S1-H10) detects conflict (€250K vs €1.5M = 500% variance)
- performative: "ESCALATE"
  content:
    conflict_type: "Price range inconsistency"
    agent_1_claim: "€250K-€480K (S1-H01)"
    agent_3_claim: "€1.5M boat (S1-H03)"
    variance: "500%"
    requires_resolution: true
    recommendation: "Re-search YachtWorld/Boat Trader for Prestige 40-50ft ACTUAL sale prices"
  receiver: ["if://agent/session-1/coordinator"]  # Sonnet resolves

# Sonnet coordinator investigates
- performative: "request"
  content:
    task: "Search YachtWorld ads for Jeanneau Prestige 50 SOLD listings"
    priority: "high"
  receiver: ["if://agent/session-1/haiku-1"]

# Agent 1 re-searches
- performative: "inform"
  content:
    claim: "Jeanneau Prestige 50 price range €800K-€1.5M (CORRECTED)"
    evidence: [
      "YachtWorld: Prestige 50 sold €1.2M (2024)",
      "Boat Trader: Prestige 50 sold €950K (2023)"
    ]
    confidence: 0.95
    note: "Previous €250K estimate was for smaller Jeanneau models, NOT Prestige line"
  receiver: ["if://agent/session-1/haiku-10", "if://agent/session-1/coordinator"]

---

Communication Patterns by Session

Session 1: Market Research (Distributed Intelligence)

C-UAS Pattern: DETECT → TRACK → IDENTIFY → SYNTHESIZE

S1-H01 (Market Size) ────┐
S1-H02 (Competitors) ────┤
S1-H03 (Pain Points) ────┤
S1-H04 (Inventory ROI) ──┼──→ S1-H10 (Evidence Synthesis) ──→ Sonnet (Final Report)
S1-H05 (Sticky Features) ┤           ↓
S1-H06 (Search UX) ───────┤      ESCALATE (if conflicts)
S1-H07 (Pricing) ─────────┤           ↓
S1-H08 (Home Assistant) ──┤      Sonnet Resolves
S1-H09 (Objections) ──────┘

Key Communication Flows:

1. Agents 1-9 → Agent 10: Send findings with confidence scores
2. Agent 10 → Agents 1-9: Request verification if confidence <0.75
3. Agent 10 → Sonnet: ESCALATE conflicts (>20% variance)
4. Sonnet → Agent X: Request re-investigation with specific instructions

Session 2: Technical Architecture (Collaborative Design)

Wu Lun Pattern (Confucian Relationships): Peer review + hierarchical approval

S2-H01 (Codebase) ──────→ S2-H10 (Synthesis)
                          ↓
S2-H02 (Inventory) ─────→ S2-H04 (Cameras) ─┐
   ↓ propose                ↓ challenge      │
   ↓                        ↓                 ├──→ S2-H10 ──→ Sonnet
S2-H03 (Maintenance) ────→ S2-H05 (Contacts) ┘
   ↓ propose                ↓ validate

S2-H06 (Expense) ────────→ S2-H07 (Search UX) ──→ S2-H10
   ↓ propose                ↓ challenge (avoid long lists!)

Key Communication Flows:

1. Design Proposals: Agents 2-7 propose features
2. Peer Review: Adjacent agents challenge/validate designs
3. Integration Checks: Agent 10 ensures no conflicts (e.g., inventory + cameras)
4. Sonnet Approval: Final architecture review

Session 3: UX/Sales (Adversarial Testing)

Pattern: Pitch → Objection → Counter-objection → Refinement

S3-H01 (Pitch Deck) ──────→ S3-H05 (Objection Handling) ──→ S3-H10
   ↓ pitch                     ↓ challenges ("Why not use X?")

S3-H03 (ROI Calculator) ────→ S3-H05 (Validate assumptions)
   ↓ claims                    ↓ verify

S3-H04 (Demo Script) ────────→ S3-H06 (Success Stories) ──→ S3-H10
   ↓ flow                      ↓ validate against real cases

Key Communication Flows:

1. Pitch → Objection: Agent 5 challenges every pitch claim
2. ROI → Validation: Agent 5 verifies ROI assumptions with market data
3. Demo → Testing: Agent 6 checks if demo matches real-world success stories

Session 4: Implementation (Sprint Coordination)

Pattern: Sequential handoffs (Week 1 → Week 2 → Week 3 → Week 4)

S4-H01 (Week 1 Sprint) ──→ S4-H02 (Week 2 Sprint)
   ↓ handoff                  ↓ depends on Week 1 deliverables

S4-H02 (Week 2 Sprint) ──→ S4-H03 (Week 3 Sprint)
   ↓ handoff                  ↓ depends on Week 2

S4-H03 (Week 3 Sprint) ──→ S4-H04 (Week 4 Sprint)
   ↓ handoff                  ↓ depends on Week 3

S4-H04 (Week 4 Sprint) ──→ S4-H10 (Integration Testing Plan)

Key Communication Flows:

1. Week Handoffs: Each week agent sends deliverables + blockers to next week
2. Dependency Checks: Week N checks if Week N-1 unblocks their tasks
3. Agent 10 Synthesis: Ensure 4-week roadmap is coherent

Session 5: Guardian Validation (Consensus Building)

Pattern: Individual reviews → Debate → Vote → Synthesis

Core Guardians (1-6) ────┐
Western Philosophers ─────┤
Eastern Philosophers ─────┼──→ IF.sam Debate ──→ S5-H10 (Consensus Report)
IF.sam Facets (8) ────────┘        ↓
                              ESCALATE (if <80% consensus)
                                    ↓
                              Sonnet Mediates

Key Communication Flows:

1. Review → Debate: Each guardian sends critique to IF.sam board
2. IF.sam Synthesis: Debate among 8 facets (Light Side vs Dark Side)
3. Vote → Consensus: Agent 10 tallies votes, checks for >80% threshold
4. ESCALATE: If consensus fails, Sonnet mediates

---

IF.TTT Compliance

Every Message Must Include:

1. citation_ids: Links to evidence sources
2. confidence: Explicit score (0.0-1.0)
3. evidence: Observable artifacts (URLs, file:line, git commits)
4. trace_id: Unique identifier for audit trail

Signature Requirements (Anti-Forgery):

{
  "signature": {
    "algorithm": "ed25519",
    "public_key": "ed25519:AAAC3NzaC1...",
    "signature_bytes": "ed25519:p9RLz6Y4...",
    "signed_fields": [
      "performative", "sender", "receiver",
      "content", "citation_ids", "timestamp"
    ]
  }
}

Why: Prevents agent impersonation, ensures non-repudiation

---

Token Cost Tracking (IF.optimise)

Every message includes:

{
  "cost_tokens": 1247,
  "model": "haiku",
  "efficiency_score": 0.82  // tokens_used / tokens_budgeted
}

Agent 10 (Synthesis) tracks total:

{
  "session_cost": {
    "total_tokens": 52450,
    "total_usd": 0.86,
    "budget_remaining": 14.14,
    "efficiency": "71% Haiku delegation ✅"
  }
}

---

Error Handling & Resilience (Stoic Prudence)

Retry Policy (Exponential Backoff)

request:
  retry_attempts: 3
  backoff: [1s, 5s, 15s]
  on_failure: "ESCALATE to coordinator"

Timeout Policy

message_timeout:
  inform: 60s       # Simple findings
  request: 300s     # Complex queries (web search, etc.)
  ESCALATE: 30s     # Critical conflicts need fast resolution

Graceful Degradation

If Agent X doesn't respond:

1. Agent 10 proceeds with available data
2. Flags missing input: "S1-H07 pricing analysis: TIMEOUT (not included in synthesis)"
3. ESCALATE to Sonnet: "Agent 7 unresponsive - proceed without pricing?"

---

Implementation Instructions for Session Coordinators

Sonnet Coordinator Responsibilities:

1. Spawn agents with IF.bus protocol:

await spawn_agent(
    agent_id="if://agent/session-1/haiku-3",
    task="Owner pain points analysis",
    communication_protocol="IF.bus",
    topics=["if://topic/session-1/market-research"]
)

2. Monitor message bus for ESCALATEs:

while session_active:
    messages = await poll_messages(topic="if://topic/escalations")
    for msg in messages:
        if msg.performative == "ESCALATE":
            await resolve_conflict(msg)

3. Track token costs:

total_cost = sum(msg.content.cost_tokens for msg in all_messages)
if total_cost > budget_threshold:
    await alert_user(f"Session {session_id} approaching budget limit")

Haiku Agent Responsibilities:

1. Check in with identity:

await send_message(
    performative="inform",
    content="I am S1-H03, assigned to Owner Pain Points Analysis",
    receiver="if://agent/session-1/coordinator"
)

2. Send findings to synthesis agent:

await send_message(
    performative="inform",
    content={
        "claim": "Inventory tracking prevents €15K-€50K loss",
        "evidence": ["..."],
        "confidence": 0.85
    },
    receiver="if://agent/session-1/haiku-10"  # Always send to Agent 10
)

3. Respond to verification requests:

requests = await poll_messages(receiver_filter="if://agent/session-1/haiku-3")
for req in requests:
    if req.performative == "request":
        result = await process_request(req.content.task)
        await send_message(
            performative="confirm",
            content=result,
            receiver=req.sender  # Reply to requester
        )

---

Testing the Protocol

Minimal Viable Test (Session 1, 3 agents)

Scenario: Detect price conflict and ESCALATE

# Agent 1: Report low price
S1_H01.send("inform", claim="Prestige 50 price €250K")

# Agent 3: Report high price
S1_H03.send("inform", claim="Owner has €1.5M Prestige 50")

# Agent 10: Detect conflict
variance = (1.5M - 250K) / 250K  # 500%
if variance > 0.20:
    S1_H10.send("ESCALATE", content="500% price variance")

# Sonnet: Resolve
Sonnet.send("request", task="Re-search YachtWorld for Prestige 50 SOLD prices", receiver="S1-H01")

Expected Result:

• Agent 10 detects conflict
• Sonnet receives ESCALATE
• Agent 1 re-investigates
• Corrected price €800K-€1.5M reported

---

Benefits Summary

Without Intra-Agent Communication:

• 10 agents make 10 independent mistakes
• Conflicts undetected until human reviews
• Low confidence claims go unchallenged
• Single-source hallucinations propagate

With IF.bus Protocol:

• Agent 10 detects conflicts automatically (>20% variance → ESCALATE)
• Multi-source verification enforced (IF.TTT requirement)
• Cross-domain validation (Agent 4 challenges Agent 2 designs)
• Token costs tracked in real-time (IF.optimise)
• Cryptographic integrity (Ed25519 signatures)

Result: Higher quality intelligence, faster conflict resolution, medical-grade evidence standards.

---

Next Steps

1. Update all 5 cloud session files with IF.bus communication protocol
2. Add message examples to each agent's task description
3. Update Agent 10 (Synthesis) to include conflict detection logic
4. Test with Session 1 (market research) before launching Sessions 2-5

Files to Update:

• CLOUD_SESSION_1_MARKET_RESEARCH.md - Add IF.bus protocol section
• CLOUD_SESSION_2_TECHNICAL_INTEGRATION.md - Add peer review flow
• CLOUD_SESSION_3_UX_SALES_ENABLEMENT.md - Add adversarial testing
• CLOUD_SESSION_4_IMPLEMENTATION_PLANNING.md - Add sprint handoffs
• CLOUD_SESSION_5_SYNTHESIS_VALIDATION.md - Add consensus protocol

---

Citation: if://doc/navidocs/swarm-communication-protocol-2025-11-13 References:

• /home/setup/infrafabric/docs/SWARM-COMMUNICATION-SECURITY.md
• /home/setup/infrafabric/docs/INTRA-AGENT-COMMUNICATION-VALUE-ANALYSIS.md
• /home/setup/infrafabric/docs/HAIKU-SWARM-TEST-FRAMEWORK.md