runtime.py

"""
OMEN Engine Core — Plugin Runtime

Manages plugin discovery, loading, lifecycle, event routing, and fault isolation.

Reference: docs/loe-1-engine.md
"""

from __future__ import annotations

import importlib
import json
import logging
from dataclasses import dataclass, field
from pathlib import Path
from typing import Any

logger = logging.getLogger("omen.engine.core.runtime")


# ---------------------------------------------------------------------------
# Plugin Manifest
# ---------------------------------------------------------------------------

@dataclass
class PluginManifest:
    plugin_id: str
    name: str
    version: str
    description: str
    capabilities: list[str] = field(default_factory=list)
    dependencies: list[str] = field(default_factory=list)
    configuration_schema: dict[str, Any] = field(default_factory=dict)
    omen_sdk_version: str = ">=1.0.0"
    ai_assisted: bool = False
    classification: str = "UNCLASSIFIED"

    @classmethod
    def from_file(cls, path: Path) -> "PluginManifest":
        data = json.loads(path.read_text())
        return cls(**{k: v for k, v in data.items() if k in cls.__dataclass_fields__})


# ---------------------------------------------------------------------------
# Plugin Registry
# ---------------------------------------------------------------------------

class PluginRegistry:
    """
    Central registry of loaded plugins.

    In production this is backed by a signed manifest store.
    This stub uses an in-memory dict for development and testing.
    """

    def __init__(self) -> None:
        self._plugins: dict[str, Any] = {}
        self._manifests: dict[str, PluginManifest] = {}

    def register(self, plugin: Any, manifest: PluginManifest) -> None:
        if manifest.plugin_id in self._plugins:
            raise ValueError(f"Plugin already registered: {manifest.plugin_id}")
        self._plugins[manifest.plugin_id] = plugin
        self._manifests[manifest.plugin_id] = manifest
        logger.info("Registered plugin: %s v%s", manifest.plugin_id, manifest.version)

    def get(self, plugin_id: str) -> Any | None:
        return self._plugins.get(plugin_id)

    def get_manifest(self, plugin_id: str) -> PluginManifest | None:
        return self._manifests.get(plugin_id)

    def list_plugin_ids(self) -> list[str]:
        return list(self._plugins.keys())

    def unregister(self, plugin_id: str) -> None:
        self._plugins.pop(plugin_id, None)
        self._manifests.pop(plugin_id, None)
        logger.info("Unregistered plugin: %s", plugin_id)


# ---------------------------------------------------------------------------
# Plugin Runtime
# ---------------------------------------------------------------------------

class PluginRuntime:
    """
    Manages the lifecycle of all registered plugins.

    TODO (Phase 1):
    - Add sandboxed execution with resource limits
    - Add plugin signature verification
    - Add capability enforcement at subscription time
    - Add fault isolation (exception in one plugin must not crash others)
    """

    def __init__(self, registry: PluginRegistry, event_bus: Any) -> None:
        self.registry = registry
        self.event_bus = event_bus
        self._running: set[str] = set()

    def start_plugin(self, plugin_id: str, config: dict[str, Any]) -> None:
        plugin = self.registry.get(plugin_id)
        if plugin is None:
            raise KeyError(f"Plugin not found: {plugin_id}")
        if plugin_id in self._running:
            logger.warning("Plugin already running: %s", plugin_id)
            return

        manifest = self.registry.get_manifest(plugin_id)
        self._enforce_capabilities(manifest)

        try:
            plugin.on_start(config)
            self._running.add(plugin_id)
            logger.info("Started plugin: %s", plugin_id)
        except Exception as exc:
            logger.error("Failed to start plugin %s: %s", plugin_id, exc, exc_info=True)
            raise

    def stop_plugin(self, plugin_id: str) -> None:
        plugin = self.registry.get(plugin_id)
        if plugin is None or plugin_id not in self._running:
            return
        try:
            plugin.on_stop()
        except Exception as exc:
            logger.warning("Error stopping plugin %s: %s", plugin_id, exc)
        finally:
            self._running.discard(plugin_id)
            logger.info("Stopped plugin: %s", plugin_id)

    def dispatch_event(self, event: Any) -> list[Any]:
        """Dispatch an event to all running plugins. Returns all output events."""
        output_events: list[Any] = []
        for plugin_id in list(self._running):
            plugin = self.registry.get(plugin_id)
            if plugin is None:
                continue
            try:
                results = plugin.on_event(event)
                output_events.extend(results or [])
            except Exception as exc:
                logger.error(
                    "Plugin %s raised exception handling event %s: %s",
                    plugin_id, getattr(event, "event_type", "?"), exc,
                    exc_info=True,
                )
                # Fault isolation: continue to next plugin
        return output_events

    def running_plugins(self) -> list[str]:
        return list(self._running)

    def _enforce_capabilities(self, manifest: PluginManifest | None) -> None:
        if manifest is None:
            return
        # TODO: Check declared capabilities against policy
        # For now, log a warning if no capabilities declared
        if not manifest.capabilities:
            logger.warning("Plugin %s declares no capabilities", manifest.plugin_id)