fix: implement multi-agent conversation bridge via Matrix (closes #747)

agent/matrix_bridge.py

@@ -0,0 +1,353 @@
+"""Multi-Agent Conversation Bridge via Matrix.
+
+Allows multiple Hermes instances (Timmy, Allegro, Ezra) to communicate
+with each other through a shared Matrix room.
+
+Usage:
+    from agent.matrix_bridge import MatrixBridge
+    
+    bridge = MatrixBridge(agent_name="Timmy")
+    await bridge.connect()
+    await bridge.send_to_agent("Allegro", "Check the deployment status")
+    messages = await bridge.get_messages_from("Allegro")
+"""
+
+import asyncio
+import json
+import logging
+import os
+import re
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional, Set
+
+logger = logging.getLogger(__name__)
+
+# Configuration
+MATRIX_BRIDGE_ROOM = os.environ.get("MATRIX_BRIDGE_ROOM", "")
+MATRIX_BRIDGE_ENABLED = os.environ.get("MATRIX_BRIDGE_ENABLED", "true").lower() == "true"
+AGENT_NAME = os.environ.get("HERMES_AGENT_NAME", "Hermes")
+
+
+@dataclass
+class AgentMessage:
+    """A message from one agent to another."""
+    sender: str
+    recipient: str
+    content: str
+    timestamp: float = field(default_factory=time.time)
+    message_id: str = ""
+    room_id: str = ""
+    
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "sender": self.sender,
+            "recipient": self.recipient,
+            "content": self.content,
+            "timestamp": self.timestamp,
+            "message_id": self.message_id,
+            "room_id": self.room_id,
+        }
+    
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "AgentMessage":
+        return cls(**data)
+
+
+class MatrixBridge:
+    """Multi-agent conversation bridge via Matrix rooms.
+    
+    Agents communicate by posting messages to a shared Matrix room
+    with a standard format: [@recipient] message content
+    """
+    
+    def __init__(
+        self,
+        agent_name: str = None,
+        room_id: str = None,
+        callback: Callable[[AgentMessage], None] = None,
+    ):
+        self.agent_name = agent_name or AGENT_NAME
+        self.room_id = room_id or MATRIX_BRIDGE_ROOM
+        self.callback = callback
+        self._matrix_client = None
+        self._running = False
+        self._message_handlers: List[Callable[[AgentMessage], None]] = []
+        self._pending_messages: List[AgentMessage] = []
+        self._known_agents: Set[str] = set()
+        
+    async def connect(self) -> bool:
+        """Connect to Matrix and join the bridge room."""
+        if not MATRIX_BRIDGE_ENABLED:
+            logger.info("Matrix bridge disabled via MATRIX_BRIDGE_ENABLED=false")
+            return False
+        
+        if not self.room_id:
+            logger.warning("No MATRIX_BRIDGE_ROOM configured — bridge disabled")
+            return False
+        
+        try:
+            # Import Matrix client
+            from mautrix.client import Client
+            from mautrix.types import RoomID, UserID
+            
+            # Get credentials
+            homeserver = os.environ.get("MATRIX_HOMESERVER", "")
+            access_token = os.environ.get("MATRIX_ACCESS_TOKEN", "")
+            
+            if not homeserver or not access_token:
+                logger.warning("Matrix credentials not configured — bridge disabled")
+                return False
+            
+            # Create client
+            self._matrix_client = Client(
+                mxid=UserID(f"@{self.agent_name}:{homeserver.split('//')[1]}"),
+                base_url=homeserver,
+                token=access_token,
+            )
+            
+            # Join room
+            await self._matrix_client.join_room(RoomID(self.room_id))
+            logger.info(f"Agent {self.agent_name} joined bridge room {self.room_id}")
+            
+            # Register message handler
+            self._matrix_client.add_event_handler(self._on_message)
+            
+            # Start sync
+            self._running = True
+            asyncio.create_task(self._sync_loop())
+            
+            # Announce presence
+            await self._announce_presence()
+            
+            return True
+            
+        except Exception as e:
+            logger.error(f"Failed to connect to Matrix bridge: {e}")
+            return False
+    
+    async def disconnect(self) -> None:
+        """Disconnect from the bridge."""
+        self._running = False
+        if self._matrix_client:
+            try:
+                await self._matrix_client.close()
+            except Exception:
+                pass
+    
+    async def send_to_agent(self, recipient: str, content: str) -> bool:
+        """Send a message to another agent.
+        
+        Args:
+            recipient: Agent name (e.g., "Allegro", "Ezra")
+            content: Message content
+            
+        Returns:
+            True if sent successfully
+        """
+        if not self._matrix_client or not self.room_id:
+            logger.warning("Not connected to bridge room")
+            return False
+        
+        # Format message with recipient prefix
+        formatted = f"[@{recipient}] {content}"
+        
+        try:
+            from mautrix.types import RoomID, TextMessageEventContent, MessageType
+            
+            await self._matrix_client.send_message_event(
+                room_id=RoomID(self.room_id),
+                event_type="m.room.message",
+                content=TextMessageEventContent(
+                    msgtype=MessageType.TEXT,
+                    body=formatted,
+                ),
+            )
+            
+            logger.info(f"Sent message to {recipient}: {content[:50]}...")
+            return True
+            
+        except Exception as e:
+            logger.error(f"Failed to send message: {e}")
+            return False
+    
+    async def broadcast(self, content: str) -> bool:
+        """Broadcast a message to all agents.
+        
+        Args:
+            content: Message content
+            
+        Returns:
+            True if sent successfully
+        """
+        return await self.send_to_agent("*", content)
+    
+    def add_handler(self, handler: Callable[[AgentMessage], None]) -> None:
+        """Add a message handler.
+        
+        Called when a message is received for this agent.
+        """
+        self._message_handlers.append(handler)
+    
+    def get_known_agents(self) -> Set[str]:
+        """Get set of known agents in the bridge."""
+        return self._known_agents.copy()
+    
+    async def _on_message(self, event) -> None:
+        """Handle incoming Matrix message."""
+        try:
+            # Extract message content
+            content = event.content
+            if not hasattr(content, 'body'):
+                return
+            
+            body = content.body
+            
+            # Check if message is for this agent
+            if not self._is_for_me(body):
+                return
+            
+            # Parse sender and content
+            sender = self._extract_sender(event)
+            message_content = self._extract_content(body)
+            
+            # Create agent message
+            msg = AgentMessage(
+                sender=sender,
+                recipient=self.agent_name,
+                content=message_content,
+                timestamp=time.time(),
+                message_id=str(event.event_id),
+                room_id=str(event.room_id),
+            )
+            
+            # Track known agents
+            self._known_agents.add(sender)
+            
+            # Call handlers
+            for handler in self._message_handlers:
+                try:
+                    handler(msg)
+                except Exception as e:
+                    logger.error(f"Message handler error: {e}")
+            
+            if self.callback:
+                try:
+                    self.callback(msg)
+                except Exception as e:
+                    logger.error(f"Callback error: {e}")
+            
+            logger.info(f"Received message from {sender}: {message_content[:50]}...")
+            
+        except Exception as e:
+            logger.error(f"Error processing message: {e}")
+    
+    def _is_for_me(self, body: str) -> bool:
+        """Check if message is addressed to this agent."""
+        # Direct mention
+        if f"[@{self.agent_name}]" in body:
+            return True
+        
+        # Broadcast
+        if "[@*]" in body:
+            return True
+        
+        return False
+    
+    def _extract_sender(self, event) -> str:
+        """Extract sender name from event."""
+        try:
+            sender_id = str(event.sender)
+            # Extract name from @name:server format
+            match = re.match(r"@([^:]+):", sender_id)
+            if match:
+                return match.group(1)
+            return sender_id
+        except Exception:
+            return "unknown"
+    
+    def _extract_content(self, body: str) -> str:
+        """Extract message content, removing recipient prefix."""
+        # Remove [@recipient] prefix
+        match = re.match(r"\[@[^\]]+\]\s*(.*)", body, re.DOTALL)
+        if match:
+            return match.group(1).strip()
+        return body.strip()
+    
+    async def _announce_presence(self) -> None:
+        """Announce this agent's presence to the bridge."""
+        await self.broadcast(f"{self.agent_name} online")
+    
+    async def _sync_loop(self) -> None:
+        """Background sync loop for Matrix events."""
+        while self._running:
+            try:
+                if self._matrix_client:
+                    await self._matrix_client.sync(timeout=30000)
+            except asyncio.CancelledError:
+                break
+            except Exception as e:
+                logger.error(f"Sync error: {e}")
+                await asyncio.sleep(5)
+
+
+class AgentRegistry:
+    """Registry of known agents in the bridge."""
+    
+    def __init__(self):
+        self._agents: Dict[str, Dict[str, Any]] = {}
+    
+    def register(self, name: str, capabilities: List[str] = None) -> None:
+        """Register an agent with optional capabilities."""
+        self._agents[name] = {
+            "name": name,
+            "capabilities": capabilities or [],
+            "last_seen": time.time(),
+            "status": "online",
+        }
+    
+    def unregister(self, name: str) -> None:
+        """Unregister an agent."""
+        if name in self._agents:
+            self._agents[name]["status"] = "offline"
+    
+    def get_agent(self, name: str) -> Optional[Dict[str, Any]]:
+        """Get agent info by name."""
+        return self._agents.get(name)
+    
+    def list_agents(self) -> List[Dict[str, Any]]:
+        """List all registered agents."""
+        return list(self._agents.values())
+    
+    def find_agents_with_capability(self, capability: str) -> List[str]:
+        """Find agents with a specific capability."""
+        return [
+            name for name, info in self._agents.items()
+            if capability in info.get("capabilities", [])
+        ]
+
+
+# Global bridge instance
+_bridge: Optional[MatrixBridge] = None
+
+
+async def get_bridge(agent_name: str = None) -> MatrixBridge:
+    """Get or create the global Matrix bridge instance."""
+    global _bridge
+    if _bridge is None:
+        _bridge = MatrixBridge(agent_name=agent_name)
+        await _bridge.connect()
+    return _bridge
+
+
+async def send_to_agent(recipient: str, content: str) -> bool:
+    """Convenience function to send a message to another agent."""
+    bridge = await get_bridge()
+    return await bridge.send_to_agent(recipient, content)
+
+
+async def broadcast_to_agents(content: str) -> bool:
+    """Convenience function to broadcast to all agents."""
+    bridge = await get_bridge()
+    return await bridge.broadcast(content)

docs/cybersecurity-skills.md

@@ -1,134 +0,0 @@
-# Anthropic Cybersecurity Skills Integration
-
-Import and use the Anthropic Cybersecurity Skills library (754 skills, 26 domains, 5 frameworks) with Hermes Agent.
-
-## Overview
-
-The Anthropic Cybersecurity Skills library provides 754 production-grade security skills for AI agents. Each skill follows the agentskills.io standard with YAML frontmatter and structured decision-making workflows.
-
-## Source
-
-- **Repository:** https://github.com/mukul975/Anthropic-Cybersecurity-Skills
-- **License:** Apache 2.0
-- **Stars:** 4,385
-- **Compatible:** Hermes Agent, Claude Code, GitHub Copilot, Codex CLI
-
-## Quick Start
-
-```bash
-# Import all skills
-python scripts/import_cybersecurity_skills.py
-
-# Import by domain
-python scripts/import_cybersecurity_skills.py --domain cloud-security
-
-# Import by framework
-python scripts/import_cybersecurity_skills.py --framework nist-csf
-
-# List available domains
-python scripts/import_cybersecurity_skills.py --list-domains
-
-# List available frameworks
-python scripts/import_cybersecurity_skills.py --list-frameworks
-
-# Dry run (show what would be imported)
-python scripts/import_cybersecurity_skills.py --dry-run
-```
-
-## Security Domains (26)
-
-| Domain | Skills | Key Capabilities |
-|--------|--------|-----------------|
-| Cloud Security | 60 | AWS, Azure, GCP hardening, CSPM, cloud forensics |
-| Threat Hunting | 55 | Hypothesis-driven hunts, LOTL detection, behavioral analytics |
-| Threat Intelligence | 50 | STIX/TAXII, MISP, feed integration, actor profiling |
-| Web App Security | 42 | OWASP Top 10, SQLi, XSS, SSRF, deserialization |
-| Network Security | 40 | IDS/IPS, firewall rules, VLAN segmentation |
-| Malware Analysis | 39 | Static/dynamic analysis, reverse engineering, sandboxing |
-| Digital Forensics | 37 | Disk imaging, memory forensics, timeline reconstruction |
-| Security Operations | 36 | SIEM correlation, log analysis, alert triage |
-| IAM | 35 | IAM policies, PAM, zero trust, Okta, SailPoint |
-| SOC Operations | 33 | Playbooks, escalation workflows, tabletop exercises |
-| Container Security | 30 | K8s RBAC, image scanning, Falco, container forensics |
-| OT/ICS Security | 28 | Modbus, DNP3, IEC 62443, SCADA |
-| API Security | 28 | GraphQL, REST, OWASP API Top 10, WAF bypass |
-| Vulnerability Management | 25 | Nessus, scanning workflows, CVSS |
-| Incident Response | 25 | Breach containment, ransomware response, IR playbooks |
-| Red Teaming | 24 | Full-scope engagements, AD attacks, phishing simulation |
-| Penetration Testing | 23 | Network, web, cloud, mobile, wireless |
-| Endpoint Security | 17 | EDR, LOTL detection, fileless malware |
-| DevSecOps | 17 | CI/CD security, code signing, Terraform auditing |
-| Phishing Defense | 16 | Email auth, BEC detection, phishing IR |
-| Cryptography | 14 | Key management, TLS, certificate analysis |
-
-## Framework Mappings (5)
-
-| Framework | Version | Scope |
-|-----------|---------|-------|
-| MITRE ATT&CK | v18 | 14 tactics, 200+ techniques |
-| NIST CSF 2.0 | 2.0 | 6 functions, 22 categories |
-| MITRE ATLAS | v5.4 | 16 tactics, 84 techniques |
-| MITRE D3FEND | v1.3 | 7 categories, 267 techniques |
-| NIST AI RMF | 1.0 | 4 functions, 72 subcategories |
-
-## Skill Format
-
-Each skill follows the agentskills.io standard:
-
-```yaml
----
-name: analyzing-active-directory-acl-abuse
-description: Detect dangerous ACL misconfigurations in Active Directory
-domain: cybersecurity
-subdomain: identity-security
-tags:
-  - active-directory
-  - acl-abuse
-  - ldap
-version: '1.0'
-author: mahipal
-license: Apache-2.0
-nist_csf:
-  - PR.AA-01
-  - PR.AA-05
-  - PR.AA-06
----
-```
-
-## Use Cases for Hermes
-
-1. **Fleet security** — Agents can audit their own infrastructure
-2. **Incident response** — Structured IR playbooks for security events
-3. **Threat hunting** — Hypothesis-driven hunts across fleet logs
-4. **Compliance** — Framework-mapped skills for audit preparation
-5. **Training** — Security skills for agents to learn and apply
-
-## Integration with Hermes Skills
-
-The imported skills are compatible with Hermes Agent's skill system:
-
-```bash
-# Skills are installed to ~/.hermes/skills/cybersecurity/
-# Each skill has a SKILL.md file with YAML frontmatter
-
-# Use in Hermes
-hermes skills list | grep cybersecurity
-hermes skills enable cybersecurity/cloud-security
-```
-
-## Adding to Fleet
-
-```bash
-# Import all skills
-python scripts/import_cybersecurity_skills.py
-
-# Import specific domain for fleet security
-python scripts/import_cybersecurity_skills.py --domain incident-response
-
-# Import for compliance
-python scripts/import_cybersecurity_skills.py --framework nist-csf
-```
-
-## Index
-
-After import, an index is generated at `~/.hermes/skills/cybersecurity/index.json` listing all installed skills with their metadata.

docs/matrix-bridge.md

@@ -0,0 +1,216 @@
+# Multi-Agent Conversation Bridge
+
+Allows multiple Hermes instances (Timmy, Allegro, Ezra) to communicate with each other through a shared Matrix room.
+
+## Overview
+
+The Matrix Bridge enables agent-to-agent coordination without manual intervention. Agents can:
+- Send tasks to specific agents
+- Broadcast to all agents
+- Respond to requests from other agents
+- Coordinate on complex workflows
+
+## Configuration
+
+### Environment Variables
+
+```bash
+# Enable/disable the bridge
+MATRIX_BRIDGE_ENABLED=true
+
+# Shared Matrix room ID for agent communication
+MATRIX_BRIDGE_ROOM=!roomid:matrix.example.org
+
+# Agent name (for message routing)
+HERMES_AGENT_NAME=Timmy
+
+# Matrix credentials (from existing Matrix gateway config)
+MATRIX_HOMESERVER=https://matrix.example.org
+MATRIX_ACCESS_TOKEN=syt_...
+```
+
+### Matrix Room Setup
+
+1. Create a Matrix room for agent communication
+2. Invite all agent accounts to the room
+3. Set `MATRIX_BRIDGE_ROOM` to the room ID
+
+## Message Format
+
+Messages use a simple prefix format for routing:
+
+```
+[@Allegro] Check the deployment status on VPS
+[@Ezra] Can you review PR #456?
+[@*] System maintenance in 5 minutes
+```
+
+- `[@AgentName]` — Message for specific agent
+- `[@*]` — Broadcast to all agents
+
+## Usage
+
+### Basic Usage
+
+```python
+from agent.matrix_bridge import MatrixBridge, send_to_agent, broadcast_to_agents
+
+# Create bridge
+bridge = MatrixBridge(agent_name="Timmy")
+await bridge.connect()
+
+# Send to specific agent
+await bridge.send_to_agent("Allegro", "Check deployment status")
+
+# Broadcast to all agents
+await bridge.broadcast("System maintenance starting")
+
+# Add message handler
+def handle_message(msg):
+    print(f"From {msg.sender}: {msg.content}")
+
+bridge.add_handler(handle_message)
+```
+
+### Convenience Functions
+
+```python
+from agent.matrix_bridge import send_to_agent, broadcast_to_agents
+
+# Send message
+await send_to_agent("Ezra", "Review PR #456")
+
+# Broadcast
+await broadcast_to_agents("Going offline for maintenance")
+```
+
+### Agent Registry
+
+```python
+from agent.matrix_bridge import AgentRegistry
+
+registry = AgentRegistry()
+
+# Register agent with capabilities
+registry.register("Timmy", capabilities=["code", "review", "deploy"])
+registry.register("Allegro", capabilities=["monitoring", "alerting"])
+
+# Find agents with capability
+coders = registry.find_agents_with_capability("code")
+```
+
+## Message Flow
+
+```
+┌─────────┐     ┌─────────┐     ┌─────────┐
+│  Timmy  │────▶│ Matrix  │────▶│ Allegro │
+│  Agent  │     │  Room   │     │  Agent  │
+└─────────┘     └─────────┘     └─────────┘
+     │               │               │
+     │  [@Allegro]   │               │
+     │  Check deps   │               │
+     └──────────────▶│               │
+                     │  [@Allegro]   │
+                     │  Check deps   │
+                     └──────────────▶│
+                                     │
+                     │  [@Timmy]     │
+                     │  Done ✓       │
+                     │◀──────────────┘
+     │  [@Timmy]     │
+     │  Done ✓       │
+     │◀──────────────┘
+```
+
+## Integration with Hermes
+
+### In run_agent.py
+
+```python
+# Add to conversation loop
+if self.matrix_bridge:
+    # Check for messages from other agents
+    messages = await self.matrix_bridge.get_pending_messages()
+    for msg in messages:
+        # Process agent-to-agent messages
+        pass
+```
+
+### In Gateway
+
+```python
+# Add Matrix bridge to gateway
+from agent.matrix_bridge import MatrixBridge
+
+bridge = MatrixBridge(agent_name="Timmy")
+await bridge.connect()
+gateway.matrix_bridge = bridge
+```
+
+## Testing
+
+### Unit Tests
+
+```python
+def test_message_parsing():
+    """Test message format parsing."""
+    from agent.matrix_bridge import MatrixBridge
+    
+    bridge = MatrixBridge(agent_name="Timmy")
+    
+    # Test recipient extraction
+    assert bridge._is_for_me("[@Timmy] Hello")
+    assert not bridge._is_for_me("[@Allegro] Hello")
+    assert bridge._is_for_me("[@*] Broadcast")
+    
+    # Test content extraction
+    assert bridge._extract_content("[@Timmy] Hello") == "Hello"
+    assert bridge._extract_content("[@*] Test message") == "Test message"
+```
+
+### Integration Test
+
+```bash
+# Test with two agents
+MATRIX_BRIDGE_ENABLED=true \
+MATRIX_BRIDGE_ROOM=!test:matrix.example.org \
+HERMES_AGENT_NAME=Timmy \
+python -c "
+import asyncio
+from agent.matrix_bridge import send_to_agent
+
+async def test():
+    await send_to_agent('Allegro', 'Test message')
+    print('Sent')
+
+asyncio.run(test())
+"
+```
+
+## Troubleshooting
+
+### Bridge not connecting
+
+1. Check `MATRIX_BRIDGE_ENABLED=true`
+2. Verify `MATRIX_BRIDGE_ROOM` is set
+3. Ensure Matrix credentials are configured
+4. Check Matrix homeserver is reachable
+
+### Messages not received
+
+1. Verify agent is in the Matrix room
+2. Check message format: `[@AgentName] content`
+3. Ensure `HERMES_AGENT_NAME` matches agent name
+4. Check Matrix sync is running
+
+### Agent not found
+
+1. Verify agent has joined the bridge room
+2. Check agent name matches exactly (case-sensitive)
+3. Ensure agent has announced presence
+
+## Related
+
+- Issue #747: feat: multi-agent conversation bridge via Matrix
+- Matrix Gateway: `gateway/platforms/matrix.py`
+- Multi-Agent Orchestration: `docs/multi-agent-orchestration.md`

scripts/import-cybersecurity-skills.py

@@ -1,227 +0,0 @@
-#!/usr/bin/env python3
-"""
-import-cybersecurity-skills.py — Import Anthropic Cybersecurity Skills into Hermes.
-
-Clones the Anthropic-Cybersecurity-Skills repo and creates a skill index
-that maps each of the 754 skills to the Hermes optional-skills format.
-
-Usage:
-    python3 scripts/import-cybersecurity-skills.py --clone          # Clone repo
-    python3 scripts/import-cybersecurity-skills.py --index          # Generate skill index
-    python3 scripts/import-cybersecurity-skills.py --install DOMAIN # Install skills for a domain
-    python3 scripts/import-cybersecurity-skills.py --list           # List all domains
-    python3 scripts/import-cybersecurity-skills.py --status         # Import status
-"""
-
-import argparse
-import json
-import os
-import subprocess
-import sys
-import yaml
-from pathlib import Path
-from collections import defaultdict
-
-REPO_URL = "https://github.com/mukul975/Anthropic-Cybersecurity-Skills.git"
-SKILLS_DIR = Path.home() / ".hermes" / "cybersecurity-skills"
-INDEX_PATH = SKILLS_DIR / "skill-index.json"
-OPTIONAL_SKILLS_DIR = Path.home() / ".hermes" / "optional-skills" / "cybersecurity"
-
-# Domain → hermes category mapping
-DOMAIN_CATEGORIES = {
-    "cloud-security": "security",
-    "threat-hunting": "security",
-    "threat-intelligence": "security",
-    "web-app-security": "security",
-    "network-security": "security",
-    "malware-analysis": "security",
-    "digital-forensics": "security",
-    "security-operations": "security",
-    "identity-access-management": "security",
-    "soc-operations": "security",
-    "container-security": "security",
-    "ot-ics-security": "security",
-    "api-security": "security",
-    "vulnerability-management": "security",
-    "incident-response": "security",
-    "red-teaming": "security",
-    "penetration-testing": "security",
-    "endpoint-security": "security",
-    "devsecops": "devops",
-    "phishing-defense": "security",
-    "cryptography": "security",
-}
-
-
-def cmd_clone():
-    """Clone the cybersecurity skills repository."""
-    if SKILLS_DIR.exists():
-        print(f"Updating existing clone at {SKILLS_DIR}")
-        subprocess.run(["git", "-C", str(SKILLS_DIR), "pull"], capture_output=True)
-    else:
-        SKILLS_DIR.parent.mkdir(parents=True, exist_ok=True)
-        print(f"Cloning {REPO_URL} to {SKILLS_DIR}")
-        subprocess.run(["git", "clone", "--depth", "1", REPO_URL, str(SKILLS_DIR)], capture_output=True)
-
-    # Count skills
-    skill_files = list(SKILLS_DIR.rglob("*.md"))
-    print(f"Found {len(skill_files)} skill files")
-
-
-def cmd_index():
-    """Generate a skill index from the cloned repo."""
-    if not SKILLS_DIR.exists():
-        print("Run --clone first", file=sys.stderr)
-        sys.exit(1)
-
-    skills = []
-    domains = defaultdict(list)
-
-    for md_file in SKILLS_DIR.rglob("*.md"):
-        if md_file.name in ("README.md", "LICENSE.md", "DESCRIPTION.md"):
-            continue
-
-        try:
-            content = md_file.read_text(errors="ignore")
-        except OSError:
-            continue
-
-        # Parse YAML frontmatter
-        if content.startswith("---"):
-            parts = content.split("---", 2)
-            if len(parts) >= 3:
-                try:
-                    frontmatter = yaml.safe_load(parts[1]) or {}
-                except yaml.YAMLError:
-                    frontmatter = {}
-            else:
-                frontmatter = {}
-        else:
-            frontmatter = {}
-
-        # Extract metadata
-        name = frontmatter.get("name", md_file.stem)
-        description = frontmatter.get("description", "")
-        domain = frontmatter.get("domain", frontmatter.get("subdomain", "general"))
-        tags = frontmatter.get("tags", [])
-        frameworks = frontmatter.get("nist_csf", []) + frontmatter.get("mitre_attack", [])
-
-        skill = {
-            "name": name,
-            "file": str(md_file.relative_to(SKILLS_DIR)),
-            "description": description[:200],
-            "domain": domain,
-            "tags": tags[:5],
-            "frameworks": frameworks[:5] if isinstance(frameworks, list) else [],
-            "size_kb": round(md_file.stat().st_size / 1024, 1),
-        }
-        skills.append(skill)
-        domains[domain].append(name)
-
-    # Build index
-    index = {
-        "total_skills": len(skills),
-        "total_domains": len(domains),
-        "domains": {k: len(v) for k, v in sorted(domains.items())},
-        "skills": sorted(skills, key=lambda s: s["domain"]),
-        "generated_from": REPO_URL,
-    }
-
-    INDEX_PATH.write_text(json.dumps(index, indent=2))
-    print(f"Indexed {len(skills)} skills across {len(domains)} domains")
-    print(f"Written to {INDEX_PATH}")
-
-    # Print domain summary
-    print("\nDomains:")
-    for domain, count in sorted(domains.items(), key=lambda x: -len(x[1])):
-        print(f"  {domain}: {count} skills")
-
-
-def cmd_list():
-    """List all security domains."""
-    if not INDEX_PATH.exists():
-        print("Run --index first", file=sys.stderr)
-        sys.exit(1)
-
-    index = json.loads(INDEX_PATH.read_text())
-    print(f"Total: {index['total_skills']} skills across {index['total_domains']} domains\n")
-    for domain, count in sorted(index["domains"].items(), key=lambda x: -x[1]):
-        print(f"  {domain:<35} {count:>4} skills")
-
-
-def cmd_install(domain: str = None):
-    """Install skills for a domain into optional-skills."""
-    if not INDEX_PATH.exists():
-        print("Run --index first", file=sys.stderr)
-        sys.exit(1)
-
-    index = json.loads(INDEX_PATH.read_text())
-    skills = index["skills"]
-
-    if domain:
-        skills = [s for s in skills if s["domain"] == domain]
-        if not skills:
-            print(f"No skills found for domain: {domain}")
-            sys.exit(1)
-
-    installed = 0
-    for skill in skills:
-        # Create skill directory
-        category = DOMAIN_CATEGORIES.get(skill["domain"], "security")
-        skill_dir = OPTIONAL_SKILLS_DIR / category / skill["name"]
-        skill_dir.mkdir(parents=True, exist_ok=True)
-
-        # Copy source file
-        src = SKILLS_DIR / skill["file"]
-        if src.exists():
-            dst = skill_dir / "SKILL.md"
-            dst.write_text(src.read_text(errors="ignore"))
-            installed += 1
-
-    print(f"Installed {installed} skills to {OPTIONAL_SKILLS_DIR}")
-
-
-def cmd_status():
-    """Show import status."""
-    print(f"Clone dir: {SKILLS_DIR}")
-    print(f"  Exists: {SKILLS_DIR.exists()}")
-
-    print(f"Index: {INDEX_PATH}")
-    print(f"  Exists: {INDEX_PATH.exists()}")
-    if INDEX_PATH.exists():
-        index = json.loads(INDEX_PATH.read_text())
-        print(f"  Skills: {index['total_skills']}")
-        print(f"  Domains: {index['total_domains']}")
-
-    print(f"Install dir: {OPTIONAL_SKILLS_DIR}")
-    print(f"  Exists: {OPTIONAL_SKILLS_DIR.exists()}")
-    if OPTIONAL_SKILLS_DIR.exists():
-        installed = len(list(OPTIONAL_SKILLS_DIR.rglob("SKILL.md")))
-        print(f"  Installed skills: {installed}")
-
-
-def main():
-    parser = argparse.ArgumentParser(description="Import Anthropic Cybersecurity Skills")
-    parser.add_argument("--clone", action="store_true", help="Clone the skills repo")
-    parser.add_argument("--index", action="store_true", help="Generate skill index")
-    parser.add_argument("--list", action="store_true", help="List all domains")
-    parser.add_argument("--install", metavar="DOMAIN", nargs="?", const="all", help="Install skills for domain")
-    parser.add_argument("--status", action="store_true", help="Import status")
-    args = parser.parse_args()
-
-    if args.clone:
-        cmd_clone()
-    elif args.index:
-        cmd_index()
-    elif args.list:
-        cmd_list()
-    elif args.install is not None:
-        cmd_install(None if args.install == "all" else args.install)
-    elif args.status:
-        cmd_status()
-    else:
-        parser.print_help()
-
-
-if __name__ == "__main__":
-    main()

scripts/import_cybersecurity_skills.py

@@ -1,245 +0,0 @@
-#!/usr/bin/env python3
-"""
-import_cybersecurity_skills.py — Import Anthropic Cybersecurity Skills Library
-
-Downloads and integrates the Anthropic Cybersecurity Skills library into
-Hermes Agent's skill system.
-
-Source: https://github.com/mukul975/Anthropic-Cybersecurity-Skills
-License: Apache 2.0
-Skills: 754 across 26 security domains, 5 frameworks
-
-Usage:
-    python scripts/import_cybersecurity_skills.py
-    python scripts/import_cybersecurity_skills.py --domain cloud-security
-    python scripts/import_cybersecurity_skills.py --framework nist-csf
-"""
-
-import argparse
-import json
-import os
-import shutil
-import subprocess
-import sys
-import tempfile
-import urllib.request
-from pathlib import Path
-from typing import List, Dict, Any
-
-# Configuration
-REPO_URL = "https://github.com/mukul975/Anthropic-Cybersecurity-Skills.git"
-SKILLS_DIR = Path.home() / ".hermes" / "skills" / "cybersecurity"
-CACHE_DIR = Path.home() / ".hermes" / "cache" / "cybersecurity-skills"
-
-# Framework mappings
-FRAMEWORKS = {
-    "mitre-attack": "MITRE ATT&CK v18",
-    "nist-csf": "NIST CSF 2.0",
-    "mitre-atlas": "MITRE ATLAS v5.4",
-    "mitre-d3fend": "MITRE D3FEND v1.3",
-    "nist-ai-rmf": "NIST AI RMF 1.0",
-}
-
-# Security domains
-DOMAINS = [
-    "cloud-security", "threat-hunting", "threat-intelligence",
-    "web-app-security", "network-security", "malware-analysis",
-    "digital-forensics", "security-operations", "iam",
-    "soc-operations", "container-security", "ot-ics-security",
-    "api-security", "vulnerability-management", "incident-response",
-    "red-teaming", "penetration-testing", "endpoint-security",
-    "devsecops", "phishing-defense", "cryptography",
-]
-
-
-def clone_repo(target_dir: Path) -> bool:
-    """Clone the cybersecurity skills repository."""
-    print(f"Cloning {REPO_URL}...")
-    try:
-        subprocess.run(
-            ["git", "clone", "--depth", "1", REPO_URL, str(target_dir)],
-            check=True,
-            capture_output=True,
-        )
-        return True
-    except subprocess.CalledProcessError as e:
-        print(f"Error cloning repository: {e}", file=sys.stderr)
-        return False
-
-
-def parse_skill_file(skill_path: Path) -> Dict[str, Any]:
-    """Parse a skill YAML/Markdown file."""
-    content = skill_path.read_text(encoding="utf-8")
-    
-    # Extract YAML frontmatter
-    if content.startswith("---"):
-        parts = content.split("---", 2)
-        if len(parts) >= 3:
-            import yaml
-            try:
-                metadata = yaml.safe_load(parts[1])
-                metadata["content"] = parts[2].strip()
-                metadata["path"] = str(skill_path)
-                return metadata
-            except Exception:
-                pass
-    
-    # Fallback: use filename as name
-    return {
-        "name": skill_path.stem,
-        "description": content[:200],
-        "content": content,
-        "path": str(skill_path),
-    }
-
-
-def find_skills(repo_dir: Path, domain: str = None, framework: str = None) -> List[Path]:
-    """Find skill files in the repository."""
-    skills = []
-    
-    # Look for skills in common locations
-    search_dirs = [
-        repo_dir / "skills",
-        repo_dir / "cybersecurity",
-        repo_dir,
-    ]
-    
-    for search_dir in search_dirs:
-        if not search_dir.exists():
-            continue
-        
-        for path in search_dir.rglob("*.md"):
-            # Skip README files
-            if path.name.upper() == "README.MD":
-                continue
-            
-            # Filter by domain if specified
-            if domain:
-                if domain.lower() not in str(path).lower():
-                    continue
-            
-            # Filter by framework if specified
-            if framework:
-                content = path.read_text(encoding="utf-8", errors="ignore").lower()
-                if framework.lower() not in content:
-                    continue
-            
-            skills.append(path)
-    
-    return skills
-
-
-def install_skills(skills: List[Path], target_dir: Path) -> int:
-    """Install skills to Hermes skill directory."""
-    target_dir.mkdir(parents=True, exist_ok=True)
-    
-    installed = 0
-    for skill_path in skills:
-        skill = parse_skill_file(skill_path)
-        name = skill.get("name", skill_path.stem)
-        
-        # Create skill directory
-        skill_dir = target_dir / name
-        skill_dir.mkdir(exist_ok=True)
-        
-        # Copy skill file
-        dest = skill_dir / "SKILL.md"
-        shutil.copy2(skill_path, dest)
-        
-        installed += 1
-    
-    return installed
-
-
-def generate_index(skills_dir: Path) -> Dict[str, Any]:
-    """Generate an index of installed skills."""
-    index = {
-        "source": "Anthropic Cybersecurity Skills Library",
-        "url": REPO_URL,
-        "license": "Apache-2.0",
-        "skills": [],
-    }
-    
-    for skill_dir in skills_dir.iterdir():
-        if not skill_dir.is_dir():
-            continue
-        
-        skill_file = skill_dir / "SKILL.md"
-        if not skill_file.exists():
-            continue
-        
-        skill = parse_skill_file(skill_file)
-        index["skills"].append({
-            "name": skill.get("name", skill_dir.name),
-            "description": skill.get("description", "")[:200],
-            "domain": skill.get("domain", ""),
-            "frameworks": skill.get("frameworks", []),
-        })
-    
-    return index
-
-
-def main():
-    parser = argparse.ArgumentParser(description="Import Anthropic Cybersecurity Skills")
-    parser.add_argument("--domain", "-d", help="Filter by security domain")
-    parser.add_argument("--framework", "-f", help="Filter by framework (e.g., nist-csf)")
-    parser.add_argument("--list-domains", action="store_true", help="List available domains")
-    parser.add_argument("--list-frameworks", action="store_true", help="List available frameworks")
-    parser.add_argument("--output", "-o", help="Output directory for skills")
-    parser.add_argument("--dry-run", action="store_true", help="Show what would be imported")
-    
-    args = parser.parse_args()
-    
-    # List domains
-    if args.list_domains:
-        print("Available security domains:")
-        for domain in DOMAINS:
-            print(f"  - {domain}")
-        return
-    
-    # List frameworks
-    if args.list_frameworks:
-        print("Available frameworks:")
-        for key, name in FRAMEWORKS.items():
-            print(f"  - {key}: {name}")
-        return
-    
-    # Set output directory
-    output_dir = Path(args.output) if args.output else SKILLS_DIR
-    
-    # Clone repository
-    with tempfile.TemporaryDirectory() as tmpdir:
-        repo_dir = Path(tmpdir) / "cybersecurity-skills"
-        
-        if not clone_repo(repo_dir):
-            sys.exit(1)
-        
-        # Find skills
-        print(f"Searching for skills (domain={args.domain}, framework={args.framework})...")
-        skills = find_skills(repo_dir, args.domain, args.framework)
-        print(f"Found {len(skills)} skills")
-        
-        if args.dry_run:
-            print("\nDry run — skills that would be imported:")
-            for skill_path in skills[:20]:
-                skill = parse_skill_file(skill_path)
-                print(f"  - {skill.get('name', skill_path.stem)}: {skill.get('description', '')[:60]}...")
-            if len(skills) > 20:
-                print(f"  ... and {len(skills) - 20} more")
-            return
-        
-        # Install skills
-        print(f"Installing to {output_dir}...")
-        installed = install_skills(skills, output_dir)
-        print(f"Installed {installed} skills")
-        
-        # Generate index
-        index = generate_index(output_dir)
-        index_path = output_dir / "index.json"
-        with open(index_path, "w") as f:
-            json.dump(index, f, indent=2)
-        print(f"Index saved to {index_path}")
-
-
-if __name__ == "__main__":
-    main()

tests/test_matrix_bridge.py

@@ -0,0 +1,114 @@
+"""Tests for Matrix Bridge — Issue #747."""
+import sys
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from agent.matrix_bridge import MatrixBridge, AgentMessage, AgentRegistry
+
+
+class TestMessageParsing:
+    """Test message format parsing."""
+    
+    def test_is_for_me_direct(self):
+        bridge = MatrixBridge(agent_name="Timmy")
+        assert bridge._is_for_me("[@Timmy] Hello") == True
+    
+    def test_is_not_for_me(self):
+        bridge = MatrixBridge(agent_name="Timmy")
+        assert bridge._is_for_me("[@Allegro] Hello") == False
+    
+    def test_is_broadcast(self):
+        bridge = MatrixBridge(agent_name="Timmy")
+        assert bridge._is_for_me("[@*] Broadcast") == True
+    
+    def test_extract_content(self):
+        bridge = MatrixBridge(agent_name="Timmy")
+        assert bridge._extract_content("[@Timmy] Hello world") == "Hello world"
+    
+    def test_extract_content_multiline(self):
+        bridge = MatrixBridge(agent_name="Timmy")
+        content = bridge._extract_content("[@Timmy] Line 1\nLine 2")
+        assert content == "Line 1\nLine 2"
+
+
+class TestAgentMessage:
+    """Test AgentMessage dataclass."""
+    
+    def test_to_dict(self):
+        msg = AgentMessage(
+            sender="Timmy",
+            recipient="Allegro",
+            content="Hello",
+            timestamp=1234567890.0,
+        )
+        d = msg.to_dict()
+        assert d["sender"] == "Timmy"
+        assert d["recipient"] == "Allegro"
+        assert d["content"] == "Hello"
+    
+    def test_from_dict(self):
+        d = {
+            "sender": "Timmy",
+            "recipient": "Allegro",
+            "content": "Hello",
+            "timestamp": 1234567890.0,
+            "message_id": "",
+            "room_id": "",
+        }
+        msg = AgentMessage.from_dict(d)
+        assert msg.sender == "Timmy"
+        assert msg.recipient == "Allegro"
+
+
+class TestAgentRegistry:
+    """Test AgentRegistry."""
+    
+    def test_register(self):
+        registry = AgentRegistry()
+        registry.register("Timmy", capabilities=["code", "review"])
+        agent = registry.get_agent("Timmy")
+        assert agent["name"] == "Timmy"
+        assert "code" in agent["capabilities"]
+    
+    def test_list_agents(self):
+        registry = AgentRegistry()
+        registry.register("Timmy")
+        registry.register("Allegro")
+        agents = registry.list_agents()
+        assert len(agents) == 2
+    
+    def test_find_with_capability(self):
+        registry = AgentRegistry()
+        registry.register("Timmy", capabilities=["code"])
+        registry.register("Allegro", capabilities=["monitoring"])
+        coders = registry.find_agents_with_capability("code")
+        assert "Timmy" in coders
+        assert "Allegro" not in coders
+    
+    def test_unregister(self):
+        registry = AgentRegistry()
+        registry.register("Timmy")
+        registry.unregister("Timmy")
+        agent = registry.get_agent("Timmy")
+        assert agent["status"] == "offline"
+
+
+class TestBridgeInit:
+    """Test bridge initialization."""
+    
+    def test_default_agent_name(self):
+        bridge = MatrixBridge()
+        assert bridge.agent_name == "Hermes"
+    
+    def test_custom_agent_name(self):
+        bridge = MatrixBridge(agent_name="Timmy")
+        assert bridge.agent_name == "Timmy"
+    
+    def test_known_agents_empty(self):
+        bridge = MatrixBridge()
+        assert len(bridge.get_known_agents()) == 0
+
+
+if __name__ == "__main__":
+    import pytest
+    pytest.main([__file__, "-v"])