Skip to content

Use Claude Code, Codex, VSCode, Pi, and OpenCode (and 6 other harnesses) for free (1.3B+ free tokens) from your terminal, app, IDE, or phone, and now from the browser with native browser sessions (multi-harness + multi-model) like OpenClaw (voice supported + ToS friendly)

Python

patch: add safe local provider availability diagnostics (#2077)

FengCi7facec83d09b
diff --git a/README.md b/README.md
index 974eebc8..1c76eeb7 100644
--- a/README.md
+++ b/README.md
@@ -330,6 +330,8 @@ ollama serve
Use the tag shown by `ollama list` with the `ollama/` prefix. `OLLAMA_BASE_URL` defaults to `http://localhost:11434`.
+Provider cards show the checked endpoint and response time, with a useful message when a local server is unavailable. After starting the server or correcting its settings, click **Test** to refresh its models.
+
</details>
<details>
diff --git a/e2e/test_admin_providers.py b/e2e/test_admin_providers.py
index e8554b14..bd7fc700 100644
--- a/e2e/test_admin_providers.py
+++ b/e2e/test_admin_providers.py
@@ -214,8 +214,14 @@ def test_delayed_startup_status_does_not_replace_a_manual_provider_check(
@pytest.mark.parametrize("availability_first", [False, True])
[email protected]("discovery", ["starting", "ready", "failed"])
[email protected]("available", [False, True])
def test_local_model_discovery_takes_precedence_over_reachability(
- page: Page, admin_base_url: str, availability_first: bool
+ page: Page,
+ admin_base_url: str,
+ availability_first: bool,
+ discovery: str,
+ available: bool,
) -> None:
startup: list[Route] = []
availability: list[Route] = []
@@ -227,18 +233,44 @@ def test_local_model_discovery_takes_precedence_over_reachability(
_open_admin(page, admin_base_url, {"width": 1280, "height": 720})
page.wait_for_function("!!state.startupRequest && !!state.localStatusRequest")
snapshot = page.request.get(f"{admin_base_url}/admin/api/status").json()
- snapshot["startup"]["providers"]["lmstudio"] = "ready"
+ snapshot["startup"]["providers"]["lmstudio"] = discovery
snapshot["cached_models"]["lmstudio"] = ["local-model"]
+ primary = {
+ "starting": "Checking models…",
+ "ready": "1 model available",
+ "failed": "Could not load models. Check the provider's settings and retry.",
+ }[discovery]
+ probe = {
+ "status": "reachable" if available else "offline",
+ "base_url": "http://localhost:1234/v1",
+ "status_code": 200 if available else 503,
+ "probe_path": "/models",
+ "latency_ms": 12.5,
+ }
+ diagnostic = (
+ "Reachable: http://localhost:1234/v1"
+ if available
+ else "Unavailable: http://localhost:1234/v1 returned HTTP 503"
+ ) + " (GET /models, 12.5 ms)"
result = page.locator('[data-provider-check-result="lmstudio"]')
+ detail = page.locator('[data-provider-availability-result="lmstudio"]')
+ dialog = open_provider(page, "lmstudio")
if availability_first:
- availability.pop().continue_()
- expect(result).to_have_text("Reachable: http://localhost:1234/v1")
+ availability.pop().fulfill(json=probe)
+ expect(result).to_have_text(diagnostic)
+ expect(detail).to_be_hidden()
startup.pop(0).fulfill(json=snapshot)
- expect(result).to_have_text("1 model available")
+ expect(result).to_have_text(primary)
if not availability_first:
- availability.pop().continue_()
+ availability.pop().fulfill(json=probe)
page.wait_for_function("!state.localStatusRequest")
- expect(result).to_have_text("1 model available")
+ expect(result).to_have_text(primary)
+ expect(detail).to_have_text(diagnostic)
+ expect(detail).to_have_class(
+ "provider-availability-result " + ("ok" if available else "error")
+ )
+ expect(dialog.locator("#providerDialogCheck")).to_have_text(primary)
+ expect(dialog.locator("#providerDialogAvailability")).to_have_text(diagnostic)
def test_provider_check_failure_is_separate_and_never_exposes_exception_text(
@@ -379,6 +411,74 @@ def test_local_availability_failure_does_not_fail_admin_loading(
assert errors == []
+ "viewport",
+ ({"width": 1280, "height": 720}, {"width": 390, "height": 844}),
+)
+def test_local_provider_diagnostics_are_visible_on_cards_and_in_the_dialog(
+ page: Page, admin_base_url: str, viewport: ViewportSize
+) -> None:
+ errors: list[str] = []
+ page.on("pageerror", lambda error: errors.append(str(error)))
+ timeout_message = (
+ "The local provider availability check timed out. "
+ "Check that its server is responsive and retry."
+ )
+ results = {
+ "lmstudio": {
+ "provider_id": "lmstudio",
+ "status": "reachable",
+ "base_url": "http://localhost:1234/v1",
+ "probe_path": "/models",
+ "latency_ms": 12.5,
+ "error_type": None,
+ },
+ "llamacpp": {
+ "provider_id": "llamacpp",
+ "status": "offline",
+ "base_url": "http://localhost:8080/v1",
+ "status_code": 503,
+ "probe_path": "/models",
+ "latency_ms": 8,
+ "error_type": "http_error",
+ },
+ "ollama": {
+ "provider_id": "ollama",
+ "status": "offline",
+ "base_url": "http://localhost:11434",
+ "message": timeout_message,
+ "probe_path": "/api/tags",
+ "latency_ms": 1500,
+ "error_type": "timeout",
+ "private_diagnostic": "private-credential-marker",
+ },
+ }
+
+ def reply(route: Route) -> None:
+ provider_id = route.request.url.split("/")[-2]
+ route.fulfill(json=results[provider_id])
+
+ page.route("**/admin/api/providers/*/local-status", reply)
+ _open_admin(page, admin_base_url, viewport)
+
+ expect(page.locator('[data-provider-check-result="lmstudio"]')).to_have_text(
+ "Reachable: http://localhost:1234/v1 (GET /models, 12.5 ms)"
+ )
+ expect(page.locator('[data-provider-check-result="llamacpp"]')).to_have_text(
+ "Unavailable: http://localhost:8080/v1 returned HTTP 503 (GET /models, 8 ms)"
+ )
+ expected_timeout = f"Unavailable: {timeout_message} (GET /api/tags, 1500 ms)"
+ expect(page.locator('[data-provider-check-result="ollama"]')).to_have_text(
+ expected_timeout
+ )
+ dialog = open_provider(page, "ollama")
+ expect(dialog.locator("#providerDialogCheck")).to_have_text(expected_timeout)
+ expect(dialog.locator("#providerDialogCheck")).to_be_in_viewport()
+ expect(dialog.get_by_role("button", name="Test", exact=True)).to_be_enabled()
+ assert "private-credential-marker" not in page.locator("body").inner_text()
+ assert errors == []
+
+
@pytest.mark.parametrize("manual_finished", [False, True])
def test_manual_provider_test_takes_precedence_over_automatic_availability(
page: Page, admin_base_url: str, manual_finished: bool
diff --git a/e2e/test_local_provider_diagnostics.py b/e2e/test_local_provider_diagnostics.py
new file mode 100644
index 00000000..9ba77015
--- /dev/null
+++ b/e2e/test_local_provider_diagnostics.py
@@ -0,0 +1,121 @@
+"""Endpoint diagnostics remain visible beside selected-provider discovery."""
+
+import httpx
+import pytest
+from playwright.sync_api import Page, Route, expect
+
+from e2e.provider_support import close_provider, open_provider
+from free_claude_code.providers.runtime import ProviderRuntime
+
+
+def admin_client_files(monkeypatch):
+ # The fixture invokes this hook before startup. Only the external provider
+ # boundary fails; the manager, status API, and browser remain real.
+ resolve = ProviderRuntime.resolve_provider
+
+ async def timeout_local(runtime, provider_id, api_key_number=1):
+ if provider_id in {"lmstudio", "llamacpp", "ollama"}:
+ raise httpx.ReadTimeout("private-provider-error")
+ return await resolve(runtime, provider_id, api_key_number)
+
+ monkeypatch.setattr(ProviderRuntime, "resolve_provider", timeout_local)
+
+
+def timeout_probe(provider_id):
+ return {
+ "provider_id": provider_id,
+ "status": "offline",
+ "message": "The local provider availability check timed out. Check that its server is responsive and retry.",
+ "probe_path": "/api/tags" if provider_id == "ollama" else "/models",
+ "latency_ms": 1500,
+ "error_type": "timeout",
+ }
+
+
+ ("admin_base_url", "provider_id"),
+ [
+ ({"MODEL": f"{provider}/local-model"}, provider)
+ for provider in ("lmstudio", "llamacpp", "ollama")
+ ],
+ indirect=["admin_base_url"],
+)
+def test_selected_local_provider_keeps_endpoint_diagnostics_and_manual_ownership(
+ page: Page, admin_base_url: str, provider_id: str
+):
+ page.route(
+ f"**/admin/api/providers/{provider_id}/local-status",
+ lambda route: route.fulfill(json=timeout_probe(provider_id)),
+ )
+ page.goto(f"{admin_base_url}/admin")
+ primary = page.locator(f'[data-provider-check-result="{provider_id}"]')
+ detail = page.locator(f'[data-provider-availability-result="{provider_id}"]')
+ expect(primary).to_contain_text("timed out")
+ expect(detail).to_contain_text("1500 ms")
+ expect(detail).to_contain_text(
+ "GET /api/tags" if provider_id == "ollama" else "GET /models"
+ )
+ dialog = open_provider(page, provider_id)
+ expect(dialog.locator("#providerDialogAvailability")).to_have_text(
+ detail.inner_text()
+ )
+ expect(dialog.locator("#providerDialogAvailability")).to_be_in_viewport()
+ assert "private-provider-error" not in page.locator("body").inner_text()
+
+ manual: list[Route] = []
+ page.route(
+ f"**/admin/api/providers/{provider_id}/test", lambda route: manual.append(route)
+ )
+ with page.expect_request(f"**/admin/api/providers/{provider_id}/test"):
+ dialog.get_by_role("button", name="Test", exact=True).click()
+ expect(primary).to_have_text("Checking...")
+ expect(detail).to_be_hidden()
+ expect(dialog.locator("#providerDialogAvailability")).to_be_hidden()
+ manual.pop().fulfill(json={"ok": True, "models": ["local-model"]})
+ expect(primary).to_have_text("1 model available")
+ page.wait_for_function("!state.startupRequest")
+ expect(detail).to_be_hidden()
+
+
+ "admin_base_url", [{"MODEL": "lmstudio/local-model"}], indirect=True
+)
+def test_availability_detail_clears_on_dialog_switch_and_configuration_reload(
+ page: Page, admin_base_url: str
+):
+ page.route(
+ "**/admin/api/providers/lmstudio/local-status",
+ lambda route: route.fulfill(json=timeout_probe("lmstudio")),
+ )
+ page.goto(f"{admin_base_url}/admin")
+ detail = page.locator('[data-provider-availability-result="lmstudio"]')
+ expect(detail).to_contain_text("1500 ms")
+ dialog = open_provider(page, "lmstudio")
+ expect(dialog.locator("#providerDialogAvailability")).to_be_visible()
+ close_provider(page)
+ dialog = open_provider(page, "open_router")
+ expect(dialog.locator("#providerDialogAvailability")).to_be_hidden()
+ close_provider(page)
+ open_provider(page, "lmstudio")
+ expect(dialog.locator("#providerDialogAvailability")).to_be_visible()
+ close_provider(page)
+ page.locator("#addCustomProvider").click()
+ expect(dialog.locator("#providerDialogAvailability")).to_be_hidden()
+ close_provider(page)
+
+ pending: list[Route] = []
+ page.route(
+ "**/admin/api/providers/lmstudio/local-status",
+ lambda route: pending.append(route),
+ )
+ with page.expect_request("**/admin/api/providers/lmstudio/local-status"):
+ page.evaluate("load({providersOnly: true})")
+ expect(detail).to_be_hidden()
+ dialog = open_provider(page, "lmstudio")
+ expect(dialog.locator("#providerDialogAvailability")).to_be_hidden()
+ pending.pop().fulfill(json={**timeout_probe("lmstudio"), "latency_ms": 2500})
+ expect(detail).to_contain_text("2500 ms")
+ expect(dialog.locator("#providerDialogAvailability")).to_have_text(
+ detail.inner_text()
+ )
diff --git a/src/free_claude_code/api/admin_routes.py b/src/free_claude_code/api/admin_routes.py
index fdb284ed..fa2abc40 100644
--- a/src/free_claude_code/api/admin_routes.py
+++ b/src/free_claude_code/api/admin_routes.py
@@ -2,6 +2,7 @@
from collections.abc import Awaitable, Callable, Mapping
from pathlib import Path
+from time import perf_counter
import httpx
from fastapi import (
@@ -550,9 +551,13 @@ async def _check_local_provider(
"status": "missing_url",
"label": "Missing URL",
"base_url": base_url,
+ "probe_path": path,
+ "latency_ms": None,
+ "error_type": None,
}
url = f"{clean_url}{path}"
+ started = perf_counter()
try:
async with httpx.AsyncClient(timeout=1.5) as client:
response = await client.get(url)
@@ -563,6 +568,9 @@ async def _check_local_provider(
"label": "Reachable" if ok else "Offline",
"base_url": base_url,
"status_code": response.status_code,
+ "probe_path": path,
+ "latency_ms": round((perf_counter() - started) * 1000, 2),
+ "error_type": None if ok else "http_error",
}
except Exception as exc:
logger.debug(
@@ -570,15 +578,40 @@ async def _check_local_provider(
provider_id,
type(exc).__name__,
)
+ error_type, message = _local_provider_failure(exc)
return {
"provider_id": provider_id,
"status": "offline",
"label": "Offline",
"base_url": base_url,
- "message": _LOCAL_PROVIDER_CHECK_FAILURE_MESSAGE,
+ "message": message,
+ "probe_path": path,
+ "latency_ms": round((perf_counter() - started) * 1000, 2),
+ "error_type": error_type,
}
+def _local_provider_failure(exc: Exception) -> tuple[str, str]:
+ if isinstance(exc, httpx.TimeoutException):
+ return (
+ "timeout",
+ "The local provider availability check timed out. Check that its server is responsive and retry.",
+ )
+ if isinstance(exc, (httpx.ConnectError, httpx.ProxyError)):
+ return "connection_error", _LOCAL_PROVIDER_CHECK_FAILURE_MESSAGE
+ if isinstance(exc, (httpx.InvalidURL, httpx.UnsupportedProtocol)):
+ return (
+ "invalid_url",
+ "Check the local provider's HTTP or HTTPS base URL and port.",
+ )
+ if isinstance(exc, httpx.RequestError):
+ return (
+ "transport_error",
+ "The connection ended before the availability check completed. Retry and check the local server logs.",
+ )
+ return "unexpected_error", _LOCAL_PROVIDER_CHECK_FAILURE_MESSAGE
+
+
def _require_connected_account_provider(provider_id: str) -> None:
descriptor = PROVIDER_CATALOG.get(provider_id)
if (
diff --git a/src/free_claude_code/api/admin_static/admin.css b/src/free_claude_code/api/admin_static/admin.css
index 08e7a1d4..f65e6f3d 100644
--- a/src/free_claude_code/api/admin_static/admin.css
+++ b/src/free_claude_code/api/admin_static/admin.css
@@ -361,7 +361,8 @@ button.startup-busy::before,
.provider-dialog .field-grid { grid-template-columns: minmax(0, 1fr); }
.provider-dialog .field.advanced-field { display: flex; }
.provider-dialog .provider-actions:not(:empty),
-.provider-dialog .provider-check-result:not([hidden]) { margin-bottom: 20px; }
+.provider-dialog .provider-check-result:not([hidden]),
+.provider-dialog .provider-availability-result:not([hidden]) { margin-bottom: 20px; }
.provider-dialog .message-area:empty { display: none; }
.provider-dialog-footer { display: flex; justify-content: flex-end; gap: 12px; margin-top: 24px; }
@@ -411,24 +412,28 @@ button.startup-busy::before,
overflow-wrap: anywhere;
}
-.provider-check-result {
+.provider-check-result,
+.provider-availability-result {
color: var(--muted);
font-size: 12px;
line-height: 1.4;
overflow-wrap: anywhere;
}
-.provider-check-result.ok {
+.provider-check-result.ok,
+.provider-availability-result.ok {
color: var(--ok);
}
-.provider-check-result.error {
+.provider-check-result.error,
+.provider-availability-result.error {
color: var(--error);
}
.provider-meta.error { color: var(--error); }
-.provider-check-result.checking {
+.provider-check-result.checking,
+.provider-availability-result.checking {
color: var(--info);
}
diff --git a/src/free_claude_code/api/admin_static/admin.js b/src/free_claude_code/api/admin_static/admin.js
index 72c670b1..620bc523 100644
--- a/src/free_claude_code/api/admin_static/admin.js
+++ b/src/free_claude_code/api/admin_static/admin.js
@@ -407,6 +407,10 @@ function updateProviderCard(provider) {
result.className = "provider-check-result";
result.dataset.providerCheckResult = provider.provider_id;
result.hidden = true;
+ const availability = document.createElement("span");
+ availability.className = "provider-availability-result";
+ availability.dataset.providerAvailabilityResult = provider.provider_id;
+ availability.hidden = true;
const actions = document.createElement("div");
actions.className = "provider-actions";
if (oauth) populateConnectedAccountActions(provider, status, actions);
@@ -418,7 +422,7 @@ function updateProviderCard(provider) {
settings.setAttribute("aria-controls", "providerDialog");
actions.appendChild(settings);
}
- card.replaceChildren(title, meta, result, actions);
+ card.replaceChildren(title, meta, result, availability, actions);
const next = [...grid.children].find((other) => other !== card &&
connectedAccountName(provider).localeCompare(providerDisplayName(other.dataset.provider), "en", { sensitivity: "base" }) < 0);
if (card.parentElement !== grid || card.nextElementSibling !== (next || null)) grid.insertBefore(card, next || null);
@@ -489,6 +493,7 @@ async function openCustomProviderDialog(providerId = null) {
byId("providerDialogTitle").textContent = providerId ? provider.display_name : "Add provider";
byId("providerMessage").textContent = "";
byId("providerDialogCheck").hidden = true;
+ renderProviderCheckMessage(byId("providerDialogAvailability"), null);
const fields = byId("providerFields");
fields.replaceChildren();
const formats = (state.config.custom_reasoning_formats || {})[provider.api_format] || ["provider_default"];
@@ -553,10 +558,8 @@ function renderProviderDialogActions(provider) {
actions.appendChild(button);
}
const check = oauth ? null : providerCheckResult(provider.provider_id);
- const result = byId("providerDialogCheck");
- result.className = `provider-check-result ${check?.status || ""}`;
- result.textContent = check?.message || "";
- result.hidden = !check?.message;
+ renderProviderCheckMessage(byId("providerDialogCheck"), check);
+ renderProviderCheckMessage(byId("providerDialogAvailability"), check?.availability);
byId("saveProvider").hidden = !provider.settings_keys?.length;
renderStartup();
}
@@ -779,14 +782,16 @@ function providerCheckResult(providerId) {
// An explicit check takes precedence over background discovery and reachability.
if (check?.source === "manual") return check;
const discovery = state.startup?.startup?.providers?.[providerId];
- if (discovery === "starting") return { status: "checking", message: "Checking models…" };
- if (discovery === "failed") {
- return { status: "error", message: state.startup.startup.provider_errors?.[providerId] || "Could not load models. Check the provider's settings and retry." };
+ let result;
+ if (discovery === "starting") {
+ result = { status: "checking", message: "Checking models…" };
+ } else if (discovery === "failed") {
+ result = { status: "error", message: state.startup.startup.provider_errors?.[providerId] || "Could not load models. Check the provider's settings and retry." };
+ } else if (discovery === "ready") {
+ result = { status: "ok", message: modelCountMessage(state.startup.cached_models[providerId]?.length || 0) };
}
- if (discovery === "ready") {
- return { status: "ok", message: modelCountMessage(state.startup.cached_models[providerId]?.length || 0) };
- }
- return check;
+ // Model discovery and endpoint reachability are separate observations.
+ return result ? { ...result, availability: check } : check;
}
function updateProviderCheckResult(providerId, status, message, source = "manual") {
@@ -794,8 +799,17 @@ function updateProviderCheckResult(providerId, status, message, source = "manual
renderProviderCheckResult(providerId);
}
+function renderProviderCheckMessage(element, check) {
+ for (const status of ["ok", "error", "checking"]) {
+ element.classList.toggle(status, check?.status === status);
+ }
+ element.textContent = check?.message || "";
+ element.hidden = !check?.message;
+}
+
function renderProviderCheckResult(providerId) {
- const { status = "", message = "" } = providerCheckResult(providerId) || {};
+ const check = providerCheckResult(providerId);
+ const { status = "" } = check || {};
const card = document.querySelector(`[data-provider="${providerId}"]`);
if (!card) return;
const provider = connectedAccountDescriptor(providerId);
@@ -810,15 +824,11 @@ function renderProviderCheckResult(providerId) {
if (account?.state === "error") meta.classList.add("error");
return;
}
- const result = card.querySelector(".provider-check-result");
- result.className = `provider-check-result ${status}`;
- result.textContent = message;
- result.hidden = !message;
+ renderProviderCheckMessage(card.querySelector(".provider-check-result"), check);
+ renderProviderCheckMessage(card.querySelector(".provider-availability-result"), check?.availability);
if (state.providerId === providerId) {
- const modalResult = byId("providerDialogCheck");
- modalResult.className = result.className;
- modalResult.textContent = message;
- modalResult.hidden = !message;
+ renderProviderCheckMessage(byId("providerDialogCheck"), check);
+ renderProviderCheckMessage(byId("providerDialogAvailability"), check?.availability);
}
}
@@ -1653,8 +1663,14 @@ async function refreshLocalStatus(config) {
const provider = await api(`/admin/api/providers/${providerId}/local-status`);
if (state.localStatusRequest !== request || !request.providerIds.has(providerId)) return;
if (provider.status === "missing_url") return;
+ const diagnostics = [];
+ if (provider.probe_path) diagnostics.push(`GET ${provider.probe_path}`);
+ if (typeof provider.latency_ms === "number" && Number.isFinite(provider.latency_ms)) {
+ diagnostics.push(`${provider.latency_ms} ms`);
+ }
+ const suffix = diagnostics.length ? ` (${diagnostics.join(", ")})` : "";
if (provider.status === "reachable") {
- updateProviderCheckResult(providerId, "ok", `Reachable: ${provider.base_url}`, "availability");
+ updateProviderCheckResult(providerId, "ok", `Reachable: ${provider.base_url}${suffix}`, "availability");
return;
}
const detail = provider.message
@@ -1662,7 +1678,7 @@ async function refreshLocalStatus(config) {
: provider.status_code
? `${provider.base_url} returned HTTP ${provider.status_code}`
: "The local provider did not respond.";
- updateProviderCheckResult(providerId, "error", `Unavailable: ${detail}`, "availability");
+ updateProviderCheckResult(providerId, "error", `Unavailable: ${detail}${suffix}`, "availability");
} catch {
if (state.localStatusRequest !== request || !request.providerIds.has(providerId)) return;
updateProviderCheckResult(providerId, "error", "Availability check failed. Use Test to retry.", "availability");
diff --git a/src/free_claude_code/api/admin_static/index.html b/src/free_claude_code/api/admin_static/index.html
index c8a3fe23..ee1d94ce 100644
--- a/src/free_claude_code/api/admin_static/index.html
+++ b/src/free_claude_code/api/admin_static/index.html
@@ -259,6 +259,7 @@
<div id="providerDialogBody">
<div id="providerDialogActions" class="provider-actions"></div>
<div id="providerDialogCheck" class="provider-check-result" role="status" hidden></div>
+ <div id="providerDialogAvailability" class="provider-availability-result" role="status" hidden></div>
<div id="providerFields" class="field-grid"></div>
</div>
<div id="providerMessage" class="message-area" role="status"></div>
diff --git a/tests/api/test_admin.py b/tests/api/test_admin.py
index f9478335..13468bdf 100644
--- a/tests/api/test_admin.py
+++ b/tests/api/test_admin.py
@@ -2379,7 +2379,9 @@ def test_admin_local_provider_failure_does_not_return_exception_text(
)
assert "CREDENTIAL[unrecognized-format-987654321]" not in provider["message"]
assert "RuntimeError" not in provider["message"]
- assert "error_type" not in provider
+ assert provider["error_type"] == "unexpected_error"
+ assert "CREDENTIAL[unrecognized-format-987654321]" not in response.text
+ assert "RuntimeError" not in response.text
@pytest.mark.parametrize(
diff --git a/tests/api/test_local_provider_diagnostics.py b/tests/api/test_local_provider_diagnostics.py
new file mode 100644
index 00000000..7220f7b9
--- /dev/null
+++ b/tests/api/test_local_provider_diagnostics.py
@@ -0,0 +1,164 @@
+from unittest.mock import AsyncMock, patch
+
+import httpx
+import pytest
+from fastapi.testclient import TestClient
+
+from free_claude_code.api import admin_routes
+from free_claude_code.config.admin.state import ConfigValueState
+from tests.api.support import create_test_app, runtime_for_app
+
+
+def local_probe(monkeypatch):
+ requests: list[httpx.Request] = []
+ async_client = httpx.AsyncClient
+ clock = iter((10.0, 10.0125))
+ monkeypatch.setattr(admin_routes, "perf_counter", lambda: next(clock))
+
+ def probe(handler, provider_id="lmstudio"):
+ def reply(request):
+ requests.append(request)
+ return handler(request)
+
+ def client(*args, **kwargs):
+ return async_client(*args, transport=httpx.MockTransport(reply), **kwargs)
+
+ monkeypatch.setattr(admin_routes.httpx, "AsyncClient", client)
+ app = create_test_app()
+ response = TestClient(
+ app, base_url="http://127.0.0.1", client=("127.0.0.1", 50000)
+ ).get(f"/admin/api/providers/{provider_id}/local-status")
+ assert response.status_code == 200
+ assert response.headers["cache-control"] == "no-store"
+ return response, requests
+
+ return probe
+
+
+ ("provider_id", "env_key", "provider_url", "probe_path"),
+ (
+ ("lmstudio", "LM_STUDIO_BASE_URL", "http://127.0.0.1:1234/v1", "/models"),
+ ("llamacpp", "LLAMACPP_BASE_URL", "http://127.0.0.1:8080/v1", "/models"),
+ ("ollama", "OLLAMA_BASE_URL", "http://127.0.0.1:11434", "/api/tags"),
+ ),
+)
+def test_local_probe_reports_the_requested_endpoint_and_elapsed_time(
+ monkeypatch, local_probe, provider_id, env_key, provider_url, probe_path
+):
+ monkeypatch.setenv(env_key, provider_url)
+ response, requests = local_probe(lambda _: httpx.Response(200), provider_id)
+
+ assert [(request.method, str(request.url)) for request in requests] == [
+ ("GET", f"{provider_url}{probe_path}")
+ ]
+ assert response.json() == {
+ "provider_id": provider_id,
+ "status": "reachable",
+ "label": "Reachable",
+ "base_url": provider_url,
+ "status_code": 200,
+ "probe_path": probe_path,
+ "latency_ms": pytest.approx(12.5),
+ "error_type": None,
+ }
+
+
[email protected]("status_code", (200, 204, 302, 401, 404, 429, 503))
+def test_local_probe_preserves_http_status_without_returning_response_content(
+ local_probe, status_code
+):
+ private = "private-response-credential-marker"
+ response, requests = local_probe(
+ lambda _: httpx.Response(
+ status_code,
+ text=private,
+ headers={"x-private-token": private},
+ )
+ )
+
+ assert len(requests) == 1
+ payload = response.json()
+ reachable = 200 <= status_code < 300
+ assert payload["status"] == ("reachable" if reachable else "offline")
+ assert payload["label"] == ("Reachable" if reachable else "Offline")
+ assert payload["status_code"] == status_code
+ assert payload["error_type"] == (None if reachable else "http_error")
+ assert payload["probe_path"] == "/models"
+ assert payload["latency_ms"] == pytest.approx(12.5)
+ assert private not in response.text
+
+
+ ("failure", "error_type"),
+ (
+ (httpx.ReadTimeout, "timeout"),
+ (httpx.ConnectError, "connection_error"),
+ (httpx.ProxyError, "connection_error"),
+ (httpx.InvalidURL, "invalid_url"),
+ (httpx.UnsupportedProtocol, "invalid_url"),
+ (httpx.ReadError, "transport_error"),
+ (RuntimeError, "unexpected_error"),
+ ),
+)
+def test_local_probe_returns_safe_failure_categories(local_probe, failure, error_type):
+ private = "CREDENTIAL[unrecognized-format-987654321]"
+
+ def fail(_request):
+ raise failure(f"Request failed with {private}")
+
+ response, requests = local_probe(fail)
+
+ assert len(requests) == 1
+ payload = response.json()
+ assert payload["status"] == "offline"
+ assert payload["label"] == "Offline"
+ assert payload["error_type"] == error_type
+ assert payload["probe_path"] == "/models"
+ assert payload["latency_ms"] == pytest.approx(12.5)
+ assert payload["message"]
+ assert private not in response.text
+ assert failure.__name__ not in response.text
+
+
[email protected]("provider_url", ("", " \t "))
+def test_missing_local_url_has_no_network_probe_or_elapsed_time(provider_url):
+ app = create_test_app()
+ runtime = runtime_for_app(app)
+ values = {
+ "LM_STUDIO_BASE_URL": ConfigValueState(value=provider_url, source="default")
+ }
+ with (
+ patch.object(runtime, "admin_values", AsyncMock(return_value=values)),
+ patch.object(admin_routes.httpx, "AsyncClient") as client,
+ patch.object(admin_routes, "perf_counter") as clock,
+ ):
+ response = TestClient(
+ app, base_url="http://127.0.0.1", client=("127.0.0.1", 50000)
+ ).get("/admin/api/providers/lmstudio/local-status")
+
+ assert response.status_code == 200
+ assert response.json() == {
+ "provider_id": "lmstudio",
+ "status": "missing_url",
+ "label": "Missing URL",
+ "base_url": provider_url,
+ "probe_path": "/models",
+ "latency_ms": None,
+ "error_type": None,
+ }
+ client.assert_not_called()
+ clock.assert_not_called()
+
+
+def test_remote_admin_cannot_trigger_a_local_provider_probe():
+ with patch.object(admin_routes.httpx, "AsyncClient") as client:
+ response = TestClient(
+ create_test_app(),
+ base_url="http://127.0.0.1",
+ client=("203.0.113.10", 50000),
+ ).get("/admin/api/providers/lmstudio/local-status")
+
+ assert response.status_code == 403
+ client.assert_not_called()