@smilintux/skcapstone 0.4.6 → 0.5.0

package/src/skcapstone/brain_first.py

@@ -0,0 +1,238 @@
+"""
+Brain-First Protocol — think before you act.
+
+Before an agent acts on any task, it consults its memory to see if it
+already knows something relevant.  This avoids redundant work, surfaces
+prior decisions, and grounds the agent in its own experience.
+
+Usage:
+    from skcapstone.brain_first import brain_first_check
+
+    result = brain_first_check("deploy the monitoring stack")
+    if result.has_memories:
+        # use result.memories as additional context
+        ...
+
+Configuration (config.yaml):
+    brain_first:
+      enabled: true          # master toggle (default: true)
+      max_results: 5          # how many memories to surface (default: 5)
+      min_importance: 0.3     # ignore low-importance memories (default: 0.3)
+      auto_inject: false      # auto-prepend memories to MCP tool responses (default: false)
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+logger = logging.getLogger("skcapstone.brain_first")
+
+# Stop-words to strip from queries before searching memory
+_STOP_WORDS = frozenset({
+    "a", "an", "the", "is", "are", "was", "were", "be", "been", "being",
+    "have", "has", "had", "do", "does", "did", "will", "would", "shall",
+    "should", "may", "might", "must", "can", "could", "to", "of", "in",
+    "for", "on", "with", "at", "by", "from", "as", "into", "through",
+    "during", "before", "after", "above", "below", "between", "out",
+    "off", "over", "under", "again", "further", "then", "once", "here",
+    "there", "when", "where", "why", "how", "all", "each", "every",
+    "both", "few", "more", "most", "other", "some", "such", "no", "nor",
+    "not", "only", "own", "same", "so", "than", "too", "very", "just",
+    "because", "but", "and", "or", "if", "while", "about", "up", "it",
+    "its", "this", "that", "these", "those", "i", "me", "my", "we",
+    "our", "you", "your", "he", "him", "his", "she", "her", "they",
+    "them", "their", "what", "which", "who", "whom",
+})
+
+
+@dataclass
+class BrainFirstConfig:
+    """Configuration for the brain-first protocol."""
+
+    enabled: bool = True
+    max_results: int = 5
+    min_importance: float = 0.3
+    auto_inject: bool = False
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "BrainFirstConfig":
+        """Create config from a dict (e.g. from config.yaml brain_first section)."""
+        return cls(
+            enabled=data.get("enabled", True),
+            max_results=data.get("max_results", 5),
+            min_importance=data.get("min_importance", 0.3),
+            auto_inject=data.get("auto_inject", False),
+        )
+
+
+@dataclass
+class BrainFirstResult:
+    """Result of a brain-first memory consultation."""
+
+    query: str
+    keywords: list[str]
+    memories: list[dict] = field(default_factory=list)
+    enabled: bool = True
+    error: Optional[str] = None
+
+    @property
+    def has_memories(self) -> bool:
+        """Whether any relevant memories were found."""
+        return len(self.memories) > 0
+
+    def as_context(self) -> str:
+        """Format memories as a context block for injection into prompts."""
+        if not self.has_memories:
+            return ""
+        lines = ["[Brain-First: relevant memories found]"]
+        for i, mem in enumerate(self.memories, 1):
+            content = mem.get("content", "")[:200]
+            layer = mem.get("layer", "?")
+            importance = mem.get("importance", 0)
+            tags = ", ".join(mem.get("tags", []))
+            lines.append(
+                f"  {i}. [{layer}|imp={importance:.1f}] {content}"
+                + (f"  tags: {tags}" if tags else "")
+            )
+        return "\n".join(lines)
+
+
+def extract_keywords(text: str) -> list[str]:
+    """Extract meaningful keywords from a text string.
+
+    Strips stop-words and short tokens, keeping domain-relevant terms.
+
+    Args:
+        text: Input text (task title, prompt, etc.).
+
+    Returns:
+        List of unique keywords, longest first.
+    """
+    # Lowercase, split on non-alphanumeric
+    tokens = re.split(r"[^a-zA-Z0-9_-]+", text.lower())
+    # Filter: no stop-words, no short tokens
+    keywords = list(dict.fromkeys(
+        t for t in tokens if t and t not in _STOP_WORDS and len(t) > 2
+    ))
+    # Sort longest first (longer terms tend to be more specific)
+    keywords.sort(key=len, reverse=True)
+    return keywords
+
+
+def _load_config() -> BrainFirstConfig:
+    """Load brain-first config from the agent's config.yaml.
+
+    Falls back to defaults if the file or section is missing.
+    """
+    try:
+        import yaml
+    except ImportError:
+        return BrainFirstConfig()
+
+    from . import AGENT_HOME, SKCAPSTONE_AGENT
+
+    for base in [
+        Path(AGENT_HOME).expanduser() / "agents" / SKCAPSTONE_AGENT,
+        Path(AGENT_HOME).expanduser(),
+    ]:
+        config_file = base / "config" / "config.yaml"
+        if config_file.exists():
+            try:
+                data = yaml.safe_load(config_file.read_text(encoding="utf-8")) or {}
+                bf_data = data.get("brain_first", {})
+                if bf_data:
+                    return BrainFirstConfig.from_dict(bf_data)
+            except Exception as exc:
+                logger.debug("Failed to load brain_first config from %s: %s", config_file, exc)
+
+    return BrainFirstConfig()
+
+
+def brain_first_check(
+    context: str,
+    config: Optional[BrainFirstConfig] = None,
+    tags: Optional[list[str]] = None,
+) -> BrainFirstResult:
+    """Consult memory before acting on a task.
+
+    This is the core brain-first function.  Given a task description or
+    prompt context, it extracts keywords, searches memory, and returns
+    any relevant memories that the agent should consider.
+
+    Args:
+        context: The task description, prompt, or action context.
+        config: Override config (uses agent config.yaml if None).
+        tags: Optional tag filter for the memory search.
+
+    Returns:
+        BrainFirstResult with any relevant memories.
+    """
+    if config is None:
+        config = _load_config()
+
+    keywords = extract_keywords(context)
+    result = BrainFirstResult(
+        query=context,
+        keywords=keywords,
+        enabled=config.enabled,
+    )
+
+    if not config.enabled:
+        result.error = "brain-first protocol disabled"
+        return result
+
+    if not keywords:
+        result.error = "no meaningful keywords extracted"
+        return result
+
+    # Build a search query from top keywords (limit to 6 to avoid noise)
+    search_query = " ".join(keywords[:6])
+
+    try:
+        from .memory_engine import search as memory_search
+        from .mcp_tools._helpers import _home
+
+        home = _home()
+        entries = memory_search(
+            home=home,
+            query=search_query,
+            tags=tags,
+            limit=config.max_results * 2,  # over-fetch, then filter
+        )
+
+        # Filter by minimum importance
+        entries = [e for e in entries if e.importance >= config.min_importance]
+
+        # Truncate to max_results
+        entries = entries[:config.max_results]
+
+        result.memories = [
+            {
+                "memory_id": e.memory_id,
+                "content": e.content[:300],
+                "layer": e.layer.value,
+                "tags": e.tags,
+                "importance": e.importance,
+                "access_count": e.access_count,
+                "source": e.source,
+            }
+            for e in entries
+        ]
+
+        logger.info(
+            "Brain-first check: %d memories found for %d keywords from '%s'",
+            len(result.memories),
+            len(keywords),
+            context[:80],
+        )
+
+    except Exception as exc:
+        result.error = f"memory search failed: {exc}"
+        logger.warning("Brain-first check failed: %s", exc)
+
+    return result

package/src/skcapstone/chat.py

@@ -204,8 +204,8 @@ class AgentChat:
                                     thread_id=msg_dict.get("thread_id"),
                                 )
                                 history.store_message(chat_msg)
-                            except Exception:
-                                pass
+                            except Exception as exc:
+                                logger.warning("Failed to store received message in history: %s", exc)
             except Exception as exc:
                 logger.warning("Receive error: %s", exc)
 
@@ -410,8 +410,8 @@ class AgentChat:
                             state["last_recv_thread"] = recv_thread
                         display = _format_content(content)
                         print(f"\n  \033[32m{sender}\033[0m \033[2m[{ts}]\033[0m  {display}\n")
-                except Exception:
-                    pass
+                except Exception as exc:
+                    logger.warning("Chat poll loop error: %s", exc)
 
         # Print header
         tr_label = "✓ connected" if transport_ok else "✗ local-only"

package/src/skcapstone/cli/__init__.py

@@ -86,6 +86,7 @@ from .search_cmd import register_search_commands
 from .mood_cmd import register_mood_commands
 from .register_cmd import register_register_commands
 from .gtd import register_gtd_commands
+from .itil import register_itil_commands
 from .skseed import register_skseed_commands
 from .service_cmd import register_service_commands
 from .telegram import register_telegram_commands
@@ -138,6 +139,7 @@ register_search_commands(main)
 register_mood_commands(main)
 register_register_commands(main)
 register_gtd_commands(main)
+register_itil_commands(main)
 register_skseed_commands(main)
 register_service_commands(main)
 register_telegram_commands(main)

package/src/skcapstone/cli/agents_spawner.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import logging
 from pathlib import Path
 from typing import Optional
 
@@ -12,6 +13,8 @@ from ._common import AGENT_HOME, console
 from rich.panel import Panel
 from rich.table import Table
 
+logger = logging.getLogger(__name__)
+
 
 def _resolve_provider_backend(provider: Optional[str], home_path: Path):
     """Resolve provider string to backend object and ProviderType.
@@ -37,8 +40,8 @@ def _resolve_provider_backend(provider: Optional[str], home_path: Path):
                 prov_backend = DockerProvider()
             elif prov_type == ProviderType.PROXMOX:
                 prov_backend = ProxmoxProvider()
-        except Exception:
-            pass
+        except Exception as exc:
+            logger.warning("Failed to initialize provider backend for %s: %s", provider, exc)
     return prov_backend, prov_type
 
 

package/src/skcapstone/cli/chat.py

@@ -13,12 +13,15 @@ skcapstone chat summary <peer>      LLM-powered conversation summary
 from __future__ import annotations
 
 import json
+import logging
 import sys
 from pathlib import Path
 from typing import Optional
 
 import click
 
+logger = logging.getLogger(__name__)
+
 from ._common import AGENT_HOME, console, get_runtime
 from ._validators import validate_agent_name
 
@@ -85,8 +88,8 @@ def _run_llm_chat(peer: str, home_path: Path, identity: str) -> None:
                     content = msg.get("content", "")[:100]
                     console.print(f"  {label}: {content}")
                 console.print()
-        except Exception:
-            pass
+        except Exception as exc:
+            logger.warning("Failed to load previous conversation history with %s: %s", peer, exc)
 
     console.print(f"[bold]Chat with [cyan]{peer}[/][/]  [dim]Ctrl+C or /quit to exit[/]\n")
 

package/src/skcapstone/cli/consciousness.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import json
+import logging
 import sys
 from pathlib import Path
 
@@ -10,6 +11,8 @@ import click
 
 from ._common import AGENT_HOME, console
 
+logger = logging.getLogger(__name__)
+
 
 def register_consciousness_commands(main: click.Group) -> None:
     """Register the consciousness command group."""
@@ -233,8 +236,8 @@ def register_consciousness_commands(main: click.Group) -> None:
                 try:
                     file_data = json.loads(daily.read_text(encoding="utf-8"))
                     quality = file_data.get("quality_avg", {})
-                except Exception:
-                    pass
+                except Exception as exc:
+                    logger.warning("Failed to read daily quality metrics from %s: %s", daily, exc)
 
         if not quality or quality.get("count", 0) == 0:
             if json_out:

package/src/skcapstone/cli/daemon.py

@@ -270,60 +270,117 @@ def register_daemon_commands(main: click.Group) -> None:
             console.print(f"  [yellow]API unreachable on port {effective_port}[/]\n")
 
     @daemon.command("install")
-    def daemon_install():
-        """Install the daemon as a systemd user service.
+    @click.option("--agent", "agent_name", default=None,
+                  help="Agent name for SKCAPSTONE_AGENT (default: from env or 'sovereign').")
+    @click.option("--start", is_flag=True, help="Start services immediately after installing.")
+    def daemon_install(agent_name: str | None, start: bool):
+        """Install the daemon as a system service.
 
-        Copies unit files to ~/.config/systemd/user/, enables at login,
-        and starts immediately. No root required.
+        On Linux: installs systemd user service units.
+        On macOS: installs launchd plist files to ~/Library/LaunchAgents/.
+
+        The --agent flag sets the SKCAPSTONE_AGENT environment variable
+        in the service definition. If not provided, uses the
+        SKCAPSTONE_AGENT env var or defaults to 'sovereign'.
 
         Examples:
 
             skcapstone daemon install
+
+            skcapstone daemon install --agent myagent --start
         """
-        from ..systemd import install_service, systemd_available
+        import platform
 
-        if not systemd_available():
-            console.print("[red]systemd user session not available.[/]")
-            console.print("[dim]This command requires a Linux system with systemd.[/]")
-            raise SystemExit(1)
+        effective_agent = agent_name or os.environ.get("SKCAPSTONE_AGENT", "sovereign")
 
-        console.print("\n[cyan]Installing skcapstone systemd service...[/]")
-        result = install_service()
+        if platform.system() == "Darwin":
+            from ..launchd import install_service as launchd_install
 
-        if result["installed"]:
-            console.print("[green]  Unit files installed.[/]")
-        if result["enabled"]:
-            console.print("[green]  Service enabled at login.[/]")
-        if result["started"]:
-            console.print("[green]  Service started.[/]")
-        console.print()
+            console.print(f"\n[cyan]Installing launchd services for agent '{effective_agent}'...[/]")
+            result = launchd_install(agent_name=effective_agent, start=start)
+
+            if result["installed"]:
+                for svc in result.get("services", []):
+                    status = "[green]loaded[/]" if svc.get("loaded") else "[green]installed[/]"
+                    console.print(f"  [green]✓[/] {svc['label']} — {status}")
+                console.print()
+                console.print("[dim]  Manage: launchctl list | grep skcapstone[/]")
+                if not start:
+                    console.print("[dim]  Start:  launchctl start com.skcapstone.daemon[/]")
+                    console.print("[dim]  Or re-run with --start to load immediately.[/]")
+            else:
+                console.print("[red]Installation failed. Check logs.[/]")
+                raise SystemExit(1)
+            console.print()
 
-        if not result["installed"]:
-            console.print("[red]Installation failed. Check logs.[/]")
+        elif platform.system() == "Linux":
+            from ..systemd import install_service, systemd_available
+
+            if not systemd_available():
+                console.print("[red]systemd user session not available.[/]")
+                console.print("[dim]This command requires a Linux system with systemd.[/]")
+                raise SystemExit(1)
+
+            console.print("\n[cyan]Installing skcapstone systemd service...[/]")
+            result = install_service(start=start)
+
+            if result["installed"]:
+                console.print("[green]  Unit files installed.[/]")
+            if result["enabled"]:
+                console.print("[green]  Service enabled at login.[/]")
+            if result.get("started"):
+                console.print("[green]  Service started.[/]")
+            console.print()
+
+            if not result["installed"]:
+                console.print("[red]Installation failed. Check logs.[/]")
+                raise SystemExit(1)
+        else:
+            console.print(f"[red]Auto-start not supported on {platform.system()}.[/]")
             raise SystemExit(1)
 
     @daemon.command("uninstall")
     def daemon_uninstall():
-        """Uninstall the systemd user service.
+        """Uninstall the system service.
 
-        Stops, disables, and removes the unit files.
+        On Linux: stops, disables, and removes systemd unit files.
+        On macOS: unloads and removes launchd plist files.
 
         Examples:
 
             skcapstone daemon uninstall
         """
-        from ..systemd import uninstall_service
+        import platform
 
-        console.print("\n[cyan]Uninstalling skcapstone systemd service...[/]")
-        result = uninstall_service()
+        if platform.system() == "Darwin":
+            from ..launchd import uninstall_service as launchd_uninstall
 
-        if result["stopped"]:
-            console.print("[green]  Service stopped.[/]")
-        if result["disabled"]:
-            console.print("[green]  Service disabled.[/]")
-        if result["removed"]:
-            console.print("[green]  Unit files removed.[/]")
-        console.print()
+            console.print("\n[cyan]Uninstalling skcapstone launchd services...[/]")
+            result = launchd_uninstall()
+
+            if result["stopped"]:
+                console.print("[green]  Services unloaded.[/]")
+            if result["removed"]:
+                for label in result.get("services", []):
+                    console.print(f"  [green]✓[/] Removed {label}")
+            console.print()
+
+        elif platform.system() == "Linux":
+            from ..systemd import uninstall_service
+
+            console.print("\n[cyan]Uninstalling skcapstone systemd service...[/]")
+            result = uninstall_service()
+
+            if result["stopped"]:
+                console.print("[green]  Service stopped.[/]")
+            if result["disabled"]:
+                console.print("[green]  Service disabled.[/]")
+            if result["removed"]:
+                console.print("[green]  Unit files removed.[/]")
+            console.print()
+
+        else:
+            console.print(f"[red]Not supported on {platform.system()}.[/]")
 
     @daemon.command("components")
     @click.option("--agent", default=None, help="Named agent to query.")
@@ -413,7 +470,10 @@ def register_daemon_commands(main: click.Group) -> None:
     @click.option("--lines", "-n", default=50, help="Number of lines (default: 50).")
     @click.option("--follow", "-f", is_flag=True, help="Show the command to follow logs live.")
     def daemon_logs(lines: int, follow: bool):
-        """Show daemon logs from journald.
+        """Show daemon logs.
+
+        On Linux: reads from journald.
+        On macOS: reads from ~/.skcapstone/logs/ files.
 
         Examples:
 
@@ -423,14 +483,29 @@ def register_daemon_commands(main: click.Group) -> None:
 
             skcapstone daemon logs -f
         """
-        from ..systemd import service_logs
+        import platform
 
-        if follow:
-            cmd = service_logs(follow=True)
-            console.print(f"\n  Run: [bold cyan]{cmd}[/]\n")
+        if platform.system() == "Darwin":
+            if follow:
+                log_path = Path.home() / ".skcapstone" / "logs" / "daemon.stdout.log"
+                console.print(f"\n  Run: [bold cyan]tail -f {log_path}[/]\n")
+            else:
+                from ..launchd import service_logs
+                output = service_logs(lines=lines)
+                if output.strip():
+                    click.echo(output)
+                else:
+                    console.print("[dim]No logs found in ~/.skcapstone/logs/[/]")
+                    console.print("[dim]Is the service installed? Run: skcapstone daemon install[/]")
         else:
-            output = service_logs(lines=lines)
-            if output.strip():
-                click.echo(output)
+            from ..systemd import service_logs
+
+            if follow:
+                cmd = service_logs(follow=True)
+                console.print(f"\n  Run: [bold cyan]{cmd}[/]\n")
             else:
-                console.print("[dim]No logs found. Is the service installed?[/]")
+                output = service_logs(lines=lines)
+                if output.strip():
+                    click.echo(output)
+                else:
+                    console.print("[dim]No logs found. Is the service installed?[/]")