The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
fix(desktop): a down local model server no longer sends the Webapp to provider sign-in
Teknium8a8d453ad12e
diff --git a/agent/error_surface.py b/agent/error_surface.pyindex 4ae25a2cdfe..a054b9c8242 100644--- a/agent/error_surface.py+++ b/agent/error_surface.py@@ -39,6 +39,7 @@ _REASON_TO_LAYER = {"loop_error": LAYER_GATEWAY, "interpreter_shutdown": LAYER_GATEWAY, "session_busy": LAYER_GATEWAY,"gateway_connection": LAYER_GATEWAY, "host_error": LAYER_GATEWAY, "workspace_unavailable": LAYER_GATEWAY,"launch_credentials_unavailable": LAYER_GATEWAY,+ "local_runtime_unavailable": LAYER_ENDPOINT, # the managed local model server is down"truncated": LAYER_PROVIDER, "empty_response": LAYER_PROVIDER, "invalid_response": LAYER_PROVIDER,"context_overflow": LAYER_PROVIDER, # a bigger-window model IS the fix, so Switch provider applies}diff --git a/apps/desktop/src/lib/error-surface.ts b/apps/desktop/src/lib/error-surface.tsindex 113c99f6955..9f87479e157 100644--- a/apps/desktop/src/lib/error-surface.ts+++ b/apps/desktop/src/lib/error-surface.ts@@ -449,6 +449,12 @@ export function errorCardActions(surface: ErrorSurface | null | undefined): Erro}}+ // The managed local model server is down: another model is the fix the card can offer, and a+ // server that is still starting (retryable) is worth one more try.+ if (surface.code === 'local_runtime_unavailable') {+ return surface.retryable ? { primary: 'retry', secondary: 'switch_provider' } : { primary: 'switch_provider' }+ }+const key = errorCardKey(surface)// errorCardKey routes a custom/local server's timeout or TLS failure to the endpoint copy.diff --git a/apps/desktop/src/lib/runtime-readiness.ts b/apps/desktop/src/lib/runtime-readiness.tsindex 85f408f9441..e075adc73b3 100644--- a/apps/desktop/src/lib/runtime-readiness.ts+++ b/apps/desktop/src/lib/runtime-readiness.ts@@ -19,6 +19,9 @@ export interface SetupStatusSnapshot {export interface RuntimeCheckSnapshot {error?: string+ /** Why the check failed, when the backend names it (`local_runtime_unavailable`: the managed+ * local model server is down). Absent on older backends and for unclassified failures. */+ error_code?: string/** True when the resolved route is the free tier rather than a credential of* the user's own. Absent on older backends. */free_tier_route?: boolean@@ -42,6 +45,8 @@ export interface RuntimeReadinessOptions {export interface RuntimeReadinessResult {checksDisagree: boolean+ /** Passed through from `setup.runtime_check.error_code`. */+ errorCode?: string/** Passed through from `setup.runtime_check`: the resolved route is the free* tier. Undefined when the check did not answer (older backend, transport* fallback) — never read it as "not free tier". */@@ -148,6 +153,7 @@ export function interpretRuntimeReadiness(// (free-tier chrome) don't have to re-issue setup.runtime_check. Left// undefined when the check said nothing — "absent" and "false" differ.const route = {+ errorCode: normalizeMessage(signals.runtime?.error_code) ?? undefined,freeTier: typeof signals.runtime?.free_tier_route === 'boolean' ? signals.runtime.free_tier_route : undefined,model: normalizeMessage(signals.runtime?.model) ?? undefined}@@ -168,7 +174,8 @@ export function interpretRuntimeReadiness(let reason = failure.runtime ?? defaultReason- if (checksDisagree && setupConfigured) {+ // A coded failure names its own cause; the suffix exists to explain an uncoded disagreement.+ if (checksDisagree && setupConfigured && !route.errorCode) {reason = `${reason} setup.status reports configured credentials, but runtime resolution still failed.`}diff --git a/apps/desktop/src/store/onboarding.ts b/apps/desktop/src/store/onboarding.tsindex 9fc6e4e15b7..fe3804c9ad3 100644--- a/apps/desktop/src/store/onboarding.ts+++ b/apps/desktop/src/store/onboarding.ts@@ -34,6 +34,7 @@ import { setMainModelAssignment } from '@/store/model-assignment'import { dismissNotification, notify, notifyError } from '@/store/notifications'import { afterOnboardingSurfaceClear, onboardingSurfaceOpen } from '@/store/onboarding-presence'import { captureOnboardingScope, type OnboardingScope } from '@/store/onboarding-scope'+import { requestRoute } from '@/store/recovery-requests'import type { AppHandoffStatus, OAuthPollResponse, OAuthProvider, OAuthStartResponse } from '@/types/hermes'type PkceStart = Extract<OAuthStartResponse, { flow: 'pkce' }>@@ -303,6 +304,29 @@ function shouldPreserveConfiguredOnBootRace(runtime: RuntimeReadinessResult, sta)}+// The selected model is the managed local runtime and its server is down (Desktop closed and took+// its server with it, still loading, or switched off). The provider IS set up, and provider sign-in+// cannot start a local server, so this never opens onboarding: the app stays usable, the status bar+// reads "inference unavailable", and a notice names the cause with the way forward.+const LOCAL_RUNTIME_UNAVAILABLE = 'local_runtime_unavailable'+const LOCAL_MODELS_ROUTE = '/settings?tab=providers&pview=local'++function isLocalRuntimeDown(runtime: RuntimeReadinessResult, state: DesktopOnboardingState): boolean {+ return runtime.source === 'runtime_check' && runtime.errorCode === LOCAL_RUNTIME_UNAVAILABLE && !state.requested+}++function keepConfiguredWithLocalRuntimeDown(reason: string) {+ writeCachedConfigured(true)+ patch({ configured: true, reason })+ notify({+ action: { label: 'Open Local models', onClick: () => requestRoute(LOCAL_MODELS_ROUTE) },+ id: 'local-runtime-unavailable',+ kind: 'warning',+ message: reason,+ title: 'Local model unavailable'+ })+}+function notifyReady(provider: string) {notify({ kind: 'success', title: 'Hermes is ready', message: `${provider} connected.` })}@@ -748,6 +772,7 @@ export function closeManualOnboarding() {export function completeDesktopOnboarding(connected = false) {clearPoll()dismissNotification('runtime-not-ready')+ dismissNotification('local-runtime-unavailable')writeCachedConfigured(true)if (connected) {@@ -850,6 +875,12 @@ export async function refreshOnboarding(ctx: OnboardingContext, stillWanted?: ()const reason = runtime.reason || state.reason || DEFAULT_ONBOARDING_REASON+ if (isLocalRuntimeDown(runtime, state)) {+ keepConfiguredWithLocalRuntimeDown(reason)++ return false+ }+if (shouldPreserveConfiguredOnBootRace(runtime, state)) {// The backend answered inside its boot window with a not-ready that is// explained by external secrets still hydrating (#124939). Do not writediff --git a/apps/shared/src/gateway-contract.generated.ts b/apps/shared/src/gateway-contract.generated.tsindex ab3df77f3a8..51912c7300b 100644--- a/apps/shared/src/gateway-contract.generated.ts+++ b/apps/shared/src/gateway-contract.generated.ts@@ -649,6 +649,7 @@ export interface SetupRuntimeCheckResult {model?: string | nullsource?: string | nullerror?: string | null+ error_code?: string | nullfree_tier_route?: boolean | nullprofile?: string | null}diff --git a/apps/shared/src/gateway-contract.openrpc.json b/apps/shared/src/gateway-contract.openrpc.jsonindex 237cd0ed52b..6a82e03754b 100644--- a/apps/shared/src/gateway-contract.openrpc.json+++ b/apps/shared/src/gateway-contract.openrpc.json@@ -40199,6 +40199,18 @@"default": null,"title": "Error"},+ "error_code": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "null"+ }+ ],+ "default": null,+ "title": "Error Code"+ },"free_tier_route": {"anyOf": [{diff --git a/gateway/run_turn_runner.py b/gateway/run_turn_runner.pyindex 9a6410cd176..af98500a160 100644--- a/gateway/run_turn_runner.py+++ b/gateway/run_turn_runner.py@@ -140,8 +140,13 @@ def _resolution_failure_reply(exc: Exception, platform: Platform) -> tuple[str,"""``(chat text, failure_reason, retryable)`` for a model/credential resolution failure before the turn."""from agent.error_classifier import FailoverReasonfrom hermes_cli.auth import AuthError, is_rate_limited_auth_error+ from hermes_cli.runtime_provider_custom import LocalRuntimeUnavailableErrorfrom hermes_state_runtime import RuntimeStoreErrorauth_permanent = FailoverReason.auth_permanent.value+ if isinstance(exc, LocalRuntimeUnavailableError):+ # The chosen model is configured; its local server is down. Not a credential verdict, so+ # the client must not offer "Update API key" or sign-in: the sentence names the fix.+ return f"⚠️ {exc}", exc.error_code, exc.retryableif isinstance(exc, RuntimeStoreError) and exc.reason == 'launch_credentials_unavailable':# The session's launch key is gone (a restart revoked a CLI --api-key, a route key changed):# the shared refusal copy names /new, never a resend.diff --git a/gateway/session_readiness.py b/gateway/session_readiness.pyindex 19d48e93714..01456278d5b 100644--- a/gateway/session_readiness.py+++ b/gateway/session_readiness.py@@ -36,6 +36,9 @@ async def readiness(authority, actor, params, *, runtime):return {'provider_configured': bool(_has_any_provider_configured(strict_profile_scope=True))}except Exception as exc: # a readiness probe reports, never raiseslogger.debug('readiness probe failed', exc_info=True)+ if runtime:+ from hermes_cli.runtime_readiness import readiness_failure+ return readiness_failure(exc)return {'ok': False, 'error': str(exc)}return await asyncio.to_thread(probe)diff --git a/hermes_cli/runtime_provider_custom.py b/hermes_cli/runtime_provider_custom.pyindex 49739d8985c..6b8439ed942 100644--- a/hermes_cli/runtime_provider_custom.py+++ b/hermes_cli/runtime_provider_custom.py@@ -582,6 +582,20 @@ def _apply_custom_provider_extras(custom_provider: dict[str, Any], target_model:result["request_overrides"] = {**(result.get("request_overrides") or {}), **request_overrides}+class LocalRuntimeUnavailableError(ValueError):+ """The selected model is the managed local runtime and its server is not serving.++ Typed so readiness probes can say "configured, but the local server is down" instead of+ "nothing configured": provider onboarding cannot start a local server.+ """++ error_code = "local_runtime_unavailable"++ def __init__(self, message: str, *, retryable: bool = False) -> None:+ super().__init__(message)+ self.retryable = retryable++def _resolve_llamacpp_runtime(requested_provider: str, explicit_api_key: Optional[str]) -> dict[str, Any]:"""Managed llama.cpp runtime: the supervised (or detected external) server, or a typed error.No server => say so and stop; falling through to the generic custom path would surface "local@@ -602,12 +616,12 @@ def _resolve_llamacpp_runtime(requested_provider: str, explicit_api_key: Optionaexcept Exception:enabled = Falseif enabled:- raise ValueError("The local model server isn't running. It may still be "- "starting — try again in a moment, or check Settings → "- "Providers → Local models.")- raise ValueError("The local model server is turned off. Turn it back on in "- "Settings → Providers → Local models, or switch to another "- "model.")+ raise LocalRuntimeUnavailableError("The local model server isn't running. It may still be "+ "starting — try again in a moment, or check Settings → "+ "Providers → Local models.", retryable=True)+ raise LocalRuntimeUnavailableError("The local model server is turned off. Turn it back on in "+ "Settings → Providers → Local models, or switch to another "+ "model.")def _custom_runtime(rp, base_url: str, api_key: Any, api_mode: Optional[str], **extra: Any) -> dict[str, Any]:diff --git a/hermes_cli/runtime_readiness.py b/hermes_cli/runtime_readiness.pyindex 71ea8fdf29f..cbc2bce05e0 100644--- a/hermes_cli/runtime_readiness.py+++ b/hermes_cli/runtime_readiness.py@@ -33,6 +33,17 @@ def missing_credentials_suffix(provider) -> str:_HINT_FAILURES_LOGGED: set[str] = set()+def readiness_failure(exc) -> dict:+ """``setup.runtime_check``'s answer when resolving the runtime raised *exc*.++ ``error_code`` rides along only for a failure provider setup cannot repair, so a client keeps+ the app open with the error instead of sending the user back through provider sign-in.+ """+ from hermes_cli.runtime_provider_custom import LocalRuntimeUnavailableError+ code = {'error_code': exc.error_code} if isinstance(exc, LocalRuntimeUnavailableError) else {}+ return {'ok': False, 'error': str(exc), **code}++def check_runtime_readiness(requested=None, *, strict_profile_scope=False, resolve=None):"""ok/error verdict for the runtime a session would be built with.diff --git a/tui_gateway/contracts/config_free_tier_control.py b/tui_gateway/contracts/config_free_tier_control.pyindex a7346e3f0a6..fde2b867413 100644--- a/tui_gateway/contracts/config_free_tier_control.py+++ b/tui_gateway/contracts/config_free_tier_control.py@@ -141,6 +141,8 @@ class SetupRuntimeCheckResult(Result):model: str | None = Nonesource: str | None = Noneerror: str | None = None+ #: ``local_runtime_unavailable``: the selected model is the managed local server and it is down.+ error_code: str | None = Nonefree_tier_route: bool | None = Noneprofile: str | None = Nonediff --git a/tui_gateway/methods_config.py b/tui_gateway/methods_config.pyindex d3641cb9079..def88d9c5b0 100644--- a/tui_gateway/methods_config.py+++ b/tui_gateway/methods_config.py@@ -480,7 +480,8 @@ def _(rid, params: dict) -> dict:return _readiness_check(rid, params, probe, probe_key=f"runtime:{requested or ''}",wait_seconds=_READINESS_SHARE_WAIT_SECONDS)except Exception as e:- return _ok(rid, {"ok": False, "error": str(e)})+ from hermes_cli.runtime_readiness import readiness_failure+ return _ok(rid, readiness_failure(e))def _redact_client_text(text: str, cap: int) -> str: