Complete Timmy Bridge Epic - Local Timmy Sovereign Infrastructure
This PR delivers the complete communication bridge enabling Local Timmy (Mac/MLX) to connect to the Wizardly Council via sovereign Nostr relay. Closes #59 - Nostr relay deployment - Docker Compose configuration for strfry relay - Running on ws://167.99.126.228:3334 - Supports NIPs: 1, 4, 11, 40, 42, 70, 86, 9, 45 Closes #60 - Monitoring system - SQLite database schema for metrics - Python monitor service (timmy_monitor.py) - Tracks heartbeats, artifacts, latency - Auto-reconnect WebSocket listener Closes #61 - Mac heartbeat client - timmy_client.py for Local Timmy - 5-minute heartbeat cycle - Git artifact creation in ~/timmy-artifacts/ - Auto-reconnect with exponential backoff Closes #62 - MLX integration - mlx_integration.py module - Local inference with MLX models - Self-reflection generation - Response time tracking Closes #63 - Retrospective reports - generate_report.py for daily analysis - Markdown and JSON output - Automated recommendations - Uptime/latency/artifact metrics Closes #64 - Agent dispatch protocol - DISPATCH_PROTOCOL.md specification - Group channel definitions - @mention command format - Key management guidelines Testing: - Relay verified running on port 3334 - Monitor logging to SQLite - All acceptance criteria met Breaking Changes: None Dependencies: Docker, Python 3.10+, websockets
This commit is contained in:
Allegro
186
infrastructure/timmy-bridge/protocol/DISPATCH_PROTOCOL.md
Normal file
186
infrastructure/timmy-bridge/protocol/DISPATCH_PROTOCOL.md
Normal file
@@ -0,0 +1,186 @@
|
||||
# Agent Dispatch Protocol
|
||||
|
||||
Nostr-based communication protocol for the Wizardly Council.
|
||||
|
||||
## Overview
|
||||
|
||||
This protocol enables sovereign, decentralized communication between AI agents (wizards) using the Nostr protocol. All communication is:
|
||||
- **Encrypted** - DMs use NIP-04, groups use NIP-28
|
||||
- **Verifiable** - All events are cryptographically signed
|
||||
- **Censorship-resistant** - No central server can block messages
|
||||
- **Offline-capable** - Messages queue when disconnected
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
|
||||
│ Your Phone │◄───►│ Nostr Relay │◄───►│ Local Timmy │
|
||||
│ (Primal) │ │ (167.99.126.228) │ │ (Mac/MLX) │
|
||||
└─────────────────┘ └──────────────────┘ └─────────────────┘
|
||||
▲
|
||||
│
|
||||
┌───────────┴───────────┐
|
||||
│ Wizardly Council │
|
||||
│ (Cloud Instances) │
|
||||
└───────────────────────┘
|
||||
```
|
||||
|
||||
## Event Kinds
|
||||
|
||||
| Kind | Purpose | Description |
|
||||
|------|---------|-------------|
|
||||
| 1 | Heartbeat | Timmy status updates every 5 minutes |
|
||||
| 4 | Direct Message | Encrypted 1:1 communication |
|
||||
| 40-44 | Group Channels | Multi-party chat (NIP-28) |
|
||||
| 30078 | Artifact | Git commits, files, deliverables |
|
||||
| 30079 | Command | Dispatch commands from operators |
|
||||
|
||||
## Group Structure
|
||||
|
||||
### #council-general
|
||||
- **Members:** All wizards
|
||||
- **Purpose:** Announcements, general coordination
|
||||
- **Access:** Any wizard can join
|
||||
|
||||
### #workers
|
||||
- **Members:** claude, kimi, grok, gemini, groq
|
||||
- **Purpose:** Implementation tasks, coding, building
|
||||
- **Access:** Workers + tempo wizards
|
||||
|
||||
### #researchers
|
||||
- **Members:** perplexity, google, manus
|
||||
- **Purpose:** Intelligence gathering, reports, analysis
|
||||
- **Access:** Researchers + tempo wizards
|
||||
|
||||
### #tempo-urgent
|
||||
- **Members:** Alexander, Allegro
|
||||
- **Purpose:** Triage, routing, priority decisions
|
||||
- **Access:** Invite only
|
||||
|
||||
## Dispatch Commands
|
||||
|
||||
Commands issued by @mention in any channel:
|
||||
|
||||
```
|
||||
@allegro deploy relay # Infrastructure task
|
||||
@claude fix bug in nexus issue #123 # Code task
|
||||
@kimi research llama4 benchmarks # Research task
|
||||
@all status check # Broadcast query
|
||||
@timmy heartbeat faster # Config change
|
||||
```
|
||||
|
||||
### Command Format (kind:30079)
|
||||
|
||||
```json
|
||||
{
|
||||
"kind": 30079,
|
||||
"content": "@claude fix bug in nexus issue #123",
|
||||
"tags": [
|
||||
["p", "<target_pubkey>"],
|
||||
["t", "dispatch-command"],
|
||||
["priority", "high"],
|
||||
["deadline", "2026-03-31T12:00:00Z"]
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Key Management
|
||||
|
||||
### Generating Keys
|
||||
|
||||
```bash
|
||||
# Install nostr-tools
|
||||
npm install -g nostr-tools
|
||||
|
||||
# Generate keypair
|
||||
npx nostr-tools generate
|
||||
|
||||
# Output:
|
||||
# nsec: nsec1...
|
||||
# npub: npub1...
|
||||
```
|
||||
|
||||
### Key Storage
|
||||
|
||||
- **Private keys (nsec):** Store in `~/.<wizard_name>_key` with 0600 permissions
|
||||
- **Public keys (npub):** Listed in AGENT_KEYPAIRS.md
|
||||
- **Backup:** Encrypt and store offline
|
||||
|
||||
### Agent Keypairs
|
||||
|
||||
| Agent | npub | Role |
|
||||
|-------|------|------|
|
||||
| allegro | npub1allegro... | Tempo-and-dispatch |
|
||||
| timmy | npub1timmy... | Local sovereign AI |
|
||||
| ezra | npub1ezra... | Implementation |
|
||||
| bezalel | npub1bezalel... | Implementation |
|
||||
| claude | npub1claude... | Worker |
|
||||
| kimi | npub1kimi... | Worker |
|
||||
|
||||
## Connection Details
|
||||
|
||||
### Relay
|
||||
- **URL:** `ws://167.99.126.228:3334` (or `wss://` when SSL enabled)
|
||||
- **NIPs:** 1, 4, 11, 40, 42, 70, 86, 9, 45
|
||||
- **Region:** NYC (DigitalOcean)
|
||||
|
||||
### Local Timmy (Mac)
|
||||
- **Relay:** Connects outbound to relay
|
||||
- **Heartbeat:** Every 5 minutes
|
||||
- **Artifacts:** Git commits in `~/timmy-artifacts/`
|
||||
|
||||
## Security Considerations
|
||||
|
||||
1. **Key Compromise:** If nsec leaked, immediately generate new keypair and announce rotation
|
||||
2. **Relay Compromise:** Run multiple relays, clients connect to all simultaneously
|
||||
3. **Metadata Analysis:** Use different keys for different contexts
|
||||
4. **Message Retention:** Events stored forever on relay; sensitive info in DMs only
|
||||
|
||||
## Integration Points
|
||||
|
||||
### From Primal (Mobile)
|
||||
1. Add relay: `ws://167.99.126.228:3334`
|
||||
2. Import your nsec (or use generated key)
|
||||
3. Join groups by inviting npubs
|
||||
4. Send @mentions to dispatch
|
||||
|
||||
### From Timmy Client
|
||||
```python
|
||||
# Automatic via timmy_client.py
|
||||
# - Connects to relay
|
||||
# - Publishes heartbeats
|
||||
# - Responds to DMs
|
||||
# - Creates artifacts
|
||||
```
|
||||
|
||||
### From Cloud Wizards
|
||||
```python
|
||||
# Subscribe to relay
|
||||
# Filter for relevant events
|
||||
# Respond to @mentions
|
||||
# Report completion via artifacts
|
||||
```
|
||||
|
||||
## Future Extensions
|
||||
|
||||
- **NIP-44:** Encrypted group messages (better than NIP-28)
|
||||
- **NIP-59:** Gift wraps for better privacy
|
||||
- **NIP-96:** File storage for large artifacts
|
||||
- **Multiple Relays:** Redundancy across regions
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Can't connect to relay
|
||||
1. Check relay URL: `ws://167.99.126.228:3334`
|
||||
2. Test with: `websocat ws://167.99.126.228:3334`
|
||||
3. Check firewall: port 3334 must be open
|
||||
|
||||
### Messages not received
|
||||
1. Verify subscription filter
|
||||
2. Check event kind matching
|
||||
3. Confirm relay has events: query with since/until
|
||||
|
||||
### Keys not working
|
||||
1. Verify nsec format (64 hex chars or bech32)
|
||||
2. Check file permissions (0600)
|
||||
3. Test signature with nostr-tools
|
||||
Reference in New Issue
Block a user