hermes-hub/docs/UI_STATE_CONTRACT.md

Hermes Hub UI state contract

• Contract version: 1.0
• Published against: f171a8069d97aef5d3a45f838daed63abf2e69c1
• Contract owner: antigravity/state-layer
• Consumer: codex/ui-redesign

This document describes the backend state that the native UI may render. It is descriptive of the code at the published commit, not of intended future data. Fields marked real are backed by persisted configuration, authentication metadata, runtime health or provider responses. Fields marked derived are computed from real fields. Fields marked estimated or placeholder must be labelled as such or hidden by the UI.

1. Snapshot boundary

HubSnapshot

Defined in router/state_store.py as a frozen dataclass.

Field	Type	Reality and meaning
generation	int	Real local sequence. Monotonically increases for every accepted rebuild within one process. Starts at 1; an empty bootstrap snapshot uses 0.
timestamp	float	Real local time (time.time()) when the snapshot was built.
profiles_by_provider	dict[str, list[ProfileViewModel]]	Derived normalized profiles grouped by provider.
all_profiles	dict[str, ProfileViewModel]	Derived map keyed by profile_id. Profile IDs are assumed globally unique by this map.
readiness	SystemReadiness	Derived readiness summary.
agents	list[AgentViewModel]	Derived current role assignments.
providers	list[ProviderSummary]	Derived provider summaries.
routing	dict[str, RolePipeline]	Derived routing pipelines keyed by role ID.
quotas	dict[str, QuotaSnapshot]	Mixed. Keyed by profile_id; see provider truth matrix below.
metrics	dict[str, Any]	Real local diagnostics only: generation, build duration, profile counts and refresh counters. These are not provider throughput/error metrics.
is_stale	bool	True only for the empty bootstrap snapshot at this version. No age-based stale policy is implemented yet.

Consistency guarantees:

• The store publishes one snapshot reference after building it under an RLock; readers never observe the assignment half-complete.
• frozen=True prevents replacing dataclass attributes, but nested dicts, lists and contained models remain mutable. The snapshot is therefore shallowly immutable, not deeply immutable.
• generation is the UI comparison key. A public seq field does not exist in version 1.0.
• Scheduler request seq is internal to HubStateStore; stale requests are rejected when seq < _latest_applied_seq. The accepted seq is not exposed to the UI.
• get_snapshot() returns the cached snapshot; on first use it performs a non-forced state build.

2. Account and health models

ProfileViewModel

Field	Type	Optional	Reality and meaning
profile_id	str	no	Real configuration slot/profile ID.
display_name	str	no	Real configured name when present; otherwise a local fallback.
account_identity	str	no	Best available identifier: email → display name → provider account ID → profile ID. Real when auth metadata/JWT contains identity; fallback otherwise.
provider	str	no	Real normalized provider ID.
provider_display_name	str	no	Derived localized/display label.
assigned_roles	list[str]	no	Derived from router config. Includes primary/fallback annotations.
primary_role	str	yes	Derived/configured. May be absent.
is_main_account	bool	no	Real local profile preference.
is_main_orchestrator	bool	no	Derived from orchestrator chain.
auth_state	str	no	Normalized auth state; meanings below.
health_state	str	no	Normalized health state; meanings below.
health_label_ru	str	no	Derived presentation label.
model_states	dict[str, ModelFamilyHealth]	no	Derived from local health tracker/runtime observations. Empty if unobserved.
cooldown_remaining_sec	int	no	Derived local runtime state. Zero when unknown/not cooling down.
last_checked_at	str	yes	Real local check time string, not a provider timestamp.
enabled	bool	no	Real config state.
is_cold_spare	bool	no	Derived/configured.
is_empty_slot	bool	no	Derived placeholder slot with no configured auth.
email	str	logically yes	Real only if available from saved auth/JWT; empty string otherwise.
plan	str	logically yes	Display text. At version 1.0 several providers receive inferred defaults; UI must show only if plan_code != UNKNOWN and source is made trustworthy in a later contract revision.
plan_code	str	no	May be inferred (PRO, PLUS, MAX, etc.); not uniformly provider-confirmed.
quota_snapshot	QuotaSnapshot	yes	See quota matrix.
preferred_models	list[str]	no	Real config/model-discovery values when present.

auth_state values:

Value	Meaning
AUTHENTICATED	Saved authentication material passed the local presence/shape checks. It does not guarantee a fresh remote token check.
AUTH_REQUIRED	No usable saved authentication material is available.
AUTH_EXPIRED	Backend identified expired authentication. Not all providers can distinguish this from AUTH_REQUIRED.

health_state values:

Value	Meaning
healthy	Locally considered available.
quota_low	Local/provider quota evidence indicates a warning threshold.
quota_exhausted	Runtime/provider evidence indicates exhausted quota.
cooldown	Local health tracker has an active cooldown.
rate_limited	Runtime observed a rate limit.
not_configured	Empty slot/no account.
auth_required	Authentication missing.
auth_expired	Authentication expired when distinguishable.
disabled	Disabled in configuration.
cold_spare	Configured reserve not currently active.
unhealthy	Failure not represented by a more specific state.
not_tested	No usable health observation exists.

ModelFamilyHealth

family, display_name, status, status_label_ru are required derived fields. cooldown_remaining_sec defaults to 0. reset_at and reason are optional and exist only when the local health tracker recorded them.

3. Identity and plan provenance

AccountIdentity carries provider/profile ID, optional email, display name, provider account ID, organization, SubscriptionPlan, auth method, authenticated flag and local verification time.

Identity preference is contractual:

1. email;
2. display name/username;
3. provider account ID;
4. profile ID fallback.

The backend never exposes access tokens, refresh tokens, authorization codes or raw API keys through these ViewModels.

SubscriptionPlan.source may be provider_api, provider_auth, jwt_claim, inferred or unknown. At version 1.0 plan detection in AccountQuotaService._resolve_identity() assigns inferred provider defaults when explicit metadata is missing. Therefore the UI must hide a plan badge unless a later contract revision supplies trustworthy plan provenance alongside ProfileViewModel.

4. Quota models

QuotaSnapshot

Field	Type	Reality and meaning
account_id	str	Real local profile/account key.
provider	str	Real normalized provider ID.
buckets	list[QuotaBucket]	Separate pools; never combine them into one percent.
fetched_at	timezone-aware datetime	Real local collection time.
stale_after_seconds	int	Local cache TTL, default 300 seconds.
source	str	Provenance. baseline, estimated, unconfigured, local_heuristic imply is_estimated=True.
unavailable_reason	Optional[str]	Human-readable reason when data cannot be collected.
is_estimated	property	Derived solely from source.

QuotaBucket

Field	Type	Notes
id	str	Stable bucket key.
display_name	str	User-facing label. This is the requested logical label.
model_family	Optional[str]	Family/pool selector when known.
used_percent	Optional[float]	0–100; reconciled from remaining percent when one side exists.
remaining_percent	Optional[float]	0–100; reconciled from used percent when one side exists.
used_absolute	Optional[int]	Requested logical used.
remaining_absolute	Optional[int]	Absolute remaining quantity.
limit_absolute	Optional[int]	Requested logical limit.
reset_at	Optional[datetime]	Reset time if measured or estimated.
reset_in_seconds	Optional[int]	Relative reset duration if known.
period	Optional[str]	5h, 7d, 30d, sliding, or provider-specific.
status	str	healthy, warning, exhausted, unknown; derived from remaining values where available.

Requested fields unit and scope do not exist in version 1.0. The closest available fields are absolute-value semantics implied by the provider and model_family/period. The UI must not invent units.

Provider truth matrix at contract version 1.0

Provider	Buckets emitted	Values	Reset	Source / UI treatment
Antigravity	Claude 5h, Claude Weekly, Gemini 5h, Gemini Weekly	Percent/absolute values are absent	Locally projected +5h/+7d	baseline; estimated, label explicitly. No live provider quota call.
OpenAI Codex	Session, Weekly	Values absent	Locally projected +5h/+7d	baseline; estimated.
OpenCode Go	Sliding, Weekly, Monthly	Values absent	Weekly/monthly locally projected; sliding reset absent	baseline; estimated.
Claude	Current session, Current week	Values absent	Locally projected +5h/+7d	baseline; estimated.
Grok	Weekly, GrokChat, GrokBuild, frequent tasks, normal tasks	Usage/remaining absent. Task limits 10/30 are static placeholders.	Mostly absent	baseline; estimated.
Unknown provider	One default bucket	Values and reset absent	absent	baseline; estimated.
Unconfigured account	No buckets	no data	absent	unconfigured; show unavailable reason.

Runtime 429 handling may set one matching bucket to 100% used / 0% remaining with a locally assumed reset duration. This is real evidence of exhaustion but the reset time remains estimated.

5. Team and routing models

AgentViewModel

Required fields: role ID/name/description, optional assigned profile ID and display name, provider ID/display name, model, account identity, routing position, status/status label, active flag and orchestrator flag. cooldown_remaining_sec is derived local runtime state.

Reality notes:

• role/profile chain comes from router configuration;
• the selected model is the first preferred model or the string default;
• active selection is the first healthy profile in the chain;
• there is no active-session field and no per-agent quota field in version 1.0.

RolePipeline

Fields: role_id, role_name_ru, default_model, max_failover, session_affinity, active_profile_id, nodes.

Each PipelineNode contains profile ID, display name, provider display name, model, health status/label, active flag and cooldown seconds. Node order is the configured primary → fallback order. The first healthy node is marked active.

Version 1.0 does not include account identity, quota snapshot/status or a failover reason in each node. The UI may show the order and health but must not invent why a switch happened.

ProviderSummary

Contains provider ID/name; total, connected, online, auth-required, quota-exhausted and cold-spare counts; discovered model names; and a local last refresh time string. Counts are derived from ProfileViewModel objects.

SystemReadiness

Contains state (healthy, limited, degraded, critical), localized title and summary, ready/total counts for roles, connected/total accounts, ready/total providers, and warning strings. All values are derived from the current local profile and routing state; they are not remote SLA metrics.

6. Event bus contract

Callbacks receive (event_name: str, payload: Any). Delivery is synchronous on the publishing thread unless the caller uses publish_to_ui(root, ...), which schedules through root.after(0, ...).

Event	Payload contract at v1.0	Emission status
ACCOUNT_UPDATED	{profile_id, profile, generation}	Emitted after targeted account delta rebuild when the profile exists.
ACCOUNT_ADDED	Intended {provider, profile_id, profile?, generation?}	Declared only; no canonical publisher yet.
ACCOUNT_REMOVED	Intended {provider, profile_id, generation?}	Declared only.
ACCOUNT_AUTH_CHANGED	Intended {provider, profile_id, auth_state, generation?}	Declared only.
QUOTA_UPDATED	{provider, profile_id, quota_snapshot}	Emitted by HubStateStore.apply_delta_quota_updated; generation absent. Collector listeners use a separate callback API.
QUOTA_STALE	Intended {provider, profile_id}	Declared only.
PROVIDER_HEALTH_CHANGED	Intended provider summary/delta	Declared only.
ROUTING_UPDATED	Intended {role_id, pipeline, reason?, generation?}	Declared and consumed by UI, but no canonical backend publisher.
ROUTING_SLOT_UPDATED	Intended targeted role/slot delta	Declared only.
AGENT_UPDATED	Intended {role_id, agent, generation?}	Declared only.
SYSTEM_READINESS_CHANGED	SystemReadiness object	Emitted after every accepted full rebuild.
REFRESH_STARTED	{key, seq}	Emitted by scheduler before a task.
REFRESH_COMPLETED	{generation, duration_ms}	Emitted by state store after rebuild.
REFRESH_FAILED	{key, error}	Emitted by scheduler on failure. Error text must already be secret-safe.

Quota/account events are intended to update one stable UI widget keyed by profile_id; they must not be treated as instructions to reconstruct every account card.

7. Backend gaps

The following cannot be honestly implemented by UI code alone:

1. No provider currently supplies live numeric quota values through AccountQuotaService; every configured-provider collector returns baseline buckets.
2. Antigravity bucket separation exists structurally, but the four values and reset times are not measured from provider responses.
3. HubSnapshot has no public request seq; it exposes only generation.
4. Snapshot immutability is shallow.
5. is_stale has no age/source policy beyond the empty bootstrap snapshot.
6. Plan provenance is not carried into ProfileViewModel; inferred plans cannot be distinguished safely by the UI.
7. AgentViewModel lacks active session and quota data.
8. PipelineNode lacks account identity, quota state and failover reason.
9. Most targeted event constants are declared but have no canonical publisher.
10. Single/all scheduler triggers start nested asynchronous quota workers and may rebuild state before those quota workers finish.
11. Stale-response protection records seq before the slow work is complete, so the current implementation does not fully prove that a late result can never overwrite a newer result.
12. Provider latency, RPS, error percentage, costs and remote SLA are absent. The UI must display Н/Д or omit those blocks.

Any contract extension must update this document and identify the implementing commit before UI code relies on the new fields.