nucleus-mcp 1.0.7 → 1.2.0

package/src/mcp_server_nucleus/runtime/crdt_task_store.py

@@ -1,349 +0,0 @@
-"""
-CRDTTaskStore - Conflict-free Distributed Task Store
-Implements Last-Writer-Wins (LWW) + Vector Clocks
-
-Path B: Simple, scalable, production-ready
-- Handles concurrent writes without locks
-- Guarantees zero data loss (CRDT invariant)
-- Auto-resolves conflicts with LWW + vector clocks
-- Scales 1→100→10K users with same code
-- Single-process MVP, multi-process ready
-
-Author: NOP V3 - January 2026
-"""
-
-import json
-import time
-import threading
-from typing import Dict, List, Optional, Set
-from collections import defaultdict
-from copy import deepcopy
-
-
-class CRDTTaskStore:
-    """
-    Conflict-free replicated data type for task management.
-    
-    Key guarantees:
-    - Zero data loss: Every write is persisted
-    - Causality: Vector clocks track dependencies
-    - Conflict resolution: LWW (Last-Writer-Wins) with timestamps
-    - Convergence: All replicas eventually see same state
-    - Idempotency: Same write applied multiple times = same result
-    
-    Single-process implementation (thread-safe for concurrent writes).
-    Multi-replica merge() support for future distributed sync.
-    """
-    
-    def __init__(self, replica_id: str = "default"):
-        """
-        Initialize CRDT task store.
-        
-        Args:
-            replica_id: Unique identifier for this replica (used for multi-replica merge)
-        """
-        self.replica_id = replica_id
-        self._tasks: Dict[str, Dict] = {}  # task_id -> Task
-        self._clocks: Dict[str, int] = defaultdict(int)  # replica_id -> clock value (for vector clocks)
-        self._timestamps: Dict[str, int] = {}  # task_id -> LWW timestamp
-        self._tombstones: Set[str] = set()  # Deleted task IDs (for CRDT consistency)
-        self._lock = threading.RLock()  # Thread-safe concurrent writes
-        
-    def _increment_clock(self) -> None:
-        """Increment vector clock for this replica."""
-        self._clocks[self.replica_id] += 1
-        
-    def _get_vector_clock(self) -> Dict[str, int]:
-        """Get current vector clock state."""
-        return dict(self._clocks)
-    
-    def _merge_vector_clocks(self, incoming: Dict[str, int]) -> Dict[str, int]:
-        """Merge incoming vector clock with local clock (element-wise max)."""
-        merged = dict(self._clocks)
-        for replica_id, clock_value in incoming.items():
-            merged[replica_id] = max(merged.get(replica_id, 0), clock_value)
-        return merged
-    
-    def add_task(self, task: Dict) -> Dict:
-        """
-        Add a new task to the store.
-        
-        Args:
-            task: Task dict with keys: id, title, status, tier, created_at, assigned_to (optional)
-            
-        Returns:
-            Task with CRDT metadata added (updated_at, replica_id, vector_clock)
-            
-        Guarantees:
-            - Task is immediately visible to all readers
-            - Timestamp ensures consistent ordering
-            - Vector clock tracks causality
-        """
-        with self._lock:
-            task_id = task.get("id")
-            if not task_id:
-                raise ValueError("Task must have 'id' field")
-            
-            current_time = int(time.time() * 1000)  # Epoch milliseconds
-            
-            # Add CRDT metadata
-            self._increment_clock()
-            enriched_task = {
-                **task,
-                "updated_at": current_time,
-                "replica_id": self.replica_id,
-                "vector_clock": self._get_vector_clock(),
-                "created_at": task.get("created_at", current_time),
-            }
-            
-            self._tasks[task_id] = enriched_task
-            self._timestamps[task_id] = current_time
-            
-            # Remove from tombstones if previously deleted
-            self._tombstones.discard(task_id)
-            
-            return deepcopy(enriched_task)
-    
-    def update_task(self, task_id: str, updates: Dict) -> Dict:
-        """
-        Update an existing task with LWW conflict resolution.
-        
-        Args:
-            task_id: ID of task to update
-            updates: Dict of fields to update (status, assigned_to, title, etc.)
-            
-        Returns:
-            Updated task
-            
-        Raises:
-            KeyError: If task doesn't exist
-            
-        Conflict Resolution:
-            - Incoming update has new timestamp (LWW)
-            - Only applied if newer than existing
-            - Vector clock updated to track causality
-        """
-        with self._lock:
-            if task_id not in self._tasks:
-                raise KeyError(f"Task {task_id} not found")
-            
-            if task_id in self._tombstones:
-                raise KeyError(f"Task {task_id} has been deleted")
-            
-            current_time = int(time.time() * 1000)
-            self._increment_clock()
-            
-            existing = self._tasks[task_id]
-            
-            # LWW: Use new timestamp (later write wins)
-            updated_task = {
-                **existing,
-                **updates,
-                "updated_at": current_time,
-                "replica_id": self.replica_id,
-                "vector_clock": self._get_vector_clock(),
-            }
-            
-            self._tasks[task_id] = updated_task
-            self._timestamps[task_id] = current_time
-            
-            return deepcopy(updated_task)
-    
-    def delete_task(self, task_id: str) -> bool:
-        """
-        Delete a task (tombstone-based deletion for CRDT safety).
-        
-        Args:
-            task_id: ID of task to delete
-            
-        Returns:
-            True if deleted, False if not found
-            
-        Note:
-            Uses tombstones to track deleted tasks. This prevents
-            re-insertion of deleted data during multi-replica merges.
-        """
-        with self._lock:
-            if task_id not in self._tasks:
-                return False
-            
-            del self._tasks[task_id]
-            self._tombstones.add(task_id)
-            if task_id in self._timestamps:
-                del self._timestamps[task_id]
-            
-            return True
-    
-    def get_task(self, task_id: str) -> Optional[Dict]:
-        """
-        Retrieve a single task by ID.
-        
-        Args:
-            task_id: ID of task
-            
-        Returns:
-            Task dict or None if not found
-        """
-        with self._lock:
-            task = self._tasks.get(task_id)
-            return deepcopy(task) if task else None
-    
-    def get_all_tasks(self) -> List[Dict]:
-        """
-        Retrieve all tasks (consistent snapshot).
-        
-        Returns:
-            List of all tasks, sorted by updated_at (newest first)
-            
-        Consistency:
-            - Snapshot is taken within lock
-            - No tasks added/removed during read
-            - All timestamps consistent
-        """
-        with self._lock:
-            tasks = [deepcopy(t) for t in self._tasks.values()]
-            # Sort by updated_at descending (newest first)
-            tasks.sort(key=lambda t: t.get("updated_at", 0), reverse=True)
-            return tasks
-    
-    def get_tasks_by_tier(self, tier: str) -> List[Dict]:
-        """Get all tasks for a specific tier."""
-        with self._lock:
-            tasks = [
-                deepcopy(t) for t in self._tasks.values()
-                if t.get("tier") == tier
-            ]
-            tasks.sort(key=lambda t: t.get("updated_at", 0), reverse=True)
-            return tasks
-    
-    def get_tasks_by_status(self, status: str) -> List[Dict]:
-        """Get all tasks with a specific status."""
-        with self._lock:
-            tasks = [
-                deepcopy(t) for t in self._tasks.values()
-                if t.get("status") == status
-            ]
-            tasks.sort(key=lambda t: t.get("updated_at", 0), reverse=True)
-            return tasks
-    
-    def merge(self, remote_store: "CRDTTaskStore") -> None:
-        """
-        Merge this store with a remote store using LWW + vector clocks.
-        
-        Args:
-            remote_store: Another CRDTTaskStore to merge with
-            
-        Algorithm:
-            1. For each task in remote:
-               - If not in local: add it (new task)
-               - If in local: compare timestamps (LWW wins)
-               - Merge vector clocks (element-wise max)
-            2. Update local vector clock with remote state
-            
-        Result:
-            - All replicas converge to same state
-            - No data loss
-            - Conflicts auto-resolved by timestamp
-        """
-        with self._lock:
-            remote_tasks = remote_store.get_all_tasks()
-            
-            for remote_task in remote_tasks:
-                task_id = remote_task.get("id")
-                remote_timestamp = remote_task.get("updated_at", 0)
-                
-                if task_id in self._tombstones:
-                    # Local delete wins - skip remote version
-                    continue
-                
-                if task_id not in self._tasks:
-                    # New task from remote
-                    self._tasks[task_id] = deepcopy(remote_task)
-                    self._timestamps[task_id] = remote_timestamp
-                else:
-                    # Task exists locally - LWW: newer wins
-                    local_timestamp = self._timestamps.get(task_id, 0)
-                    
-                    if remote_timestamp > local_timestamp:
-                        # Remote is newer, use it
-                        self._tasks[task_id] = deepcopy(remote_task)
-                        self._timestamps[task_id] = remote_timestamp
-                    # else: local is newer, keep local version
-                
-                # Merge vector clocks
-                local_vc = self._tasks[task_id].get("vector_clock", {})
-                remote_vc = remote_task.get("vector_clock", {})
-                merged_vc = self._merge_vector_clocks({**local_vc, **remote_vc})
-                self._tasks[task_id]["vector_clock"] = merged_vc
-            
-            # Merge remote tombstones
-            remote_tombstones = remote_store._tombstones
-            for tombstone_id in remote_tombstones:
-                if tombstone_id in self._tasks:
-                    del self._tasks[tombstone_id]
-                self._tombstones.add(tombstone_id)
-            
-            # Merge vector clocks globally
-            remote_clocks = remote_store._clocks
-            for replica_id, clock_value in remote_clocks.items():
-                self._clocks[replica_id] = max(
-                    self._clocks.get(replica_id, 0),
-                    clock_value
-                )
-    
-    def to_json(self) -> str:
-        """
-        Export store to JSON for persistence.
-        
-        Returns:
-            JSON string with all tasks, tombstones, and vector clocks
-            
-        Format:
-            {
-                "replica_id": "...",
-                "tasks": [...],
-                "tombstones": [...],
-                "vector_clocks": {...}
-            }
-        """
-        with self._lock:
-            export_data = {
-                "replica_id": self.replica_id,
-                "tasks": list(self._tasks.values()),
-                "tombstones": list(self._tombstones),
-                "vector_clocks": dict(self._clocks),
-            }
-            return json.dumps(export_data, indent=2, default=str)
-    
-    def from_json(self, json_str: str) -> None:
-        """
-        Import store from JSON (e.g., for recovery from persistence).
-        
-        Args:
-            json_str: JSON string from to_json()
-            
-        Note:
-            This overwrites current state. Use for recovery only.
-        """
-        with self._lock:
-            data = json.loads(json_str)
-            
-            self.replica_id = data.get("replica_id", "default")
-            self._tasks = {t["id"]: t for t in data.get("tasks", [])}
-            self._tombstones = set(data.get("tombstones", []))
-            self._clocks = defaultdict(int, data.get("vector_clocks", {}))
-            self._timestamps = {
-                t["id"]: t.get("updated_at", 0)
-                for t in data.get("tasks", [])
-            }
-    
-    def get_stats(self) -> Dict:
-        """Get store statistics for monitoring."""
-        with self._lock:
-            return {
-                "replica_id": self.replica_id,
-                "total_tasks": len(self._tasks),
-                "tombstones": len(self._tombstones),
-                "vector_clock": dict(self._clocks),
-                "memory_estimate_kb": len(self.to_json()) / 1024,
-            }

package/src/mcp_server_nucleus/runtime/critic.py

@@ -1,150 +0,0 @@
-
-import os
-import json
-import time
-from pathlib import Path
-from typing import Dict
-import logging
-
-# Configure logger
-logger = logging.getLogger("nucleus.critic")
-
-try:
-    from mcp_server_nucleus.runtime.llm_client import DualEngineLLM
-except ImportError:
-    # Fallback for when running in simpler contexts
-    DualEngineLLM = None
-
-def get_brain_path() -> Path:
-    """Get the brain path from environment variable."""
-    brain_path = os.environ.get("NUCLEAR_BRAIN_PATH")
-    if not brain_path:
-        # Fallback for dev/test if env not set, check common locations
-        cwd = Path.cwd()
-        if (cwd / ".brain").exists():
-            return cwd / ".brain"
-        # Try finding in parent directories
-        for parent in cwd.parents:
-            if (parent / ".brain").exists():
-                return parent / ".brain"
-        raise ValueError("NUCLEAR_BRAIN_PATH environment variable not set and .brain not found")
-    
-    path = Path(brain_path)
-    if not path.exists():
-         raise ValueError(f"Brain path does not exist: {brain_path}")
-    return path
-
-def _critique_code(file_path: str) -> Dict:
-    """
-    Critique a specific file using the Critic Agent persona.
-    """
-    try:
-        brain = get_brain_path()
-        
-        # 1. Resolve Target File
-        # Handle absolute or relative paths
-        if file_path.startswith("/"):
-            target_path = Path(file_path)
-        else:
-            # Assume relative to project root (parent of .brain)
-            target_path = brain.parent / file_path
-
-        if not target_path.exists():
-            return {"success": False, "error": f"File not found: {file_path}"}
-        
-        code_content = target_path.read_text()
-
-        # 2. Read System Prompt
-        critic_prompt_path = brain / "agents" / "critic.md"
-        if not critic_prompt_path.exists():
-            return {"success": False, "error": "Critic persona not found in .brain/agents/critic.md"}
-        
-        system_prompt = critic_prompt_path.read_text()
-
-        # 3. Initialize LLM
-        if not DualEngineLLM:
-             return {"success": False, "error": "LLM Client not available (ImportError)"}
-
-        try:
-            llm = DualEngineLLM(
-                model_name="gemini-2.0-flash-exp",
-                system_instruction=system_prompt
-            )
-        except Exception as e:
-            return {"success": False, "error": f"LLM Init failed: {e}"}
-
-        # 4. Construct Prompt
-        user_prompt = f"""
-ACTION: Review the following code file.
-
-TARGET: {file_path}
-
-CONTENT:
-```
-{code_content}
-```
-
-INSTRUCTIONS:
-1. Analyze for bugs, security flaws, style violations, and adherence to best practices.
-2. Check against the Prime Directives.
-3. Output your critique in valid JSON format ONLY. 
-   Do not include markdown formatting (like ```json), just the raw JSON string.
-   Use the schema defined in 'Completion Events' (e.g., event_type="review_approved" or "review_blocked").
-   
-   Example Success:
-   {{
-     "event_type": "review_approved",
-     "severity": "ROUTINE",
-     "payload": {{ "target": "...", "notes": "LGTM" }}
-   }}
-   
-   Example Failure:
-   {{
-     "event_type": "review_blocked", 
-     "severity": "HIGH",
-     "payload": {{ "issues": [...] }}
-   }}
-"""
-
-        # 5. Call LLM
-        logger.info(f"Invoking Critic on {file_path}")
-        response = llm.generate_content(user_prompt)
-        
-        if not response or not hasattr(response, 'text'):
-            return {"success": False, "error": "LLM returned empty response"}
-
-        raw_text = response.text
-        
-        # Naive JSON extraction
-        start = raw_text.find("{")
-        end = raw_text.rfind("}") + 1
-        
-        if start != -1 and end != -1:
-            json_str = raw_text[start:end]
-            try:
-                critique_data = json.loads(json_str)
-            except json.JSONDecodeError:
-                 return {"success": False, "error": "Invalid JSON from Critic", "raw": raw_text}
-        else:
-            return {"success": False, "error": "No JSON found in Critic response", "raw": raw_text}
-            
-        # 6. Save Artifact
-        timestamp = int(time.time())
-        filename = f"code_review_{target_path.name}_{timestamp}.json"
-        review_path = brain / "artifacts" / "reviews" / filename
-        review_path.parent.mkdir(parents=True, exist_ok=True)
-        review_path.write_text(json.dumps(critique_data, indent=2))
-        
-        # 7. Extract status for easy consumption
-        status = "APPROVED" if critique_data.get("event_type") == "review_approved" else "BLOCKED"
-        
-        return {
-            "success": True, 
-            "status": status,
-            "review_path": str(review_path),
-            "critique": critique_data
-        }
-
-    except Exception as e:
-        logger.error(f"Critique failed: {e}")
-        return {"success": False, "error": f"Critique generation failed: {str(e)}"}

package/src/mcp_server_nucleus/runtime/daemon.py

@@ -1,142 +0,0 @@
-
-"""
-Nucleus Daemon Manager.
-The Kernel service that runs the persistent background agent.
-
-Strategic Role:
-- Lifecycle Management: Startup, Shutdown, Signal Handling.
-- process Safety: Enforces BrainLock to ensure only one Daemon runs.
-- Heartbeat: Updates status for the HUD.
-"""
-
-import asyncio
-import signal
-import sys
-import logging
-from pathlib import Path
-from typing import Optional
-
-from .locking import get_lock, BrainLock
-from .policy import DirectivesLoader
-from .orchestrator import SwarmsOrchestrator
-from .hooks import IdentityKey, AmbientTelemetry, InsightExchange, RemoteExecutionProtocol
-
-# Configure logging
-logging.basicConfig(
-    level=logging.INFO,
-    format='%(asctime)s [%(name)s] %(levelname)s: %(message)s',
-    handlers=[
-        logging.StreamHandler(sys.stdout),
-        logging.FileHandler("daemon.log")
-    ]
-)
-logger = logging.getLogger("NucleusDaemon")
-
-class DaemonManager:
-    def __init__(self, brain_path: Path):
-        self.brain_path = brain_path
-        self.lock: Optional[BrainLock] = None
-        self.running = False
-        self.policy_engine = DirectivesLoader(brain_path)
-        self.orchestrator = SwarmsOrchestrator(brain_path)
-        
-        # Strategic Hooks (The Billion Dollar Extensions)
-        self.identity = IdentityKey(brain_path)
-        self.pulse = AmbientTelemetry(brain_path, identity=self.identity)
-        self.insight_exchange = InsightExchange(brain_path)
-        self.grid = RemoteExecutionProtocol(brain_path)
-        
-    async def start(self):
-        """Start the Daemon sequence"""
-        logger.info("Nucleus Daemon Starting...")
-        
-        # 1. Acquire Lock
-        lock_dir = self.brain_path / ".locks"
-        self.lock = get_lock("daemon_process", base_dir=lock_dir)
-        
-        if not self.lock.acquire(timeout=1.0):
-            logger.error("Could not acquire daemon lock. Is another instance running?")
-            sys.exit(1)
-            
-        logger.info("🔒 BrainLock Acquired. I am the Sovereign Process.")
-        self.running = True
-        
-        # 2. Setup Signals
-        loop = asyncio.get_running_loop()
-        for sig in (signal.SIGINT, signal.SIGTERM):
-            loop.add_signal_handler(sig, lambda: asyncio.create_task(self.shutdown()))
-            
-        # 3. Load Policy
-        policy = self.policy_engine.load_policy()
-        logger.info(f"📜 Policy Loaded: Mode={policy.get('mode')}, Safety={policy.get('safety_level')}")
-        
-        # 4. Main Event Loop
-        try:
-            await self.main_loop()
-        except asyncio.CancelledError:
-            logger.info("Daemon cancelled.")
-        except Exception as e:
-            logger.exception(f"Daemon crashed: {e}")
-        finally:
-            await self.shutdown()
-
-    async def main_loop(self):
-        """The Core Preemptive Loop"""
-        logger.info("🚀 Daemon is active. Entering Main Loop.")
-        
-        while self.running:
-            # Heartbeat (The Ambient Pulse)
-            status = "busy" if self.orchestrator._active_missions else "idle"
-            self.pulse.beat(status, len(self.orchestrator._active_missions))
-            logger.debug(f"❤️ Heartbeat ({status})")
-            
-            # Monitor Swarms
-            active_count = len(self.orchestrator._active_missions)
-            if active_count > 0:
-                logger.info(f"🦾 Active Swarms: {active_count}")
-            
-            # TODO: Phase A Components
-            # - Check AsyncFileWatcher
-            # - Check Pending Commitments (SwarmsOrchestrator)
-            
-            # Simulation of work (Polling interval)
-            # In future, this is replaced by Event triggers to avoid busy wait
-            await asyncio.sleep(5) 
-            
-    async def shutdown(self):
-        """Graceful Shutdown"""
-        if not self.running:
-            return
-            
-        logger.info("🛑 Shutdown initiated...")
-        self.running = False
-        
-        # Release resources
-        if self.lock:
-            self.lock.release()
-            logger.info("🔓 BrainLock Released.")
-            
-        # TODO: Close sockets, database connections
-        
-        logger.info("Daemon Stopped.")
-        sys.exit(0)
-
-def run_daemon():
-    """Entry point for the daemon service"""
-    # Determine Brain Path (Environment or Default)
-    import os
-    brain_path_str = os.environ.get("NUCLEUS_BRAIN_PATH")
-    if not brain_path_str:
-        # Dev fallback
-        brain_path = Path.cwd() / ".brain" # simplistic
-    else:
-        brain_path = Path(brain_path_str)
-        
-    daemon = DaemonManager(brain_path)
-    try:
-        asyncio.run(daemon.start())
-    except KeyboardInterrupt:
-        pass # Handled in handler
-        
-if __name__ == "__main__":
-    run_daemon()