# Hermes Hub — UI State & ViewModel Contract

**Document Version:** 1.0.0  
**Date:** 2026-08-21  
**Status:** Canonical Interface Specification for UI (Codex Assignment B) & State Layer (Antigravity Assignment A)  
**Scope:** `src/antigravity_provider/router/state_store.py`, `unified_health.py`, `account_identity.py`, `event_bus.py`

---

## 1. Executive Architecture & Invariants

1. **Single Source of Truth (`HubSnapshot`):** The entire UI layer reads state exclusively from the immutable `HubSnapshot` supplied by `HubStateStore.get().get_snapshot()` or emitted via `EventBus`. Views MUST NOT call scanning/probing methods (e.g. `scan_all()`).
2. **Delta Updates via `EventBus`:** Incremental updates (quota shifts, single account mutations, route swaps) dispatch targeted typed events on `EventBus.get()`.
3. **Data Truthfulness Invariant:** Unverified or offline metrics MUST report `is_estimated = True` with source `"baseline"` or `"estimated"`, and percentages as `None` (UI displays «Доступна» / «(оценка)»). Fabricated percentages or false `*_api` source labels are strictly forbidden.

---

## 2. Core Snapshot Model: `HubSnapshot`

Immutable snapshot (`@dataclass(frozen=True)`) representing the state of Hermes Hub at generation `generation`.

| Field | Type | Description | Real / Simulated |
|---|---|---|---|
| `generation` | `int` | Monotonically increasing generation number (increments on every snapshot update). | **Real** |
| `timestamp` | `float` | UNIX epoch timestamp when snapshot was created (`time.time()`). | **Real** |
| `profiles_by_provider` | `Dict[str, List[ProfileViewModel]]` | Profiles grouped by provider identifier (`"antigravity"`, `"openai-codex"`, `"opencode-go"`, `"claude"`, `"grok"`). | **Real** |
| `all_profiles` | `Dict[str, ProfileViewModel]` | Flat lookup map of all profiles indexed by `profile_id`. | **Real** |
| `readiness` | `SystemReadiness` | Aggregated system readiness, role coverage metrics, and warnings. | **Real** |
| `agents` | `List[AgentViewModel]` | List of logical agent roles and their active routing status. | **Real** |
| `providers` | `List[ProviderSummary]` | Summary status per provider for quick overview cards. | **Real** |
| `routing` | `Dict[str, RolePipeline]` | Role pipelines mapping `role_id` to failover nodes. | **Real** |
| `quotas` | `Dict[str, QuotaSnapshot]` | Map of `profile_id` -> `QuotaSnapshot`. | **Real** |
| `metrics` | `Dict[str, Any]` | Internal metrics (e.g. `refresh_runs_total`, `refresh_failures_total`). | **Real** |
| `is_stale` | `bool` | True if background refresh is overdue (> 300s). | **Real** |

### Helper Methods
- `get_profile(profile_id: str) -> Optional[ProfileViewModel]`
- `get_provider_profiles(provider: str) -> List[ProfileViewModel]`
- `get_role_pipeline(role_id: str) -> Optional[RolePipeline]`

---

## 3. Account View Model: `ProfileViewModel`

Model representing an individual account/slot card in UI views.

| Field | Type | Nullable / Optional | Description & Values |
|---|---|---|---|
| `profile_id` | `str` | No | Unique profile identifier (e.g. `"ag-w1"`, `"codex-slot-1"`). |
| `display_name` | `str` | No | User-facing display title (e.g. `"Antigravity Slot 1"`). |
| `account_identity` | `str` | No | Primary user identity (email, account ID, or profile ID). |
| `provider` | `str` | No | Provider ID (`"antigravity"`, `"openai-codex"`, `"opencode-go"`, `"claude"`, `"grok"`). |
| `provider_display_name` | `str` | No | Formatted provider name (e.g. `"Google Antigravity"`, `"OpenAI Codex"`). |
| `assigned_roles` | `List[str]` | No | List of role names assigned to this profile. |
| `primary_role` | `Optional[str]` | Yes | Primary assigned role name (or `None` if unassigned / spare). |
| `is_main_account` | `bool` | No | True if designated as Main Account for general execution. |
| `is_main_orchestrator` | `bool` | No | True if designated as Orchestrator profile. |
| `auth_state` | `str` | No | `"AUTHENTICATED"` \| `"AUTH_REQUIRED"` \| `"AUTH_EXPIRED"` \| `"UNCONFIGURED"`. |
| `health_state` | `str` | No | `"healthy"` \| `"warning"` \| `"exhausted"` \| `"rate_limited"` \| `"cooldown"` \| `"auth_required"` \| `"disabled"` \| `"cold_spare"` \| `"unhealthy"` \| `"not_configured"`. |
| `health_label_ru` | `str` | No | Localized Russian status text (e.g. `"Готов"`, `"Исчерпан"`, `"Ограничение"`). |
| `model_states` | `Dict[str, ModelFamilyHealth]` | No | Per-family health records (e.g. `{"gemini": ModelFamilyHealth(...)}`). |
| `cooldown_remaining_sec` | `int` | No | Seconds until cooldown/rate-limit expires (`0` if healthy). |
| `last_checked_at` | `Optional[str]` | Yes | Formatted time string (e.g. `"15:42:10"` or `"недавно"`). |
| `enabled` | `bool` | No | True if slot is enabled in `router_profiles.yaml`. |
| `is_cold_spare` | `bool` | No | True if authenticated but unassigned to any active role chain. |
| `is_empty_slot` | `bool` | No | True if unauthenticated placeholder slot. |
| `email` | `str` | No | Email parsed from JWT/API (empty string if unavailable). |
| `plan` | `str` | No | Localized plan string (e.g. `"Тариф: MAX"`, `"Тариф: PRO"`, `"Тариф: неизвестен"`). |
| `plan_code` | `str` | No | Normalized plan code (`"PRO"`, `"PLUS"`, `"MAX"`, `"SUPERGROK"`, `"UNKNOWN"`). |
| `quota_snapshot` | `Optional[QuotaSnapshot]` | Yes | Associated quota snapshot object. |
| `preferred_models` | `List[str]` | No | List of configured models for this profile. |

---

## 4. Quota Models: `QuotaSnapshot` & `QuotaBucket`

### `QuotaSnapshot` Schema
- `account_id: str` — Profile or Account ID
- `provider: str` — Provider ID
- `buckets: List[QuotaBucket]` — 1 to 4 limit buckets
- `fetched_at: datetime` — UTC timestamp of measurement
- `stale_after_seconds: int` — Expiry window (default 300s)
- `source: str` — `"baseline"` \| `"estimated"` \| `"runtime_event"` \| `"provider_api"`
- `is_estimated: bool` — **True** if offline baseline / heuristic, **False** if verified live API
- `freshness_label() -> str` — e.g. `"Обновлено: только что"`, `"Обновлено: 5 мин назад"`

### `QuotaBucket` Schema
- `id: str` — e.g. `"antigravity.claude.5h"`, `"codex.weekly"`, `"grok.frequent_tasks"`
- `display_name: str` — e.g. `"5h"`, `"Weekly"`, `"Задачи"`, `"Запросы"`
- `model_family: Optional[str]` — Model family bounded by this bucket (`"gemini"`, `"claude"`, `"gpt"`, `"grok"`, `"opencode"`)
- `used_percent: Optional[float]` — `0.0 .. 100.0` or `None` if unmeasured
- `remaining_percent: Optional[float]` — `0.0 .. 100.0` or `None` if unmeasured
- `used_absolute: Optional[int]` — Absolute units used (if reported by provider API)
- `remaining_absolute: Optional[int]` — Absolute units remaining
- `limit_absolute: Optional[int]` — Absolute maximum limit
- `reset_at: Optional[datetime]` — UTC reset timestamp
- `reset_in_seconds: Optional[int]` — Seconds until quota reset
- `period: Optional[str]` — `"5h"`, `"7d"`, `"30d"`, `"sliding"`
- `status: str` — `"healthy"`, `"warning"`, `"exhausted"`, `"unknown"`
- `formatted_remaining() -> str` — e.g. `"Доступна"`, `"Осталось 85%"`, `"150/1000"`
- `formatted_reset() -> Optional[str]` — e.g. `"Сброс через 1ч 45м"`, `None`

---

## 5. Actual Provider Quota Breakdown (Live vs Estimated)

| Provider | Real Quota APIs Available? | Buckets Populated | `source` | `is_estimated` | Notes |
|---|---|---|---|---|---|
| **Google Antigravity** | Partial (via CLI runtime 429 reset parsing) | `antigravity.claude.5h`, `antigravity.claude.weekly`, `antigravity.gemini` | `"baseline"` or `"runtime_event"` | `True` (baseline) / `False` (on 429 event) | Baseline shows «Доступна (оценка)». On 429, parses exact reset duration. |
| **OpenAI Codex** | Device flow / local token | `codex.primary.weekly` | `"baseline"` or `"runtime_event"` | `True` (baseline) / `False` (on 429 event) | Baseline shows «Доступна (оценка)». |
| **xAI Grok** | Device flow / token | `grok.frequent_tasks`, `grok.daily_quota` | `"baseline"` or `"runtime_event"` | `True` (baseline) / `False` (on 429 event) | Baseline shows «Доступна (оценка)». |
| **Anthropic Claude** | Token / PKCE | `claude.session.5h`, `claude.weekly` | `"baseline"` or `"runtime_event"` | `True` (baseline) / `False` (on 429 event) | Baseline shows «Доступна (оценка)». |
| **OpenCode Go** | Local CLI / API key | `opencode.tasks` | `"baseline"` | `True` | Baseline shows «Доступна (оценка)». |

---

## 6. Routing & System ViewModels

### `SystemReadiness`
- `state: str` — `"healthy"` \| `"limited"` \| `"degraded"` \| `"critical"`
- `title_ru: str` — Summary title (e.g. `"Система готова к работе"`)
- `summary_ru: str` — Explanatory status text
- `roles_ready_count: int`, `total_roles: int`
- `accounts_connected_count: int`, `total_accounts: int`
- `providers_ready_count: int`, `total_providers: int`
- `warnings: List[str]` — Critical warning strings for banner display

### `AgentViewModel`
- `role_id: str` — Logical role (e.g. `"coder-primary"`, `"reviewer"`)
- `role_name_ru: str`, `role_description_ru: str`
- `assigned_profile_id: Optional[str]`, `assigned_display_name: Optional[str]`
- `provider: str`, `provider_display_name: str`, `model: str`
- `routing_position: str` — `"Primary"`, `"Fallback 1"`, `"Fallback 2"`
- `status: str` — `"healthy"`, `"exhausted"`, `"auth_required"`, `"unconfigured"`
- `is_active: bool`, `is_main_orchestrator: bool`, `cooldown_remaining_sec: int`

### `RolePipeline` & `PipelineNode`
- `RolePipeline`: `role_id`, `role_name_ru`, `default_model`, `max_failover`, `session_affinity`, `active_profile_id`, `nodes: List[PipelineNode]`
- `PipelineNode`: `profile_id`, `display_name`, `provider`, `model`, `status`, `status_label_ru`, `is_active: bool`, `cooldown_remaining_sec: int`

### `ProviderSummary`
- `provider_id: str`, `provider_name: str`, `total_slots: int`, `connected_count: int`, `online_count: int`
- `auth_required_count: int`, `quota_exhausted_count: int`, `cold_spare_count: int`
- `discovered_models: List[str]`, `last_refresh_at: str`

---

## 7. EventBus Event Catalog & Payloads

Subscribers register with `EventBus.get().subscribe(event_name, callback)`:

| Event Constant | Name String | Payload Schema | Trigger Condition |
|---|---|---|---|
| `EVENT_ACCOUNT_UPDATED` | `"ACCOUNT_UPDATED"` | `{"provider": str, "profile_id": str, "profile": ProfileViewModel}` | Single profile auth, role, or state changed |
| `EVENT_ACCOUNT_ADDED` | `"ACCOUNT_ADDED"` | `{"provider": str, "profile_id": str}` | New account authorized / connected |
| `EVENT_ACCOUNT_REMOVED` | `"ACCOUNT_REMOVED"` | `{"provider": str, "profile_id": str}` | Account removed / disconnected |
| `EVENT_ACCOUNT_AUTH_CHANGED` | `"ACCOUNT_AUTH_CHANGED"` | `{"provider": str, "profile_id": str, "auth_state": str}` | Token expired or auth invalidated |
| `EVENT_QUOTA_UPDATED` | `"QUOTA_UPDATED"` | `{"provider": str, "profile_id": str, "snapshot": QuotaSnapshot}` | Single account quota changed (429 or refresh) |
| `EVENT_QUOTA_STALE` | `"QUOTA_STALE"` | `{"provider": str, "profile_id": str}` | Quota snapshot expired |
| `EVENT_PROVIDER_HEALTH_CHANGED` | `"PROVIDER_HEALTH_CHANGED"` | `{"provider": str, "summary": ProviderSummary}` | Aggregate provider health shift |
| `EVENT_ROUTING_UPDATED` | `"ROUTING_UPDATED"` | `{"role_id": str, "pipeline": RolePipeline}` | Active role routing modified |
| `EVENT_ROUTING_SLOT_UPDATED` | `"ROUTING_SLOT_UPDATED"` | `{"role_id": str, "node": PipelineNode}` | Failover occurred to backup node |
| `EVENT_AGENT_UPDATED` | `"AGENT_UPDATED"` | `{"role_id": str, "agent": AgentViewModel}` | Agent role status changed |
| `EVENT_SYSTEM_READINESS_CHANGED`| `"SYSTEM_READINESS_CHANGED"`| `{"readiness": SystemReadiness}` | Global readiness level shifted |
| `EVENT_REFRESH_STARTED` | `"REFRESH_STARTED"` | `{"scope": str, "provider": Optional[str], "seq": int}` | Background refresh task started |
| `EVENT_REFRESH_COMPLETED` | `"REFRESH_COMPLETED"` | `{"scope": str, "provider": Optional[str], "seq": int}` | Background refresh task succeeded |
| `EVENT_REFRESH_FAILED` | `"REFRESH_FAILED"` | `{"scope": str, "provider": Optional[str], "error": str, "seq": int}` | Background refresh task failed |

---

## 8. Backend Gaps (Known Limitations & Gaps)

To maintain complete transparency and prevent UI fabrication:

1. **Live Quota Metrics:**
   - OpenAI, xAI, and Claude do not offer public standard REST endpoints for real-time per-second token balances on OAuth device tokens without dedicated organization admin keys.
   - Consequently, initial state reports `source="baseline"`, `is_estimated=True`, and percentages as `None`.
   - Quotas transition to `status="exhausted"`, `source="runtime_event"`, `is_estimated=False` with exact reset timers **only upon encountering real provider 429 responses** during runtime execution.
2. **Subscription Expiry Timestamps:**
   - `SubscriptionPlan.expires_at` and `renews_at` are populated when present in JWT claims (e.g. Google CloudCode / Anthropic JWT claims); otherwise they are `None`.
3. **Model Discovery:**
   - Static default fallback models are provided when offline or before the first CLI invocation.