182 lines
13 KiB
Markdown
182 lines
13 KiB
Markdown
# 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.
|