halyn 0.2.0__py3-none-any.whl

halyn/drivers/ssh.py

@@ -0,0 +1,131 @@
+# Copyright (c) 2026 Elmadani SALKA. All rights reserved.
+# Licensed under the MIT License. See LICENSE file.
+"""
+SSH Driver v2 — With Manifest + Events.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import shlex
+from typing import Any
+
+from nrp import NRPDriver, ShieldRule, ShieldType
+from nrp import NRPId
+from nrp import NRPManifest, ChannelSpec, ActionSpec, ShieldSpec
+
+
+class SSHDriver(NRPDriver):
+    """Control any machine via SSH. Self-describing."""
+
+    def __init__(self, host: str, user: str = "", key_path: str = "", port: int = 22) -> None:
+        super().__init__()
+        self.host = host
+        self.user = user
+        self.key_path = key_path
+        self.port = port
+
+    def manifest(self) -> NRPManifest:
+        nrp_id = self._nrp_id or NRPId.create("local", "server", self.host.replace(".", "-"))
+        return NRPManifest(
+            nrp_id=nrp_id,
+            manufacturer="Generic",
+            model="Linux Server",
+            observe=[
+                ChannelSpec("hostname", "string", description="Machine hostname"),
+                ChannelSpec("cpu", "int", description="CPU core count"),
+                ChannelSpec("ram", "string", description="RAM total and free"),
+                ChannelSpec("disk", "string", description="Root disk usage"),
+                ChannelSpec("load", "string", description="System load average"),
+                ChannelSpec("uptime", "string", description="System uptime"),
+                ChannelSpec("status", "string", description="Quick alive check"),
+            ],
+            act=[
+                ActionSpec("shell", {"command": "string — shell command"}, "Execute shell command", dangerous=True),
+                ActionSpec("file_read", {"path": "string — file path"}, "Read file contents"),
+                ActionSpec("file_write", {"path": "string", "content": "string"}, "Write file", dangerous=True),
+                ActionSpec("service_restart", {"service": "string"}, "Restart systemd service", dangerous=True),
+                ActionSpec("file_list", {"path": "string — directory"}, "List directory"),
+                ActionSpec("process_list", {}, "Top processes by memory"),
+                ActionSpec("log_tail", {"source": "string", "lines": "int"}, "Tail logs"),
+                ActionSpec("git_status", {"path": "string"}, "Git repository state"),
+            ],
+            shield=[
+                ShieldSpec("no_rm_rf", "pattern", "rm -rf", description="Block recursive delete"),
+                ShieldSpec("no_shutdown", "pattern", "shutdown", description="Block shutdown"),
+                ShieldSpec("no_reboot", "pattern", "reboot", description="Block reboot"),
+                ShieldSpec("no_mkfs", "pattern", "mkfs", description="Block format"),
+                ShieldSpec("no_dd", "pattern", "dd if=", description="Block raw disk write"),
+                ShieldSpec("confirm_deploy", "confirm", "deploy", description="Confirm before deploy"),
+            ],
+        )
+
+    async def observe(self, channels: list[str] | None = None) -> dict[str, Any]:
+        channels = channels or ["hostname", "cpu", "ram", "disk", "load"]
+        commands = {
+            "hostname": "hostname",
+            "cpu": "nproc",
+            "ram": "free -h | grep Mem",
+            "disk": "df -h / | tail -1",
+            "load": "cat /proc/loadavg",
+            "uptime": "uptime -p 2>/dev/null || uptime",
+            "status": "echo ok",
+        }
+        state: dict[str, Any] = {}
+        for ch in channels:
+            if ch in commands:
+                try:
+                    state[ch] = self._exec(commands[ch]).strip()
+                except Exception as e:
+                    state[ch] = f"error: {e}"
+        return state
+
+    async def act(self, command: str, args: dict[str, Any]) -> Any:
+        if command == "shell":
+            return self._exec(args.get("command", "echo no command"), args.get("timeout", 30))
+        elif command == "file_read":
+            return self._exec(f"cat {shlex.quote(args['path'])}", 10)
+        elif command == "file_write":
+            content = args["content"].replace("'", "'\\''")
+            path = shlex.quote(args["path"])
+            self._exec(f"mkdir -p $(dirname {path}) && printf '%s' '{content}' > {path}", 10)
+            return {"written": len(args["content"])}
+        elif command == "service_restart":
+            return self._exec(f"systemctl restart {shlex.quote(args['service'])}", 15)
+        elif command == "file_list":
+            return self._exec(f"ls -la {shlex.quote(args.get('path', '.'))}", 10)
+        elif command == "process_list":
+            return self._exec("ps aux --sort=-%mem | head -15", 10)
+        elif command == "log_tail":
+            src = args.get("source", "syslog")
+            n = min(args.get("lines", 30), 200)
+            if src.startswith("/"):
+                return self._exec(f"tail -{n} {shlex.quote(src)}", 10)
+            return self._exec(f"journalctl -u {shlex.quote(src)} --no-pager -n {n}", 10)
+        elif command == "git_status":
+            path = shlex.quote(args.get("path", "."))
+            return self._exec(f"cd {path} && git branch --show-current && git status --short && git log --oneline -3", 10)
+        return self._exec(args.get("command", command), args.get("timeout", 30))
+
+    def shield_rules(self) -> list[ShieldRule]:
+        return [
+            ShieldRule("no_rm_rf", ShieldType.PATTERN, "rm -rf"),
+            ShieldRule("no_shutdown", ShieldType.PATTERN, "shutdown"),
+            ShieldRule("no_reboot", ShieldType.PATTERN, "reboot"),
+            ShieldRule("no_mkfs", ShieldType.PATTERN, "mkfs"),
+            ShieldRule("no_dd", ShieldType.PATTERN, "dd if="),
+        ]
+
+    def _exec(self, cmd: str, timeout: int = 30) -> str:
+        parts = ["ssh", "-o", "StrictHostKeyChecking=no", "-o", "ConnectTimeout=5"]
+        if self.key_path:
+            parts += ["-i", self.key_path]
+        if self.port != 22:
+            parts += ["-p", str(self.port)]
+        target = f"{self.user}@{self.host}" if self.user else self.host
+        parts += [target, cmd]
+        r = subprocess.run(parts, capture_output=True, text=True, timeout=min(timeout, 300))
+        if r.returncode != 0 and r.stderr.strip():
+            raise RuntimeError(r.stderr[:500])
+        return r.stdout
+

halyn/drivers/unitree.py

@@ -0,0 +1,103 @@
+# Copyright (c) 2026 Elmadani SALKA. All rights reserved.
+# Licensed under the MIT License. See LICENSE file.
+"""
+Unitree Driver — G1, H1, Go2 robots.
+
+Uses Unitree SDK2 Python bindings.
+Falls back to HTTP API if SDK not available.
+"""
+from __future__ import annotations
+from typing import Any
+from nrp import NRPDriver, ShieldRule, ShieldType
+
+class UnitreeDriver(NRPDriver):
+    def __init__(self, robot_ip: str = "192.168.123.161", model: str = "g1") -> None:
+        self.robot_ip = robot_ip
+        self.model = model
+        self._sdk: Any = None
+
+    @property
+    def kind(self) -> str: return "unitree"
+
+    @property
+    def capabilities(self) -> list[str]:
+        return ["stand", "sit", "walk", "stop", "pick", "place",
+                "move_joint", "set_speed", "get_state", "emergency_stop"]
+
+    async def connect(self) -> bool:
+        try:
+            import unitree_sdk2py as sdk
+            self._sdk = sdk.Robot(self.robot_ip)
+            self._sdk.connect()
+            return True
+        except ImportError:
+            # Try HTTP fallback
+            try:
+                import aiohttp
+                async with aiohttp.ClientSession() as s:
+                    async with s.get(f"http://{self.robot_ip}:8080/status",
+                                     timeout=aiohttp.ClientTimeout(total=3)) as r:
+                        return r.status == 200
+            except Exception:
+                return False
+
+    async def observe(self, channels: list[str] | None = None) -> dict[str, Any]:
+        channels = channels or ["joints", "imu", "battery", "mode"]
+        state: dict[str, Any] = {}
+        if self._sdk:
+            s = self._sdk.get_state()
+            if "joints" in channels:
+                state["joints"] = s.get("joint_angles", {})
+            if "imu" in channels:
+                state["imu"] = s.get("imu", {})
+            if "battery" in channels:
+                state["battery"] = s.get("battery_percent", 0)
+            if "mode" in channels:
+                state["mode"] = s.get("mode", "unknown")
+        else:
+            import aiohttp
+            async with aiohttp.ClientSession() as session:
+                async with session.get(f"http://{self.robot_ip}:8080/state") as r:
+                    state = await r.json()
+        return state
+
+    async def act(self, command: str, args: dict[str, Any]) -> Any:
+        if command == "emergency_stop":
+            if self._sdk:
+                self._sdk.emergency_stop()
+            return {"stopped": True}
+        if command == "stand":
+            if self._sdk: self._sdk.stand()
+            return {"mode": "standing"}
+        if command == "sit":
+            if self._sdk: self._sdk.sit()
+            return {"mode": "sitting"}
+        if command == "walk":
+            speed = args.get("speed", 0.3)
+            direction = args.get("direction", "forward")
+            if self._sdk: self._sdk.walk(speed, direction)
+            return {"walking": True, "speed": speed}
+        if command == "stop":
+            if self._sdk: self._sdk.stop()
+            return {"mode": "idle"}
+        if command == "pick":
+            target = args.get("target", "")
+            if self._sdk: self._sdk.pick(target)
+            return {"picking": target}
+        if command == "move_joint":
+            joint = args["joint"]
+            angle = args["angle"]
+            if self._sdk: self._sdk.move_joint(joint, angle)
+            return {"joint": joint, "angle": angle}
+        raise ValueError(f"Unknown unitree command: {command}")
+
+    def shield_rules(self) -> list[ShieldRule]:
+        return [
+            ShieldRule("max_speed", ShieldType.LIMIT, 1.5, "m/s", "Maximum walking speed"),
+            ShieldRule("max_joint_speed", ShieldType.LIMIT, 2.0, "rad/s", "Maximum joint velocity"),
+            ShieldRule("workspace", ShieldType.ZONE, {"x":[-3,3],"y":[-3,3],"z":[0,1.5]}, "m", "Allowed area"),
+            ShieldRule("min_battery", ShieldType.THRESHOLD, 10, "percent", "Stop below 10%"),
+            ShieldRule("max_payload", ShieldType.LIMIT, 3, "kg", "Maximum carry weight"),
+            ShieldRule("emergency_stop", ShieldType.COMMAND, True, description="Always allowed"),
+        ]
+

halyn/drivers/websocket.py

@@ -0,0 +1,175 @@
+# Copyright (c) 2026 Elmadani SALKA. All rights reserved.
+# Licensed under the MIT License. See LICENSE file.
+"""
+WebSocket meta-driver — bidirectional real-time channels.
+
+Covers: live dashboards, streaming APIs, real-time data feeds,
+WebSocket-based IoT platforms, home automation bridges (e.g. Home Assistant).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import time
+from typing import Any
+
+from nrp import (
+    NRPDriver, NRPManifest, NRPId,
+    ChannelSpec, ActionSpec, ShieldSpec, ShieldRule, ShieldType, Severity,
+)
+
+log = logging.getLogger("halyn.drivers.websocket")
+
+try:
+    import aiohttp
+    HAS_WS = True
+except ImportError:
+    HAS_WS = False
+
+
+class WebSocketDriver(NRPDriver):
+    """
+    Persistent WebSocket connection with message routing.
+
+    Receives JSON messages, indexes them by a configurable key,
+    and exposes the latest state per channel. Outbound messages
+    are sent via act().
+    """
+
+    def __init__(
+        self,
+        url: str,
+        auth_token: str = "",
+        channels: list[str] | None = None,
+        message_key: str = "type",
+        ping_interval: float = 30.0,
+    ) -> None:
+        super().__init__()
+        self.url = url
+        self.auth_token = auth_token
+        self.channel_names = channels or ["default"]
+        self.message_key = message_key
+        self.ping_interval = ping_interval
+        self._ws = None
+        self._session = None
+        self._state: dict[str, Any] = {}
+        self._msg_count = 0
+        self._connected_at = 0.0
+        self._listen_task = None
+
+    def manifest(self) -> NRPManifest:
+        observe = [
+            ChannelSpec("connected", "bool"),
+            ChannelSpec("message_count", "int"),
+            ChannelSpec("uptime", "float", unit="seconds"),
+        ]
+        for ch in self.channel_names:
+            observe.append(ChannelSpec(ch, "json", rate="on_change"))
+
+        return NRPManifest(
+            nrp_id=self._nrp_id or NRPId.create("local", "ws", self.url.split("/")[-1]),
+            manufacturer="WebSocket",
+            model=self.url,
+            observe=observe,
+            act=[
+                ActionSpec("send", {"message": "json — payload to send"}, "Send JSON message"),
+                ActionSpec("send_raw", {"data": "string"}, "Send raw text"),
+                ActionSpec("subscribe", {"channel": "string"}, "Subscribe to channel"),
+                ActionSpec("reconnect", {}, "Force reconnect"),
+            ],
+            shield=[ShieldSpec("rate", "limit", 100, "msg/s")],
+        )
+
+    async def connect(self) -> bool:
+        if not HAS_WS:
+            log.warning("websocket: aiohttp required")
+            return False
+        try:
+            headers: dict[str, str] = {}
+            if self.auth_token:
+                headers["Authorization"] = self.auth_token
+            self._session = aiohttp.ClientSession()
+            self._ws = await self._session.ws_connect(
+                self.url, headers=headers,
+                heartbeat=self.ping_interval,
+            )
+            self._connected_at = time.time()
+            self._listen_task = asyncio.create_task(self._listen())
+            log.info("ws.connected url=%s", self.url)
+            return True
+        except Exception as e:
+            log.error("ws.connect_failed url=%s error=%s", self.url, e)
+            return False
+
+    async def observe(self, channels: list[str] | None = None) -> dict[str, Any]:
+        state: dict[str, Any] = {
+            "connected": self._ws is not None and not self._ws.closed,
+            "message_count": self._msg_count,
+            "uptime": time.time() - self._connected_at if self._connected_at else 0,
+        }
+        targets = channels or self.channel_names
+        for ch in targets:
+            if ch in self._state:
+                state[ch] = self._state[ch]
+        return state
+
+    async def act(self, command: str, args: dict[str, Any]) -> Any:
+        if command == "reconnect":
+            await self.disconnect()
+            return {"reconnected": await self.connect()}
+
+        if not self._ws or self._ws.closed:
+            return {"error": "not connected"}
+
+        if command == "send":
+            msg = args.get("message", {})
+            await self._ws.send_json(msg)
+            return {"sent": True, "size": len(json.dumps(msg))}
+        if command == "send_raw":
+            data = args.get("data", "")
+            await self._ws.send_str(data)
+            return {"sent": True, "size": len(data)}
+        if command == "subscribe":
+            ch = args.get("channel", "")
+            if ch and ch not in self.channel_names:
+                self.channel_names.append(ch)
+            return {"subscribed": ch}
+
+        return {"error": f"unknown: {command}"}
+
+    def shield_rules(self) -> list[ShieldRule]:
+        return [ShieldRule("rate", ShieldType.LIMIT, 100)]
+
+    async def disconnect(self) -> None:
+        if self._listen_task:
+            self._listen_task.cancel()
+        if self._ws and not self._ws.closed:
+            await self._ws.close()
+        if self._session:
+            await self._session.close()
+        self._ws = None
+        self._session = None
+
+    async def _listen(self) -> None:
+        try:
+            async for msg in self._ws:
+                if msg.type == aiohttp.WSMsgType.TEXT:
+                    self._msg_count += 1
+                    try:
+                        data = json.loads(msg.data)
+                        key = data.get(self.message_key, "default")
+                        self._state[key] = data
+                        if self._event_bus:
+                            await self.emit(f"ws_message_{key}", data=data)
+                    except json.JSONDecodeError:
+                        self._state["raw"] = msg.data
+                elif msg.type in (aiohttp.WSMsgType.CLOSED, aiohttp.WSMsgType.ERROR):
+                    break
+        except asyncio.CancelledError:
+            pass
+        except Exception as e:
+            log.error("ws.listen_error: %s", e)
+            if self._event_bus:
+                await self.emit("ws_disconnected", Severity.WARNING, error=str(e))

halyn/engine.py

@@ -0,0 +1,222 @@
+# Copyright (c) 2026 Elmadani SALKA. All rights reserved.
+# Licensed under the MIT License. See LICENSE file.
+"""
+Engine — The nerve center.
+
+Routes actions to tools. Enforces policy. Writes audit.
+Every side effect passes through here. No exceptions.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import json
+import logging
+import time
+from typing import Any, Callable, Awaitable
+
+from .types import (
+    Action, Result, AuditEntry, Node, NodeKind,
+    ToolSpec, ToolCategory, ActionStatus, PolicyRule,
+)
+
+log = logging.getLogger("jarvis.engine")
+
+ToolFn = Callable[[dict[str, Any], Node | None], Any | Awaitable[Any]]
+
+
+class Registry:
+    """All tools, all nodes, one place. Thread-safe by design (async single-thread)."""
+
+    __slots__ = ("_tools", "_tool_fns", "_nodes", "_policies")
+
+    def __init__(self) -> None:
+        self._tools: dict[str, ToolSpec] = {}
+        self._tool_fns: dict[str, ToolFn] = {}
+        self._nodes: dict[str, Node] = {}
+        self._policies: list[PolicyRule] = []
+
+    def register_tool(
+        self,
+        name: str,
+        fn: ToolFn,
+        category: ToolCategory = ToolCategory.EXECUTOR,
+        description: str = "",
+        dangerous: bool = False,
+    ) -> None:
+        self._tools[name] = ToolSpec(name, category, description, dangerous)
+        self._tool_fns[name] = fn
+
+    def register_node(self, node: Node) -> None:
+        self._nodes[node.name] = node
+        log.info("node.registered name=%s kind=%s host=%s", node.name, node.kind.value, node.host)
+
+    def add_policy(self, rule: PolicyRule) -> None:
+        self._policies.append(rule)
+
+    @property
+    def tool_names(self) -> list[str]:
+        return list(self._tools)
+
+    @property
+    def nodes(self) -> dict[str, Node]:
+        return dict(self._nodes)
+
+    def get_tool_fn(self, name: str) -> ToolFn | None:
+        return self._tool_fns.get(name)
+
+    def get_node(self, name: str) -> Node | None:
+        return self._nodes.get(name)
+
+    def get_spec(self, name: str) -> ToolSpec | None:
+        return self._tools.get(name)
+
+
+class AuditLog:
+    """Append-only, hash-chained audit trail."""
+
+    __slots__ = ("_entries", "_last_hash")
+
+    def __init__(self) -> None:
+        self._entries: list[AuditEntry] = []
+        self._last_hash: str = "0" * 64
+
+    def append(self, entry: AuditEntry) -> None:
+        entry.prev_hash = self._last_hash
+        payload = f"{entry.timestamp}:{entry.tool}:{entry.node}:{entry.status}:{entry.prev_hash}"
+        entry.entry_hash = hashlib.sha256(payload.encode()).hexdigest()
+        self._last_hash = entry.entry_hash
+        self._entries.append(entry)
+        # Bound memory — keep last 10K entries in-memory, older go to disk
+        if len(self._entries) > 10_000:
+            self._entries = self._entries[-5_000:]
+
+    def recent(self, n: int = 50) -> list[AuditEntry]:
+        return self._entries[-n:]
+
+    @property
+    def count(self) -> int:
+        return len(self._entries)
+
+    def verify_chain(self) -> bool:
+        """Verify integrity of the audit chain."""
+        for i in range(1, len(self._entries)):
+            if self._entries[i].prev_hash != self._entries[i - 1].entry_hash:
+                return False
+        return True
+
+
+class Shield:
+    """Security middleware. Blocks dangerous commands before execution."""
+
+    DESTRUCTIVE_PATTERNS: tuple[str, ...] = (
+        "rm -rf", "rm -r /", "mkfs", "dd if=", "format ",
+        "DROP TABLE", "DROP DATABASE", "TRUNCATE", "DELETE FROM",
+        "shutdown", "reboot", "halt", "init 0",
+        "chmod 777 /", "chown", "> /dev/sd",
+    )
+
+    def check(self, action: Action, spec: ToolSpec | None) -> ActionStatus | None:
+        """Returns ActionStatus.DENIED if blocked, None if allowed."""
+        if spec and spec.dangerous:
+            log.warning("shield.dangerous tool=%s node=%s", action.tool, action.node)
+
+        cmd = action.args.get("command", "") + action.args.get("path", "")
+        cmd_lower = cmd.lower()
+
+        for pattern in self.DESTRUCTIVE_PATTERNS:
+            if pattern.lower() in cmd_lower:
+                log.warning("shield.blocked pattern=%s cmd=%s", pattern, cmd[:100])
+                return ActionStatus.DENIED
+
+        return None
+
+
+class Engine:
+    """The single entry point for all actions. Routes, guards, executes, audits."""
+
+    __slots__ = ("registry", "audit", "shield", "_started")
+
+    def __init__(self) -> None:
+        self.registry = Registry()
+        self.audit = AuditLog()
+        self.shield = Shield()
+        self._started = time.monotonic()
+
+    async def execute(self, action: Action, user: str = "default") -> Result:
+        """Execute one action. The only way to do anything."""
+        t0 = time.monotonic()
+
+        # 1. Resolve tool
+        fn = self.registry.get_tool_fn(action.tool)
+        if fn is None:
+            return self._fail(action, f"unknown tool: {action.tool}", t0, user)
+
+        spec = self.registry.get_spec(action.tool)
+
+        # 2. Resolve node
+        node = self.registry.get_node(action.node)
+        if action.node != "local" and node is None:
+            return self._fail(action, f"unknown node: {action.node}", t0, user)
+
+        # 3. Shield check
+        verdict = self.shield.check(action, spec)
+        if verdict is not None:
+            return self._result(action, verdict, None, "blocked by shield", t0, user)
+
+        # 4. Execute
+        try:
+            if asyncio.iscoroutinefunction(fn):
+                data = await fn(action.args, node)
+            else:
+                data = fn(action.args, node)
+            result = self._result(action, ActionStatus.OK, data, "", t0, user)
+
+        except TimeoutError:
+            result = self._result(action, ActionStatus.TIMEOUT, None, "timeout", t0, user)
+        except Exception as exc:
+            result = self._result(action, ActionStatus.FAILED, None, str(exc)[:500], t0, user)
+
+        return result
+
+    async def batch(self, actions: list[Action], user: str = "default") -> list[Result]:
+        """Execute multiple actions sequentially. Future: parallel with DAG."""
+        return [await self.execute(a, user) for a in actions]
+
+    def health(self) -> dict[str, Any]:
+        uptime = time.monotonic() - self._started
+        return {
+            "status": "ok",
+            "uptime_s": round(uptime, 1),
+            "tools": len(self.registry.tool_names),
+            "nodes": len(self.registry.nodes),
+            "actions_total": self.audit.count,
+            "audit_chain_valid": self.audit.verify_chain(),
+        }
+
+    # ─── Internal ──────────────────────────────────
+
+    def _result(
+        self, action: Action, status: ActionStatus,
+        data: Any, error: str, t0: float, user: str,
+    ) -> Result:
+        elapsed = (time.monotonic() - t0) * 1000
+        result = Result(
+            status=status, data=data, error=error,
+            elapsed_ms=round(elapsed, 2),
+            node=action.node, tool=action.tool,
+        )
+        self.audit.append(AuditEntry(
+            tool=action.tool, node=action.node,
+            status=status.value, elapsed_ms=result.elapsed_ms,
+            user=user, error=error[:200] if error else "",
+        ))
+        lvl = logging.INFO if result.ok else logging.WARNING
+        log.log(lvl, "action.%s tool=%s node=%s ms=%.1f",
+                status.value, action.tool, action.node, elapsed)
+        return result
+
+    def _fail(self, action: Action, error: str, t0: float, user: str) -> Result:
+        return self._result(action, ActionStatus.FAILED, None, error, t0, user)
+