gateway: capture real provider-reported cost (openrouter usage accounting)

Cost displays were estimates from a pricing table; on OpenRouter the
status bar never reflected what was actually charged. Now cost is
provider-REPORTED only, end to end:

- OpenRouter requests carry usage:{include:true} (profile + legacy
  transport paths); the response usage.cost field (credits, 1:1 USD)
  is captured per call into agent.session_actual_cost_usd and
  persisted to the sessions DB actual_cost_usd column (NULL-safe:
  unreported calls never touch the stored value).
- Nous keeps its x-nous-credits-* header capture; the header delta
  now surfaces as the session's real cost via real_session_cost_usd.
- Providers that report nothing accumulate NOTHING: cost fields stay
  absent/None (the TUI hides its cost segment), never a fabricated
  $0.00 and never an estimate. _get_usage, gateway /usage and the
  CLI usage page all switched off estimate_usage_cost for display.
- Per-model session accumulator (session_model_usage) records real
  per-call counts and provider-reported cost per model.

agent/agent_init.py

@@ -1620,6 +1620,12 @@ def init_agent(
     agent.session_cache_write_tokens = 0
     agent.session_reasoning_tokens = 0
     agent.session_estimated_cost_usd = 0.0
+    # Provider-REPORTED cost only (e.g. OpenRouter usage.cost). None means
+    # "nothing reported" — distinct from a real $0.00.
+    agent.session_actual_cost_usd = None
+    # Per-model session usage rows for /usage: {model: {calls, input, output,
+    # cache_read, cache_write, cost_usd|None}}.
+    agent.session_model_usage = {}
     agent.session_cost_status = "unknown"
     agent.session_cost_source = "none"
     

agent/conversation_loop.py

@@ -57,7 +57,11 @@ from agent.process_bootstrap import _install_safe_stdio
 from agent.prompt_caching import apply_anthropic_cache_control
 from agent.retry_utils import jittered_backoff
 from agent.trajectory import has_incomplete_scratchpad
-from agent.usage_pricing import estimate_usage_cost, normalize_usage
+from agent.usage_pricing import (
+    estimate_usage_cost,
+    extract_provider_cost_usd,
+    normalize_usage,
+)
 from hermes_constants import PARTIAL_STREAM_STUB_ID
 from hermes_logging import set_session_context
 from tools.skill_provenance import set_current_write_origin
@@ -1633,6 +1637,37 @@ def run_conversation(
                     agent.session_cost_status = cost_result.status
                     agent.session_cost_source = cost_result.source
 
+                    # ── Real provider-REPORTED cost (never estimated) ──
+                    # OpenRouter usage accounting returns ``usage.cost`` on the
+                    # response when the request carries usage:{include:true}
+                    # (added on OpenRouter routes). When the provider reports
+                    # nothing, this stays None — absent, NOT zero — so cost
+                    # displays hide instead of showing a fabricated $0.00.
+                    reported_cost_usd = extract_provider_cost_usd(response.usage)
+                    if reported_cost_usd is not None:
+                        _prev_actual = getattr(agent, "session_actual_cost_usd", None)
+                        agent.session_actual_cost_usd = (_prev_actual or 0.0) + reported_cost_usd
+                        agent.session_cost_status = "actual"
+                        agent.session_cost_source = "provider_cost_api"
+
+                    # Per-model session breakdown for /usage — counts are always
+                    # real; cost_usd only accumulates provider-reported values
+                    # and stays None when the provider reports nothing.
+                    _model_usage = getattr(agent, "session_model_usage", None)
+                    if _model_usage is None:
+                        _model_usage = agent.session_model_usage = {}
+                    _mrow = _model_usage.setdefault(agent.model, {
+                        "calls": 0, "input": 0, "output": 0,
+                        "cache_read": 0, "cache_write": 0, "cost_usd": None,
+                    })
+                    _mrow["calls"] += 1
+                    _mrow["input"] += canonical_usage.input_tokens
+                    _mrow["output"] += canonical_usage.output_tokens
+                    _mrow["cache_read"] += canonical_usage.cache_read_tokens
+                    _mrow["cache_write"] += canonical_usage.cache_write_tokens
+                    if reported_cost_usd is not None:
+                        _mrow["cost_usd"] = (_mrow["cost_usd"] or 0.0) + reported_cost_usd
+
                     # Persist token counts to session DB for /insights.
                     # Do this for every platform with a session_id so non-CLI
                     # sessions (gateway, cron, delegated runs) cannot lose
@@ -1659,8 +1694,14 @@ def run_conversation(
                                 reasoning_tokens=canonical_usage.reasoning_tokens,
                                 estimated_cost_usd=float(cost_result.amount_usd)
                                 if cost_result.amount_usd is not None else None,
-                                cost_status=cost_result.status,
-                                cost_source=cost_result.source,
+                                # Provider-reported per-call cost delta. NULL
+                                # (not 0) when the provider reported nothing —
+                                # the SQL CASE keeps actual_cost_usd untouched.
+                                actual_cost_usd=reported_cost_usd,
+                                cost_status="actual"
+                                if reported_cost_usd is not None else cost_result.status,
+                                cost_source="provider_cost_api"
+                                if reported_cost_usd is not None else cost_result.source,
                                 billing_provider=agent.provider,
                                 billing_base_url=agent.base_url,
                                 billing_mode="subscription_included"

agent/transports/chat_completions.py

@@ -388,6 +388,13 @@ class ChatCompletionsTransport(ProviderTransport):
         if provider_prefs and is_openrouter:
             extra_body["provider"] = provider_prefs
 
+        # OpenRouter usage accounting — response `usage.cost` carries the REAL
+        # charged cost (credits are 1:1 USD). Parity with the profile path in
+        # plugins/model-providers/openrouter/__init__.py; this branch only runs
+        # when the OpenRouter profile isn't loaded.
+        if is_openrouter:
+            extra_body["usage"] = {"include": True}
+
         # Pareto Code router plugin — model-gated. Same shape as the
         # profile path in plugins/model-providers/openrouter/__init__.py;
         # this branch only runs when the OpenRouter profile isn't loaded.

agent/usage_pricing.py

@@ -849,6 +849,73 @@ def estimate_usage_cost(
     )
 
 
+def _finite_nonneg_number(value: Any) -> Optional[float]:
+    """Return ``value`` as a float when it is a real, finite, non-negative
+    number (int/float, not bool); otherwise None."""
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        return None
+    try:
+        f = float(value)
+    except (TypeError, ValueError):
+        return None
+    if f != f or f in (float("inf"), float("-inf")) or f < 0:
+        return None
+    return f
+
+
+def extract_provider_cost_usd(response_usage: Any) -> Optional[float]:
+    """Provider-REPORTED cost (USD) from a response ``usage`` object, or None.
+
+    Reads the ``usage.cost`` field that OpenRouter's usage accounting returns
+    (``usage: {"include": true}`` request param; OpenRouter credits are 1:1
+    USD). OpenRouter-compatible aggregators use the same field. This NEVER
+    estimates: when the provider reports nothing, the result is None — callers
+    must treat None as "no cost data", not zero. A reported ``0`` is a real
+    zero (e.g. free-tier models) and is returned as ``0.0``.
+    """
+    if response_usage is None:
+        return None
+    cost = getattr(response_usage, "cost", None)
+    if cost is None and isinstance(response_usage, dict):
+        cost = response_usage.get("cost")
+    return _finite_nonneg_number(cost)
+
+
+def real_session_cost_usd(agent: Any) -> Optional[float]:
+    """Session-cumulative provider-REPORTED cost in USD, or None.
+
+    Combines the two real sources Hermes has — no estimation, ever:
+      - ``agent.session_actual_cost_usd``: per-response ``usage.cost``
+        accumulator (OpenRouter usage accounting).
+      - Nous ``x-nous-credits-*`` header delta via
+        ``agent.get_credits_spent_micros()`` (account-level spend since the
+        session first saw a header; clamped at 0 so a mid-session top-up
+        doesn't render a negative cost).
+
+    Returns None when neither source has reported anything — callers must
+    hide their cost display in that case rather than showing $0.00.
+    """
+    total: Optional[float] = None
+
+    actual = _finite_nonneg_number(getattr(agent, "session_actual_cost_usd", None))
+    if actual is not None:
+        total = actual
+
+    try:
+        spent_micros = agent.get_credits_spent_micros()
+    except Exception:
+        spent_micros = None
+    if spent_micros is not None:
+        try:
+            spent_usd = max(0, int(spent_micros)) / 1_000_000
+        except (TypeError, ValueError):
+            spent_usd = None
+        if spent_usd is not None:
+            total = (total or 0.0) + spent_usd
+
+    return total
+
+
 def has_known_pricing(
     model_name: str,
     provider: Optional[str] = None,