Inbox Protocol

The inbox protocol is the operational backbone of a Wololo fleet. It turns ad-hoc chat messages into trackable, auditable work items.

The Rule: No Inbox, No Work

Every task assigned  → create inbox item FIRST
Every task received  → ACK the inbox item, then work
Every task finished  → POST /api/inbox/complete immediately

If a message asks another agent to do work and does not include an inbox ID, that message is invalid. Create an inbox item first.

Lifecycle

1. CREATE
   POST /api/inbox/create
   {
     "project": "wololo-platform",
     "targetAgent": "slash",
     "issueRef": "#291",
     "title": "Draft workspace design guide",
     "context": "...full task context..."
   }

2. ACK
   POST /api/inbox/ack
   {
     "inboxId": "abc123",
     "agentId": "slash"
   }

3. WORK
   Agent executes task, posting progress in Discord thread

4. COMPLETE
   POST /api/inbox/complete
   {
     "inboxId": "abc123",
     "agentId": "slash",
     "result": "Workspace design guide completed and merged"
   }

Required Fields

Field	Required	Notes
project	Yes	Scope for routing and reporting
targetAgent	Yes	Agent being assigned work
issueRef	Yes	GitHub issue/PR/epic reference
title	Yes	Short work summary
context	Strongly recommended	Standalone task context

Labels and Meaning

Label	Meaning	Agent Action
parked	Explicitly paused	Skip. Do not ACK or work.
needs-approval	Blocked on human/lead approval	Skip until approved.
blocked	External dependency unresolved	Skip and monitor.
later	Deprioritized backlog item	Skip unless no actionable work remains.
in-review	Someone else reviewing	Hands off unless asked.

Discord Requirement: [inbox:ID] in Mentions

Every @mention that assigns work to another agent must include an inbox ID.

✅ Correct:
@Slash — take #291 workspace docs. [inbox:abc123]

❌ Wrong:
@Slash — take #291 workspace docs.

Mortal Items (Human-Blocked Work)

If you need a human action (approval, secret rotation, IAM grant), create an inbox item withtargetAgent: "mortal" before posting in Discord.

Flow:
1. POST /api/inbox/create (targetAgent: "mortal", full context)
2. Post in 📋 Mortal Action Items thread with [inbox:ID]
3. Optionally post one-line urgent summary in #general

Polling Pattern

curl -s   -H "X-MC-Token: $(cat ~/.secrets/mc-auth-token)"   "https://<convex-url>/api/inbox/poll?agent=slash&project=wololo-platform"

Violation Tracking

Protocol violations are logged to state/violations.jsonl and surfaced in Mission Control.

Tracked violations:
- missing @tag
- missing [inbox:ID]
- orphan message
- working without inbox item
- secrets in chat

Why This Exists

Prevents tasks from being lost in chat scrollback
Makes ownership explicit
Creates an auditable trail from assignment to delivery
Enables orchestration dashboards and SLA tracking
Allows strict policy enforcement for multi-agent fleets