Skip to content

armgit / ODS

Public Imported from GitHub
0

ODS V3 Pre-Release: Public testing and refinement ahead of the official V3 launch. Turn your PC, Mac, or Linux box into a private AI server.

39.0 KB
Raw Blame
"""Shared configuration and manifest loading for ODS Dashboard API."""

import json
import logging
import os
import re
from pathlib import Path
from typing import Any, Mapping
from urllib.parse import urlparse

import yaml

from env_values import parse_env_value

logger = logging.getLogger(__name__)

# --- Paths ---

INSTALL_DIR = os.environ.get("ODS_INSTALL_DIR", os.path.expanduser("~/ods"))
DATA_DIR = os.environ.get("ODS_DATA_DIR", os.path.expanduser("~/.ods"))
EXTENSIONS_DIR = Path(
    os.environ.get(
        "ODS_EXTENSIONS_DIR",
        str(Path(INSTALL_DIR) / "extensions" / "services")
    )
)

DEFAULT_SERVICE_HOST = os.environ.get("SERVICE_HOST", "host.docker.internal")
GPU_BACKEND = os.environ.get("GPU_BACKEND", "nvidia")
ODS_MODES = frozenset({"local", "cloud", "hybrid"})
LOCAL_MODEL_MODES = frozenset({"local", "hybrid"})
# Readable for one release: managed AMD installs written before round F name
# the retired Lemonade mode until the installer migrates their .env.
LEGACY_ODS_MODES = {"lemonade": "local"}
LLM_CONTRACT_ROUTES = frozenset({"gateway", "direct"})
LLM_CONTRACT_PINNING = frozenset({"none", "dynamic"})


def normalize_ods_mode(value: Any) -> str:
    """Return a supported ODS mode or ``unknown`` for missing/invalid input."""
    mode = str(value or "").strip().lower()
    mode = LEGACY_ODS_MODES.get(mode, mode)
    return mode if mode in ODS_MODES else "unknown"


def normalize_llm_backend(value: Any) -> str:
    """Every managed runtime is llama-server; ``lemonade`` reads as it for one release."""
    backend = str(value or "").strip().lower()
    return "llama-server" if backend == "lemonade" else backend


def normalize_llm_contract(value: Any) -> dict[str, Any] | None:
    """Normalize a manifest ``llm`` contract for API and harness consumers."""
    if not isinstance(value, dict):
        return None

    consumes = bool(value.get("consumes", False))
    route = str(value.get("route") or "").strip().lower()
    pinning = str(value.get("pinning") or "").strip().lower()
    if route not in LLM_CONTRACT_ROUTES:
        route = "direct" if consumes else ""
    if pinning not in LLM_CONTRACT_PINNING:
        pinning = "none"

    normalized: dict[str, Any] = {
        "consumes": consumes,
        "route": route,
        "pinning": pinning,
    }

    min_context = value.get("min_context")
    if min_context is not None:
        try:
            normalized["min_context"] = max(0, int(min_context))
        except (TypeError, ValueError):
            logger.warning("Ignoring invalid llm.min_context value: %r", min_context)

    probe = value.get("probe")
    if isinstance(probe, dict):
        normalized["probe"] = probe.copy()

    swap_safe = bool(consumes and (route == "gateway" or pinning == "dynamic"))
    normalized["swap_safe"] = swap_safe
    # camelCase alias: the fleet model-ui harness gates required probes on llm.swapSafe
    normalized["swapSafe"] = swap_safe
    normalized["badge"] = "swap-safe" if swap_safe else "not-swap-safe"
    if not consumes:
        normalized["swap_safe_reason"] = "This service does not declare LLM inference consumption."
    elif route == "gateway":
        normalized["swap_safe_reason"] = "Routes through the ODS gateway alias and follows model swaps automatically."
    elif pinning == "dynamic":
        normalized["swap_safe_reason"] = "Declares a dynamic model refresh path and is re-probed after swaps."
    else:
        normalized["swap_safe_reason"] = "Direct model route without a declared refresh path; swaps may require reconciliation."

    return normalized


# This is the mode of the running dashboard-api container. Unlike the mounted
# .env file, the process environment is fixed until the service is recreated.
ODS_MODE_EFFECTIVE = normalize_ods_mode(os.environ.get("ODS_MODE"))


_ENV_FILE_PERMISSION_ERROR: str | None = None
_ENV_FILE_PERMISSION_ERROR_LOGGED: bool = False


def get_env_file_read_error() -> str | None:
    """Return the last permission error encountered when reading .env, if any."""
    return _ENV_FILE_PERMISSION_ERROR


def _reset_env_permission_state() -> None:
    global _ENV_FILE_PERMISSION_ERROR, _ENV_FILE_PERMISSION_ERROR_LOGGED
    _ENV_FILE_PERMISSION_ERROR = None
    _ENV_FILE_PERMISSION_ERROR_LOGGED = False


def _handle_env_permission_error(
    env_path: Path, key_or_keys: Any, exc: PermissionError
) -> None:
    global _ENV_FILE_PERMISSION_ERROR, _ENV_FILE_PERMISSION_ERROR_LOGGED
    _ENV_FILE_PERMISSION_ERROR = (
        f"Permission denied reading {env_path}; live settings may be unavailable"
    )
    if not _ENV_FILE_PERMISSION_ERROR_LOGGED:
        logger.warning(
            "Permission denied reading environment file %s for %s: %s",
            env_path,
            key_or_keys,
            exc,
        )
        _ENV_FILE_PERMISSION_ERROR_LOGGED = True


def _handle_env_read_success(env_path: Path) -> None:
    global _ENV_FILE_PERMISSION_ERROR, _ENV_FILE_PERMISSION_ERROR_LOGGED
    if _ENV_FILE_PERMISSION_ERROR_LOGGED or _ENV_FILE_PERMISSION_ERROR is not None:
        logger.info(
            "Successfully read environment file %s; cleared previous permission error",
            env_path,
        )
    _ENV_FILE_PERMISSION_ERROR = None
    _ENV_FILE_PERMISSION_ERROR_LOGGED = False


def _find_env_file_value(key: str) -> tuple[bool, str]:
    """Return the last persisted value and distinguish missing from empty."""
    env_path = Path(INSTALL_DIR) / ".env"
    found = False
    value = ""
    try:
        lines = env_path.read_text(encoding="utf-8").splitlines()
        _handle_env_read_success(env_path)
        for line in lines:
            if line.startswith(f"{key}="):
                found = True
                value = parse_env_value(line.split("=", 1)[1])
    except PermissionError as exc:
        _handle_env_permission_error(env_path, f"key {key}", exc)
    except FileNotFoundError:
        _reset_env_permission_state()
    except (OSError, UnicodeError):
        pass
    return found, value


def _read_env_from_file(key: str) -> str:
    """Read a variable from the persisted .env file."""
    return _find_env_file_value(key)[1]


def read_live_env_value(key: str, default: str = "") -> str:
    """Read mutable ODS state from the mounted .env before process startup env."""
    found, value = _find_env_file_value(key)
    if found:
        return value
    return os.environ.get(key, "") or default


def read_live_env_values(keys: tuple[str, ...]) -> dict[str, str]:
    """Read one persisted snapshot so a route and its credential cannot diverge."""
    values = {key: os.environ.get(key, "") for key in keys}
    env_path = Path(INSTALL_DIR) / ".env"
    try:
        text = env_path.read_text(encoding="utf-8")
        _handle_env_read_success(env_path)
    except PermissionError as exc:
        _handle_env_permission_error(env_path, f"keys {keys}", exc)
        return values
    except FileNotFoundError:
        _reset_env_permission_state()
        return values
    except (OSError, UnicodeError):
        return values
    for line in text.splitlines():
        key, separator, raw = line.partition("=")
        if separator and key in values:
            values[key] = parse_env_value(raw)
    return values


def _apply_host_native_llm_service_override(
    services: dict[str, dict[str, Any]],
    gpu_backend: str,
    environment: Mapping[str, str] | None = None,
) -> None:
    """Route probes to native inference rather than the container's default port."""
    env = environment if environment is not None else os.environ
    if str(gpu_backend).lower() == "apple":
        service = services.get("llama-server")
        if not service or str(env.get("LLM_BACKEND", "")).lower() == "external":
            return
        # The macOS overlay supplies the Docker-reachable native endpoint.
        # Do not substitute a general model-router/LiteLLM URL here.
        configured_url = env.get("OLLAMA_URL", "")
        if not configured_url:
            return
        try:
            parsed = urlparse(configured_url)
            port = parsed.port if parsed.port is not None else 80
            if (parsed.scheme != "http" or not parsed.hostname
                    or parsed.username is not None or parsed.password is not None
                    or parsed.query or parsed.fragment or not 1 <= port <= 65535):
                return
        except ValueError:
            return
        service["host"] = parsed.hostname
        service["port"] = port
        return
    # A llama-server.exe on the Windows host: the legacy native flow (AMD), or
    # the WSL Portal (whose WSL side may see no GPU) through host.docker.internal.
    if str(gpu_backend).lower() not in {"amd", "cpu"}:
        return
    if str(env.get("AMD_INFERENCE_LOCATION", "")).strip().lower() != "host":
        return
    if str(env.get("LLM_BACKEND", "")).strip().lower() == "external":
        return
    service = services.get("llama-server")
    if not service:
        return

    # The generic LLM URL can be LiteLLM. Its model aliases do not identify
    # the served model; probe the server's own container-visible origin.
    # LEMONADE_CONTAINER_BASE_URL is that origin's one-release legacy name.
    generic_url = str(env.get("LLM_API_URL") or "")
    configured_url = (
        env.get("NATIVE_LLM_CONTAINER_BASE_URL")
        or env.get("LEMONADE_CONTAINER_BASE_URL")
        or env.get("OLLAMA_URL")
        or env.get("LLM_URL")
        or (generic_url if "litellm" not in generic_url.lower() else "")
        or f"http://host.docker.internal:{env.get('AMD_INFERENCE_PORT', '8080')}"
    )
    parsed = urlparse(str(configured_url).strip())
    if not parsed.hostname:
        logger.warning("Ignoring invalid host-native LLM URL: %s", configured_url)
        return
    try:
        port = parsed.port or int(env.get("AMD_INFERENCE_PORT", "8080"))
    except ValueError:
        logger.warning("Ignoring invalid host-native LLM port in URL: %s", configured_url)
        return

    service["host"] = parsed.hostname
    service["port"] = port
    # The in-stack container is off on this route; its sidebar link (OLLAMA_PORT, 11434) opened an error page.
    service["external_link"] = False
    logger.info("Host-native llama-server detected; routing LLM probes to %s:%d", parsed.hostname, port)


def _apply_external_llm_service_override(
    services: dict[str, dict[str, Any]],
    environment: Mapping[str, str] | None = None,
) -> None:
    """Route dashboard LLM probes to a validated external Ollama/LM Studio endpoint."""
    env = environment if environment is not None else os.environ
    if str(env.get("LLM_BACKEND", "")).strip().lower() != "external":
        return
    service = services.get("llama-server")
    if not service:
        return

    configured_url = (
        env.get("EXTERNAL_LLM_CONTAINER_URL")
        or env.get("LLM_API_URL")
        or ""
    )
    parsed = urlparse(str(configured_url).strip())
    if parsed.scheme not in {"http", "https"} or not parsed.hostname:
        logger.warning("Ignoring invalid external LLM URL: %s", configured_url)
        return
    try:
        port = parsed.port or (443 if parsed.scheme == "https" else 80)
    except ValueError:
        logger.warning("Ignoring invalid external LLM port in URL: %s", configured_url)
        return

    provider = str(env.get("EXTERNAL_LLM_PROVIDER", "")).strip().lower()
    health_paths = {
        "ollama": "/api/tags",
        "lmstudio": "/v1/models",
    }
    service["host"] = parsed.hostname
    service["port"] = port
    # The health probe reaches the API with its own scheme and Host header;
    # an HTTPS API answered the old http://host:443 probe with an error.
    service["scheme"] = parsed.scheme
    service["external_api"] = True
    service["health"] = health_paths.get(provider, "/v1/models")
    service["name"] = {
        "ollama": "Ollama (External LLM)",
        "lmstudio": "LM Studio (External LLM)",
    }.get(provider, "External LLM")
    logger.info(
        "External %s inference detected; routing LLM probes to %s:%d%s",
        provider or "OpenAI-compatible",
        parsed.hostname,
        port,
        service["health"],
    )


VLLM_SERVICE_HOST = "vllm-server"
VLLM_SERVICE_PORT = 8000
VLLM_CONTAINER = "ods-vllm-server"


def _apply_vllm_service_override(
    services: dict[str, dict[str, Any]],
    environment: Mapping[str, str] | None = None,
) -> None:
    """Route the LLM row's probes to the vLLM engine (LLM_BACKEND=vllm).

    docker-compose.vllm.yml profiles the in-stack llama-server out and runs
    vllm-server on the ODS network: /health answers 200 with an empty body once
    the model is loaded, /v1/models lists the served id. As for a host-native
    or external route, the row keeps the llama-server id that chat, readiness
    and features key on; its container is ods-vllm-server, which the host
    agent's Docker health snapshot reports (a cold start reads as starting),
    and it publishes no host port to link to.
    """
    env = environment if environment is not None else os.environ
    if str(env.get("LLM_BACKEND", "")).strip().lower() != "vllm":
        return
    service = services.get("llama-server")
    if not service:
        return
    service["host"] = VLLM_SERVICE_HOST
    service["port"] = VLLM_SERVICE_PORT
    service["health"] = "/health"
    service["container_name"] = VLLM_CONTAINER
    service["name"] = "vLLM (LLM Inference)"
    service["external_link"] = False
    logger.info("vLLM engine selected; routing LLM probes to %s:%d", VLLM_SERVICE_HOST, VLLM_SERVICE_PORT)


def _read_env_value(key: str) -> str:
    return (os.environ.get(key) or _read_env_from_file(key)).strip()


def _service_public_url_key(service_id: str) -> str:
    return re.sub(r"[^A-Za-z0-9]+", "_", service_id).strip("_").upper()


def _valid_public_url(value: str) -> str:
    candidate = value.strip().rstrip("/")
    if not candidate:
        return ""
    parsed = urlparse(candidate)
    if parsed.scheme not in {"http", "https"} or not parsed.netloc:
        logger.warning("Ignoring invalid public service URL: %s", value)
        return ""
    return candidate


def _read_service_public_url_map() -> dict[str, str]:
    raw = _read_env_value("ODS_SERVICE_PUBLIC_URLS")
    if not raw:
        return {}
    try:
        data = json.loads(raw)
    except json.JSONDecodeError:
        logger.warning("Ignoring invalid ODS_SERVICE_PUBLIC_URLS JSON")
        return {}
    if not isinstance(data, dict):
        logger.warning("Ignoring ODS_SERVICE_PUBLIC_URLS because it is not a JSON object")
        return {}
    return {
        str(key): _valid_public_url(str(value))
        for key, value in data.items()
        if str(value).strip()
    }


def _candidate_public_url_env_names(
    service_id: str,
    service: dict[str, Any],
    ext_port_env: str | None,
) -> list[str]:
    service_key = _service_public_url_key(service_id)
    names = [
        service.get("public_url_env", ""),
        f"{service_key}_PUBLIC_URL",
        f"ODS_{service_key}_PUBLIC_URL",
    ]
    if ext_port_env:
        if ext_port_env.endswith("_EXTERNAL_PORT"):
            names.append(f"{ext_port_env.removesuffix('_EXTERNAL_PORT')}_PUBLIC_URL")
        if ext_port_env.endswith("_PORT"):
            names.append(f"{ext_port_env.removesuffix('_PORT')}_PUBLIC_URL")
        names.append(f"{ext_port_env}_PUBLIC_URL")
    return [name for index, name in enumerate(names) if name and name not in names[:index]]


def _resolve_public_service_url(
    service_id: str,
    service: dict[str, Any],
    ext_port_env: str | None,
    public_url_map: dict[str, str],
) -> str:
    service_key = _service_public_url_key(service_id)
    for map_key in (service_id, service_key, service_key.lower()):
        url = public_url_map.get(map_key)
        if url:
            return url
    for env_name in _candidate_public_url_env_names(service_id, service, ext_port_env):
        url = _valid_public_url(_read_env_value(env_name))
        if url:
            return url
    return ""


# --- Manifest Loading ---

MAX_MANIFEST_DEPTH = 32
MAX_MANIFEST_NODES = 10_000
MAX_MANIFEST_BYTES = 1_048_576


class _ManifestLoader(yaml.SafeLoader):
    """Bound composition before recursive parsing or YAML merge expansion."""

    def __init__(self, stream):
        super().__init__(stream)
        self.manifest_depth = -1
        self.manifest_nodes = 0

    def compose_node(self, parent, index):
        self.manifest_depth += 1
        self.manifest_nodes += 1
        try:
            if self.manifest_depth > MAX_MANIFEST_DEPTH:
                raise ValueError(f"Manifest nesting exceeds {MAX_MANIFEST_DEPTH} levels")
            if self.manifest_nodes > MAX_MANIFEST_NODES:
                raise ValueError("Manifest structure exceeds node limit")
            return super().compose_node(parent, index)
        finally:
            self.manifest_depth -= 1


def _validate_yaml_graph(root) -> None:
    # Memoize subtree size and height, counting each alias occurrence toward
    # expanded size without actually expanding it. Validate before constructors
    # flatten merge keys, which can otherwise allocate exponentially many pairs.
    memo = {}
    active = set()

    def visit(node):
        marker = id(node)
        if marker in active:
            raise ValueError("Manifest contains a cyclic structure")
        if marker in memo:
            return memo[marker]
        active.add(marker)
        if isinstance(node, yaml.MappingNode):
            children = (child for pair in node.value for child in pair)
        elif isinstance(node, yaml.SequenceNode):
            children = iter(node.value)
        else:
            children = iter(())
        size, height = 1, 0
        for child in children:
            child_size, child_height = visit(child)
            size += child_size
            height = max(height, child_height + 1)
            if size > MAX_MANIFEST_NODES:
                raise ValueError("Manifest alias expansion exceeds node limit")
            if height > MAX_MANIFEST_DEPTH:
                raise ValueError(f"Manifest nesting exceeds {MAX_MANIFEST_DEPTH} levels")
        active.remove(marker)
        memo[marker] = size, height
        return size, height

    visit(root)


def _validate_manifest_depth(value: Any, *, depth: int = 0, active: set[int] | None = None) -> None:
    """Reject pathological nested or cyclic YAML/JSON structures early."""
    if depth > MAX_MANIFEST_DEPTH:
        raise ValueError(f"Manifest nesting exceeds {MAX_MANIFEST_DEPTH} levels")
    if not isinstance(value, (dict, list)):
        return
    active = active if active is not None else set()
    marker = id(value)
    if marker in active:
        raise ValueError("Manifest contains a cyclic structure")
    active.add(marker)
    try:
        if isinstance(value, dict):
            for key, item in value.items():
                _validate_manifest_depth(key, depth=depth + 1, active=active)
                _validate_manifest_depth(item, depth=depth + 1, active=active)
        else:
            for item in value:
                _validate_manifest_depth(item, depth=depth + 1, active=active)
    finally:
        active.remove(marker)


def _read_manifest_file(path: Path) -> dict[str, Any]:
    """Load a JSON or YAML extension manifest file."""
    with path.open("rb") as stream:
        raw = stream.read(MAX_MANIFEST_BYTES + 1)
    if len(raw) > MAX_MANIFEST_BYTES:
        raise ValueError("Manifest exceeds size limit")
    text = raw.decode("utf-8")
    try:
        if path.suffix.lower() == ".json":
            data = json.loads(text)
        else:
            loader = _ManifestLoader(text)
            try:
                node = loader.get_single_node()
                _validate_yaml_graph(node)
                data = loader.construct_document(node) if node is not None else None
            finally:
                loader.dispose()
    except RecursionError as exc:
        raise ValueError(f"Manifest nesting exceeds {MAX_MANIFEST_DEPTH} levels") from exc
    _validate_manifest_depth(data)
    if not isinstance(data, dict):
        raise ValueError("Manifest root must be an object")
    return data


def load_extension_manifests(
    manifest_dir: Path, gpu_backend: str,
    *, only_service_ids: frozenset[str] | None = None,
) -> tuple[dict[str, dict[str, Any]], list[dict[str, Any]], list[dict[str, str]]]:
    """Load service and feature definitions from extension manifests.

    Returns a 3-tuple: (services, features, errors) where *errors* is a list
    of ``{"file": ..., "error": ...}`` dicts for manifests that failed to load.
    """
    services: dict[str, dict[str, Any]] = {}
    features: list[dict[str, Any]] = []
    errors: list[dict[str, str]] = []
    loaded = 0

    if not manifest_dir.exists():
        logger.info("Extension manifest directory not found: %s", manifest_dir)
        return services, features, errors

    public_url_map = _read_service_public_url_map()

    manifest_files: list[Path] = []
    for item in sorted(manifest_dir.iterdir()):
        if only_service_ids is not None and item.name not in only_service_ids:
            continue
        if item.is_dir():
            for name in ("manifest.yaml", "manifest.yml", "manifest.json"):
                candidate = item / name
                if candidate.exists():
                    manifest_files.append(candidate)
                    break
        elif item.suffix.lower() in (".yaml", ".yml", ".json"):
            manifest_files.append(item)

    for path in manifest_files:
        try:
            # Skip disabled extensions (compose.yaml.disabled convention)
            ext_dir = path.parent
            if (ext_dir / "compose.yaml.disabled").exists() or (ext_dir / "compose.yml.disabled").exists():
                logger.debug("Skipping disabled extension: %s", ext_dir.name)
                continue

            manifest = _read_manifest_file(path)
            if manifest.get("schema_version") != "ods.services.v1":
                logger.warning("Skipping manifest with unsupported schema_version: %s", path)
                errors.append({"file": str(path), "error": "Unsupported schema_version"})
                continue

            service = manifest.get("service")
            if isinstance(service, dict):
                service_id = service.get("id")
                if not service_id:
                    raise ValueError("service.id is required")
                compose_file = str(service.get("compose_file") or "").strip()
                if service.get("type") == "docker" and compose_file:
                    compose_path = ext_dir / compose_file
                    if not compose_path.exists():
                        logger.debug(
                            "Skipping docker service %s because %s is not installed",
                            service_id,
                            compose_path,
                        )
                        continue
                supported = service.get("gpu_backends", ["amd", "nvidia", "apple"])
                if gpu_backend == "apple":
                    if (
                        service.get("type") == "host-systemd"
                        and not service.get("macos_host_supported", False)
                    ):
                        continue  # Linux-only service, not available on macOS
                    # All docker services run on macOS regardless of gpu_backends declaration
                elif gpu_backend not in supported and "all" not in supported:
                    continue

                host_env = service.get("host_env")
                default_host = service.get("default_host", "localhost")
                host = os.environ.get(host_env, default_host) if host_env else default_host

                ext_port_env = service.get("external_port_env")
                ext_port_default = service.get("external_port_default", service.get("port", 0))
                if ext_port_env:
                    val = os.environ.get(ext_port_env) or _read_env_from_file(ext_port_env)
                    external_port = int(val) if val else int(ext_port_default)
                else:
                    external_port = int(ext_port_default)

                public_url = _resolve_public_service_url(service_id, service, ext_port_env, public_url_map)
                service_config = {
                    "host": host,
                    "port": int(service.get("port", 0)),
                    "external_port": external_port,
                    "health": service.get("health", "/health"),
                    "name": service.get("name", service_id),
                    "ui_path": service.get("ui_path", "/"),
                    "public_url": public_url,
                    "external_link": bool(service.get("external_link", True)),
                    "macos_host_supported": bool(service.get("macos_host_supported", False)),
                    "container_name": service.get("container_name", f"ods-{service_id}"),
                    "depends_on": service.get("depends_on", []),
                    "category": service.get("category", "optional"),
                    "host_network": bool(service.get("host_network", False)),
                    "socket_only": bool(service.get("socket_only", False)),
                    "setup_hook": service.get("setup_hook", ""),
                    "hooks": service.get("hooks", {}),
                    "gpu_backends": service.get("gpu_backends", []),
                    **({"type": service["type"]} if "type" in service else {}),
                    **({"health_port": int(service["health_port"])} if "health_port" in service else {}),
                }
                llm_contract = normalize_llm_contract(service.get("llm"))
                if llm_contract is not None:
                    service_config["llm"] = llm_contract
                services[service_id] = service_config

            manifest_features = manifest.get("features", [])
            if isinstance(manifest_features, list):
                for feature in manifest_features:
                    if not isinstance(feature, dict):
                        continue
                    supported = feature.get("gpu_backends", ["amd", "nvidia", "apple"])
                    if gpu_backend != "apple" and gpu_backend not in supported and "all" not in supported:
                        continue
                    if feature.get("id") and feature.get("name"):
                        missing = [f for f in ("description", "icon", "category", "setup_time", "priority") if f not in feature]
                        if missing:
                            logger.warning("Feature '%s' in %s missing optional fields: %s", feature["id"], path, ", ".join(missing))
                        features.append(feature)

            loaded += 1
        except (yaml.YAMLError, json.JSONDecodeError, OSError, KeyError, TypeError, ValueError) as e:
            logger.warning("Failed loading manifest %s: %s", path, e)
            errors.append({"file": str(path), "error": str(e)})

    logger.info("Loaded %d extension manifests (%d services, %d features)", loaded, len(services), len(features))
    return services, features, errors


# --- Service Registry ---

MANIFEST_SERVICES, MANIFEST_FEATURES, MANIFEST_ERRORS = load_extension_manifests(EXTENSIONS_DIR, GPU_BACKEND)
SERVICES = MANIFEST_SERVICES
if not SERVICES:
    logger.error("No services loaded from manifests in %s — dashboard will have no services", EXTENSIONS_DIR)

LLM_BACKEND = normalize_llm_backend(os.environ.get("LLM_BACKEND", ""))
_apply_host_native_llm_service_override(SERVICES, GPU_BACKEND)
_apply_external_llm_service_override(SERVICES)
_apply_vllm_service_override(SERVICES)

# --- Features ---

FEATURES = MANIFEST_FEATURES
if not FEATURES:
    logger.warning("No features loaded from manifests — check %s", EXTENSIONS_DIR)

# --- Workflow Config ---


def resolve_workflow_dir() -> Path:
    """Resolve canonical workflow directory with legacy fallback."""
    env_dir = os.environ.get("WORKFLOW_DIR")
    if env_dir:
        return Path(env_dir)
    canonical = Path(INSTALL_DIR) / "config" / "n8n"
    try:
        if canonical.exists():
            return canonical
    except PermissionError:
        # Optional host configuration may belong to a different UID. Keep
        # the canonical path so the workflow endpoint can report unavailable
        # access, rather than crashing startup or selecting an empty fallback.
        return canonical
    return Path(INSTALL_DIR) / "workflows"


WORKFLOW_DIR = resolve_workflow_dir()
WORKFLOW_CATALOG_FILE = WORKFLOW_DIR / "catalog.json"
DEFAULT_WORKFLOW_CATALOG = {"workflows": [], "categories": {}}

def _default_n8n_url() -> str:
    cfg = SERVICES.get("n8n", {})
    host = cfg.get("host", "n8n")
    port = cfg.get("port", 5678)
    return f"http://{host}:{port}"

N8N_URL = os.environ.get("N8N_URL", _default_n8n_url())

# --- Setup / Personas ---

SETUP_CONFIG_DIR = Path(DATA_DIR) / "config"

PERSONAS = {
    "general": {
        "name": "General Helper",
        "system_prompt": "You are a friendly and helpful AI assistant. You're knowledgeable, patient, and aim to be genuinely useful. Keep responses clear and conversational.",
        "icon": "\U0001f4ac"
    },
    "coding": {
        "name": "Coding Buddy",
        "system_prompt": "You are a skilled programmer and technical assistant. You write clean, well-documented code and explain technical concepts clearly. You're precise, thorough, and love solving problems.",
        "icon": "\U0001f4bb"
    },
    "creative": {
        "name": "Creative Writer",
        "system_prompt": "You are an imaginative creative writer and storyteller. You craft vivid descriptions, engaging narratives, and think outside the box. You're expressive and enjoy wordplay.",
        "icon": "\U0001f3a8"
    }
}

# --- Sidebar Icons ---

SIDEBAR_ICONS = {
    "open-webui": "MessageSquare",
    "n8n": "Network",
    "hermes": "Bot",
    "hermes-proxy": "Shield",
    "opencode": "Code",
    "perplexica": "Search",
    "comfyui": "Image",
    "token-spy": "Terminal",
    "langfuse": "BarChart2",
}

# --- Extensions Portal ---

CATALOG_PATH = Path(os.environ.get(
    "ODS_EXTENSIONS_CATALOG",
    str(Path(INSTALL_DIR) / "config" / "extensions-catalog.json")
))

EXTENSIONS_LIBRARY_DIR = Path(os.environ.get(
    "ODS_EXTENSIONS_LIBRARY_DIR",
    str(Path(DATA_DIR) / "extensions-library")
))

USER_EXTENSIONS_DIR = Path(os.environ.get(
    "ODS_USER_EXTENSIONS_DIR",
    str(Path(DATA_DIR) / "user-extensions")
))

def _load_core_service_ids() -> frozenset:
    core_ids_path = Path(INSTALL_DIR) / "config" / "core-service-ids.json"
    if core_ids_path.exists():
        try:
            return frozenset(json.loads(core_ids_path.read_text(encoding="utf-8")))
        except (json.JSONDecodeError, OSError):
            pass
    # Fallback to hardcoded list
    return frozenset({
        "dashboard-api", "dashboard", "llama-server", "model-router", "open-webui",
        "litellm", "langfuse", "hermes", "hermes-proxy", "n8n", "opencode",
        "perplexica", "searxng", "qdrant", "remote-provider-egress",
        "remote-provider-ssh-tunnel", "tts", "whisper",
        "embeddings", "token-spy", "comfyui", "ape", "privacy-shield",
    })


CORE_SERVICE_IDS = _load_core_service_ids()

# Always-on services defined in docker-compose.base.yml — never manageable via API.
# Distinct from CORE_SERVICE_IDS (the full built-in service allowlist).
ALWAYS_ON_SERVICES: frozenset = frozenset({
    "llama-server", "model-router", "remote-provider-egress",
    "remote-provider-ssh-tunnel", "open-webui", "dashboard", "dashboard-api",
})

# Built-ins qualified for Dashboard Library Add/Disable. The live health poll
# must refresh this same set after a fragment changes without an API restart.
# A lean install adds the original stack back from here, one click each; every
# entry was enabled live from a lean fleet install and proved working. Token
# Spy and APE build app source locally and wait for a reviewed source recipe.
LIBRARY_MANAGEABLE_BUILTINS: frozenset = frozenset({
    "n8n", "perplexica", "searxng",
    "hermes", "hermes-proxy", "qdrant", "embeddings", "tts", "whisper",
    "comfyui", "langfuse",
})


_CATALOG_ID_RE = re.compile(r"[a-z0-9][a-z0-9_-]*")


def load_extension_catalog() -> list[dict]:
    """Load the static extensions catalog JSON. Returns empty list on failure."""
    if not CATALOG_PATH.exists():
        logger.info("Extensions catalog not found at %s", CATALOG_PATH)
        return []
    try:
        data = json.loads(CATALOG_PATH.read_text(encoding="utf-8"))
    except (json.JSONDecodeError, OSError) as e:
        logger.warning("Failed to load extensions catalog: %s", e)
        return []
    # Catalog ids name folders (progress files, library receipts, installed
    # trees), so an entry whose id is not a plain extension id is dropped.
    entries = []
    for entry in data.get("extensions", []):
        identifier = entry.get("id") if isinstance(entry, dict) else None
        if isinstance(identifier, str) and _CATALOG_ID_RE.fullmatch(identifier):
            entries.append(entry)
        else:
            logger.warning("Ignoring extensions catalog entry with invalid id %r", identifier)
    return entries


EXTENSION_CATALOG = load_extension_catalog()

# --- Host Agent ---

def _running_inside_container() -> bool:
    """Best-effort check for Docker/Podman/containerd runtime context."""
    if Path("/.dockerenv").exists():
        return True
    try:
        cgroup = Path("/proc/1/cgroup").read_text(encoding="utf-8").lower()
    except OSError:
        return False
    return any(marker in cgroup for marker in ("docker", "containerd", "kubepods", "podman"))


def _running_under_wsl(release_path: str = "/proc/sys/kernel/osrelease") -> bool:
    """Return whether the dashboard container shares a WSL Linux kernel."""
    try:
        release = Path(release_path).read_text(encoding="utf-8")
    except OSError:
        return False
    return "microsoft" in release.casefold()


def _detect_container_default_gateway(route_path: str = "/proc/net/route") -> str:
    """Return this container's default-gateway IP, or empty on failure.

    Reads /proc/net/route directly so the container image doesn't need
    iproute2 installed. The default route line has destination 00000000 and
    a little-endian-hex gateway in the 3rd field.

    Why this matters: dashboard-api runs on `ods-network` (a custom bridge,
    e.g. 172.18.0.0/16). On Linux, the ods-host-agent binds to that network's
    host-side gateway when it can, so targeting this container's default gateway
    is routable without depending on `host.docker.internal:host-gateway`, which
    Docker often resolves to the default bridge gateway (172.17.0.1). That
    default bridge address is unreachable from custom networks under Docker's
    default DOCKER-ISOLATION-STAGE-2 iptables rules.
    """
    try:
        with open(route_path, "r", encoding="utf-8") as f:
            for line in f.readlines()[1:]:
                fields = line.strip().split()
                # destination == 0.0.0.0 AND flags has RTF_GATEWAY (0x2)
                if len(fields) < 4 or fields[1] != "00000000":
                    continue
                gw_hex = fields[2]
                try:
                    flags = int(fields[3], 16)
                    gateway_raw = int(gw_hex, 16)
                except ValueError:
                    continue
                if not (flags & 0x2) or gateway_raw == 0 or len(gw_hex) != 8:
                    continue
                # Little-endian: 0100A8C0 -> 192.168.0.1
                return ".".join(
                    str(int(gw_hex[i:i + 2], 16)) for i in (6, 4, 2, 0)
                )
    except OSError:
        pass
    return ""


def _resolve_agent_host() -> str:
    """Pick the host name/IP to use for the ods-host-agent.

    Priority:
      1. ODS_AGENT_HOST env (explicit operator override)
      2. host.docker.internal under WSL/Docker Desktop, whose compose gateway
         belongs to Docker Desktop and is not an address the WSL host can bind
      3. The container's own default-gateway IP on native Linux
      4. host.docker.internal (legacy fallback — broken on custom networks
         under default Docker iptables, but kept so explicit operator setups
         relying on it don't silently change)
    """
    explicit = os.environ.get("ODS_AGENT_HOST", "").strip()
    if explicit:
        return explicit
    if _running_inside_container():
        if _running_under_wsl():
            logger.info("Resolved ODS_AGENT_HOST=host.docker.internal for WSL")
            return "host.docker.internal"
        gw = _detect_container_default_gateway()
        if gw:
            logger.info("Resolved ODS_AGENT_HOST=%s via /proc/net/route", gw)
            return gw
    logger.warning(
        "Could not detect container default gateway; falling back to "
        "host.docker.internal. If host-agent calls time out, set "
        "ODS_AGENT_HOST=<host-ip> in dashboard-api's environment."
    )
    return "host.docker.internal"


AGENT_HOST = _resolve_agent_host()
AGENT_PORT = int(os.environ.get("ODS_AGENT_PORT", "7710"))
AGENT_URL = f"http://{AGENT_HOST}:{AGENT_PORT}"
DASHBOARD_API_KEY = os.environ.get("DASHBOARD_API_KEY", "")
# Prefer dedicated ODS_AGENT_KEY; fall back to DASHBOARD_API_KEY for
# existing installs that haven't generated a separate key yet.
ODS_AGENT_KEY = os.environ.get("ODS_AGENT_KEY", "") or DASHBOARD_API_KEY


# --- Templates ---

TEMPLATES_DIR = Path(
    os.environ.get(
        "ODS_TEMPLATES_DIR",
        str(Path(INSTALL_DIR) / "templates")
    )
)

_TEMPLATE_SCHEMA = None
try:
    import jsonschema as _jsonschema_mod
    _schema_path = Path(__file__).parent.parent.parent / "schema" / "service-template.v1.json"
    if _schema_path.exists():
        _TEMPLATE_SCHEMA = json.loads(_schema_path.read_text(encoding="utf-8"))
except ImportError:
    _jsonschema_mod = None


def load_templates() -> list[dict]:
    """Load service templates from YAML files. Returns empty list on failure."""
    if not TEMPLATES_DIR.exists():
        logger.info("Templates directory not found at %s", TEMPLATES_DIR)
        return []

    templates = []
    for path in sorted(TEMPLATES_DIR.iterdir()):
        if path.suffix.lower() not in (".yaml", ".yml"):
            continue
        try:
            data = yaml.safe_load(path.read_text(encoding="utf-8"))
            if not isinstance(data, dict):
                logger.warning("Skipping template %s: root is not a mapping", path.name)
                continue
            if data.get("schema_version") != "ods.templates.v1":
                logger.warning("Skipping template %s: unsupported schema_version", path.name)
                continue
            # Validate against JSON Schema if available
            if _TEMPLATE_SCHEMA is not None and _jsonschema_mod is not None:
                try:
                    _jsonschema_mod.validate(data, _TEMPLATE_SCHEMA)
                except _jsonschema_mod.ValidationError as ve:
                    logger.warning("Template validation failed for %s: %s", path.name, ve.message)
                    continue
            template = data.get("template")
            if not isinstance(template, dict) or not template.get("id") or not template.get("services"):
                logger.warning("Skipping template %s: missing required fields", path.name)
                continue
            templates.append(template)
        except (yaml.YAMLError, OSError, ValueError) as e:
            logger.warning("Failed loading template %s: %s", path.name, e)

    logger.info("Loaded %d service templates", len(templates))
    return templates


TEMPLATES = load_templates()