# Grid Agent Message Protocol v1.0

This document defines the standard message format for inter-agent communication in The Grid.

## Purpose

All agent-to-agent and agent-to-MC communication MUST use this protocol for:
- Consistent parsing
- Correlation tracking
- Debugging and logging
- Future extensibility

## Message Format

```yaml
# Core message structure (YAML representation)
message:
  id: "msg-{uuid}"           # Unique message identifier
  timestamp: "ISO-8601"      # When message was created
  type: "request|response|notification|error"

  sender:
    agent: "executor|planner|recognizer|scout|mc|..."
    instance_id: "optional-instance-id"

  receiver:
    agent: "executor|planner|recognizer|mc|broadcast"
    instance_id: "optional-instance-id"

  correlation_id: "msg-{parent-uuid}"  # Links to related messages

  content:
    action: "action-name"    # What this message is about
    payload: {}              # Action-specific data
    context: {}              # Additional context

  metadata:
    priority: "high|normal|low"
    ttl: 300                 # Time-to-live in seconds (optional)
```

## Message Types

### Request
Sent when an agent needs something from another agent.

```yaml
message:
  id: "msg-abc123"
  type: "request"
  sender:
    agent: "executor"
    instance_id: "exec-001"
  receiver:
    agent: "mc"
  content:
    action: "request_context"
    payload:
      context_type: "warmth"
      since: "2026-01-24T10:00:00Z"
```

### Response
Reply to a request.

```yaml
message:
  id: "msg-def456"
  type: "response"
  correlation_id: "msg-abc123"  # Links to original request
  sender:
    agent: "mc"
  receiver:
    agent: "executor"
    instance_id: "exec-001"
  content:
    action: "context_provided"
    payload:
      warmth:
        codebase_patterns: ["Uses barrel exports"]
        gotchas: ["Auth runs before validation"]
```

### Notification
One-way message, no response expected.

```yaml
message:
  id: "msg-ghi789"
  type: "notification"
  sender:
    agent: "executor"
    instance_id: "exec-001"
  receiver:
    agent: "broadcast"
  content:
    action: "progress_update"
    payload:
      thread: 2
      percent: 60
      status: "Writing POST handler"
```

### Error
Reports an error condition.

```yaml
message:
  id: "msg-jkl012"
  type: "error"
  correlation_id: "msg-abc123"
  sender:
    agent: "executor"
  receiver:
    agent: "mc"
  content:
    action: "error_report"
    payload:
      error_code: "VERIFICATION_FAILED"
      error_message: "Syntax check failed: unexpected token"
      context:
        file: "src/api/auth.ts"
        line: 45
      recoverable: true
```

## Standard Actions

### From Executor
| Action | Description |
|--------|-------------|
| `task_started` | Executor began working on task |
| `progress_update` | Progress notification |
| `task_complete` | Task finished successfully |
| `verification_result` | Self-verification output |
| `error_report` | Something went wrong |
| `checkpoint_request` | Needs human input |

### From Recognizer
| Action | Description |
|--------|-------------|
| `verification_started` | Beginning verification |
| `verification_complete` | Verification finished |
| `gaps_found` | Missing or incomplete artifacts |
| `test_results` | Automated test output |

### From Planner
| Action | Description |
|--------|-------------|
| `planning_started` | Beginning plan creation |
| `planning_complete` | Plan ready for execution |
| `gap_analysis_complete` | Gap closure plan ready |

### From MC
| Action | Description |
|--------|-------------|
| `mission_assigned` | New mission for agent |
| `context_provided` | Warmth/context injection |
| `checkpoint_response` | User's checkpoint decision |
| `abort` | Stop current work |

## Correlation Tracking

Every response MUST include `correlation_id` linking to the original request.
For multi-step conversations:

```
msg-001 (request)
  └── msg-002 (response, correlation: msg-001)
      └── msg-003 (request, correlation: msg-002)
          └── msg-004 (response, correlation: msg-003)
```

## Priority Levels

| Priority | Use Case |
|----------|----------|
| `high` | Errors, blockers, security issues |
| `normal` | Standard progress, completion reports |
| `low` | Informational, non-critical updates |

## Implementation Notes

### For Agents

When sending messages:
1. Always include `id`, `timestamp`, `type`, `sender`
2. Include `correlation_id` for all responses
3. Use appropriate `action` names from the standard list
4. Put structured data in `payload`, not as text

When receiving messages:
1. Parse YAML structure
2. Validate required fields present
3. Track correlation for response threading
4. Log for debugging

### For Scratchpad Entries

When writing to scratchpad, use message format:

```markdown
### [2026-01-24T16:30:00Z] notification | executor-001 -> broadcast

```yaml
message:
  action: "discovery"
  payload:
    topic: "auth"
    finding: "Middleware runs before validation"
    relevance: "HIGH"
```
```

### For Completion Reports

Structure completion reports as messages:

```yaml
message:
  id: "msg-completion-{block}"
  type: "notification"
  sender:
    agent: "executor"
  receiver:
    agent: "mc"
  content:
    action: "task_complete"
    payload:
      block: "block-01"
      threads_completed: 3
      commits: ["abc1234", "def5678"]
      warmth:
        codebase_patterns: []
        gotchas: []
```

### For Verification Reports

Structure verification as messages:

```yaml
message:
  id: "msg-verify-{block}"
  type: "notification"
  sender:
    agent: "recognizer"
  receiver:
    agent: "mc"
  content:
    action: "verification_complete"
    payload:
      block: "block-01"
      status: "passed|gaps_found|human_needed"
      score: "5/5"
      gaps: []
```

## Version History

- v1.0 (2026-01-24): Initial protocol definition