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

monoco/core/automation/__init__.py

@@ -2,8 +2,6 @@
 Automation Module - Event-driven automation framework.
 
 This module provides:
-- YAML/JSON configuration parsing
-- Trigger configuration management
 - Field change detection
 - Independent Event Handlers for Agent collaboration (FEAT-0162)
 
@@ -12,11 +10,6 @@ stateless microservice that responds to specific events. Workflow emerges
 from the natural interaction of handlers.
 """
 
-from .config import (
-    TriggerConfig,
-    AutomationConfig,
-    load_automation_config,
-)
 from .field_watcher import (
     YAMLFrontMatterExtractor,
     FieldWatcher,
@@ -32,10 +25,6 @@ from .handlers import (
 )
 
 __all__ = [
-    # Config
-    "TriggerConfig",
-    "AutomationConfig",
-    "load_automation_config",
     # Field watching
     "YAMLFrontMatterExtractor",
     "FieldWatcher",

monoco/core/automation/handlers.py

@@ -21,7 +21,7 @@ from __future__ import annotations
 
 import logging
 from pathlib import Path
-from typing import Any, Dict, Optional, Set
+from typing import Any, Dict, List, Optional, Set
 
 from monoco.core.scheduler import (
     AgentEvent,
@@ -31,6 +31,8 @@ from monoco.core.scheduler import (
     event_bus,
 )
 from monoco.core.router import ActionResult
+from monoco.features.memo.models import Memo
+from monoco.features.memo.core import load_memos, get_inbox_path
 
 logger = logging.getLogger(__name__)
 
@@ -361,6 +363,12 @@ class MemoThresholdHandler:
     Condition: Pending memo count exceeds threshold
     Action: Spawn Architect agent to analyze and create Issues
     
+    Signal Queue Model (FEAT-0165):
+    - Memos are signals, not assets
+    - File existence = signal pending
+    - File cleared = signal consumed
+    - Git is the archive, not app state
+    
     Emergent Workflow: Memos (threshold) → Architect → Issues
     
     This handler is stateless and self-contained.
@@ -384,7 +392,6 @@ class MemoThresholdHandler:
         self.name = name
         self.threshold = threshold
         self._subscribed = False
-        self._last_processed_count = 0
     
     def _should_handle(self, event: AgentEvent) -> bool:
         """
@@ -400,65 +407,110 @@ class MemoThresholdHandler:
             logger.debug(f"Pending count {pending_count} below threshold {self.threshold}")
             return False
         
-        if pending_count <= self._last_processed_count:
-            logger.debug(f"Already processed {self._last_processed_count} memos, skipping")
-            return False
-        
         return True
     
     async def _handle(self, event: AgentEvent) -> Optional[ActionResult]:
         """
         Handle the event by spawning Architect agent.
         
-        The Architect will:
-        1. Read the Memos/inbox.md file
-        2. Analyze accumulated ideas
-        3. Create appropriate Issue tickets
-        4. Clear or organize processed memos
+        Signal Queue Semantics:
+        1. Atomically load and clear inbox BEFORE scheduling
+        2. Memos are embedded in prompt, not read from file
+        3. File cleared = consumed, no state needed
+        
+        This ensures:
+        - Natural idempotency (deleted memos won't be reprocessed)
+        - No dependency on memory state across restarts
+        - Architect always has data even if file is cleared
         """
-        file_path = event.payload.get("path", "Memos/inbox.md")
+        file_path_str = event.payload.get("path", "Memos/inbox.md")
+        file_path = Path(file_path_str)
         pending_count = event.payload.get("pending_count", 0)
         
-        logger.info(f"MemoThresholdHandler: Spawning Architect for {pending_count} memos")
+        logger.info(f"MemoThresholdHandler: Processing {pending_count} memos")
         
-        self._last_processed_count = pending_count
+        # Phase 1: Atomically load and clear inbox
+        try:
+            # Load memos before clearing
+            memos = self._load_and_clear_memos(file_path)
+            if not memos:
+                logger.warning("Inbox was empty after locking, skipping")
+                return None
+        except Exception as e:
+            logger.error(f"Failed to load and clear inbox: {e}")
+            return ActionResult.failure_result(
+                error=f"Failed to consume memos: {e}",
+                metadata={"file_path": file_path_str},
+            )
         
+        # Phase 2: Schedule Architect with embedded memos
         task = AgentTask(
             task_id=f"architect-memo-{event.timestamp.timestamp()}",
             role_name="Architect",
             issue_id="memo-analysis",
-            prompt=self._build_prompt(file_path, pending_count),
+            prompt=self._build_prompt(file_path_str, memos),
             engine="gemini",
             timeout=900,
             metadata={
                 "trigger": "memo_threshold",
-                "file_path": file_path,
+                "file_path": file_path_str,
                 "pending_count": pending_count,
                 "threshold": self.threshold,
+                "memo_count": len(memos),
             },
         )
         
         try:
             session_id = await self.scheduler.schedule(task)
-            logger.info(f"Architect scheduled: session={session_id}")
+            logger.info(f"Architect scheduled: session={session_id} with {len(memos)} memos")
             
             return ActionResult.success_result(
                 output={
                     "session_id": session_id,
                     "role": "Architect",
                     "trigger": "memo_threshold",
-                    "pending_count": pending_count,
+                    "memo_count": len(memos),
                 },
-                metadata={"file_path": file_path},
+                metadata={"file_path": file_path_str},
             )
         
         except Exception as e:
             logger.error(f"Failed to spawn Architect: {e}")
+            # Note: At this point memos are already cleared from inbox
+            # This is intentional - we trade "at-least-once" for "at-most-once" semantics
+            # If Architect fails, the memos are in git history
             return ActionResult.failure_result(
                 error=f"Failed to schedule Architect: {e}",
-                metadata={"file_path": file_path},
+                metadata={"file_path": file_path_str, "memos_consumed": len(memos)},
             )
     
+    def _load_and_clear_memos(self, inbox_path: Path) -> List[Memo]:
+        """
+        Atomically load all memos and clear the inbox file.
+        
+        This implements the "consume" operation in signal queue model.
+        File existence is the state - clearing the file marks all signals consumed.
+        """
+        # Resolve path relative to project root if needed
+        if not inbox_path.is_absolute():
+            from monoco.core.config import find_monoco_root
+            project_root = find_monoco_root()
+            inbox_path = project_root / inbox_path
+        
+        if not inbox_path.exists():
+            return []
+        
+        # Load memos directly from inbox path
+        # inbox_path is Memos/inbox.md, issues_root is sibling: Issues/
+        issues_root = inbox_path.parent.parent / "Issues"
+        memos = load_memos(issues_root)
+        
+        # Clear inbox (atomic write)
+        inbox_path.write_text("# Monoco Memos Inbox\n\n", encoding="utf-8")
+        logger.info(f"Inbox cleared after consuming {len(memos)} memos")
+        
+        return memos
+    
     async def __call__(self, event: AgentEvent) -> Optional[ActionResult]:
         """Make handler callable - used as EventBus callback."""
         try:
@@ -486,18 +538,48 @@ class MemoThresholdHandler:
         self._subscribed = False
         logger.info(f"{self.name} stopped")
     
-    def _build_prompt(self, file_path: str, pending_count: int) -> str:
-        """Build the prompt for the Architect agent."""
-        return f"""You are the Architect. {pending_count} memos have accumulated in {file_path}.
+    def _build_prompt(self, file_path: str, memos: List[Memo]) -> str:
+        """Build the prompt for the Architect agent with embedded memos."""
+        # Format memos for prompt
+        memo_sections = []
+        for i, memo in enumerate(memos, 1):
+            section = f"""### Memo {i} (ID: {memo.uid})
+- **Time**: {memo.timestamp.strftime("%Y-%m-%d %H:%M:%S")}
+- **Type**: {memo.type}
+- **Source**: {memo.source}
+- **Author**: {memo.author}
+{'' if not memo.context else f'- **Context**: `{memo.context}`'}
+
+{memo.content}
+"""
+            memo_sections.append(section)
+        
+        memos_text = "\n".join(memo_sections)
+        
+        return f"""You are the Architect. {len(memos)} memos have been consumed from {file_path}.
 
-Your task:
-1. Read and analyze the accumulated memos
+## Consumed Memos (Signal Queue Model)
+
+The following memos have been atomically consumed from the inbox. 
+They are provided here for your analysis - do NOT read the inbox file as it has been cleared.
+
+{memos_text}
+
+## Your Task
+
+1. Analyze the accumulated memos above
 2. Categorize and prioritize the ideas
 3. Create Issue tickets for actionable items:
    - Use `monoco issue create` command
    - Set appropriate type (feature, fix, chore)
    - Set stage to 'draft' for review
-4. Organize or clear processed memos
+4. Link related memos to created issues via `source_memo` field if applicable
+
+## Signal Queue Semantics
+
+- Memos are signals, not assets - they are consumed (deleted) upon processing
+- No need to "resolve" or "link" memos - just create Issues from them
+- Historical memos can be found in git history if needed
 
 Focus on turning raw ideas into structured, actionable work items."""
 

monoco/core/config.py

@@ -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)