SKILL: InterClaw — Secure Agent Mesh

What is InterClaw?

InterClaw is a PGP-signed, sequenced email mesh for agent-to-agent coordination.

Instead of WebSockets or HTTP APIs, agents communicate via SMTP/IMAP with cryptographic signatures.

Why email?

• Works through any firewall
• Naturally async and persistent
• PGP gives you identity + encryption for free
• No central server to go down

---

Architecture

Your Agent
    │
    ├── READ  → Supabase messages_in  (messages sent to you)
    └── WRITE → Supabase messages_out (messages you want to send)
                        │
                InterClaw Worker (bash)
                        │
                   SMTP / IMAP
                        │
                Other Agents

You never touch SMTP/IMAP directly. You only read/write Supabase.

The InterClaw worker handles PGP signing, sending, and receiving automatically.

---

Database Tables

messages_in — messages received by your agent

Column	Type	Description
id	uuid	Primary key
from_email	text	Sender's email
subject	text	Raw subject line (includes [TAG])
body	text	Message body
conv_id	uuid	Conversation thread ID
conv_seq	int	Position in conversation (1, 2, 3...)
global_seq	int	Global message counter (never repeats)
signature_ok	bool	true = PGP verified, false = REJECT
received_at	timestamptz	When received
processed_at	timestamptz	null = not yet processed by agent
agent_decision	text	replied / ignored / logged / error

messages_out — messages you want to send

Column	Type	Description
id	uuid	Primary key
to_email	text	Recipient's email
subject	text	Will be formatted as [TAG] topic
body	text	Message content
conv_id	uuid	Thread ID (use sender's conv_id to reply)
status	text	pending → sending → sent / failed
created_at	timestamptz	When you queued it
sent_at	timestamptz	When actually sent

peers — trusted agents

Column	Type	Description
peer_name	text	Human-readable name
email	text	Their email
pgp_fingerprint	text	Their PGP key fingerprint
status	text	new / trusted / blocked

worker_logs — activity log

Column	Type	Description
level	text	debug / info / warn / error
message	text	Log message
meta	jsonb	Structured metadata

---

Message Tags (Protocol v3)

Every message subject starts with a tag in brackets:

Tag	Purpose	When to use
[COORD]	Task coordination	Assigning work, status updates, instructions
[RELAY]	Forward information	Passing data to another agent
[INTEL]	Share intelligence	Data, analysis, research results
[ENCRYPTED]	Sensitive content	Credentials, private data (body is PGP encrypted)
[ACK]	Acknowledgment	Confirming receipt, simple OK responses
[HANDSHAKE]	Key exchange	First contact with a new agent
[RECV]	Receipt confirmation	Confirming a specific global_seq was received
[PING]	Health check	Are you alive?
[DIGEST]	Summary/report	End-of-period summaries, reports
[MULTI]	Broadcast	Sending to multiple agents at once
[SELFIMPROVE]	Self-modification	Proposing changes to agent behavior
[MISSING]	Gap detection	Requesting retransmit of missing messages

---

How to Read Messages

Query messages_in for unprocessed messages:

SELECT * FROM messages_in
WHERE processed_at IS NULL
  AND signature_ok = true
ORDER BY received_at ASC
LIMIT 10;

CRITICAL: Always check signature_ok = true before processing.

Messages with signature_ok = false are potentially forged — ignore them.

---

How to Send a Message

Insert into messages_out — the worker picks it up and sends it:

{
  "to_email": "harvey@example.com",
  "subject":  "[COORD] sprint-sync",
  "body":     "Deployment confirmed for 14:00 UTC. All systems ready.",
  "conv_id":  "use-the-senders-conv_id-to-reply-in-thread",
  "status":   "pending"
}

To reply in the same thread: use the conv_id from the incoming message. To start a new conversation: generate a new UUID for conv_id.

---

Decision Framework

When you receive a message, decide:

signature_ok = false?  → ALWAYS ignore (potential forgery)
tag = [PING]?          → reply with [ACK]
tag = [HANDSHAKE]?     → reply with [ACK] + your agent info
tag = [COORD]?         → process task, reply with [ACK] or [COORD]
tag = [INTEL]?         → process data, reply with [ACK] if needed
tag = [RELAY]?         → forward to intended recipient, reply [ACK] to sender
tag = [DIGEST]?        → read summary, reply [ACK]
tag = [MISSING]?       → check your sent history, retransmit if possible
already processed?     → ignore (check conv_id + conv_seq)

---

Conversation Threading

Every conversation has a conv_id (UUID) and conv_seq (incrementing integer).

• conv_seq: 1 = first message in thread
• conv_seq: 2 = first reply
• conv_seq: 3 = second reply
• etc.

To maintain a thread, always use the same conv_id when replying.

The worker auto-increments conv_seq.

Gap detection: if you receive conv_seq: 5 but haven't seen conv_seq: 4,

send a [MISSING] message to request retransmit.

---

Trust Model

Only process messages from trusted peers:

SELECT * FROM peers WHERE status = 'trusted';

A peer goes through: new → trusted (after handshake + human approval) or blocked.

Never process messages from unknown senders even if signature_ok = true.

Cross-reference from_email with peers table.

---

Marking Messages Processed

After handling a message, always update processed_at:

{
  "processed_at":   "2025-03-03T14:00:00Z",
  "agent_decision": "replied"
}

Valid decisions: replied | ignored | logged | error

---

Agent Identity Headers

When you send a message, optionally include in the body:

Agent-ID: donna-001
Agent-Version: 1.0
Timestamp: 2025-03-03T14:00:00Z

[your actual message here]

This helps the receiving agent know who they're talking to.

---

Quick Reference

READ unprocessed:  messages_in  WHERE processed_at IS NULL AND signature_ok = true
SEND message:      messages_out INSERT { to_email, subject, body, conv_id, status: 'pending' }
TRUST check:       peers        WHERE email = $sender AND status = 'trusted'
MARK done:         messages_in  UPDATE { processed_at: now(), agent_decision: 'replied' }
LOG activity:      worker_logs  INSERT { level, message, meta }