Mailbox Protocol

What is the Mailbox Protocol?

The Mailbox Protocol is CCCC's file-based message exchange system that enables structured communication between AI agents. Unlike real-time API calls, the Mailbox Protocol uses files as message queues, providing:

Persistence: Messages survive session interruptions
Auditability: Full communication history is preserved
Transparency: Humans can inspect all agent exchanges
Flexibility: Works with any CLI-based AI tool

Message Structure

Basic Message Format

Each message in the mailbox follows a typed structure:

{
  "id": "msg_20250115_001",
  "timestamp": "2025-01-15T10:30:00Z",
  "from": "peera",
  "to": "peerb",
  "type": "CLAIM",
  "content": {
    "statement": "Use JWT for authentication",
    "rationale": "Stateless, scalable, industry standard",
    "evidence": ["RFC 7519", "Current architecture patterns"]
  },
  "context": {
    "task_id": "task_auth_001",
    "round": 1
  }
}

Message Types

CCCC uses a structured debate protocol with typed messages:

Type	Purpose	Response Expected
`CLAIM`	Initial proposal	COUNTER or AGREE
`COUNTER`	Challenge with alternative	EVIDENCE or CONCEDE
`EVIDENCE`	Support for position	AGREE or further COUNTER
`AGREE`	Consensus reached	None (end of exchange)
`CONCEDE`	Withdraw position	None (adopts counter)
`QUERY`	Request information	RESPONSE
`RESPONSE`	Answer to query	Varies

The CLAIM/COUNTER/EVIDENCE Pattern

Standard Debate Flow

Round 1:
  PeerA → CLAIM: "Implement feature X using approach A"

Round 2:
  PeerB → COUNTER: "Approach B would be better because..."

Round 3:
  PeerA → EVIDENCE: "Approach A handles edge case Y, see test..."

Round 4:
  PeerB → AGREE: "Convinced. Proceeding with Approach A."

→ Consensus logged to SUBPOR.md
→ Implementation begins

Example Exchange

Task: Implement user authentication

┌─────────────────────────────────────────────────┐
│ PeerA CLAIM                                     │
├─────────────────────────────────────────────────┤
│ Type: CLAIM                                     │
│ Statement: Use session-based authentication    │
│ Rationale:                                      │
│   - Simpler to implement                        │
│   - Built-in CSRF protection                    │
│   - Easy to invalidate                          │
└─────────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────────┐
│ PeerB COUNTER                                   │
├─────────────────────────────────────────────────┤
│ Type: COUNTER                                   │
│ Statement: JWT would be more appropriate        │
│ Rationale:                                      │
│   - Stateless for horizontal scaling            │
│   - Works with mobile clients                   │
│   - Microservices friendly                      │
│ Challenge: How does session scale to 3 servers? │
└─────────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────────┐
│ PeerA EVIDENCE                                  │
├─────────────────────────────────────────────────┤
│ Type: EVIDENCE                                  │
│ Response: Sessions can use Redis for state      │
│ Evidence:                                       │
│   - Redis session store handles 100k+ req/s    │
│   - Used by Twitter, GitHub, Shopify            │
│ Compromise: Redis sessions + JWT for mobile?    │
└─────────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────────┐
│ PeerB AGREE                                     │
├─────────────────────────────────────────────────┤
│ Type: AGREE                                     │
│ Statement: Accept hybrid approach               │
│ Decision: Redis sessions (web) + JWT (mobile)   │
│ Implementation: Start with session, add JWT     │
└─────────────────────────────────────────────────┘

Mailbox File Structure

Directory Layout

.cccc/
└── mailbox/
    ├── peera/
    │   ├── inbox.json       # Messages TO PeerA
    │   ├── outbox.json      # Messages FROM PeerA
    │   └── archive/         # Processed messages
    ├── peerb/
    │   ├── inbox.json
    │   ├── outbox.json
    │   └── archive/
    ├── foreman/
    │   ├── inbox.json
    │   ├── outbox.json
    │   └── directives/      # Standing orders
    └── shared/
        ├── consensus.json   # Agreed decisions
        └── blockers.json    # Unresolved issues

Inbox File Format

{
  "queue": [
    {
      "id": "msg_001",
      "timestamp": "2025-01-15T10:30:00Z",
      "from": "peerb",
      "type": "COUNTER",
      "content": {...},
      "status": "unread"
    }
  ],
  "last_read": "2025-01-15T10:29:00Z"
}

Outbox File Format

{
  "sent": [
    {
      "id": "msg_002",
      "timestamp": "2025-01-15T10:35:00Z",
      "to": "peerb",
      "type": "EVIDENCE",
      "content": {...},
      "delivered": true
    }
  ]
}

Consensus Building

How Consensus is Reached

Proposal Phase: One peer makes a CLAIM
Challenge Phase: Other peer responds (COUNTER or preliminary AGREE)
Evidence Phase: If challenged, provide supporting evidence
Resolution Phase: Reach AGREE or escalate

Consensus Requirements

orchestration:
  consensus_threshold: 0.8   # Agreement level needed
  max_debate_rounds: 5       # Rounds before escalation

Deadlock Handling

When peers can't agree after max_debate_rounds:

1. Foreman is notified (if enabled)
2. Auxiliary agent may be consulted
3. Human notification sent via IM
4. Deadlock logged to .cccc/mailbox/shared/blockers.json

Evidence Requirements

What Counts as Evidence

CCCC agents are expected to provide substantive evidence:

Strong Evidence:

Code examples demonstrating approach
Test results proving hypothesis
Documentation/specs references
Performance benchmarks
Security analysis

Weak Evidence (may be challenged):

Assertions without backing
Popularity arguments alone
"Everyone does it this way"

Evidence in Messages

{
  "type": "EVIDENCE",
  "content": {
    "statement": "JWT refresh tokens prevent session hijacking",
    "evidence": [
      {
        "type": "code",
        "data": "// Refresh token implementation...",
        "source": "auth.ts:45-60"
      },
      {
        "type": "reference",
        "data": "OWASP Session Management Cheat Sheet",
        "url": "https://cheatsheetseries.owasp.org/..."
      },
      {
        "type": "test",
        "data": "tests/auth.test.ts - 'prevents replay attacks'",
        "result": "PASS"
      }
    ]
  }
}

Message Routing

How Messages Flow

Agent writes to outbox
        ↓
Orchestrator picks up message
        ↓
Validates message format
        ↓
Routes to recipient's inbox
        ↓
Recipient processes on next cycle
        ↓
Response flows back

Routing Rules

From	To	Route
PeerA	PeerB	Direct peer-to-peer
PeerB	PeerA	Direct peer-to-peer
Foreman	All Peers	Broadcast directive
Peer	Foreman	Status/escalation report
Any	Auxiliary	On-demand consultation

Special Message Types

Foreman Directives

When Foreman needs to realign peers:

{
  "type": "DIRECTIVE",
  "from": "foreman",
  "to": ["peera", "peerb"],
  "content": {
    "action": "realign",
    "message": "Focus drifting from auth to UI. Refocus on authentication.",
    "reference": "POR.md#current-goals"
  }
}

Escalation Messages

When human intervention is needed:

{
  "type": "ESCALATE",
  "from": "peera",
  "to": "human",
  "content": {
    "reason": "Cannot proceed without API key decision",
    "options": ["Use existing key", "Generate new key", "Skip for now"],
    "deadline": "2025-01-15T12:00:00Z"
  }
}

Configuring Mailbox Behavior

Basic Configuration

mailbox:
  base_dir: .cccc/mailbox
  archive_after: 24h
  max_queue_size: 100

Evidence Requirements

mailbox:
  evidence_required:
    for_claims: optional
    for_counters: required
    minimum_strength: moderate

Round Limits

mailbox:
  max_rounds_per_topic: 5
  escalate_on_deadlock: true
  deadlock_threshold: 3  # Consecutive counters without progress

Debugging Mailbox Issues

View Current Mailbox State

# See all pending messages
cccc mailbox status

# View specific agent's inbox
cccc mailbox show peera --inbox

# Check for deadlocks
cccc mailbox check-health

Common Issues

Messages Not Delivered:

# Check mailbox permissions
ls -la .cccc/mailbox/

# Validate message format
cccc mailbox validate

Agents Talking Past Each Other:

# Review recent exchange
cccc mailbox history --last 10

# Check if on same topic
cat .cccc/mailbox/shared/current_topic.json

Stuck in Loop:

# Check round counter
cccc status --detailed

# Force resolution
cccc mailbox resolve --force-consensus

Inspecting Mailbox for Debugging

Read Raw Messages

# All unprocessed messages
cat .cccc/mailbox/peera/inbox.json | jq .

# Specific message
cat .cccc/mailbox/peera/inbox.json | jq '.queue[0]'

View Consensus History

cat .cccc/mailbox/shared/consensus.json | jq .

Archive Analysis

# Count messages by type
find .cccc/mailbox/*/archive -name "*.json" | \
  xargs cat | jq '.type' | sort | uniq -c

Integration with POR/SUBPOR

Automatic Logging

When consensus is reached, it's automatically logged:

SUBPOR.md Entry:

## Task: Implement Authentication

### Decision: Hybrid Auth Strategy
- **Decided**: 2025-01-15 10:45 UTC
- **Approach**: Redis sessions (web) + JWT (mobile)
- **Consensus**: PeerA/PeerB agreement after 4 rounds
- **Evidence**: See .cccc/mailbox/archive/msg_004.json

### Debate Summary
1. PeerA proposed session-based auth
2. PeerB countered with JWT for scaling
3. PeerA provided Redis evidence
4. Consensus reached on hybrid approach

Best Practices

1. Review Mailbox Regularly

# Quick health check
cccc mailbox status

# Look for patterns
grep -r "COUNTER" .cccc/mailbox/*/archive | wc -l

2. Clear Archives Periodically

# Archive old messages
cccc mailbox archive --older-than 7d

# Compress for storage
cccc mailbox compress-archive

3. Monitor Consensus Rate

High counter/claim ratio may indicate:

Unclear goals
Mismatched agent configurations
Task too ambiguous

4. Use Escalation Appropriately

Configure escalation for critical decisions:

mailbox:
  escalate_topics:
    - security
    - architecture
    - breaking_changes

Next Steps

Learn about Agent Roles for role configuration
Explore Configuration for mailbox settings
Review Usage Guide for practical workflows