feat: Add presence heartbeat for Matrix online status

- matrix-gateway: POST /internal/matrix/presence/online endpoint - usePresenceHeartbeat hook with activity tracking - Auto away after 5 min inactivity - Offline on page close/visibility change - Integrated in MatrixChatRoom component
2025-11-27 00:19:40 -08:00
parent 5bed515852
commit 3de3c8cb36
6371 changed files with 1317450 additions and 932 deletions
--- a/services/router/README.md
+++ b/services/router/README.md
@@ -0,0 +1,211 @@
+# DAGI Router Service
+
+**Routes events to appropriate agents and services**
+
+## Purpose
+
+DAGI Router is the central orchestrator that routes various events (filter decisions, direct invocations, scheduled jobs) to agent-runtime for execution.
+
+## Features
+
+- **Filter Decision Routing**: Processes `agent.filter.decision` events
+- **Agent Invocation**: Creates and publishes `router.invoke.agent` messages
+- **Configurable**: YAML-based routing configuration
+- **Test Mode**: HTTP endpoint for testing routing logic
+
+## Architecture
+
+```
+agent.filter.decision (NATS)
+    ↓
+router: Create AgentInvocation
+    ↓
+router.invoke.agent (NATS)
+    ↓
+agent-runtime (subscribes)
+```
+
+## Routing Rules
+
+### Messaging Inbound (Phase 2)
+
+**Input**: `agent.filter.decision` (from agent-filter)  
+**Output**: `router.invoke.agent` (to agent-runtime)
+
+**Logic**:
+1. Only process `decision == "allow"`
+2. Ensure `target_agent_id` is present
+3. Create `AgentInvocation` with channel context
+4. Publish to NATS
+
+### Future Rules (Phase 3+)
+
+- Direct agent invocations (API calls)
+- Scheduled/cron invocations
+- Webhook-triggered invocations
+- Agent-to-agent communication
+
+## API
+
+### Health Check
+```http
+GET /health
+
+Response:
+{
+  "status": "ok",
+  "service": "router",
+  "version": "1.0.0",
+  "nats_connected": true,
+  "messaging_inbound_enabled": true
+}
+```
+
+### Test Routing (Manual)
+```http
+POST /internal/router/test-messaging
+Content-Type: application/json
+
+{
+  "channel_id": "test-channel",
+  "matrix_event_id": "$event123",
+  "microdao_id": "microdao:daarion",
+  "decision": "allow",
+  "target_agent_id": "agent:sofia"
+}
+
+Response:
+{
+  "agent_id": "agent:sofia",
+  "entrypoint": "channel_message",
+  "payload": {
+    "channel_id": "test-channel",
+    "matrix_event_id": "$event123",
+    "microdao_id": "microdao:daarion",
+    "rewrite_prompt": null
+  }
+}
+```
+
+## Configuration
+
+**File**: `router_config.yaml`
+
+```yaml
+messaging_inbound:
+  enabled: true
+  source_subject: "agent.filter.decision"
+  target_subject: "router.invoke.agent"
+```
+
+## Environment Variables
+
+- `NATS_URL`: NATS server URL (default: `nats://nats:4222`)
+
+## Running Locally
+
+### Install Dependencies
+```bash
+pip install -r requirements.txt
+```
+
+### Run Service
+```bash
+uvicorn main:app --reload --port 8000
+```
+
+### Test
+```bash
+# Health check
+curl http://localhost:8000/health
+
+# Test routing
+curl -X POST http://localhost:8000/internal/router/test-messaging \
+  -H "Content-Type: application/json" \
+  -d '{
+    "channel_id": "test-123",
+    "matrix_event_id": "$test",
+    "microdao_id": "microdao:daarion",
+    "decision": "allow",
+    "target_agent_id": "agent:sofia"
+  }'
+```
+
+## Docker
+
+### Build
+```bash
+docker build -t daarion/router:latest .
+```
+
+### Run
+```bash
+docker run -p 8000:8000 \
+  -e NATS_URL=nats://nats:4222 \
+  daarion/router:latest
+```
+
+## NATS Events
+
+### Subscribes To
+- **Subject**: `agent.filter.decision`
+- **Payload**: `FilterDecision`
+
+### Publishes To
+- **Subject**: `router.invoke.agent`
+- **Payload**: `AgentInvocation`
+
+## Monitoring
+
+### Logs
+
+```bash
+docker logs -f router
+
+# Look for:
+# ✅ Connected to NATS
+# ✅ Subscribed to agent.filter.decision
+# 🔀 Processing filter decision
+# ✅ Decision: allow
+# 🚀 Created invocation for agent:sofia
+# ✅ Published invocation
+```
+
+## Troubleshooting
+
+### Not Routing Messages
+
+**Check**:
+1. Is router subscribed to NATS?
+2. Is agent-filter publishing decisions?
+3. Are decisions "allow"?
+4. Is target_agent_id present?
+
+```bash
+# Check NATS subscription
+docker exec -it router cat /app/router_config.yaml
+
+# Test routing logic
+curl -X POST http://localhost:8000/internal/router/test-messaging \
+  -d @test_decision.json
+```
+
+## Future Enhancements
+
+- [ ] Multiple routing strategies
+- [ ] Agent load balancing
+- [ ] Priority queues
+- [ ] Rate limiting per agent
+- [ ] Retry logic
+- [ ] Dead letter queue
+- [ ] Routing analytics
+
+## Version
+
+**Current**: 1.0.0  
+**Status**: Production Ready (Phase 2)  
+**Last Updated**: 2025-11-24
+
+
+
+