anon_auth.py 60 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152
  1. """Nous free-tier identity: the ``anonymous`` auth method of the ``nous`` provider.
  2. The identity is created in two places: by the desktop's first install, which claims the welcome
  3. trial (``hermes_cli.welcome_trial``), and on the first hosted connector action for anyone without a
  4. Nous identity (``tools.connectors.gateway.config.ensure_guest_identity``, gated by ``guest_allowed``).
  5. Either mints an anonymous Nous account (``POST /api/anonymous/create``); its ``anon_`` credential is
  6. later exchanged for short-lived JWTs (``POST /api/anonymous/token``). The result is persisted as the
  7. singleton ``providers.nous``. Only a guest stamped with the trial claim carries inference
  8. (:func:`free_inference_active`), on every surface of the install once the desktop claimed it: chats,
  9. cron, side agents, workers, the CLI. Every other guest serves connectors and managed tools. In the resolver ladder (``resolve_provider``) a guest that
  10. carries inference sits directly above the implicit AWS Bedrock chain (NS-829): any explicit provider
  11. (env key, ``model.provider``, OpenRouter pool, a logged-in ``active_provider``) beats it, and the
  12. ladder never creates one.
  13. Only two mechanics differ from an OAuth login and both are isolated behind ``is_guest_state``:
  14. token acquisition (re-exchange the ``anon_`` credential; there is no refresh token) and routing
  15. (the welcome inference host, single model ``nous/welcome``).
  16. Users are never shown the words guest / anonymous / account for this state: surfaces say
  17. "Nous · free tier". Two user-facing verbs reach the same flow, both keeping the identity's
  18. connectors: ``hermes auth upgrade`` in a terminal and ``/login`` inside a chat.
  19. Lifecycle lives in ONE primitive, :func:`_reconcile_and_provision`: adopt what the shared store already
  20. holds, else mint under the shared-store lock. :func:`ensure_portal_identity` (connectors) and the
  21. welcome-trial claim are its only callers; nothing else calls :func:`mint_guest`.
  22. """
  23. from __future__ import annotations
  24. import logging
  25. import math
  26. import os
  27. import time
  28. from dataclasses import dataclass
  29. from datetime import datetime, timedelta, timezone, UTC
  30. from pathlib import Path
  31. from typing import Any, Callable, Dict, Optional
  32. from agent.retry_utils import parse_retry_after_seconds
  33. from hermes_cli.auth_constants import (
  34. AuthError, DEFAULT_NOUS_PORTAL_URL, DEFAULT_NOUS_WELCOME_URL, NOUS_INFERENCE_INVOKE_SCOPE, WELCOME_CLAIM_FLAG,
  35. _decode_jwt_claims, httpx)
  36. logger = logging.getLogger("hermes_cli.auth")
  37. ANON_AUTH_METHOD = "anonymous"
  38. ANON_CLIENT_ID = "nas-anonymous"
  39. ANON_ACCOUNT_TIER = "anonymous"
  40. GUEST_MODEL = "nous/welcome"
  41. ANON_SECRET_HEADER = "x-anonymous-api-secret"
  42. # The shared secret gates the anonymous surface during its integration phase. It is a deployment
  43. # secret (Sid's), read from the environment only.
  44. ANON_SECRET_ENV = "HERMES_ANON_API_SECRET"
  45. # Preview cohort for the free tier's connector set, sent once on account creation so the account
  46. # service can record it on the account. "1" / "true" send true and "0" / "false" send false; anything
  47. # else (unset included) omits the field and the service applies its default. Self-reported and
  48. # baked into desktop bundles in plain text: the service must treat it as a preference, never proof.
  49. PREVIEW_FULL_CONNECTORS_ENV = "HERMES_PREVIEW_FULL_CONNECTORS"
  50. GUEST_MINT_TIMEOUT_SECONDS = 5.0
  51. # Copy shared by every surface that names the free tier (R-USR-1): never guest / anonymous / account.
  52. FREE_TIER_LABEL = "Nous · free tier"
  53. UPGRADE_HINT = "Run `hermes auth upgrade` to sign in with a Nous account, or /login inside a chat."
  54. FREE_TIER_NOT_SIGNED_IN = (
  55. "You're not signed in. Free inference and connectors are always on. "
  56. "Run `hermes auth` to sign in with a Nous account.")
  57. class AnonCredentialDead(AuthError):
  58. """NAS no longer knows this ``anon_`` credential (reaped, or claimed into a real account).
  59. The one client rule for reap AND claim: mark dead, re-mint on the next need.
  60. """
  61. def _anon_err(message: str, code: str, *, retry_after: Optional[float] = None) -> AuthError:
  62. """An ``AuthError`` for a free-tier failure *code*; terminal-ness is the code's (``ANON_TERMINAL_CODES``)."""
  63. return AuthError(message, code=code, retry_after=retry_after, retryable=code not in ANON_TERMINAL_CODES)
  64. # --- Free-tier failure codes ------------------------------------------------------------------------
  65. #
  66. # Every way the account service (NAS) or the wire can refuse the free tier, as one ``AuthError.code``
  67. # each. Surfaces key their copy on the code; the message on the error is the surface-agnostic
  68. # fallback (no ``/login``, no ``hermes`` verb, no guest / anonymous / credential). ``retryable``
  69. # says whether a later attempt can succeed at all; ``retry_after`` is the wait the server named.
  70. #
  71. # What NAS actually sends (nous-account-service ``api/anonymous/gate.ts`` and the routes behind it):
  72. # 404 ``not_found`` the surface is not enabled on this deployment (terminal)
  73. # 503 ``temporarily_disabled`` the ops breaker is tripped (transient, no hint)
  74. # 429 ``temporarily_unavailable`` + Retry-After per-address / per-credential limits
  75. # 428 ``pow_required`` / ``pow_invalid`` / ``pow_replayed`` proof-of-work enforced (not implemented here)
  76. # 428 ``challenge_required`` + ``challenges[]`` a browser challenge first (``anon_challenge``)
  77. # 403 ``signin_required`` / ``access_denied`` this client is refused without an account
  78. # 404 ``unknown_token`` the credential was reaped or claimed (re-mint)
  79. # 403 ``account_locked`` the account is locked (dead; never re-mint from it)
  80. # 401 an outstanding JWT whose account is gone (re-mint)
  81. ANON_GATE_CLOSED = "anon_gate_closed" # not enabled here: sign in, or another provider
  82. ANON_GATE_PAUSED = "anon_gate_paused" # ops breaker: keep checking in the background
  83. ANON_RATE_LIMITED = "anon_rate_limited" # too many sign-ups / exchanges: wait Retry-After
  84. ANON_POW_REQUIRED = "anon_pow_required" # proof of work requested: deferred, sign in instead
  85. ANON_ACCOUNT_LOCKED = "anon_account_locked" # dead, and no replacement is minted from it
  86. ANON_CREDENTIAL_DEAD = "anon_credential_dead" # reaped or claimed: replaced silently, once
  87. ANON_UNREACHABLE = "anon_unreachable" # timeout, DNS, refused connection
  88. ANON_SERVER_ERROR = "anon_server_error" # 5xx, non-JSON, malformed success body
  89. ANON_CHALLENGE_REQUIRED = "anon_challenge_required" # a browser check is still pending (``anon_challenge``)
  90. ANON_SIGNIN_REQUIRED = "anon_signin_required" # refused without an account, or a 428 this version can't run
  91. # Codes a later attempt cannot fix (for this process / this version).
  92. ANON_TERMINAL_CODES = frozenset({
  93. ANON_GATE_CLOSED, ANON_POW_REQUIRED, ANON_ACCOUNT_LOCKED, ANON_SIGNIN_REQUIRED})
  94. # Codes that mean the account service itself is not answering: a sign-in (which goes through the
  95. # same service) cannot help either, so surfaces offer "try again" / "another provider" only.
  96. ANON_UNREACHABLE_CODES = frozenset({ANON_UNREACHABLE, ANON_SERVER_ERROR})
  97. # Copy per code: what happened, then the one honest way forward. The free MODEL is never "off":
  98. # what is unavailable is using Hermes without signing in, and signing in is free.
  99. _SIGNIN_IS_FREE = "Signing in is free."
  100. ANON_FAILURE_COPY = {
  101. ANON_GATE_CLOSED: f"This version can't be used without a Nous account. {_SIGNIN_IS_FREE}",
  102. ANON_GATE_PAUSED: f"Using Hermes without signing in is paused for a moment. {_SIGNIN_IS_FREE}",
  103. ANON_RATE_LIMITED: "Lots of people are getting started right now. Try again in {wait}. "
  104. "Signing in is free and skips the wait.",
  105. ANON_POW_REQUIRED: "The Nous server asked for a proof of work, but that isn't implemented in your "
  106. "Agent yet. Sign in with a Nous account to continue.",
  107. ANON_CHALLENGE_REQUIRED: "Finish the quick check in your browser, then try again.",
  108. ANON_SIGNIN_REQUIRED: "Free guest access isn't available here. Sign in with a Nous account to continue.",
  109. ANON_ACCOUNT_LOCKED: f"This session can't continue without signing in. {_SIGNIN_IS_FREE}",
  110. ANON_CREDENTIAL_DEAD: "Your session ended. A new one starts on its own.",
  111. ANON_UNREACHABLE: "The Nous service couldn't be reached. Check your internet connection and try again.",
  112. ANON_SERVER_ERROR: "The Nous service had a hiccup. Try again in a moment.",
  113. }
  114. def friendly_wait(seconds: Any) -> str:
  115. """A rounded, spoken duration for user copy: "a few seconds", "about a minute", "about 5 minutes",
  116. "about an hour". Never a raw second count."""
  117. try:
  118. s = max(0.0, float(seconds or 0))
  119. except (TypeError, ValueError):
  120. s = 0.0
  121. if s <= 15:
  122. return "a few seconds"
  123. if s < 90:
  124. return "about a minute"
  125. if s < 3600:
  126. return f"about {round(s / 60)} minutes"
  127. hours = round(s / 3600)
  128. return "about an hour" if hours <= 1 else f"about {hours} hours"
  129. def anon_failure_copy(code: str, *, retry_after: Any = None) -> str:
  130. """The surface-agnostic sentence for a free-tier failure *code* (``ANON_FAILURE_COPY``)."""
  131. template = ANON_FAILURE_COPY.get(code) or ANON_FAILURE_COPY[ANON_SERVER_ERROR]
  132. return template.format(wait=friendly_wait(retry_after if retry_after else 60))
  133. def guest_allowed() -> bool:
  134. """``nous.guest`` (default True) has not switched guests off: no connector guest, no trial."""
  135. try:
  136. from hermes_cli.config import load_config_readonly
  137. nous_cfg = load_config_readonly().get("nous")
  138. except Exception: # config unreadable: keep today's behaviour (no guest) rather than mint
  139. logger.debug("guest: config unreadable, treating nous.guest as false", exc_info=True)
  140. return False
  141. if not isinstance(nous_cfg, dict):
  142. return True
  143. return bool(nous_cfg.get("guest", True))
  144. def is_guest_state(state: Any) -> bool:
  145. return isinstance(state, dict) and state.get("auth_method") == ANON_AUTH_METHOD
  146. def is_anonymous_request(provider: Any, api_key: Any) -> bool:
  147. """Select anonymous error UX from the credential actually sent, never the saved profile or URL.
  148. This is display/recovery metadata, not token verification; the gateway authenticates the JWT.
  149. Named free accounts and opaque API keys must retain normal provider errors.
  150. """
  151. from hermes_cli.auth_constants import _decode_jwt_claims
  152. return provider == "nous" and _decode_jwt_claims(api_key).get("account_tier") == ANON_ACCOUNT_TIER
  153. def is_anonymous_agent(agent: Any) -> bool:
  154. """:func:`is_anonymous_request` for a live agent: read at call time, since the credential rotates."""
  155. return is_anonymous_request(getattr(agent, "provider", ""), getattr(agent, "api_key", None))
  156. def current_nous_state() -> Optional[dict[str, Any]]:
  157. """The profile's ``providers.nous`` state without locking or network (status/picker reads)."""
  158. from hermes_cli.auth import _load_auth_store, _load_provider_state
  159. try:
  160. return _load_provider_state(_load_auth_store(), "nous")
  161. except Exception as exc:
  162. logger.debug("guest: auth store unreadable: %s", exc)
  163. return None
  164. def has_guest() -> bool:
  165. return is_guest_state(current_nous_state())
  166. def on_local_desktop_backend() -> bool:
  167. """This activity is work for the Desktop app on this machine: a request from, or a turn of a chat
  168. created by, a connection ``process_identity.local_desktop_client`` accepted. Never an SSH, URL or
  169. cloud backend, a shell the desktop launched, or the gateway's other clients."""
  170. from hermes_cli.process_identity import serves_local_desktop_now
  171. return serves_local_desktop_now()
  172. def free_inference_active(state: Any = None) -> bool:
  173. """The welcome trial carries inference: a guest that claimed it and guests
  174. still allowed. Only the claim is the local Desktop's (``welcome_trial``); once claimed, every
  175. surface of the install runs on it. *state* defaults to the profile's."""
  176. state = current_nous_state() if state is None else state
  177. return is_guest_state(state) and state.get(WELCOME_CLAIM_FLAG) is True and guest_allowed()
  178. def trial_model() -> str:
  179. """The last rung of model resolution, below every model the user named (``model.default``, a cron
  180. or task pin): ``nous/welcome`` while the welcome trial carries inference, else ''. Never written to
  181. config.yaml, so it stops applying the moment the user configures a real model."""
  182. return GUEST_MODEL if free_inference_active() else ""
  183. def has_free_tier_account() -> bool:
  184. """True when the profile's Nous identity is a guest that carries inference here.
  185. Profile-level: use for status, picker and notice surfaces. Routing decisions (which model a
  186. request may carry) must use :func:`route_is_welcome_host` on the SELECTED runtime instead: a
  187. credential-pool entry can pick a paid Nous key while the profile singleton is still a guest.
  188. """
  189. return free_inference_active()
  190. def guest_without_free_tier(state: Any) -> bool:
  191. """A guest that does not carry inference here: it serves connectors and managed tools only, so
  192. inference, account and status readers treat the profile as not signed in."""
  193. return is_guest_state(state) and not free_inference_active(state)
  194. def free_tier_route() -> bool:
  195. from hermes_cli.auth import resolve_provider
  196. return has_free_tier_account() and resolve_provider("auto") == "nous"
  197. WELCOME_HOSTS = frozenset({"welcome-api.nousresearch.com"})
  198. # Dev-only: extra hostnames that count as the welcome host, comma-separated (for example
  199. # ``127.0.0.1`` while ``NOUS_INFERENCE_BASE_URL`` points at a local stand-in). Read from the
  200. # environment, which the user controls, so it sits at the same trust level as the URL override
  201. # itself; it never widens the NETWORK-side allowlist in ``auth_nous``.
  202. EXTRA_WELCOME_HOSTS_ENV = "HERMES_EXTRA_WELCOME_HOSTS"
  203. def welcome_hosts() -> frozenset[str]:
  204. """``WELCOME_HOSTS`` plus any ``HERMES_EXTRA_WELCOME_HOSTS`` entries (lowercased hostnames)."""
  205. raw = os.environ.get(EXTRA_WELCOME_HOSTS_ENV) or ""
  206. extra = {part.strip().lower() for part in raw.split(",") if part.strip()}
  207. return WELCOME_HOSTS | frozenset(extra) if extra else WELCOME_HOSTS
  208. def pin_model_for_route(provider: Any, base_url: Any, model: Any) -> Any:
  209. """Model policy at agent START: on the Nous welcome host the model is ``nous/welcome``; anywhere
  210. else the caller's model stands. Used once, when the route is first finalized. Mid-conversation
  211. route changes go through :func:`route_can_serve_model` instead: a conversation's model is never
  212. silently rewritten by a credential rotation.
  213. """
  214. if provider == "nous" and route_is_welcome_host(base_url):
  215. if model and model != GUEST_MODEL:
  216. logger.info("Nous free tier: using %s instead of configured model %s", GUEST_MODEL, model)
  217. return GUEST_MODEL
  218. return model
  219. def route_can_serve_model(provider: Any, base_url: Any, model: Any) -> bool:
  220. """Eligibility for a credential ROTATION: the welcome host serves only ``nous/welcome``, so a
  221. conversation on any other model must not be rotated onto it (and a ``nous/welcome`` conversation
  222. may move to the portal host, which serves it too). Non-Nous routes are always eligible."""
  223. if provider != "nous" or not route_is_welcome_host(base_url):
  224. return True
  225. return not model or model == GUEST_MODEL
  226. def route_is_welcome_host(base_url: Any) -> bool:
  227. """The routing predicate for the free tier: the welcome host serves exactly ``nous/welcome``.
  228. Keyed on the resolved endpoint, never on profile state, so a paid pool credential routed to the
  229. portal host keeps its model even when a guest singleton exists beside it.
  230. """
  231. from urllib.parse import urlparse
  232. try:
  233. host = (urlparse(str(base_url or "")).hostname or "").lower()
  234. except ValueError:
  235. return False
  236. return host in welcome_hosts()
  237. def on_free_model(agent: Any, base_url: Any) -> bool:
  238. """The request went to the free tier's host on a free-tier credential."""
  239. return route_is_welcome_host(base_url) and is_anonymous_agent(agent)
  240. def anon_secret() -> str:
  241. return (os.environ.get(ANON_SECRET_ENV) or "").strip()
  242. def _anon_headers() -> dict[str, str]:
  243. from hermes_cli.anon_challenge import user_agent
  244. headers = {"content-type": "application/json", "user-agent": user_agent()}
  245. if secret := anon_secret():
  246. headers[ANON_SECRET_HEADER] = secret
  247. return headers
  248. # (status, NAS ``error``) -> (exception class, code). ``None`` matches any error string for that
  249. # status; an exact pair wins over the wildcard. Anything unlisted is a server error.
  250. _NAS_REFUSALS: dict[tuple, tuple] = {
  251. (404, "unknown_token"): (AnonCredentialDead, ANON_CREDENTIAL_DEAD),
  252. (404, None): (AuthError, ANON_GATE_CLOSED), # uniform with a nonexistent route, on purpose
  253. (401, "invalid_shared_secret"): (AuthError, ANON_GATE_CLOSED), # pre-launch NAS builds only
  254. (401, None): (AnonCredentialDead, ANON_CREDENTIAL_DEAD),
  255. (403, "account_locked"): (AnonCredentialDead, ANON_ACCOUNT_LOCKED),
  256. (403, "anonymous_accounts_disabled"): (AuthError, ANON_GATE_PAUSED), # pre-launch names
  257. (403, "circuit_open"): (AuthError, ANON_GATE_PAUSED),
  258. (428, None): (AuthError, ANON_POW_REQUIRED),
  259. (429, None): (AuthError, ANON_RATE_LIMITED),
  260. (503, "temporarily_disabled"): (AuthError, ANON_GATE_PAUSED),
  261. }
  262. # An endpoint-specific verdict: builds the error from the refusal's JSON body.
  263. _Verdict = Callable[[dict[str, Any]], AuthError]
  264. def _raise_for_anon_status(
  265. response: httpx.Response, *, action: str, overrides: Optional[dict[tuple, _Verdict]] = None,
  266. ) -> dict[str, Any]:
  267. try:
  268. payload = response.json()
  269. except ValueError:
  270. payload = {}
  271. if not isinstance(payload, dict):
  272. payload = {}
  273. error = str(payload.get("error") or "")
  274. status = response.status_code
  275. if status in (200, 201):
  276. return payload
  277. if error.startswith("pow_"):
  278. error = "pow_" # pow_required / pow_invalid / pow_replayed are one verdict
  279. # An endpoint's own verdicts (same keys as ``_NAS_REFUSALS``) win over the table.
  280. if overrides:
  281. build = overrides.get((status, error)) or overrides.get((status, None))
  282. if build:
  283. raise build(payload)
  284. cls, code = (_NAS_REFUSALS.get((status, error)) or _NAS_REFUSALS.get((status, None))
  285. or ((AuthError, ANON_POW_REQUIRED) if error == "pow_" else (AuthError, ANON_SERVER_ERROR)))
  286. if code == ANON_SERVER_ERROR:
  287. logger.info("Nous free tier %s failed (%s%s)", action, status, f": {error}" if error else "")
  288. retry_after = parse_retry_after_seconds(response.headers)
  289. raise cls(anon_failure_copy(code, retry_after=retry_after), code=code, retry_after=retry_after,
  290. retryable=code not in ANON_TERMINAL_CODES)
  291. def mint_request_body() -> dict[str, Any]:
  292. """The ``/api/anonymous/create`` body: ``{"preview_full_connectors": bool}`` when the env var is
  293. ``1`` / ``true`` or ``0`` / ``false``, else ``{}``."""
  294. raw = (os.environ.get(PREVIEW_FULL_CONNECTORS_ENV) or "").strip()
  295. return {"preview_full_connectors": raw in ("1", "true")} if raw in ("1", "true", "0", "false") else {}
  296. def mint_guest(client: httpx.Client, portal_base_url: str) -> dict[str, Any]:
  297. """``POST /api/anonymous/create`` -> ``{user_id, org_id, token, idle_ttl_days}``. Token shown once."""
  298. response = client.post(
  299. f"{portal_base_url.rstrip('/')}/api/anonymous/create", headers=_anon_headers(), json=mint_request_body())
  300. payload = _raise_for_anon_status(response, action="sign-up")
  301. token = payload.get("token")
  302. if not isinstance(token, str) or not token.startswith("anon_"):
  303. logger.info("Nous free tier sign-up returned no credential")
  304. raise _anon_err(ANON_FAILURE_COPY[ANON_SERVER_ERROR], ANON_SERVER_ERROR)
  305. return payload
  306. # ``purpose: "connectors"`` (NAS hermes-portal#1516) mints a JWT whose only scope is
  307. # ``connectors:invoke``: connector routes and the tool gateway accept it, the welcome host refuses it,
  308. # and NAS never puts the free-inference challenge in front of it. A NAS from before #1516 ignores the
  309. # field and answers with an inference token (a superset), so which slot a token fills is read off its
  310. # ``scope`` claim, never off the purpose that asked for it.
  311. def is_connectors_only(token: Any) -> bool:
  312. """*token* carries a scope claim and it lacks ``inference:invoke`` (a scopeless JWT reads as today's)."""
  313. from hermes_cli.auth_nous import _scope_values
  314. claims = _decode_jwt_claims(token)
  315. scopes = _scope_values(claims.get("scope")) | _scope_values(claims.get("scp"))
  316. return bool(scopes) and NOUS_INFERENCE_INVOKE_SCOPE not in scopes
  317. def held_connectors_token(state: Any, *, skew_seconds: Optional[int] = None) -> Optional[str]:
  318. """The bearer a connectors / managed-tools call sends: the profile's token (for a guest the
  319. inference one, a superset), else a guest's connectors-only token, preferring one that outlives
  320. *skew_seconds*. ``None`` also accepts an expiring token (availability probes)."""
  321. from hermes_cli.auth import _is_expiring
  322. if not isinstance(state, dict):
  323. return None
  324. slots = (state, state.get("connectors_token") if is_guest_state(state) else None)
  325. held = [(s["access_token"], s.get("expires_at")) for s in slots
  326. if isinstance(s, dict) and isinstance(s.get("access_token"), str) and s["access_token"]]
  327. live = next((token for token, exp in held if not _is_expiring(exp, skew_seconds or 0)), None)
  328. return live or (held[0][0] if held and skew_seconds is None else None)
  329. def exchange_anon_jwt(
  330. client: httpx.Client, portal_base_url: str, anon_token: str, *, auth_state: dict[str, Any],
  331. purpose: str,
  332. ) -> dict[str, Any]:
  333. """``POST /api/anonymous/token {token}`` -> ``{access_token, expires_in, inference_base_url, ...}``.
  334. Raises :class:`AnonCredentialDead` on 404 ``unknown_token`` / 401 (reaped or claimed), and
  335. :class:`~hermes_cli.anon_challenge.AnonChallengeRequired` (carrying what the status poll needs:
  336. portal, credential, and the *auth_state* whose ``tls`` block the mint used) on a browser challenge.
  337. """
  338. from hermes_cli import anon_challenge
  339. response = client.post(
  340. f"{portal_base_url.rstrip('/')}/api/anonymous/token", headers=_anon_headers(),
  341. json={"token": anon_token, "client": anon_challenge.client_info(), "purpose": purpose})
  342. def challenge(body: dict[str, Any]) -> AuthError:
  343. return anon_challenge.challenge_error(
  344. body, portal_base_url=portal_base_url, anon_token=anon_token, auth_state=auth_state)
  345. def signin(body: dict[str, Any]) -> AuthError:
  346. # Refused without an account, or a 428 this version has no primitive for: either way the
  347. # honest way forward is a sign-in, in the service's own words when it sent some.
  348. return anon_challenge.signin_required_error(body.get("message"))
  349. def proof_of_work(_body: dict[str, Any]) -> AuthError:
  350. # The PoW verdict, kept out of the 428 sign-in catch-all below.
  351. return _anon_err(ANON_FAILURE_COPY[ANON_POW_REQUIRED], ANON_POW_REQUIRED)
  352. # The challenge gate sits on the token exchange only; every other endpoint keeps the table.
  353. payload = _raise_for_anon_status(response, action="token exchange", overrides={
  354. (428, "challenge_required"): challenge, (428, "pow_"): proof_of_work, (428, None): signin,
  355. (403, "signin_required"): signin, (403, "access_denied"): signin})
  356. if not isinstance(payload.get("access_token"), str) or not payload["access_token"]:
  357. logger.info("Nous free tier token exchange returned no token")
  358. raise _anon_err(ANON_FAILURE_COPY[ANON_SERVER_ERROR], ANON_SERVER_ERROR)
  359. # A connectors-only grant must neither clear nor announce an inference challenge.
  360. if not is_connectors_only(payload["access_token"]):
  361. anon_challenge.note_optional_challenges(payload, portal_base_url)
  362. return payload
  363. def apply_exchange_to_state(state: dict[str, Any], exchanged: dict[str, Any]) -> None:
  364. """Write a fresh exchange result into a guest state in place: an inference token (token, expiry,
  365. routing) into the state itself, a connectors-only one into ``connectors_token`` beside it."""
  366. from hermes_cli.auth_nous import _validate_nous_inference_url_from_network
  367. access_token = exchanged["access_token"]
  368. claims = _decode_jwt_claims(access_token)
  369. now = datetime.now(UTC)
  370. exp = claims.get("exp")
  371. if isinstance(exp, (int, float)):
  372. expires_at = datetime.fromtimestamp(float(exp), tz=UTC)
  373. else:
  374. expires_at = now + timedelta(seconds=int(exchanged.get("expires_in") or 900))
  375. if is_connectors_only(access_token):
  376. state["connectors_token"] = {"access_token": access_token, "expires_at": expires_at.isoformat()}
  377. return
  378. # NAS names the welcome host on every exchange; absent (older NAS) or outside the allowlist
  379. # (a staging host without NOUS_INFERENCE_BASE_URL set), the literal stands in. Never the paid
  380. # host: the gateway cross-refuses an anonymous JWT there.
  381. inference_url = (_validate_nous_inference_url_from_network(exchanged.get("inference_base_url"))
  382. or DEFAULT_NOUS_WELCOME_URL)
  383. scope = claims.get("scope") or claims.get("scp") or state.get("scope")
  384. if isinstance(scope, (list, tuple)):
  385. scope = " ".join(str(s) for s in scope)
  386. state.update(
  387. access_token=access_token, token_type="Bearer", scope=scope,
  388. obtained_at=now.isoformat(), expires_at=expires_at.isoformat(),
  389. expires_in=max(0, int((expires_at - now).total_seconds())),
  390. account_tier=str(claims.get("account_tier") or ANON_ACCOUNT_TIER))
  391. state["inference_base_url"] = inference_url
  392. for key in ("user_id", "org_id"):
  393. if exchanged.get(key):
  394. state[key] = exchanged[key]
  395. state.pop("refresh_token", None)
  396. def _portal_base_url() -> str:
  397. from hermes_cli.auth_nous import _nous_portal_env_override
  398. return (_nous_portal_env_override() or DEFAULT_NOUS_PORTAL_URL).rstrip("/")
  399. def _shared_identity_key(state: Any) -> Optional[str]:
  400. """Stable identity of a Nous credential: the anon_ token for a guest, the refresh token for an
  401. account. Used to decide whether two stores hold the SAME identity."""
  402. if not isinstance(state, dict):
  403. return None
  404. return state.get("anon_token") if is_guest_state(state) else state.get("refresh_token")
  405. def _mint_locked(client: httpx.Client, portal: str, auth_store: dict[str, Any], *,
  406. welcome_claim: bool) -> dict[str, Any]:
  407. """Mint under the caller's locks. The identity is persisted as soon as ``create`` succeeds, BEFORE
  408. the exchange: a 429 or timeout on the exchange must not lose a credential NAS still honours (the
  409. next attempt exchanges the stored one instead of minting again). *welcome_claim* is written in
  410. that same save, so a claimed guest is never left unstamped."""
  411. from hermes_cli.auth import _store_provider_state, _save_auth_store
  412. from hermes_cli.auth_nous import _write_shared_nous_state
  413. minted = mint_guest(client, portal)
  414. state: dict[str, Any] = {
  415. "auth_method": ANON_AUTH_METHOD, "account_tier": ANON_ACCOUNT_TIER,
  416. "anon_token": minted["token"], "client_id": ANON_CLIENT_ID,
  417. "portal_base_url": portal.rstrip("/"),
  418. "user_id": minted.get("user_id"), "org_id": minted.get("org_id"),
  419. "idle_ttl_days": minted.get("idle_ttl_days"),
  420. WELCOME_CLAIM_FLAG: welcome_claim,
  421. }
  422. _store_provider_state(auth_store, "nous", state, set_active=False)
  423. _save_auth_store(auth_store)
  424. _write_shared_nous_state(state, renewal=False)
  425. logger.info("Nous free tier ready (identity minted)")
  426. return state
  427. # Per-process mint memo: a failed mint is not retried until its cooldown has passed (a closed gate
  428. # is never retried; a 429 waits out ``Retry-After``; an unreachable portal climbs a short ladder),
  429. # so a boot-time blip cannot hammer the portal AND cannot disable the free tier for the whole
  430. # process the way a plain "tried once" flag did. ``clear_dead_guest`` resets it because a retired
  431. # credential is a reason to mint again; an explicit user retry (``force=True``) bypasses it.
  432. # Keyed per profile home ("" for the unscoped launch profile): profile A's 429 must not stop
  433. # profile B from ever getting an identity.
  434. _MINT_RETRY_LADDER = (15.0, 60.0, 300.0) # unreachable / server error, attempt 1, 2, 3+
  435. _MINT_PAUSED_MIN_WAIT = 60.0 # ops breaker: never poll it faster than this
  436. @dataclass
  437. class MintFailure:
  438. """Why the last mint for a profile failed and when the next one may run."""
  439. code: str
  440. message: str
  441. retryable: bool
  442. retry_after: float # the wait this failure asked for, in seconds (0 for a terminal code)
  443. not_before: float # ``time.monotonic()`` before which ``ensure_portal_identity`` stays quiet
  444. attempts: int = 1
  445. def remaining(self) -> float:
  446. # Rounded to the millisecond: ``(now + wait) - now`` is not exactly ``wait`` in floating point,
  447. # and the ceil below turned that dust into an extra whole second ("retry in 61s").
  448. return 0.0 if not self.retryable else max(0.0, round(self.not_before - time.monotonic(), 3))
  449. def as_payload(self) -> dict[str, Any]:
  450. """The wire shape every status RPC carries: ``{error_code, error, retryable, retry_after}``
  451. with ``retry_after`` the seconds still to wait (whole, rounded up)."""
  452. return {"error_code": self.code, "error": self.message, "retryable": self.retryable,
  453. "retry_after": math.ceil(self.remaining()) if self.retryable else 0}
  454. _mint_failures: dict[str, MintFailure] = {}
  455. def _mint_memo_key() -> str:
  456. from hermes_constants import get_hermes_home_override, hermes_home_key
  457. return "" if get_hermes_home_override() is None else hermes_home_key()
  458. def _mint_failure_for_profile() -> Optional[MintFailure]:
  459. return _mint_failures.get(_mint_memo_key())
  460. def _clear_mint_failure() -> None:
  461. _mint_failures.pop(_mint_memo_key(), None)
  462. def reset_mint_memo_for_tests() -> None:
  463. _mint_failures.clear()
  464. def last_mint_failure() -> Optional[dict[str, Any]]:
  465. """The most recent mint failure for this profile as a wire payload, or None (never failed, or
  466. cleared by a later success / retirement)."""
  467. failure = _mint_failure_for_profile()
  468. return failure.as_payload() if failure else None
  469. def classify_mint_exception(exc: BaseException) -> AuthError:
  470. """Every mint failure as one ``AuthError`` with a code: the portal's own refusals already are;
  471. the wire's (timeout, DNS, refused connection) and anything else get a code here. Pure: *exc* is
  472. never mutated (an uncoded ``AuthError`` is re-raised as a server-error twin)."""
  473. if isinstance(exc, AuthError) and exc.code:
  474. return exc
  475. transport = (TimeoutError, ConnectionError, OSError)
  476. try:
  477. transport = transport + (httpx.TimeoutException, httpx.TransportError)
  478. except Exception: # httpx unavailable (lazy proxy): the stdlib set stands
  479. pass
  480. code = ANON_UNREACHABLE if isinstance(exc, transport) else ANON_SERVER_ERROR
  481. wrapped = _anon_err(ANON_FAILURE_COPY[code], code, retry_after=getattr(exc, "retry_after", None))
  482. wrapped.__cause__ = exc
  483. return wrapped
  484. def _note_mint_failure(err: AuthError) -> MintFailure:
  485. code = str(err.code or ANON_SERVER_ERROR)
  486. previous = _mint_failure_for_profile()
  487. attempts = previous.attempts + 1 if previous and previous.code == code else 1
  488. retryable = code not in ANON_TERMINAL_CODES
  489. if not retryable:
  490. wait, not_before = 0.0, float("inf")
  491. else:
  492. hinted = err.retry_after
  493. wait = float(hinted) if hinted else _MINT_RETRY_LADDER[min(attempts, len(_MINT_RETRY_LADDER)) - 1]
  494. if code == ANON_GATE_PAUSED:
  495. wait = max(wait, _MINT_PAUSED_MIN_WAIT)
  496. wait = max(1.0, wait)
  497. not_before = time.monotonic() + wait
  498. failure = MintFailure(code=code, message=str(err), retryable=retryable, retry_after=wait,
  499. not_before=not_before, attempts=attempts)
  500. _mint_failures[_mint_memo_key()] = failure
  501. return failure
  502. def _reconcile_and_provision(*, timeout_seconds: float, force: bool = False,
  503. welcome_claim: bool = False) -> Optional[dict[str, Any]]:
  504. """The lifecycle body, run under profile lock THEN shared lock (the documented order).
  505. 1. The shared store is the identity of record for this Hermes root. If it holds an identity
  506. that differs from the profile's, the profile adopts it (a stale guest never outlives a
  507. sibling profile's sign-in, and never overwrites it).
  508. 2. Otherwise the profile's own identity stands.
  509. 3. Nothing anywhere: mint, persisting the credential before exchanging it.
  510. """
  511. from hermes_cli.auth import (
  512. _auth_store_lock, _load_auth_store, _load_provider_state, _save_auth_store,
  513. _store_provider_state, _resolve_verify)
  514. from hermes_cli.auth_nous import (
  515. _SHARED_RENEWAL_KEY, _nous_http_client, _nous_shared_store_lock, _read_shared_nous_state,
  516. _write_shared_nous_state)
  517. portal = _portal_base_url()
  518. with _auth_store_lock():
  519. auth_store = _load_auth_store()
  520. profile_state = _load_provider_state(auth_store, "nous")
  521. with _nous_shared_store_lock(timeout_seconds=max(timeout_seconds, 5.0)):
  522. shared = _read_shared_nous_state()
  523. if shared and _shared_identity_key(shared) != _shared_identity_key(profile_state):
  524. state = {k: v for k, v in shared.items() if k != _SHARED_RENEWAL_KEY} # another account's tokens
  525. _store_provider_state(auth_store, "nous", state, set_active=not is_guest_state(state))
  526. _save_auth_store(auth_store)
  527. logger.debug("Nous identity adopted from the shared store")
  528. return state
  529. if profile_state:
  530. if not shared:
  531. _write_shared_nous_state(profile_state, renewal=False)
  532. return profile_state
  533. # A caller queued on these locks behind a mint that just failed waits out its cooldown.
  534. failure = _mint_failure_for_profile()
  535. if failure and not force and time.monotonic() < failure.not_before:
  536. return None
  537. verify = _resolve_verify(insecure=None, ca_bundle=None, auth_state=None)
  538. try:
  539. with _nous_http_client(timeout_seconds, verify) as client:
  540. return _mint_locked(client, portal, auth_store, welcome_claim=welcome_claim)
  541. except Exception as exc:
  542. # Noted before the locks are released, so a caller queued on them sees the cooldown.
  543. err = classify_mint_exception(exc)
  544. err.mint_failure = _note_mint_failure(err)
  545. if err is exc:
  546. raise
  547. raise err from exc
  548. def ensure_portal_identity(
  549. *, explicit: bool, timeout_seconds: float = GUEST_MINT_TIMEOUT_SECONDS, force: bool = False,
  550. welcome_claim: bool = False,
  551. ) -> Optional[dict[str, Any]]:
  552. """Make sure this profile has a Nous identity (guest or account); mint a guest only if the shared
  553. store has none. Returns the ``providers.nous`` state, or None (disabled / failed once already).
  554. ``explicit`` is required and must be True: the only callers are the first hosted connector action
  555. (``tools.connectors.gateway.config.ensure_guest_identity``), the connectors dead-credential
  556. replacement (``managed_tool_gateway._replace_dead_guest_token``) and the desktop's welcome-trial
  557. claim (``welcome_trial.claim_desktop_free_tier``), which passes ``welcome_claim=True`` so a guest
  558. it mints carries the stamp from its first write. Every other guest is minted with
  559. ``welcome_claim: False`` and serves connectors only.
  560. Nothing creates an identity as a side effect of reading status, resolving a provider or fetching a
  561. connector bearer (NS-845 Q1.2).
  562. Order: gate (``guest_allowed``) -> reconcile with the shared store -> mint. Locks are taken
  563. profile first, then shared, matching every other Nous path. Blocking, bounded by ``timeout_seconds``.
  564. A failed mint is memoised with a cooldown (``MintFailure``): until it passes, and for a
  565. terminal code forever, this returns None without touching the portal. ``force=True`` is the
  566. user's own retry: it makes exactly one attempt
  567. regardless of the cooldown. Every failure raises an ``AuthError`` whose ``code`` is one of the
  568. ``ANON_*`` codes and whose ``retry_after`` / ``retryable`` say what a caller may do next.
  569. """
  570. if not explicit:
  571. raise ValueError("ensure_portal_identity: only explicit creators may call this (explicit=True)")
  572. if not guest_allowed():
  573. return None
  574. failure = _mint_failure_for_profile()
  575. if failure and not force and not current_nous_state() and time.monotonic() < failure.not_before:
  576. return None # in cooldown (or terminal) for this profile; do not hammer the portal
  577. try:
  578. state = _reconcile_and_provision(timeout_seconds=timeout_seconds, force=force,
  579. welcome_claim=welcome_claim)
  580. except Exception as exc:
  581. err = classify_mint_exception(exc)
  582. noted = getattr(err, "mint_failure", None) or _note_mint_failure(err)
  583. logger.info("Nous free tier not set up (%s, attempt %d%s)", noted.code, noted.attempts,
  584. f", next try in {noted.retry_after:.0f}s" if noted.retryable else ", not retried")
  585. if err is exc:
  586. raise
  587. raise err from exc
  588. if state is not None:
  589. _clear_mint_failure()
  590. # Adopting a sibling profile's sign-in replaced this profile's guest under the locks above.
  591. from hermes_cli.guest_handoff import drain
  592. drain()
  593. return state
  594. def refresh_guest_state(state: dict[str, Any], client: httpx.Client, *, purpose: str) -> str:
  595. """Token-acquisition seam for a guest: re-exchange the ``anon_`` credential in place and return
  596. the minted token. Every caller names its *purpose*: ``"connectors"`` for connector and managed-tool
  597. bearers, ``"inference"`` only for a guest that carries the welcome trial.
  598. The portal URL is the resolver's canonical one (env override, else the validated stored URL,
  599. else the default), never a raw stored value on its own.
  600. Raises :class:`AnonCredentialDead` when NAS no longer knows the credential; the caller owns
  601. re-minting (:func:`ensure_portal_identity` after :func:`clear_dead_guest`).
  602. """
  603. if purpose == "inference" and not free_inference_active(state):
  604. # The one place a guest's inference token is minted: only the welcome trial on the desktop's
  605. # local backend carries one. Not terminal: the guest stays for connectors.
  606. raise AuthError("Hermes is not logged into Nous Portal.", provider="nous", code="nous_auth_missing")
  607. anon_token = state.get("anon_token")
  608. if not isinstance(anon_token, str) or not anon_token:
  609. raise AnonCredentialDead(ANON_FAILURE_COPY[ANON_CREDENTIAL_DEAD], code=ANON_CREDENTIAL_DEAD)
  610. from hermes_cli.auth import _nous_portal_base_url
  611. exchanged = exchange_anon_jwt(
  612. client, _nous_portal_base_url(state), anon_token, auth_state=state, purpose=purpose)
  613. apply_exchange_to_state(state, exchanged)
  614. return exchanged["access_token"]
  615. def clear_dead_guest(reason: str, *, dead_token: Optional[str] = None) -> None:
  616. """Drop a dead guest so the next need re-mints.
  617. Only the identity that actually failed is removed: a stale profile whose credential NAS rejected
  618. must not erase a sibling profile's newer sign-in or replacement guest from the shared store. When
  619. *dead_token* is None the profile's current guest is treated as the failed one.
  620. """
  621. from hermes_cli.auth import (
  622. _auth_store_lock, _load_auth_store, _load_provider_state, _save_auth_store, _store_section)
  623. from hermes_cli.auth_nous import _clear_shared_nous_state, _nous_shared_store_lock, _read_shared_nous_state
  624. with _auth_store_lock():
  625. auth_store = _load_auth_store()
  626. state = _load_provider_state(auth_store, "nous")
  627. if is_guest_state(state):
  628. token = dead_token or state.get("anon_token")
  629. if state.get("anon_token") == token:
  630. _store_section(auth_store, "providers").pop("nous", None)
  631. _store_section(auth_store, "credential_pool").pop("nous", None)
  632. if auth_store.get("active_provider") == "nous":
  633. auth_store["active_provider"] = None
  634. _save_auth_store(auth_store)
  635. else:
  636. token = dead_token
  637. with _nous_shared_store_lock():
  638. shared = _read_shared_nous_state()
  639. if token and is_guest_state(shared) and shared.get("anon_token") == token:
  640. _clear_shared_nous_state(reason)
  641. _clear_mint_failure()
  642. logger.info("Nous free-tier identity retired (%s); a new one is set up on next use", reason)
  643. # --- Gateway welcome-tier contract: structured refusals and the model-switch header ------------------
  644. #
  645. # The inference gateway answers a welcome-tier request it will not serve with a structured 429
  646. # (``{status, message, reason, retry_after, alternates?, upgrade_url?}``), and a request on the wrong
  647. # host with a 400 (or a 403 while the tier is dark) whose message names the right host. A NAMED
  648. # account that still asks for ``nous/welcome`` is served the id's backing model and told what to
  649. # switch to in the ``x-nous-model-switch`` response header. Every rule for reading those lives here;
  650. # the error classifier and the turn loop only call in.
  651. MODEL_SWITCH_HEADER = "x-nous-model-switch"
  652. # Fairshare refusal reasons the welcome tier can answer with (api ``FairshareRefusalReason``).
  653. WELCOME_REFUSAL_REASONS = frozenset(
  654. {"model_not_free", "feature_not_free", "at_capacity", "admission_closed", "rate_limited"})
  655. # Reasons that mean "not on this tier, ever": no retry helps, only a sign-in or another provider.
  656. WELCOME_TIER_GATE_REASONS = frozenset({"model_not_free", "feature_not_free"})
  657. # Gateway messages (lowercased substrings) for a request on the wrong host or a dark tier.
  658. _WELCOME_ROUTE_REFUSALS = (
  659. ("anonymous accounts must use", "anon_on_paid_host"),
  660. ("serves anonymous hermes agent accounts only", "named_on_welcome_host"),
  661. ("anonymous accounts are not accepted", "tier_disabled"),
  662. # The gateway's answer to an expired or unreadable bearer: the credential, not the tier. A
  663. # retry that waited out a long rate limit outlives the 15-minute free-tier JWT and lands here.
  664. ("invalid jwt", "session_expired"),
  665. )
  666. _WELCOME_ROUTE_COPY = {
  667. # Only reachable when the route heal (``turn_recovery._recover_welcome_tier``) could not move
  668. # the session: the one cause left is a user-set NOUS_INFERENCE_BASE_URL naming the paid host.
  669. "anon_on_paid_host": "This install is set to use a different Nous server (NOUS_INFERENCE_BASE_URL). "
  670. "Unset it to use the free model, or sign in. {signin}",
  671. "named_on_welcome_host": "This Nous account needs to reconnect. {model_hint}",
  672. "tier_disabled": "Using Hermes without signing in is switched off right now. "
  673. "Sign in to keep chatting, it's free. {signin}",
  674. # Only reachable when re-exchanging the free credential failed (``turn_recovery._recover_welcome_tier``).
  675. "session_expired": "Hermes couldn't renew its connection to the free model. "
  676. "Send your message again, or sign in to keep chatting, it's free. {signin}",
  677. }
  678. # The sign-in door, phrased for a chat surface (slash command) and for a terminal.
  679. _SIGNIN_CHAT = "To sign in: /login."
  680. _SIGNIN_TERMINAL = "To sign in: `hermes auth upgrade`."
  681. _MODEL_HINT_CHAT = "Run /model and pick the Nous row again."
  682. _MODEL_HINT_TERMINAL = "Run `hermes model` and pick the Nous row again."
  683. # Terminal copy for a free-model outage once the retries are spent (5xx, transport failure).
  684. FREE_TIER_OUTAGE_COPY = ("The free model is having trouble responding right now. "
  685. "Try sending your message again in a minute.")
  686. def parse_welcome_refusal(body: Any) -> Optional[dict[str, Any]]:
  687. """The structured welcome-tier refusal in a gateway 429 body, or None for any other shape.
  688. Returns ``{"reason", "retry_after", "alternates", "upgrade_url"}`` with ``retry_after`` an int
  689. of whole seconds (0 when the gateway sent none) and ``alternates`` a list of model ids.
  690. """
  691. if not isinstance(body, dict):
  692. return None
  693. reason = body.get("reason")
  694. if not isinstance(reason, str) or reason not in WELCOME_REFUSAL_REASONS:
  695. return None
  696. raw_retry = body.get("retry_after")
  697. try:
  698. retry_after = max(0, int(float(raw_retry))) if raw_retry not in (None, "") else 0
  699. except (TypeError, ValueError):
  700. retry_after = 0
  701. raw_alternates = body.get("alternates")
  702. alternates = [str(a) for a in raw_alternates if isinstance(a, str) and a] if isinstance(raw_alternates, list) else []
  703. upgrade_url = body.get("upgrade_url")
  704. return {"reason": reason, "retry_after": retry_after, "alternates": alternates,
  705. "upgrade_url": upgrade_url if isinstance(upgrade_url, str) else ""}
  706. def welcome_refusal_copy(refusal: dict[str, Any], *, model: str = "", in_chat: bool = True, door: bool = True) -> str:
  707. """User copy for a structured welcome-tier refusal: what happened and the one way forward.
  708. Never guest / anonymous / claim; ``in_chat`` picks ``/login`` over the terminal verb.
  709. ``door=False`` leaves the "To sign in: …" tail off, for a surface that renders the sign-in as
  710. a button beside the sentence (the desktop's error card)."""
  711. signin = (_SIGNIN_CHAT if in_chat else _SIGNIN_TERMINAL) if door else ""
  712. reason = str(refusal.get("reason") or "")
  713. alternates = refusal.get("alternates") or []
  714. serves = alternates[0] if alternates else GUEST_MODEL
  715. retry = int(refusal.get("retry_after") or 0)
  716. wait = friendly_wait(retry) if retry > 0 else "a little while"
  717. if reason == "model_not_free":
  718. what = f"{model} isn't" if model else "That model isn't"
  719. return (f"{what} available without signing in, so Hermes uses {serves} for now. "
  720. f"Sign in for more models. {signin}").rstrip()
  721. if reason == "feature_not_free":
  722. return f"That isn't available without signing in. Sign in to use it, it's free. {signin}".rstrip()
  723. if reason == "at_capacity":
  724. return ("Chatting without signing in is really busy right now. Sign in to skip the queue, "
  725. f"it's free, or try again in {wait}. {signin}").rstrip()
  726. if reason == "admission_closed":
  727. return ("Chatting without signing in is full right now. Sign in to keep going, "
  728. f"it's free, or try again in {wait}. {signin}").rstrip()
  729. if reason == "rate_limited":
  730. return (f"You've used up the allowance for chatting without signing in. It refreshes in {wait}. "
  731. f"Sign in for a bigger allowance, it's free. {signin}").rstrip()
  732. return f"Hermes couldn't send that without signing in. Signing in is free. {signin}".rstrip()
  733. def welcome_route_refusal(status: Any, message: Any, base_url: Any = None) -> Optional[str]:
  734. """Which host cross-refusal a gateway 400/403 is; None for any other error.
  735. ``"anon_on_paid_host"``: a free-tier JWT reached the paid host. ``"named_on_welcome_host"``: an
  736. account or API key reached the free tier's host. ``"tier_disabled"``: the tier is dark
  737. (``WELCOME_MODE=off``). Each is deterministic for the request: retrying cannot help.
  738. ``"session_expired"``: the 403 names the bearer (``invalid jwt``); a fresh credential heals it.
  739. The dark-tier 403 is keyed on the ROUTE, not the message: the gateway's permission error
  740. carries only its generic sentence (the detail stays in its logs), so any 403 answered by the
  741. welcome host means the tier refused this install. The message needles remain for gateways
  742. that do spell it out, and for the two wrong-host 400s."""
  743. if status not in (400, 403):
  744. return None
  745. text = str(message or "").lower()
  746. kind = next((kind for needle, kind in _WELCOME_ROUTE_REFUSALS if needle in text), None)
  747. if kind is None and status == 403 and route_is_welcome_host(base_url):
  748. return "tier_disabled"
  749. return kind
  750. def welcome_route_refusal_copy(kind: str, *, in_chat: bool = True, door: bool = True) -> str:
  751. template = _WELCOME_ROUTE_COPY.get(kind) or "Hermes couldn't reach the free model on this route."
  752. return template.format(
  753. host=DEFAULT_NOUS_WELCOME_URL, signin=(_SIGNIN_CHAT if in_chat else _SIGNIN_TERMINAL) if door else "",
  754. model_hint=_MODEL_HINT_CHAT if in_chat else _MODEL_HINT_TERMINAL).rstrip()
  755. def note_model_switch(agent: Any, headers: Any) -> Optional[str]:
  756. """Record the gateway's ``x-nous-model-switch`` header on *agent* for the next call, if present.
  757. The header arrives on a NAMED account's response that asked for ``nous/welcome`` (the gateway
  758. served the backing model and billed it normally): the free tier's model no longer belongs in
  759. this install's configuration. Recorded here, applied by :func:`apply_model_switch` between
  760. calls so a response still streaming is never re-labelled under itself. Returns the backing id.
  761. """
  762. if headers is None:
  763. return None
  764. value = None
  765. try:
  766. value = headers.get(MODEL_SWITCH_HEADER)
  767. if value is None and hasattr(headers, "items"):
  768. value = next((v for k, v in headers.items() if str(k).lower() == MODEL_SWITCH_HEADER), None)
  769. except Exception:
  770. return None
  771. backing = str(value or "").strip()
  772. if not backing:
  773. return None
  774. requested = str(getattr(agent, "model", "") or "")
  775. if backing == requested:
  776. return None
  777. try:
  778. agent._nous_pending_model_switch = (requested, backing)
  779. except Exception:
  780. return None
  781. return backing
  782. def apply_model_switch(agent: Any) -> Optional[str]:
  783. """Move *agent* (and the config default, when it still names the switched id) to the backing
  784. model the gateway named. Returns the new model, or None when nothing was pending.
  785. Runs once per recorded header, between calls. The conversation keeps its history; only the id
  786. the next request carries changes, so a promoted account stops relying on the gateway's reverse
  787. map. The config write is the same one a sign-in completion uses, so ``hermes model`` and the
  788. gateway's config re-read agree with the live session.
  789. """
  790. pending = getattr(agent, "_nous_pending_model_switch", None)
  791. if not pending:
  792. return None
  793. agent._nous_pending_model_switch = None
  794. requested, backing = pending
  795. if str(getattr(agent, "model", "") or "") != requested:
  796. return None # the session already moved (a /model, a sign-in sweep)
  797. agent.model = backing
  798. # The gateway's cache check compares agent.model with the config default and evicts on a
  799. # mismatch it did not cause; this pair names the move so the check can recognise exactly this
  800. # server-driven switch even when the config write below did not land.
  801. agent._nous_model_switch = (requested, backing)
  802. logger.info("Nous gateway asked to switch %s -> %s; applied for this session", requested, backing)
  803. try:
  804. from hermes_cli.config import load_config_readonly
  805. raw = load_config_readonly().get("model")
  806. model_cfg = raw if isinstance(raw, dict) else ({"default": raw} if isinstance(raw, str) else {})
  807. if str(model_cfg.get("default") or "").strip() == requested:
  808. from hermes_cli.auth import _update_config_for_provider
  809. _update_config_for_provider(
  810. "nous", str(getattr(agent, "base_url", "") or ""), default_model=backing)
  811. logger.info("Config default model moved %s -> %s", requested, backing)
  812. except Exception as exc:
  813. logger.debug("model switch: config default left as is: %s", exc)
  814. status = getattr(agent, "_buffer_status", None)
  815. if callable(status):
  816. try:
  817. status(f"Model is now {backing} (your account's model; {requested} is the free tier's).")
  818. except Exception:
  819. pass
  820. return backing
  821. # One-time CLI notice: an install whose inference is carried by an explicit provider learns once that
  822. # the free tier (inference + connectors) now exists. The flag lives on the guest state itself so it
  823. # dies with the identity; a fresh guest (re-mint, new profile) may announce itself once more.
  824. GUEST_NOTICE_FLAG = "guest_notice_shown"
  825. def guest_notice_pending() -> bool:
  826. """True when a guest identity exists and the one-time availability notice has not been shown."""
  827. state = current_nous_state()
  828. return free_inference_active(state) and not bool(state.get(GUEST_NOTICE_FLAG))
  829. def mark_guest_notice_shown() -> bool:
  830. """Persist ``guest_notice_shown`` on the guest's ``providers.nous`` state (whichever store holds it).
  831. Returns True when a flag was written; False when there is no guest to mark."""
  832. return set_guest_flag(GUEST_NOTICE_FLAG) is not None
  833. def set_guest_flag(flag: str) -> Optional[dict[str, Any]]:
  834. """Set *flag* on the guest's ``providers.nous`` state in whichever store holds it, and return the
  835. updated state; None when there is no guest."""
  836. from hermes_cli.auth import _provider_state_transaction
  837. with _provider_state_transaction("nous") as (auth_store, state, source_path):
  838. if not is_guest_state(state) or source_path is None:
  839. return None
  840. if state.get(flag):
  841. return state
  842. state = {**state, flag: True}
  843. _save_guest_state(auth_store, state, source_path)
  844. return state
  845. def _save_guest_state(auth_store: dict[str, Any], state: dict[str, Any], source_path: Path) -> None:
  846. """Write the guest's ``providers.nous`` back to the store it was read from (the caller holds its lock)."""
  847. from hermes_cli.auth import _auth_file_path, _load_auth_store, _same_path, _save_auth_store, _store_section
  848. if _same_path(source_path, _auth_file_path()):
  849. _store_section(auth_store, "providers")["nous"] = state
  850. _save_auth_store(auth_store)
  851. else:
  852. source_store = _load_auth_store(source_path)
  853. _store_section(source_store, "providers")["nous"] = state
  854. _save_auth_store(source_store, target_path=source_path)
  855. # --- Sign-in completion: the account state from a token grant, and the config settle -------------
  856. #
  857. # Every Nous sign-in is the plain device-code login (``anon_sign_in.run_sign_in``). The free tier it
  858. # replaces hands its apps over in ``guest_handoff`` after the save. User-facing copy never says
  859. # guest / anonymous / claim.
  860. UPGRADED_AUTH_METHOD = "oauth_device_code"
  861. def _account_state_from_token(
  862. token_data: dict[str, Any], *, portal_base_url: str, client_id: str, scope: Optional[str], verify: Any,
  863. timeout_seconds: float,
  864. ) -> dict[str, Any]:
  865. """The ``providers.nous`` shape for the signed-in account (same fields the device-code login writes)."""
  866. from hermes_cli.auth import PROVIDER_REGISTRY, _coerce_ttl_seconds, _optional_base_url, _tls_state_from_verify
  867. from hermes_cli.auth_nous import _NOUS_EMPTY_AGENT_KEY_FIELDS, _iso_after, refresh_nous_oauth_from_state
  868. now = datetime.now(UTC)
  869. ttl = _coerce_ttl_seconds(token_data.get("expires_in", 0))
  870. inference_url = (
  871. _optional_base_url(token_data.get("inference_base_url"))
  872. or PROVIDER_REGISTRY["nous"].inference_base_url.rstrip("/"))
  873. state = {
  874. "portal_base_url": portal_base_url, "inference_base_url": inference_url,
  875. "client_id": client_id, "scope": token_data.get("scope") or scope,
  876. "token_type": token_data.get("token_type", "Bearer"),
  877. "access_token": token_data["access_token"], "refresh_token": token_data.get("refresh_token"),
  878. "obtained_at": now.isoformat(), "expires_at": _iso_after(now, ttl), "expires_in": ttl,
  879. "tls": _tls_state_from_verify(verify), **_NOUS_EMPTY_AGENT_KEY_FIELDS}
  880. state = refresh_nous_oauth_from_state(state, timeout_seconds=timeout_seconds, force_refresh=False)
  881. state["auth_method"] = UPGRADED_AUTH_METHOD
  882. return state
  883. def settle_after_upgrade(account_state: dict[str, Any]) -> dict[str, Any]:
  884. """After a sign-in from the free tier persisted the account: move the config off the free tier's route.
  885. Picking the free-tier row may have written ``model.default: nous/welcome`` and ``model.base_url``
  886. = welcome host. An account cannot keep either: the welcome host refuses account tokens, and the
  887. portal host serves ``nous/welcome`` as a paid model. When the config is on the free tier's route,
  888. ``model.base_url`` becomes the account's inference host and ``model.default`` the recommended
  889. default for the account's tier (:func:`hermes_cli.models.recommended_nous_default_model`, the
  890. same pick as ``GET /api/model/recommended-default``), through the same config write a plain Nous
  891. login uses. A config on the user's own model and host is left alone.
  892. Every sign-in completion (CLI ``hermes auth upgrade``, the desktop poller) calls this once, after
  893. ``persist_nous_credentials``. Returns ``{"model": str, "changed": bool}``: ``model`` is the default
  894. the config now carries (``""`` when it carries none); ``changed`` says whether this call wrote it.
  895. Never raises: a failed pick or write is logged and reported as ``changed: False`` so the sign-in
  896. itself still counts.
  897. """
  898. from hermes_cli.config import load_config_readonly
  899. try:
  900. raw = load_config_readonly().get("model")
  901. except Exception as exc:
  902. logger.warning("sign-in completion: config unreadable, default model left as is: %s", exc)
  903. return {"model": "", "changed": False}
  904. model_cfg = raw if isinstance(raw, dict) else ({"default": raw} if isinstance(raw, str) else {})
  905. current = str(model_cfg.get("default") or "").strip()
  906. on_welcome_model = current == GUEST_MODEL
  907. on_welcome_host = route_is_welcome_host(model_cfg.get("base_url"))
  908. if not (on_welcome_model or on_welcome_host):
  909. return {"model": current, "changed": False}
  910. model = current
  911. if on_welcome_model:
  912. from hermes_cli.models import recommended_nous_default_model
  913. try:
  914. model = str(recommended_nous_default_model().get("model") or "")
  915. except Exception as exc:
  916. logger.debug("sign-in completion: recommended default unavailable: %s", exc)
  917. model = ""
  918. try:
  919. from hermes_cli.auth import _update_config_for_provider
  920. # One write: host and default move together, so a failure leaves the config as it was
  921. # rather than the account host paired with the welcome model. No eligible recommendation
  922. # (Portal unreachable, or the plan and org policy admit nothing) clears the default in that
  923. # same write; the runtime's silent default applies until the user picks one with `hermes model`.
  924. _update_config_for_provider(
  925. "nous", str(account_state.get("inference_base_url") or ""),
  926. default_model=model if on_welcome_model else None,
  927. clear_default=on_welcome_model and not model)
  928. except Exception as exc:
  929. logger.warning("sign-in completion: could not update the default model: %s", exc)
  930. return {"model": current, "changed": False}
  931. return {"model": model, "changed": True}
  932. def _poll_for_token(*args, **kwargs) -> dict[str, Any]:
  933. """Keep both the sign-in module seam and the device-flow seam live at call time."""
  934. from hermes_cli.auth_device_flow import _poll_for_token as poll
  935. return poll(*args, **kwargs)
  936. def persist_nous_credentials(*args, **kwargs):
  937. """Keep the existing auth_nous persistence seam behind the sign-in entry point."""
  938. from hermes_cli.auth_nous import persist_nous_credentials as persist
  939. return persist(*args, **kwargs)
  940. # Public sign-in imports remain here for existing callers and module-attribute patches.
  941. # The flow imports this module only inside calls, so either module can be imported first.
  942. from hermes_cli.anon_sign_in import (
  943. AlreadySignedIn,
  944. Cancelled,
  945. Code,
  946. Completed,
  947. FREE_TIER_RATE_LIMIT_CARD,
  948. FREE_TIER_RATE_LIMIT_CHAT,
  949. Failed,
  950. LOGIN_BUSY_ELSEWHERE,
  951. LOGIN_COMMAND,
  952. LOGIN_DM_ONLY,
  953. LOGIN_NOT_ALLOWED,
  954. LOGIN_STARTING,
  955. SignInState,
  956. TimedOut,
  957. UPGRADE_ALREADY_SIGNED_IN,
  958. UPGRADE_CANCELLED,
  959. UPGRADE_DO_NOT_SHARE,
  960. UPGRADE_NOT_COMPLETED,
  961. UPGRADE_NO_DEFAULT_CHAT,
  962. UPGRADE_NO_DEFAULT_TERMINAL,
  963. UPGRADE_START,
  964. UPGRADE_TIMED_OUT,
  965. UPGRADE_WAITING,
  966. UPGRADE_WAITING_UP_TO,
  967. Waiting,
  968. _default_persist_guard,
  969. format_wait_line,
  970. run_sign_in,
  971. )
  972. from hermes_cli.anon_sign_in_cli import (
  973. drain_sign_in_copy,
  974. render_sign_in_cli,
  975. render_sign_in_cli_code,
  976. upgrade_guest,
  977. )