hermes-agent/tui_gateway/contracts/config_free_tier_control.py

696 lines
24 KiB
Python

"""Contracts: config, setup readiness, free tier, model inventory, connectors, diagnostics,
image generation and structured session control.
Handlers: ``tui_gateway/methods_config.py`` (``config.get``, ``setup.*``, ``diagnostics.share_nous``),
``methods_config_set.py`` (``config.set``), ``methods_free_tier.py``, ``methods_shared_metrics.py``,
``methods_complete.py``
(``model.options``), ``methods_connectors.py``, ``methods_images.py``, ``methods_session_control.py``
and ``methods_session.py`` (``verification.status``).
"""
from __future__ import annotations
from typing import Literal
from pydantic import Field
from .base import JsonValue, Params, Result, WireEnum
from .common import OkResult, OpenModel, ProfileParams, SessionLiveInfo
from .registry import method
# ── config.get ────────────────────────────────────────────────────────────────────────────────
class ConfigGetParams(ProfileParams):
"""``key`` selects one getter from ``_CONFIG_GETTERS``; ``cwd`` feeds the ``project`` getter,
``session_id`` lets ``reasoning`` / ``fast`` answer with the session's live pin."""
key: str
cwd: str | None = None
session_id: str | None = None
class ConfigProviderRef(OpenModel):
"""``hermes_cli/models.py::list_available_providers`` row."""
id: str
label: str
aliases: list[str] = Field(default_factory=list)
authenticated: bool = False
class ConfigGetResult(Result):
"""Union of every getter's payload: ``value`` for the simple words, ``config`` for ``full``,
``mtime`` / ``mcp_rev`` for the poller, ``model`` / ``provider`` / ``providers`` for ``provider``,
``home`` / ``display`` for ``profile``, ``cwd`` / ``branch`` for ``project``, ``prompt``."""
value: str | None = None
display: str | None = None
tool_progress: str | None = None
model: str | None = None
provider: str | None = None
providers: list[ConfigProviderRef] | None = None
home: str | None = None
cwd: str | None = None
branch: str | None = None
config: dict[str, JsonValue] | None = None
prompt: str | None = None
mtime: float | None = None
mcp_rev: str | None = None
method("config.get", params=ConfigGetParams, result=ConfigGetResult,
doc="Read one normalised config value (or the whole effective config) the way the UIs render it.")
# ── config.set ────────────────────────────────────────────────────────────────────────────────
class ConfigSetScope(WireEnum):
session = "session"
global_ = "global"
once = "once"
class ConfigSetParams(ProfileParams):
"""``key`` picks the setter (``_CONFIG_SETTERS``, ``details_mode.<section>``, display toggles);
``value`` is the raw word/string the setter normalises (falsy non-strings are reported back in
the error). ``scope`` applies to ``yolo`` / ``reasoning``; ``confirm_expensive_model`` to ``model``."""
key: str
value: JsonValue = ""
session_id: str | None = None
scope: str | None = None
confirm_expensive_model: bool = False
class ConfigSetResult(Result):
"""``{key, value}`` plus the setter's extras: model switches add ``warning`` /
``confirm_required`` / ``confirm_message`` / ``scope`` / ``deferred``; ``focus`` adds
``tool_progress``; ``cwd`` adds ``cwd`` / ``branch``; ``personality`` adds ``history_reset`` /
``info``; ``yolo`` reports its ``scope``. ``value`` is a bool only for the display toggles."""
key: str
value: str | bool | None = None
warning: str | None = None
confirm_required: bool | None = None
confirm_message: str | None = None
scope: str | None = None
deferred: bool | None = None
tool_progress: str | None = None
cwd: str | None = None
branch: str | None = None
history_reset: bool | None = None
info: SessionLiveInfo | None = None
method("config.set", params=ConfigSetParams, result=ConfigSetResult,
doc="Change one config key (persisted or session-scoped) and read back the normalised value.")
# ── setup readiness ───────────────────────────────────────────────────────────────────────────
class SetupStatusResult(Result):
"""``provider_configured`` is the loose answer; the boot record's fields (``ready``,
``free_tier_account``, ``free_tier_route``, ``other_providers``, ``inference_provider``) ride along
on the launch profile. An unknown ``profile`` answers ``ok=False`` + ``error``."""
provider_configured: bool | None = None
ready: bool | None = None
free_tier_account: bool | None = None
free_tier_route: bool | None = None
other_providers: bool | None = None
inference_provider: str | None = None
profile: str | None = None
ok: bool | None = None
error: str | None = None
error_code: str | None = None
retryable: bool | None = None
retry_after: int | None = None
method("setup.status", params=ProfileParams, result=SetupStatusResult,
doc="Loose provider check: is ANY provider auth state discoverable for the (launch or named) profile.")
class SetupRuntimeCheckParams(ProfileParams):
provider: str | None = None
class SetupRuntimeCheckResult(Result):
"""``ok=False`` + ``error`` when the resolved model can't be served; ``free_tier_route`` says the
selected route is the welcome host."""
ok: bool
provider: str | None = None
model: str | None = None
source: str | None = None
error: str | None = None
free_tier_route: bool | None = None
profile: str | None = None
method("setup.runtime_check", params=SetupRuntimeCheckParams, result=SetupRuntimeCheckResult,
doc="Strict provider check through the same runtime resolution the agent uses on session creation.")
# ── diagnostics.share_nous ────────────────────────────────────────────────────────────────────
class DiagnosticsShareNousParams(Params):
error_context: str | None = None
extra_files: dict[str, str] | None = None
log_lines: int | None = None
class DiagnosticsShareNousResult(Result):
"""Structured envelope: ``ok=False`` + ``error`` renders inline instead of failing the RPC."""
ok: bool
view_url: str | None = None
upload_id: str | None = None
expires_at: str | None = None
error: str | None = None
method("diagnostics.share_nous", params=DiagnosticsShareNousParams, result=DiagnosticsShareNousResult,
doc="Upload a force-redacted debug bundle to Nous-internal diagnostics storage.")
# ── free tier ─────────────────────────────────────────────────────────────────────────────────
class FreeTierStatusResult(Result):
"""``available`` = an identity exists AND the tier is on; whether inference runs on it is
``setup.runtime_check.free_tier_route``'s question."""
has_guest: bool
enabled: bool
available: bool
notice_pending: bool
model: str
label: str
error: str | None = None
error_code: str | None = None
retryable: bool | None = None
retry_after: int | None = None
method("free_tier.status", params=ProfileParams, result=FreeTierStatusResult,
doc="Pure read of the focused profile's free-tier identity state (no network, no side effects).")
class FreeTierProvisionResult(Result):
has_guest: bool
enabled: bool
error: str | None = None
error_code: str | None = None
retryable: bool | None = None
retry_after: int | None = None
method("free_tier.provision", params=ProfileParams, result=FreeTierProvisionResult,
doc="Explicit retry of the free-tier identity mint when the boot bootstrap could not create it.")
class FreeTierAckNoticeResult(Result):
acked: bool
method("free_tier.ack_notice", params=ProfileParams, result=FreeTierAckNoticeResult,
doc="Mark the one-time availability notice as shown on the free-tier identity.")
# ── shared metrics consent ────────────────────────────────────────────────────────────────────
class SharedMetricsConsentResult(Result):
"""The focused profile's ``telemetry.shared_metrics`` opt-ins. ``send`` is never true while
``enabled`` is false; ``decided`` = either key is written in config.yaml (the shipped defaults
are not an answer)."""
enabled: bool
send: bool
decided: bool
method("shared_metrics.status", params=ProfileParams, result=SharedMetricsConsentResult,
doc="Pure read of the focused profile's shared-metrics opt-ins (collection, upload, answered).")
class SharedMetricsSetParams(ProfileParams):
"""``send`` is ignored unless ``enabled``; ``first_run`` marks the Desktop first-run answer."""
enabled: bool
send: bool = False
first_run: bool = False
method("shared_metrics.set", params=SharedMetricsSetParams, result=SharedMetricsConsentResult,
doc="Write both shared-metrics opt-ins at once (send requires collection) and reconcile consent windows.")
class SharedMetricsSlashCommandParams(ProfileParams):
"""``command`` is the raw typed name (no leading ``/``, no args); the backend canonicalizes it
against the published registry. ``session_id`` scopes the count to that session's profile."""
command: str
session_id: str | None = None
class SharedMetricsSlashCommandResult(Result):
ok: bool
method("shared_metrics.slash_command", params=SharedMetricsSlashCommandParams,
result=SharedMetricsSlashCommandResult,
doc="Count one user-typed slash command (fire-and-forget; a no-op unless shared metrics are on).")
class SharedMetricsStartupLatencyParams(ProfileParams):
"""``elapsed_ms`` = the client's own launch (TUI process start / Desktop app start) to ready
(TUI gateway ready / Desktop backend attached), measured once per launch by the client. The
client names its surface because a Desktop may attach to a URL/cloud backend where
``HERMES_DESKTOP`` is unset; without it the backend falls back to its own client detection.
``launch_id`` is an opaque per-launch token the backend latches on (never recorded), so a
reconnect re-sending the same launch counts once while a new launch counts again."""
elapsed_ms: float
surface: Literal["desktop_attach", "tui"] | None = None
launch_id: str | None = None
class SharedMetricsStartupLatencyResult(Result):
ok: bool
method("shared_metrics.startup_latency", params=SharedMetricsStartupLatencyParams,
result=SharedMetricsStartupLatencyResult,
doc="Record one client launch-to-ready latency (fire-and-forget; a no-op unless shared metrics are on).")
# ---- v4 reliability ----
class SharedMetricsUpdateRunParams(ProfileParams):
"""One Desktop PACKAGED self-update (electron-updater / App Installer / Store). Source-checkout
hand-offs run ``hermes update`` and are counted from its receipt, never here. Raw words; the
backend buckets them: ``outcome`` success|failed|noop|refused, ``failed_stage``
download|verify|apply|restart, ``mechanism`` the updater strategy kind, ``duration_ms`` wall
time, ``from_commit_date`` the updated-from build's commit time (epoch seconds) when known."""
outcome: str
failed_stage: str | None = None
mechanism: str | None = None
duration_ms: float | None = None
from_commit_date: float | None = None
class SharedMetricsUpdateRunResult(Result):
ok: bool
method("shared_metrics.update_run", params=SharedMetricsUpdateRunParams, result=SharedMetricsUpdateRunResult,
doc="Count one Desktop packaged self-update outcome (fire-and-forget; a no-op unless shared metrics are on).")
# ---- end v4 reliability ----
# ---- v5 desktop ----
class SharedMetricsDesktopFeatureUseParams(ProfileParams):
"""``area`` is a Desktop surface id (``command_palette``, ``terminal_pane``, ``settings_<view>`` …);
the backend collapses anything outside its closed set to ``other``."""
area: str
method("shared_metrics.desktop_feature_use", params=SharedMetricsDesktopFeatureUseParams,
result=OkResult,
doc="Count one Desktop area used today (fire-and-forget; once per area per UTC day; a no-op unless on).")
class SharedMetricsDesktopFrictionParams(ProfileParams):
"""``kind`` notice_dismissed|error_toast|renderer_crash|backend_disconnect|slow_frame; ``detail`` a
closed code-defined word for that kind (notice id, error category, crash reason, drop reason, frame
duration bucket), never message text."""
kind: str
detail: str
method("shared_metrics.desktop_friction", params=SharedMetricsDesktopFrictionParams,
result=OkResult,
doc="Count one Desktop friction event (fire-and-forget; capped per day; a no-op unless on).")
class SharedMetricsDesktopOnboardingParams(ProfileParams):
"""``step`` a Desktop first-run step id; ``event`` reached|completed|abandoned."""
step: str
event: str
method("shared_metrics.desktop_onboarding", params=SharedMetricsDesktopOnboardingParams,
result=OkResult,
doc="Count one Desktop first-run step transition (fire-and-forget; once per step+event; a no-op unless on).")
class SharedMetricsDesktopDislikeParams(ProfileParams):
"""``signal`` quick_close|cancelled|setting_off_default|rage_click|undo|feature_disabled; ``target`` a
closed code-defined id for that signal (area, flow, action, undo path, feature toggle); ``setting`` a
config key for setting_off_default only (the value is never sent — the backend compares it to the
default)."""
signal: str
target: str = ""
setting: str | None = None
method("shared_metrics.desktop_dislike", params=SharedMetricsDesktopDislikeParams,
result=OkResult,
doc="Count one Desktop dislike signal (fire-and-forget; capped per signal per day; a no-op unless on).")
class SharedMetricsDesktopModeDay(Params):
mode: Literal["bots", "sessions"]
active_ms: float = 0
messages_sent: int = 0
class SharedMetricsDesktopActionDay(Params):
action: str
via: Literal["click", "menu", "palette", "shortcut"]
count: int
class SharedMetricsDesktopDailyParams(ProfileParams):
"""One finished UTC day of Desktop use, aggregated on the client. ``day`` (YYYY-MM-DD) only latches
a resend and is never recorded; the raw counts are bucketed by the backend."""
day: str
bot_count: int = 0
modes: list[SharedMetricsDesktopModeDay] = Field(default_factory=list)
actions: list[SharedMetricsDesktopActionDay] = Field(default_factory=list)
class SharedMetricsDesktopDailyResult(Result):
recorded: bool
method("shared_metrics.desktop_daily", params=SharedMetricsDesktopDailyParams,
result=SharedMetricsDesktopDailyResult,
doc="Record one finished Desktop day (mode use + button presses); recorded=false keeps it for a retry.")
# ---- end v5 desktop ----
# ── model.options ─────────────────────────────────────────────────────────────────────────────
class ModelOptionsParams(ProfileParams):
session_id: str | None = None
explicit_only: bool = False
include_unconfigured: bool = False
refresh: bool = False
# TODO(common): ModelPricing / ModelCapabilities / ModelOptionProvider are also the row shape of
# ``model.save_key``'s ``provider`` — the parent consolidates into contracts/common.py.
class ModelPricing(Result):
"""``hermes_cli/inventory.py::_apply_pricing`` — formatted $/Mtok strings (``""`` unknown,
``"free"``); the sale fields are Nous Portal-only."""
input: str
output: str
cache: str | None = None
free: bool
discount_percent: int | None = None
was_input: str | None = None
was_output: str | None = None
class ModelCapabilities(Result):
"""``hermes_cli/inventory.py::_apply_capabilities``."""
fast: bool
reasoning: bool
can_disable_reasoning: bool | None = None
class ModelOptionProvider(OpenModel):
"""One ``hermes_cli/inventory.py::build_models_payload`` provider row (the union of every field
the builder sets; ``pricing_pending`` / ``free_tier_pending`` mark the cached-only path)."""
slug: str
name: str
models: list[str] = Field(default_factory=list)
total_models: int | None = None
is_current: bool | None = None
is_user_defined: bool | None = None
source: str | None = None
aliases: list[str] | None = None
api_url: str | None = None
auth_type: str | None = None
authenticated: bool | None = None
key_env: str | None = None
warning: str | None = None
featured_models: list[str] | None = None
capabilities: dict[str, ModelCapabilities] | None = None
pricing: dict[str, ModelPricing] | None = None
pricing_pending: bool | None = None
free_tier: bool | None = None
free_tier_pending: bool | None = None
free_tier_row: bool | None = None
unavailable_models: list[str] | None = None
class ModelOptionsResult(Result):
providers: list[ModelOptionProvider]
model: str = ""
provider: str = ""
method("model.options", params=ModelOptionsParams, result=ModelOptionsResult,
doc="Provider/model inventory for the picker, layered over the session's live provider when given.")
# ── image.generate ────────────────────────────────────────────────────────────────────────────
class ImageGenerateParams(Params):
prompt: str | None = None
aspect_ratio: str | None = None
probe: JsonValue | None = None # truthy word/flag: availability check only
max_bytes: int | None = None
class ImageGenerateResult(Result):
"""``probe`` answers ``{available}`` alone; ``image_data`` (data URL) is omitted when the
download failed or exceeded ``max_bytes`` so callers fall back to ``image``."""
available: bool
success: bool | None = None
image: str | None = None
image_data: str | None = None
error: str | None = None
method("image.generate", params=ImageGenerateParams, result=ImageGenerateResult,
doc="Generate an image through the tool's provider dispatcher and hand the renderer a data URL.")
# ── session.control ───────────────────────────────────────────────────────────────────────────
class GoalContractSnapshot(Result):
"""``hermes_cli/goals.py::GoalContract.to_dict``."""
outcome: str = ""
verification: str = ""
constraints: str = ""
boundaries: str = ""
stop_when: str = ""
class GoalGateSnapshot(Result):
command: str
timeout_seconds: int
max_retries: int
attempts: int
last_exit_code: int | None = None
class WaitBarrierUntil(Result):
type: Literal["until"]
until_at: float
reason: str = ""
class WaitBarrierTarget(Result):
type: Literal["session", "pid"]
target: str | int
reason: str = ""
class GoalSnapshot(Result):
"""``methods_session_control.py::_safe_goal_snapshot`` — the frontend-safe GoalState subset."""
title: str
status: str
turns_used: int
max_turns: int
contract: GoalContractSnapshot
subgoals: list[str]
gates: list[GoalGateSnapshot]
created_at: float | None = None
updated_at: float | None = None
paused_reason: str | None = None
last_verdict: str | None = None
last_reason: str | None = None
wait_barrier: WaitBarrierUntil | WaitBarrierTarget | None = Field(default=None, discriminator="type")
class LoopSnapshot(Result):
"""``_safe_loop_snapshot`` — persisted LoopState fields, never its route."""
prompt: str
status: str
mode: str
interval_seconds: float
current_delay: float
times: int
until: str
max_ticks: int
ticks_fired: int
created_at: float
last_fired_at: float
next_due_at: float
awaiting_response: bool
deferred_by_goal: bool
paused_reason: str | None = None
last_stop_reason: str | None = None
class HeartbeatSnapshot(Result):
prompt: str
status: str
interval_seconds: int
created_at: float
last_fired_at: float
fire_count: int
class SessionControlSnapshot(Result):
"""``_snapshot_control`` — ``revision`` is a hash of the visible state (``""`` when empty);
``updated_at`` is the newest persisted timestamp (``0`` when none)."""
goal: GoalSnapshot | None
loop: LoopSnapshot | None
heartbeat: HeartbeatSnapshot | None
revision: str
updated_at: float
class SessionControlReadParams(ProfileParams):
session_id: str
class SessionControlReadResult(Result):
control: SessionControlSnapshot
method("session.control.read", params=SessionControlReadParams, result=SessionControlReadResult,
doc="Stable, allowlisted snapshot of one live session's goal / loop / heartbeat state.")
class SessionControlAction(WireEnum):
goal_pause = "goal.pause"
goal_resume = "goal.resume"
goal_clear = "goal.clear"
goal_unwait = "goal.unwait"
loop_pause = "loop.pause"
loop_resume = "loop.resume"
loop_stop = "loop.stop"
subgoal_add = "subgoal.add"
subgoal_remove = "subgoal.remove"
subgoal_clear = "subgoal.clear"
heartbeat_pause = "heartbeat.pause"
heartbeat_resume = "heartbeat.resume"
heartbeat_clear = "heartbeat.clear"
class SessionControlArgs(Params):
"""``subgoal.add`` reads ``text``; ``subgoal.remove`` reads the 1-based ``index``."""
text: str | None = None
index: int | None = None
class SessionControlParams(ProfileParams):
"""``action`` is validated by the handler (unknown / gate actions answer ``4004``), so it stays a
string on the wire; ``SessionControlAction`` lists the accepted set."""
session_id: str
action: str
args: SessionControlArgs | None = None
class SessionControlDispatch(Result):
"""``_dispatch_envelope`` — the command result's user-visible envelope, every key always present."""
type: str | None
output: str | None
notice: str | None
message: str | None
display: str | None
class SessionControlResult(Result):
control: SessionControlSnapshot
dispatch: SessionControlDispatch
method("session.control", params=SessionControlParams, result=SessionControlResult,
doc="Run one allowlisted goal / loop / subgoal / heartbeat action and return the exact resulting snapshot.")
# ── verification.status ───────────────────────────────────────────────────────────────────────
class VerificationStatusParams(ProfileParams):
session_id: str | None = None
session_key: str | None = None
cwd: str | None = None
class VerificationEvidenceRow(OpenModel):
"""One ``verification_events`` row (``agent/verification_evidence.py``)."""
id: int | None = None
created_at: str | None = None
session_id: str | None = None
cwd: str | None = None
root: str | None = None
command: str | None = None
canonical_command: str | None = None
kind: str | None = None
scope: str | None = None
status: str | None = None
exit_code: int | None = None
output_summary: str | None = None
class VerificationStatusInfo(Result):
"""``verification_status()``: ``disabled`` / ``not_applicable`` / ``unverified`` / ``stale`` or the
latest event's own status; ``root`` and friends only once a workspace was identified."""
status: str
evidence: VerificationEvidenceRow | None = None
root: str | None = None
session_id: str | None = None
changed_paths: list[str] | None = None
class VerificationStatusResult(Result):
verification: VerificationStatusInfo
method("verification.status", params=VerificationStatusParams, result=VerificationStatusResult,
doc="Best known verification evidence for a cwd/session; read-only, never runs checks.")