# EVENTS.md — Event Format and Channels

All communication between system components happens through Redis using structured JSON events.

---

## Universal Event Schema

```json
{
  "id": "evt-20260204-00123",
  "source": "gpu-box",
  "type": "system.alert",
  "timestamp": 1738678200,
  "severity": "medium",
  "payload": {}
}
```

---

## Channels

### james.events.system

Emitted by Watchers.

**Examples:**

- `container_down`
- `vram_high`
- `disk_full`
- `service_unhealthy`

### james.events.mail

Emitted by Mail Agent.

**Examples:**

- `important_email`
- `invoice_detected`
- `security_notice`

### james.decisions

Emitted by Analyst.

Contains priority, confidence, and suggested actions.

### james.actions

Emitted after human or policy approval.

Consumed by Action Router.

### james.audit

Immutable log of:

- Events
- Decisions
- Approvals
- Executed actions

---

## Severity Levels

- `low` → informational
- `medium` → notable
- `high` → urgent
- `critical` → immediate attention

---

## Event Types

### System Events

- `system.metrics`
- `container.stopped`
- `container.restarted`
- `disk.high_usage`
- `cpu.high_usage`
- `memory.high_usage`
- `gpu.vram_high`
- `service.unhealthy`
- `backup.failed`

### Mail Events

- `mail.action_required`
- `mail.invoice`
- `mail.security_alert`
- `mail.newsletter`

### Decision Events

- `decision.action_suggested`
- `decision.approval_required`
- `decision.denied`
- `decision.no_action`

### Action Events

- `action.executed`
- `action.failed`
- `action.pending_approval`
- `action.allowed`
- `action.denied`

---

## Decision Payload (example)

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

## Action Payload (example)

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