halyn 0.2.0__py3-none-any.whl

halyn/memory/store.py

@@ -0,0 +1,200 @@
+# Copyright (c) 2026 Elmadani SALKA. All rights reserved.
+# Licensed under the MIT License. See LICENSE file.
+"""
+Memory — Jarvis never forgets.
+
+SQLite + FTS5. Persistent across sessions.
+Facts (key-value), Journal (timeline), Skills (learned patterns).
+"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+import time
+from pathlib import Path
+from typing import Any
+
+from ..types import ToolCategory
+
+
+class Memory:
+    """Persistent memory. Survives reboots. Searchable."""
+
+    __slots__ = ("_db", "_path")
+
+    def __init__(self, path: str = "~/.jarvis/memory.db") -> None:
+        self._path = Path(path).expanduser()
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        self._db = sqlite3.connect(str(self._path), check_same_thread=False)
+        self._db.execute("PRAGMA journal_mode=WAL")
+        self._db.execute("PRAGMA synchronous=NORMAL")
+        self._init()
+
+    def _init(self) -> None:
+        self._db.executescript("""
+            CREATE TABLE IF NOT EXISTS facts (
+                key TEXT PRIMARY KEY,
+                value TEXT NOT NULL,
+                category TEXT NOT NULL DEFAULT 'general',
+                updated_at REAL NOT NULL
+            );
+            CREATE TABLE IF NOT EXISTS journal (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                ts REAL NOT NULL,
+                event TEXT NOT NULL,
+                detail TEXT NOT NULL DEFAULT '',
+                node TEXT NOT NULL DEFAULT 'local'
+            );
+            CREATE TABLE IF NOT EXISTS skills (
+                name TEXT PRIMARY KEY,
+                trigger_pattern TEXT NOT NULL,
+                actions TEXT NOT NULL,
+                times_used INTEGER NOT NULL DEFAULT 0,
+                created_at REAL NOT NULL
+            );
+        """)
+        # FTS5 for full-text search (safe to call multiple times)
+        try:
+            self._db.execute(
+                "CREATE VIRTUAL TABLE IF NOT EXISTS facts_fts "
+                "USING fts5(key, value, category)"
+            )
+        except sqlite3.OperationalError:
+            pass  # Already exists or FTS5 not available
+        self._db.commit()
+
+    # ─── Facts ──────────────────────────────────────
+
+    def remember(self, key: str, value: Any, category: str = "general") -> None:
+        v = json.dumps(value) if not isinstance(value, str) else value
+        now = time.time()
+        self._db.execute(
+            "INSERT OR REPLACE INTO facts (key, value, category, updated_at) VALUES (?, ?, ?, ?)",
+            (key, v, category, now),
+        )
+        # Sync FTS
+        try:
+            self._db.execute("DELETE FROM facts_fts WHERE key = ?", (key,))
+            self._db.execute("INSERT INTO facts_fts (key, value, category) VALUES (?, ?, ?)", (key, v, category))
+        except sqlite3.OperationalError:
+            pass
+        self._db.commit()
+
+    def recall(self, key: str) -> str | None:
+        row = self._db.execute("SELECT value FROM facts WHERE key = ?", (key,)).fetchone()
+        return row[0] if row else None
+
+    def forget(self, key: str) -> bool:
+        cur = self._db.execute("DELETE FROM facts WHERE key = ?", (key,))
+        self._db.commit()
+        return cur.rowcount > 0
+
+    def search(self, query: str, limit: int = 10) -> list[dict[str, str]]:
+        """Full-text search. Falls back to LIKE if FTS5 unavailable."""
+        try:
+            rows = self._db.execute(
+                "SELECT key, value, category FROM facts_fts WHERE facts_fts MATCH ? LIMIT ?",
+                (query, limit),
+            ).fetchall()
+        except sqlite3.OperationalError:
+            like = f"%{query}%"
+            rows = self._db.execute(
+                "SELECT key, value, category FROM facts WHERE key LIKE ? OR value LIKE ? LIMIT ?",
+                (like, like, limit),
+            ).fetchall()
+        return [{"key": r[0], "value": r[1], "category": r[2]} for r in rows]
+
+    def facts(self, category: str | None = None) -> list[dict[str, str]]:
+        if category:
+            rows = self._db.execute(
+                "SELECT key, value, category FROM facts WHERE category = ? ORDER BY updated_at DESC",
+                (category,),
+            ).fetchall()
+        else:
+            rows = self._db.execute(
+                "SELECT key, value, category FROM facts ORDER BY updated_at DESC"
+            ).fetchall()
+        return [{"key": r[0], "value": r[1], "category": r[2]} for r in rows]
+
+    # ─── Journal ────────────────────────────────────
+
+    def log(self, event: str, detail: str = "", node: str = "local") -> None:
+        self._db.execute(
+            "INSERT INTO journal (ts, event, detail, node) VALUES (?, ?, ?, ?)",
+            (time.time(), event, detail, node),
+        )
+        self._db.commit()
+
+    def recent(self, n: int = 20) -> list[dict[str, Any]]:
+        rows = self._db.execute(
+            "SELECT ts, event, detail, node FROM journal ORDER BY id DESC LIMIT ?", (n,)
+        ).fetchall()
+        return [{"ts": r[0], "event": r[1], "detail": r[2], "node": r[3]} for r in rows]
+
+    # ─── Skills ─────────────────────────────────────
+
+    def learn(self, name: str, trigger: str, actions: list[str]) -> None:
+        self._db.execute(
+            "INSERT OR REPLACE INTO skills (name, trigger_pattern, actions, times_used, created_at) "
+            "VALUES (?, ?, ?, 0, ?)",
+            (name, trigger, json.dumps(actions), time.time()),
+        )
+        self._db.commit()
+
+    def get_skill(self, name: str) -> dict[str, Any] | None:
+        row = self._db.execute(
+            "SELECT name, trigger_pattern, actions, times_used FROM skills WHERE name = ?",
+            (name,),
+        ).fetchone()
+        if row:
+            return {"name": row[0], "trigger": row[1], "actions": json.loads(row[2]), "used": row[3]}
+        return None
+
+    def close(self) -> None:
+        self._db.close()
+
+
+# ─── Tool wrappers ──────────────────────────────────
+
+_instance: Memory | None = None
+
+def _mem() -> Memory:
+    global _instance
+    if _instance is None:
+        _instance = Memory()
+    return _instance
+
+
+def tool_remember(args: dict[str, Any], node: Any) -> str:
+    _mem().remember(args["key"], args["value"], args.get("category", "general"))
+    return "remembered"
+
+def tool_recall(args: dict[str, Any], node: Any) -> str | None:
+    return _mem().recall(args["key"])
+
+def tool_forget(args: dict[str, Any], node: Any) -> str:
+    ok = _mem().forget(args["key"])
+    return "forgotten" if ok else "not found"
+
+def tool_search(args: dict[str, Any], node: Any) -> list[dict[str, str]]:
+    return _mem().search(args["query"], args.get("limit", 10))
+
+def tool_log(args: dict[str, Any], node: Any) -> str:
+    _mem().log(args["event"], args.get("detail", ""), args.get("node", "local"))
+    return "logged"
+
+def tool_journal(args: dict[str, Any], node: Any) -> list[dict[str, Any]]:
+    return _mem().recent(args.get("n", 20))
+
+
+def register_memory(engine: Any) -> None:
+    """Plug memory tools into the engine."""
+    reg = engine.registry
+    reg.register_tool("remember", tool_remember, ToolCategory.MEMORY, "Store a fact")
+    reg.register_tool("recall", tool_recall, ToolCategory.MEMORY, "Recall a fact by key")
+    reg.register_tool("forget", tool_forget, ToolCategory.MEMORY, "Remove a fact")
+    reg.register_tool("search_memory", tool_search, ToolCategory.MEMORY, "Search all memory")
+    reg.register_tool("log_event", tool_log, ToolCategory.MEMORY, "Log an event")
+    reg.register_tool("journal", tool_journal, ToolCategory.MEMORY, "Recent events")
+

halyn/nrp_bridge.py

@@ -0,0 +1,213 @@
+# Copyright (c) 2026 Elmadani SALKA. All rights reserved.
+# Licensed under the MIT License. See LICENSE file.
+"""
+NRP Bridge v2 — Connects Driver + Identity + Manifest + Events to Engine.
+
+This is the integration layer. One function does everything:
+  1. Connects the driver
+  2. Reads the manifest (auto-description)
+  3. Generates engine tools from manifest
+  4. Wires events
+  5. Enforces shield rules from manifest
+
+After registration, the AI sees the node and knows everything about it.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from nrp import NRPDriver, ShieldRule, ShieldType
+from .engine import Engine
+from nrp import NRPId
+from nrp import NRPManifest
+from nrp import EventBus, NRPEvent, Severity
+from .types import Node, NodeKind, ToolCategory, ActionStatus
+
+log = logging.getLogger("jarvis.nrp")
+
+NODE_KIND_MAP: dict[str, NodeKind] = {
+    "ssh": NodeKind.SSH, "adb": NodeKind.ADB, "docker": NodeKind.DOCKER,
+    "ros2": NodeKind.LOCAL, "unitree": NodeKind.LOCAL, "mqtt": NodeKind.LOCAL,
+    "dji": NodeKind.LOCAL, "browser": NodeKind.LOCAL, "opcua": NodeKind.LOCAL,
+    "http": NodeKind.LOCAL, "serial": NodeKind.LOCAL,
+}
+
+
+async def register_nrp_node(
+    engine: Engine,
+    nrp_id: NRPId | str,
+    driver: NRPDriver,
+    event_bus: EventBus | None = None,
+) -> NRPManifest:
+    """
+    Register a device into the engine via NRP.
+
+    Primary registration entry point.
+    Returns the manifest for inspection/logging.
+    """
+    # 1. Parse ID
+    if isinstance(nrp_id, str):
+        nrp_id = NRPId.parse(nrp_id)
+    node_name = nrp_id.short  # "robot/g1-01"
+
+    # 2. Bind events
+    bus = event_bus or EventBus()
+    driver.bind(nrp_id, bus)
+
+    # 3. Connect
+    alive = await driver.connect()
+    if not alive:
+        log.warning("nrp.connect_failed id=%s", nrp_id.uri)
+
+    # 4. Read manifest
+    manifest = driver.manifest()
+    log.info("nrp.manifest id=%s observe=%d act=%d shield=%d",
+             nrp_id.uri, len(manifest.observe), len(manifest.act), len(manifest.shield))
+
+    # 5. Register node
+    kind_str = nrp_id.kind
+    kind = NODE_KIND_MAP.get(kind_str, NodeKind.LOCAL)
+    node = Node(
+        name=node_name, kind=kind, alive=alive,
+        labels={"nrp_id": nrp_id.uri, "nrp_kind": kind_str,
+                "manufacturer": manifest.manufacturer, "model": manifest.model},
+    )
+    engine.registry.register_node(node)
+
+    # 6. Get shield rules for enforcement
+    shield_rules = driver.shield_rules()
+
+    # 7. Register observe tool (reads all or specific channels)
+    async def _observe(args: dict[str, Any], target: Any) -> dict[str, Any]:
+        channels = args.get("channels")
+        if isinstance(channels, str):
+            channels = [c.strip() for c in channels.split(",")]
+        return await driver.observe(channels)
+
+    engine.registry.register_tool(
+        f"{node_name}.observe", _observe, ToolCategory.OBSERVER,
+        f"Observe {nrp_id.uri} — {_describe_observe(manifest)}",
+    )
+
+    # 8. Register act tool (with shield enforcement)
+    async def _act(args: dict[str, Any], target: Any) -> Any:
+        command = args.get("command", "")
+        cmd_args = {k: v for k, v in args.items() if k != "command"}
+        # Enforce shield rules
+        violation = _check_shield(command, cmd_args, shield_rules)
+        if violation:
+            log.warning("nrp.shield_blocked id=%s cmd=%s rule=%s",
+                       nrp_id.uri, command, violation)
+            await driver.emit("shield_blocked", Severity.WARNING,
+                            command=command, rule=violation)
+            raise PermissionError(f"Shield blocked: {violation}")
+        result = await driver.act(command, cmd_args)
+        return result
+
+    engine.registry.register_tool(
+        f"{node_name}.act", _act, ToolCategory.EXECUTOR,
+        f"Act on {nrp_id.uri} — {_describe_act(manifest)}", dangerous=True,
+    )
+
+    # 9. Register individual action shortcuts
+    for action_spec in manifest.act:
+        aname = action_spec.name
+
+        async def _shortcut(args: dict[str, Any], target: Any, _cmd: str = aname) -> Any:
+            return await _act({"command": _cmd, **args}, target)
+
+        engine.registry.register_tool(
+            f"{node_name}.{aname}", _shortcut, ToolCategory.EXECUTOR,
+            action_spec.description or f"{aname} on {nrp_id.short}",
+            dangerous=action_spec.dangerous,
+        )
+
+    # 10. Register shield info tool
+    def _shield_info(args: dict[str, Any], target: Any) -> list[dict[str, Any]]:
+        return [s.to_dict() for s in manifest.shield]
+
+    engine.registry.register_tool(
+        f"{node_name}.shield", _shield_info, ToolCategory.OBSERVER,
+        f"Safety rules for {nrp_id.uri}",
+    )
+
+    # 11. Register manifest tool (the AI can inspect the full description)
+    def _manifest_info(args: dict[str, Any], target: Any) -> str:
+        return manifest.to_llm_description()
+
+    engine.registry.register_tool(
+        f"{node_name}.info", _manifest_info, ToolCategory.OBSERVER,
+        f"Full description of {nrp_id.uri}",
+    )
+
+    # 12. Heartbeat
+    async def _heartbeat(args: dict[str, Any], target: Any) -> dict[str, Any]:
+        return await driver.heartbeat()
+
+    engine.registry.register_tool(
+        f"{node_name}.heartbeat", _heartbeat, ToolCategory.OBSERVER,
+        f"Health check {nrp_id.uri}",
+    )
+
+    # 13. Log registration event
+    await bus.emit_simple(nrp_id.uri, "node_registered", Severity.INFO,
+                          alive=alive, tools=len(manifest.act) + 4,
+                          observe_channels=len(manifest.observe))
+
+    tool_count = len(manifest.act) + 4  # observe + act + shield + info + heartbeat + shortcuts
+    log.info("nrp.registered id=%s alive=%s tools=%d", nrp_id.uri, alive, tool_count)
+
+    return manifest
+
+
+# ─── Shield enforcement ─────────────────────────────
+
+def _check_shield(command: str, args: dict[str, Any], rules: list[ShieldRule]) -> str | None:
+    """Check if a command violates any shield rule. Returns rule name or None."""
+    for rule in rules:
+        if rule.type == ShieldType.PATTERN:
+            pattern = str(rule.value).lower()
+            cmd_lower = command.lower() + " " + " ".join(str(v) for v in args.values()).lower()
+            if pattern in cmd_lower:
+                return rule.name
+
+        elif rule.type == ShieldType.LIMIT:
+            # Check if any numeric arg exceeds the limit
+            limit_val = float(rule.value) if rule.value is not None else None
+            if limit_val is not None:
+                for v in args.values():
+                    try:
+                        if abs(float(v)) > limit_val:
+                            return rule.name
+                    except (TypeError, ValueError):
+                        pass
+
+        elif rule.type == ShieldType.THRESHOLD:
+            # Threshold = minimum value. Below = blocked.
+            thresh = float(rule.value) if rule.value is not None else None
+            if thresh is not None and "battery" in rule.name.lower():
+                # Battery threshold checked at observe time, not act time
+                pass
+
+    return None
+
+
+# ─── Description helpers ────────────────────────────
+
+def _describe_observe(m: NRPManifest) -> str:
+    if not m.observe:
+        return "no channels"
+    names = [c.name for c in m.observe[:5]]
+    more = f" +{len(m.observe) - 5} more" if len(m.observe) > 5 else ""
+    return "channels: " + ", ".join(names) + more
+
+
+def _describe_act(m: NRPManifest) -> str:
+    if not m.act:
+        return "no actions"
+    names = [a.name for a in m.act[:5]]
+    more = f" +{len(m.act) - 5} more" if len(m.act) > 5 else ""
+    return "commands: " + ", ".join(names) + more
+

halyn/sanitizer.py

@@ -0,0 +1,120 @@
+# Copyright (c) 2026 Elmadani SALKA. All rights reserved.
+# Licensed under the MIT License. See LICENSE file.
+"""
+Sanitizer — Clean all inputs before execution.
+
+Prevents: command injection, path traversal, output flooding.
+Applied BEFORE the shield, BEFORE the driver.
+"""
+
+from __future__ import annotations
+
+import re
+import logging
+from typing import Any
+
+log = logging.getLogger("jarvis.sanitizer")
+
+# Max output size to prevent OOM
+MAX_OUTPUT_BYTES: int = 1_048_576  # 1MB
+
+# Max timeout any user can request
+MAX_TIMEOUT: int = 300  # 5 minutes
+
+# Shell injection patterns (beyond what shield catches)
+INJECTION_PATTERNS: tuple[str, ...] = (
+    "$(", "`",           # Command substitution
+    " | ", " || ",       # Pipe to another command
+    " ; ",               # Command chaining
+    " && ",              # Conditional chaining
+    "\n",               # Newline injection
+    ">> /etc/", "> /etc/",  # Write to system files
+    "curl ", "wget ",    # Download and execute
+    "nc ", "ncat ",      # Netcat reverse shells
+    "python -c", "python3 -c",  # Inline code execution
+    "perl -e", "ruby -e",
+    "base64 -d",         # Decode hidden payloads
+)
+
+# Path traversal patterns
+PATH_TRAVERSAL: tuple[str, ...] = (
+    "..",
+    "~root",
+    "/etc/shadow",
+    "/etc/passwd",
+    "/proc/",
+    "/sys/",
+)
+
+
+def sanitize_action(tool: str, args: dict[str, Any]) -> dict[str, Any]:
+    """
+    Sanitize action arguments. Returns cleaned args.
+    Raises ValueError if dangerous.
+    """
+    args = dict(args)  # Don't mutate original
+
+    # Cap timeout everywhere
+    if "timeout" in args:
+        args["timeout"] = min(int(args["timeout"]), MAX_TIMEOUT)
+
+    # Cap output limit
+    if "limit" in args:
+        args["limit"] = min(int(args["limit"]), MAX_OUTPUT_BYTES)
+    if "lines" in args:
+        args["lines"] = min(int(args["lines"]), 500)
+    if "n" in args and isinstance(args["n"], int):
+        args["n"] = min(args["n"], 500)
+
+    # Shell command sanitization
+    if tool in ("shell",) and "command" in args:
+        cmd = args["command"]
+        _check_injection(cmd)
+
+    # File path sanitization
+    if "path" in args:
+        path = str(args["path"])
+        _check_path(path)
+
+    return args
+
+
+def sanitize_output(data: Any) -> Any:
+    """Truncate output to prevent OOM."""
+    if isinstance(data, str) and len(data) > MAX_OUTPUT_BYTES:
+        truncated = data[:MAX_OUTPUT_BYTES]
+        log.warning("sanitizer.output_truncated original=%d", len(data))
+        return truncated + f"\n... [truncated, {len(data)} bytes total]"
+    return data
+
+
+def _check_injection(cmd: str) -> None:
+    """Check for shell injection patterns in non-shell tools."""
+    # For the "shell" tool, we ALLOW these (that's the point of shell).
+    # But we LOG them for the audit trail.
+    for pattern in INJECTION_PATTERNS:
+        if pattern in cmd:
+            log.info("sanitizer.injection_pattern cmd=%s pattern=%s", cmd[:100], pattern)
+            # We don't block — shield handles dangerous patterns.
+            # We just make sure the audit knows.
+            return
+
+
+def _check_path(path: str) -> None:
+    """Block path traversal."""
+    for pattern in PATH_TRAVERSAL:
+        if pattern in path:
+            raise ValueError(f"path traversal blocked: {pattern}")
+
+
+def redact_error(error: str) -> str:
+    """Remove sensitive info from error messages before sending to client."""
+    # Remove file paths
+    error = re.sub(r"/[\w/.-]+\.(?:pem|key|crt|conf|env)", "[REDACTED_PATH]", error)
+    # Remove IP:port patterns that might reveal internal topology
+    error = re.sub(r"\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}:\d+", "[REDACTED_HOST]", error)
+    # Remove potential credentials
+    error = re.sub(r"(?:password|passwd|token|secret|key)[\s=:]+\S+", "[REDACTED]", error, flags=re.IGNORECASE)
+    # Limit length
+    return error[:300]
+