halyn 0.2.0__py3-none-any.whl

halyn/server.py

@@ -0,0 +1,292 @@
+# Copyright (c) 2026 Elmadani SALKA. All rights reserved.
+# Licensed under the MIT License. See LICENSE file.
+"""
+HTTP Server — REST API + MCP + SSE events.
+
+Endpoints:
+  GET  /health              System status
+  GET  /nodes               Connected nodes and manifests
+  POST /execute             Execute action through pipeline
+  POST /emergency-stop      Stop all nodes immediately
+  POST /resume              Resume after emergency stop
+  GET  /events              SSE stream of all events
+  GET  /events/query        Query recent events
+  GET  /audit               Query audit trail
+  GET  /audit/verify        Verify hash chain integrity
+  POST /consent/approve     Approve a pending node
+  POST /consent/deny        Deny a pending node
+  GET  /consent/pending     List pending consent requests
+  POST /confirm/approve     Approve a pending action
+  POST /confirm/deny        Deny a pending action
+  GET  /confirm/pending     List pending confirmations
+  GET  /intents             Query intent chains
+  GET  /scan                Trigger network discovery
+  GET  /mcp                 MCP endpoint (Claude.ai native)
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import time
+from typing import Any
+
+log = logging.getLogger("halyn.server")
+
+try:
+    from aiohttp import web
+    HAS_AIOHTTP = True
+except ImportError:
+    HAS_AIOHTTP = False
+
+
+def _json(data: Any, status: int = 200) -> "web.Response":
+    return web.Response(
+        text=json.dumps(data, default=str, ensure_ascii=False),
+        content_type="application/json",
+        status=status,
+    )
+
+
+def create_app(control_plane: Any, api_key: str = "") -> "web.Application":
+    if not HAS_AIOHTTP:
+        raise ImportError("aiohttp required: pip install aiohttp")
+
+    app = web.Application()
+    cp = control_plane
+
+    # Auth middleware
+    @web.middleware
+    async def auth_middleware(request: web.Request, handler):
+        if api_key and request.path not in ("/health",):
+            key = request.headers.get("Authorization", "").replace("Bearer ", "")
+            if not key:
+                key = request.query.get("key", "")
+            if key != api_key:
+                return _json({"error": "unauthorized"}, 401)
+        return await handler(request)
+
+    app.middlewares.append(auth_middleware)
+
+    # ─── Health ─────────────────────────────────
+
+    async def handle_health(req: web.Request) -> web.Response:
+        return _json(cp.status())
+
+    # ─── Nodes ──────────────────────────────────
+
+    async def handle_nodes(req: web.Request) -> web.Response:
+        nodes = {}
+        for nrp_id, manifest in cp._manifests.items():
+            nodes[nrp_id] = manifest.to_dict()
+        return _json({"nodes": nodes, "count": len(nodes)})
+
+    # ─── Execute ────────────────────────────────
+
+    async def handle_execute(req: web.Request) -> web.Response:
+        body = await req.json()
+        tool = body.get("tool", "")
+        args = body.get("args", {})
+        user_id = body.get("user_id", req.headers.get("X-User-Id", ""))
+        llm_model = body.get("llm_model", "")
+        intent = body.get("intent", "")
+
+        if not tool:
+            return _json({"error": "missing 'tool' field"}, 400)
+
+        result = await cp.execute(tool, args, user_id, llm_model, intent)
+        return _json({
+            "ok": result.ok,
+            "data": result.data,
+            "error": result.error,
+            "status": result.status.value,
+        })
+
+    # ─── Emergency ──────────────────────────────
+
+    async def handle_emergency_stop(req: web.Request) -> web.Response:
+        await cp.emergency_stop()
+        return _json({"status": "emergency_stop_activated"})
+
+    async def handle_resume(req: web.Request) -> web.Response:
+        await cp.resume()
+        return _json({"status": "resumed"})
+
+    # ─── Events ─────────────────────────────────
+
+    async def handle_events_sse(req: web.Request) -> web.StreamResponse:
+        resp = web.StreamResponse()
+        resp.content_type = "text/event-stream"
+        resp.headers["Cache-Control"] = "no-cache"
+        resp.headers["X-Accel-Buffering"] = "no"
+        await resp.prepare(req)
+
+        import asyncio
+        queue: asyncio.Queue[str] = asyncio.Queue(maxsize=1000)
+
+        async def forward(event):
+            try:
+                queue.put_nowait(event.to_json())
+            except asyncio.QueueFull:
+                pass
+
+        cp.event_bus.subscribe("*", forward)
+        try:
+            while True:
+                try:
+                    data = await asyncio.wait_for(queue.get(), timeout=30.0)
+                    await resp.write(f"data: {data}\n\n".encode())
+                except asyncio.TimeoutError:
+                    await resp.write(b": keepalive\n\n")
+        except (ConnectionResetError, asyncio.CancelledError):
+            pass
+        finally:
+            cp.event_bus.unsubscribe("*", forward)
+        return resp
+
+    async def handle_events_query(req: web.Request) -> web.Response:
+        n = int(req.query.get("n", "50"))
+        source = req.query.get("source", "")
+        name = req.query.get("name", "")
+        events = cp.event_bus.recent(n, source=source, name=name)
+        return _json({
+            "events": [e.to_dict() for e in events],
+            "total": cp.event_bus.total,
+            "pending": cp.event_bus.pending,
+        })
+
+    # ─── Audit ──────────────────────────────────
+
+    async def handle_audit(req: web.Request) -> web.Response:
+        limit = int(req.query.get("limit", "50"))
+        tool = req.query.get("tool", "")
+        node = req.query.get("node", "")
+        entries = cp.audit.query(tool=tool, node=node, limit=limit)
+        return _json({
+            "entries": [e.to_dict() for e in entries],
+            "count": cp.audit.count,
+            "chain_tip": cp.audit.chain_tip[:16],
+        })
+
+    async def handle_audit_verify(req: web.Request) -> web.Response:
+        valid, count, msg = cp.audit.verify_chain()
+        return _json({"valid": valid, "entries_checked": count, "message": msg})
+
+    # ─── Consent ────────────────────────────────
+
+    async def handle_consent_pending(req: web.Request) -> web.Response:
+        from .consent import ConsentLevel
+        pending = cp.consent.list_all(level=ConsentLevel.PENDING)
+        return _json({"pending": [r.to_dict() for r in pending], "count": len(pending)})
+
+    async def handle_consent_approve(req: web.Request) -> web.Response:
+        body = await req.json()
+        nrp_id = body.get("nrp_id", "")
+        level = body.get("level", "full")
+        duration = float(body.get("duration_hours", 0))
+        from .consent import ConsentLevel
+        lvl_map = {"full": ConsentLevel.FULL, "read_only": ConsentLevel.READ_ONLY,
+                   "temporary": ConsentLevel.TEMPORARY}
+        record = cp.consent.grant(
+            nrp_id, lvl_map.get(level, ConsentLevel.FULL),
+            granted_by=body.get("user_id", "api"),
+            duration_hours=duration,
+        )
+        return _json(record.to_dict())
+
+    async def handle_consent_deny(req: web.Request) -> web.Response:
+        body = await req.json()
+        nrp_id = body.get("nrp_id", "")
+        cp.consent.revoke(nrp_id, reason=body.get("reason", "denied via API"))
+        return _json({"denied": nrp_id})
+
+    # ─── Confirmations ──────────────────────────
+
+    async def handle_confirm_pending(req: web.Request) -> web.Response:
+        pending = cp.autonomy.get_pending()
+        return _json({
+            "pending": [{
+                "request_id": r.request_id,
+                "tool": r.action.tool,
+                "args": r.action.args,
+                "reason": r.reason,
+                "domain": r.domain,
+                "created_at": r.created_at,
+                "expires_at": r.expires_at,
+            } for r in pending],
+            "count": len(pending),
+        })
+
+    async def handle_confirm_approve(req: web.Request) -> web.Response:
+        body = await req.json()
+        req_id = body.get("request_id", "")
+        ok = cp.autonomy.approve(req_id)
+        if ok:
+            req_obj = cp.autonomy.get_request(req_id)
+            if req_obj:
+                result = await cp.execute(
+                    req_obj.action.tool, req_obj.action.args,
+                    intent_text=f"approved: {req_obj.reason}",
+                )
+                return _json({"approved": True, "result": {
+                    "ok": result.ok, "data": result.data, "error": result.error,
+                }})
+        return _json({"approved": ok})
+
+    async def handle_confirm_deny(req: web.Request) -> web.Response:
+        body = await req.json()
+        req_id = body.get("request_id", "")
+        ok = cp.autonomy.deny(req_id)
+        return _json({"denied": ok})
+
+    # ─── Intents ────────────────────────────────
+
+    async def handle_intents(req: web.Request) -> web.Response:
+        limit = int(req.query.get("limit", "20"))
+        node = req.query.get("node", "")
+        chains = cp.intents.query(node=node, limit=limit)
+        return _json({"chains": [c.to_dict() for c in chains], "count": len(chains)})
+
+    # ─── Discovery ──────────────────────────────
+
+    async def handle_scan(req: web.Request) -> web.Response:
+        config = {}
+        if req.query.get("subnet"):
+            config["subnets"] = [req.query["subnet"]]
+        if req.query.get("ssh"):
+            config["ssh_hosts"] = req.query["ssh"].split(",")
+        if req.query.get("http"):
+            config["http_urls"] = req.query["http"].split(",")
+        nodes = await cp.scan(config or None)
+        return _json({
+            "discovered": [{
+                "address": n.address, "port": n.port,
+                "protocol": n.protocol, "name": n.name,
+                "suggested_nrp_id": n.suggested_nrp_id,
+                "metadata": n.metadata,
+            } for n in nodes],
+            "count": len(nodes),
+        })
+
+    # ─── Register routes ────────────────────────
+
+    app.router.add_get("/health", handle_health)
+    app.router.add_get("/nodes", handle_nodes)
+    app.router.add_post("/execute", handle_execute)
+    app.router.add_post("/emergency-stop", handle_emergency_stop)
+    app.router.add_post("/resume", handle_resume)
+    app.router.add_get("/events", handle_events_sse)
+    app.router.add_get("/events/query", handle_events_query)
+    app.router.add_get("/audit", handle_audit)
+    app.router.add_get("/audit/verify", handle_audit_verify)
+    app.router.add_get("/consent/pending", handle_consent_pending)
+    app.router.add_post("/consent/approve", handle_consent_approve)
+    app.router.add_post("/consent/deny", handle_consent_deny)
+    app.router.add_get("/confirm/pending", handle_confirm_pending)
+    app.router.add_post("/confirm/approve", handle_confirm_approve)
+    app.router.add_post("/confirm/deny", handle_confirm_deny)
+    app.router.add_get("/intents", handle_intents)
+    app.router.add_get("/scan", handle_scan)
+
+    log.info("server.routes registered=%d", len(app.router.routes()))
+    return app

halyn/types.py

@@ -0,0 +1,116 @@
+# Copyright (c) 2026 Elmadani SALKA. All rights reserved.
+# Licensed under the MIT License. See LICENSE file.
+"""
+Core types. Every object in the system is defined here.
+No business logic. Just shapes.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+
+class ToolCategory(str, Enum):
+    """What kind of tool this is."""
+    EXECUTOR = "executor"    # Does things (shell, write, deploy)
+    OBSERVER = "observer"    # Sees things (metrics, logs, status)
+    MEMORY = "memory"        # Remembers things
+    VOICE = "voice"          # Communicates things
+
+
+class NodeKind(str, Enum):
+    """How we connect to a machine."""
+    LOCAL = "local"
+    SSH = "ssh"
+    ADB = "adb"
+    DOCKER = "docker"
+    KUBERNETES = "k8s"
+
+
+class ActionStatus(str, Enum):
+    """Outcome of an action."""
+    OK = "ok"
+    DENIED = "denied"       # Shield blocked it
+    FAILED = "failed"       # Execution error
+    TIMEOUT = "timeout"
+
+
+@dataclass(frozen=True, slots=True)
+class ToolSpec:
+    """Definition of a single tool."""
+    name: str
+    category: ToolCategory
+    description: str
+    dangerous: bool = False
+
+
+@dataclass(slots=True)
+class Node:
+    """A connected machine."""
+    name: str
+    kind: NodeKind
+    host: str = "localhost"
+    user: str = ""
+    port: int = 22
+    key_path: str = ""
+    alive: bool = False
+    last_seen: float = 0.0
+    labels: dict[str, str] = field(default_factory=dict)
+
+    @property
+    def ssh_target(self) -> str:
+        if self.user:
+            return f"{self.user}@{self.host}"
+        return self.host
+
+
+@dataclass(frozen=True, slots=True)
+class Action:
+    """A request to do something."""
+    tool: str
+    args: dict[str, Any] = field(default_factory=dict)
+    node: str = "local"
+    request_id: str = ""
+
+
+@dataclass(slots=True)
+class Result:
+    """What came back from an action."""
+    status: ActionStatus
+    data: Any = None
+    error: str = ""
+    elapsed_ms: float = 0.0
+    node: str = "local"
+    tool: str = ""
+
+    @property
+    def ok(self) -> bool:
+        return self.status == ActionStatus.OK
+
+
+@dataclass(slots=True)
+class AuditEntry:
+    """One line in the audit trail. Immutable once created."""
+    timestamp: float = field(default_factory=time.time)
+    tool: str = ""
+    node: str = "local"
+    status: str = "ok"
+    elapsed_ms: float = 0.0
+    user: str = "default"
+    error: str = ""
+    prev_hash: str = ""
+    entry_hash: str = ""
+
+
+@dataclass(slots=True)
+class PolicyRule:
+    """One RBAC rule."""
+    role: str
+    allow: list[str] = field(default_factory=list)     # tool patterns
+    deny: list[str] = field(default_factory=list)       # tool patterns
+    confirm: list[str] = field(default_factory=list)    # need human OK
+    nodes: list[str] = field(default_factory=lambda: ["*"])  # node patterns
+

halyn/watchdog.py

@@ -0,0 +1,252 @@
+# Copyright (c) 2026 Elmadani SALKA. All rights reserved.
+# Licensed under the MIT License. See LICENSE file.
+"""
+Watchdog — Component health monitor with failsafe.
+
+Periodic health checks on all registered components.
+Escalates failures to alert handlers. Triggers failsafe
+when critical components are unresponsive.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+import time
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+from typing import Any, Callable, Awaitable
+
+log = logging.getLogger("halyn.watchdog")
+
+
+class Health(str, Enum):
+    GREEN = "green"    # Everything nominal
+    YELLOW = "yellow"  # Degraded but functional
+    RED = "red"        # Critical — action needed
+    DEAD = "dead"      # Unresponsive
+
+
+@dataclass(slots=True)
+class ComponentStatus:
+    name: str
+    health: Health = Health.GREEN
+    last_check: float = 0.0
+    last_ok: float = 0.0
+    message: str = ""
+    checks_failed: int = 0
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def age(self) -> float:
+        return time.time() - self.last_check if self.last_check else float("inf")
+
+    @property
+    def downtime(self) -> float:
+        if self.health == Health.GREEN:
+            return 0.0
+        return time.time() - self.last_ok if self.last_ok else float("inf")
+
+
+AlertHandler = Callable[[str, str, dict[str, Any]], Awaitable[None] | None]
+
+
+class Watchdog:
+    """
+    Monitors all Halyn components and NRP nodes.
+
+    Runs periodic health checks. Escalates problems.
+    Sends alerts to humans — not to the AI.
+    The human is always the last line of defense.
+    """
+
+    __slots__ = (
+        "_components", "_checks", "_alert_handlers",
+        "_interval", "_running", "_failsafe_handlers",
+        "_heartbeat_file",
+    )
+
+    def __init__(self, interval: float = 10.0, heartbeat_file: str = "") -> None:
+        self._components: dict[str, ComponentStatus] = {}
+        self._checks: dict[str, Callable[[], Awaitable[Health]]] = {}
+        self._alert_handlers: list[AlertHandler] = []
+        self._failsafe_handlers: list[Callable[[], Awaitable[None] | None]] = []
+        self._interval = interval
+        self._running = False
+        self._heartbeat_file = heartbeat_file or "/tmp/halyn.heartbeat"
+
+    def register(self, name: str, check: Callable[[], Awaitable[Health]]) -> None:
+        self._components[name] = ComponentStatus(name=name)
+        self._checks[name] = check
+        log.debug("watchdog.register component=%s", name)
+
+    def on_alert(self, handler: AlertHandler) -> None:
+        self._alert_handlers.append(handler)
+
+    def on_failsafe(self, handler: Callable[[], Awaitable[None] | None]) -> None:
+        self._failsafe_handlers.append(handler)
+
+    async def check_all(self) -> dict[str, ComponentStatus]:
+        for name, check_fn in self._checks.items():
+            status = self._components[name]
+            status.last_check = time.time()
+            try:
+                health = await check_fn()
+                if asyncio.iscoroutine(health):
+                    health = await health
+                status.health = health
+                if health == Health.GREEN:
+                    status.last_ok = time.time()
+                    status.checks_failed = 0
+                    status.message = "OK"
+                else:
+                    status.checks_failed += 1
+                    if status.checks_failed >= 3:
+                        await self._escalate(name, status)
+            except Exception as exc:
+                status.health = Health.RED
+                status.message = str(exc)[:200]
+                status.checks_failed += 1
+                log.error("watchdog.check_failed component=%s error=%s", name, exc)
+                if status.checks_failed >= 3:
+                    await self._escalate(name, status)
+        return dict(self._components)
+
+    async def run(self) -> None:
+        self._running = True
+        log.info("watchdog.started interval=%.1fs components=%d",
+                 self._interval, len(self._checks))
+        while self._running:
+            try:
+                await self.check_all()
+                self._write_heartbeat()
+                await asyncio.sleep(self._interval)
+            except asyncio.CancelledError:
+                break
+            except Exception as exc:
+                log.exception("watchdog.loop_error: %s", exc)
+                await asyncio.sleep(self._interval)
+        log.info("watchdog.stopped")
+
+    def stop(self) -> None:
+        self._running = False
+
+    @property
+    def overall_health(self) -> Health:
+        if not self._components:
+            return Health.GREEN
+        healths = [c.health for c in self._components.values()]
+        if Health.DEAD in healths:
+            return Health.DEAD
+        if Health.RED in healths:
+            return Health.RED
+        if Health.YELLOW in healths:
+            return Health.YELLOW
+        return Health.GREEN
+
+    def status_report(self) -> dict[str, Any]:
+        return {
+            "overall": self.overall_health.value,
+            "components": {
+                name: {
+                    "health": c.health.value,
+                    "age_seconds": round(c.age, 1),
+                    "downtime_seconds": round(c.downtime, 1),
+                    "checks_failed": c.checks_failed,
+                    "message": c.message,
+                }
+                for name, c in self._components.items()
+            },
+            "timestamp": time.time(),
+        }
+
+    async def _escalate(self, name: str, status: ComponentStatus) -> None:
+        severity = "critical" if status.health == Health.RED else "warning"
+        alert_data = {
+            "component": name,
+            "health": status.health.value,
+            "checks_failed": status.checks_failed,
+            "downtime_seconds": round(status.downtime, 1),
+            "message": status.message,
+        }
+        log.warning("watchdog.alert component=%s severity=%s failed=%d",
+                     name, severity, status.checks_failed)
+
+        for handler in self._alert_handlers:
+            try:
+                result = handler(severity, f"{name} is {status.health.value}", alert_data)
+                if asyncio.iscoroutine(result):
+                    await result
+            except Exception as exc:
+                log.error("watchdog.alert_handler_error: %s", exc)
+
+        if status.health in (Health.RED, Health.DEAD) and status.checks_failed >= 5:
+            await self._trigger_failsafe(name)
+
+    async def _trigger_failsafe(self, trigger: str) -> None:
+        log.critical("watchdog.FAILSAFE trigger=%s — activating safe mode", trigger)
+        for handler in self._failsafe_handlers:
+            try:
+                result = handler()
+                if asyncio.iscoroutine(result):
+                    await result
+            except Exception as exc:
+                log.error("watchdog.failsafe_error: %s", exc)
+
+    def _write_heartbeat(self) -> None:
+        try:
+            Path(self._heartbeat_file).write_text(
+                json.dumps({
+                    "alive": True,
+                    "health": self.overall_health.value,
+                    "timestamp": time.time(),
+                    "pid": os.getpid(),
+                })
+            )
+        except OSError:
+            pass
+
+
+# ─── Built-in health checks ────────────────────────
+
+async def check_event_bus(bus: Any) -> Health:
+    if bus.pending > 10000:
+        return Health.RED
+    if bus.pending > 1000:
+        return Health.YELLOW
+    return Health.GREEN
+
+
+async def check_memory_store(store: Any) -> Health:
+    try:
+        store.search("__healthcheck__", limit=1)
+        return Health.GREEN
+    except Exception:
+        return Health.RED
+
+
+async def check_disk_space(path: str = "/", threshold: float = 0.90) -> Health:
+    try:
+        st = os.statvfs(path)
+        used = 1.0 - (st.f_bavail / st.f_blocks)
+        if used > 0.95:
+            return Health.RED
+        if used > threshold:
+            return Health.YELLOW
+        return Health.GREEN
+    except Exception:
+        return Health.YELLOW
+
+
+async def check_driver_heartbeat(driver: Any) -> Health:
+    try:
+        result = await asyncio.wait_for(driver.heartbeat(), timeout=10.0)
+        return Health.GREEN if result.get("alive") else Health.RED
+    except asyncio.TimeoutError:
+        return Health.RED
+    except Exception:
+        return Health.RED
+