Neuro-Rift · Neuro-Rift · Mar 14, 2026 · Mar 14, 2026 · codeant-ai · Mar 14, 2026
diff --git a/model_capability_check.py b/model_capability_check.py
@@ -0,0 +1,92 @@
+"""Ollama model capability verification for autonomous NeuroRift agent mode."""
+from __future__ import annotations
+
+import json
+import subprocess
+from typing import Any
+
+CAPABILITY_PROMPT = """Evaluate whether you can reliably perform the following tasks:
+
+* structured tool invocation
+* Linux command generation
+* file creation and modification
+* interpreting tool outputs
+* multi-step reasoning for autonomous agents
+
+Return a JSON response:
+{
+"tool_usage": true/false,
+"command_generation": true/false,
+"filesystem_operations": true/false,
+"multi_step_reasoning": true/false,
+"agent_ready": true/false
+}"""
+
+
+def _extract_json(raw_text: str) -> dict[str, Any]:
+    raw_text = (raw_text or "").strip()
+    start = raw_text.find("{")
+    end = raw_text.rfind("}")
+    if start == -1 or end == -1 or end <= start:
+        raise ValueError("No JSON object found in model response")
+    return json.loads(raw_text[start : end + 1])
-    start = raw_text.find("{")
-    end = raw_text.rfind("}")
-    if start == -1 or end == -1 or end <= start:
-        raise ValueError("No JSON object found in model response")
-    return json.loads(raw_text[start : end + 1])
+    decoder = json.JSONDecoder()
+    for idx, char in enumerate(raw_text):
+        if char != "{":
+            continue
+        try:
+            parsed, _ = decoder.raw_decode(raw_text[idx:])
+        except json.JSONDecodeError:
+            continue
+        if isinstance(parsed, dict):
+            return parsed
+    raise ValueError("No JSON object found in model response")
-    start = raw_text.find("{")
-    end = raw_text.rfind("}")
-    if start == -1 or end == -1 or end <= start:
-        raise ValueError("No JSON object found in model response")
-    return json.loads(raw_text[start : end + 1])
+    decoder = json.JSONDecoder()
+    for idx, char in enumerate(raw_text):
+        if char != "{":
+            continue
+        try:
+            parsed, _ = decoder.raw_decode(raw_text[idx:])
+        except json.JSONDecodeError:
+            continue
+        if isinstance(parsed, dict):
+            return parsed
+    raise ValueError("No JSON object found in model response")
+
+
+def verify_model_capabilities(model_name: str) -> dict[str, Any]:
+    try:
+        proc = subprocess.run(
+            ["ollama", "run", model_name, CAPABILITY_PROMPT],
+            capture_output=True,
+            text=True,
+            timeout=120,
+            check=False,
+        )
+    except FileNotFoundError:
+        return {"ok": False, "error": "ollama_missing", "agent_ready": False}
+    except Exception as exc:  # defensive for unstable environments
+        return {"ok": False, "error": f"ollama_exec_error:{type(exc).__name__}", "agent_ready": False}
+
+    if proc.returncode != 0:
+        return {
+            "ok": False,
+            "error": f"ollama_returned_{proc.returncode}",
+            "stderr": proc.stderr,
+            "agent_ready": False,
+        }
+
+    try:
+        parsed = _extract_json(proc.stdout)
+    except Exception as exc:
+        return {
+            "ok": False,
+            "error": f"invalid_capability_json:{type(exc).__name__}",
+            "raw": proc.stdout[:1000],
+            "agent_ready": False,
+        }
+
+    required = {
+        "tool_usage",
+        "command_generation",
+        "filesystem_operations",
+        "multi_step_reasoning",
+        "agent_ready",
+    }
+    if not required.issubset(parsed):
+        return {
+            "ok": False,
+            "error": "capability_fields_missing",
+            "parsed": parsed,
+            "agent_ready": False,
+        }
+
+    parsed["ok"] = bool(parsed.get("agent_ready"))
+    return parsed
-    required = {
-        "tool_usage",
-        "command_generation",
-        "filesystem_operations",
-        "multi_step_reasoning",
-        "agent_ready",
-    }
-    if not required.issubset(parsed):
-        return {
-            "ok": False,
-            "error": "capability_fields_missing",
-            "parsed": parsed,
-            "agent_ready": False,
-        }
-
-    parsed["ok"] = bool(parsed.get("agent_ready"))
-    return parsed
+    required = {
+        "tool_usage",
+        "command_generation",
+        "filesystem_operations",
+        "multi_step_reasoning",
+        "agent_ready",
+    }
+    if not isinstance(parsed, dict) or not required.issubset(parsed):
+        return {
+            "ok": False,
+            "error": "capability_fields_missing",
+            "parsed": parsed,
+            "agent_ready": False,
+        }
+
+    for field in required:
+        if not isinstance(parsed.get(field), bool):
+            return {
+                "ok": False,
+                "error": f"capability_field_not_boolean:{field}",
+                "parsed": parsed,
+                "agent_ready": False,
+            }
+
+    parsed["ok"] = parsed["agent_ready"]
+    return parsed
-    required = {
-        "tool_usage",
-        "command_generation",
-        "filesystem_operations",
-        "multi_step_reasoning",
-        "agent_ready",
-    }
-    if not required.issubset(parsed):
-        return {
-            "ok": False,
-            "error": "capability_fields_missing",
-            "parsed": parsed,
-            "agent_ready": False,
-        }
-
-    parsed["ok"] = bool(parsed.get("agent_ready"))
-    return parsed
+    required = {
+        "tool_usage",
+        "command_generation",
+        "filesystem_operations",
+        "multi_step_reasoning",
+        "agent_ready",
+    }
+    if not isinstance(parsed, dict) or not required.issubset(parsed):
+        return {
+            "ok": False,
+            "error": "capability_fields_missing",
+            "parsed": parsed,
+            "agent_ready": False,
+        }
+
+    for field in required:
+        if not isinstance(parsed.get(field), bool):
+            return {
+                "ok": False,
+                "error": f"capability_field_not_boolean:{field}",
+                "parsed": parsed,
+                "agent_ready": False,
+            }
+
+    parsed["ok"] = parsed["agent_ready"]
+    return parsed
+
+
+if __name__ == "__main__":
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Check Ollama model capability for NeuroRift agent mode")
+    parser.add_argument("--model", required=True)
+    args = parser.parse_args()
+    print(json.dumps(verify_model_capabilities(args.model), indent=2))
diff --git a/neurorift/__init__.py b/neurorift/__init__.py
@@ -0,0 +1 @@
+
diff --git a/neurorift/channels/__init__.py b/neurorift/channels/__init__.py
@@ -0,0 +1 @@
+
diff --git a/neurorift/channels/channel_router.py b/neurorift/channels/channel_router.py
@@ -0,0 +1,2 @@
+class ChannelRouter:
+    def route(self, msg: dict): return msg
diff --git a/neurorift/channels/cli_channel.py b/neurorift/channels/cli_channel.py
@@ -0,0 +1,5 @@
+class Channel:
+    def connect(self): return True
+    def receive_message(self, payload=None): return payload or {}
+    def send_message(self, message): return message
+    def close(self): return True
diff --git a/neurorift/channels/discord_channel.py b/neurorift/channels/discord_channel.py
@@ -0,0 +1,5 @@
+class Channel:
+    def connect(self): return True
+    def receive_message(self, payload=None): return payload or {}
+    def send_message(self, message): return message
+    def close(self): return True
diff --git a/neurorift/channels/telegram_channel.py b/neurorift/channels/telegram_channel.py
@@ -0,0 +1,5 @@
+class Channel:
+    def connect(self): return True
+    def receive_message(self, payload=None): return payload or {}
+    def send_message(self, message): return message
+    def close(self): return True
diff --git a/neurorift/channels/web_channel.py b/neurorift/channels/web_channel.py
@@ -0,0 +1,5 @@
+class Channel:
+    def connect(self): return True
+    def receive_message(self, payload=None): return payload or {}
-    def receive_message(self, payload=None): return payload or {}
+    def receive_message(self, payload=None): return {} if payload is None else payload
-    def receive_message(self, payload=None): return payload or {}
+    def receive_message(self, payload=None): return {} if payload is None else payload
+    def send_message(self, message): return message
+    def close(self): return True
diff --git a/neurorift/clawhub/__init__.py b/neurorift/clawhub/__init__.py
@@ -0,0 +1 @@
+
diff --git a/neurorift/clawhub/clawhub_api.py b/neurorift/clawhub/clawhub_api.py
@@ -0,0 +1,2 @@
+class ClawHubAPI:
+    base_url = 'https://clawhub.example/api'
diff --git a/neurorift/clawhub/clawhub_client.py b/neurorift/clawhub/clawhub_client.py
@@ -0,0 +1,11 @@
+from pathlib import Path
+import shutil
+class ClawHubClient:
+    def __init__(self, cache_dir: Path): self.cache_dir=cache_dir; cache_dir.mkdir(parents=True, exist_ok=True)
+    def fetch_skill(self, skill_name: str, source_dir: Path) -> Path:
+        src = source_dir / skill_name
-        src = source_dir / skill_name
+        skill_path = Path(skill_name)
+        if skill_path.is_absolute() or ".." in skill_path.parts or skill_path.name != skill_name:
+            raise ValueError("Invalid skill name")
+        src = source_dir / skill_path
-        src = source_dir / skill_name
+        skill_path = Path(skill_name)
+        if skill_path.is_absolute() or ".." in skill_path.parts or skill_path.name != skill_name:
+            raise ValueError("Invalid skill name")
+        src = source_dir / skill_path
+        if not src.exists(): raise FileNotFoundError(skill_name)
-        if not src.exists(): raise FileNotFoundError(skill_name)
+        if not src.is_dir():
+            raise FileNotFoundError(skill_name)
-        if not src.exists(): raise FileNotFoundError(skill_name)
+        if not src.is_dir():
+            raise FileNotFoundError(skill_name)
+        dst = self.cache_dir / skill_name
+        if dst.exists(): shutil.rmtree(dst)
+        shutil.copytree(src, dst)
+        return dst
diff --git a/neurorift/clawhub/clawhub_resolver.py b/neurorift/clawhub/clawhub_resolver.py
@@ -0,0 +1,3 @@
+class ClawHubResolver:
+    def resolve(self, skill_name: str) -> str:
+        return f'https://clawhub.example/skills/{skill_name}'
diff --git a/neurorift/cli/__init__.py b/neurorift/cli/__init__.py
@@ -0,0 +1 @@
+
diff --git a/neurorift/cli/neurorift_cli.py b/neurorift/cli/neurorift_cli.py
@@ -0,0 +1,6 @@
+"""Package-level CLI helper that delegates to global entrypoint."""
+from __future__ import annotations
+
+from neurorift_cli import build_parser, install_global_wrapper, main
+
+__all__ = ["build_parser", "install_global_wrapper", "main"]
diff --git a/neurorift/config/__init__.py b/neurorift/config/__init__.py
@@ -0,0 +1 @@
+
diff --git a/neurorift/config/channel_config.py b/neurorift/config/channel_config.py
@@ -0,0 +1 @@
+CHANNELS = ['cli','websocket','discord','telegram','api']
diff --git a/neurorift/config/model_config.py b/neurorift/config/model_config.py
@@ -0,0 +1 @@
+MODEL_PROVIDERS = ['deepseek','mistral','llama','openai']
diff --git a/neurorift/config/settings.py b/neurorift/config/settings.py
@@ -0,0 +1,5 @@
+from dataclasses import dataclass
+from pathlib import Path
+@dataclass
+class Settings:
+    data_dir: Path = Path.home()/'.neurorift'
diff --git a/neurorift/core/__init__.py b/neurorift/core/__init__.py
@@ -0,0 +1 @@
+
diff --git a/neurorift/core/agent_loop.py b/neurorift/core/agent_loop.py
@@ -0,0 +1,3 @@
+class AgentLoop:
+    async def handle_message(self, session, message: str) -> dict:
+        return {"success": True, "response": f"Session {session.session_id}: {message}"}
diff --git a/neurorift/core/agent_manager.py b/neurorift/core/agent_manager.py
@@ -0,0 +1,15 @@
+from dataclasses import dataclass
+from neurorift.core.agent_loop import AgentLoop
+from neurorift.sessions.session_manager import SessionManager
+
+@dataclass
+class AgentHandle:
+    session_id: str
+    user_id: str
+    channel: str
+
+class AgentManager:
+    def __init__(self, session_manager: SessionManager, agent_loop: AgentLoop):
+        self.session_manager = session_manager
+        self.agent_loop = agent_loop
+        self.handles: dict[str, AgentHandle] = {}
diff --git a/neurorift/core/planner.py b/neurorift/core/planner.py
@@ -0,0 +1,10 @@
+from dataclasses import dataclass
+
+@dataclass
+class PlannedStep:
+    order: int
+    action: str
+
+class Planner:
+    def create_plan(self, objective: str) -> list[PlannedStep]:
+        return [PlannedStep(order=1, action=f"Investigate: {objective}")] if objective else []
-        return [PlannedStep(order=1, action=f"Investigate: {objective}")] if objective else []
+        normalized_objective = objective.strip()
+        return [PlannedStep(order=1, action=f"Investigate: {normalized_objective}")] if normalized_objective else []
-        return [PlannedStep(order=1, action=f"Investigate: {objective}")] if objective else []
+        normalized_objective = objective.strip()
+        return [PlannedStep(order=1, action=f"Investigate: {normalized_objective}")] if normalized_objective else []
diff --git a/neurorift/core/task_router.py b/neurorift/core/task_router.py
@@ -0,0 +1,3 @@
+class TaskRouter:
+    def route(self, task: str) -> dict:
+        return {"task": task, "route": "agent_loop"}
diff --git a/neurorift/execution/__init__.py b/neurorift/execution/__init__.py
@@ -0,0 +1 @@
+
diff --git a/neurorift/execution/command_runner.py b/neurorift/execution/command_runner.py
@@ -0,0 +1,5 @@
+import subprocess
+class CommandRunner:
+    def run(self, cmd: list[str]):
+        p=subprocess.run(cmd, capture_output=True, text=True, check=False)
+        return {"success": p.returncode==0, "stdout": p.stdout, "stderr": p.stderr, "exit_code": p.returncode}
-        p=subprocess.run(cmd, capture_output=True, text=True, check=False)
-        return {"success": p.returncode==0, "stdout": p.stdout, "stderr": p.stderr, "exit_code": p.returncode}
+        try:
+            p = subprocess.run(cmd, capture_output=True, text=True, check=False, timeout=30)
+            return {"success": p.returncode == 0, "stdout": p.stdout, "stderr": p.stderr, "exit_code": p.returncode}
+        except subprocess.TimeoutExpired:
+            return {"success": False, "stdout": "", "stderr": "Command timed out", "exit_code": 124}
-        p=subprocess.run(cmd, capture_output=True, text=True, check=False)
-        return {"success": p.returncode==0, "stdout": p.stdout, "stderr": p.stderr, "exit_code": p.returncode}
+        try:
+            p = subprocess.run(cmd, capture_output=True, text=True, check=False, timeout=30)
+            return {"success": p.returncode == 0, "stdout": p.stdout, "stderr": p.stderr, "exit_code": p.returncode}
+        except subprocess.TimeoutExpired:
+            return {"success": False, "stdout": "", "stderr": "Command timed out", "exit_code": 124}
diff --git a/neurorift/execution/resource_limits.py b/neurorift/execution/resource_limits.py
@@ -0,0 +1,6 @@
+from dataclasses import dataclass
+@dataclass
+class ResourceLimits:
+    timeout_seconds:int=30
+    memory_limit_mb:int=512
+    cpu_seconds:int=20
diff --git a/neurorift/execution/retry_manager.py b/neurorift/execution/retry_manager.py
@@ -0,0 +1,4 @@
+import time
+class RetryManager:
+    def __init__(self, retries=2): self.retries=retries
+    def wait(self, attempt): time.sleep(2**attempt)
diff --git a/neurorift/execution/sandbox_runner.py b/neurorift/execution/sandbox_runner.py
@@ -0,0 +1,3 @@
+from neurorift.execution.command_runner import CommandRunner
+class SandboxRunner(CommandRunner):
+    pass
diff --git a/neurorift/gateway/__init__.py b/neurorift/gateway/__init__.py
@@ -0,0 +1 @@
+
diff --git a/neurorift/gateway/api_server.py b/neurorift/gateway/api_server.py
@@ -0,0 +1,2 @@
+class APIServer:
+    def start(self): return True
diff --git a/neurorift/gateway/auth_manager.py b/neurorift/gateway/auth_manager.py
@@ -0,0 +1,2 @@
+class AuthManager:
+    def validate(self, token: str): return bool(token)
diff --git a/neurorift/gateway/websocket_gateway.py b/neurorift/gateway/websocket_gateway.py
@@ -0,0 +1,2 @@
+class WebSocketGateway:
+    def start(self): return True
diff --git a/neurorift/memory/__init__.py b/neurorift/memory/__init__.py
@@ -0,0 +1 @@
+
diff --git a/neurorift/memory/long_term_memory.py b/neurorift/memory/long_term_memory.py
@@ -0,0 +1,3 @@
+class LongTermMemory:
+    def __init__(self): self.data={}
+    def store(self, user_id: str, key: str, value): self.data.setdefault(user_id,{})[key]=value
diff --git a/neurorift/memory/memory_compaction.py b/neurorift/memory/memory_compaction.py
@@ -0,0 +1,2 @@
+class MemoryCompaction:
+    def compact(self, messages: list[str]): return {"summary": " ".join(messages[:10]), "kept": messages[-10:]}
diff --git a/neurorift/memory/short_term_memory.py b/neurorift/memory/short_term_memory.py
@@ -0,0 +1,4 @@
+from collections import defaultdict, deque
+class ShortTermMemory:
+    def __init__(self, limit: int = 30): self.buffers=defaultdict(lambda: deque(maxlen=limit))
+    def add(self, sid: str, msg: str): self.buffers[sid].append(msg)
diff --git a/neurorift/memory/vector_memory.py b/neurorift/memory/vector_memory.py
@@ -0,0 +1,3 @@
+class VectorMemory:
+    def semantic_search(self, user_id: str, query: str, top_k: int = 5): return []
+    def time_based_retrieval(self, user_id: str, limit: int = 10): return []
diff --git a/neurorift/models/__init__.py b/neurorift/models/__init__.py
@@ -0,0 +1 @@
+
diff --git a/neurorift/models/context_builder.py b/neurorift/models/context_builder.py
@@ -0,0 +1,2 @@
+class ContextBuilder:
+    def build(self, session, memories): return {"session": session.session_id, "memories": memories}
diff --git a/neurorift/models/model_failover.py b/neurorift/models/model_failover.py
@@ -0,0 +1,2 @@
+class ModelFailover:
+    def pick(self, providers): return providers[0] if providers else "fallback"
diff --git a/neurorift/models/model_router.py b/neurorift/models/model_router.py
@@ -0,0 +1,2 @@
+class ModelRouter:
+    async def generate(self, prompt: str): return {"response": prompt, "model": "openai", "tokens": len(prompt.split()), "cost": 0.0}
diff --git a/neurorift/models/prompt_builder.py b/neurorift/models/prompt_builder.py
@@ -0,0 +1,2 @@
+class PromptBuilder:
+    def build(self, message: str, context: dict): return f"{context}\n{message}"
diff --git a/neurorift/sessions/__init__.py b/neurorift/sessions/__init__.py
@@ -0,0 +1 @@
+
diff --git a/neurorift/sessions/session_context.py b/neurorift/sessions/session_context.py
@@ -0,0 +1,19 @@
+from dataclasses import dataclass, field
+from enum import Enum
+from datetime import datetime, timezone
+
+class SessionState(str, Enum):
+    CREATED="CREATED"; ACTIVE="ACTIVE"; IDLE="IDLE"; PAUSED="PAUSED"; CLOSED="CLOSED"
+
+@dataclass
+class SessionContext:
+    session_id: str
+    user_id: str
+    channel: str
+    state: SessionState = SessionState.CREATED
+    message_history: list[dict] = field(default_factory=list)
+    tool_usage: list[dict] = field(default_factory=list)
+    context_window: list[str] = field(default_factory=list)
+    memory_references: list[str] = field(default_factory=list)
+    created_at: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+    updated_at: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
-    updated_at: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+    updated_at: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+
+    def __post_init__(self):
+        if isinstance(self.state, str):
+            self.state = SessionState(self.state)
-    updated_at: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+    updated_at: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+
+    def __post_init__(self):
+        if isinstance(self.state, str):
+            self.state = SessionState(self.state)
diff --git a/neurorift/sessions/session_manager.py b/neurorift/sessions/session_manager.py
@@ -0,0 +1,13 @@
+import uuid
+from pathlib import Path
+from neurorift.sessions.session_context import SessionContext, SessionState
+from neurorift.sessions.session_store import SessionStore
+
+class SessionManager:
+    def __init__(self, root: Path):
+        self.store = SessionStore(root)
+        self.sessions: dict[str, SessionContext] = {}
+    def create_session(self, user_id: str, channel: str) -> SessionContext:
+        sid=str(uuid.uuid4()); s=SessionContext(session_id=sid,user_id=user_id,channel=channel,state=SessionState.ACTIVE)
+        self.sessions[sid]=s; self.store.save(s); return s
-        self.sessions[sid]=s; self.store.save(s); return s
+        self.store.save(s); self.sessions[sid]=s; return s
-        self.sessions[sid]=s; self.store.save(s); return s
+        self.store.save(s); self.sessions[sid]=s; return s
+    def get_session(self, sid: str): return self.sessions.get(sid) or self.store.load(sid)
-    def get_session(self, sid: str): return self.sessions.get(sid) or self.store.load(sid)
+    def get_session(self, sid: str):
+        session = self.sessions.get(sid) or self.store.load(sid)
+        if session and isinstance(session.state, str):
+            session.state = SessionState(session.state)
+        return session
-    def get_session(self, sid: str): return self.sessions.get(sid) or self.store.load(sid)
+    def get_session(self, sid: str):
+        session = self.sessions.get(sid) or self.store.load(sid)
+        if session and isinstance(session.state, str):
+            session.state = SessionState(session.state)
+        return session
diff --git a/neurorift/sessions/session_pruner.py b/neurorift/sessions/session_pruner.py
@@ -0,0 +1,3 @@
+class SessionPruner:
+    def prune(self, sessions: dict, max_idle_hours: int = 24) -> list[str]:
+        return []
diff --git a/neurorift/sessions/session_store.py b/neurorift/sessions/session_store.py
@@ -0,0 +1,12 @@
+import json
+from pathlib import Path
+from neurorift.sessions.session_context import SessionContext
+
+class SessionStore:
+    def __init__(self, root: Path):
+        self.root = root; self.root.mkdir(parents=True, exist_ok=True)
+    def path(self, sid: str) -> Path: return self.root / f"{sid}.json"
-    def path(self, sid: str) -> Path: return self.root / f"{sid}.json"
+    def path(self, sid: str) -> Path:
+        candidate = (self.root / f"{sid}.json").resolve()
+        root_resolved = self.root.resolve()
+        if root_resolved not in candidate.parents:
+            raise ValueError("Invalid session id")
+        return candidate
-    def path(self, sid: str) -> Path: return self.root / f"{sid}.json"
+    def path(self, sid: str) -> Path:
+        candidate = (self.root / f"{sid}.json").resolve()
+        root_resolved = self.root.resolve()
+        if root_resolved not in candidate.parents:
+            raise ValueError("Invalid session id")
+        return candidate
+    def save(self, session: SessionContext): self.path(session.session_id).write_text(json.dumps(session.__dict__, default=str), encoding='utf-8')
+    def load(self, sid: str):
+        p=self.path(sid)
+        return SessionContext(**json.loads(p.read_text(encoding='utf-8'))) if p.exists() else None
-        p=self.path(sid)
-        return SessionContext(**json.loads(p.read_text(encoding='utf-8'))) if p.exists() else None
+        p=self.path(sid)
+                if not p.exists():
+                    return None
+                data = json.loads(p.read_text(encoding='utf-8'))
+                if "state" in data:
+                    data["state"] = SessionContext.__annotations__["state"](data["state"])
+                return SessionContext(**data)
-        p=self.path(sid)
-        return SessionContext(**json.loads(p.read_text(encoding='utf-8'))) if p.exists() else None
+        p=self.path(sid)
+                if not p.exists():
+                    return None
+                data = json.loads(p.read_text(encoding='utf-8'))
+                if "state" in data:
+                    data["state"] = SessionContext.__annotations__["state"](data["state"])
+                return SessionContext(**data)
diff --git a/neurorift/skill_store/__init__.py b/neurorift/skill_store/__init__.py
@@ -0,0 +1 @@
+
diff --git a/neurorift/skill_store/cache/__init__.py b/neurorift/skill_store/cache/__init__.py
@@ -0,0 +1 @@
+
diff --git a/neurorift/skill_store/installed/__init__.py b/neurorift/skill_store/installed/__init__.py
@@ -0,0 +1 @@
+
diff --git a/neurorift/skill_store/installed/recon_scanner/README.md b/neurorift/skill_store/installed/recon_scanner/README.md
@@ -0,0 +1 @@
+# recon_scanner
diff --git a/neurorift/skill_store/installed/recon_scanner/__init__.py b/neurorift/skill_store/installed/recon_scanner/__init__.py
@@ -0,0 +1 @@
+
diff --git a/neurorift/skill_store/installed/recon_scanner/requirements.txt b/neurorift/skill_store/installed/recon_scanner/requirements.txt
@@ -0,0 +1 @@
+requests
diff --git a/neurorift/skill_store/installed/recon_scanner/skill.json b/neurorift/skill_store/installed/recon_scanner/skill.json
@@ -0,0 +1,8 @@
+{
+  "name": "recon_scanner",
+  "version": "1.0",
+  "description": "basic reconnaissance scanner",
+  "entrypoint": "skill.py",
+  "command": "scan",
+  "dependencies": ["nmap"]
+}
diff --git a/neurorift/skill_store/installed/recon_scanner/skill.py b/neurorift/skill_store/installed/recon_scanner/skill.py
@@ -0,0 +1,2 @@
+def run(target: str = '127.0.0.1'):
+    return {'action': 'scan', 'target': target, 'status': 'simulated'}
diff --git a/neurorift/skills/__init__.py b/neurorift/skills/__init__.py
@@ -0,0 +1 @@
+
diff --git a/neurorift/skills/installer.py b/neurorift/skills/installer.py
@@ -0,0 +1,24 @@
+import json, shutil
+from pathlib import Path
+from neurorift.skills.skill_validator import SkillValidator
+from neurorift.skills.registry import SkillRegistry
+
+class SkillInstaller:
+    def __init__(self, base: Path):
+        self.base=base; self.installed=base/'installed'; self.cache=base/'cache'
+        self.installed.mkdir(parents=True, exist_ok=True); self.cache.mkdir(parents=True, exist_ok=True)
+        self.validator=SkillValidator(); self.registry=SkillRegistry(base)
+    def install(self, pkg: Path):
+        ok,missing=self.validator.validate(pkg)
+        if not ok: return {'success': False, 'error': f'missing:{missing}'}
+        meta=json.loads((pkg/'skill.json').read_text(encoding='utf-8')); name=meta['name']
-        meta=json.loads((pkg/'skill.json').read_text(encoding='utf-8')); name=meta['name']
+        try:
+            meta = json.loads((pkg / 'skill.json').read_text(encoding='utf-8'))
+            name = meta['name']
+        except (OSError, json.JSONDecodeError, KeyError):
+            return {'success': False, 'error': 'invalid skill metadata'}
-        meta=json.loads((pkg/'skill.json').read_text(encoding='utf-8')); name=meta['name']
+        try:
+            meta = json.loads((pkg / 'skill.json').read_text(encoding='utf-8'))
+            name = meta['name']
+        except (OSError, json.JSONDecodeError, KeyError):
+            return {'success': False, 'error': 'invalid skill metadata'}
+        dst=self.installed/name
+        if dst.exists(): shutil.rmtree(dst)
+        shutil.copytree(pkg,dst)
+        self.registry.add(name)
+        return {'success': True, 'name': name, 'path': str(dst)}
+    def uninstall(self, name: str):
+        dst=self.installed/name
+        if dst.exists(): shutil.rmtree(dst)
-        dst=self.installed/name
-        if dst.exists(): shutil.rmtree(dst)
+        base_dir = self.installed.resolve()
+        dst = (self.installed / name).resolve()
+        if base_dir not in dst.parents:
+            return {'success': False, 'error': 'invalid skill name'}
+        if dst.exists(): shutil.rmtree(dst)
-        dst=self.installed/name
-        if dst.exists(): shutil.rmtree(dst)
+        base_dir = self.installed.resolve()
+        dst = (self.installed / name).resolve()
+        if base_dir not in dst.parents:
+            return {'success': False, 'error': 'invalid skill name'}
+        if dst.exists(): shutil.rmtree(dst)
+        self.registry.remove(name)
+        return {'success': True, 'name': name}
diff --git a/neurorift/skills/loader.py b/neurorift/skills/loader.py
@@ -0,0 +1,9 @@
+import importlib.util, json
+from pathlib import Path
+class SkillLoader:
+    def run(self, skill_dir: Path, **kwargs):
+        meta=json.loads((skill_dir/'skill.json').read_text(encoding='utf-8'))
-        meta=json.loads((skill_dir/'skill.json').read_text(encoding='utf-8'))
+        meta_path = skill_dir / 'skill.json'
+        if not meta_path.exists():
+            return {'error': 'skill metadata not found'}
+        meta = json.loads(meta_path.read_text(encoding='utf-8'))
-        meta=json.loads((skill_dir/'skill.json').read_text(encoding='utf-8'))
+        meta_path = skill_dir / 'skill.json'
+        if not meta_path.exists():
+            return {'error': 'skill metadata not found'}
+        meta = json.loads(meta_path.read_text(encoding='utf-8'))
+        entry=skill_dir/meta['entrypoint']
-        entry=skill_dir/meta['entrypoint']
+        entry_name=str(meta.get('entrypoint','')).strip()
+        if (not entry_name) or ('.' in entry_name) or ('/' in entry_name) or ('\\' in entry_name) or (not entry_name.replace('_','').isalnum()):
+            return {'error':'invalid entrypoint'}
+        module_name=f"neurorift.skills.{entry_name}"
+        spec=importlib.util.find_spec(module_name)
+        if spec is None or spec.loader is None:
+            return {'error':'unknown skill'}
+        mod=importlib.util.module_from_spec(spec); spec.loader.exec_module(mod)
-        entry=skill_dir/meta['entrypoint']
+        entry = (skill_dir / meta['entrypoint']).resolve()
+        try:
+            entry.relative_to(skill_dir.resolve())
+        except ValueError:
+            return {'error': 'invalid entrypoint path'}
-        entry=skill_dir/meta['entrypoint']
+        entry_name=str(meta.get('entrypoint','')).strip()
+        if (not entry_name) or ('.' in entry_name) or ('/' in entry_name) or ('\\' in entry_name) or (not entry_name.replace('_','').isalnum()):
+            return {'error':'invalid entrypoint'}
+        module_name=f"neurorift.skills.{entry_name}"
+        spec=importlib.util.find_spec(module_name)
+        if spec is None or spec.loader is None:
+            return {'error':'unknown skill'}
+        mod=importlib.util.module_from_spec(spec); spec.loader.exec_module(mod)
-        entry=skill_dir/meta['entrypoint']
+        entry = (skill_dir / meta['entrypoint']).resolve()
+        try:
+            entry.relative_to(skill_dir.resolve())
+        except ValueError:
+            return {'error': 'invalid entrypoint path'}
+        spec=importlib.util.spec_from_file_location(f"skill_{meta['name']}", entry)
+        mod=importlib.util.module_from_spec(spec); spec.loader.exec_module(mod)
-        spec=importlib.util.spec_from_file_location(f"skill_{meta['name']}", entry)
-        mod=importlib.util.module_from_spec(spec); spec.loader.exec_module(mod)
+        spec = importlib.util.spec_from_file_location(f"skill_{meta['name']}", entry)
+        if spec is None or spec.loader is None:
+            return {'error': 'invalid skill entrypoint'}
+        try:
+            mod = importlib.util.module_from_spec(spec)
+            spec.loader.exec_module(mod)
+        except OSError as exc:
+            return {'error': f'failed to load skill module: {exc}'}
-        spec=importlib.util.spec_from_file_location(f"skill_{meta['name']}", entry)
-        mod=importlib.util.module_from_spec(spec); spec.loader.exec_module(mod)
+        spec = importlib.util.spec_from_file_location(f"skill_{meta['name']}", entry)
+        if spec is None or spec.loader is None:
+            return {'error': 'invalid skill entrypoint'}
+        try:
+            mod = importlib.util.module_from_spec(spec)
+            spec.loader.exec_module(mod)
+        except OSError as exc:
+            return {'error': f'failed to load skill module: {exc}'}
+        return mod.run(**kwargs) if hasattr(mod, 'run') else {'error':'missing run()'}
diff --git a/neurorift/skills/registry.py b/neurorift/skills/registry.py
@@ -0,0 +1,15 @@
+import json
+from pathlib import Path
+class SkillRegistry:
+    def __init__(self, root: Path):
+        self.path = root / 'registry.json'; root.mkdir(parents=True, exist_ok=True)
+        if not self.path.exists(): self.path.write_text(json.dumps({'installed_skills': []}, indent=2), encoding='utf-8')
+    def read(self): return json.loads(self.path.read_text(encoding='utf-8'))
-    def read(self): return json.loads(self.path.read_text(encoding='utf-8'))
+    def read(self):
+        try:
+            return json.loads(self.path.read_text(encoding='utf-8'))
+        except json.JSONDecodeError:
+            return {'installed_skills': []}
-    def read(self): return json.loads(self.path.read_text(encoding='utf-8'))
+    def read(self):
+        try:
+            return json.loads(self.path.read_text(encoding='utf-8'))
+        except json.JSONDecodeError:
+            return {'installed_skills': []}
+    def list(self): return self.read().get('installed_skills', [])
+    def add(self, name):
+        data=self.read(); skills=data.setdefault('installed_skills', [])
+        if name not in skills: skills.append(name)
+        self.path.write_text(json.dumps(data, indent=2), encoding='utf-8')
-    def add(self, name):
-        data=self.read(); skills=data.setdefault('installed_skills', [])
-        if name not in skills: skills.append(name)
-        self.path.write_text(json.dumps(data, indent=2), encoding='utf-8')
+    def add(self, name):
+        lock_path = self.path.with_suffix(".lock")
+        with lock_path.open("w", encoding="utf-8") as lock_file:
+            import fcntl
+            fcntl.flock(lock_file.fileno(), fcntl.LOCK_EX)
+            data = self.read()
+            skills = data.setdefault('installed_skills', [])
+            if name not in skills:
+                skills.append(name)
+            self.path.write_text(json.dumps(data, indent=2), encoding='utf-8')
-    def add(self, name):
-        data=self.read(); skills=data.setdefault('installed_skills', [])
-        if name not in skills: skills.append(name)
-        self.path.write_text(json.dumps(data, indent=2), encoding='utf-8')
+    def add(self, name):
+        lock_path = self.path.with_suffix(".lock")
+        with lock_path.open("w", encoding="utf-8") as lock_file:
+            import fcntl
+            fcntl.flock(lock_file.fileno(), fcntl.LOCK_EX)
+            data = self.read()
+            skills = data.setdefault('installed_skills', [])
+            if name not in skills:
+                skills.append(name)
+            self.path.write_text(json.dumps(data, indent=2), encoding='utf-8')
+    def remove(self, name):
+        data=self.read(); data['installed_skills']=[s for s in data.get('installed_skills',[]) if s!=name]
+        self.path.write_text(json.dumps(data, indent=2), encoding='utf-8')
-    def remove(self, name):
-        data=self.read(); data['installed_skills']=[s for s in data.get('installed_skills',[]) if s!=name]
-        self.path.write_text(json.dumps(data, indent=2), encoding='utf-8')
+    def remove(self, name):
+        lock_path = self.path.with_suffix(".lock")
+        with lock_path.open("w", encoding="utf-8") as lock_file:
+            import fcntl
+            fcntl.flock(lock_file.fileno(), fcntl.LOCK_EX)
+            data = self.read()
+            data['installed_skills'] = [s for s in data.get('installed_skills', []) if s != name]
+            self.path.write_text(json.dumps(data, indent=2), encoding='utf-8')
-    def remove(self, name):
-        data=self.read(); data['installed_skills']=[s for s in data.get('installed_skills',[]) if s!=name]
-        self.path.write_text(json.dumps(data, indent=2), encoding='utf-8')
+    def remove(self, name):
+        lock_path = self.path.with_suffix(".lock")
+        with lock_path.open("w", encoding="utf-8") as lock_file:
+            import fcntl
+            fcntl.flock(lock_file.fileno(), fcntl.LOCK_EX)
+            data = self.read()
+            data['installed_skills'] = [s for s in data.get('installed_skills', []) if s != name]
+            self.path.write_text(json.dumps(data, indent=2), encoding='utf-8')
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		class ChannelRouter:
		def route(self, msg: dict): return msg
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		class ClawHubAPI:
		base_url = 'https://clawhub.example/api'
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		CHANNELS = ['cli','websocket','discord','telegram','api']
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		MODEL_PROVIDERS = ['deepseek','mistral','llama','openai']
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		class AuthManager:
		def validate(self, token: str): return bool(token)
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		class WebSocketGateway:
		def start(self): return True
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		class MemoryCompaction:
		def compact(self, messages: list[str]): return {"summary": " ".join(messages[:10]), "kept": messages[-10:]}
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		class ContextBuilder:
		def build(self, session, memories): return {"session": session.session_id, "memories": memories}
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		class ModelFailover:
		def pick(self, providers): return providers[0] if providers else "fallback"
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		class ModelRouter:
		async def generate(self, prompt: str): return {"response": prompt, "model": "openai", "tokens": len(prompt.split()), "cost": 0.0}