openclaw/workspace/james/docs/EVENTS.md

EVENTS.md — Event Format and Channels

All James components communicate through Redis using a universal JSON schema.

---

Schema

Schema file: workspace/james/schemas/event.json

{
  "id": "evt-20260204-00123",
  "source": "node-a",
  "type": "system.metrics",
  "timestamp": 1738678200,
  "severity": "low",
  "payload": {}
}

Validation

• Runtime validation: workspace/james/lib/schema.py
• CLI validation: workspace/james/tools/validate_event.py

---

Channels

• james.events.system — watcher events
• james.events.mail — mail agent events
• james.events.voice — voice stub output
• james.decisions — analyst output
• james.actions — policy output
• james.audit — audit replay channel

---

Event Types (implemented)

System

• system.metrics
• disk.high_usage
• cpu.high_usage
• memory.high_usage
• gpu.vram_high
• container.running
• container.stopped

Mail

• mail.action_required
• mail.invoice
• mail.security_alert
• mail.newsletter
• mail.fyi

Decision

• decision.action_suggested
• decision.no_action

Action

• action.pending_approval
• action.allowed
• action.denied

Voice

• voice.briefing
• voice.approval_request

---

Severity

• low — informational
• medium — notable
• high — urgent
• critical — immediate attention

---

Decision Payload (example)

{
  "summary": "disk.high_usage on node-a",
  "priority": "medium",
  "confidence": 0.72,
  "suggested_actions": [
    {
      "action": "refresh_status",
      "target": "node-a",
      "reason": "disk.high_usage threshold exceeded"
    }
  ],
  "event": {
    "id": "evt-20260204-00123",
    "type": "disk.high_usage",
    "source": "node-a",
    "severity": "medium"
  }
}

Action Payload (example)

{
  "decision_id": "evt-20260204-04567",
  "decision_event": {
    "id": "evt-20260204-00123",
    "type": "disk.high_usage",
    "source": "node-a",
    "severity": "medium"
  },
  "actions": [
    {
      "action": "refresh_status",
      "target": "node-a",
      "reason": "disk.high_usage threshold exceeded",
      "classification": "internal",
      "decision_id": "evt-20260204-04567",
      "decision_event_id": "evt-20260204-00123",
      "requested_by": "node-a",
      "status": "allowed"
    }
  ]
}