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: Discover local models automatically (#2104)

Ali Khokhar261b12f96499
diff --git a/README.md b/README.md
index 0c60e56b..7ae21467 100644
--- a/README.md
+++ b/README.md
@@ -313,6 +313,8 @@ For another API endpoint, open **Providers → Custom providers → Add provider
<details>
<summary><strong>Local provider setup</strong></summary>
+FCC automatically discovers models from running local servers at startup. If you start a server later, click **Refresh models** in Admin to add its models to the picker.
+
### LM Studio
Start LM Studio's local server, load a tool-capable model, and use the model identifier shown by LM Studio with the `lmstudio/` prefix. The default URL is `http://localhost:1234/v1`.
@@ -505,15 +507,6 @@ Uninstalling FCC leaves Muse Code installed.
### Uninstall
Stop every running FCC command and quit connected desktop/editor apps before uninstalling.
-The uninstaller disconnects recognized FCC integrations before removing the tool,
-preserving unrelated application settings. If cleanup fails, FCC and `~/.fcc/`
-remain available so you can correct the problem and retry.
-You can also run `fcc-doctor --disconnect-integrations` separately.
-If a VS Code gateway's address or token no longer matches FCC's current settings,
-cleanup stops without changing that connection; disconnect it manually before retrying.
-For older FCC versions without this command, update first or disconnect through
-Admin, then use `--keep-integrations` (PowerShell: `-KeepIntegrations`) to skip
-automatic cleanup. This option intentionally leaves application settings unchanged.
**Removes**
diff --git a/e2e/conftest.py b/e2e/conftest.py
index 0ba57745..d3afd859 100644
--- a/e2e/conftest.py
+++ b/e2e/conftest.py
@@ -257,6 +257,12 @@ def admin_base_url(
provider_secret = "CREDENTIAL[unrecognized-format-987654321]"
providers: dict[str, BaseProvider] = {
+ **{
+ name: _ModelListingProvider(
+ error=ConnectionError("Local fixture is offline")
+ )
+ for name in ("lmstudio", "llamacpp", "ollama")
+ },
"nvidia_nim": _ModelListingProvider(),
"open_router": _ModelListingProvider(
frozenset(
diff --git a/e2e/test_admin_providers.py b/e2e/test_admin_providers.py
index bd7fc700..8c53006c 100644
--- a/e2e/test_admin_providers.py
+++ b/e2e/test_admin_providers.py
@@ -351,13 +351,13 @@ def test_admin_loading_finishes_before_local_availability_checks(
elif payload["provider_id"] == "ollama":
payload.update(status="missing_url", label="Missing URL", base_url="")
route.fulfill(json=payload)
- expect(page.locator('[data-provider-check-result="lmstudio"]')).to_have_text(
+ expect(page.locator('[data-provider-availability-result="lmstudio"]')).to_have_text(
"Reachable: http://localhost:1234/v1"
)
- expect(page.locator('[data-provider-check-result="llamacpp"]')).to_have_text(
+ expect(page.locator('[data-provider-availability-result="llamacpp"]')).to_have_text(
"Unavailable: http://localhost:8080/v1 returned HTTP 503"
)
- expect(page.locator('[data-provider-check-result="ollama"]')).to_be_hidden()
+ expect(page.locator('[data-provider-availability-result="ollama"]')).to_be_hidden()
expect(
page.locator('[data-provider="lmstudio"]').get_by_role(
"button", name="Edit", exact=True
@@ -392,11 +392,13 @@ def test_local_availability_failure_does_not_fail_admin_loading(
for provider_id in ("lmstudio", "llamacpp", "ollama"):
card = page.locator(f'[data-provider="{provider_id}"]')
if provider_id == "lmstudio":
- expect(card.locator(".provider-check-result")).to_have_text(
+ expect(card.locator(".provider-availability-result")).to_have_text(
"Availability check failed. Use Test to retry."
)
else:
- expect(card.locator(".provider-check-result")).to_contain_text("Reachable:")
+ expect(card.locator(".provider-availability-result")).to_contain_text(
+ "Reachable:"
+ )
expect(card.get_by_role("button", name="Edit", exact=True)).to_have_class(
"secondary-button"
)
@@ -461,19 +463,19 @@ def test_local_provider_diagnostics_are_visible_on_cards_and_in_the_dialog(
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(
+ expect(page.locator('[data-provider-availability-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(
+ expect(page.locator('[data-provider-availability-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(
+ expect(page.locator('[data-provider-availability-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.locator("#providerDialogAvailability")).to_have_text(expected_timeout)
+ expect(dialog.locator("#providerDialogAvailability")).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 == []
@@ -520,7 +522,7 @@ def test_manual_provider_test_takes_precedence_over_automatic_availability(
availability.pop().continue_()
response.value.finished()
page.evaluate("() => new Promise(requestAnimationFrame)")
- other = page.locator('[data-provider-check-result="ollama"]')
+ other = page.locator('[data-provider-availability-result="ollama"]')
if manual_finished:
expect(result).to_have_text(
"Unavailable: Could not refresh this provider's models."
diff --git a/e2e/test_admin_status_independence.py b/e2e/test_admin_status_independence.py
index 2c1549a0..b966ce18 100644
--- a/e2e/test_admin_status_independence.py
+++ b/e2e/test_admin_status_independence.py
@@ -81,14 +81,14 @@ def test_local_cards_render_before_slowest_check(page, admin_base_url):
page.wait_for_function("window.heldLocalCheck === true")
lmstudio_response.value.finished()
llamacpp_response.value.finished()
- expect(page.locator('[data-provider-check-result="lmstudio"]')).to_have_text(
+ expect(page.locator('[data-provider-availability-result="lmstudio"]')).to_have_text(
"Reachable: http://localhost:1234/v1"
)
- expect(page.locator('[data-provider-check-result="llamacpp"]')).to_have_text(
+ expect(page.locator('[data-provider-availability-result="llamacpp"]')).to_have_text(
"Availability check failed. Use Test to retry."
)
assert len(pending) == 1
- expect(page.locator('[data-provider-check-result="ollama"]')).to_be_hidden()
+ expect(page.locator('[data-provider-availability-result="ollama"]')).to_be_hidden()
pending.pop().fulfill(
json={
"provider_id": "ollama",
@@ -96,7 +96,7 @@ def test_local_cards_render_before_slowest_check(page, admin_base_url):
"base_url": "http://localhost:11434",
}
)
- expect(page.locator('[data-provider-check-result="ollama"]')).to_have_text(
+ expect(page.locator('[data-provider-availability-result="ollama"]')).to_have_text(
"Reachable: http://localhost:11434"
)
diff --git a/e2e/test_local_provider_diagnostics.py b/e2e/test_local_provider_diagnostics.py
index 9ba77015..be37828f 100644
--- a/e2e/test_local_provider_diagnostics.py
+++ b/e2e/test_local_provider_diagnostics.py
@@ -1,5 +1,7 @@
"""Endpoint diagnostics remain visible beside selected-provider discovery."""
+import re
+
import httpx
import pytest
from playwright.sync_api import Page, Route, expect
@@ -33,6 +35,35 @@ def timeout_probe(provider_id):
}
[email protected]("provider_id", ["lmstudio", "llamacpp", "ollama"])
+def test_optional_local_absence_is_neutral_and_manual_test_reports_error(
+ 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_have_text("Local server unavailable")
+ expect(primary).not_to_have_class(re.compile(r"\berror\b"))
+ expect(detail).to_contain_text("1500 ms")
+ expect(detail).not_to_have_class(re.compile(r"\berror\b"))
+ dialog = open_provider(page, provider_id)
+ expect(dialog.locator("#providerDialogAvailability")).to_have_text(
+ detail.inner_text()
+ )
+ dialog.get_by_role("button", name="Test", exact=True).click()
+ expect(primary).to_contain_text("timed out")
+ expect(primary).to_have_class(re.compile(r"\berror\b"))
+ expect(detail).to_be_hidden()
+ assert "private-provider-error" not in page.locator("body").inner_text()
+ close_provider(page)
+ page.evaluate("load({providersOnly: true})")
+ expect(primary).to_have_text("Local server unavailable")
+
+
@pytest.mark.parametrize(
("admin_base_url", "provider_id"),
[
diff --git a/src/free_claude_code/api/admin_static/admin.js b/src/free_claude_code/api/admin_static/admin.js
index 620bc523..1b95a22c 100644
--- a/src/free_claude_code/api/admin_static/admin.js
+++ b/src/free_claude_code/api/admin_static/admin.js
@@ -789,6 +789,12 @@ function providerCheckResult(providerId) {
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) };
+ } else if (discovery === "unavailable") {
+ return {
+ status: "",
+ message: "Local server unavailable",
+ availability: check ? { ...check, status: "" } : undefined,
+ };
}
// Model discovery and endpoint reachability are separate observations.
return result ? { ...result, availability: check } : check;
diff --git a/src/free_claude_code/providers/admission.py b/src/free_claude_code/providers/admission.py
index 00b7e2e4..bc43bda3 100644
--- a/src/free_claude_code/providers/admission.py
+++ b/src/free_claude_code/providers/admission.py
@@ -5,7 +5,9 @@ import math
import random
import time
import uuid
-from collections.abc import Awaitable, Callable
+from collections.abc import Awaitable, Callable, Generator
+from contextlib import contextmanager
+from contextvars import ContextVar
from dataclasses import dataclass, field
from datetime import UTC, datetime
from email.utils import parsedate_to_datetime
@@ -36,6 +38,23 @@ DEFAULT_UPSTREAM_BASE_DELAY = 2.0
DEFAULT_UPSTREAM_MAX_DELAY = 60.0
DEFAULT_UPSTREAM_JITTER = 1.0
+_quiet_discovery = ContextVar("quiet_discovery_recovery_logs", default=False)
+
+
+@contextmanager
+def quiet_discovery_recovery_logs(enabled: bool) -> Generator[None]:
+ """Keep optional probe retries at debug level without silencing other tasks."""
+ token = _quiet_discovery.set(enabled)
+ try:
+ yield
+ finally:
+ _quiet_discovery.reset(token)
+
+
+def _log_recovery(message: str, *args: object) -> None:
+ log = logger.debug if _quiet_discovery.get() else logger.warning
+ log(message, *args)
+
class ProviderOperationKind(StrEnum):
"""Safe trace category for one physical provider call."""
@@ -179,8 +198,16 @@ class ProviderExecution:
return result
finally:
await attempt.aclose()
- except asyncio.CancelledError:
+ except asyncio.CancelledError as cancelled:
self.abandon()
+ # A discovery deadline can interrupt retry backoff. Retain the
+ # provider failure so diagnostics can distinguish absence from DNS,
+ # TLS or HTTP failures while cancellation still propagates.
+ if (
+ operation_kind is ProviderOperationKind.MODEL_DISCOVERY
+ and self._last_failure is not None
+ ):
+ raise cancelled from self._last_failure
raise
except Exception as error:
self.fail(error)
@@ -577,7 +604,7 @@ class ProviderAdmissionController:
continue
try:
if sleep_delay > 0:
- logger.warning(
+ _log_recovery(
"Provider {} recovery active, waiting {:.1f}s for one probe",
self._provider_name,
sleep_delay,
@@ -769,7 +796,7 @@ class ProviderAdmissionController:
label = self._failure_label(status, error)
if became_leader:
- logger.warning(
+ _log_recovery(
"{}, attempt {}/{} failed; one provider recovery probe in {:.1f}s",
label,
execution.attempts_started,
@@ -802,7 +829,7 @@ class ProviderAdmissionController:
max_attempts=execution.max_attempts,
)
else:
- logger.warning(
+ _log_recovery(
"{} retry exhausted (attempts={})",
label,
execution.attempts_started,
diff --git a/src/free_claude_code/providers/runtime/discovery.py b/src/free_claude_code/providers/runtime/discovery.py
index 2833cbb4..1e070403 100644
--- a/src/free_claude_code/providers/runtime/discovery.py
+++ b/src/free_claude_code/providers/runtime/discovery.py
@@ -133,13 +133,27 @@ def model_list_provider_ids_for_settings(
connected_provider_ids: tuple[str, ...] = (),
) -> tuple[str, ...]:
"""Return providers worth discovering for this process configuration."""
- referenced_ids = referenced_provider_ids(settings)
- return tuple(
- provider_id
- for provider_id in model_cache_provider_ids_for_settings(
- settings, connected_provider_ids
- )
- if settings.custom_provider(provider_id) is not None
- or not PROVIDER_CATALOG[provider_id].local
- or provider_id in referenced_ids
+ return model_cache_provider_ids_for_settings(settings, connected_provider_ids)
+
+
+def is_optional_local_provider(settings: Settings, provider_id: str) -> bool:
+ """Identify default local endpoints the user has not explicitly configured."""
+ descriptor = PROVIDER_CATALOG.get(provider_id)
+ return (
+ descriptor is not None
+ and descriptor.local
+ and provider_id not in referenced_provider_ids(settings)
+ # Validation retains explicitly supplied fields, even default-valued URLs.
+ and descriptor.base_url_attr not in settings.model_fields_set
+ and not (descriptor.proxy_attr and getattr(settings, descriptor.proxy_attr))
)
+
+
+def is_optional_local_failure(
+ settings: Settings, provider_id: str, message: str | None
+) -> bool:
+ """An unused default endpoint being absent is normal during discovery."""
+ return is_optional_local_provider(settings, provider_id) and message in {
+ _FAILURE_MESSAGES["connection"],
+ _FAILURE_MESSAGES["timeout"],
+ }
diff --git a/src/free_claude_code/runtime/diagnostics.py b/src/free_claude_code/runtime/diagnostics.py
index 7ffc2311..e096beb0 100644
--- a/src/free_claude_code/runtime/diagnostics.py
+++ b/src/free_claude_code/runtime/diagnostics.py
@@ -329,7 +329,7 @@ def model_discovery_report(settings: Settings) -> dict[str, Any]:
r"custom_[a-f0-9]{32}", provider_id
):
continue
- if state not in ("starting", "ready", "failed"):
+ if state not in ("starting", "ready", "failed", "unavailable"):
continue
row = {"state": state}
if state == "failed":
diff --git a/src/free_claude_code/runtime/provider_manager.py b/src/free_claude_code/runtime/provider_manager.py
index 0ac830fd..7c8bb4c1 100644
--- a/src/free_claude_code/runtime/provider_manager.py
+++ b/src/free_claude_code/runtime/provider_manager.py
@@ -15,6 +15,7 @@ from free_claude_code.application.model_metadata import (
)
from free_claude_code.application.ports import ModelCatalogPort, ModelCatalogSnapshot
from free_claude_code.application.readiness import InitializationWait
+from free_claude_code.config.provider_catalog import PROVIDER_CATALOG
from free_claude_code.config.settings import Settings
from free_claude_code.core.async_tasks import run_sync_owned
from free_claude_code.core.json_types import JsonObject
@@ -26,6 +27,8 @@ from free_claude_code.providers.base import BaseProvider
from free_claude_code.providers.model_listing import model_infos_from_ids
from free_claude_code.providers.runtime.discovery import (
_provider_query_failure_reason,
+ is_optional_local_failure,
+ is_optional_local_provider,
model_cache_provider_ids_for_settings,
model_list_provider_ids_for_settings,
referenced_provider_ids,
@@ -39,6 +42,8 @@ ProviderRuntimeFactory = Callable[
ConnectedProviderIds = Callable[[], tuple[str, ...]]
CommitConfig = Callable[[], Awaitable[None]]
+LOCAL_DISCOVERY_TIMEOUT_SECONDS = 5.0
+
class ModelCatalogPublisher(Protocol):
"""Publish a frozen model inventory without reading loop-owned mutable state."""
@@ -288,12 +293,31 @@ class ProviderRuntimeManager:
return ProviderModelRefreshResult(refreshed_provider_ids=(provider_id,))
try:
provider = await generation.runtime.resolve_provider(provider_id)
- infos = await provider.list_model_infos()
+ from free_claude_code.providers.admission import (
+ quiet_discovery_recovery_logs,
+ )
+
+ descriptor = PROVIDER_CATALOG.get(provider_id)
+ timeout = (
+ LOCAL_DISCOVERY_TIMEOUT_SECONDS
+ if descriptor is not None and descriptor.local
+ else None
+ )
+ with quiet_discovery_recovery_logs(
+ is_optional_local_provider(generation.settings, provider_id)
+ ):
+ async with asyncio.timeout(timeout):
+ infos = await provider.list_model_infos()
except asyncio.CancelledError:
raise
except Exception as exc:
message = _provider_query_failure_reason(exc)
- logger.warning(
+ log = (
+ logger.debug
+ if is_optional_local_failure(generation.settings, provider_id, message)
+ else logger.warning
+ )
+ log(
"Provider model discovery skipped: provider={} reason={}",
provider_id,
message,
@@ -359,6 +383,21 @@ class ProviderRuntimeManager:
for provider_id in generation.initial_ids
):
break
+ failures = {
+ provider: message
+ for result in results
+ if isinstance(result, ProviderModelRefreshResult)
+ for provider, message in result.failure_messages.items()
+ }
+ failed_ids = tuple(
+ provider
+ for result in results
+ if isinstance(result, ProviderModelRefreshResult)
+ for provider in result.failed_provider_ids
+ if not is_optional_local_failure(
+ generation.settings, provider, failures.get(provider)
+ )
+ )
return ProviderModelRefreshResult(
refreshed_provider_ids=tuple(
provider
@@ -366,18 +405,8 @@ class ProviderRuntimeManager:
if isinstance(result, ProviderModelRefreshResult)
for provider in result.refreshed_provider_ids
),
- failed_provider_ids=tuple(
- provider
- for result in results
- if isinstance(result, ProviderModelRefreshResult)
- for provider in result.failed_provider_ids
- ),
- failure_messages={
- provider: message
- for result in results
- if isinstance(result, ProviderModelRefreshResult)
- for provider, message in result.failure_messages.items()
- },
+ failed_provider_ids=failed_ids,
+ failure_messages={provider: failures[provider] for provider in failed_ids},
)
def start_model_list_refresh(self) -> None:
@@ -484,8 +513,12 @@ class ProviderRuntimeManager:
elif task.cancelled() or task.exception() is not None:
state = "failed"
else:
- state = "failed" if task.result().failed_provider_ids else "ready"
- if message := task.result().failure_messages.get(provider_id):
+ result = task.result()
+ message = result.failure_messages.get(provider_id)
+ state = "failed" if result.failed_provider_ids else "ready"
+ if is_optional_local_failure(generation.settings, provider_id, message):
+ state = "unavailable"
+ elif message:
errors[provider_id] = message
providers[provider_id] = state
return {
@@ -584,6 +617,23 @@ class ProviderRuntimeManager:
settings, self._connected_provider_ids()
)
)
+ for provider_id in cache.cached_model_ids():
+ descriptor = PROVIDER_CATALOG.get(provider_id)
+ if (
+ descriptor is not None
+ and descriptor.local
+ and any(
+ attr is not None
+ and getattr(previous.settings, attr)
+ != getattr(settings, attr)
+ for attr in (
+ descriptor.base_url_attr,
+ descriptor.proxy_attr,
+ )
+ )
+ ):
+ cache.remove_provider(provider_id)
+ cache.add_provider(provider_id)
for definition in settings.custom_providers:
old = previous.settings.custom_provider(definition.provider_id)
if old is None or not definition.same_inventory(old):
diff --git a/tests/cli/test_doctor.py b/tests/cli/test_doctor.py
index 43dbb6d4..0e356619 100644
--- a/tests/cli/test_doctor.py
+++ b/tests/cli/test_doctor.py
@@ -39,11 +39,15 @@ def test_live_discovery_report_projects_only_safe_current_errors(monkeypatch):
"providers": {
"nvidia_nim": "failed",
"open_router": "ready",
+ "lmstudio": "unavailable",
+ "llamacpp": "unavailable",
+ "ollama": "unavailable",
"private-canary": "failed",
},
"provider_errors": {
"nvidia_nim": message,
"open_router": "private-canary",
+ "ollama": "private-canary",
},
},
},
@@ -54,6 +58,8 @@ def test_live_discovery_report_projects_only_safe_current_errors(monkeypatch):
assert result["status"] == "available"
assert result["providers"]["nvidia_nim"] == {"state": "failed", "message": message}
assert result["providers"]["open_router"] == {"state": "ready"}
+ for provider_id in ("lmstudio", "llamacpp", "ollama"):
+ assert result["providers"][provider_id] == {"state": "unavailable"}
assert "private-canary" not in json.dumps(result)
assert requests == [
(
diff --git a/tests/providers/test_model_discovery.py b/tests/providers/test_model_discovery.py
index bd07166e..0c471d4d 100644
--- a/tests/providers/test_model_discovery.py
+++ b/tests/providers/test_model_discovery.py
@@ -73,7 +73,13 @@ def _manager(
settings: Settings,
providers: dict[str, BaseProvider] | None = None,
) -> ProviderRuntimeManager:
- providers = providers or {}
+ providers = {
+ **{
+ provider_id: FakeProvider(error=ConnectionError("Local fixture is offline"))
+ for provider_id in ("lmstudio", "llamacpp", "ollama")
+ },
+ **(providers or {}),
+ }
return ProviderRuntimeManager(
settings,
runtime_factory=lambda snapshot, admission_registry: ProviderRuntime(
@@ -646,7 +652,7 @@ async def test_failed_startup_discovery_remains_eligible_for_explicit_refresh()
@pytest.mark.asyncio
-async def test_runtime_refresh_model_list_cache_uses_configured_remote_keys_and_referenced_local() -> (
+async def test_runtime_refresh_model_list_cache_uses_configured_remote_keys_and_all_locals() -> (
None
):
settings = _settings(
@@ -667,8 +673,9 @@ async def test_runtime_refresh_model_list_cache_uses_configured_remote_keys_and_
assert runtime.cached_model_ids() == {
"open_router": frozenset({"anthropic/claude-sonnet"}),
"lmstudio": frozenset({"local-qwen"}),
+ "ollama": frozenset({"llama3.1"}),
}
- assert result.refreshed_provider_ids == ("lmstudio", "open_router")
+ assert result.refreshed_provider_ids == ("lmstudio", "open_router", "ollama")
assert result.failed_provider_ids == ()
diff --git a/tests/runtime/test_integration_startup.py b/tests/runtime/test_integration_startup.py
index 1fd720f8..ea204d71 100644
--- a/tests/runtime/test_integration_startup.py
+++ b/tests/runtime/test_integration_startup.py
@@ -54,6 +54,8 @@ def runtime():
)
async def construct(_id, _settings, _admission_registry, _api_key_number):
+ if _id in {"lmstudio", "llamacpp", "ollama"}:
+ raise ConnectionError("Local fixture is offline")
return provider
manager = ProviderRuntimeManager(
diff --git a/tests/runtime/test_local_model_discovery.py b/tests/runtime/test_local_model_discovery.py
new file mode 100644
index 00000000..91888eae
--- /dev/null
+++ b/tests/runtime/test_local_model_discovery.py
@@ -0,0 +1,422 @@
+"""Local discovery uses the shared catalog without requiring a selected model."""
+
+import asyncio
+import socket
+from unittest.mock import AsyncMock, MagicMock
+
+import httpx
+import pytest
+
+from free_claude_code.application.model_catalog import read_model_catalog
+from free_claude_code.application.model_metadata import ProviderModelInfo
+from free_claude_code.config.loader import compose_settings_snapshot
+from free_claude_code.config.model_refs import ModelFallback
+from free_claude_code.config.provider_catalog import PROVIDER_CATALOG
+from free_claude_code.config.settings import Settings
+from free_claude_code.providers.admission import (
+ ProviderAdmissionController,
+ ProviderOperationKind,
+)
+from free_claude_code.providers.base import BaseProvider
+from free_claude_code.providers.model_listing import ModelListResponseError
+from free_claude_code.providers.runtime import ProviderRuntime
+from free_claude_code.runtime import provider_manager
+from free_claude_code.runtime.provider_manager import ProviderRuntimeManager
+
+LOCAL_IDS = ("lmstudio", "llamacpp", "ollama")
+
+
+def provider(*ids, error=None):
+ value = MagicMock(spec=BaseProvider)
+ value.list_model_infos = AsyncMock(
+ return_value=frozenset(ProviderModelInfo(model) for model in ids),
+ side_effect=error,
+ )
+ value.cleanup = AsyncMock()
+ return value
+
+
+def manager_for(settings=None, providers=None, **kwargs):
+ settings = settings or Settings()
+ providers = providers or {name: provider(name + "-model") for name in LOCAL_IDS}
+ all_providers = {
+ "nvidia_nim": provider("cloud-model"),
+ **{name: provider(error=ConnectionError()) for name in LOCAL_IDS},
+ **providers,
+ }
+ return ProviderRuntimeManager(
+ settings,
+ runtime_factory=lambda snapshot, registry: ProviderRuntime(
+ snapshot,
+ registry,
+ {(name, 1): value for name, value in all_providers.items()},
+ ),
+ **kwargs,
+ )
+
+
+async def test_startup_discovers_unselected_locals_once_and_publishes_them():
+ providers = {name: provider(name + "-model") for name in LOCAL_IDS}
+ publisher = MagicMock()
+ manager = manager_for(providers=providers, model_catalog_publisher=publisher)
+ try:
+ manager.start_model_list_refresh()
+ await manager.wait_for_catalog()
+ manager.start_model_list_refresh()
+ await manager.wait_for_catalog()
+ assert set(LOCAL_IDS) <= manager.cached_model_ids().keys()
+ assert all(
+ value.list_model_infos.await_count == 1 for value in providers.values()
+ )
+ published = read_model_catalog(publisher.publish.call_args.args[0])
+ assert {name + "/" + name + "-model" for name in LOCAL_IDS} <= {
+ model.provider_model_ref for model in published.models
+ }
+ assert (
+ published.default_model_id == read_model_catalog(manager).default_model_id
+ )
+ finally:
+ await manager.close()
+
+
+async def test_cancelled_local_waiter_preserves_probe_and_refresh_recovers_inventory():
+ entered, release = asyncio.Event(), asyncio.Event()
+
+ async def held():
+ entered.set()
+ await release.wait()
+ return frozenset({ProviderModelInfo("installed")})
+
+ local = provider(error=held)
+ manager = manager_for(providers={"ollama": local})
+ waiter = asyncio.create_task(manager.refresh_provider("ollama"))
+ try:
+ await asyncio.wait_for(entered.wait(), 1)
+ waiter.cancel()
+ with pytest.raises(asyncio.CancelledError):
+ await waiter
+ release.set()
+ await manager.wait_for_catalog()
+ assert local.list_model_infos.await_count == 1
+ assert manager.cached_model_ids()["ollama"] == {"installed"}
+ local.list_model_infos.side_effect = ConnectionError()
+ assert (await manager.refresh_provider("ollama")).failed_provider_ids == (
+ "ollama",
+ )
+ assert manager.cached_model_ids()["ollama"] == {"installed"}
+ local.list_model_infos.side_effect = None
+ local.list_model_infos.return_value = frozenset(
+ {ProviderModelInfo("newly-installed")}
+ )
+ await manager.refresh_model_list_cache()
+ assert manager.cached_model_ids()["ollama"] == {"newly-installed"}
+ finally:
+ release.set()
+ await manager.close()
+
+
+async def test_shutdown_cancels_owned_local_probes_and_cleans_providers():
+ started = set()
+ cancelled = set()
+ ready = asyncio.Event()
+
+ def held(name):
+ async def list_models():
+ started.add(name)
+ if started == set(LOCAL_IDS):
+ ready.set()
+ try:
+ await asyncio.Event().wait()
+ finally:
+ cancelled.add(name)
+
+ return list_models
+
+ providers = {name: provider(error=held(name)) for name in LOCAL_IDS}
+ manager = manager_for(providers=providers)
+ try:
+ manager.start_model_list_refresh()
+ await asyncio.wait_for(ready.wait(), 1)
+ finally:
+ await asyncio.wait_for(manager.close(), 1)
+ assert cancelled == set(LOCAL_IDS)
+ for value in providers.values():
+ value.cleanup.assert_awaited_once()
+
+
+async def test_local_deadlines_are_parallel_and_do_not_block_other_provider_readiness(
+ monkeypatch,
+):
+ monkeypatch.setattr(
+ provider_manager, "LOCAL_DISCOVERY_TIMEOUT_SECONDS", 0.05, raising=False
+ )
+ entered = set()
+ cancelled = set()
+ all_started = asyncio.Event()
+
+ def held(name):
+ async def list_models():
+ entered.add(name)
+ if len(entered) == len(LOCAL_IDS):
+ all_started.set()
+ try:
+ await asyncio.Event().wait()
+ finally:
+ cancelled.add(name)
+
+ return list_models
+
+ providers = {name: provider(error=held(name)) for name in LOCAL_IDS}
+ manager = manager_for(
+ Settings.model_validate({"NVIDIA_NIM_API_KEY": "test"}), providers
+ )
+ try:
+ manager.start_model_list_refresh()
+ await asyncio.wait_for(all_started.wait(), 1)
+ async with await manager.acquire() as lease:
+ await asyncio.wait_for(lease.resolve_provider("nvidia_nim"), 1)
+ assert lease.model_info("nvidia_nim", "cloud-model") is not None
+ result = await asyncio.wait_for(manager.refresh_model_list_cache(), 1)
+ assert not result.failed_provider_ids
+ assert cancelled == set(LOCAL_IDS)
+ status = manager.catalog_status()
+ assert status["catalog"] == "ready"
+ assert status["catalog_file"] == "ready"
+ assert all(status["providers"][name] == "unavailable" for name in LOCAL_IDS)
+ finally:
+ await manager.close()
+
+
+ "failure", [ConnectionError("private-url"), TimeoutError("private-url")]
+)
+async def test_optional_absence_is_quiet_but_shared_manual_test_keeps_failure(
+ failure, caplog
+):
+ entered, release = asyncio.Event(), asyncio.Event()
+
+ async def fail():
+ entered.set()
+ await release.wait()
+ raise failure
+
+ providers = {
+ name: provider(error=fail if name == "ollama" else ConnectionError())
+ for name in LOCAL_IDS
+ }
+ manager = manager_for(providers=providers)
+ try:
+ automatic = asyncio.create_task(manager.refresh_model_list_cache())
+ await asyncio.wait_for(entered.wait(), 1)
+ manual = asyncio.create_task(manager.refresh_provider("ollama"))
+ await asyncio.sleep(0)
+ release.set()
+ assert not (await automatic).failed_provider_ids
+ result = await manual
+ assert result.failed_provider_ids == ("ollama",)
+ assert "private-url" not in str(result.failure_messages)
+ assert providers["ollama"].list_model_infos.await_count == 1
+ assert manager.catalog_status()["providers"]["ollama"] == "unavailable"
+ assert not [record for record in caplog.records if record.levelno >= 30]
+ finally:
+ release.set()
+ await manager.close()
+
+
+ "intent",
+ ["managed_default", "process_default", "url", "proxy", "model", "fallback"],
+)
+async def test_explicit_local_configuration_reports_failure(intent):
+ default_url = Settings().ollama_base_url
+ expected_provider = "lmstudio" if intent == "proxy" else "ollama"
+ if intent == "managed_default":
+ settings = compose_settings_snapshot(
+ {"OLLAMA_BASE_URL": default_url}, {}
+ ).settings
+ elif intent == "process_default":
+ settings = compose_settings_snapshot(
+ {}, {"OLLAMA_BASE_URL": default_url}
+ ).settings
+ else:
+ changes = {
+ "url": {"ollama_base_url": "http://localhost:11435"},
+ "proxy": {"lmstudio_proxy": "http://localhost:8000"},
+ "model": {"model": "ollama/test-model"},
+ "fallback": {
+ "model_fallbacks": (ModelFallback(model="ollama/test-model"),)
+ },
+ }
+ settings = Settings().model_copy(update=changes[intent])
+ providers = {name: provider(error=ConnectionError()) for name in LOCAL_IDS}
+ manager = manager_for(settings, providers)
+ try:
+ result = await manager.refresh_model_list_cache()
+ assert result.failed_provider_ids == (expected_provider,)
+ assert expected_provider in result.failure_messages
+ assert manager.catalog_status()["providers"][expected_provider] == "failed"
+ finally:
+ await manager.close()
+
+
+ "failure",
+ [
+ ModelListResponseError("private-response"),
+ httpx.HTTPStatusError(
+ "private-response",
+ request=httpx.Request("GET", "http://localhost"),
+ response=httpx.Response(401),
+ ),
+ RuntimeError("private-response"),
+ ],
+)
+async def test_responding_or_broken_optional_provider_reports_real_errors(failure):
+ providers = {
+ name: provider(error=failure if name == "ollama" else ConnectionError())
+ for name in LOCAL_IDS
+ }
+ manager = manager_for(providers=providers)
+ try:
+ result = await manager.refresh_model_list_cache()
+ assert result.failed_provider_ids == ("ollama",)
+ assert "private-response" not in str(result.failure_messages)
+ assert manager.catalog_status()["providers"]["ollama"] == "failed"
+ finally:
+ await manager.close()
+
+
+ ("local_id", "attr"),
+ [
+ (name, attr)
+ for name in LOCAL_IDS
+ for attr in (
+ PROVIDER_CATALOG[name].base_url_attr,
+ PROVIDER_CATALOG[name].proxy_attr,
+ )
+ if attr is not None
+ ],
+)
+async def test_local_endpoint_change_discards_old_inventory_on_failed_rediscovery(
+ local_id, attr
+):
+ providers = {name: provider(error=ConnectionError()) for name in LOCAL_IDS}
+ manager = manager_for(providers=providers)
+ try:
+ manager.cache_model_infos(local_id, {ProviderModelInfo("old-server-model")})
+ settings = manager.current_settings().model_copy(
+ update={attr: "http://localhost:9999"}
+ )
+ await manager.replace(settings, commit=AsyncMock())
+ await manager.wait_for_catalog()
+ assert local_id not in manager.cached_model_ids()
+ assert local_id + "/old-server-model" not in {
+ model.provider_model_ref for model in read_model_catalog(manager).models
+ }
+ finally:
+ await manager.close()
+
+
+async def test_optional_timeout_releases_real_admission_and_keeps_recovery_logs_quiet(
+ monkeypatch, caplog
+):
+ monkeypatch.setattr(provider_manager, "LOCAL_DISCOVERY_TIMEOUT_SECONDS", 0.05)
+ controller = ProviderAdmissionController(
+ provider_name="ollama",
+ rate_limit=1000,
+ rate_window=1,
+ max_concurrency=1,
+ base_delay=0.1,
+ max_delay=0.1,
+ jitter=0,
+ )
+
+ async def offline():
+ raise httpx.ConnectError("private-address")
+
+ async def list_models():
+ return await controller.start_execution().run_call(
+ offline, operation_kind=ProviderOperationKind.MODEL_DISCOVERY
+ )
+
+ providers = {
+ name: provider(error=list_models if name == "ollama" else ConnectionError())
+ for name in LOCAL_IDS
+ }
+ manager = manager_for(providers=providers)
+ try:
+ result = await manager.refresh_model_list_cache()
+ assert not result.failed_provider_ids
+ assert not [record for record in caplog.records if record.levelno >= 30]
+ async with await manager.acquire() as lease:
+ assert await lease.resolve_provider("ollama") is providers["ollama"]
+ assert (
+ await asyncio.wait_for(
+ controller.start_execution().run_call(
+ AsyncMock(return_value="healthy"),
+ operation_kind=ProviderOperationKind.GENERATION,
+ ),
+ 1,
+ )
+ == "healthy"
+ )
+ finally:
+ await manager.close()
+
+
+ "failure",
+ [
+ socket.gaierror("private-host"),
+ httpx.HTTPStatusError(
+ "private-response",
+ request=httpx.Request("GET", "http://localhost"),
+ response=httpx.Response(503),
+ ),
+ ],
+)
+async def test_local_deadline_preserves_actual_failure_during_admission_backoff(
+ monkeypatch, failure
+):
+ monkeypatch.setattr(provider_manager, "LOCAL_DISCOVERY_TIMEOUT_SECONDS", 0.05)
+ controller = ProviderAdmissionController(
+ provider_name="ollama",
+ rate_limit=1000,
+ rate_window=1,
+ max_concurrency=1,
+ base_delay=0.1,
+ max_delay=0.1,
+ jitter=0,
+ )
+
+ async def broken():
+ if isinstance(failure, socket.gaierror):
+ raise httpx.ConnectError("private-host") from failure
+ raise failure
+
+ async def list_models():
+ return await controller.start_execution().run_call(
+ broken, operation_kind=ProviderOperationKind.MODEL_DISCOVERY
+ )
+
+ manager = manager_for(providers={"ollama": provider(error=list_models)})
+ try:
+ result = await manager.refresh_model_list_cache()
+ assert result.failed_provider_ids == ("ollama",)
+ expected = (
+ "DNS lookup failed" if isinstance(failure, socket.gaierror) else "HTTP 503"
+ )
+ assert expected in result.failure_messages["ollama"]
+ finally:
+ await manager.close()
diff --git a/tests/runtime/test_provider_manager.py b/tests/runtime/test_provider_manager.py
index 4dd4be80..6122eaff 100644
--- a/tests/runtime/test_provider_manager.py
+++ b/tests/runtime/test_provider_manager.py
@@ -32,6 +32,8 @@ class FakeRuntime(ProviderRuntime):
async def resolve_provider(
self, provider_id: str, api_key_number: int = 1
) -> BaseProvider:
+ if provider_id in {"lmstudio", "llamacpp", "ollama"}:
+ raise ConnectionError("Local fixture is offline")
return cast(BaseProvider, self.provider)
async def cleanup(self) -> None:
@@ -111,11 +113,18 @@ async def test_discovery_error_follows_attempt_and_generation_without_losing_cac
provider.list_model_infos.side_effect = held
refresh = asyncio.create_task(manager.refresh_provider("nvidia_nim"))
await entered.wait()
- assert manager.catalog_status()["providers"] == {"nvidia_nim": "starting"}
+ local_states = dict.fromkeys(("lmstudio", "llamacpp", "ollama"), "unavailable")
+ assert manager.catalog_status()["providers"] == {
+ "nvidia_nim": "starting",
+ **local_states,
+ }
assert manager.catalog_status()["provider_errors"] == {}
release.set()
assert (await refresh).failure_messages == {}
- assert manager.catalog_status()["providers"] == {"nvidia_nim": "ready"}
+ assert manager.catalog_status()["providers"] == {
+ "nvidia_nim": "ready",
+ **local_states,
+ }
provider.list_model_infos.side_effect = httpx2.ProxyError("secret-canary")
await manager.refresh_provider("nvidia_nim")
await manager.replace(settings, commit=AsyncMock())
diff --git a/tests/runtime/test_vscode_chat_sync.py b/tests/runtime/test_vscode_chat_sync.py
index 3457566d..398a417a 100644
--- a/tests/runtime/test_vscode_chat_sync.py
+++ b/tests/runtime/test_vscode_chat_sync.py
@@ -30,7 +30,9 @@ async def runtime(request):
return_value=frozenset({ProviderModelInfo("one")})
)
- async def construct(*_):
+ async def construct(provider_id, *_):
+ if provider_id in {"lmstudio", "llamacpp", "ollama"}:
+ raise ConnectionError()
return provider
manager = ProviderRuntimeManager(