# 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`

```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)

```json
{
  "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)

```json
{
  "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"
    }
  ]
}
```