Skip to content

Dodaios is an open-source agent OS for your desktop: it runs your coding agents, browser and apps by voice or chat, on your own machine. Formerly Personal Jarvis.

20.1 KB
Raw Blame
"""Reading how much of each subscription's plan is already spent.

What these pin down is not "does the JSON parse" but the handful of ways a
usage meter can be confidently wrong, which is worse than having none at all:

* a CACHED reading must never be reported as a live one — it is the number a
  user picks a subscription on, and for an idle seat it can be days old;
* a per-model weekly budget must survive alongside the overall weekly one,
  because 55% overall next to 99% on one model is the case where "plenty left"
  is the wrong conclusion;
* which of Codex's two windows is the short one is decided by its LENGTH, not
  by the slot it arrives in;
* a CLI with no reader must get an honest "unsupported", never a neighbouring
  provider's numbers;
* nothing here ever reaches the network in a test, and nothing ever returns a
  token.
"""

from __future__ import annotations

import json
from pathlib import Path

import pytest

from dodaios import agent_usage
from dodaios.agent_accounts import AgentAccount

#: Captured before any fixture runs. The autouse ``_no_network`` fixture below
#: replaces the module attribute, so a test that wants to exercise the REAL
#: transport helper cannot read it back off the module — it would get the stub.
_REAL_HTTP_GET_JSON = agent_usage._http_get_json


@pytest.fixture(autouse=True)
def _no_cache_between_tests() -> None:
    agent_usage.clear_cache()


@pytest.fixture(autouse=True)
def _no_network(monkeypatch: pytest.MonkeyPatch) -> None:
    """Every live probe fails unless a test opts in.

    A unit test that quietly reaches the real provider is a test that passes on
    the maintainer's machine and hangs in CI, so the default is "no answer" and
    the disk fallbacks are what get exercised.
    """
    monkeypatch.setattr(agent_usage, "_http_get_json", lambda url, headers: None)


def _account(platform: str, config_dir: Path, *, builtin: bool = False) -> AgentAccount:
    return AgentAccount(
        id=f"{platform}:test",
        platform=platform,
        label="Test seat",
        config_dir=config_dir,
        builtin=builtin,
    )


# ----------------------------------------------------------------- claude


CLAUDE_LIMITS_PAYLOAD = {
    "five_hour": {"utilization": 2.0, "resets_at": "2026-08-13T13:20:00+00:00"},
    "seven_day": {"utilization": 74.0, "resets_at": "2026-08-14T06:00:00+00:00"},
    "limits": [
        {
            "kind": "session",
            "group": "session",
            "percent": 2,
            "severity": "normal",
            "resets_at": "2026-08-13T13:20:00+00:00",
            "scope": None,
        },
        {
            "kind": "weekly_all",
            "group": "weekly",
            "percent": 74,
            "severity": "normal",
            "resets_at": "2026-08-14T06:00:00+00:00",
            "scope": None,
        },
        {
            "kind": "weekly_scoped",
            "group": "weekly",
            "percent": 100,
            "severity": "critical",
            "resets_at": "2026-08-14T06:00:00+00:00",
            "scope": {"model": {"id": None, "display_name": "Fable"}, "surface": None},
        },
    ],
}


def test_claude_keeps_the_scoped_weekly_budget_next_to_the_overall_one() -> None:
    """A model at 100% must not be hidden behind an overall week at 74%."""
    windows = agent_usage._claude_windows(CLAUDE_LIMITS_PAYLOAD)
    kinds = [w.kind for w in windows]
    assert kinds == ["session", "weekly", "weekly_scoped"]
    scoped = windows[2]
    assert scoped.percent == 100
    assert scoped.severity == "critical"
    assert scoped.scope_label == "Fable"


def test_claude_uses_the_providers_own_severity_not_its_own_arithmetic() -> None:
    """74% is 'normal' because the provider said so, not because 74 < 80."""
    payload = {
        "limits": [
            {"kind": "weekly_all", "group": "weekly", "percent": 12, "severity": "critical"},
        ]
    }
    (window,) = agent_usage._claude_windows(payload)
    assert window.severity == "critical"


def test_claude_falls_back_to_the_named_fields_when_there_is_no_limits_array() -> None:
    """An older payload shape still shows both headline numbers."""
    payload = {
        "five_hour": {"utilization": 10.0, "resets_at": "2026-08-13T13:20:00+00:00"},
        "seven_day": {"utilization": 90.0, "resets_at": "2026-08-14T06:00:00+00:00"},
    }
    windows = agent_usage._claude_windows(payload)
    assert [w.kind for w in windows] == ["session", "weekly"]
    assert windows[0].window_minutes == 300
    assert windows[1].window_minutes == 10080
    # No severity is stated in this shape, so the shared scale decides.
    assert windows[1].severity == "warning"


def test_claude_reports_a_disk_reading_as_cached_with_the_providers_timestamp(
    tmp_path: Path,
) -> None:
    """The whole honesty contract: an old number must not look like a live one."""
    (tmp_path / ".claude.json").write_text(
        json.dumps(
            {
                "oauthAccount": {"organizationRateLimitTier": "default_claude_max_20x"},
                "cachedUsageUtilization": {
                    "fetchedAtMs": 1786557552405,
                    "utilization": CLAUDE_LIMITS_PAYLOAD,
                },
            }
        ),
        encoding="utf-8",
    )
    usage = agent_usage.read_usage(_account("claude", tmp_path))
    assert usage.status == "ok"
    assert usage.source == "cached"
    assert usage.as_of == pytest.approx(1786557552.405)
    assert usage.plan == "Max 20x"
    assert len(usage.windows) == 3


def test_claude_without_any_login_says_signed_out_rather_than_zero_percent(
    tmp_path: Path,
) -> None:
    """An empty seat must not draw a reassuring 0% bar."""
    usage = agent_usage.read_usage(_account("claude", tmp_path))
    assert usage.status == "signed_out"
    assert usage.windows == ()


def test_an_unmapped_plan_tier_is_still_shown_readably(tmp_path: Path) -> None:
    (tmp_path / ".claude.json").write_text(
        json.dumps({"oauthAccount": {"organizationRateLimitTier": "default_claude_max_50x"}}),
        encoding="utf-8",
    )
    usage = agent_usage.read_usage(_account("claude", tmp_path))
    assert usage.plan == "Max 50X"


# ------------------------------------------------------------------ codex


def _codex_signed_in(config_dir: Path) -> None:
    (config_dir / "auth.json").write_text(
        json.dumps({"tokens": {"access_token": "not-a-real-token", "account_id": "acct"}}),
        encoding="utf-8",
    )


def test_codex_names_its_windows_by_length_not_by_slot() -> None:
    """'primary' is not always the weekly one — the window length decides."""
    windows = agent_usage._codex_rate_limit_windows(
        {
            "primary": {"used_percent": 40.0, "window_minutes": 10080, "resets_at": 1786977114},
            "secondary": {"used_percent": 8.0, "window_minutes": 300, "resets_at": 1786900000},
        }
    )
    # Sorted shortest window first, which is also the display order.
    assert [w.kind for w in windows] == ["session", "weekly"]
    assert windows[0].percent == 8.0
    assert windows[1].percent == 40.0
    assert windows[0].resets_at is not None and windows[0].resets_at.endswith("+00:00")


def test_codex_recognises_a_thirty_day_window_as_monthly() -> None:
    """Measured on a real seat: 43200 minutes must not read as 'other'."""
    (window,) = agent_usage._codex_rate_limit_windows(
        {"primary": {"used_percent": 70.0, "window_minutes": 43200, "resets_at": 1789000000}}
    )
    assert window.kind == "monthly"


def test_codex_reads_the_newest_rate_limits_out_of_a_session_transcript(
    tmp_path: Path,
) -> None:
    """The disk fallback that carries this feature when the endpoint cannot."""
    _codex_signed_in(tmp_path)
    sessions = tmp_path / "sessions" / "2026" / "08" / "13"
    sessions.mkdir(parents=True)
    rollout = sessions / "rollout-2026-08-13T10-00-00-abc.jsonl"
    lines = [
        json.dumps({"timestamp": "2026-08-13T09:00:00.000Z", "type": "event_msg", "payload": {}}),
        json.dumps(
            {
                "timestamp": "2026-08-13T09:30:00.000Z",
                "type": "event_msg",
                "payload": {
                    "type": "token_count",
                    "rate_limits": {
                        "primary": {"used_percent": 11.0, "window_minutes": 10080},
                    },
                },
            }
        ),
        json.dumps(
            {
                "timestamp": "2026-08-13T10:00:00.000Z",
                "type": "event_msg",
                "payload": {
                    "type": "token_count",
                    "rate_limits": {
                        "plan_type": "plus",
                        "primary": {"used_percent": 23.0, "window_minutes": 10080},
                    },
                },
            }
        ),
    ]
    rollout.write_text("\n".join(lines) + "\n", encoding="utf-8")

    usage = agent_usage.read_usage(_account("codex", tmp_path))
    assert usage.status == "ok"
    assert usage.source == "cached"
    assert usage.plan == "Plus"
    # The LAST record wins — an earlier one in the same file is strictly older.
    assert [w.percent for w in usage.windows] == [23.0]


def test_codex_finds_the_record_in_a_transcript_larger_than_the_tail_window(
    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    """Only the tail is read, so the seek must not cut the answer off."""
    monkeypatch.setattr(agent_usage, "ROLLOUT_TAIL_BYTES", 2048)
    _codex_signed_in(tmp_path)
    sessions = tmp_path / "sessions"
    sessions.mkdir(parents=True)
    rollout = sessions / "rollout-big.jsonl"
    padding = [json.dumps({"type": "noise", "payload": {"blob": "x" * 200}}) for _ in range(200)]
    answer = json.dumps(
        {
            "timestamp": "2026-08-13T10:00:00.000Z",
            "payload": {"rate_limits": {"primary": {"used_percent": 5.0, "window_minutes": 300}}},
        }
    )
    rollout.write_text("\n".join([*padding, answer]) + "\n", encoding="utf-8")

    usage = agent_usage.read_usage(_account("codex", tmp_path))
    assert usage.status == "ok"
    assert [w.kind for w in usage.windows] == ["session"]


def test_codex_on_an_api_key_says_there_is_no_plan_limit(tmp_path: Path) -> None:
    """Per-request billing has no window to spend down — an empty bar would lie."""
    (tmp_path / "auth.json").write_text(json.dumps({"OPENAI_API_KEY": "sk-test"}), encoding="utf-8")
    usage = agent_usage.read_usage(_account("codex", tmp_path))
    assert usage.status == "unsupported"


def test_codex_signed_in_but_never_used_is_unavailable_not_zero(tmp_path: Path) -> None:
    _codex_signed_in(tmp_path)
    usage = agent_usage.read_usage(_account("codex", tmp_path))
    assert usage.status == "unavailable"
    assert usage.windows == ()


# ---------------------------------------------------------------- generic


def test_an_unknown_cli_gets_an_honest_answer_not_a_neighbours_numbers(
    tmp_path: Path,
) -> None:
    """The failure an `if claude / else codex` pair would produce silently."""
    (tmp_path / ".claude.json").write_text(
        json.dumps({"cachedUsageUtilization": {"utilization": CLAUDE_LIMITS_PAYLOAD}}),
        encoding="utf-8",
    )
    usage = agent_usage.read_usage(_account("some-new-cli", tmp_path))
    assert usage.status == "unsupported"
    assert usage.windows == ()


def test_supports_usage_reports_only_the_clis_with_a_real_reader() -> None:
    assert agent_usage.supports_usage("claude") is True
    assert agent_usage.supports_usage("codex") is True
    assert agent_usage.supports_usage("some-new-cli") is False


# ------------------------------------------------------------- collect/cache


def test_collect_serves_the_cache_until_the_ttl_expires(tmp_path: Path) -> None:
    """The panel polls; a percentage does not move fast enough to re-ask each time."""
    calls: list[str] = []
    account = _account("claude", tmp_path)

    def counting_reader(acc: AgentAccount) -> agent_usage.AccountUsage:
        calls.append(acc.id)
        return agent_usage.AccountUsage(account_id=acc.id, platform=acc.platform, status="ok")

    original = agent_usage._READERS["claude"]
    agent_usage._READERS["claude"] = counting_reader
    try:
        agent_usage.collect([account])
        agent_usage.collect([account])
        assert calls == [account.id]
        # A forced refresh is what the manual button does, and it must bypass it.
        agent_usage.collect([account], refresh=True)
        assert len(calls) == 2
        # A zero TTL means "never reuse", which is how the tests above stay honest.
        agent_usage.collect([account], ttl=0)
        assert len(calls) == 3
    finally:
        agent_usage._READERS["claude"] = original


def test_a_reader_that_raises_costs_one_row_not_the_panel(tmp_path: Path) -> None:
    account = _account("claude", tmp_path)

    def exploding_reader(_acc: AgentAccount) -> agent_usage.AccountUsage:
        raise RuntimeError("provider changed everything")

    original = agent_usage._READERS["claude"]
    agent_usage._READERS["claude"] = exploding_reader
    try:
        usage = agent_usage.read_usage(account)
    finally:
        agent_usage._READERS["claude"] = original
    assert usage.status == "unavailable"


def test_no_reading_ever_carries_a_credential(tmp_path: Path) -> None:
    """The wire shape is display-only by construction."""
    (tmp_path / ".claude.json").write_text(
        json.dumps({"cachedUsageUtilization": {"utilization": CLAUDE_LIMITS_PAYLOAD}}),
        encoding="utf-8",
    )
    (tmp_path / ".credentials.json").write_text(
        json.dumps(
            {
                "claudeAiOauth": {
                    "accessToken": "sk-ant-oat-secret",
                    "refreshToken": "refresh-secret",
                    "expiresAt": 1,
                }
            }
        ),
        encoding="utf-8",
    )
    payload = json.dumps(agent_usage.read_usage(_account("claude", tmp_path)).to_dict())
    assert "secret" not in payload
    assert "sk-ant" not in payload


# ------------------------------------------------------------------ shared


@pytest.mark.parametrize(
    ("percent", "expected"),
    [(0.0, "normal"), (79.9, "normal"), (80.0, "warning"), (94.9, "warning"), (95.0, "critical")],
)
def test_one_severity_scale_serves_every_provider(percent: float, expected: str) -> None:
    """Two rows at the same percentage must never be coloured differently."""
    assert agent_usage._severity(percent) == expected


def test_an_unreachable_host_is_left_alone_but_an_http_error_is_retried(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    """An offline machine must not pay a six-second timeout on every poll.

    The asymmetry is the point: being unreachable is expensive and stays true
    for a while, so it earns a cooldown. An HTTP status answers instantly, so
    retrying it costs nothing — and cooling THAT down would keep a seat on
    cached numbers for minutes after a one-off server hiccup.
    """
    monkeypatch.setattr(agent_usage, "_http_get_json", _REAL_HTTP_GET_JSON)
    agent_usage.clear_cache()

    attempts: list[str] = []

    class _Unreachable:
        def get(self, url: str, **_kw: object) -> object:
            attempts.append(url)
            raise OSError("no route to host")

    class _Rejecting:
        def get(self, url: str, **_kw: object) -> object:
            attempts.append(url)

            class _Response:
                status_code = 403

                def json(self) -> object:
                    return {}

            return _Response()

    monkeypatch.setattr(agent_usage._HTTP_POOL, "client", lambda: _Unreachable())
    assert agent_usage._http_get_json("https://example.invalid/u", {}) is None
    assert agent_usage._http_get_json("https://example.invalid/u", {}) is None
    assert attempts == ["https://example.invalid/u"], "the second probe must be skipped"

    attempts.clear()
    agent_usage.clear_cache()
    monkeypatch.setattr(agent_usage._HTTP_POOL, "client", lambda: _Rejecting())
    assert agent_usage._http_get_json("https://example.invalid/v", {}) is None
    assert agent_usage._http_get_json("https://example.invalid/v", {}) is None
    assert len(attempts) == 2, "a rejected request must still be retried"


def test_an_over_consumed_window_is_clamped_to_full_rather_than_dropped() -> None:
    """103% means 'full'; refusing to draw it would hide the worst state."""
    assert agent_usage._clamp_percent(103) == 100.0
    assert agent_usage._clamp_percent(-5) == 0.0
    assert agent_usage._clamp_percent("nope") is None
    assert agent_usage._clamp_percent(True) is None


def test_codex_spark_never_replaces_the_main_weekly_allowance(tmp_path: Path) -> None:
    _codex_signed_in(tmp_path)
    sessions = tmp_path / "sessions"
    sessions.mkdir()

    def event(stamp, limit_id, percent):
        return json.dumps(
            {
                "timestamp": stamp,
                "payload": {
                    "rate_limits": {
                        "limit_id": limit_id,
                        "plan_type": "pro",
                        "primary": {"used_percent": percent, "window_minutes": 10080},
                    }
                },
            }
        )

    # The same stream can report the main allowance followed by a Spark update.
    (sessions / "rollout-main.jsonl").write_text(
        event("2026-09-10T12:00:00Z", "codex", 46)
        + "\n"
        + event("2026-09-10T12:01:00Z", "codex_bengalfox", 0),
        encoding="utf-8",
    )
    # A newly touched transcript is not necessarily the freshest measurement.
    (sessions / "rollout-old.jsonl").write_text(
        event("2026-09-09T12:00:00Z", "codex", 20), encoding="utf-8"
    )
    usage = agent_usage.read_usage(_account("codex", tmp_path))
    assert usage.status == "ok" and usage.source == "cached"
    assert [(w.kind, w.percent) for w in usage.windows] == [("weekly", 46)]


def test_codex_spark_only_is_unavailable_not_an_empty_main_budget(tmp_path: Path) -> None:
    _codex_signed_in(tmp_path)
    sessions = tmp_path / "sessions"
    sessions.mkdir()
    (sessions / "rollout-spark.jsonl").write_text(
        json.dumps(
            {
                "payload": {
                    "rate_limits": {
                        "limit_id": "codex_bengalfox",
                        "primary": {"used_percent": 0, "window_minutes": 10080},
                    }
                }
            }
        ),
        encoding="utf-8",
    )
    assert agent_usage.read_usage(_account("codex", tmp_path)).status == "unavailable"


@pytest.mark.parametrize("percent", [0, 54, 100])
def test_grok_build_reads_live_credit_usage_for_its_own_account(tmp_path, monkeypatch, percent):
    scope = "https://auth.x.ai::b1a00492-073a-47ea-816f-4c329264a828"
    (tmp_path / "auth.json").write_text(
        json.dumps(
            {
                scope: {
                    "auth_mode": "oidc",
                    "key": "grok-test-bearer",
                }
            }
        ),
        encoding="utf-8",
    )

    def get(url, headers):
        assert url == "https://cli-chat-proxy.grok.com/v1/billing?format=credits"
        assert headers["Authorization"] == "Bearer grok-test-bearer"
        return {
            "config": {
                "creditUsagePercent": percent,
                "currentPeriod": {
                    "type": "USAGE_PERIOD_TYPE_WEEKLY",
                    "end": "2026-09-14T12:59:05Z",
                },
            }
        }

    monkeypatch.setattr(agent_usage, "_http_get_json", get)
    usage = agent_usage.read_usage(_account("grok-build", tmp_path))
    assert usage.status == "ok" and usage.source == "live"
    assert usage.windows[0].kind == "weekly" and usage.windows[0].percent == percent
    assert usage.windows[0].resets_at is not None
    assert "grok-test-bearer" not in json.dumps(usage.to_dict())


def test_grok_missing_usage_does_not_invent_zero(tmp_path, monkeypatch):
    scope = "https://auth.x.ai::b1a00492-073a-47ea-816f-4c329264a828"
    (tmp_path / "auth.json").write_text(
        json.dumps(
            {
                scope: {
                    "auth_mode": "oidc",
                    "key": "grok-test-bearer",
                }
            }
        ),
        encoding="utf-8",
    )
    monkeypatch.setattr(agent_usage, "_http_get_json", lambda *args: {"config": {}})
    usage = agent_usage.read_usage(_account("grok-build", tmp_path))
    assert usage.status == "unavailable" and usage.windows == ()