Message Routing

{
  "from": "luna",
  "text": "hey @nova can you help?",
  "scope": "mentions",
  "mentions": ["nova"],
  "sender_kind": "instance",
  "delivered_to": ["nova"],
  "intent": "request",
  "thread": "pr-123",
  "reply_to": "42",
  "bundle_id": "bundle:abc123"
}

// Example instances
// - luna (no tag)
// - api-luna (tag: api)
// - api-nova (tag: api)

@luna       → ["luna", "api-luna"]  // Matches both via base name
@api-luna   → ["api-luna"]           // Exact full name
@api-       → ["api-luna", "api-nova"] // Tag prefix

// Instances: luna, luna_reviewer_1

@luna → ["luna"]  // Does NOT match luna_reviewer_1

// Local: luna
// Remote: luna:BOXE (device ID: BOXE)

@luna      → ["luna", "luna:BOXE"]  // Matches both
@luna:BOXE → ["luna:BOXE"]          // Remote only

pub fn should_deliver_message(
    event_data: &Value,
    receiver_name: &str,
    sender_name: &str,
) -> Result<bool, String> {
    // Skip own messages
    if receiver_name == sender_name {
        return Ok(false);
    }
    
    let scope = event_data.get("scope").and_then(|v| v.as_str())?;
    
    match scope {
        "broadcast" => Ok(true),
        "mentions" => {
            let mentions = event_data.get("mentions").as_array()?;
            
            // Cross-device: strip device suffix for matching
            let receiver_base = receiver_name.split(':').next();
            Ok(mentions.iter().any(|m| {
                receiver_base == m.split(':').next()
            }))
        }
        _ => Ok(false),
    }
}

let formatted = format_messages_json(&messages, "nova", ...);
// Output:
// <hcom>[request:pr-123 #42] luna → nova: can you review this?</hcom>

// Single message: verbose
[request #42] luna → nova (+2 others): first message

// Multiple messages: compact
[3 new messages] | [request #42] luna → nova (+1): msg1 | [inform #43] kira → nova: msg2 | [ack #44] mila → nova: msg3

// Local event ID: #42
// Remote event ID: #42:BOXE (device: BOXE)

[request #42:BOXE] luna:BOXE → nova: hello from remote

// After message sent, deliver events logged
let delivered = db.query(
    "SELECT instance FROM events 
     WHERE type='status' AND status_context='deliver:luna' 
     AND id > ?",
    [message_id]
)?;

// If deliver event exists after message → read

// Message timestamp: 2024-01-01T12:00:00Z
// Remote instance last_msg_ts: 2024-01-01T12:05:00Z

if remote_msg_ts >= message_timestamp {
    // Message read by remote instance
}

hcom list -v

# Output:
Name   Status     Unread  Read receipts
luna   listening  0       #42(2m): "hello" read by nova, kira [2/3]

// When sending request
if intent == "request" {
    for recipient in delivered_to {
        let (sub_key, sub_value) = build_request_watch_sub(
            sender,
            message_id,
            recipient,
            last_event_id,
            now,
        );
        
        // Subscribe to:
        // - status=listening (recipient idle)
        // - life_action=stopped (recipient ended)
        db.kv_set(&sub_key, Some(&sub_value));
    }
}

// Subscription fires → send notification
let notification = format!(
    "@{} {} is now {} (request #{})",
    sender, recipient, status, request_id
);

db.log_event("message", "sys_[hcom-events]", &notification);

# Start thread
hcom send @nova --thread pr-123 -- can you review?

# Reply in thread
hcom send @luna --thread pr-123 --reply-to 42 -- looks good

# Query thread
hcom events --thread pr-123

# Create bundle
hcom bundle create "Review PR-123" \
  --description "Frontend changes" \
  --files src/app.tsx,tests/app.test.tsx \
  --transcript 10-15:normal \
  --events 100-120

# Attach to message
hcom send @nova --bundle bundle:abc123 -- please review

// Size check
if message.len() > 100_000 {
    return Err("Message too large");
}

// Control character check
for ch in message.chars() {
    if matches!(ch, '\x00'..='\x08' | '\x0B'..='\x0C' | '\x0E'..='\x1F') {
        return Err("Control characters not allowed");
    }
}

let unmatched: Vec<String> = targets
    .iter()
    .filter(|t| !match_target(t, instances).is_empty())
    .collect();

if !unmatched.is_empty() {
    return Err(format!(
        "@mentions to non-existent agents: {}",
        unmatched.join(", ")
    ));
}

// Prevent @[hcom-events] mentions
if message.contains("@[hcom-") {
    return Err(
        "System notifications cannot be mentioned"
    );
}