fix(cline-pass): correct upstream-id reverse map and API base path

Follows PR #122 (squash-merged to dev as commit 8a23432) with two
bug fixes that surfaced after deployment.

Bug 1 — empty WebUI quota card (deployment 2026-07-11 ~02:34 UTC):

  The quota tracker's _build_billing_url() defensively stripped a
  trailing /v1 from the resolved base, producing the wrong URL:

    https://api.cline.bot/api/users/me/plan/usage-limits

  instead of the correct documented path:

    https://api.cline.bot/api/v1/users/me/plan/usage-limits

  The upstream call 404'd, no baselines landed in UsageManager, and
  the /v1/quota-stats filter (total_requests == 0 and no quota data)
  dropped the provider entirely from the response.

  Fix: removed the trailing-/v1 strip in _build_billing_url. The
  Cline API is a flat /api/v1 namespace — the helper just joins
  base + path. Also unified provider routing on self.api_base so
  chat completions, model discovery, and quota polling all hit
  the same documented /api/v1/... prefix.

  Root cause: first cut conflated 'OpenAI-compatible body' with
  'OpenAI-compatible path prefix'. Cline's API is rooted at /api/v1/,
  not /v1/.

Bug 2 — upstream-id double-prefix (Kilo Code review on PR #122):

  _build_reverse_map wrapped the already-prefixed upstream ids
  (`cline-pass/glm-5.2`) with `cline_pass/` again, producing
  double-prefixed keys (`cline_pass/cline-pass/glm-5.2`) that
  `normalize_model_for_tracking` never matched. As a result, raw
  upstream ids from Cline error messages and quota breakdowns
  were passed through unchanged instead of being mapped to the
  proxy's display names — breaking the very 'WebUI/pricing maps
  upstream → display' feature the original PR description called
  out.

  Umans does not have this bug because its UMANS_MODELS upstream
  ids are bare (`umans-kimi-k2.6`); wrapping with `umans/`
  produces a valid reverse-map key. ClinePass cannot reuse that
  trick because the upstream ids already include the `cline-pass/`
  prefix.

  Fix: _build_reverse_map stores the raw upstream id as the key
  (no proxy prefix wrapping) and the proxy display name
  (`cline_pass/<bare>`) as the value. normalize_model_for_tracking
  handles all three caller-input shapes (raw upstream id, proxy
  display name, bare) and returns the canonical display name.

Stack compliance:

  Adds a `cline-pass` entry under `allowed_duplicate_features` in
  `.fork/stack.yml` since this is a `fix()` companion to the
  existing `feat(cline-pass):` commit on dev. The xai and umans
  feature areas already follow this pattern.

Regression coverage (10 new tests, all pass):

  test_build_billing_url_default_base_passes_path_through
  test_build_billing_url_preserves_v1_in_api_v1_base
  test_build_billing_url_trailing_slash_on_base_is_normalised
  test_provider_api_base_default_uses_documented_upstream
  test_provider_uses_single_api_base_for_both_models_and_chat
  test_build_reverse_map_keys_are_raw_upstream_ids
  test_normalize_model_from_raw_upstream_id
  test_normalize_model_from_proxy_display_name
  test_normalize_model_from_bare_name
  test_normalize_model_unknown_returns_input

  The test_provider_* tests pin both the documented upstream URLs
  and the single-base invariant so a future split between
  quota/chat/models bases will fail CI loudly instead of silently
  404'ing in production.

Verification:

  uv run python3 -m py_compile — passed (all 3 changed Python files)
  uv run ruff check --select F401,F811,F821,E9 — passed
  uv run --with pytest python3 -m pytest tests/test_cline_pass_quota_tracker.py -q
    — 34 passed
  uv run --with pytest --with pytest-asyncio python3 -m pytest tests/ -q
    — 493 passed (+3 from this branch); same 15 pre-existing setup
    errors and same 2 pre-existing umans/xai test failures as dev
    (unrelated to this PR).

Files (5):

  src/rotator_library/providers/cline_pass_provider.py
  src/rotator_library/providers/utilities/cline_pass_quota_tracker.py
  tests/test_cline_pass_quota_tracker.py
  .fork/stack.yml
  .fork/features/cline-pass.md

Author: b3nw

.fork/features/cline-pass.md

@@ -151,3 +151,71 @@ Notes:
   `SingletonABCMeta` singleton so all test cases share one instance,
   and the `__init__`-built reverse map is reused across cases. No
   cleanup needed (and cleanup would actually break later tests).
+
+## 2026-07-11 — Fix wrong API base path (deployment hotfix)
+
+Target: `feat(cline-pass): add ClinePass provider with 3-window quota tracking`
+Files:
+- `src/rotator_library/providers/cline_pass_provider.py`
+- `src/rotator_library/providers/utilities/cline_pass_quota_tracker.py`
+- `tests/test_cline_pass_quota_tracker.py`
+
+Problem (caught from production deployment on 2026-07-11, 02:34 UTC):
+1. **Chat completions returned 404.** The provider class introduced
+   a separate `CLINE_PASS_LITELLM_BASE = "https://api.cline.bot/v1"`
+   for chat routing (assumption: "Cline is OpenAI-shaped, base is
+   `/v1`"). The actual upstream path is
+   `https://api.cline.bot/api/v1/chat/completions` — the prefix is
+   `/api/v1`, not `/v1`. Every request landed at
+   `https://api.cline.bot/v1/chat/completions` and 404'd.
+2. **Quota card empty in WebUI.** The quota tracker's
+   `_build_billing_url()` defensively stripped a trailing `/v1` from
+   `_resolve_api_base()`, producing
+   `https://api.cline.bot/api/users/me/plan/usage-limits` instead
+   of the correct
+   `https://api.cline.bot/api/v1/users/me/plan/usage-limits`. The
+   upstream call 404'd, baseline writes never happened, and the
+   `/v1/quota-stats` filter (`total_requests == 0 and no quota data`)
+   then dropped the provider from the response.
+
+Root cause (both bugs):
+- Mistakenly assumed "OpenAI-compatible *body*" implied "OpenAI-compatible
+  *path prefix*". Cline's API uses `/api/v1/`, not `/v1/`. The
+  original writeup's `cline.md` documented the quota endpoint URL as
+  `https://api.cline.bot/api/v1/users/me/plan/usage-limits` — if
+  that had been more directly referenced during the first cut, the
+  bug would have been caught.
+- The first cut unhelpfully split into two bases (one for quota, one
+  for chat) and then rewrote the quota URL. The chat URL was wrong
+  by construction; the quota URL was wrong by post-processing.
+
+Fix:
+- Drop `CLINE_PASS_LITELLM_BASE` and the `self.litellm_base`
+  attribute. Chat completions now use `self.api_base`, same as
+  quota and model discovery. `self.api_base` defaults to
+  `https://api.cline.bot/api/v1` and is overridable via
+  `CLINE_PASS_API_BASE`.
+- Remove the trailing-`/v1` strip in `_build_billing_url()`. The
+  upstream is a flat `/api/v1` namespace — the helper just joins
+  base + path.
+- Update the docstring on the constant to call out the path-prefix
+  gotcha so this doesn't regress.
+
+Regression coverage (4 new tests, all pass):
+- `test_build_billing_url_default_base_passes_path_through` — default
+  base yields `https://api.cline.bot/api/v1/users/me/plan`.
+- `test_build_billing_url_preserves_v1_in_api_v1_base` — pinning
+  the no-strip behavior.
+- `test_build_billing_url_trailing_slash_on_base_is_normalised` —
+  trailing slash on the base doesn't double up.
+- `test_provider_api_base_default_uses_documented_upstream` —
+  provider default matches the Cline docs.
+- `test_provider_uses_single_api_base_for_both_models_and_chat` —
+  pinning the single-base invariant so a future split can't
+  reintroduce Bug 1.
+
+Verification:
+- `uv run python3 -m py_compile` — passed (all 3 files)
+- `uv run ruff check --select F401,F811,F821,E9` — passed (all 3 files)
+- `uv run --with pytest python3 -m pytest tests/test_cline_pass_quota_tracker.py -q` — 34 passed
+- `uv run --with pytest --with pytest-asyncio python3 -m pytest tests/ -q` — 493 passed (+3), same 15 pre-existing setup errors and same 2 pre-existing umans/xai test failures as `dev` (unrelated to this PR).

.fork/stack.yml

@@ -26,6 +26,10 @@ rules:
       - "feat(xai): add xAI Grok OAuth provider with PKCE and Device Code flows"
       - "feat(xai): enable xAI Grok device-code OAuth in admin WebUI"
       - "fix(xai): set Grok Build User-Agent on all requests to fix billing classification"
+      - "feat(xai): route all chat completions through CLI proxy"
+    cline-pass:
+      - "fix(cline-pass): correct upstream-id reverse map and API base path"
+      - "feat(cline-pass): add ClinePass provider with 3-window quota tracking"
     umans:
       - "feat(umans): add Umans provider with request-based quota tracking"
       - "fix(umans): normalize API base and show quota without proxy requests"

src/rotator_library/providers/cline_pass_provider.py

@@ -76,11 +76,12 @@
     "qwen3.7-plus": {"id": "cline-pass/qwen3.7-plus"},
 }
 
-# The Cline API base includes the ``/api/v1`` path prefix (different from
-# standard OpenAI's ``/v1``). We strip it here and re-add ``/v1`` for
-# LiteLLM's openai/ provider, which expects the conventional shape.
+# The Cline API is rooted at https://api.cline.bot/api/v1 — every endpoint
+# (chat completions, models, usage-limits, plan) lives under that /api/v1
+# prefix. Do NOT use the standard OpenAI ``/v1`` shape here: Cline's path is
+# ``/api/v1/chat/completions``, not ``/v1/chat/completions``. (Deployment
+# 2026-07-11: routing via ``/v1`` produced 404s.)
 CLINE_PASS_DEFAULT_API_BASE = "https://api.cline.bot/api/v1"
-CLINE_PASS_LITELLM_BASE = "https://api.cline.bot/v1"
 
 # Litellm params accepted for the openai/ provider route. Mirrors the
 # x_ai / ollama_cloud allowlists; conservative subset that the Cline API
@@ -152,9 +153,6 @@ def __init__(self):
         self.api_base = os.getenv(
             "CLINE_PASS_API_BASE", CLINE_PASS_DEFAULT_API_BASE
         )
-        self.litellm_base = os.getenv(
-            "CLINE_PASS_LITELLM_BASE", CLINE_PASS_LITELLM_BASE
-        )
         self.model_definitions = ModelDefinitions()
         # Upstream-id -> display-name reverse map (mirrors Umans pattern).
         # Built lazily from the active model catalog (env override first,
@@ -371,13 +369,16 @@ async def acompletion(
                 f"(set CLINE_PASS_MODELS or update DEFAULT_CLINEPASS_MODELS)"
             )
 
+        # ``self.api_base`` is rooted at ``/api/v1`` — LiteLLM's openai/
+        # provider appends ``/chat/completions`` to whatever base you give
+        # it, so the resulting URL is ``https://api.cline.bot/api/v1/chat/completions``.
         kwargs["model"] = f"openai/{upstream_id}"
         kwargs["api_key"] = credential
-        kwargs["api_base"] = self.litellm_base
+        kwargs["api_base"] = self.api_base
         kwargs["custom_llm_provider"] = "openai"
         kwargs["client"] = openai.AsyncOpenAI(
             api_key=credential,
-            base_url=self.litellm_base,
+            base_url=self.api_base,
             http_client=client,
         )
 

src/rotator_library/providers/utilities/cline_pass_quota_tracker.py

@@ -148,7 +148,14 @@ def _as_optional_float(value: Any) -> Optional[float]:
 
 
 def _resolve_api_base() -> str:
-    """Resolve the Cline API base (allows override for testing)."""
+    """Resolve the Cline API base (allows override for testing).
+
+    The upstream is rooted at https://api.cline.bot/api/v1 — every
+    endpoint (chat completions, models, usage-limits, plan) lives
+    under that ``/api/v1`` prefix. We do **not** strip the trailing
+    ``/v1``: doing so produces ``https://api.cline.bot/api/...`` which
+    404s on the upstream (caught in deployment 2026-07-11).
+    """
     # ``or`` (not the second arg of getenv) so an empty string falls back to
     # the default — operators occasionally set ``CLINE_PASS_API_BASE=""`` to
     # "reset" and we shouldn't break the tracker when they do.
@@ -158,12 +165,13 @@ def _resolve_api_base() -> str:
 
 
 def _build_billing_url(path: str) -> str:
-    """Join the API base with a path, tolerating a base that already ends with ``/v1``."""
+    """Join the API base with a path.
+
+    The Cline API is a flat ``/api/v1`` namespace; no path rewriting is
+    needed. Path may be passed with or without a leading slash.
+    """
     base = _resolve_api_base()
     suffix = path if path.startswith("/") else f"/{path}"
-    # If the base already includes /v1, strip it so we never produce /v1/v1
-    if base.endswith("/v1"):
-        base = base[:-3]
     return f"{base}{suffix}"
 
 

tests/test_cline_pass_quota_tracker.py

@@ -62,28 +62,40 @@ def test_coerce_percent_rejects_bools():
 # ---------------------------------------------------------------------------
 
 
-def test_build_billing_url_strips_trailing_v1():
+def test_build_billing_url_default_base_passes_path_through():
+    """Default base ``https://api.cline.bot/api/v1`` is the upstream's
+    flat namespace — no path rewriting. The URL helper just joins the
+    base with the caller-supplied path.
+
+    Regression for the deployment on 2026-07-11: the previous
+    implementation stripped a trailing ``/v1`` from the base, producing
+    ``https://api.cline.bot/api/...`` paths that 404'd upstream and
+    meant quota baselines never landed in the UsageManager (the WebUI
+    quota card then had no data to render).
+    """
     with patch.dict(
         "os.environ",
-        {"CLINE_PASS_API_BASE": "https://api.cline.bot/api/v1"},
+        {"CLINE_PASS_API_BASE": ""},
         clear=False,
     ):
         assert (
-            _build_billing_url("/users/me/plan/usage-limits")
-            == "https://api.cline.bot/api/users/me/plan/usage-limits"
+            _build_billing_url("/users/me/plan")
+            == "https://api.cline.bot/api/v1/users/me/plan"
         )
 
 
-def test_build_billing_url_default_base():
+def test_build_billing_url_preserves_v1_in_api_v1_base():
+    """The Cline API is ``/api/v1``, NOT ``/v1``. We must not strip the
+    trailing ``/v1`` from the base — it's part of the upstream namespace.
+    """
     with patch.dict(
         "os.environ",
-        {"CLINE_PASS_API_BASE": ""},
+        {"CLINE_PASS_API_BASE": "https://api.cline.bot/api/v1"},
         clear=False,
     ):
-        # Default base is https://api.cline.bot/api/v1; /v1 should be stripped
         assert (
-            _build_billing_url("/users/me/plan")
-            == "https://api.cline.bot/api/users/me/plan"
+            _build_billing_url("/users/me/plan/usage-limits")
+            == "https://api.cline.bot/api/v1/users/me/plan/usage-limits"
         )
 
 
@@ -95,7 +107,20 @@ def test_build_billing_url_no_leading_slash():
     ):
         assert (
             _build_billing_url("users/me/plan/usage-limits")
-            == "https://api.cline.bot/api/users/me/plan/usage-limits"
+            == "https://api.cline.bot/api/v1/users/me/plan/usage-limits"
+        )
+
+
+def test_build_billing_url_trailing_slash_on_base_is_normalised():
+    with patch.dict(
+        "os.environ",
+        {"CLINE_PASS_API_BASE": "https://api.cline.bot/api/v1/"},
+        clear=False,
+    ):
+        # Base is rstripped so we don't get a doubled slash
+        assert (
+            _build_billing_url("/users/me/plan")
+            == "https://api.cline.bot/api/v1/users/me/plan"
         )
 
 
@@ -607,3 +632,49 @@ def test_normalize_model_unknown_returns_input():
     )
     # Empty
     assert provider.normalize_model_for_tracking("") == ""
+
+
+# ---------------------------------------------------------------------------
+# Routing URLs (regression for deployment 2026-07-11)
+# ---------------------------------------------------------------------------
+
+
+def test_provider_api_base_default_uses_documented_upstream():
+    """Without an env override, the provider should default to the
+    documented Cline API base ``https://api.cline.bot/api/v1``.
+
+    Regression: the previous default introduced a separate
+    ``/v1`` (no ``api/``) base for chat routing, which produced
+    404s on every request — ``https://api.cline.bot/v1/chat/completions``
+    is NOT the Cline API path; the path is ``/api/v1/chat/completions``.
+    """
+    from rotator_library.providers.cline_pass_provider import (
+        ClinePassProvider,
+        CLINE_PASS_DEFAULT_API_BASE,
+    )
+
+    assert CLINE_PASS_DEFAULT_API_BASE == "https://api.cline.bot/api/v1"
+    provider = ClinePassProvider()
+    assert provider.api_base == "https://api.cline.bot/api/v1"
+
+
+def test_provider_uses_single_api_base_for_both_models_and_chat():
+    """The provider must use the SAME base for model discovery and
+    chat completions — the Cline API is rooted at ``/api/v1`` and
+    every endpoint (models, chat completions, usage-limits, plan)
+    lives under that prefix.
+    """
+    from rotator_library.providers.cline_pass_provider import ClinePassProvider
+
+    provider = ClinePassProvider()
+    # ``api_base`` drives both ``get_models`` (fetches ``{api_base}/models``)
+    # and ``acompletion`` (sets litellm ``api_base`` so openai/ builds
+    # ``{api_base}/chat/completions``). If we ever split them again, the
+    # deployment 2026-07-11 failure will recur.
+    api_base = provider.api_base
+    assert api_base == "https://api.cline.bot/api/v1"
+    # Sanity check the constructed URLs the proxy actually hits
+    expected_chat_url = f"{api_base}/chat/completions"
+    assert expected_chat_url == "https://api.cline.bot/api/v1/chat/completions"
+    expected_models_url = f"{api_base.rstrip('/')}/models"
+    assert expected_models_url == "https://api.cline.bot/api/v1/models"