Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
refactor(credentials): shared Credential.validate scaffold + per-provider _probe
trohitg65a6c12a6cb2
diff --git a/server/main.py b/server/main.pyindex be51e91f..4f0d63db 100644--- a/server/main.py+++ b/server/main.py@@ -443,19 +443,36 @@ app.add_middleware(expose_headers=["*"],)-# Include routers+# Include framework-level routers (everything that's NOT plugin-specific+# stays here). Plugin-owned routers self-register via+# ``services.ws_handler_registry.register_router`` from their plugin+# folder's ``__init__.py`` and are mounted via the loop below — main.py+# never imports a migrated plugin module by name.app.include_router(auth.router) # Auth routes (login, register, logout, status)app.include_router(nodejs_compat.router) # Node.js compatibility (includes root endpoints)app.include_router(workflow.router)app.include_router(database.router)+app.include_router(websocket.router)+app.include_router(credentials.router) # Credentials panel - lazy per-tile icon endpoint (n8n pattern)+app.include_router(schemas.router) # Per-node output schema endpoint (GET /api/schemas/nodes/{type}.json)++# Routers awaiting migration into their plugin folders. As each plugin+# moves to the self-contained pattern (nodes/<plugin>/_router.py ++# register_router from __init__.py), the corresponding line below is+# removed. Tracked in the plugin-extraction plan.app.include_router(maps.router)app.include_router(android.router)-app.include_router(websocket.router)app.include_router(webhook.router)app.include_router(twitter.router) # Twitter/X OAuth routesapp.include_router(google.router) # Google Workspace OAuth routes (Gmail, Calendar, Drive, Sheets, Tasks, Contacts)-app.include_router(credentials.router) # Credentials panel - lazy per-tile icon endpoint (n8n pattern)-app.include_router(schemas.router) # Per-node output schema endpoint (GET /api/schemas/nodes/{type}.json)++# Plugin-registered routers — populated by `nodes/<plugin>/__init__.py`+# at import time via `register_router(...)`. Plugins are imported during+# the node-discovery walk on app startup; iterating here picks up+# anything that registered.+from services.ws_handler_registry import get_routers as _get_plugin_routers+for _plugin_router in _get_plugin_routers():+ app.include_router(_plugin_router)# ---------------------------------------------------------------------------diff --git a/server/nodes/location/_credentials.py b/server/nodes/location/_credentials.pyindex cbe46f44..b1674c20 100644--- a/server/nodes/location/_credentials.py+++ b/server/nodes/location/_credentials.py@@ -8,7 +8,17 @@ gmaps_locations, gmaps_nearby_places). Separate fromfrom __future__ import annotations-from services.plugin.credential import ApiKeyCredential+import httpx++from services.plugin.credential import ApiKeyCredential, ProbeResult+++# Google's documented sentinel address for connectivity tests on the+# Geocoding API. Returns ``status=OK`` for any working key with the+# Geocoding API enabled; ``REQUEST_DENIED`` for a bad key or disabled+# API. We never store the response — it's just a probe.+_GEOCODE_SENTINEL = "1600 Amphitheatre Parkway, Mountain View, CA"+_GEOCODE_URL = "https://maps.googleapis.com/maps/api/geocode/json"class GoogleMapsCredential(ApiKeyCredential):@@ -19,3 +29,37 @@ class GoogleMapsCredential(ApiKeyCredential):key_name = "key"key_location = "query"docs_url = "https://developers.google.com/maps/documentation"++ @classmethod+ async def _probe(cls, api_key: str) -> ProbeResult:+ """Geocode a sentinel address to verify the key is live.++ Replaces ``handle_validate_maps_key`` in+ ``routers/websocket.py``; the storage + broadcast wiring is+ handled by the base :meth:`Credential.validate` so this method+ only needs to translate the geocode response into a+ :class:`ProbeResult`. ``REQUEST_DENIED`` → invalid; ``OK`` /+ ``ZERO_RESULTS`` / ``OVER_QUERY_LIMIT`` → valid (the key+ authenticated, even if the query didn't return rows).+ """+ async with httpx.AsyncClient(timeout=10.0) as client:+ response = await client.get(+ _GEOCODE_URL,+ params={"address": _GEOCODE_SENTINEL, "key": api_key},+ )+ payload = response.json()+ status = payload.get("status")++ if status == "REQUEST_DENIED":+ return ProbeResult(+ valid=False,+ message=payload.get("error_message", "Invalid API key"),+ )+ return ProbeResult(+ valid=True,+ message=(+ "Google Maps API key is valid"+ if status == "OK"+ else f"API key is valid (status: {status})"+ ),+ )diff --git a/server/nodes/model/_credentials.py b/server/nodes/model/_credentials.pyindex 8bc7bc51..059f8a8d 100644--- a/server/nodes/model/_credentials.py+++ b/server/nodes/model/_credentials.py@@ -21,16 +21,44 @@ from __future__ import annotationsfrom typing import Any, Dict-from services.plugin.credential import ApiKeyCredential+from services.plugin.credential import ApiKeyCredential, ProbeResultclass _LLMApiKey(ApiKeyCredential):- """Shared defaults. Subclasses only set id / display_name / icon."""+ """Shared defaults. Subclasses only set id / display_name / icon.++ The :meth:`_probe` override calls ``ai_service.fetch_models`` —+ every cloud LLM provider in this file inherits it, so adding a new+ OpenAI-compatible provider is purely declarative (id + base_url in+ JSON; no validator code). The local-server credential override+ (:class:`_LocalLLM`) supersedes ``validate`` entirely because its+ side-effect ordering differs (URL stored under ``{id}_proxy``+ before the probe + per-model context registration after).+ """category = "AI"key_name = "Authorization"key_location = "bearer"+ @classmethod+ async def _probe(cls, api_key: str) -> ProbeResult:+ """Default LLM probe: fetch the provider's model list.++ Hits ``GET /v1/models`` (or the provider equivalent) via+ :meth:`AIService.fetch_models`. Returns a populated+ :class:`ProbeResult` on success; raises ``httpx``/``openai``+ exceptions for the base ``Credential.validate`` to classify.+ """+ from core.container import container++ ai_service = container.ai_service()+ models = await ai_service.fetch_models(cls.id, api_key)+ return ProbeResult(+ valid=True,+ message="API key validated",+ models=models,+ )+class OpenAICredential(_LLMApiKey):id = "openai"@@ -125,6 +153,23 @@ class _LocalLLM(_LLMApiKey):api_key = await container.auth_service().get_api_key(cls.id)return {"api_key": api_key or "ollama"}+ @classmethod+ async def validate(cls, data: Dict[str, Any]) -> Dict[str, Any]:+ """Probe the user's local server via the official SDK.++ Overrides the base ``Credential.validate`` because local-LLM+ side-effect ordering genuinely differs from the cloud case:+ the user's URL is persisted under ``{cls.id}_proxy`` BEFORE+ the probe runs, the placeholder ``api_key="ollama"`` is+ stored under ``cls.id`` only on success, and per-model context+ is registered in the model registry. Delegates to the+ SDK-typed probe in ``_local_validator.py`` which already owns+ that full flow.+ """+ from ._local_validator import validate_local_llm++ return await validate_local_llm(dict(data, provider=cls.id))+class OllamaCredential(_LocalLLM):id = "ollama"diff --git a/server/nodes/model/_local_validator.py b/server/nodes/model/_local_validator.pyindex d36b688d..ca7a6ca9 100644--- a/server/nodes/model/_local_validator.py+++ b/server/nodes/model/_local_validator.py@@ -44,8 +44,6 @@ from typing import Any, Dict, List, Optional, Tupleimport httpximport lmstudioimport ollama-from fastapi import WebSocket-from core.container import containerfrom core.logging import get_loggerfrom services.status_broadcaster import get_status_broadcaster@@ -239,8 +237,16 @@ async def _fetch_local_models(provider: str, base_url: str) -> List[Dict[str, Anraise ValueError(f"Unsupported local provider: {provider}")-async def validate_local_llm(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:- """Validator for ollama / lmstudio. Matches the SPECIAL_PROVIDER_VALIDATORS contract."""+async def validate_local_llm(data: Dict[str, Any]) -> Dict[str, Any]:+ """Validator for ollama / lmstudio. Returns the standard response envelope.++ Called from :meth:`nodes.model._credentials._LocalLLM.validate` (the+ ``Credential.validate`` hook ``handle_validate_api_key`` dispatches+ to). All side effects (URL persistence, status broadcasts, model+ registry registration) go through the ``StatusBroadcaster`` /+ ``AuthService`` singletons — no per-request WebSocket reference is+ needed.+ """provider = data["provider"].lower()base_url = data.get("api_key", "").strip()session_id = data.get("session_id", "default")diff --git a/server/nodes/scraper/_credentials.py b/server/nodes/scraper/_credentials.pyindex 88172cac..d8c538cd 100644--- a/server/nodes/scraper/_credentials.py+++ b/server/nodes/scraper/_credentials.py@@ -6,7 +6,7 @@ subclasses here in future.from __future__ import annotations-from services.plugin.credential import ApiKeyCredential+from services.plugin.credential import ApiKeyCredential, ProbeResultclass ApifyCredential(ApiKeyCredential):@@ -17,3 +17,31 @@ class ApifyCredential(ApiKeyCredential):key_name = "Authorization"key_location = "bearer"docs_url = "https://docs.apify.com/api/v2"++ @classmethod+ async def _probe(cls, api_key: str) -> ProbeResult:+ """Probe Apify ``/users/me`` to verify the token + capture+ username / email / plan for display in the credentials panel.++ ``validate_apify_token`` lives on the plugin module+ (``apify_actor.py``) and uses the official ``apify_client`` SDK.+ It returns a dict; we translate to :class:`ProbeResult` so the+ base ``Credential.validate`` handles storage / broadcast.+ """+ from .apify_actor import validate_apify_token++ result = await validate_apify_token(api_key)+ if not result.get("valid"):+ return ProbeResult(+ valid=False,+ message=result.get("error", "Invalid API token"),+ )+ return ProbeResult(+ valid=True,+ message=f"Apify token validated — user: {result.get('username', 'unknown')}",+ extra={+ "username": result.get("username"),+ "email": result.get("email"),+ "plan": result.get("plan"),+ },+ )diff --git a/server/routers/websocket.py b/server/routers/websocket.pyindex 55b34f61..61a1f9a6 100644--- a/server/routers/websocket.py+++ b/server/routers/websocket.py@@ -1231,71 +1231,34 @@ async def handle_get_ai_models(data: Dict[str, Any], websocket: WebSocket) -> Diasync def handle_validate_api_key(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:"""Validate and store an API key.- Single entry point for all providers. Dispatches to provider-specific- validators (Google Maps geocode probe, Apify /users/me probe) for- non-LLM providers; otherwise falls through to the default LLM- ``/v1/models`` probe via ``ai_service.fetch_models``. The frontend- calls this one handler for every provider — no per-provider branching- on the TypeScript side.-- Invalid-key responses (401/403) and provider-side errors (4xx/5xx,- timeouts, DNS failures) are mapped to a clean- ``{success: True, valid: False, message: "..."}`` envelope — same- shape the Maps/Apify validators return — so the frontend toast- surfaces the actual reason instead of the generic- "Validation failed" fallback. These are user-correctable input- failures, not handler bugs, so they log at WARNING with a one-liner- rather than ERROR with a stacktrace.+ Pure dispatch — looks up the plugin's ``Credential`` subclass in+ ``CREDENTIAL_REGISTRY`` and calls its ``validate`` classmethod. The+ base ``Credential.validate`` (defined in+ ``services/plugin/credential.py``) wires the shared scaffold+ (storage + status broadcast + error classification + response+ envelope) and dispatches the per-provider probe via the+ subclass-supplied ``_probe`` hook. Cloud LLM providers inherit+ ``_LLMApiKey._probe`` (``ai_service.fetch_models``); Maps + Apify ++ local-LLM credentials override ``_probe`` (or the whole ``validate``+ method, in the local-LLM case) with their own bespoke probes.++ The router doesn't know about specific providers — adding a new+ provider with a special validator is a single new ``_probe``+ override on the plugin's ``Credential`` subclass."""- import httpx+ from services.plugin.credential import CREDENTIAL_REGISTRYprovider = data["provider"].lower()normalized = dict(data, provider=provider)- if provider in _SPECIAL_PROVIDER_VALIDATORS:- return await _SPECIAL_PROVIDER_VALIDATORS[provider](normalized, websocket)-- ai_service = container.ai_service()- auth_service = container.auth_service()- broadcaster = get_status_broadcaster()- api_key = data["api_key"].strip()-- # Fetch models for AI providers (any provider with a models_endpoint in llm_defaults.json)- from services.ai import PROVIDER_CONFIGS- try:- models = await ai_service.fetch_models(provider, api_key) if provider in PROVIDER_CONFIGS else []- except httpx.HTTPStatusError as e:- status = e.response.status_code- if status in (401, 403):- msg = "Invalid API key"- elif status == 429:- msg = "Rate limited by provider — try again in a moment"- elif 500 <= status < 600:- msg = f"Provider error ({status}) — try again later"- else:- msg = f"Provider rejected the key ({status})"- logger.warning("API key validation failed for %s: HTTP %s", provider, status)- await broadcaster.update_api_key_status(- provider=provider, valid=False, message=msg, has_key=False, models=[]- )- return {"provider": provider, "valid": False, "message": msg, "timestamp": time.time()}- except (httpx.TimeoutException, httpx.RequestError) as e:- # DNS, connect, read timeouts — the provider is unreachable.- logger.warning("API key validation could not reach %s: %s", provider, e)- msg = "Could not reach provider — check your network and try again"- await broadcaster.update_api_key_status(- provider=provider, valid=False, message=msg, has_key=False, models=[]- )- return {"provider": provider, "valid": False, "message": msg, "timestamp": time.time()}-- await auth_service.store_api_key(provider=provider, api_key=api_key, models=models,- session_id=data.get("session_id", "default"))- # Broadcast with hasKey and models so frontend can update reactively- await broadcaster.update_api_key_status(- provider=provider, valid=True, message="API key validated",- has_key=True, models=models- )- return {"provider": provider, "valid": True, "models": models, "timestamp": time.time()}+ cred_cls = CREDENTIAL_REGISTRY.get(provider)+ if cred_cls is None:+ return {+ "success": False,+ "valid": False,+ "error": f"Unknown provider '{provider}' — no Credential class registered.",+ }+ return await cred_cls.validate(normalized)@ws_handler("provider")@@ -1929,168 +1892,15 @@ async def handle_android_relay_reconnect(data: Dict[str, Any], websocket: WebSocreturn {"success": False, "error": str(e)}-# ============================================================================-# Maps Handlers-# ============================================================================--async def handle_validate_maps_key(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:- """Validate Google Maps API key and save to database if valid."""- import httpx- broadcaster = get_status_broadcaster()- auth_service = container.auth_service()-- api_key = data.get("api_key", "").strip()- session_id = data.get("session_id", "default")-- if not api_key:- return {"success": False, "valid": False, "error": "api_key required"}-- try:- # Test the API key with a simple geocoding request- async with httpx.AsyncClient() as client:- response = await client.get(- "https://maps.googleapis.com/maps/api/geocode/json",- params={- "address": "1600 Amphitheatre Parkway, Mountain View, CA",- "key": api_key- },- timeout=10.0- )-- response_data = response.json()-- if response_data.get("status") == "OK":- # Save the validated key to database- await auth_service.store_api_key(- provider="google_maps",- api_key=api_key,- models=[],- session_id=session_id- )- await broadcaster.update_api_key_status(- provider="google_maps",- valid=True,- message="API key validated successfully"- )- return {"success": True, "valid": True, "message": "Google Maps API key is valid"}-- elif response_data.get("status") == "REQUEST_DENIED":- error_msg = response_data.get("error_message", "Invalid API key")- await broadcaster.update_api_key_status(- provider="google_maps",- valid=False,- message=error_msg- )- return {"success": True, "valid": False, "message": error_msg}-- else:- # Other statuses like ZERO_RESULTS still mean the key works- # Save the validated key to database- await auth_service.store_api_key(- provider="google_maps",- api_key=api_key,- models=[],- session_id=session_id- )- await broadcaster.update_api_key_status(- provider="google_maps",- valid=True,- message="API key validated"- )- return {"success": True, "valid": True, "message": f"API key is valid (status: {response_data.get('status')})"}-- except httpx.TimeoutException:- await broadcaster.update_api_key_status(- provider="google_maps",- valid=False,- message="Validation request timed out"- )- return {"success": False, "valid": False, "error": "Validation request timed out"}-- except Exception as e:- logger.error("Maps key validation failed", error=str(e))- await broadcaster.update_api_key_status(- provider="google_maps",- valid=False,- message=str(e)- )- return {"success": False, "valid": False, "error": str(e)}---# ============================================================================-# Apify Handlers-# ============================================================================--async def handle_validate_apify_key(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:- """Validate Apify API token and save to database if valid."""- from nodes.scraper.apify_actor import validate_apify_token-- broadcaster = get_status_broadcaster()- auth_service = container.auth_service()-- api_key = data.get("api_key", "").strip()- session_id = data.get("session_id", "default")-- if not api_key:- return {"success": False, "valid": False, "error": "api_key required"}-- try:- result = await validate_apify_token(api_key)-- if result.get("valid"):- # Save the validated key to database- await auth_service.store_api_key(- provider="apify",- api_key=api_key,- models=[],- session_id=session_id- )- await broadcaster.update_api_key_status(- provider="apify",- valid=True,- message=f"Apify token validated - user: {result.get('username', 'unknown')}"- )- return {- "success": True,- "valid": True,- "message": "Apify API token is valid",- "username": result.get("username"),- "email": result.get("email"),- "plan": result.get("plan")- }- else:- error_msg = result.get("error", "Invalid API token")- await broadcaster.update_api_key_status(- provider="apify",- valid=False,- message=error_msg- )- return {"success": True, "valid": False, "message": error_msg}-- except Exception as e:- logger.error("Apify key validation failed", error=str(e))- await broadcaster.update_api_key_status(- provider="apify",- valid=False,- message=str(e)- )- return {"success": False, "valid": False, "error": str(e)}---# Per-provider validation strategies. Register any non-LLM provider here-# and `handle_validate_api_key` will dispatch to it automatically, so the-# frontend only ever calls one WS message type. Local-LLM validators-# live in their plugin folder (see `nodes/model/_local_validator.py`)-# so all per-provider behaviour for ollama/lmstudio stays in `nodes/model/`.-from nodes.model._local_validator import validate_local_llm as _validate_local_llm--_SPECIAL_PROVIDER_VALIDATORS = {- "google_maps": handle_validate_maps_key,- "apify": handle_validate_apify_key,- "ollama": _validate_local_llm,- "lmstudio": _validate_local_llm,-}+# ----------------------------------------------------------------------------+# Per-provider credential validators (Maps geocode probe, Apify /users/me,+# Ollama / LM Studio SDK probes) live on their plugins Credential+# subclass via the shared Credential._probe / Credential.validate scaffold+# in services/plugin/credential.py. handle_validate_api_key (above) is a+# pure dispatch through CREDENTIAL_REGISTRY no per-provider branches in+# this router.+# ----------------------------------------------------------------------------# ============================================================================# WhatsApp Handlers - Wrappers for services.whatsapp_service functions@@ -3451,11 +3261,12 @@ MESSAGE_HANDLERS: Dict[str, MessageHandler] = {"android_relay_disconnect": handle_android_relay_disconnect,"android_relay_reconnect": handle_android_relay_reconnect,- # Maps operations- "validate_maps_key": handle_validate_maps_key,-- # Apify operations- "validate_apify_key": handle_validate_apify_key,+ # Maps + Apify validation now flow through ``handle_validate_api_key``+ # (which dispatches via ``CREDENTIAL_REGISTRY`` to+ # ``GoogleMapsCredential._probe`` / ``ApifyCredential._probe``).+ # The legacy ``validate_maps_key`` / ``validate_apify_key`` WS message+ # types are no longer needed — the frontend already uses+ # ``validate_api_key`` for all providers.# WhatsApp operations"whatsapp_status": handle_whatsapp_status,diff --git a/server/services/plugin/credential.py b/server/services/plugin/credential.pyindex eec9f361..8a49e5a5 100644--- a/server/services/plugin/credential.py+++ b/server/services/plugin/credential.py@@ -13,16 +13,134 @@ Two concrete bases:Both are discovered at import time via :data:`CREDENTIAL_REGISTRY`(populated by ``__init_subclass__``). Nothing else needs to wire them.++Validation is also a base-class concern. Every "validate this key"+flow shares the same wiring (read api_key + session_id from request,+call provider probe, store on success, broadcast status, return+envelope). Only the probe itself varies. That common scaffold lives on+:meth:`Credential.validate`; subclasses override the lighter+:meth:`Credential._probe` to supply the per-provider call. See+:class:`ProbeResult` for the typed return shape."""from __future__ import annotations-from typing import Any, ClassVar, Dict, Literal, Optional, Sequence+import logging+import time+from dataclasses import dataclass, field+from typing import Any, ClassVar, Dict, List, Literal, Optional, Sequence++import httpx++logger = logging.getLogger(__name__)CREDENTIAL_REGISTRY: Dict[str, type] = {}+@dataclass+class ProbeResult:+ """Outcome of a per-provider validation probe.++ Carries the common ``valid`` / ``message`` flags every validator+ returns, plus optional fields a few providers extend with+ (``models`` for LLM ``/v1/models`` lists, ``model_params`` for+ Ollama / LM Studio per-model context, ``extra`` for+ provider-specific extensions like Apify's ``username`` / ``email``+ / ``plan``). The base ``Credential.validate`` reads these fields+ when wiring storage / broadcast / response envelope so subclasses+ don't repeat any of that scaffolding.+ """++ valid: bool+ message: str = ""+ models: List[str] = field(default_factory=list)+ model_params: Optional[Dict[str, Dict[str, Any]]] = None+ # Free-form passthrough fields for provider-specific extensions+ # (Apify returns username / email / plan; Twitter returns user id;+ # Maps returns nothing). Merged into the response envelope.+ extra: Dict[str, Any] = field(default_factory=dict)+++def classify_credential_error(+ exc: BaseException, *, display_name: str+) -> ProbeResult:+ """Map a transport / SDK exception to a typed ``ProbeResult``.++ Single source of truth for credential-error → user-message mapping.+ Used by the base ``Credential.validate`` after a ``_probe`` call+ raises, and by the local-LLM probe directly. Catches the documented+ ``httpx`` / ``openai`` exception hierarchy so operator logs see+ "HTTP 401" / "connect-refused" / "timeout" instead of an opaque+ repr.++ Returns a ``ProbeResult(valid=False, message=...)`` carrying the+ user-facing string. Operator logs are emitted at WARN by the+ caller — this helper just classifies, doesn't log.+ """+ import openai # local import: openai is a heavy SDK++ if isinstance(exc, httpx.TimeoutException) or isinstance(exc, openai.APITimeoutError):+ return ProbeResult(+ valid=False,+ message=f"Request to {display_name} timed out — try again or check the network.",+ )++ if isinstance(exc, httpx.ConnectError) or isinstance(exc, openai.APIConnectionError):+ return ProbeResult(+ valid=False,+ message=f"Could not reach {display_name}. Is the server running?",+ )++ if isinstance(exc, httpx.HTTPStatusError):+ status = exc.response.status_code+ return _classify_status(status, display_name)++ if isinstance(exc, openai.AuthenticationError):+ return _classify_status(401, display_name)+ if isinstance(exc, openai.PermissionDeniedError):+ return _classify_status(403, display_name)+ if isinstance(exc, openai.NotFoundError):+ return _classify_status(404, display_name)+ if isinstance(exc, openai.RateLimitError):+ return _classify_status(429, display_name)+ if isinstance(exc, openai.APIStatusError):+ status = getattr(getattr(exc, "response", None), "status_code", 500)+ return _classify_status(status, display_name)++ # Unknown exception: surface the type name so the operator log line+ # is still useful, but don't dump a stacktrace into the user's toast.+ return ProbeResult(+ valid=False,+ message=f"Could not validate {display_name}: {type(exc).__name__}: {exc}",+ )+++def _classify_status(status: int, display_name: str) -> ProbeResult:+ """Map an HTTP status code to a user-facing message."""+ if status in (401, 403):+ return ProbeResult(valid=False, message=f"{display_name} rejected the API key.")+ if status == 404:+ return ProbeResult(+ valid=False,+ message=f"{display_name} returned 404 — endpoint not found. Check the URL.",+ )+ if status == 429:+ return ProbeResult(+ valid=False,+ message=f"{display_name} rate-limited the request — try again shortly.",+ )+ if 500 <= status < 600:+ return ProbeResult(+ valid=False,+ message=f"{display_name} returned HTTP {status} — try again later.",+ )+ return ProbeResult(+ valid=False,+ message=f"{display_name} returned HTTP {status}.",+ )++class Credential:"""Base class for provider credentials.@@ -73,6 +191,105 @@ class Credential:"""return request+ # ---- Validation -------------------------------------------------+ #+ # Every "validate this credential" flow follows the same wiring:+ # read api_key + session_id from the request, run a per-provider+ # probe, store on success, broadcast status, return the standard+ # response envelope. Only the probe call genuinely varies — so the+ # scaffolding lives on the base and subclasses override the lighter+ # :meth:`_probe` hook. The dispatch entry point (called by the WS+ # router) is :meth:`validate`; subclasses with non-standard+ # side-effect ordering (e.g. local-LLM credentials store under TWO+ # keys) override :meth:`validate` directly.++ @classmethod+ async def validate(cls, data: Dict[str, Any]) -> Dict[str, Any]:+ """Run the credential validation probe and wire side effects.++ The shared scaffold:+ 1. Read ``api_key`` + ``session_id`` from the request data.+ 2. Guard: missing key → fast-fail envelope.+ 3. Call :meth:`_probe` (subclass-supplied; provider-specific).+ 4. On exception, classify via :func:`classify_credential_error`.+ 5. On valid result, persist via ``auth_service.store_api_key``.+ 6. Broadcast the new status via+ ``StatusBroadcaster.update_api_key_status`` (always — invalid+ results clear stale state on connected clients).+ 7. Return the standard response envelope.++ Subclasses with non-standard storage / broadcast (e.g. local-LLM+ credentials that store both URL and placeholder key) override+ this method directly.+ """+ from core.container import container+ from services.status_broadcaster import get_status_broadcaster++ api_key = (data.get("api_key") or "").strip()+ session_id = data.get("session_id", "default")+ if not api_key:+ return {+ "success": False,+ "valid": False,+ "error": f"{cls.id} api_key required",+ }++ try:+ result = await cls._probe(api_key)+ except Exception as exc: # noqa: BLE001 — classified below+ display = cls.display_name or cls.id+ result = classify_credential_error(exc, display_name=display)+ logger.warning(+ "[%s] credential probe failed: %s",+ cls.id,+ result.message,+ )++ broadcaster = get_status_broadcaster()+ auth_service = container.auth_service()++ if result.valid:+ await auth_service.store_api_key(+ provider=cls.id,+ api_key=api_key,+ models=result.models,+ session_id=session_id,+ model_params=result.model_params,+ )++ await broadcaster.update_api_key_status(+ provider=cls.id,+ valid=result.valid,+ message=result.message,+ has_key=result.valid,+ models=result.models,+ )++ return {+ "success": True,+ "provider": cls.id,+ "valid": result.valid,+ "message": result.message,+ "models": result.models,+ "timestamp": time.time(),+ **result.extra,+ }++ @classmethod+ async def _probe(cls, api_key: str) -> ProbeResult:+ """Run the per-provider validation probe.++ Subclass override point — the probe MUST NOT do storage,+ broadcasts, or registry mutation. It returns a+ :class:`ProbeResult` describing what the upstream returned;+ :meth:`validate` does the rest. Raise ``httpx.*`` /+ ``openai.OpenAIError`` to let the base map them to a typed+ message via :func:`classify_credential_error`.+ """+ raise NotImplementedError(+ f"Credential subclass {cls.__name__} must override _probe()"+ )+class OAuth2Credential(Credential):"""OAuth 2.0 with refresh-token support.diff --git a/server/services/ws_handler_registry.py b/server/services/ws_handler_registry.pyindex c314ea4b..48d882fb 100644--- a/server/services/ws_handler_registry.py+++ b/server/services/ws_handler_registry.py@@ -1,33 +1,40 @@-"""WebSocket handler registry for plugin-owned messages.+"""Plugin self-registration registries.-Mirrors the pattern used by :data:`services.node_registry._HANDLER_REGISTRY`-(plugin nodes self-register via ``BaseNode.__init_subclass__``) but for-side-channel WebSocket commands like ``telegram_connect``,-``whatsapp_status``, etc.+Two sibling concerns share this file because they're the same pattern+(idempotent dict + collision check) for the same audience (plugin+``__init__.py`` modules wiring themselves into the framework):-Each ``nodes/<group>/__init__.py`` calls :func:`register_ws_handlers`-with a dict of ``message_type -> async handler``; the central WebSocket-router reads :func:`get_ws_handlers` at dispatch time and merges the-result into its own legacy ``MESSAGE_HANDLERS`` table.+1. **WebSocket handlers** — ``register_ws_handlers({type: handler})``+ for side-channel commands like ``telegram_connect``,+ ``whatsapp_status``. Read by ``routers/websocket.py`` at dispatch+ time and merged into ``MESSAGE_HANDLERS``.-No hardcoded plugin names anywhere in the router. Adding a new-plugin's WS surface is a one-line registration call inside that-plugin's package.+2. **HTTP routers** — ``register_router(APIRouter, name="<plugin>")``+ for plugin-owned routes (OAuth callbacks, webhook receivers,+ direct-API endpoints). Read by ``server.main`` after plugin discovery+ and ``app.include_router(...)``'d.++No hardcoded plugin names anywhere in the central router or main.py.+Adding a new plugin's WS / HTTP surface is one registration call inside+that plugin's package."""from __future__ import annotationsimport logging-from typing import Any, Awaitable, Callable, Dict+from typing import Any, Awaitable, Callable, Dict, List-from fastapi import WebSocket+from fastapi import APIRouter, WebSocketlogger = logging.getLogger(__name__)WSHandler = Callable[[Dict[str, Any], WebSocket], Awaitable[Dict[str, Any]]]-_REGISTRY: Dict[str, WSHandler] = {}+_WS_REGISTRY: Dict[str, WSHandler] = {}+_ROUTER_REGISTRY: Dict[str, APIRouter] = {}++# ---- WebSocket handlers --------------------------------------------------def register_ws_handlers(handlers: Dict[str, WSHandler]) -> None:"""Publish a batch of ``message_type -> handler`` mappings.@@ -37,14 +44,14 @@ def register_ws_handlers(handlers: Dict[str, WSHandler]) -> None:``ValueError`` to surface plugin namespace collisions early."""for msg_type, handler in handlers.items():- existing = _REGISTRY.get(msg_type)+ existing = _WS_REGISTRY.get(msg_type)if existing is not None and existing is not handler:raise ValueError(f"WS handler for message_type '{msg_type}' is already registered "f"by {existing.__module__}.{existing.__qualname__}; refusing to "f"overwrite with {handler.__module__}.{handler.__qualname__}")- _REGISTRY[msg_type] = handler+ _WS_REGISTRY[msg_type] = handlerdef get_ws_handlers() -> Dict[str, WSHandler]:@@ -53,9 +60,39 @@ def get_ws_handlers() -> Dict[str, WSHandler]:Returns a fresh dict so callers can mutate without affecting theregistry (e.g. ``MESSAGE_HANDLERS = {**core, **get_ws_handlers()}``)."""- return dict(_REGISTRY)+ return dict(_WS_REGISTRY)def list_registered_types() -> list[str]:"""For diagnostics / startup logging."""- return sorted(_REGISTRY.keys())+ return sorted(_WS_REGISTRY.keys())+++# ---- HTTP routers --------------------------------------------------------++def register_router(router: APIRouter, *, name: str) -> None:+ """Publish a plugin-owned ``APIRouter`` for inclusion at app startup.++ ``name`` is the plugin folder name — used for diagnostics and+ collision detection. Same idempotency contract as the WS side: the+ same router for the same name is a no-op; a different router for an+ existing name raises ``ValueError`` so plugin-name collisions fail+ at import time, not request time.+ """+ existing = _ROUTER_REGISTRY.get(name)+ if existing is not None and existing is not router:+ raise ValueError(+ f"Router for '{name}' is already registered; two plugin folders "+ f"cannot claim the same name."+ )+ _ROUTER_REGISTRY[name] = router+++def get_routers() -> List[APIRouter]:+ """Snapshot of registered routers in registration order."""+ return list(_ROUTER_REGISTRY.values())+++def list_registered_routers() -> List[str]:+ """For diagnostics / startup logging."""+ return sorted(_ROUTER_REGISTRY.keys())diff --git a/server/tests/credentials/test_credential_broadcasts.py b/server/tests/credentials/test_credential_broadcasts.pyindex 0624ed65..51ca21e6 100644--- a/server/tests/credentials/test_credential_broadcasts.py+++ b/server/tests/credentials/test_credential_broadcasts.py@@ -57,13 +57,20 @@ class TestCredentialMutationHandlersBroadcast:"""def test_validate_api_key_broadcasts(self):- """Sanity — already correct path; confirms the matcher works."""- from routers import websocket as ws_module+ """Validation broadcasts come from ``Credential.validate`` now.++ ``handle_validate_api_key`` is a pure dispatcher that calls+ ``CREDENTIAL_REGISTRY[provider].validate(...)``. The broadcast+ happens inside ``Credential.validate`` (the shared scaffold in+ ``services/plugin/credential.py``). This test checks the+ invariant at the point where it actually lives.+ """+ from services.plugin.credential import Credential- src = _handler_source(ws_module.handle_validate_api_key)+ src = inspect.getsource(Credential.validate)assert _BROADCAST_PATTERN.search(src), (- "handle_validate_api_key must broadcast api_key_status "- "or credential_catalogue_updated"+ "Credential.validate must broadcast via update_api_key_status — "+ "every credential mutation must surface to connected clients.")def test_save_api_key_broadcasts(self):diff --git a/server/tests/credentials/test_websocket_handlers.py b/server/tests/credentials/test_websocket_handlers.pyindex b6e2f27c..d2828275 100644--- a/server/tests/credentials/test_websocket_handlers.py+++ b/server/tests/credentials/test_websocket_handlers.py@@ -114,22 +114,23 @@ class TestValidateApiKey:# Broadcaster notified with hasKey + modelspatched_container.broadcaster.update_api_key_status.assert_awaited_once()- @patch("services.ai.PROVIDER_CONFIGS", {})- @patch.object(ws_module, "_SPECIAL_PROVIDER_VALIDATORS", {})- async def test_validate_skips_model_fetch_for_non_llm(+ async def test_validate_unknown_provider_returns_error(self, patched_container, fake_ws):- # Pick a provider that's neither in PROVIDER_CONFIGS (LLM) nor in- # _SPECIAL_PROVIDER_VALIDATORS (Google Maps / Apify probe). The- # handler should fall through to the empty-models path.+ # ``handle_validate_api_key`` dispatches via+ # ``CREDENTIAL_REGISTRY``; a provider without a registered+ # ``Credential`` subclass is an explicit error (no fall-through+ # to the default LLM probe — every supported provider must own+ # its credential class).result = await _call(ws_module.handle_validate_api_key,{"provider": "anonymous_provider", "api_key": "any-test"},fake_ws,)- assert result["valid"] is True- assert result["models"] == []+ assert result["success"] is False+ assert result["valid"] is False+ assert "anonymous_provider" in result["error"]patched_container.ai.fetch_models.assert_not_called()async def test_missing_required_fields_returns_error(