nucleus-mcp 1.0.7 → 1.2.0

package/src/mcp_server_nucleus/runtime/task_scheduler.py

@@ -1,488 +0,0 @@
-"""
-TaskScheduler - Intelligent Task Assignment Engine
-Implements Priority Queue + Agent State Machine + Dependency Resolution
-
-Path A: Simple, deterministic, scales 1→1000 agents
-- Priority queue per tier (T1, T2, T3, T4)
-- Agent capacity tracking (busy vs available)
-- Dependency resolution (blocked tasks)
-- FIFO fairness within tier
-- Deadline-aware scheduling
-- Zero conflicts guarantee
-
-Author: NOP V3 - January 2026
-"""
-
-import time
-import threading
-from typing import Dict, List, Optional, Set
-from collections import defaultdict
-from copy import deepcopy
-from enum import Enum
-
-
-class TaskStatus(str, Enum):
-    """Task status in scheduler."""
-    PENDING = "PENDING"
-    SCHEDULED = "SCHEDULED"
-    BLOCKED = "BLOCKED"
-    ASSIGNED = "ASSIGNED"
-    COMPLETED = "COMPLETED"
-
-
-class TaskPriority(str, Enum):
-    """Task priority levels."""
-    HIGH = "HIGH"
-    MEDIUM = "MEDIUM"
-    LOW = "LOW"
-
-    def sort_value(self) -> int:
-        """Return numeric value for sorting (lower = higher priority)."""
-        return {"HIGH": 0, "MEDIUM": 1, "LOW": 2}[self.value]
-
-
-class TaskTier(str, Enum):
-    """Task difficulty tiers."""
-    T1_PLANNING = "T1_PLANNING"
-    T2_CODE = "T2_CODE"
-    T3_REVIEW = "T3_REVIEW"
-    T4_DEPLOY = "T4_DEPLOY"
-
-    def sort_value(self) -> int:
-        """Return numeric value for tier ordering."""
-        return {"T1_PLANNING": 0, "T2_CODE": 1, "T3_REVIEW": 2, "T4_DEPLOY": 3}[self.value]
-
-
-class AgentState:
-    """Represents state of a single agent."""
-
-    def __init__(self, agent_id: str, tier: str, capacity: int = 5):
-        self.id = agent_id
-        self.tier = tier
-        self.capacity = capacity
-        self.current_tasks: Set[str] = set()
-        self.available = True
-        self.last_heartbeat = int(time.time() * 1000)
-        self.tasks_completed = 0
-
-    def is_available(self) -> bool:
-        """Check if agent has capacity for new task."""
-        return len(self.current_tasks) < self.capacity
-
-    def assign_task(self, task_id: str) -> bool:
-        """Assign task to agent if capacity available."""
-        if not self.is_available():
-            return False
-        self.current_tasks.add(task_id)
-        return True
-
-    def complete_task(self, task_id: str) -> bool:
-        """Mark task as completed, free capacity."""
-        if task_id in self.current_tasks:
-            self.current_tasks.remove(task_id)
-            self.tasks_completed += 1
-            return True
-        return False
-
-    def to_dict(self) -> Dict:
-        """Convert to dictionary."""
-        return {
-            "id": self.id,
-            "tier": self.tier,
-            "capacity": self.capacity,
-            "current_tasks": list(self.current_tasks),
-            "available": self.is_available(),
-            "last_heartbeat": self.last_heartbeat,
-            "tasks_completed": self.tasks_completed,
-        }
-
-
-class ScheduleDecision:
-    """Represents a scheduling decision for a task."""
-
-    def __init__(
-        self,
-        task_id: str,
-        agent_id: Optional[str] = None,
-        reason: str = "queued",
-    ):
-        self.task_id = task_id
-        self.agent_id = agent_id
-        self.scheduled_at = int(time.time() * 1000)
-        self.reason = reason  # assigned, blocked, queued
-
-    def to_dict(self) -> Dict:
-        """Convert to dictionary."""
-        return {
-            "task_id": self.task_id,
-            "agent_id": self.agent_id,
-            "scheduled_at": self.scheduled_at,
-            "reason": self.reason,
-        }
-
-
-class TaskScheduler:
-    """
-    Intelligent task assignment engine.
-
-    Key guarantees:
-    - Zero scheduling conflicts: Each task assigned to at most one agent
-    - Fairness: Tasks distributed evenly across agents in tier
-    - Dependency resolution: Blocked tasks queued, not scheduled
-    - Deadline-aware: Urgent tasks scheduled first
-    - FIFO within tier: Stable ordering
-    - Capacity respected: No over-booking agents
-    - Tier matching: Tasks only assigned to agents of matching tier
-    - Performance: <500ms for 100K tasks
-
-    Single-process implementation (thread-safe).
-    Multi-agent coordination ready for future distributed scheduler.
-    """
-
-    def __init__(self, max_agents: int = 1000):
-        """
-        Initialize task scheduler.
-
-        Args:
-            max_agents: Maximum number of agents (for allocation)
-        """
-        self.max_agents = max_agents
-        self.agent_registry: Dict[str, AgentState] = {}  # agent_id -> AgentState
-        self.task_states: Dict[str, Dict] = {}  # task_id -> TaskState
-        self.dependency_graph: Dict[str, Set[str]] = defaultdict(set)  # task_id -> blocked_by task_ids
-        self.task_queues: Dict[str, List] = {
-            "T1_PLANNING": [],
-            "T2_CODE": [],
-            "T3_REVIEW": [],
-            "T4_DEPLOY": [],
-        }  # tier -> priority queue
-        self.lock = threading.RLock()
-        self.stats = {
-            "scheduled": 0,
-            "blocked": 0,
-            "queued": 0,
-            "completed": 0,
-        }
-
-    def register_agent(self, agent_id: str, tier: str, capacity: int = 5) -> Dict:
-        """
-        Register new agent into scheduler.
-
-        Args:
-            agent_id: Unique agent identifier
-            tier: Task tier (T1_PLANNING, T2_CODE, T3_REVIEW, T4_DEPLOY)
-            capacity: Max concurrent tasks this agent can handle
-
-        Returns:
-            AgentState as dictionary
-        """
-        with self.lock:
-            if agent_id in self.agent_registry:
-                raise ValueError(f"Agent {agent_id} already registered")
-
-            agent = AgentState(agent_id, tier, capacity)
-            self.agent_registry[agent_id] = agent
-            return agent.to_dict()
-
-    def unregister_agent(self, agent_id: str) -> bool:
-        """
-        Unregister agent from scheduler.
-
-        Args:
-            agent_id: Agent to unregister
-
-        Returns:
-            True if unregistered, False if not found
-        """
-        with self.lock:
-            if agent_id not in self.agent_registry:
-                return False
-
-            agent = self.agent_registry[agent_id]
-
-            # Free all assigned tasks
-            for task_id in list(agent.current_tasks):
-                if task_id in self.task_states:
-                    self.task_states[task_id]["assigned_to"] = None
-                    self.task_states[task_id]["status"] = TaskStatus.PENDING.value
-
-            del self.agent_registry[agent_id]
-            return True
-
-    def mark_task_done(self, task_id: str, agent_id: str) -> bool:
-        """
-        Mark task as completed, free agent capacity.
-
-        Args:
-            task_id: Task that completed
-            agent_id: Agent that completed it
-
-        Returns:
-            True if marked done, False if not found
-        """
-        with self.lock:
-            if agent_id not in self.agent_registry:
-                return False
-
-            agent = self.agent_registry[agent_id]
-            if not agent.complete_task(task_id):
-                return False
-
-            if task_id in self.task_states:
-                self.task_states[task_id]["status"] = TaskStatus.COMPLETED.value
-                self.stats["completed"] += 1
-
-            return True
-
-    def resolve_dependencies(self, task_id: str) -> bool:
-        """
-        Check if all dependencies of a task are satisfied.
-
-        Args:
-            task_id: Task to check
-
-        Returns:
-            True if all blocked_by tasks are completed, False otherwise
-        """
-        with self.lock:
-            if task_id not in self.task_states:
-                return False
-
-            blocked_by = self.task_states[task_id].get("blocked_by", [])
-
-            for blocker_id in blocked_by:
-                if blocker_id not in self.task_states:
-                    continue  # Blocker not in scheduler
-
-                blocker_status = self.task_states[blocker_id].get("status")
-                if blocker_status != TaskStatus.COMPLETED.value:
-                    return False  # Blocker not completed
-
-            return True  # All blockers completed
-
-    def schedule_batch(
-        self,
-        tasks: List[Dict],
-        force_schedule: bool = False,
-    ) -> List[Dict]:
-        """
-        Schedule a batch of tasks across agents.
-
-        Args:
-            tasks: List of task dicts with id, tier, priority, blocked_by, deadline
-            force_schedule: If True, use best-effort (may over-book)
-
-        Returns:
-            List of ScheduleDecision dicts (assigned, blocked, queued)
-
-        Algorithm:
-            1. Add tasks to internal state
-            2. Resolve dependencies (mark blocked)
-            3. Sort by: priority, deadline, FIFO (created_at)
-            4. For each non-blocked task:
-               - Find agent with matching tier + available capacity
-               - Assign task to agent
-               - Mark as scheduled
-            5. Return decisions
-        """
-        with self.lock:
-            decisions = []
-            time.time()
-
-            # Phase 1: Add tasks to internal state
-            for task in tasks:
-                task_id = task.get("id")
-                if task_id in self.task_states:
-                    continue  # Already tracked
-
-                self.task_states[task_id] = {
-                    "id": task_id,
-                    "status": TaskStatus.PENDING.value,
-                    "tier": task.get("tier", "T1_PLANNING"),
-                    "priority": task.get("priority", "MEDIUM"),
-                    "deadline": task.get("deadline"),
-                    "created_at": task.get("created_at", int(time.time() * 1000)),
-                    "assigned_to": None,
-                    "blocked_by": task.get("blocked_by", []),
-                }
-
-            # Phase 2: Resolve dependencies, categorize tasks
-            blocked_tasks = set()
-            pending_tasks = []
-
-            for task in tasks:
-                task_id = task.get("id")
-                task_state = self.task_states[task_id]
-
-                # Check if task is blocked
-                is_blocked = not self.resolve_dependencies(task_id)
-
-                if is_blocked:
-                    blocked_tasks.add(task_id)
-                    task_state["status"] = TaskStatus.BLOCKED.value
-                    decisions.append(
-                        ScheduleDecision(task_id, reason="blocked").to_dict()
-                    )
-                    self.stats["blocked"] += 1
-                else:
-                    pending_tasks.append(task_state)
-
-            # Phase 3: Sort pending tasks by priority/deadline/FIFO
-            def sort_key(task_state):
-                priority = TaskPriority[task_state["priority"]].sort_value()
-                deadline = task_state.get("deadline") or float("inf")
-                created_at = task_state.get("created_at", float("inf"))
-                # Sort by: priority (low first), deadline (early first), FIFO (early created first)
-                return (priority, deadline, created_at)
-
-            pending_tasks.sort(key=sort_key)
-
-            # Phase 4: Assign tasks to agents
-            for task_state in pending_tasks:
-                task_id = task_state["id"]
-                tier = task_state["tier"]
-
-                # Find available agent with matching tier
-                assigned_agent = None
-                for agent in self.agent_registry.values():
-                    if agent.tier == tier and agent.is_available():
-                        assigned_agent = agent
-                        break
-
-                if assigned_agent:
-                    # Assign task to agent
-                    if assigned_agent.assign_task(task_id):
-                        task_state["status"] = TaskStatus.SCHEDULED.value
-                        task_state["assigned_to"] = assigned_agent.id
-                        decisions.append(
-                            ScheduleDecision(
-                                task_id, agent_id=assigned_agent.id, reason="assigned"
-                            ).to_dict()
-                        )
-                        self.stats["scheduled"] += 1
-                    else:
-                        # Capacity exhausted
-                        task_state["status"] = TaskStatus.PENDING.value
-                        decisions.append(
-                            ScheduleDecision(task_id, reason="queued").to_dict()
-                        )
-                        self.stats["queued"] += 1
-                else:
-                    # No available agent with matching tier
-                    task_state["status"] = TaskStatus.PENDING.value
-                    decisions.append(
-                        ScheduleDecision(task_id, reason="queued").to_dict()
-                    )
-                    self.stats["queued"] += 1
-
-            return decisions
-
-    def get_agent_state(self, agent_id: str) -> Optional[Dict]:
-        """
-        Get current state of an agent.
-
-        Args:
-            agent_id: Agent to query
-
-        Returns:
-            AgentState dict or None if not found
-        """
-        with self.lock:
-            agent = self.agent_registry.get(agent_id)
-            return agent.to_dict() if agent else None
-
-    def get_all_agents(self) -> List[Dict]:
-        """
-        Get all registered agents.
-
-        Returns:
-            List of AgentState dicts
-        """
-        with self.lock:
-            return [agent.to_dict() for agent in self.agent_registry.values()]
-
-    def get_pending_tasks(self, agent_id: str) -> List[Dict]:
-        """
-        Get tasks assigned to an agent (pending execution).
-
-        Args:
-            agent_id: Agent to query
-
-        Returns:
-            List of task dicts
-        """
-        with self.lock:
-            if agent_id not in self.agent_registry:
-                return []
-
-            agent = self.agent_registry[agent_id]
-            pending = []
-
-            for task_id in agent.current_tasks:
-                if task_id in self.task_states:
-                    pending.append(deepcopy(self.task_states[task_id]))
-
-            return pending
-
-    def get_scheduling_stats(self) -> Dict:
-        """
-        Get scheduler statistics.
-
-        Returns:
-            Dict with scheduled, blocked, queued, completed counts
-        """
-        with self.lock:
-            return {
-                "scheduled": self.stats["scheduled"],
-                "blocked": self.stats["blocked"],
-                "queued": self.stats["queued"],
-                "completed": self.stats["completed"],
-                "total_agents": len(self.agent_registry),
-                "total_tasks": len(self.task_states),
-            }
-
-    def get_task_state(self, task_id: str) -> Optional[Dict]:
-        """
-        Get state of a specific task.
-
-        Args:
-            task_id: Task to query
-
-        Returns:
-            TaskState dict or None if not found
-        """
-        with self.lock:
-            return deepcopy(self.task_states.get(task_id))
-
-    def get_fairness_metrics(self) -> Dict:
-        """
-        Get fairness metrics for each tier.
-
-        Returns:
-            Dict with per-tier fairness stats (task distribution across agents)
-        """
-        with self.lock:
-            fairness = {}
-
-            for tier in ["T1_PLANNING", "T2_CODE", "T3_REVIEW", "T4_DEPLOY"]:
-                tier_agents = [
-                    a for a in self.agent_registry.values() if a.tier == tier
-                ]
-
-                if not tier_agents:
-                    continue
-
-                task_counts = [len(a.current_tasks) for a in tier_agents]
-                avg_tasks = sum(task_counts) / len(tier_agents) if tier_agents else 0
-                variance = sum((x - avg_tasks) ** 2 for x in task_counts) / len(
-                    task_counts
-                ) if tier_agents else 0
-
-                fairness[tier] = {
-                    "agents": len(tier_agents),
-                    "task_counts": task_counts,
-                    "avg_tasks_per_agent": avg_tasks,
-                    "variance": variance,
-                }
-
-            return fairness

package/src/mcp_server_nucleus/runtime/team.py

@@ -1,59 +0,0 @@
-"""
-TeamManager: The Hive Mind.
-Manages Shared Configuration and Trust Roots for the Team.
-
-Strategic Role:
-- SYNC: Ensures all agents on the team use the same Registry.
-- TRUST: Distributes the Team Lead's public keys.
-- POLICY: Enforces team-wide rules (e.g. "Signed Only").
-"""
-
-import json
-import logging
-from typing import List, Optional
-from pathlib import Path
-from pydantic import BaseModel, Field
-
-logger = logging.getLogger("TEAM")
-
-class TeamPolicy(BaseModel):
-    require_signed: bool = True
-    min_trust_level: str = "verified"
-
-class TeamConfig(BaseModel):
-    team_id: str
-    name: str
-    registry_url: Optional[str] = None
-    trusted_keys: List[str] = []
-    policy: TeamPolicy = Field(default_factory=TeamPolicy)
-
-class TeamManager:
-    def __init__(self, brain_path: Path):
-        self.brain_path = brain_path
-        self.config_path = brain_path / "config" / "team.json"
-        
-    def get_config(self) -> Optional[TeamConfig]:
-        """Load and return the current team configuration."""
-        if not self.config_path.exists():
-            return None
-            
-        try:
-            data = json.loads(self.config_path.read_text())
-            return TeamConfig(**data)
-        except Exception as e:
-            logger.error(f"Failed to load team config: {e}")
-            return None
-
-    def get_trusted_roots(self) -> List[str]:
-        """Return the list of trusted key fingerprints defined by the team."""
-        config = self.get_config()
-        if config:
-            return config.trusted_keys
-        return []
-        
-    def get_registry_url(self) -> Optional[str]:
-        """Return the team's private registry URL if configured."""
-        config = self.get_config()
-        if config:
-            return config.registry_url
-        return None