credits_tracker.py 50 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940
  1. """Nous credits: parse ``x-nous-credits-*`` / ``x-nous-tool-pool-*`` response
  2. headers into a validated CreditsState (depletion = paid_access, subscription-cap
  3. used_fraction, warn-once schema-version gating) and drive the notice policy.
  4. Header contract: see ``_HEADER_FIELDS``. Money is micros ints only; ``*_usd``
  5. strings are preserved verbatim (never re-parsed to float)."""
  6. from __future__ import annotations
  7. import logging
  8. import os
  9. import re
  10. import threading
  11. import time
  12. from dataclasses import dataclass
  13. from decimal import Decimal
  14. from typing import Any, Mapping, Optional
  15. from utils import is_truthy_value
  16. from agent.usage_gauges import (
  17. BP_FULL,
  18. SCOPE_TOP_TIER,
  19. WindowGauge,
  20. all_scope,
  21. binding_gauge,
  22. gauge_limit_name,
  23. parse_gauges,
  24. paused_for_payment,
  25. top_tier_gauge,
  26. )
  27. logger = logging.getLogger(__name__)
  28. _version_warning_emitted: bool = False # warn-once latch (per process)
  29. _VALID_DENOMINATOR_KINDS = frozenset({"subscription_cap", "none", "usage_window"})
  30. _USD_RE = re.compile(r"^-?\d+\.\d{2}$") # optional minus, digits, exactly 2 decimals
  31. _SENTINEL = object() # "parse failed"
  32. # Usage-window plans: the allowances are the server's gauge list
  33. # (agent/usage_gauges.py), percents in basis points. Which allowances exist, their
  34. # order and which models each stops all come from the server.
  35. _VALID_SPEND_SOURCES = frozenset({"included", "payg"})
  36. def _safe_int(value: Any) -> Any:
  37. """Exact int (money-safe) or ``_SENTINEL``. ``int()`` directly, NOT ``int(float())``
  38. (precision loss above 2**53 corrupts money); float-shaped strings fail."""
  39. try:
  40. return _SENTINEL if value is None else int(str(value))
  41. except (TypeError, ValueError):
  42. return _SENTINEL
  43. @dataclass
  44. class CreditsState:
  45. """Credits state parsed from x-nous-credits-* response headers."""
  46. version: int = 0
  47. remaining_micros: int = 0
  48. remaining_usd: str = ""
  49. subscription_micros: int = 0 # SIGNED — the ONLY field allowed negative (debt)
  50. subscription_usd: str = ""
  51. subscription_limit_micros: Optional[int] = None # PAIRED + OPTIONAL (only when subscription_cap)
  52. subscription_limit_usd: Optional[str] = None
  53. rollover_micros: int = 0
  54. purchased_micros: int = 0
  55. purchased_usd: str = ""
  56. tool_pool_micros: int = 0
  57. tool_pool_gated_off: bool = False
  58. denominator_kind: str = "none" # "subscription_cap" | "none" | "usage_window"
  59. paid_access: bool = True # depletion keys off THIS == False, NEVER remaining==0
  60. disabled_reason: Optional[str] = None # header omitted entirely when null
  61. as_of_ms: int = 0
  62. captured_at: float = 0.0 # time.time() when captured
  63. from_header: bool = False # True only when populated by parse_credits_headers()
  64. # ── usage_window only (empty / defaults otherwise): the server's allowances, in display order.
  65. gauges: tuple[WindowGauge, ...] = ()
  66. spend_source: Optional[str] = None # "included" | "payg" — which wallet the LAST request drew on
  67. # An admitted reply the server did not meter (no spend source: a skipped guard). A full gauge on it is no
  68. # refusal, so it raises no limit stop; the next metered reply or 402 decides.
  69. unmetered: bool = False
  70. paused_reason: Optional[str] = None # e.g. "payment_past_due": the window is withheld, not spent
  71. auto_top_up_enabled: bool = False # seed-only today (the header set does not carry it)
  72. # The account setting "Keep going on credits". False = a used-up
  73. # allowance stops (402) even with a balance; None = a server that predates it (top-up is spent).
  74. keep_going_on_credits: Optional[bool] = None
  75. @property
  76. def credits_pay(self) -> bool:
  77. """Top-up credits will cover Hermes usage once the included allowance is used up."""
  78. return self.purchased_micros > 0 and self.keep_going_on_credits is not False
  79. @property
  80. def has_data(self) -> bool:
  81. return self.captured_at > 0
  82. @property
  83. def age_seconds(self) -> float:
  84. return time.time() - self.captured_at if self.has_data else float("inf")
  85. @property
  86. def depleted(self) -> bool:
  87. """``paid_access == False`` ONLY — ``remaining_micros == 0`` is a false positive
  88. when the balance is zero but access is live (renewal pending)."""
  89. return not self.paid_access
  90. @property
  91. def is_usage_window(self) -> bool:
  92. """A usage-window plan with at least one allowance that stops every paid model."""
  93. return self.denominator_kind == "usage_window" and bool(all_scope(self.gauges))
  94. @property
  95. def binding_gauge(self) -> Optional[WindowGauge]:
  96. """The all-scope allowance that binds (see :func:`usage_gauges.binding_gauge`). Usage window only."""
  97. return binding_gauge(self.gauges) if self.is_usage_window else None
  98. @property
  99. def top_tier_gauge(self) -> Optional[WindowGauge]:
  100. return top_tier_gauge(self.gauges) if self.is_usage_window else None
  101. @property
  102. def used_fraction(self) -> Optional[float]:
  103. """Fraction of the cap consumed in [0.0, 1.0]; None without a computable denominator.
  104. Credit-grant: guarded on the LIMIT FIELD (the real denominator), not ``denominator_kind``.
  105. Usage window: the binding all-scope allowance (whichever stops every model first)."""
  106. if self.is_usage_window:
  107. return self.binding_gauge.used_fraction # type: ignore[union-attr]
  108. lim = self.subscription_limit_micros
  109. if not isinstance(lim, int) or lim <= 0:
  110. return None
  111. return max(0.0, min(1.0, (lim - self.subscription_micros) / lim))
  112. @property
  113. def window_resets_at_ms(self) -> Optional[int]:
  114. """Reset instant of the binding allowance."""
  115. g = self.binding_gauge
  116. return g.resets_at_ms if g is not None else None
  117. @property
  118. def top_tier_resets_at_ms(self) -> Optional[int]:
  119. g = self.top_tier_gauge
  120. return g.resets_at_ms if g is not None else None
  121. @property
  122. def top_tier_used_bp(self) -> Optional[int]:
  123. g = self.top_tier_gauge
  124. return g.used_bp if g is not None else None
  125. @property
  126. def window_exhausted(self) -> bool:
  127. """An allowance that stops every paid model is full. Paused (payment) is NOT exhausted: nothing was spent."""
  128. return self.is_usage_window and any(g.full for g in all_scope(self.gauges))
  129. @property
  130. def top_tier_exhausted(self) -> bool:
  131. """The top-tier allowance is full (a percent, like the others — not a blocked flag)."""
  132. g = self.top_tier_gauge
  133. return g is not None and g.full
  134. # ── Credits policy constants. Switching notices sticky→TTL later also needs a
  135. # paired *_TTL_MS per notice kind (AgentNotice has the field; not plumbed yet).
  136. CREDITS_NOTICE_KIND = "sticky" # v1: credits notices are sticky
  137. CREDITS_RESTORED_TTL_MS = 8000 # the only TTL notice in v1 (depletion-recovery confirmation)
  138. # Usage-gauge bands (ascending): (threshold_fraction, level, label_pct). One
  139. # escalating line shows the HIGHEST band reached; climbing replaces it, recovery steps down.
  140. CREDITS_USAGE_BANDS: tuple[tuple[float, str, int], ...] = ((0.50, "info", 50), (0.75, "warn", 75), (0.90, "warn", 90))
  141. CREDITS_USAGE_KEY = "credits.usage"
  142. # Min subscription balance counting as "grant not yet spent" for the grant_spent
  143. # gate. 1¢: portal-seeded states (float dollars → micros) can carry sub-cent residue
  144. # where headers report 0 — without the floor a seed opens the gate and the first
  145. # header re-creates the at-open nag.
  146. GRANT_UNSPENT_MIN_MICROS = 10_000
  147. # Usage-window notice keys. ``credits.window_payg`` is the one-shot "now spending top-up credits" line;
  148. # ``credits.depleted`` is reused for the hard stop so the TUI/desktop native-notification mapping
  149. # (keyed on ``credits.depleted`` / ``credits.restored``) keeps working without a client change.
  150. CREDITS_WINDOW_PAYG_KEY = "credits.window_payg"
  151. CREDITS_DEPLETED_KEY = "credits.depleted"
  152. # A window plan's limit line (day / week / month / top-tier used up, credits won't pay). Its own key so the
  153. # desktop can leave it to the refused turn's error card, which says the same sentence with buttons; the
  154. # CLI and TUI show it like any other notice. Payment-paused and depleted stay on ``credits.depleted``.
  155. CREDITS_WINDOW_LIMIT_KEY = "credits.window_limit"
  156. CREDITS_RESTORED_KEY = "credits.restored"
  157. CREDITS_GRANT_SPENT_KEY = "credits.grant_spent"
  158. _DEPLETED_TEXT = "✕ Credit access paused · run /topup to top up"
  159. _PAUSED_TEXT = "✕ Included usage paused · your subscription payment failed · update your card, or add credits in /topup to keep going"
  160. _PAUSED_OTHER_TEXT = "✕ Included usage paused · see Billing in the Portal, or add credits in /topup to keep going"
  161. _TOP_TIER_LIMIT = "You've hit your monthly large-model limit"
  162. _AUTO_TOP_UP_SUFFIX = " · auto top-up is on"
  163. def new_credits_latch() -> dict:
  164. """Fresh notice latch for :func:`evaluate_credits_notices`; every producer builds it here so a new gate key lands everywhere."""
  165. return {"active": set(), "seen_below_90": False, "usage_band": None, "seen_grant_unspent": False, "texts": {}}
  166. def format_window_reset(resets_at_ms: Optional[int], now_ms: Optional[int] = None) -> str:
  167. """Local-time reset for notices: ``HH:MM`` within 24h, ``Tue HH:MM`` within a week, ``Nov 3`` beyond (the
  168. monthly large-model allowance), ``shortly`` once passed (the server rolls the clock on the next request, so a stale
  169. stamp is never contradicted)."""
  170. if not isinstance(resets_at_ms, int) or resets_at_ms <= 0:
  171. return "the next reset"
  172. now = int(time.time() * 1000) if now_ms is None else now_ms
  173. if resets_at_ms <= now:
  174. return "shortly"
  175. try:
  176. stamp = time.localtime(resets_at_ms / 1000)
  177. except (ValueError, OverflowError, OSError):
  178. return "the next reset"
  179. left = resets_at_ms - now
  180. if left >= 7 * 24 * 3600 * 1000:
  181. return f"{time.strftime('%b', stamp)} {stamp.tm_mday}"
  182. return time.strftime("%H:%M" if left < 24 * 3600 * 1000 else "%a %H:%M", stamp)
  183. def _resets(resets_at_ms: Optional[int]) -> str:
  184. """`` · resets 15:56``; empty when the instant is unknown."""
  185. return f" · resets {format_window_reset(resets_at_ms)}" if isinstance(resets_at_ms, int) and resets_at_ms > 0 else ""
  186. def _spent_window(state: CreditsState) -> tuple[str, Optional[int]]:
  187. """The binding allowance's limit name (``daily``; an unknown id: the server's label) and its reset."""
  188. g = state.binding_gauge
  189. return (gauge_limit_name(g), g.resets_at_ms) if g is not None else ("daily", None)
  190. # A window plan's approach warning: once per allowance per reset, at this fraction (the 50 / 75 bands are
  191. # noise on a plan whose gauges reset daily). The percent always comes from the server.
  192. WINDOW_APPROACH_FRACTION = 0.90
  193. CREDITS_WINDOW_APPROACH_PREFIX = "credits.window."
  194. WINDOW_APPROACH_TTL_MS = 10_000
  195. def window_approach_key(gauge_id: str) -> str:
  196. """``credits.window.<gauge id>``: one key per allowance, so a client replaces it in place."""
  197. return CREDITS_WINDOW_APPROACH_PREFIX + gauge_id
  198. def _window_approach_text(g: WindowGauge) -> str:
  199. """``⚠ 90% of your weekly limit used · resets Thu 09:00``."""
  200. pct = min(99, int(g.used_fraction * 100))
  201. return f"⚠ {pct}% of your {gauge_limit_name(g)} limit used{_resets(g.resets_at_ms)}"
  202. def _stop_gauge(state: CreditsState, *, model_is_top_tier: Optional[bool]) -> Optional[WindowGauge]:
  203. """The full allowance behind the limit line, by :func:`agent.plan_limits.blocking_gauge` (the rule
  204. ``limit_hit`` reads, so the line, the retry time and the card agree). A full top-tier allowance counts only on
  205. a refusal: the API stamps ``spend-source`` on every admitted request and never on a 402, so header-sourced
  206. + no source = this model was refused; an ``included`` source means the model is not top-tier and a seed
  207. cannot know the model. A refusal no all-scope allowance explains is the top-tier one (a cold catalog).
  208. ``model_is_top_tier=None`` (tier unknown) counts the top-tier allowance as one that may stop the model, so
  209. of several full ones the later reset wins and no retry is promised before the model can run."""
  210. if not state.is_usage_window:
  211. return None
  212. from agent.plan_limits import blocking_gauge
  213. refused = state.from_header and state.spend_source is None
  214. g = blocking_gauge("", state.gauges, free=False, top_tier=refused and model_is_top_tier is not False)
  215. if g is None and refused and state.top_tier_exhausted:
  216. return state.top_tier_gauge
  217. return g
  218. def _window_hard_stop(state: CreditsState, *, model_is_free: bool, model_is_top_tier: Optional[bool] = False) -> Optional[str]:
  219. """Blocking copy for a usage-window account, or None. ``paid_access`` is the portal's word (dunning);
  220. then: payment paused with no credits (credits keep a paused plan going whatever the setting says; a
  221. card update restores included usage), the large-model allowance used with no pay path, the window used with no
  222. pay path. A free model keeps inferencing, so only the payment-paused line survives it.
  223. The credits step comes from :func:`agent.plan_limits.credits_action`, the rule every limit surface reads."""
  224. purchased = state.purchased_micros
  225. if state.paused_reason and purchased <= 0:
  226. return _PAUSED_TEXT if paused_for_payment(state.paused_reason) else _PAUSED_OTHER_TEXT
  227. if not state.paid_access:
  228. return None if model_is_free else _DEPLETED_TEXT
  229. if model_is_free or state.credits_pay:
  230. return None
  231. if state.unmetered:
  232. return None
  233. from agent.plan_limits import credits_action
  234. action = _CREDITS_STEP[credits_action(state.keep_going_on_credits, purchased)]
  235. g = _stop_gauge(state, model_is_top_tier=model_is_top_tier)
  236. if g is None:
  237. return None
  238. if g.scope == SCOPE_TOP_TIER:
  239. auto = _AUTO_TOP_UP_SUFFIX if state.auto_top_up_enabled and action == _ADD_CREDITS_ACTION else ""
  240. return f"✕ {_TOP_TIER_LIMIT}{_resets(g.resets_at_ms)} · {action}{auto}"
  241. return f"✕ You've hit your {gauge_limit_name(g)} limit{_resets(g.resets_at_ms)} · {action}"
  242. def window_stop_resets_at_ms(state: CreditsState, *, model_is_top_tier: Optional[bool] = False) -> Optional[int]:
  243. """When the allowance behind :func:`_window_hard_stop`'s limit line frees up (the same gauge)."""
  244. if state.unmetered:
  245. return None
  246. g = _stop_gauge(state, model_is_top_tier=model_is_top_tier)
  247. return g.resets_at_ms if g is not None else None
  248. # "Keep going on credits": the account setting (/topup or Portal billing), off by default on a window plan.
  249. _ADD_CREDITS_ACTION = "/topup to add credits"
  250. _CREDITS_STEP = { # keyed by agent.plan_limits.credits_action
  251. "use_credits": "turn on Keep going in /topup",
  252. "add_credits": _ADD_CREDITS_ACTION,
  253. "add_credits_and_keep_going": "add credits and turn on Keep going in /topup",
  254. }
  255. def _window_payg_text(state: CreditsState) -> Optional[str]:
  256. """The one-shot PAYG line: the last request drew on top-up credits instead of the window. None otherwise."""
  257. if not (state.spend_source == "payg" and state.purchased_micros > 0):
  258. return None
  259. if state.window_exhausted:
  260. name, resets = _spent_window(state)
  261. text = f"• You've hit your {name} limit{_resets(resets)} · now using credits"
  262. elif state.top_tier_exhausted:
  263. text = f"• {_TOP_TIER_LIMIT}{_resets(state.top_tier_resets_at_ms)} · large models now use credits"
  264. else:
  265. text = "• Now using credits"
  266. return text + (_AUTO_TOP_UP_SUFFIX if state.auto_top_up_enabled else "")
  267. def _reconcile_sticky(key: str, text: Optional[str], level: str, latch: dict, to_show: list, to_clear: list) -> None:
  268. """Show / replace / clear one sticky line by key: a text change re-emits (clear first), None clears."""
  269. active, texts = latch["active"], latch.setdefault("texts", {})
  270. if text is not None and (key not in active or texts.get(key) != text):
  271. if key in active:
  272. to_clear.append(key)
  273. to_show.append(_sticky_notice(text, level, key))
  274. active.add(key)
  275. texts[key] = text
  276. elif text is None and key in active:
  277. to_clear.append(key)
  278. active.discard(key)
  279. texts.pop(key, None)
  280. def _evaluate_window_notices(state: CreditsState, latch: dict, *, model_is_free: bool,
  281. model_is_top_tier: bool = False) -> tuple[list, list]:
  282. """Notice policy for a usage-window account (see :func:`evaluate_credits_notices` for the contract).
  283. Approach: each allowance warns once at 90% per reset (``credits.window.<id>``, a TTL heads-up; the
  284. limit line takes over when it runs out). The top-tier allowance warns only while the session is on a
  285. top-tier model (no other model moves it); a free model warns about nothing. grant_spent never fires (no
  286. grant); a payment pause / depleted account reuses ``credits.depleted`` and its ``credits.restored``."""
  287. to_show: list = []
  288. to_clear: list = []
  289. active = latch["active"]
  290. warned: dict = latch.setdefault("window_warned", {})
  291. if CREDITS_USAGE_KEY in active: # the credit-grant band does not apply to a window plan
  292. _reconcile_sticky(CREDITS_USAGE_KEY, None, "info", latch, to_show, to_clear)
  293. latch["usage_band"] = None
  294. for g in state.gauges:
  295. relevant = not model_is_free and (g.scope != SCOPE_TOP_TIER or model_is_top_tier)
  296. if relevant and not g.full and g.used_fraction >= WINDOW_APPROACH_FRACTION \
  297. and warned.get(g.id) != g.resets_at_ms:
  298. # A heads-up, not a state: shown once (TTL) and never re-shown for the same reset.
  299. warned[g.id] = g.resets_at_ms
  300. key = window_approach_key(g.id)
  301. to_show.append(AgentNotice(text=_window_approach_text(g), level="warn", kind="ttl",
  302. ttl_ms=WINDOW_APPROACH_TTL_MS, key=key, id=key))
  303. if CREDITS_GRANT_SPENT_KEY in active: # a plan flip mid-session: the grant line has no meaning here
  304. to_clear.append(CREDITS_GRANT_SPENT_KEY)
  305. active.discard(CREDITS_GRANT_SPENT_KEY)
  306. stop = _window_hard_stop(state, model_is_free=model_is_free, model_is_top_tier=model_is_top_tier)
  307. limit = stop is not None and stop not in (_PAUSED_TEXT, _PAUSED_OTHER_TEXT, _DEPLETED_TEXT)
  308. was_stopped = CREDITS_DEPLETED_KEY in active or CREDITS_WINDOW_LIMIT_KEY in active
  309. _reconcile_sticky(CREDITS_WINDOW_LIMIT_KEY, stop if limit else None, "error", latch, to_show, to_clear)
  310. _reconcile_sticky(CREDITS_DEPLETED_KEY, None if limit else stop, "error", latch, to_show, to_clear)
  311. if was_stopped and stop is None and state.paid_access and not model_is_free:
  312. # Genuine recovery (a reset, a top-up, a paid renewal) — a free-model switch is not "restored".
  313. to_show.append(AgentNotice(text="✓ Credit access restored", level="success", kind="ttl",
  314. ttl_ms=CREDITS_RESTORED_TTL_MS, key=CREDITS_RESTORED_KEY, id=CREDITS_RESTORED_KEY))
  315. _reconcile_sticky(CREDITS_WINDOW_PAYG_KEY, None if stop else _window_payg_text(state), "warn", latch, to_show, to_clear)
  316. return (to_show, to_clear)
  317. @dataclass
  318. class AgentNotice:
  319. """Driver-agnostic out-of-band notice (``AIAgent.notice_callback`` / ``notice_clear_callback``); each driver
  320. renders its own way. ``kind``/``ttl_ms`` stay expressive so a future config can switch v1's sticky notices to TTL."""
  321. text: str
  322. level: str = "info" # info | warn | error | success
  323. kind: str = "sticky" # sticky | ttl
  324. ttl_ms: Optional[int] = None # honored only when kind == "ttl"
  325. key: Optional[str] = None # dedupe / fired-once-latch / clear key
  326. id: Optional[str] = None
  327. def _sticky_notice(text: str, level: str, key: str) -> AgentNotice:
  328. return AgentNotice(text=text, level=level, kind=CREDITS_NOTICE_KIND, key=key, id=key)
  329. def _is_nous_welcome_route(base_url: str) -> bool:
  330. """True when *base_url* is the Nous welcome host, which serves only the free tier. Local data only;
  331. False wherever the free tier is not built in. The host is the evidence, not the model name: the paid
  332. inference host can serve ``nous/welcome`` to a named account, and that account's depletion is real."""
  333. try:
  334. from hermes_cli.anon_auth import route_is_welcome_host
  335. except ImportError:
  336. return False
  337. return route_is_welcome_host(base_url)
  338. def is_free_tier_model(model: str, base_url: str = "") -> bool:
  339. """True when *model* is a Nous free-tier model, using ONLY local data: (1) ``:free`` suffix — canonical
  340. Nous free SKU marker; (2) ``stealth/`` prefix — stealth-preview SKUs are free without the suffix
  341. (naming-convention trust: a PAID ``stealth/`` model would wrongly suppress the banner); (3) a PEEK into
  342. ``hermes_cli.models``' pricing cache (filled by the model picker; a miss never fetches). Fail-open to
  343. False (depleted notice still shows): a wrong warning is recoverable noise; hiding it masks a real block."""
  344. if not model:
  345. return False
  346. if model.endswith(":free") or model.startswith("stealth/"):
  347. return True
  348. if not base_url:
  349. return False
  350. # (4) the Nous free tier: the welcome host serves only the free tier. A free-tier identity carries $0
  351. # by design, so the portal seed reports paid_access=False for it; that is not a depleted account, and
  352. # "run /topup" means nothing to it. Local data only, same as the rules above.
  353. if _is_nous_welcome_route(base_url):
  354. return True
  355. try:
  356. from hermes_cli.models import _is_model_free
  357. from hermes_cli.models_pricing import peek_cached_pricing
  358. pricing = peek_cached_pricing(base_url) # owns the /v1-suffix and auth-state key details
  359. return bool(pricing) and _is_model_free(model, pricing)
  360. except Exception:
  361. return False
  362. def evaluate_credits_notices(state: CreditsState, latch: dict, *, model_is_free: bool = False,
  363. model_is_top_tier: bool = False) -> tuple[list[AgentNotice], list[str]]:
  364. """Reconcile credits notices against the latch (see :func:`new_credits_latch`); mutates ``latch`` IN
  365. PLACE. Pure — no I/O, no agent/run_agent imports. ``model_is_free`` suppresses ``credits.depleted`` (a
  366. depleted account on a free model keeps inferencing) WITHOUT emitting "restored" — that fires only on a
  367. genuine ``paid_access`` flip back to True. Returns ``(to_show, to_clear)``; caller emits to_clear FIRST.
  368. A usage-window state (day/week percents, no grant) takes the window policy; everything else is unchanged."""
  369. if state.is_usage_window:
  370. return _evaluate_window_notices(state, latch, model_is_free=model_is_free,
  371. model_is_top_tier=model_is_top_tier)
  372. to_show: list[AgentNotice] = []
  373. to_clear: list[str] = []
  374. uf, active = state.used_fraction, latch["active"]
  375. for window_key in (CREDITS_WINDOW_PAYG_KEY, CREDITS_WINDOW_LIMIT_KEY):
  376. if window_key in active: # only ever set by the window policy; a stale line after a plan change
  377. to_clear.append(window_key)
  378. active.discard(window_key)
  379. latch.get("texts", {}).pop(window_key, None)
  380. # Crossing latch: band notices fire only once uf was observed below the LOWEST
  381. # band, so a session opening mid-range doesn't fire on its first observation
  382. # (the cold-start seed primes this when it WANTS an open-high warning).
  383. if uf is not None and uf < CREDITS_USAGE_BANDS[0][0]:
  384. latch["seen_below_90"] = True
  385. # Grant-spent gate: fires only after this session OBSERVED the grant unspent
  386. # (≥1¢). Opening at grant-spent is a steady STATE (/usage carries it), not an
  387. # event. Unlike seen_below_90, seeds must NOT prime this gate.
  388. if uf is not None and uf < 1.0 and state.subscription_micros >= GRANT_UNSPENT_MIN_MICROS:
  389. latch["seen_grant_unspent"] = True
  390. # Highest band reached (ascending → last match wins); None below all. Top-up
  391. # suppression: with purchased credits the cap gauge is the wrong denominator
  392. # ("90% used" on $50 of top-up is noise; it used to stick PERMANENTLY beside
  393. # grant_spent at >=100%) — grant_spent covers the cap-reached case, and a
  394. # mid-session top-up flips current_band → None so the clear path removes the line.
  395. current_band: Optional[tuple[float, str, int]] = None
  396. if uf is not None and state.purchased_micros <= 0:
  397. current_band = next((b for b in reversed(CREDITS_USAGE_BANDS) if uf >= b[0]), None)
  398. # ── usage gauge: highest crossed band only; replace on band change (climb or
  399. # step-down); clear below the lowest band or when the denominator vanishes.
  400. target_band = current_band[2] if (current_band and latch["seen_below_90"]) else None
  401. if target_band != latch.get("usage_band"):
  402. if CREDITS_USAGE_KEY in active:
  403. to_clear.append(CREDITS_USAGE_KEY)
  404. active.discard(CREDITS_USAGE_KEY)
  405. if target_band is not None:
  406. # Absolute dollars used (a bare "N%" is only meaningful against a Nous cap): cap − remaining,
  407. # clamped [0, cap]; "$?" if a producer set the limit without its *_usd. Re-emits on band change only.
  408. level = current_band[1] # type: ignore[index] (current_band set when target_band set)
  409. lim = state.subscription_limit_micros or 0
  410. used_usd = f"{max(0, min(lim, lim - state.subscription_micros)) / 1_000_000:.2f}" if lim else "?"
  411. text = f"{'⚠' if level == 'warn' else '•'} You've used ${used_usd} of your ${state.subscription_limit_usd or '?'} cap"
  412. to_show.append(_sticky_notice(text, level, CREDITS_USAGE_KEY))
  413. active.add(CREDITS_USAGE_KEY)
  414. latch["usage_band"] = target_band
  415. # ── grant_spent: the gate guards only the SHOW and is CONSUMED by it — one
  416. # announcement per crossing. A header flicker (uf → None → 1.0) clears the
  417. # line but cannot re-announce; only a renewal re-opening the gate (fresh ≥1¢
  418. # observation) arms the next. .get(): default closed for hand-built latches.
  419. grant_cond = (
  420. state.denominator_kind == "subscription_cap" and uf is not None and uf >= 1.0 and state.purchased_micros > 0
  421. )
  422. if grant_cond and "credits.grant_spent" not in active and latch.get("seen_grant_unspent", False):
  423. to_show.append(_sticky_notice(f"• Grant spent · ${state.purchased_usd} top-up left", "info", "credits.grant_spent"))
  424. active.add("credits.grant_spent")
  425. latch["seen_grant_unspent"] = False
  426. elif "credits.grant_spent" in active and not grant_cond:
  427. to_clear.append("credits.grant_spent")
  428. active.discard("credits.grant_spent")
  429. # ── depleted: suppressed while the model is free (inference still works).
  430. depleted_cond = not state.paid_access
  431. show_depleted = depleted_cond and not model_is_free
  432. if show_depleted and "credits.depleted" not in active:
  433. to_show.append(_sticky_notice("✕ Credit access paused · run /topup to top up", "error", "credits.depleted"))
  434. active.add("credits.depleted")
  435. elif "credits.depleted" in active and not show_depleted:
  436. to_clear.append("credits.depleted")
  437. active.discard("credits.depleted")
  438. if not depleted_cond: # genuine recovery only — a free-model switch while depleted is NOT "restored"
  439. to_show.append(AgentNotice(
  440. text="✓ Credit access restored", level="success", kind="ttl",
  441. ttl_ms=CREDITS_RESTORED_TTL_MS, key="credits.restored", id="credits.restored",
  442. ))
  443. return (to_show, to_clear)
  444. # Header contract: (field, kind[, default-when-absent]); a field is REQUIRED unless it has a default.
  445. # Header name = ``x-nous-credits-<field>`` (``x-nous-<field>`` for tool_pool_*), underscores → dashes.
  446. # micros: int >= 0 ("signed": may be negative; "bp": 0..10000); usd: the server's formatted string ^-?\d+\.\d{2}$
  447. # (never re-parsed); bool: "true"/"false" STRING. Handled inline: subscription-limit-* (PAIRED/optional),
  448. # denominator-kind ("subscription_cap" | "none"), disabled-reason (omitted when null).
  449. _HEADER_FIELDS: tuple[tuple, ...] = (
  450. ("remaining_micros", "micros"), ("subscription_micros", "signed"), ("rollover_micros", "micros"),
  451. ("purchased_micros", "micros"), ("as_of_ms", "micros"), ("tool_pool_micros", "micros", 0),
  452. ("remaining_usd", "usd"), ("subscription_usd", "usd"), ("purchased_usd", "usd"),
  453. ("paid_access", "bool", True), # absent → fail-open (assume access)
  454. ("tool_pool_gated_off", "bool", False),
  455. )
  456. # Credit-grant plan fields. Required on a credit note; a usage_window note may omit them (the server can
  457. # retire them with legacy plans). Malformed is still a miss. The top-up balance (purchased_*) is optional on a
  458. # window note too: a refused (402) request carries only the window headers; the capture keeps the last balance.
  459. _GRANT_ONLY_FIELDS = frozenset({
  460. "remaining_micros", "remaining_usd", "subscription_micros", "subscription_usd", "rollover_micros", "as_of_ms",
  461. })
  462. _WINDOW_OPTIONAL_FIELDS = _GRANT_ONLY_FIELDS | {"purchased_micros", "purchased_usd"}
  463. # Usage-window headers, read only when ``denominator-kind`` is ``usage_window``: the gauge list
  464. # (``x-nous-credits-window-gauges``, REQUIRED: a note that names the kind but has no readable list is a
  465. # miss), plus the optional ``-spend-source`` / ``-window-paused-reason`` / ``-keep-going-on-credits``.
  466. _GAUGES_HEADER = "x-nous-credits-window-gauges"
  467. def _header_name(field: str) -> str:
  468. return "x-nous-" + ("" if field.startswith("tool_pool_") else "credits-") + field.replace("_", "-")
  469. def _parse_window_fields(lowered: Mapping[str, str]) -> Optional[dict[str, Any]]:
  470. """Usage-window fields from lowercased headers; None when the gauge list is absent or unreadable.
  471. ``spend_source`` outside its vocabulary reads as absent (fail-open)."""
  472. gauges = parse_gauges(lowered.get(_GAUGES_HEADER))
  473. if gauges is None or not all_scope(gauges):
  474. return None
  475. out: dict[str, Any] = {"gauges": gauges}
  476. source = lowered.get("x-nous-credits-spend-source")
  477. out["spend_source"] = source if source in _VALID_SPEND_SOURCES else None
  478. paused = lowered.get("x-nous-credits-window-paused-reason")
  479. out["paused_reason"] = paused.strip() if isinstance(paused, str) and paused.strip() else None
  480. keep_going = (lowered.get("x-nous-credits-keep-going-on-credits") or "").strip().lower()
  481. out["keep_going_on_credits"] = {"on": True, "off": False}.get(keep_going) # anything else: unknown (older server)
  482. return out
  483. def _parse_field(kind: str, raw: Optional[str], default: Any = _SENTINEL) -> Any:
  484. """One header value → field value; ``default`` when absent, ``_SENTINEL`` on a contract violation."""
  485. if raw is None:
  486. return default
  487. if kind in ("micros", "signed", "bp"):
  488. val = _safe_int(raw)
  489. if val is _SENTINEL or (kind != "signed" and val < 0):
  490. return _SENTINEL
  491. # bp: basis points of a window, 0..10000 inclusive (anything past is a violation).
  492. return _SENTINEL if kind == "bp" and val > BP_FULL else val
  493. if kind == "usd":
  494. return raw if _USD_RE.match(raw) else _SENTINEL
  495. flag = raw.strip().lower()
  496. return _SENTINEL if flag not in ("true", "false") else flag == "true"
  497. def parse_credits_headers(headers: Mapping[str, str], provider: str = "") -> Optional[CreditsState]:
  498. """Parse x-nous-credits-* (and x-nous-tool-pool-*) headers into a CreditsState.
  499. None (miss) on ANY of: no version header; version != 1 (> 1 also warns once);
  500. a required field violating ``_HEADER_FIELDS``; unknown ``denominator_kind``;
  501. any unexpected exception. Fail-open on the subscription_limit pair: a
  502. half-pair (only -micros or only -usd) parses as both-absent (both None)."""
  503. global _version_warning_emitted
  504. try:
  505. # Cheap probe before the lowercase copy (header names are case-insensitive): bail when the
  506. # version header is absent — the hot path for non-Nous providers.
  507. if not any(k.lower() == "x-nous-credits-version" for k in headers):
  508. return None
  509. lowered = {k.lower(): v for k, v in headers.items()}
  510. version_val = _safe_int(lowered.get("x-nous-credits-version"))
  511. if version_val is _SENTINEL:
  512. return None
  513. if version_val != 1:
  514. if version_val > 1 and not _version_warning_emitted:
  515. _version_warning_emitted = True
  516. logger.warning("credits header version %d unsupported, ignoring — update Hermes", version_val)
  517. return None
  518. denominator_kind = lowered.get("x-nous-credits-denominator-kind", "none")
  519. window_note = denominator_kind == "usage_window"
  520. fields: dict[str, Any] = {}
  521. for name, kind, *default in _HEADER_FIELDS:
  522. raw = lowered.get(_header_name(name))
  523. if raw is None and window_note and name in _WINDOW_OPTIONAL_FIELDS:
  524. continue # a window note may drop these: dataclass default
  525. fields[name] = _parse_field(kind, raw, *default)
  526. lim_micros_raw = lowered.get("x-nous-credits-subscription-limit-micros")
  527. lim_usd_raw = lowered.get("x-nous-credits-subscription-limit-usd")
  528. if lim_micros_raw is not None and lim_usd_raw is not None:
  529. fields["subscription_limit_micros"] = _parse_field("micros", lim_micros_raw)
  530. fields["subscription_limit_usd"] = _parse_field("usd", lim_usd_raw)
  531. if _SENTINEL in fields.values() or denominator_kind not in _VALID_DENOMINATOR_KINDS:
  532. return None
  533. if window_note:
  534. window = _parse_window_fields(lowered)
  535. if window is None:
  536. return None
  537. fields.update(window)
  538. disabled_reason = lowered.get("x-nous-credits-disabled-reason") # None if absent (omitted when null)
  539. return CreditsState(version=version_val, denominator_kind=denominator_kind, disabled_reason=disabled_reason,
  540. captured_at=time.time(), from_header=True, **fields)
  541. except Exception: # fail-open → miss; the breadcrumb distinguishes a parser regression from a no-headers response
  542. logger.debug("credits ▸ parse_credits_headers raised (fail-open miss)", exc_info=True)
  543. return None
  544. def response_is_usage_window(http_response: Any) -> bool:
  545. """True iff *http_response* carries complete usage-window ``x-nous-credits-*`` headers (the same
  546. test as ``CreditsState.is_usage_window``). Lets the window-only header captures leave every other
  547. account untouched. Never raises."""
  548. try:
  549. headers = getattr(http_response, "headers", None) if http_response is not None else None
  550. if not headers:
  551. return False
  552. state = parse_credits_headers(headers)
  553. return state is not None and state.is_usage_window
  554. except Exception:
  555. logger.debug("Usage-window header parse failed", exc_info=True)
  556. return False
  557. # ── Dev fixtures (HERMES_DEV_CREDITS_FIXTURE): throwaway scaffolding to trigger any notice state
  558. # without real spend. Value is a state NAME or a FILE PATH whose contents are a name (re-read every
  559. # turn → `echo depleted > /tmp/cf` flips live). Drives per-turn notices, the cold-start seed, and /usage.
  560. def _fixture(remaining: str, subscription: str, limit: Optional[str] = None, purchased: Optional[str] = None,
  561. *, paid: bool = True, reason: Optional[str] = None) -> dict:
  562. """Fixture spec from *_usd strings; micros derived exactly (Decimal)."""
  563. d: dict = {}
  564. for field, usd in (("remaining", remaining), ("subscription", subscription), ("subscription_limit", limit), ("purchased", purchased)):
  565. if usd is not None:
  566. d[f"{field}_micros"], d[f"{field}_usd"] = int(Decimal(usd) * 1_000_000), usd
  567. if limit is not None:
  568. d["denominator_kind"] = "subscription_cap"
  569. d["paid_access"] = paid
  570. return d if reason is None else {**d, "disabled_reason": reason}
  571. _DEV_FIXTURES: dict[str, dict] = {
  572. "healthy": _fixture("30.34", "18.00", "20.00", "12.34"), # used_fraction ~0.1, paid → no notice (recovery target)
  573. "sub_50pct": _fixture("10.00", "10.00", "20.00"), # used_fraction == 0.5 → credits.usage band 50 (info)
  574. "sub_75pct": _fixture("5.00", "5.00", "20.00"), # used_fraction == 0.75 → band 75 (warn)
  575. "sub_90pct": _fixture("2.00", "2.00", "20.00"), # used_fraction == 0.9 → band 90 (warn)
  576. # uf == 1.0 + purchased>0 → SILENT at open (crossing-gated); flip healthy →
  577. # grant_exhausted via the fixture-file path to see credits.grant_spent
  578. "grant_exhausted": _fixture("12.34", "0.00", "20.00", "12.34"),
  579. "depleted": _fixture("0.00", "0.00", None, "0.00", paid=False, reason="out_of_credits"), # → credits.depleted
  580. # subscription in debt (negative, the only signed field) → depleted
  581. "debt": _fixture("0.00", "-5.00", "20.00", "0.00", paid=False, reason="out_of_credits"),
  582. }
  583. def dev_fixture_credits_state() -> Optional[CreditsState]:
  584. """Fixture CreditsState for HERMES_DEV_CREDITS_FIXTURE, or None (unknown name / unset). Prod-leak guard:
  585. applies ONLY when HERMES_DEV_CREDITS is also on, so a stray fixture env var never surfaces fabricated balances."""
  586. name = os.environ.get("HERMES_DEV_CREDITS_FIXTURE", "").strip()
  587. if not name or not is_truthy_value(os.environ.get("HERMES_DEV_CREDITS")):
  588. return None
  589. if os.path.sep in name or "/" in name: # looks like a path → read the name from the file
  590. try:
  591. with open(name, "r", encoding="utf-8-sig") as fh:
  592. name = fh.read().strip()
  593. except OSError:
  594. return None
  595. if not (spec := _DEV_FIXTURES.get(name.lower())):
  596. return None
  597. # Stamp what the REAL parser always guarantees so a fixture is field-identical to a
  598. # parse_credits_headers() result: version 1 and a valid purchased_usd (zero top-up = "0.00").
  599. return CreditsState(**{"version": 1, "purchased_usd": "0.00", **spec}, from_header=True, captured_at=time.time())
  600. def _credits_state_from_account(info) -> Optional[CreditsState]:
  601. """Map a NousPortalAccountInfo into a header-shaped CreditsState for the seed. Float account dollars →
  602. micros plus a DISPLAY *_usd (formatting account floats is allowed; parsing a server *_usd is not). Fail-open → None."""
  603. try:
  604. acc = getattr(info, "paid_service_access_info", None)
  605. sub = getattr(info, "subscription", None)
  606. def _money(dollars) -> tuple[int, str]: # (micros, display usd); (0, "") when absent
  607. return (round(dollars * 1_000_000), f"{dollars:.2f}") if isinstance(dollars, (int, float)) else (0, "")
  608. fields: dict[str, Any] = {}
  609. for prefix, attr in (("remaining", "total_usable_credits"), ("subscription", "subscription_credits_remaining"),
  610. ("purchased", "purchased_credits_remaining")):
  611. fields[f"{prefix}_micros"], fields[f"{prefix}_usd"] = _money(getattr(acc, attr, None))
  612. monthly = getattr(sub, "monthly_credits", None)
  613. cap = _money(monthly) if isinstance(monthly, (int, float)) and monthly > 0 else (None, None)
  614. paid = getattr(info, "paid_service_access", None)
  615. window = _window_seed_fields(getattr(info, "usage_window", None))
  616. if window is not None:
  617. # A usage-window account: the gauge is the window, the grant fields are meaningless (kept 0).
  618. fields["subscription_micros"], fields["subscription_usd"] = 0, "0.00"
  619. cap = (None, None)
  620. return CreditsState(
  621. **fields, subscription_limit_micros=cap[0], subscription_limit_usd=cap[1], from_header=False, captured_at=time.time(),
  622. rollover_micros=_money(getattr(sub, "rollover_credits", None))[0], paid_access=paid if isinstance(paid, bool) else True,
  623. denominator_kind="usage_window" if window is not None else ("subscription_cap" if cap[0] is not None else "none"),
  624. **(window or {}),
  625. )
  626. except Exception:
  627. logger.debug("credits ▸ seed account→state mapping failed", exc_info=True)
  628. return None
  629. def _window_seed_fields(uw) -> Optional[dict[str, Any]]:
  630. """Portal ``usage_window`` (NousUsageWindowInfo or dict) → CreditsState window fields; None unless it
  631. carries a readable gauge list with an all-scope allowance (same requirement as the header parser)."""
  632. if uw is None:
  633. return None
  634. get = uw.get if isinstance(uw, dict) else (lambda k, d=None: getattr(uw, k, d))
  635. gauges = parse_gauges(get("gauges"))
  636. if gauges is None or not all_scope(gauges):
  637. return None
  638. out: dict[str, Any] = {"gauges": gauges}
  639. out["auto_top_up_enabled"] = get("auto_top_up_enabled") is True
  640. keep_going = get("keep_going_on_credits")
  641. out["keep_going_on_credits"] = keep_going if isinstance(keep_going, bool) else None
  642. paused = get("paused_reason")
  643. out["paused_reason"] = paused if isinstance(paused, str) and paused else None
  644. return out
  645. # Process-lifetime memory of the usage band last shown per session_id: see
  646. # _remember_shown_band. Bounded MRU so a long-lived gateway cannot grow it without limit.
  647. _seen_usage_bands: dict = {}
  648. _SEEN_USAGE_BANDS_MAX = 500
  649. def _remember_shown_band(session_id, band) -> None:
  650. """Remember the usage band last evaluated for ``session_id`` (process-lifetime).
  651. Desktop reap/resume rebuilds the AIAgent per turn, so the in-memory ``_credits_latch``
  652. (and its ``usage_band``) never survives across messages — every rebuild re-announces the
  653. current band as a fresh crossing (#101578). ``agent.session_id`` IS stable across those
  654. rebuilds, so this map lets ``_hydrate_seed_state`` restore the band the user already saw.
  655. Deliberately NOT durable: a real process restart is a real ``session open`` and the
  656. cold-start seed should still warn immediately. Bounded (MRU eviction) so a long-lived
  657. gateway juggling many sessions cannot grow it without limit."""
  658. if not session_id:
  659. return
  660. _seen_usage_bands.pop(session_id, None) # re-insert at the MRU end
  661. _seen_usage_bands[session_id] = band
  662. if len(_seen_usage_bands) > _SEEN_USAGE_BANDS_MAX:
  663. _seen_usage_bands.pop(next(iter(_seen_usage_bands)))
  664. # Window plans: the same per-session memory for the window notices (limit / now-using-credits / paused lines
  665. # and the 90% heads-ups), so a rebuilt agent does not re-show a line this session already showed.
  666. _WINDOW_NOTICE_KEYS = (CREDITS_WINDOW_PAYG_KEY, CREDITS_WINDOW_LIMIT_KEY, CREDITS_DEPLETED_KEY)
  667. _seen_window_notices: dict = {}
  668. def restore_window_notices(session_id, latch: dict) -> None:
  669. """Load what this session already showed into a fresh latch (once per latch). Never raises."""
  670. try:
  671. if not session_id or latch.get("window_restored"):
  672. return
  673. latch["window_restored"] = True
  674. saved = _seen_window_notices.get(session_id)
  675. if not saved:
  676. return
  677. texts = latch.setdefault("texts", {})
  678. for key, text in saved["texts"].items():
  679. if key not in latch["active"]:
  680. latch["active"].add(key)
  681. texts[key] = text
  682. latch.setdefault("window_warned", {}).update(saved["warned"])
  683. except Exception:
  684. logger.debug("window notice restore failed", exc_info=True)
  685. def apply_keep_going_change(agent, enabled: bool) -> None:
  686. """The user just changed "Keep going on credits": the agent's state takes the new value now (the next
  687. reply's headers confirm it) and the notice policy re-runs, so a "turn on Keep going" line clears at once.
  688. The account snapshot the pickers read is refreshed in the background. Never raises."""
  689. try:
  690. from dataclasses import replace
  691. state = getattr(agent, "_credits_state", None)
  692. if state is None or not state.is_usage_window:
  693. return
  694. agent._credits_state = replace(state, keep_going_on_credits=enabled)
  695. _rerun_notice_policy(agent)
  696. from agent.memory_provider import spawn_context_thread
  697. from hermes_cli.nous_account import get_nous_portal_account_info
  698. spawn_context_thread(lambda: get_nous_portal_account_info(force_fresh=True), name="keep-going-refresh").start()
  699. except Exception:
  700. logger.debug("keep going ▸ local refresh failed", exc_info=True)
  701. def forget_window_notices(session_id) -> None:
  702. """The session is no longer on a window plan: drop its saved lines. Never raises."""
  703. _seen_window_notices.pop(session_id, None)
  704. def remember_window_notices(session_id, latch: dict) -> None:
  705. """Record the window notices this session shows now (process lifetime, bounded MRU). Never raises."""
  706. try:
  707. if not session_id:
  708. return
  709. texts = latch.get("texts", {})
  710. entry = {"texts": {k: texts[k] for k in _WINDOW_NOTICE_KEYS if k in latch["active"] and k in texts},
  711. "warned": dict(latch.get("window_warned", {}))}
  712. _seen_window_notices.pop(session_id, None)
  713. _seen_window_notices[session_id] = entry
  714. if len(_seen_window_notices) > _SEEN_USAGE_BANDS_MAX:
  715. _seen_window_notices.pop(next(iter(_seen_window_notices)))
  716. except Exception:
  717. logger.debug("window notice remember failed", exc_info=True)
  718. def _hydrate_seed_state(agent, state) -> None:
  719. """Install a seed CreditsState on the agent and fire the notice policy once. Primes the crossing gate:
  720. the cold-start snapshot IS the first observation, so a session opening in a band warns immediately."""
  721. agent._credits_state = state
  722. if getattr(agent, "_credits_session_start_micros", None) is None:
  723. agent._credits_session_start_micros = state.remaining_micros
  724. latch = getattr(agent, "_credits_latch", None)
  725. if isinstance(latch, dict) and state.used_fraction is not None:
  726. latch["seen_below_90"] = True # ONLY this gate — priming seen_grant_unspent would revive the steady-state nag
  727. # Restore the band this logical session already showed (desktop reap/resume rebuilds the
  728. # agent object but keeps session_id) so an unchanged band is not re-announced per message.
  729. prior_band = _seen_usage_bands.get(getattr(agent, "session_id", None))
  730. if prior_band is not None:
  731. latch["usage_band"] = prior_band
  732. latch["active"].add(CREDITS_USAGE_KEY)
  733. _rerun_notice_policy(agent)
  734. def _rerun_notice_policy(agent) -> None:
  735. if callable(emit := getattr(agent, "_emit_credits_notices", None)):
  736. emit()
  737. def _warm_nous_pricing_cache() -> None:
  738. """Fill the in-process Nous pricing catalog so :func:`is_free_tier_model`'s peek can answer.
  739. The peek never fetches and nothing else warms it during session start, so a cold process reads
  740. an EMPTY catalog and a subscription-billed model — which spends no credits — still draws the
  741. depleted banner. Fail-open: a miss leaves the peek exactly as it was."""
  742. try:
  743. from hermes_cli.models_pricing import get_pricing_for_provider
  744. get_pricing_for_provider("nous")
  745. except Exception:
  746. logger.debug("credits ▸ nous pricing warm failed", exc_info=True)
  747. def rewarm_pricing_before_depleted_notice(agent) -> bool:
  748. """Depleted account, model the peek cannot vouch for, Nous catalog cold: start a background warm
  749. whose completion re-runs the policy and return True so the caller defers the depleted decision
  750. to it — the session-start warm is one-shot but the catalog expires after
  751. ``_NOUS_CATALOG_TTL_SECONDS``, and a cold peek would bring the banner back for a
  752. subscription-billed model. False = decide now: peek warm, not on Nous, a warm in flight (the
  753. warm's own re-run included — fail-open, a failed fetch leaves the peek cold and the banner
  754. shows), or a fetch already failed and the cache is still refusing to dial. May raise; the notice
  755. path that calls it catches."""
  756. base_url = getattr(agent, "base_url", "") or ""
  757. if getattr(agent, "provider", "") != "nous" or not base_url:
  758. return False
  759. from hermes_cli.models_pricing import peek_cached_pricing, pricing_fetch_suppressed
  760. if peek_cached_pricing(base_url) or pricing_fetch_suppressed(base_url):
  761. return False
  762. inflight = getattr(agent, "_credits_pricing_warm", None)
  763. if inflight is not None and inflight.is_alive():
  764. return False
  765. def _warm_then_rerun() -> None:
  766. _warm_nous_pricing_cache()
  767. _rerun_notice_policy(agent)
  768. from agent.memory_provider import spawn_context_thread
  769. agent._credits_pricing_warm = spawn_context_thread(_warm_then_rerun, name="credits-pricing-warm")
  770. agent._credits_pricing_warm.start()
  771. return True
  772. def seed_credits_at_session_start(agent) -> bool:
  773. """Hydrate agent._credits_state from the portal account (or a dev fixture) and fire the notice policy so
  774. warnings show at session OPEN (TUI/desktop "ready" and plain-CLI first-turn setup). Idempotent once a seed
  775. or real header populated _credits_state. Returns True iff it seeded this call. Never raises."""
  776. try:
  777. if getattr(agent, "provider", "") != "nous" or getattr(agent, "_credits_state", None) is not None:
  778. return False
  779. try:
  780. fixture = dev_fixture_credits_state()
  781. except Exception:
  782. fixture = None
  783. if fixture is not None: # synchronous: instant, and tests rely on state + notice landing before return
  784. _hydrate_seed_state(agent, fixture)
  785. return True
  786. def _bg_seed() -> None: # FIRE-AND-FORGET: a slow portal must never delay "ready"
  787. try:
  788. from hermes_cli.nous_account import get_nous_portal_account_info
  789. # BEFORE the policy runs (either branch below): the free-model gate only PEEKS the
  790. # pricing cache, and this thread is the first thing a chat session runs that can
  791. # afford to fill it.
  792. _warm_nous_pricing_cache()
  793. info = get_nous_portal_account_info(force_fresh=True)
  794. if getattr(agent, "_credits_state", None) is not None:
  795. # A live inference header beat us — don't clobber it, but DO re-run the policy:
  796. # it evaluated against the cold cache and may be showing a banner the warm
  797. # catalog now suppresses.
  798. _rerun_notice_policy(agent)
  799. return
  800. if (state := _credits_state_from_account(info)) is not None:
  801. _hydrate_seed_state(agent, state)
  802. except Exception:
  803. logger.debug("credits ▸ session-start seed (background) failed", exc_info=True)
  804. from agent.memory_provider import spawn_context_thread
  805. spawn_context_thread(_bg_seed, name="credits-seed").start() # the warm reads the profile's auth store
  806. return True
  807. except Exception:
  808. logger.debug("credits ▸ session-start seed failed (fail-open)", exc_info=True) # innermost log: diagnosable dead seed
  809. return False