Skip to content

The agent that grows with you

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.py
index 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.ts
index 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.ts
index 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.ts
index 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 write
diff --git a/apps/shared/src/gateway-contract.generated.ts b/apps/shared/src/gateway-contract.generated.ts
index 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 | null
source?: string | null
error?: string | null
+ error_code?: string | null
free_tier_route?: boolean | null
profile?: string | null
}
diff --git a/apps/shared/src/gateway-contract.openrpc.json b/apps/shared/src/gateway-contract.openrpc.json
index 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.py
index 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 FailoverReason
from hermes_cli.auth import AuthError, is_rate_limited_auth_error
+ from hermes_cli.runtime_provider_custom import LocalRuntimeUnavailableError
from hermes_state_runtime import RuntimeStoreError
auth_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.retryable
if 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.py
index 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 raises
logger.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.py
index 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: Optiona
except Exception:
enabled = False
if 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.py
index 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.py
index 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 = None
source: str | None = None
error: str | None = None
+ #: ``local_runtime_unavailable``: the selected model is the managed local server and it is down.
+ error_code: str | None = None
free_tier_route: bool | None = None
profile: str | None = None
diff --git a/tui_gateway/methods_config.py b/tui_gateway/methods_config.py
index 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: