monoco-toolkit 0.3.11__py3-none-any.whl → 0.4.0__py3-none-any.whl

monoco/core/config.py

@@ -160,7 +160,7 @@ class AgentConcurrencyConfig(BaseModel):
     engineer: int = Field(default=1, description="Maximum concurrent Engineer agents")
     architect: int = Field(default=1, description="Maximum concurrent Architect agents")
     reviewer: int = Field(default=1, description="Maximum concurrent Reviewer agents")
-    planner: int = Field(default=1, description="Maximum concurrent Planner agents")
+    # Note: Planner role removed in FEAT-0155 (was never used)
     # Cool-down configuration
     failure_cooldown_seconds: int = Field(default=60, description="Cooldown period after a failure before retrying")
 
@@ -462,8 +462,13 @@ class ConfigMonitor:
         self.config_path = config_path
         self.on_change = on_change
         self.observer = Observer()
+        self._started = False
 
     async def start(self):
+        if self._started:
+            logger.warning(f"Config Monitor already started for {self.config_path}")
+            return
+
         loop = asyncio.get_running_loop()
         event_handler = ConfigEventHandler(loop, self.on_change, self.config_path)
 
@@ -471,15 +476,28 @@ class ConfigMonitor:
             # Ensure parent exists at least
             self.config_path.parent.mkdir(parents=True, exist_ok=True)
 
-        # We watch the parent directory for the specific file
-        self.observer.schedule(
-            event_handler, str(self.config_path.parent), recursive=False
-        )
-        self.observer.start()
-        logger.info(f"Config Monitor started for {self.config_path}")
+        # Watch the specific file, not the parent directory
+        # This avoids "already scheduled" errors when multiple files are in the same directory
+        try:
+            self.observer.schedule(
+                event_handler, str(self.config_path), recursive=False
+            )
+            self.observer.start()
+            self._started = True
+            logger.info(f"Config Monitor started for {self.config_path}")
+        except RuntimeError as e:
+            logger.error(f"Failed to start Config Monitor for {self.config_path}: {e}")
+            raise
 
     def stop(self):
-        if self.observer.is_alive():
-            self.observer.stop()
-            self.observer.join()
-        logger.info(f"Config Monitor stopped for {self.config_path}")
+        if not self._started:
+            return
+        try:
+            if self.observer.is_alive():
+                self.observer.stop()
+                self.observer.join()
+            logger.info(f"Config Monitor stopped for {self.config_path}")
+        except Exception as e:
+            logger.warning(f"Error stopping Config Monitor: {e}")
+        finally:
+            self._started = False

monoco/core/daemon/__init__.py

@@ -0,0 +1,5 @@
+"""Monoco Daemon core components."""
+
+from monoco.core.daemon.pid import PIDManager, PIDFileError, PortManager
+
+__all__ = ["PIDManager", "PIDFileError", "PortManager"]

monoco/core/daemon/pid.py

@@ -0,0 +1,290 @@
+"""PID file management and port utilities for Monoco Daemon."""
+
+import json
+import os
+import signal
+import socket
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+
+class PIDFileError(Exception):
+    """Exception raised for PID file related errors."""
+
+    pass
+
+
+class PIDManager:
+    """Manages PID file for workspace-scoped daemon process.
+
+    PID file format (JSON):
+    {
+        "pid": 12345,
+        "host": "127.0.0.1",
+        "port": 8642,
+        "started_at": "2026-02-03T12:00:00",
+        "version": "0.3.12"
+    }
+    """
+
+    PID_FILENAME = "monoco.pid"
+    PID_DIR = "run"
+
+    def __init__(self, workspace_root: Path):
+        self.workspace_root = Path(workspace_root)
+        self.pid_file = self._get_pid_file_path()
+
+    def _get_pid_file_path(self) -> Path:
+        """Get the PID file path for the workspace."""
+        pid_dir = self.workspace_root / ".monoco" / self.PID_DIR
+        pid_dir.mkdir(parents=True, exist_ok=True)
+        return pid_dir / self.PID_FILENAME
+
+    def create_pid_file(
+        self, host: str, port: int, version: str = "0.3.12"
+    ) -> Path:
+        """Create a PID file with process metadata.
+
+        Args:
+            host: The host address the daemon is listening on
+            port: The port the daemon is listening on
+            version: Monoco toolkit version
+
+        Returns:
+            Path to the created PID file
+
+        Raises:
+            PIDFileError: If PID file already exists and process is still alive
+        """
+        # Check for existing PID file
+        existing = self.read_pid_file()
+        if existing and self.is_process_alive(existing["pid"]):
+            raise PIDFileError(
+                f"Daemon already running (PID: {existing['pid']}, "
+                f"port: {existing['port']})"
+            )
+
+        # Clean up stale PID file if exists
+        if self.pid_file.exists():
+            self.remove_pid_file()
+
+        pid_data = {
+            "pid": os.getpid(),
+            "host": host,
+            "port": port,
+            "started_at": datetime.now().isoformat(),
+            "version": version,
+        }
+
+        # Write atomically using temp file
+        temp_file = self.pid_file.with_suffix(".tmp")
+        try:
+            with open(temp_file, "w", encoding="utf-8") as f:
+                json.dump(pid_data, f, indent=2)
+            temp_file.rename(self.pid_file)
+        except Exception as e:
+            if temp_file.exists():
+                temp_file.unlink()
+            raise PIDFileError(f"Failed to create PID file: {e}") from e
+
+        return self.pid_file
+
+    def read_pid_file(self) -> Optional[dict]:
+        """Read and parse the PID file.
+
+        Returns:
+            Dict with pid, host, port, started_at, version or None if not exists
+        """
+        if not self.pid_file.exists():
+            return None
+
+        try:
+            with open(self.pid_file, "r", encoding="utf-8") as f:
+                return json.load(f)
+        except (json.JSONDecodeError, IOError):
+            return None
+
+    def remove_pid_file(self) -> bool:
+        """Remove the PID file.
+
+        Returns:
+            True if file was removed, False if it didn't exist
+        """
+        try:
+            self.pid_file.unlink()
+            return True
+        except FileNotFoundError:
+            return False
+
+    @staticmethod
+    def is_process_alive(pid: int) -> bool:
+        """Check if a process with given PID is still running.
+
+        Args:
+            pid: Process ID to check
+
+        Returns:
+            True if process exists and is running
+        """
+        try:
+            os.kill(pid, 0)
+            return True
+        except (OSError, ProcessLookupError):
+            return False
+
+    def get_daemon_info(self) -> Optional[dict]:
+        """Get daemon info if it's running.
+
+        Returns:
+            Daemon info dict if running, None otherwise
+        """
+        pid_data = self.read_pid_file()
+        if not pid_data:
+            return None
+
+        if not self.is_process_alive(pid_data["pid"]):
+            # Stale PID file, clean it up
+            self.remove_pid_file()
+            return None
+
+        return pid_data
+
+    def send_signal(self, sig: int) -> bool:
+        """Send a signal to the daemon process.
+
+        Args:
+            sig: Signal to send (e.g., signal.SIGTERM)
+
+        Returns:
+            True if signal was sent successfully
+        """
+        pid_data = self.read_pid_file()
+        if not pid_data:
+            return False
+
+        pid = pid_data["pid"]
+        try:
+            os.kill(pid, sig)
+            return True
+        except (OSError, ProcessLookupError):
+            return False
+
+    def terminate(self, timeout: int = 5) -> bool:
+        """Gracefully terminate the daemon process.
+
+        Args:
+            timeout: Seconds to wait for graceful shutdown
+
+        Returns:
+            True if process was terminated
+        """
+        pid_data = self.read_pid_file()
+        if not pid_data:
+            return False
+
+        pid = pid_data["pid"]
+
+        # Try graceful shutdown first
+        try:
+            os.kill(pid, signal.SIGTERM)
+        except (OSError, ProcessLookupError):
+            # Process already gone
+            self.remove_pid_file()
+            return True
+
+        # Wait for process to terminate
+        import time
+
+        for _ in range(timeout * 10):
+            if not self.is_process_alive(pid):
+                self.remove_pid_file()
+                return True
+            time.sleep(0.1)
+
+        # Force kill if still running
+        try:
+            os.kill(pid, signal.SIGKILL)
+        except (OSError, ProcessLookupError):
+            pass
+
+        self.remove_pid_file()
+        return True
+
+
+class PortManager:
+    """Port management utilities for daemon."""
+
+    DEFAULT_PORT = 8642
+    MAX_PORT_RETRY = 100
+
+    @staticmethod
+    def is_port_in_use(port: int, host: str = "127.0.0.1") -> bool:
+        """Check if a port is already in use.
+
+        Args:
+            port: Port number to check
+            host: Host address to check
+
+        Returns:
+            True if port is in use
+        """
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+            try:
+                s.bind((host, port))
+                return False
+            except OSError:
+                return True
+
+    @classmethod
+    def find_available_port(
+        cls, start_port: int = DEFAULT_PORT, host: str = "127.0.0.1", max_retry: int = MAX_PORT_RETRY
+    ) -> int:
+        """Find an available port starting from start_port.
+
+        Args:
+            start_port: Starting port number
+            host: Host address to bind
+            max_retry: Maximum number of ports to try
+
+        Returns:
+            Available port number
+
+        Raises:
+            PIDFileError: If no available port found within range
+        """
+        for port in range(start_port, start_port + max_retry):
+            if not cls.is_port_in_use(port, host):
+                return port
+
+        raise PIDFileError(
+            f"No available port found in range {start_port}-{start_port + max_retry - 1}"
+        )
+
+    @classmethod
+    def get_port_with_fallback(
+        cls, preferred_port: int = DEFAULT_PORT, host: str = "127.0.0.1", auto_increment: bool = True
+    ) -> int:
+        """Get a port, either the preferred one or an available fallback.
+
+        Args:
+            preferred_port: Preferred port to use
+            host: Host address
+            auto_increment: If True, find next available port; if False, raise error
+
+        Returns:
+            Port number to use
+
+        Raises:
+            PIDFileError: If preferred port is in use and auto_increment is False
+        """
+        if not cls.is_port_in_use(preferred_port, host):
+            return preferred_port
+
+        if not auto_increment:
+            raise PIDFileError(
+                f"Port {preferred_port} is already in use. "
+                f"Use --port to specify a different port."
+            )
+
+        return cls.find_available_port(preferred_port + 1, host)

monoco/core/git.py

@@ -230,6 +230,21 @@ def worktree_remove(path: Path, worktree_path: Path, force: bool = False):
         raise RuntimeError(f"Failed to remove worktree: {stderr}")
 
 
+def get_current_head(path: Path) -> str:
+    """Get the current HEAD commit hash."""
+    code, stdout, stderr = _run_git(["rev-parse", "HEAD"], path)
+    if code != 0:
+        raise RuntimeError(f"Failed to get current HEAD: {stderr}")
+    return stdout.strip()
+
+
+def git_reset_hard(path: Path, ref: str):
+    """Reset the repository to a specific ref using --hard."""
+    code, _, stderr = _run_git(["reset", "--hard", ref], path)
+    if code != 0:
+        raise RuntimeError(f"Git reset --hard to {ref} failed: {stderr}")
+
+
 class GitMonitor:
     """
     Polls the Git repository for HEAD changes and triggers updates.

monoco/core/hooks/context.py

@@ -74,29 +74,90 @@ class HookContext:
     extra: Dict[str, Any] = field(default_factory=dict)
     
     @classmethod
-    def from_runtime_session(
+    def from_agent_task(
         cls,
-        runtime_session: Any,
+        task: Any,
         project_root: Optional[Path] = None,
     ) -> "HookContext":
         """
-        Create a HookContext from a RuntimeSession.
+        Create a HookContext from an AgentTask.
         
         Args:
-            runtime_session: The RuntimeSession object
+            task: The AgentTask object
             project_root: Optional project root path
             
         Returns:
             A populated HookContext
         """
-        model = runtime_session.model
+        # Build IssueInfo if we have an issue_id
+        issue_info = None
+        issue_id = getattr(task, "issue_id", None)
+        if issue_id:
+            issue_info = IssueInfo(
+                id=issue_id,
+            )
+            
+            # Try to load full issue metadata
+            try:
+                from monoco.features.issue.core import find_issue_path, parse_issue
+                from monoco.core.config import find_monoco_root
+                
+                if project_root is None:
+                    project_root = find_monoco_root()
+                
+                issues_root = project_root / "Issues"
+                issue_path = find_issue_path(issues_root, issue_id)
+                if issue_path:
+                    metadata = parse_issue(issue_path)
+                    if metadata:
+                        issue_info = IssueInfo.from_metadata(metadata)
+            except Exception:
+                pass  # Use basic issue info
         
+        # Build GitInfo
+        git_info = None
+        if project_root:
+            git_info = GitInfo(project_root=project_root)
+        
+        return cls(
+            session_id=getattr(task, "task_id", "unknown"),
+            role_name=getattr(task, "role_name", "unknown"),
+            session_status="pending",
+            created_at=getattr(task, "created_at", datetime.now()),
+            issue=issue_info,
+            git=git_info,
+        )
+    
+    @classmethod
+    def from_session_state(
+        cls,
+        session_id: str,
+        role_name: str,
+        issue_id: Optional[str],
+        status: str,
+        project_root: Optional[Path] = None,
+    ) -> "HookContext":
+        """
+        Create a HookContext from session state parameters.
+        
+        This is a more flexible factory method that doesn't depend on
+        specific session implementations.
+        
+        Args:
+            session_id: The session/task ID
+            role_name: The role name
+            issue_id: Optional issue ID
+            status: Session status
+            project_root: Optional project root path
+            
+        Returns:
+            A populated HookContext
+        """
         # Build IssueInfo if we have an issue_id
         issue_info = None
-        if model.issue_id:
+        if issue_id:
             issue_info = IssueInfo(
-                id=model.issue_id,
-                branch_name=model.branch_name,
+                id=issue_id,
             )
             
             # Try to load full issue metadata
@@ -108,7 +169,7 @@ class HookContext:
                     project_root = find_monoco_root()
                 
                 issues_root = project_root / "Issues"
-                issue_path = find_issue_path(issues_root, model.issue_id)
+                issue_path = find_issue_path(issues_root, issue_id)
                 if issue_path:
                     metadata = parse_issue(issue_path)
                     if metadata:
@@ -122,10 +183,10 @@ class HookContext:
             git_info = GitInfo(project_root=project_root)
         
         return cls(
-            session_id=model.id,
-            role_name=model.role_name,
-            session_status=model.status,
-            created_at=model.created_at,
+            session_id=session_id,
+            role_name=role_name,
+            session_status=status,
+            created_at=datetime.now(),
             issue=issue_info,
             git=git_info,
         )

monoco/core/injection.py

@@ -1,6 +1,6 @@
 import re
 from pathlib import Path
-from typing import Dict
+from typing import Dict, Optional
 
 
 class PromptInjector:
@@ -13,8 +13,52 @@ class PromptInjector:
     MANAGED_START = "<!-- MONOCO_GENERATED_START -->"
     MANAGED_END = "<!-- MONOCO_GENERATED_END -->"
 
-    def __init__(self, target_file: Path):
+    FILE_HEADER_COMMENT = """<!--
+⚠️ IMPORTANT: This file is partially managed by Monoco.
+- Content between MONOCO_GENERATED_START and MONOCO_GENERATED_END is auto-generated.
+- Do NOT manually edit the managed block.
+- Do NOT add content after MONOCO_GENERATED_END (use separate files instead).
+-->
+
+"""
+
+    def __init__(self, target_file: Path, verbose: bool = True):
         self.target_file = target_file
+        self.verbose = verbose
+
+    def _detect_external_content(self, content: str) -> Optional[str]:
+        """
+        Detects content outside the managed block.
+
+        Returns:
+            The external content string if found, None otherwise.
+        """
+        if not content or self.MANAGED_END not in content:
+            return None
+
+        # Split by MANAGED_END and check if there's non-empty content after
+        parts = content.split(self.MANAGED_END)
+        if len(parts) < 2:
+            return None
+
+        post_content = parts[-1].strip()
+        # Check if there's meaningful content (not just whitespace or newlines)
+        if post_content and len(post_content) > 10:  # Threshold to avoid false positives
+            return post_content
+        return None
+
+    def _warn_external_content(self, external_content: str):
+        """Outputs warning about external content."""
+        if not self.verbose:
+            return
+
+        # Truncate long content for warning message
+        preview = external_content[:200].replace("\n", " ")
+        if len(external_content) > 200:
+            preview += "..."
+
+        print(f"⚠️  Warning: Manual content detected after Managed Block in {self.target_file}")
+        print(f"   Consider moving to a separate file. Found content starting with: {preview}")
 
     def inject(self, prompts: Dict[str, str]) -> bool:
         """
@@ -30,6 +74,11 @@ class PromptInjector:
         if self.target_file.exists():
             current_content = self.target_file.read_text(encoding="utf-8")
 
+        # Check for external content and warn
+        external_content = self._detect_external_content(current_content)
+        if external_content:
+            self._warn_external_content(external_content)
+
         new_content = self._merge_content(current_content, prompts)
 
         if new_content != current_content:
@@ -76,12 +125,18 @@ class PromptInjector:
         managed_block_str = "\n".join(managed_block).strip() + "\n"
         managed_block_str = f"{self.MANAGED_START}\n{managed_block_str}\n{self.MANAGED_END}\n"
 
+        # 2. Add file header comment if not present
+        has_header = original.strip().startswith("<!--") and "IMPORTANT: This file is partially managed by Monoco" in original
+
         # 2. Find and replace/append in the original content
         # Check for delimiters first
         if self.MANAGED_START in original and self.MANAGED_END in original:
             try:
                 pre = original.split(self.MANAGED_START)[0]
                 post = original.split(self.MANAGED_END)[1]
+                # Add header comment if not present
+                if not has_header and not pre.strip().startswith("<!--"):
+                    pre = self.FILE_HEADER_COMMENT + pre
                 # Reconstruct
                 return pre + managed_block_str.strip() + post
             except IndexError:
@@ -105,12 +160,16 @@ class PromptInjector:
 
         if start_idx == -1:
             # Block not found, append to end
+            result = ""
+            if not has_header:
+                result = self.FILE_HEADER_COMMENT
             if original and not original.endswith("\n"):
-                return original + "\n\n" + managed_block_str.strip()
+                result += original + "\n\n" + managed_block_str.strip()
             elif original:
-                return original + "\n" + managed_block_str.strip()
+                result += original + "\n" + managed_block_str.strip()
             else:
-                return managed_block_str.strip() + "\n"
+                result += managed_block_str.strip() + "\n"
+            return result
 
         # Find end: Look for next header of level 1 or 2 (siblings or parents)
         header_level_match = re.match(r"^(#+)\s", self.MANAGED_HEADER)
@@ -134,9 +193,13 @@ class PromptInjector:
         pre_block = "\n".join(lines[:start_idx])
         post_block = "\n".join(lines[end_idx:])
 
-        result = pre_block
-        if result:
-            result += "\n\n"
+        result = ""
+        # Add header comment if not present
+        if not has_header and not pre_block.strip().startswith("<!--"):
+            result = self.FILE_HEADER_COMMENT
+
+        if pre_block:
+            result += pre_block + "\n\n"
 
         result += managed_block_str
 
@@ -218,6 +281,21 @@ class PromptInjector:
         pre_block = lines[:start_idx]
         post_block = lines[end_idx:]
 
+        # Check if pre_block contains only the file header comment
+        pre_text = "\n".join(pre_block)
+        if pre_text.strip() and "This file is partially managed by Monoco" in pre_text:
+            # Check if pre_block is just the header comment
+            is_only_header = all(
+                line.strip().startswith("<!--") or
+                line.strip().startswith("⚠️ IMPORTANT") or
+                line.strip().startswith("-") or
+                line.strip().startswith("-->") or
+                not line.strip()
+                for line in pre_block
+            )
+            if is_only_header and not post_block:
+                pre_block = []
+
         # If we removed everything, the file might become empty or just newlines
 
         new_lines = pre_block + post_block

monoco/core/integrations.py

@@ -94,14 +94,6 @@ class AgentProviderHealth(BaseModel):
 
 # Default Integration Registry
 DEFAULT_INTEGRATIONS: Dict[str, AgentIntegration] = {
-    "cursor": AgentIntegration(
-        key="cursor",
-        name="Cursor",
-        system_prompt_file=".cursorrules",
-        skill_root_dir=".cursor/skills/",
-        bin_name="cursor",
-        version_cmd="--version",
-    ),
     "claude": AgentIntegration(
         key="claude",
         name="Claude Code",
@@ -118,22 +110,6 @@ DEFAULT_INTEGRATIONS: Dict[str, AgentIntegration] = {
         bin_name="gemini",
         version_cmd="--version",
     ),
-    "qwen": AgentIntegration(
-        key="qwen",
-        name="Qwen Code",
-        system_prompt_file="QWEN.md",
-        skill_root_dir=".qwen/skills/",
-        bin_name="qwen",
-        version_cmd="--version",
-    ),
-    "kimi": AgentIntegration(
-        key="kimi",
-        name="Kimi CLI",
-        system_prompt_file="AGENTS.md",
-        skill_root_dir=".agent/skills/",
-        bin_name="kimi",
-        version_cmd="--version",
-    ),
     "agent": AgentIntegration(
         key="agent",
         name="Generic Agent",