Add app-attributed usage display (#292)

* Add app-attributed usage display

Co-authored-by: OpenAI Codex <codex@openai.com>

* Fix usage windows for local timestamps

Co-authored-by: OpenAI Codex <codex@openai.com>

* Add HF billing usage to usage display

Co-authored-by: OpenAI Codex <codex@openai.com>

* Simplify usage popover

Co-authored-by: OpenAI Codex <codex@openai.com>

* Remove token row from usage popover

Co-authored-by: OpenAI Codex <codex@openai.com>

* Move session billing note to usage header

Co-authored-by: OpenAI Codex <codex@openai.com>

* Optimize usage popover rollup loading

Co-authored-by: OpenAI Codex <codex@openai.com>

* Round usage costs to cents

Co-authored-by: OpenAI Codex <codex@openai.com>

---------

Co-authored-by: OpenAI Codex <codex@openai.com>

agent/core/session.py

@@ -137,7 +137,7 @@ class Session:
 
         # Session trajectory logging
         self.logged_events: list[dict] = []
-        self.session_start_time = datetime.now().isoformat()
+        self.session_start_time = datetime.now().astimezone().isoformat()
         self.turn_count: int = 0
         self.last_auto_save_turn: int = 0
         # Stable local save path so heartbeat saves overwrite one file instead
@@ -162,7 +162,7 @@ class Session:
         # Log event to trajectory
         self.logged_events.append(
             {
-                "timestamp": datetime.now().isoformat(),
+                "timestamp": datetime.now().astimezone().isoformat(),
                 "event_type": event.event_type,
                 "data": event.data,
             }
@@ -412,7 +412,7 @@ class Session:
         self.context_manager.running_context_usage = 0
 
         self.session_id = str(uuid.uuid4())
-        self.session_start_time = datetime.now().isoformat()
+        self.session_start_time = datetime.now().astimezone().isoformat()
         self.turn_count = 0
         self.last_auto_save_turn = 0
         self.logged_events = []

agent/core/session_persistence.py

@@ -20,6 +20,7 @@ logger = logging.getLogger(__name__)
 
 SCHEMA_VERSION = 1
 MAX_BSON_BYTES = 15 * 1024 * 1024
+USAGE_EVENT_TYPES = ("llm_call", "hf_job_complete")
 
 
 def _now() -> datetime:
@@ -86,6 +87,9 @@ class NoopSessionStore:
     async def load_events_after(self, *_: Any, **__: Any) -> list[dict[str, Any]]:
         return []
 
+    async def load_usage_events(self, *_: Any, **__: Any) -> list[dict[str, Any]]:
+        return []
+
     async def append_trace_message(self, *_: Any, **__: Any) -> int | None:
         return None
 
@@ -142,6 +146,9 @@ class MongoSessionStore(NoopSessionStore):
         await self.db.session_events.create_index(
             [("session_id", 1), ("seq", 1)], unique=True
         )
+        await self.db.session_events.create_index(
+            [("session_id", 1), ("created_at", 1), ("event_type", 1)]
+        )
         await self.db.session_trace_messages.create_index(
             [("session_id", 1), ("seq", 1)], unique=True
         )
@@ -365,6 +372,42 @@ class MongoSessionStore(NoopSessionStore):
         ).sort("seq", 1)
         return [row async for row in cursor]
 
+    async def load_usage_events(
+        self,
+        user_id: str,
+        *,
+        session_id: str | None = None,
+        start: datetime | None = None,
+        end: datetime | None = None,
+    ) -> list[dict[str, Any]]:
+        if not self._ready():
+            return []
+        session_query: dict[str, Any] = {"visibility": {"$ne": "deleted"}}
+        if user_id != "dev":
+            session_query["user_id"] = user_id
+        if session_id is not None:
+            session_query["_id"] = session_id
+
+        session_cursor = self.db.sessions.find(session_query, {"_id": 1})
+        session_ids = [str(row.get("_id")) async for row in session_cursor]
+        if not session_ids:
+            return []
+
+        event_query: dict[str, Any] = {
+            "session_id": {"$in": session_ids},
+            "event_type": {"$in": list(USAGE_EVENT_TYPES)},
+        }
+        if start is not None or end is not None:
+            created_at: dict[str, datetime] = {}
+            if start is not None:
+                created_at["$gte"] = start
+            if end is not None:
+                created_at["$lt"] = end
+            event_query["created_at"] = created_at
+
+        event_cursor = self.db.session_events.find(event_query)
+        return [row async for row in event_cursor]
+
     async def append_trace_message(
         self, session_id: str, message: dict[str, Any], source: str = "message"
     ) -> int | None:

agent/core/telemetry.py

@@ -21,6 +21,8 @@ import logging
 import time
 from typing import Any
 
+from agent.core.cost_estimation import hf_jobs_price_catalog
+
 logger = logging.getLogger(__name__)
 
 
@@ -190,6 +192,18 @@ async def record_hf_job_complete(
 
     try:
         wall_time_s = int(time.monotonic() - submit_ts)
+        billable_seconds = max(0, wall_time_s)
+        price_usd_per_hour = None
+        estimated_cost_usd = None
+        cost_estimate_source = "unknown_price"
+        prices = await hf_jobs_price_catalog()
+        if flavor in prices:
+            price_usd_per_hour = float(prices[flavor])
+            estimated_cost_usd = round(
+                price_usd_per_hour * (billable_seconds / 3600),
+                4,
+            )
+            cost_estimate_source = "runtime_price_catalog"
         await session.send_event(
             Event(
                 event_type="hf_job_complete",
@@ -198,6 +212,10 @@ async def record_hf_job_complete(
                     "flavor": flavor,
                     "final_status": final_status,
                     "wall_time_s": wall_time_s,
+                    "billable_seconds_estimate": billable_seconds,
+                    "price_usd_per_hour": price_usd_per_hour,
+                    "estimated_cost_usd": estimated_cost_usd,
+                    "cost_estimate_source": cost_estimate_source,
                 },
             )
         )

backend/models.py

@@ -120,6 +120,78 @@ class SessionYoloRequest(BaseModel):
     cost_cap_usd: float | None = Field(default=None, ge=0)
 
 
+class UsageBucket(BaseModel):
+    """App-attributed usage totals for a session or time window."""
+
+    session_id: str | None = None
+    window_start: str | None = None
+    window_end: str | None = None
+    timezone: str | None = None
+    total_usd: float = 0.0
+    inference_usd: float = 0.0
+    hf_jobs_estimated_usd: float = 0.0
+    llm_calls: int = 0
+    hf_jobs_count: int = 0
+    prompt_tokens: int = 0
+    completion_tokens: int = 0
+    cache_read_tokens: int = 0
+    cache_creation_tokens: int = 0
+    total_tokens: int = 0
+    hf_jobs_billable_seconds_estimate: int = 0
+
+
+class HfAccountUsageBucket(BaseModel):
+    """HF account billing usage for a time window."""
+
+    window_start: str | None = None
+    window_end: str | None = None
+    timezone: str | None = None
+    total_usd: float = 0.0
+    inference_providers_usd: float = 0.0
+    hf_jobs_usd: float = 0.0
+    inference_provider_requests: int = 0
+    hf_jobs_minutes: float = 0.0
+
+
+class HfInferenceProvidersCredits(BaseModel):
+    """Included and configured Inference Providers account credits."""
+
+    included_usd: float = 0.0
+    used_usd: float = 0.0
+    remaining_included_usd: float = 0.0
+    limit_usd: float = 0.0
+    remaining_limit_usd: float = 0.0
+    num_requests: int = 0
+    period_start: str | None = None
+    period_end: str | None = None
+
+
+class HfAccountUsage(BaseModel):
+    """Authoritative HF account billing usage from the signed-in token."""
+
+    source: Literal["hf_billing_usage_v2"]
+    available: bool = False
+    error: str | None = None
+    current_session: HfAccountUsageBucket | None = None
+    today: HfAccountUsageBucket | None = None
+    month: HfAccountUsageBucket | None = None
+    inference_providers_credits: HfInferenceProvidersCredits | None = None
+
+
+class UsageResponse(BaseModel):
+    """Current-user app-attributed usage response."""
+
+    source: Literal["app_telemetry"]
+    currency: Literal["USD"]
+    generated_at: str
+    timezone: str
+    session: UsageBucket | None = None
+    today: UsageBucket
+    month: UsageBucket
+    hf_account: HfAccountUsage | None = None
+    links: dict[str, str] = Field(default_factory=dict)
+
+
 class DatasetUploadResponse(BaseModel):
     """Response for a dataset file uploaded to the Hub."""
 

backend/routes/agent.py

@@ -41,6 +41,7 @@ from models import (
     SessionYoloRequest,
     SubmitRequest,
     TruncateRequest,
+    UsageResponse,
 )
 from session_manager import (
     MAX_SESSIONS,
@@ -62,6 +63,7 @@ from agent.core.model_ids import (
     MINIMAX_M27_MODEL_ID,
     strip_huggingface_model_prefix,
 )
+from usage import build_usage_response
 
 logger = logging.getLogger(__name__)
 
@@ -674,6 +676,36 @@ async def get_jobs_access_info(
     }
 
 
+@router.get("/usage", response_model=UsageResponse)
+async def get_usage(
+    request: Request,
+    session_id: str | None = None,
+    tz: str | None = None,
+    include_rollups: bool = True,
+    user: dict = Depends(get_current_user),
+) -> dict:
+    """Return app-attributed usage for the current user."""
+    if session_id:
+        await _check_session_access(
+            session_id,
+            user,
+            request,
+            preload_sandbox=False,
+        )
+    return await build_usage_response(
+        session_manager,
+        user_id=user["user_id"],
+        hf_token=(
+            resolve_hf_request_token(request, include_env_fallback=False)
+            or _user_hf_token(user)
+            or resolve_hf_request_token(request)
+        ),
+        session_id=session_id,
+        timezone_name=tz,
+        include_rollups=include_rollups,
+    )
+
+
 @router.get("/sessions", response_model=list[SessionInfo])
 async def list_sessions(user: dict = Depends(get_current_user)) -> list[SessionInfo]:
     """List sessions belonging to the authenticated user."""

backend/usage.py

@@ -0,0 +1,583 @@
+"""Usage aggregation for app-attributed ML Intern spend."""
+
+import asyncio
+import logging
+from datetime import UTC, datetime
+from typing import Any
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+import httpx
+
+USAGE_EVENT_TYPES = ("llm_call", "hf_job_complete")
+
+logger = logging.getLogger(__name__)
+
+HF_BILLING_USAGE_V2_URL = "https://huggingface.co/api/settings/billing/usage-v2"
+HF_BILLING_URL = "https://huggingface.co/settings/billing"
+HF_INFERENCE_PROVIDERS_USAGE_URL = "https://huggingface.co/settings/billing/usage"
+HF_INFERENCE_PROVIDERS_PRICING_URL = (
+    "https://huggingface.co/docs/inference-providers/en/pricing"
+)
+HF_JOBS_PRICING_URL = "https://huggingface.co/docs/hub/jobs-pricing"
+
+
+def _utc(dt: datetime) -> datetime:
+    if dt.tzinfo is None:
+        return dt.replace(tzinfo=UTC)
+    return dt.astimezone(UTC)
+
+
+def _iso(dt: datetime | None) -> str | None:
+    if dt is None:
+        return None
+    return _utc(dt).isoformat().replace("+00:00", "Z")
+
+
+def _coerce_float(value: Any) -> float:
+    if isinstance(value, bool) or value is None:
+        return 0.0
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return 0.0
+
+
+def _coerce_int(value: Any) -> int:
+    if isinstance(value, bool) or value is None:
+        return 0
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return 0
+
+
+def _nano_usd_to_usd(value: Any) -> float:
+    return _coerce_float(value) / 1_000_000_000
+
+
+def _micro_usd_to_usd(value: Any) -> float:
+    return _coerce_float(value) / 1_000_000
+
+
+def _coerce_timezone(timezone_name: str | None) -> ZoneInfo | None:
+    if not timezone_name:
+        return None
+    try:
+        return ZoneInfo(timezone_name)
+    except (ZoneInfoNotFoundError, ValueError):
+        return None
+
+
+def _normalize_event_timestamp(
+    dt: datetime,
+    *,
+    timezone_name: str | None = None,
+) -> datetime:
+    if dt.tzinfo is not None:
+        return _utc(dt)
+    timezone = _coerce_timezone(timezone_name)
+    if timezone is not None:
+        return dt.replace(tzinfo=timezone).astimezone(UTC)
+    return dt.astimezone(UTC)
+
+
+def _parse_timestamp(
+    value: Any, *, timezone_name: str | None = None
+) -> datetime | None:
+    if isinstance(value, datetime):
+        return _normalize_event_timestamp(value, timezone_name=timezone_name)
+    if not isinstance(value, str) or not value:
+        return None
+    try:
+        return _normalize_event_timestamp(
+            datetime.fromisoformat(value.replace("Z", "+00:00")),
+            timezone_name=timezone_name,
+        )
+    except ValueError:
+        return None
+
+
+def event_created_at(
+    event: dict[str, Any],
+    *,
+    timezone_name: str | None = None,
+) -> datetime | None:
+    return _parse_timestamp(
+        event.get("created_at") or event.get("timestamp"),
+        timezone_name=timezone_name,
+    )
+
+
+def resolve_usage_windows(
+    timezone_name: str | None,
+    *,
+    now: datetime | None = None,
+) -> dict[str, datetime | str]:
+    """Return UTC day/month windows for a browser timezone."""
+    try:
+        tz = ZoneInfo(timezone_name or "UTC")
+    except (ZoneInfoNotFoundError, ValueError):
+        tz = ZoneInfo("UTC")
+
+    now_utc = _utc(now or datetime.now(UTC))
+    local_now = now_utc.astimezone(tz)
+    today_local = local_now.replace(hour=0, minute=0, second=0, microsecond=0)
+    month_local = today_local.replace(day=1)
+    return {
+        "timezone": tz.key,
+        "now_utc": now_utc,
+        "today_start_utc": today_local.astimezone(UTC),
+        "month_start_utc": month_local.astimezone(UTC),
+    }
+
+
+def _empty_bucket(
+    *,
+    session_id: str | None = None,
+    window_start: datetime | None = None,
+    window_end: datetime | None = None,
+    timezone: str | None = None,
+) -> dict[str, Any]:
+    return {
+        "session_id": session_id,
+        "window_start": _iso(window_start),
+        "window_end": _iso(window_end),
+        "timezone": timezone,
+        "total_usd": 0.0,
+        "inference_usd": 0.0,
+        "hf_jobs_estimated_usd": 0.0,
+        "llm_calls": 0,
+        "hf_jobs_count": 0,
+        "prompt_tokens": 0,
+        "completion_tokens": 0,
+        "cache_read_tokens": 0,
+        "cache_creation_tokens": 0,
+        "total_tokens": 0,
+        "hf_jobs_billable_seconds_estimate": 0,
+    }
+
+
+def _empty_hf_account_bucket(
+    *,
+    window_start: datetime | None = None,
+    window_end: datetime | None = None,
+    timezone: str | None = None,
+) -> dict[str, Any]:
+    return {
+        "window_start": _iso(window_start),
+        "window_end": _iso(window_end),
+        "timezone": timezone,
+        "total_usd": 0.0,
+        "inference_providers_usd": 0.0,
+        "hf_jobs_usd": 0.0,
+        "inference_provider_requests": 0,
+        "hf_jobs_minutes": 0.0,
+    }
+
+
+def aggregate_usage_events(
+    events: list[dict[str, Any]],
+    *,
+    session_id: str | None = None,
+    window_start: datetime | None = None,
+    window_end: datetime | None = None,
+    timezone: str | None = None,
+) -> dict[str, Any]:
+    bucket = _empty_bucket(
+        session_id=session_id,
+        window_start=window_start,
+        window_end=window_end,
+        timezone=timezone,
+    )
+    for event in events:
+        event_type = event.get("event_type")
+        data = event.get("data") or {}
+        if event_type == "llm_call":
+            bucket["llm_calls"] += 1
+            bucket["inference_usd"] += _coerce_float(data.get("cost_usd"))
+            prompt_tokens = _coerce_int(data.get("prompt_tokens"))
+            completion_tokens = _coerce_int(data.get("completion_tokens"))
+            cache_read_tokens = _coerce_int(data.get("cache_read_tokens"))
+            cache_creation_tokens = _coerce_int(data.get("cache_creation_tokens"))
+            total_tokens = _coerce_int(data.get("total_tokens")) or (
+                prompt_tokens
+                + completion_tokens
+                + cache_read_tokens
+                + cache_creation_tokens
+            )
+            bucket["prompt_tokens"] += prompt_tokens
+            bucket["completion_tokens"] += completion_tokens
+            bucket["cache_read_tokens"] += cache_read_tokens
+            bucket["cache_creation_tokens"] += cache_creation_tokens
+            bucket["total_tokens"] += total_tokens
+        elif event_type == "hf_job_complete":
+            bucket["hf_jobs_count"] += 1
+            bucket["hf_jobs_estimated_usd"] += _coerce_float(
+                data.get("estimated_cost_usd")
+            )
+            bucket["hf_jobs_billable_seconds_estimate"] += _coerce_int(
+                data.get("billable_seconds_estimate") or data.get("wall_time_s")
+            )
+
+    bucket["inference_usd"] = round(bucket["inference_usd"], 6)
+    bucket["hf_jobs_estimated_usd"] = round(bucket["hf_jobs_estimated_usd"], 6)
+    bucket["total_usd"] = round(
+        bucket["inference_usd"] + bucket["hf_jobs_estimated_usd"],
+        6,
+    )
+    return bucket
+
+
+def _account_bucket_from_billing_usage(
+    payload: dict[str, Any] | None,
+    *,
+    window_start: datetime,
+    window_end: datetime,
+    timezone: str,
+) -> dict[str, Any]:
+    bucket = _empty_hf_account_bucket(
+        window_start=window_start,
+        window_end=window_end,
+        timezone=timezone,
+    )
+    usage = payload.get("usage") if isinstance(payload, dict) else {}
+    if not isinstance(usage, dict):
+        return bucket
+
+    inference = usage.get("inferenceProviders")
+    if not isinstance(inference, dict):
+        inference = {}
+    jobs = usage.get("jobs")
+    if not isinstance(jobs, dict):
+        jobs = {}
+
+    bucket["inference_providers_usd"] = round(
+        _nano_usd_to_usd(inference.get("usedNanoUsd")),
+        6,
+    )
+    bucket["hf_jobs_usd"] = round(_micro_usd_to_usd(jobs.get("usedMicroUsd")), 6)
+    bucket["inference_provider_requests"] = _coerce_int(inference.get("numRequests"))
+    bucket["hf_jobs_minutes"] = round(_coerce_float(jobs.get("totalMinutes")), 3)
+    bucket["total_usd"] = round(
+        bucket["inference_providers_usd"] + bucket["hf_jobs_usd"],
+        6,
+    )
+    return bucket
+
+
+def _inference_credits_from_billing_usage(
+    payload: dict[str, Any] | None,
+) -> dict[str, Any] | None:
+    usage = payload.get("usage") if isinstance(payload, dict) else {}
+    if not isinstance(usage, dict):
+        return None
+    inference = usage.get("inferenceProviders")
+    if not isinstance(inference, dict):
+        return None
+
+    included_usd = _nano_usd_to_usd(inference.get("includedNanoUsd"))
+    used_usd = _nano_usd_to_usd(inference.get("usedNanoUsd"))
+    limit_usd = _nano_usd_to_usd(inference.get("limitNanoUsd"))
+    return {
+        "included_usd": round(included_usd, 6),
+        "used_usd": round(used_usd, 6),
+        "remaining_included_usd": round(max(0.0, included_usd - used_usd), 6),
+        "limit_usd": round(limit_usd, 6),
+        "remaining_limit_usd": round(max(0.0, limit_usd - used_usd), 6),
+        "num_requests": _coerce_int(inference.get("numRequests")),
+        "period_start": inference.get("periodStart"),
+        "period_end": inference.get("periodEnd"),
+    }
+
+
+async def _fetch_hf_billing_usage_v2(
+    hf_token: str,
+    *,
+    start: datetime,
+    end: datetime,
+) -> dict[str, Any] | None:
+    start_ts = max(1, int(_utc(start).timestamp()))
+    end_ts = max(start_ts + 1, int(_utc(end).timestamp()))
+    try:
+        async with httpx.AsyncClient(timeout=10.0) as client:
+            response = await client.get(
+                HF_BILLING_USAGE_V2_URL,
+                params={"startDate": start_ts, "endDate": end_ts},
+                headers={"Authorization": f"Bearer {hf_token}"},
+            )
+            if response.status_code != 200:
+                logger.debug(
+                    "HF billing usage-v2 failed: status=%s body=%s",
+                    response.status_code,
+                    response.text[:200],
+                )
+                return None
+            payload = response.json()
+            return payload if isinstance(payload, dict) else None
+    except (httpx.HTTPError, ValueError) as e:
+        logger.debug("HF billing usage-v2 failed: %s", e)
+        return None
+
+
+def _session_started_at(manager: Any, session_id: str | None) -> datetime | None:
+    if not session_id:
+        return None
+    agent_session = getattr(manager, "sessions", {}).get(session_id)
+    created_at = getattr(agent_session, "created_at", None)
+    if isinstance(created_at, datetime):
+        return _utc(created_at)
+    return None
+
+
+async def _load_persisted_session_started_at(
+    manager: Any,
+    session_id: str | None,
+) -> datetime | None:
+    if not session_id:
+        return None
+    store = manager._store()
+    if not getattr(store, "enabled", False):
+        return None
+    loaded = await store.load_session(session_id)
+    metadata = loaded.get("metadata") if isinstance(loaded, dict) else None
+    created_at = metadata.get("created_at") if isinstance(metadata, dict) else None
+    if isinstance(created_at, datetime):
+        return _utc(created_at)
+    parsed = _parse_timestamp(created_at)
+    return _utc(parsed) if parsed is not None else None
+
+
+async def _build_hf_account_usage(
+    manager: Any,
+    *,
+    hf_token: str | None,
+    session_id: str | None,
+    timezone: str,
+    now_utc: datetime,
+    today_start: datetime,
+    month_start: datetime,
+    include_rollups: bool = True,
+) -> dict[str, Any]:
+    account_usage: dict[str, Any] = {
+        "source": "hf_billing_usage_v2",
+        "available": False,
+        "current_session": None,
+        "today": None,
+        "month": None,
+        "inference_providers_credits": None,
+    }
+    if not hf_token:
+        account_usage["error"] = "missing_hf_token"
+        return account_usage
+
+    session_start = _session_started_at(manager, session_id)
+    if session_start is None:
+        session_start = await _load_persisted_session_started_at(manager, session_id)
+
+    window_tasks: dict[str, tuple[datetime, asyncio.Task[dict[str, Any] | None]]] = {
+        "month": (
+            month_start,
+            asyncio.create_task(
+                _fetch_hf_billing_usage_v2(hf_token, start=month_start, end=now_utc)
+            ),
+        ),
+    }
+    if include_rollups:
+        window_tasks["today"] = (
+            today_start,
+            asyncio.create_task(
+                _fetch_hf_billing_usage_v2(hf_token, start=today_start, end=now_utc)
+            ),
+        )
+    if session_start is not None:
+        window_tasks["current_session"] = (
+            session_start,
+            asyncio.create_task(
+                _fetch_hf_billing_usage_v2(hf_token, start=session_start, end=now_utc)
+            ),
+        )
+
+    payloads: dict[str, dict[str, Any] | None] = {}
+    for name, (_, task) in window_tasks.items():
+        payloads[name] = await task
+
+    any_payload = any(isinstance(payload, dict) for payload in payloads.values())
+    account_usage["available"] = any_payload
+    if not any_payload:
+        account_usage["error"] = "billing_usage_unavailable"
+        return account_usage
+
+    for name, (start, _) in window_tasks.items():
+        payload = payloads.get(name)
+        if payload is None:
+            continue
+        account_usage[name] = _account_bucket_from_billing_usage(
+            payload,
+            window_start=start,
+            window_end=now_utc,
+            timezone=timezone,
+        )
+
+    account_usage["inference_providers_credits"] = (
+        _inference_credits_from_billing_usage(payloads.get("month"))
+    )
+    return account_usage
+
+
+def _event_in_window(
+    event: dict[str, Any],
+    *,
+    start: datetime | None = None,
+    end: datetime | None = None,
+    timezone_name: str | None = None,
+) -> bool:
+    if start is None and end is None:
+        return True
+    created_at = event_created_at(event, timezone_name=timezone_name)
+    if created_at is None:
+        return False
+    if start is not None and created_at < _utc(start):
+        return False
+    if end is not None and created_at >= _utc(end):
+        return False
+    return True
+
+
+def _events_from_runtime_session(agent_session: Any) -> list[dict[str, Any]]:
+    events: list[dict[str, Any]] = []
+    for raw in getattr(agent_session.session, "logged_events", []) or []:
+        if raw.get("event_type") not in USAGE_EVENT_TYPES:
+            continue
+        events.append(
+            {
+                "session_id": agent_session.session_id,
+                "event_type": raw.get("event_type"),
+                "data": raw.get("data") or {},
+                "timestamp": raw.get("timestamp"),
+            }
+        )
+    return events
+
+
+def _runtime_sessions_for_user(manager: Any, user_id: str) -> list[Any]:
+    sessions = list(getattr(manager, "sessions", {}).values())
+    if user_id == "dev":
+        return sessions
+    return [session for session in sessions if session.user_id == user_id]
+
+
+async def _load_usage_events(
+    manager: Any,
+    *,
+    user_id: str,
+    session_id: str | None = None,
+    start: datetime | None = None,
+    end: datetime | None = None,
+    timezone_name: str | None = None,
+) -> list[dict[str, Any]]:
+    store = manager._store()
+    if getattr(store, "enabled", False):
+        return await store.load_usage_events(
+            user_id,
+            session_id=session_id,
+            start=start,
+            end=end,
+        )
+
+    events: list[dict[str, Any]] = []
+    for agent_session in _runtime_sessions_for_user(manager, user_id):
+        if session_id is not None and agent_session.session_id != session_id:
+            continue
+        for event in _events_from_runtime_session(agent_session):
+            if _event_in_window(
+                event,
+                start=start,
+                end=end,
+                timezone_name=timezone_name,
+            ):
+                events.append(event)
+    return events
+
+
+async def build_usage_response(
+    manager: Any,
+    *,
+    user_id: str,
+    hf_token: str | None = None,
+    session_id: str | None = None,
+    timezone_name: str | None = None,
+    now: datetime | None = None,
+    include_rollups: bool = True,
+) -> dict[str, Any]:
+    windows = resolve_usage_windows(timezone_name, now=now)
+    timezone = str(windows["timezone"])
+    now_utc = windows["now_utc"]
+    today_start = windows["today_start_utc"]
+    month_start = windows["month_start_utc"]
+
+    session_events: list[dict[str, Any]] = []
+    if session_id:
+        session_events = await _load_usage_events(
+            manager,
+            user_id=user_id,
+            session_id=session_id,
+        )
+
+    today_events: list[dict[str, Any]] = []
+    month_events: list[dict[str, Any]] = []
+    if include_rollups:
+        today_events = await _load_usage_events(
+            manager,
+            user_id=user_id,
+            start=today_start,
+            end=now_utc,
+            timezone_name=timezone,
+        )
+        month_events = await _load_usage_events(
+            manager,
+            user_id=user_id,
+            start=month_start,
+            end=now_utc,
+            timezone_name=timezone,
+        )
+    hf_account = await _build_hf_account_usage(
+        manager,
+        hf_token=hf_token,
+        session_id=session_id,
+        timezone=timezone,
+        now_utc=now_utc,
+        today_start=today_start,
+        month_start=month_start,
+        include_rollups=include_rollups,
+    )
+
+    return {
+        "source": "app_telemetry",
+        "currency": "USD",
+        "generated_at": _iso(now_utc),
+        "timezone": timezone,
+        "session": (
+            aggregate_usage_events(session_events, session_id=session_id)
+            if session_id
+            else None
+        ),
+        "today": aggregate_usage_events(
+            today_events,
+            window_start=today_start,
+            window_end=now_utc,
+            timezone=timezone,
+        ),
+        "month": aggregate_usage_events(
+            month_events,
+            window_start=month_start,
+            window_end=now_utc,
+            timezone=timezone,
+        ),
+        "hf_account": hf_account,
+        "links": {
+            "hf_billing": HF_BILLING_URL,
+            "inference_providers_usage": HF_INFERENCE_PROVIDERS_USAGE_URL,
+            "inference_providers_pricing": HF_INFERENCE_PROVIDERS_PRICING_URL,
+            "jobs_pricing": HF_JOBS_PRICING_URL,
+        },
+    }

frontend/src/components/Layout/AppLayout.tsx

@@ -26,6 +26,7 @@ import SessionChat from '@/components/SessionChat';
 import CodePanel from '@/components/CodePanel/CodePanel';
 import WelcomeScreen from '@/components/WelcomeScreen/WelcomeScreen';
 import YoloControl from '@/components/YoloControl';
+import UsageMeter from '@/components/UsageMeter';
 import { apiFetch } from '@/utils/api';
 import { inferenceCreditCta, isInferenceCreditError } from '@/utils/inferenceBilling';
 
@@ -300,6 +301,7 @@ export default function AppLayout() {
           </Box>
 
           <Box sx={{ display: 'flex', alignItems: 'center', gap: 0.5 }}>
+            <UsageMeter />
             <YoloControl />
             <IconButton
               onClick={toggleTheme}

frontend/src/components/UsageMeter.tsx

@@ -0,0 +1,231 @@
+import { type ReactNode, useEffect, useMemo, useState } from 'react';
+import {
+  Box,
+  Button,
+  CircularProgress,
+  Divider,
+  Link,
+  Popover,
+  Tooltip,
+  Typography,
+} from '@mui/material';
+import PaidOutlinedIcon from '@mui/icons-material/PaidOutlined';
+import OpenInNewIcon from '@mui/icons-material/OpenInNew';
+import { useSessionStore } from '@/store/sessionStore';
+import {
+  type HfAccountUsageBucket,
+  type HfInferenceProvidersCredits,
+  type UsageBucket,
+  useUsageStore,
+} from '@/store/usageStore';
+
+function formatUsd(value: number | undefined): string {
+  const amount = value ?? 0;
+  if (amount > 0 && amount < 0.01) return '<$0.01';
+  return new Intl.NumberFormat('en-US', {
+    style: 'currency',
+    currency: 'USD',
+    minimumFractionDigits: 2,
+    maximumFractionDigits: 2,
+  }).format(amount);
+}
+
+function UsageRow({
+  label,
+  value,
+  strong = false,
+}: {
+  label: string;
+  value: string;
+  strong?: boolean;
+}) {
+  return (
+    <>
+      <Typography variant="body2" color="text.secondary">
+        {label}
+      </Typography>
+      <Typography
+        variant="body2"
+        sx={{ fontWeight: strong ? 700 : 400, fontVariantNumeric: 'tabular-nums' }}
+      >
+        {value}
+      </Typography>
+    </>
+  );
+}
+
+function UsageGrid({ children }: { children: ReactNode }) {
+  return (
+    <Box
+      sx={{
+        display: 'grid',
+        gridTemplateColumns: '1fr auto',
+        columnGap: 2,
+        rowGap: 0.5,
+        mt: 0.75,
+      }}
+    >
+      {children}
+    </Box>
+  );
+}
+
+function AccountUsageSection({
+  title,
+  account,
+  telemetry,
+}: {
+  title: string;
+  account: HfAccountUsageBucket | null | undefined;
+  telemetry: UsageBucket | null | undefined;
+}) {
+  return (
+    <Box sx={{ py: 1 }}>
+      <Typography variant="caption" sx={{ color: 'text.secondary', fontWeight: 700 }}>
+        {title}
+      </Typography>
+      <UsageGrid>
+        <UsageRow
+          label="Inference Providers"
+          value={formatUsd(account?.inference_providers_usd ?? telemetry?.inference_usd)}
+          strong
+        />
+        <UsageRow
+          label={account ? 'HF Jobs' : 'HF Jobs estimated'}
+          value={formatUsd(account?.hf_jobs_usd ?? telemetry?.hf_jobs_estimated_usd)}
+        />
+      </UsageGrid>
+    </Box>
+  );
+}
+
+function CreditsSection({ credits }: { credits: HfInferenceProvidersCredits | null | undefined }) {
+  if (!credits) return null;
+  return (
+    <>
+      <Divider />
+      <Box sx={{ py: 1 }}>
+        <Typography variant="caption" sx={{ color: 'text.secondary', fontWeight: 700 }}>
+          Inference credits
+        </Typography>
+        <UsageGrid>
+          <UsageRow
+            label="Included remaining"
+            value={formatUsd(credits.remaining_included_usd)}
+            strong
+          />
+          <UsageRow
+            label="Used / included"
+            value={`${formatUsd(credits.used_usd)} / ${formatUsd(credits.included_usd)}`}
+          />
+          {credits.limit_usd > 0 && (
+            <UsageRow
+              label="Spend limit remaining"
+              value={formatUsd(credits.remaining_limit_usd)}
+            />
+          )}
+        </UsageGrid>
+      </Box>
+    </>
+  );
+}
+
+export default function UsageMeter() {
+  const activeSessionId = useSessionStore((state) => state.activeSessionId);
+  const { usage, isLoading, error, fetchUsage } = useUsageStore();
+  const [anchorEl, setAnchorEl] = useState<HTMLElement | null>(null);
+
+  useEffect(() => {
+    void fetchUsage(activeSessionId);
+  }, [activeSessionId, fetchUsage]);
+
+  const sessionTotal =
+    usage?.hf_account?.current_session?.total_usd ?? usage?.session?.total_usd ?? 0;
+  const links = useMemo(() => usage?.links ?? {}, [usage?.links]);
+  const open = Boolean(anchorEl);
+
+  return (
+    <>
+      <Tooltip title="Usage">
+        <Button
+          size="small"
+          variant="outlined"
+          startIcon={isLoading ? <CircularProgress size={14} /> : <PaidOutlinedIcon fontSize="small" />}
+          onClick={(event) => setAnchorEl(event.currentTarget)}
+          sx={{
+            minWidth: { xs: 58, sm: 84 },
+            height: 32,
+            px: { xs: 0.75, sm: 1 },
+            borderColor: 'divider',
+            color: 'text.secondary',
+            fontVariantNumeric: 'tabular-nums',
+            '& .MuiButton-startIcon': { mr: { xs: 0.25, sm: 0.5 } },
+            '&:hover': { borderColor: 'primary.main', color: 'primary.main' },
+          }}
+        >
+          {formatUsd(sessionTotal)}
+        </Button>
+      </Tooltip>
+      <Popover
+        open={open}
+        anchorEl={anchorEl}
+        onClose={() => setAnchorEl(null)}
+        anchorOrigin={{ vertical: 'bottom', horizontal: 'right' }}
+        transformOrigin={{ vertical: 'top', horizontal: 'right' }}
+        slotProps={{
+          paper: {
+            sx: {
+              width: 320,
+              maxWidth: 'calc(100vw - 24px)',
+              maxHeight: 'calc(100vh - 24px)',
+              overflowY: 'auto',
+              p: 2,
+              border: '1px solid',
+              borderColor: 'divider',
+            },
+          },
+        }}
+      >
+        <Typography variant="subtitle2" sx={{ fontWeight: 800 }}>
+          Usage
+        </Typography>
+        <Typography variant="caption" color="text.secondary">
+          Session billing is inferred from HF account usage since session start.
+        </Typography>
+
+        {error ? (
+          <Typography variant="body2" color="error" sx={{ mt: 1.5 }}>
+            {error}
+          </Typography>
+        ) : (
+          <>
+            <AccountUsageSection
+              title="Current session"
+              account={usage?.hf_account?.current_session ?? null}
+              telemetry={usage?.session ?? null}
+            />
+            <CreditsSection credits={usage?.hf_account?.inference_providers_credits} />
+          </>
+        )}
+
+        <Box sx={{ display: 'flex', flexWrap: 'wrap', gap: 1, pt: 1 }}>
+          {links.hf_billing && (
+            <Link href={links.hf_billing} target="_blank" rel="noopener noreferrer" underline="hover" sx={{ display: 'inline-flex', alignItems: 'center', gap: 0.25, fontSize: '0.75rem' }}>
+              HF billing <OpenInNewIcon sx={{ fontSize: 12 }} />
+            </Link>
+          )}
+          {links.inference_providers_usage && (
+            <Link href={links.inference_providers_usage} target="_blank" rel="noopener noreferrer" underline="hover" sx={{ display: 'inline-flex', alignItems: 'center', gap: 0.25, fontSize: '0.75rem' }}>
+              Inference usage <OpenInNewIcon sx={{ fontSize: 12 }} />
+            </Link>
+          )}
+          {links.jobs_pricing && (
+            <Link href={links.jobs_pricing} target="_blank" rel="noopener noreferrer" underline="hover" sx={{ display: 'inline-flex', alignItems: 'center', gap: 0.25, fontSize: '0.75rem' }}>
+              Jobs pricing <OpenInNewIcon sx={{ fontSize: 12 }} />
+            </Link>
+          )}
+        </Box>
+      </Popover>
+    </>
+  );
+}

frontend/src/hooks/useAgentChat.ts

@@ -18,6 +18,7 @@ import { llmMessagesToUIMessages } from '@/lib/convert-llm-messages';
 import { apiFetch } from '@/utils/api';
 import { useAgentStore } from '@/store/agentStore';
 import { useSessionStore } from '@/store/sessionStore';
+import { useUsageStore } from '@/store/usageStore';
 import { useLayoutStore } from '@/store/layoutStore';
 import { logger } from '@/utils/logger';
 
@@ -64,6 +65,11 @@ export function useAgentChat({ sessionId, isActive, isProcessing = false, onRead
     [sessionId, updateSession],
   );
 
+  const refreshUsage = useCallback(() => {
+    const activeSessionId = useSessionStore.getState().activeSessionId;
+    void useUsageStore.getState().fetchUsage(activeSessionId);
+  }, []);
+
   // -- Build side-channel callbacks (stable ref) --------------------------
   const sideChannel = useMemo<SideChannelCallbacks>(
     () => ({
@@ -96,6 +102,7 @@ export function useAgentChat({ sessionId, isActive, isProcessing = false, onRead
       },
       onProcessingDone: () => {
         setProcessingState(false);
+        refreshUsage();
       },
       onUndoComplete: () => {
         setProcessingState(false);
@@ -230,6 +237,7 @@ export function useAgentChat({ sessionId, isActive, isProcessing = false, onRead
         // doesn't stay "processing" until the next /sessions merge —
         // activityStatus still surfaces the waiting-approval state.
         setProcessingState(false, { activityStatus: { type: 'waiting-approval' } });
+        refreshUsage();
 
         // Build panel data for this session's pending approval
         const firstTool = tools[0];
@@ -336,6 +344,9 @@ export function useAgentChat({ sessionId, isActive, isProcessing = false, onRead
         }
         updateSession(sessionId, updates);
       },
+      onUsageEvent: (eventType, data) => {
+        useUsageStore.getState().applyUsageEvent(sessionId, eventType, data);
+      },
       onInterrupted: () => { /* no-op — handled by stop() caller */ },
     }),
     // eslint-disable-next-line react-hooks/exhaustive-deps
@@ -593,6 +604,8 @@ export function useAgentChat({ sessionId, isActive, isProcessing = false, onRead
             const state = event.data?.state as string;
             const toolName = event.data?.tool as string;
             if (state === 'running' && toolName) sideChannel.onToolRunning(toolName);
+          } else if (et === 'llm_call' || et === 'hf_job_complete') {
+            sideChannel.onUsageEvent(et, (event.data || {}) as Record<string, unknown>);
           } else if (et === 'turn_complete' || et === 'error' || et === 'interrupted') {
             sideChannel.onProcessingDone();
             stopReconnect();

frontend/src/lib/sse-chat-transport.ts

@@ -39,6 +39,7 @@ export interface SideChannelCallbacks {
   onToolOutputPanel: (tool: string, toolCallId: string, output: string, success: boolean) => void;
   onStreaming: () => void;
   onToolRunning: (toolName: string, description?: string) => void;
+  onUsageEvent: (eventType: 'llm_call' | 'hf_job_complete', data: Record<string, unknown>) => void;
   onInterrupted: () => void;
 }
 
@@ -316,6 +317,11 @@ function createEventToChunkStream(sideChannel: SideChannelCallbacks): TransformS
           break;
         }
 
+        case 'llm_call':
+        case 'hf_job_complete':
+          sideChannel.onUsageEvent(event.event_type, event.data || {});
+          break;
+
         case 'turn_complete':
           endTextPart(controller);
           controller.enqueue({ type: 'finish-step' });

frontend/src/store/usageStore.ts

@@ -0,0 +1,176 @@
+import { create } from 'zustand';
+import { apiFetch } from '@/utils/api';
+
+export interface UsageBucket {
+  session_id?: string | null;
+  window_start?: string | null;
+  window_end?: string | null;
+  timezone?: string | null;
+  total_usd: number;
+  inference_usd: number;
+  hf_jobs_estimated_usd: number;
+  llm_calls: number;
+  hf_jobs_count: number;
+  prompt_tokens: number;
+  completion_tokens: number;
+  cache_read_tokens: number;
+  cache_creation_tokens: number;
+  total_tokens: number;
+  hf_jobs_billable_seconds_estimate: number;
+}
+
+export interface HfAccountUsageBucket {
+  window_start?: string | null;
+  window_end?: string | null;
+  timezone?: string | null;
+  total_usd: number;
+  inference_providers_usd: number;
+  hf_jobs_usd: number;
+  inference_provider_requests: number;
+  hf_jobs_minutes: number;
+}
+
+export interface HfInferenceProvidersCredits {
+  included_usd: number;
+  used_usd: number;
+  remaining_included_usd: number;
+  limit_usd: number;
+  remaining_limit_usd: number;
+  num_requests: number;
+  period_start?: string | null;
+  period_end?: string | null;
+}
+
+export interface HfAccountUsage {
+  source: 'hf_billing_usage_v2';
+  available: boolean;
+  error?: string | null;
+  current_session: HfAccountUsageBucket | null;
+  today: HfAccountUsageBucket | null;
+  month: HfAccountUsageBucket | null;
+  inference_providers_credits: HfInferenceProvidersCredits | null;
+}
+
+export interface UsageResponse {
+  source: 'app_telemetry';
+  currency: 'USD';
+  generated_at: string;
+  timezone: string;
+  session: UsageBucket | null;
+  today: UsageBucket;
+  month: UsageBucket;
+  hf_account?: HfAccountUsage | null;
+  links: Record<string, string>;
+}
+
+type UsageEventType = 'llm_call' | 'hf_job_complete';
+
+interface UsageStore {
+  usage: UsageResponse | null;
+  isLoading: boolean;
+  error: string | null;
+  fetchUsage: (sessionId?: string | null) => Promise<void>;
+  applyUsageEvent: (
+    sessionId: string,
+    eventType: UsageEventType,
+    data: Record<string, unknown>,
+  ) => void;
+}
+
+function numberValue(value: unknown): number {
+  return typeof value === 'number' && Number.isFinite(value) ? value : 0;
+}
+
+function intValue(value: unknown): number {
+  return Math.trunc(numberValue(value));
+}
+
+function roundUsd(value: number): number {
+  return Math.round(value * 1_000_000) / 1_000_000;
+}
+
+function usageUrl(sessionId?: string | null): string {
+  const params = new URLSearchParams();
+  const timezone = Intl.DateTimeFormat().resolvedOptions().timeZone || 'UTC';
+  params.set('tz', timezone);
+  params.set('include_rollups', 'false');
+  if (sessionId) params.set('session_id', sessionId);
+  return `/api/usage?${params.toString()}`;
+}
+
+function applyEventToBucket(
+  bucket: UsageBucket | null,
+  eventType: UsageEventType,
+  data: Record<string, unknown>,
+): UsageBucket | null {
+  if (!bucket) return null;
+  const next = { ...bucket };
+
+  if (eventType === 'llm_call') {
+    const prompt = intValue(data.prompt_tokens);
+    const completion = intValue(data.completion_tokens);
+    const cacheRead = intValue(data.cache_read_tokens);
+    const cacheCreation = intValue(data.cache_creation_tokens);
+    const total =
+      intValue(data.total_tokens) || prompt + completion + cacheRead + cacheCreation;
+    next.llm_calls += 1;
+    next.inference_usd = roundUsd(next.inference_usd + numberValue(data.cost_usd));
+    next.prompt_tokens += prompt;
+    next.completion_tokens += completion;
+    next.cache_read_tokens += cacheRead;
+    next.cache_creation_tokens += cacheCreation;
+    next.total_tokens += total;
+  } else if (eventType === 'hf_job_complete') {
+    next.hf_jobs_count += 1;
+    next.hf_jobs_estimated_usd = roundUsd(
+      next.hf_jobs_estimated_usd + numberValue(data.estimated_cost_usd),
+    );
+    next.hf_jobs_billable_seconds_estimate +=
+      intValue(data.billable_seconds_estimate) || intValue(data.wall_time_s);
+  }
+
+  next.total_usd = roundUsd(next.inference_usd + next.hf_jobs_estimated_usd);
+  return next;
+}
+
+export const useUsageStore = create<UsageStore>()((set, get) => ({
+  usage: null,
+  isLoading: false,
+  error: null,
+
+  fetchUsage: async (sessionId?: string | null) => {
+    set({ isLoading: true, error: null });
+    try {
+      let response = await apiFetch(usageUrl(sessionId));
+      if (response.status === 404 && sessionId) {
+        response = await apiFetch(usageUrl());
+      }
+      if (!response.ok) {
+        throw new Error(response.statusText || 'Failed to load usage');
+      }
+      const usage = (await response.json()) as UsageResponse;
+      set({ usage, isLoading: false, error: null });
+    } catch (error) {
+      set({
+        isLoading: false,
+        error: error instanceof Error ? error.message : 'Failed to load usage',
+      });
+    }
+  },
+
+  applyUsageEvent: (sessionId, eventType, data) => {
+    const current = get().usage;
+    if (!current) return;
+    set({
+      usage: {
+        ...current,
+        session:
+          current.session?.session_id === sessionId
+            ? applyEventToBucket(current.session, eventType, data)
+            : current.session,
+        today: applyEventToBucket(current.today, eventType, data) ?? current.today,
+        month: applyEventToBucket(current.month, eventType, data) ?? current.month,
+      },
+    });
+  },
+}));

frontend/src/types/events.ts

@@ -13,6 +13,8 @@ export type EventType =
   | 'tool_log'
   | 'approval_required'
   | 'tool_state_change'
+  | 'llm_call'
+  | 'hf_job_complete'
   | 'turn_complete'
   | 'compacted'
   | 'error'

tests/unit/test_session_persistence.py

@@ -1,10 +1,13 @@
 """Unit tests for the optional durable session store abstraction."""
 
+from datetime import datetime
+
 import pytest
 
 from agent.core.session_persistence import (
     MongoSessionStore,
     NoopSessionStore,
+    USAGE_EVENT_TYPES,
     _safe_message_doc,
 )
 
@@ -126,3 +129,111 @@ async def test_noop_store_mark_pro_seen_returns_none():
     store = NoopSessionStore()
     assert await store.mark_pro_seen("u1", is_pro=True) is None
     assert await store.mark_pro_seen("u1", is_pro=False) is None
+
+
+# ── load_usage_events ────────────────────────────────────────────────────
+
+
+class _FakeAsyncCursor:
+    def __init__(self, docs):
+        self.docs = docs
+        self.sort_calls = []
+
+    def sort(self, *args, **kwargs):
+        self.sort_calls.append((args, kwargs))
+        return self
+
+    def __aiter__(self):
+        self._iter = iter(self.docs)
+        return self
+
+    async def __anext__(self):
+        try:
+            return next(self._iter)
+        except StopIteration:
+            raise StopAsyncIteration from None
+
+
+class _FakeFindCollection:
+    def __init__(self, docs):
+        self.docs = docs
+        self.find_calls = []
+        self.cursors = []
+
+    def find(self, query, projection=None):
+        self.find_calls.append((query, projection))
+        cursor = _FakeAsyncCursor(self.docs)
+        self.cursors.append(cursor)
+        return cursor
+
+
+class _FakeUsageDB:
+    def __init__(self, *, sessions, events) -> None:
+        self.sessions = _FakeFindCollection(sessions)
+        self.session_events = _FakeFindCollection(events)
+
+
+def _store_with_fake_usage_db(*, sessions, events) -> MongoSessionStore:
+    s = MongoSessionStore.__new__(MongoSessionStore)
+    s.enabled = True
+    s.db = _FakeUsageDB(sessions=sessions, events=events)
+    return s
+
+
+@pytest.mark.asyncio
+async def test_load_usage_events_scopes_mongo_queries_to_current_user_and_window():
+    start = datetime(2026, 6, 1, 0, 0)
+    end = datetime(2026, 7, 1, 0, 0)
+    store = _store_with_fake_usage_db(
+        sessions=[{"_id": "s1"}, {"_id": "s2"}],
+        events=[
+            {"session_id": "s1", "event_type": "llm_call", "data": {"cost_usd": 1.0}}
+        ],
+    )
+
+    events = await store.load_usage_events("owner", start=start, end=end)
+
+    assert events == [
+        {"session_id": "s1", "event_type": "llm_call", "data": {"cost_usd": 1.0}}
+    ]
+    assert store.db.sessions.find_calls == [
+        (
+            {"visibility": {"$ne": "deleted"}, "user_id": "owner"},
+            {"_id": 1},
+        )
+    ]
+    assert store.db.session_events.find_calls == [
+        (
+            {
+                "session_id": {"$in": ["s1", "s2"]},
+                "event_type": {"$in": list(USAGE_EVENT_TYPES)},
+                "created_at": {"$gte": start, "$lt": end},
+            },
+            None,
+        )
+    ]
+    assert store.db.session_events.cursors[0].sort_calls == []
+
+
+@pytest.mark.asyncio
+async def test_load_usage_events_dev_mode_uses_requested_session_without_user_filter():
+    store = _store_with_fake_usage_db(
+        sessions=[{"_id": "s3"}],
+        events=[{"session_id": "s3", "event_type": "hf_job_complete", "data": {}}],
+    )
+
+    events = await store.load_usage_events("dev", session_id="s3")
+
+    assert events == [{"session_id": "s3", "event_type": "hf_job_complete", "data": {}}]
+    assert store.db.sessions.find_calls == [
+        ({"visibility": {"$ne": "deleted"}, "_id": "s3"}, {"_id": 1})
+    ]
+    assert store.db.session_events.find_calls == [
+        (
+            {
+                "session_id": {"$in": ["s3"]},
+                "event_type": {"$in": list(USAGE_EVENT_TYPES)},
+            },
+            None,
+        )
+    ]

tests/unit/test_telemetry_usage.py

@@ -0,0 +1,64 @@
+from types import SimpleNamespace
+
+import pytest
+
+from agent.core import telemetry
+
+
+class FakeSession:
+    def __init__(self):
+        self.events = []
+
+    async def send_event(self, event):
+        self.events.append(event)
+
+
+@pytest.mark.asyncio
+async def test_record_hf_job_complete_emits_runtime_cost(monkeypatch):
+    async def fake_catalog():
+        return {"a100-large": 4.0}
+
+    monkeypatch.setattr(telemetry, "hf_jobs_price_catalog", fake_catalog)
+    monkeypatch.setattr(telemetry.time, "monotonic", lambda: 130.0)
+    session = FakeSession()
+
+    await telemetry.record_hf_job_complete(
+        session,
+        SimpleNamespace(id="job-1"),
+        flavor="a100-large",
+        final_status="COMPLETED",
+        submit_ts=100.0,
+    )
+
+    event = session.events[0]
+    assert event.event_type == "hf_job_complete"
+    assert event.data["wall_time_s"] == 30
+    assert event.data["billable_seconds_estimate"] == 30
+    assert event.data["price_usd_per_hour"] == 4.0
+    assert event.data["estimated_cost_usd"] == round(4.0 * 30 / 3600, 4)
+    assert event.data["cost_estimate_source"] == "runtime_price_catalog"
+
+
+@pytest.mark.asyncio
+async def test_record_hf_job_complete_keeps_unknown_hardware_countable(monkeypatch):
+    async def fake_catalog():
+        return {}
+
+    monkeypatch.setattr(telemetry, "hf_jobs_price_catalog", fake_catalog)
+    monkeypatch.setattr(telemetry.time, "monotonic", lambda: 160.0)
+    session = FakeSession()
+
+    await telemetry.record_hf_job_complete(
+        session,
+        SimpleNamespace(id="job-2"),
+        flavor="future-gpu",
+        final_status="FAILED",
+        submit_ts=100.0,
+    )
+
+    data = session.events[0].data
+    assert data["wall_time_s"] == 60
+    assert data["billable_seconds_estimate"] == 60
+    assert data["price_usd_per_hour"] is None
+    assert data["estimated_cost_usd"] is None
+    assert data["cost_estimate_source"] == "unknown_price"

tests/unit/test_usage.py

@@ -0,0 +1,362 @@
+from datetime import UTC, datetime
+import sys
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+
+_BACKEND_DIR = Path(__file__).resolve().parent.parent.parent / "backend"
+if str(_BACKEND_DIR) not in sys.path:
+    sys.path.insert(0, str(_BACKEND_DIR))
+
+from usage import (  # noqa: E402
+    _account_bucket_from_billing_usage,
+    aggregate_usage_events,
+    build_usage_response,
+    resolve_usage_windows,
+)
+
+
+def _event(event_type, data=None, created_at="2026-06-01T12:00:00+00:00"):
+    return {
+        "event_type": event_type,
+        "data": data or {},
+        "timestamp": created_at,
+    }
+
+
+def test_aggregate_usage_events_sums_inference_and_jobs():
+    events = [
+        _event(
+            "llm_call",
+            {
+                "cost_usd": 0.125,
+                "prompt_tokens": 100,
+                "completion_tokens": 50,
+                "cache_read_tokens": 25,
+                "cache_creation_tokens": 5,
+                "total_tokens": 180,
+            },
+        ),
+        _event("llm_call", {"cost_usd": 0.25, "prompt_tokens": 10}),
+        _event(
+            "hf_job_complete",
+            {
+                "estimated_cost_usd": 1.5,
+                "billable_seconds_estimate": 1800,
+            },
+        ),
+    ]
+
+    usage = aggregate_usage_events(events, session_id="s1")
+
+    assert usage["session_id"] == "s1"
+    assert usage["llm_calls"] == 2
+    assert usage["hf_jobs_count"] == 1
+    assert usage["prompt_tokens"] == 110
+    assert usage["completion_tokens"] == 50
+    assert usage["cache_read_tokens"] == 25
+    assert usage["cache_creation_tokens"] == 5
+    assert usage["total_tokens"] == 190
+    assert usage["hf_jobs_billable_seconds_estimate"] == 1800
+    assert usage["inference_usd"] == 0.375
+    assert usage["hf_jobs_estimated_usd"] == 1.5
+    assert usage["total_usd"] == 1.875
+
+
+def test_aggregate_usage_events_treats_missing_costs_as_zero():
+    usage = aggregate_usage_events(
+        [
+            _event("llm_call", {"prompt_tokens": 7}),
+            _event("hf_job_complete", {"wall_time_s": 60}),
+        ]
+    )
+
+    assert usage["llm_calls"] == 1
+    assert usage["hf_jobs_count"] == 1
+    assert usage["prompt_tokens"] == 7
+    assert usage["hf_jobs_billable_seconds_estimate"] == 60
+    assert usage["total_usd"] == 0.0
+
+
+def test_account_bucket_from_hf_billing_usage_v2():
+    usage = _account_bucket_from_billing_usage(
+        {
+            "usage": {
+                "inferenceProviders": {
+                    "usedNanoUsd": 1_500_000_000,
+                    "numRequests": 12,
+                },
+                "jobs": {
+                    "usedMicroUsd": 250_000,
+                    "totalMinutes": 3.5,
+                },
+            }
+        },
+        window_start=datetime(2026, 6, 1, 0, 0, tzinfo=UTC),
+        window_end=datetime(2026, 6, 1, 1, 0, tzinfo=UTC),
+        timezone="UTC",
+    )
+
+    assert usage["inference_providers_usd"] == 1.5
+    assert usage["hf_jobs_usd"] == 0.25
+    assert usage["total_usd"] == 1.75
+    assert usage["inference_provider_requests"] == 12
+    assert usage["hf_jobs_minutes"] == 3.5
+
+
+def test_usage_windows_respect_browser_timezone():
+    windows = resolve_usage_windows(
+        "America/Los_Angeles",
+        now=datetime(2026, 6, 1, 7, 30, tzinfo=UTC),
+    )
+
+    assert windows["timezone"] == "America/Los_Angeles"
+    assert windows["today_start_utc"] == datetime(2026, 6, 1, 7, 0, tzinfo=UTC)
+    assert windows["month_start_utc"] == datetime(2026, 6, 1, 7, 0, tzinfo=UTC)
+
+
+class _NoopStore:
+    enabled = False
+
+
+class _RecordingStore:
+    enabled = True
+
+    def __init__(self):
+        self.calls = []
+
+    async def load_usage_events(self, user_id, **kwargs):
+        self.calls.append((user_id, kwargs))
+        return []
+
+
+class _Manager:
+    def __init__(self, sessions, store=None):
+        self.sessions = sessions
+        self.store = store or _NoopStore()
+
+    def _store(self):
+        return self.store
+
+
+def _agent_session(session_id, user_id, events):
+    return SimpleNamespace(
+        session_id=session_id,
+        user_id=user_id,
+        session=SimpleNamespace(logged_events=events),
+    )
+
+
+@pytest.mark.asyncio
+async def test_runtime_usage_excludes_other_users():
+    manager = _Manager(
+        {
+            "owner-session": _agent_session(
+                "owner-session",
+                "owner",
+                [_event("llm_call", {"cost_usd": 0.5})],
+            ),
+            "other-session": _agent_session(
+                "other-session",
+                "other",
+                [_event("llm_call", {"cost_usd": 99.0})],
+            ),
+        }
+    )
+
+    usage = await build_usage_response(
+        manager,
+        user_id="owner",
+        session_id=None,
+        timezone_name="UTC",
+        now=datetime(2026, 6, 1, 13, 0, tzinfo=UTC),
+    )
+
+    assert usage["today"]["llm_calls"] == 1
+    assert usage["today"]["inference_usd"] == 0.5
+    assert usage["month"]["inference_usd"] == 0.5
+
+
+@pytest.mark.asyncio
+async def test_runtime_usage_includes_requested_session_total():
+    manager = _Manager(
+        {
+            "s1": _agent_session(
+                "s1",
+                "owner",
+                [
+                    _event(
+                        "llm_call",
+                        {"cost_usd": 0.25},
+                        created_at="2026-05-01T12:00:00+00:00",
+                    )
+                ],
+            )
+        }
+    )
+
+    usage = await build_usage_response(
+        manager,
+        user_id="owner",
+        session_id="s1",
+        timezone_name="UTC",
+        now=datetime(2026, 6, 1, 13, 0, tzinfo=UTC),
+    )
+
+    assert usage["session"]["session_id"] == "s1"
+    assert usage["session"]["inference_usd"] == 0.25
+    assert usage["today"]["inference_usd"] == 0.0
+
+
+@pytest.mark.asyncio
+async def test_runtime_usage_interprets_naive_timestamps_in_browser_timezone():
+    manager = _Manager(
+        {
+            "s1": _agent_session(
+                "s1",
+                "owner",
+                [
+                    _event(
+                        "llm_call",
+                        {"cost_usd": 0.25, "total_tokens": 42},
+                        created_at="2026-06-05T15:00:00",
+                    )
+                ],
+            )
+        }
+    )
+
+    usage = await build_usage_response(
+        manager,
+        user_id="owner",
+        session_id="s1",
+        timezone_name="Europe/Zurich",
+        now=datetime(2026, 6, 5, 13, 30, tzinfo=UTC),
+    )
+
+    assert usage["session"]["llm_calls"] == 1
+    assert usage["today"]["llm_calls"] == 1
+    assert usage["month"]["llm_calls"] == 1
+    assert usage["today"]["total_tokens"] == 42
+
+
+@pytest.mark.asyncio
+async def test_hf_account_usage_uses_session_start_for_current_delta(monkeypatch):
+    session_created_at = datetime(2026, 6, 5, 12, 0, tzinfo=UTC)
+    manager = _Manager(
+        {
+            "s1": SimpleNamespace(
+                session_id="s1",
+                user_id="owner",
+                created_at=session_created_at,
+                session=SimpleNamespace(logged_events=[]),
+            )
+        }
+    )
+    calls = []
+
+    async def fake_fetch(_token, *, start, end):
+        calls.append((start, end))
+        if start == session_created_at:
+            used_nano = 500_000_000
+        elif start == datetime(2026, 6, 5, 0, 0, tzinfo=UTC):
+            used_nano = 1_000_000_000
+        else:
+            used_nano = 2_000_000_000
+        return {
+            "usage": {
+                "inferenceProviders": {
+                    "usedNanoUsd": used_nano,
+                    "includedNanoUsd": 2_000_000_000,
+                    "limitNanoUsd": 5_000_000_000,
+                    "numRequests": 4,
+                },
+                "jobs": {"usedMicroUsd": 0, "totalMinutes": 0},
+            }
+        }
+
+    monkeypatch.setattr("usage._fetch_hf_billing_usage_v2", fake_fetch)
+
+    usage = await build_usage_response(
+        manager,
+        user_id="owner",
+        hf_token="hf_fake",
+        session_id="s1",
+        timezone_name="UTC",
+        now=datetime(2026, 6, 5, 13, 0, tzinfo=UTC),
+    )
+
+    assert usage["hf_account"]["available"] is True
+    assert usage["hf_account"]["current_session"]["inference_providers_usd"] == 0.5
+    assert usage["hf_account"]["today"]["inference_providers_usd"] == 1.0
+    assert usage["hf_account"]["month"]["inference_providers_usd"] == 2.0
+    assert usage["hf_account"]["inference_providers_credits"] == {
+        "included_usd": 2.0,
+        "used_usd": 2.0,
+        "remaining_included_usd": 0.0,
+        "limit_usd": 5.0,
+        "remaining_limit_usd": 3.0,
+        "num_requests": 4,
+        "period_start": None,
+        "period_end": None,
+    }
+    assert {start for start, _ in calls} == {
+        datetime(2026, 6, 5, 0, 0, tzinfo=UTC),
+        datetime(2026, 6, 1, 0, 0, tzinfo=UTC),
+        session_created_at,
+    }
+
+
+@pytest.mark.asyncio
+async def test_compact_usage_skips_unused_rollup_loads(monkeypatch):
+    session_created_at = datetime(2026, 6, 5, 12, 0, tzinfo=UTC)
+    store = _RecordingStore()
+    manager = _Manager(
+        {
+            "s1": SimpleNamespace(
+                session_id="s1",
+                user_id="owner",
+                created_at=session_created_at,
+                session=SimpleNamespace(logged_events=[]),
+            )
+        },
+        store=store,
+    )
+    billing_starts = []
+
+    async def fake_fetch(_token, *, start, end):
+        billing_starts.append(start)
+        return {
+            "usage": {
+                "inferenceProviders": {
+                    "usedNanoUsd": 0,
+                    "includedNanoUsd": 2_000_000_000,
+                    "limitNanoUsd": 0,
+                },
+                "jobs": {"usedMicroUsd": 0, "totalMinutes": 0},
+            }
+        }
+
+    monkeypatch.setattr("usage._fetch_hf_billing_usage_v2", fake_fetch)
+
+    usage = await build_usage_response(
+        manager,
+        user_id="owner",
+        hf_token="hf_fake",
+        session_id="s1",
+        timezone_name="UTC",
+        now=datetime(2026, 6, 5, 13, 0, tzinfo=UTC),
+        include_rollups=False,
+    )
+
+    assert store.calls == [("owner", {"session_id": "s1", "start": None, "end": None})]
+    assert set(billing_starts) == {
+        datetime(2026, 6, 1, 0, 0, tzinfo=UTC),
+        session_created_at,
+    }
+    assert datetime(2026, 6, 5, 0, 0, tzinfo=UTC) not in billing_starts
+    assert usage["today"]["llm_calls"] == 0
+    assert usage["month"]["llm_calls"] == 0
+    assert usage["hf_account"]["today"] is None
+    assert usage["hf_account"]["month"]["inference_providers_usd"] == 0.0