rate_limit_credits.py 13 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249
  1. """Rate-limit / credits header capture and low-credit notices for ``AIAgent``.
  2. Parses provider response headers into ``_rate_limit_state`` / ``_credits_state`` and emits sticky notices.
  3. Extracted from ``run_agent.py``; every method resolves through ``AIAgent``'s MRO unchanged.
  4. """
  5. import logging
  6. import os
  7. from typing import Any
  8. from utils import is_truthy_value
  9. # Same logger name as the origin module so log records / caplog filters are unchanged.
  10. logger = logging.getLogger("run_agent")
  11. def _is_nous_agent(agent) -> bool:
  12. """True for the Nous provider (or a route to a nousresearch.com host)."""
  13. if (getattr(agent, "provider", "") or "").strip().lower() == "nous":
  14. return True
  15. from utils import base_url_host_matches
  16. base_url = str(getattr(agent, "base_url", "") or "")
  17. return bool(base_url) and base_url_host_matches(base_url, "nousresearch.com")
  18. def _response_headers(http_response: Any):
  19. """Headers of a response, or None when there is nothing to parse."""
  20. return getattr(http_response, "headers", None) if http_response is not None else None
  21. def _pct(fraction) -> str:
  22. return ("%.0f%%" % (fraction * 100)) if fraction is not None else "n/a"
  23. def _adopt_credits_state(agent, state) -> None:
  24. """Retain-last-known: overwrite state and latch session-start remaining on the first header ever seen."""
  25. agent._credits_state = state
  26. if agent._credits_session_start_micros is None:
  27. agent._credits_session_start_micros = state.remaining_micros
  28. class RateLimitCreditsMixin:
  29. """Rate-limit + credits header capture and notices (see module docstring)."""
  30. def _capture_rate_limits(self, http_response: Any) -> None:
  31. """Parse x-ratelimit-* headers from an HTTP response and cache the state (never raises)."""
  32. headers = _response_headers(http_response)
  33. if not headers:
  34. return
  35. try:
  36. from agent.rate_limit_tracker import parse_rate_limit_headers
  37. state = parse_rate_limit_headers(headers, provider=self.provider)
  38. if state is not None:
  39. self._rate_limit_state = state
  40. except Exception:
  41. pass # Never let header parsing break the agent loop
  42. def get_rate_limit_state(self):
  43. """Return the last captured RateLimitState, or None."""
  44. return self._rate_limit_state
  45. def _capture_nous_model_switch(self, http_response: Any) -> None:
  46. """Record the Nous gateway's ``x-nous-model-switch`` header (a named account asked for the
  47. free tier's model; the gateway served its backing model and named it). Applied between
  48. calls by ``hermes_cli.anon_auth.apply_model_switch``. Fail-open."""
  49. headers = _response_headers(http_response)
  50. if not headers:
  51. return
  52. try:
  53. from hermes_cli.anon_auth import note_model_switch
  54. note_model_switch(self, headers)
  55. except Exception:
  56. pass # Never let header parsing break the agent loop
  57. def _capture_anthropic_response_headers(self, http_response: Any) -> None:
  58. """Capture rate-limit + credits state from Anthropic Messages response headers (the SDK's
  59. aggregated ``Message`` drops them). Fail-open."""
  60. self._capture_rate_limits(http_response)
  61. self._capture_credits(http_response)
  62. def _capture_credits(self, http_response: Any, *, refused: bool = False) -> None:
  63. """Parse x-nous-credits-* headers, cache CreditsState, fire threshold notices.
  64. The PARSE is swallowed (miss → keep last-known); notice EVALUATION WARNS on failure so a
  65. depletion-notice bug cannot vanish silently. HERMES_DEV_CREDITS_FIXTURE injects a chosen state instead.
  66. """
  67. try:
  68. from agent.credits_tracker import dev_fixture_credits_state
  69. fixture = dev_fixture_credits_state()
  70. except Exception:
  71. fixture = None
  72. if fixture is not None:
  73. _adopt_credits_state(self, fixture)
  74. latch = getattr(self, "_credits_latch", None)
  75. if isinstance(latch, dict):
  76. # Only seen_below_90 — priming seen_grant_unspent would fire grant_spent on first observation.
  77. latch["seen_below_90"] = True # let warn90 fire without a real crossing
  78. logger.info(
  79. "credits ▸ [FIXTURE] remaining=%d (%s) · paid=%s · denom=%s · used=%s "
  80. "(real headers bypassed — `echo clear` / unset HERMES_DEV_CREDITS_FIXTURE to restore)",
  81. fixture.remaining_micros, fixture.remaining_usd or "?", fixture.paid_access, fixture.denominator_kind,
  82. _pct(fixture.used_fraction))
  83. self._emit_credits_notices()
  84. return
  85. headers = _response_headers(http_response)
  86. if not headers:
  87. return
  88. dev = is_truthy_value(os.environ.get("HERMES_DEV_CREDITS"))
  89. # Parse: fail-open → miss; never overwrite good state with None.
  90. try:
  91. from agent.credits_tracker import parse_credits_headers
  92. state = parse_credits_headers(headers, provider=self.provider)
  93. except Exception:
  94. return
  95. if state is None:
  96. if dev:
  97. logger.info("credits ▸ response had no valid x-nous-credits-* headers "
  98. "(miss — producer off / non-Nous path / >TTL stale)")
  99. return
  100. if state.is_usage_window and not _is_nous_agent(self):
  101. return # window headers from any other upstream are ignored (no window UI, no Keep going button)
  102. if state.is_usage_window and not any(k.lower() == "x-nous-credits-purchased-micros" for k in headers):
  103. # A refused request's headers omit the top-up balance: keep the last known one, not "no credits".
  104. prior = getattr(self, "_credits_state", None)
  105. if prior is not None:
  106. import dataclasses
  107. state = dataclasses.replace(state, purchased_micros=prior.purchased_micros,
  108. purchased_usd=prior.purchased_usd)
  109. if state.is_usage_window and not refused and state.spend_source is None:
  110. import dataclasses
  111. state = dataclasses.replace(state, unmetered=True) # admitted but not metered: no limit stop from it
  112. _adopt_credits_state(self, state)
  113. try:
  114. # A reply that contradicts the cached plan (upgrade, cancel, a limit filled or reset)
  115. # refreshes it once in the background, so pickers catch up without a new session.
  116. from agent.plan_snapshot_sync import sync_plan_snapshot
  117. sync_plan_snapshot(state)
  118. except Exception:
  119. logger.debug("Plan snapshot sync failed", exc_info=True)
  120. if dev:
  121. # HERMES_DEV_CREDITS streams each capture to agent.log (`hermes logs -f`, grep 'credits ▸').
  122. spent = self.get_credits_spent_micros()
  123. logger.info(
  124. "credits ▸ remaining=%d (%s) · paid=%s · denom=%s · used=%s · Δspent=%s · age=%s%s",
  125. state.remaining_micros, state.remaining_usd or "?", state.paid_access, state.denominator_kind,
  126. _pct(state.used_fraction), ("%.1f¢" % (spent / 10000)) if spent is not None else "n/a",
  127. (f"{state.age_seconds:.0f}s") if state.age_seconds != float("inf") else "n/a",
  128. (f" · disabled={state.disabled_reason}") if state.disabled_reason else "")
  129. self._emit_credits_notices()
  130. def _emit_credits_notices(self) -> None:
  131. """Run the threshold policy and emit notices (shared by the warm path and the cold-start seed).
  132. Runs only when a notice consumer is bound; WARNS on failure; clears FIRST so depleted lands last.
  133. """
  134. if getattr(self, "notice_callback", None) is None and getattr(self, "notice_clear_callback", None) is None:
  135. return
  136. state = getattr(self, "_credits_state", None)
  137. if not self._credits_notices_enabled() or state is None:
  138. return
  139. try:
  140. from agent.credits_tracker import (
  141. _remember_shown_band,
  142. evaluate_credits_notices, is_free_tier_model, new_credits_latch, rewarm_pricing_before_depleted_notice,
  143. )
  144. latch = getattr(self, "_credits_latch", None)
  145. if latch is None:
  146. latch = self._credits_latch = new_credits_latch()
  147. # Free-model gate: a depleted account can still inference on a free model. Local data only.
  148. model_is_free = is_free_tier_model(getattr(self, "model", "") or "", getattr(self, "base_url", "") or "")
  149. # Any blocking state (depleted, or a used-up window / large-model allowance) needs a warm catalog to
  150. # tell a model billed elsewhere apart once the 300s pricing cache lapses.
  151. blocking = state.depleted or state.window_exhausted or state.top_tier_exhausted
  152. if blocking and not model_is_free and rewarm_pricing_before_depleted_notice(self):
  153. return # a cold catalog cannot say the model is billed elsewhere; the warm's re-run decides
  154. model_is_top_tier = False
  155. if state.is_usage_window and not model_is_free:
  156. # The top-tier approach warning only matters while on a top-tier model (gateway mark).
  157. from agent.plan_limits import cached_pricing, is_top_tier
  158. model_is_top_tier = is_top_tier(getattr(self, "model", "") or "",
  159. cached_pricing(getattr(self, "base_url", "") or ""))
  160. session_id = getattr(self, "session_id", None)
  161. if state.is_usage_window:
  162. from agent.credits_tracker import restore_window_notices
  163. restore_window_notices(session_id, latch)
  164. to_show, to_clear = evaluate_credits_notices(
  165. state, latch, model_is_free=model_is_free, model_is_top_tier=model_is_top_tier)
  166. if state.is_usage_window:
  167. from agent.credits_tracker import remember_window_notices
  168. remember_window_notices(session_id, latch)
  169. elif session_id:
  170. from agent.credits_tracker import forget_window_notices
  171. forget_window_notices(session_id)
  172. for key in to_clear:
  173. self._emit_notice_clear(key)
  174. for notice in to_show:
  175. self._emit_notice(notice)
  176. # Record the band this session last showed so a desktop reap/resume rebuild
  177. # (fresh agent + fresh latch, SAME session_id) restores it instead of
  178. # re-announcing the unchanged band as a fresh crossing (#101578). Both the
  179. # live-header path and the cold-start seed route through here, so this is the
  180. # single chokepoint.
  181. _remember_shown_band(getattr(self, "session_id", None), latch.get("usage_band"))
  182. except Exception:
  183. logger.warning("credits notice evaluation/emit failed", exc_info=True)
  184. def _credits_notices_enabled(self) -> bool:
  185. """``display.credits_notices``, read once per agent and cached (UI noise, not correctness); fail-open True."""
  186. cached = getattr(self, "_credits_notices_enabled_cache", None)
  187. if cached is not None:
  188. return cached
  189. enabled = True
  190. try:
  191. from hermes_cli.config import load_config
  192. display = (load_config() or {}).get("display")
  193. if isinstance(display, dict) and "credits_notices" in display:
  194. enabled = bool(display["credits_notices"])
  195. except Exception:
  196. pass
  197. self._credits_notices_enabled_cache = enabled
  198. return enabled
  199. def get_credits_state(self):
  200. """Return the last captured CreditsState, or None."""
  201. return self._credits_state
  202. def get_credits_spent_micros(self):
  203. """Session-cumulative micros spent = first_seen_remaining - current_remaining. None if no data."""
  204. if self._credits_session_start_micros is None or self._credits_state is None:
  205. return None
  206. return self._credits_session_start_micros - self._credits_state.remaining_micros
  207. def _check_openrouter_cache_status(self, http_response: Any) -> None:
  208. """Log X-OpenRouter-Cache-Status; HITs count in ``_or_cache_hits``. Never raises."""
  209. headers = _response_headers(http_response)
  210. if not headers:
  211. return
  212. try:
  213. status = headers.get("x-openrouter-cache-status")
  214. if not status:
  215. return
  216. if status.upper() == "HIT":
  217. self._or_cache_hits += 1
  218. logger.info("OpenRouter response cache HIT (total: %d)", self._or_cache_hits)
  219. else:
  220. logger.debug("OpenRouter response cache %s", status.upper())
  221. except Exception:
  222. pass # Never let header parsing break the agent loop