@smilintux/skcapstone 0.1.0 → 0.2.3

package/src/skcapstone/register.py

@@ -0,0 +1,241 @@
+"""SK* suite registration orchestrator.
+
+Single source of truth for all SK* packages and their MCP servers.
+Called by `skcapstone register` and wired into `skcapstone update`.
+
+Usage:
+    from skcapstone.register import register_all
+
+    results = register_all()            # auto-detect everything
+    results = register_all(dry_run=True)  # show what would happen
+"""
+
+from __future__ import annotations
+
+import importlib.resources
+from pathlib import Path
+from typing import Optional
+
+from skmemory.register import detect_environments, register_package
+
+
+# ── Helpers ──────────────────────────────────────────────────────────────────
+
+
+def _get_skgit_env() -> Optional[dict]:
+    """Read skgit token from config file if available."""
+    token_path = Path.home() / ".config" / "skgit" / "token"
+    try:
+        token = token_path.read_text().strip()
+    except (FileNotFoundError, PermissionError):
+        token = ""
+
+    if not token:
+        return None
+
+    return {
+        "GITEA_HOST": "https://skgit.skstack01.douno.it",
+        "GITEA_ACCESS_TOKEN": token,
+    }
+
+
+# ── SK* package registry ─────────────────────────────────────────────────────
+
+
+def _build_package_registry(workspace: Optional[Path] = None) -> list[dict]:
+    """Build the SK* package registry with resolved env vars and plugin paths."""
+    if workspace is None:
+        workspace = Path.home() / "clawd"
+
+    return [
+        {
+            "name": "skmemory",
+            "mcp_cmd": "skmemory-mcp",
+            "mcp_args": [],
+            "mcp_env": None,
+            "openclaw_plugin_path": workspace / "pillar-repos" / "skmemory" / "openclaw-plugin" / "src" / "index.ts",
+        },
+        {
+            "name": "skcapstone",
+            "mcp_cmd": "skcapstone-mcp",
+            "mcp_args": [],
+            "mcp_env": None,
+            "openclaw_plugin_path": workspace / "skcapstone" / "openclaw-plugin" / "src" / "index.ts",
+        },
+        {
+            "name": "skcomm",
+            "mcp_cmd": "skcomm-mcp",
+            "mcp_args": [],
+            "mcp_env": None,
+            "openclaw_plugin_path": workspace / "pillar-repos" / "skcomm" / "openclaw-plugin" / "src" / "index.ts",
+        },
+        {
+            "name": "skchat",
+            "mcp_cmd": "skchat-mcp",
+            "mcp_args": [],
+            "mcp_env": None,
+            "openclaw_plugin_path": workspace / "pillar-repos" / "skchat" / "openclaw-plugin" / "src" / "index.ts",
+        },
+        {
+            "name": "capauth",
+            "mcp_cmd": None,
+            "mcp_args": None,
+            "mcp_env": None,
+            "openclaw_plugin_path": workspace / "pillar-repos" / "capauth" / "openclaw-plugin" / "src" / "index.ts",
+        },
+        {
+            "name": "cloud9",
+            "mcp_cmd": None,
+            "mcp_args": None,
+            "mcp_env": None,
+            "openclaw_plugin_path": workspace / "pillar-repos" / "cloud9-python" / "openclaw-plugin" / "src" / "index.ts",
+        },
+        {
+            "name": "sksecurity",
+            "mcp_cmd": None,
+            "mcp_args": None,
+            "mcp_env": None,
+            "openclaw_plugin_path": workspace / "pillar-repos" / "sksecurity" / "openclaw-plugin" / "src" / "index.ts",
+        },
+        {
+            "name": "skgit",
+            "mcp_cmd": "node",
+            "mcp_args": [str(Path.home() / ".npm-global" / "lib" / "node_modules"
+                             / "forgejo-mcp" / "build" / "index.js")],
+            "mcp_env": _get_skgit_env(),
+            "openclaw_plugin_path": workspace / "skills" / "skgit" / "openclaw-plugin" / "src" / "index.ts",
+        },
+    ]
+
+
+# ── SKILL.md locator ─────────────────────────────────────────────────────────
+
+# Mapping from package name to pillar-repo directory name
+_PILLAR_DIR_MAP: dict[str, Optional[str]] = {
+    "skmemory": "skmemory",
+    "skcapstone": None,  # lives in workspace root, not pillar-repos
+    "skcomm": "skcomm",
+    "skchat": "skchat",
+    "capauth": "capauth",
+    "cloud9": "cloud9-python",
+    "sksecurity": "sksecurity",
+    "skgit": None,  # skill dir only, no pillar repo
+}
+
+
+def find_skill_md(pkg_name: str, workspace: Optional[Path] = None) -> Optional[Path]:
+    """Locate SKILL.md for a package.
+
+    Search order:
+      1. Workspace skills directory (~/clawd/skills/<name>/SKILL.md)
+      2. Pillar repos directory (~/clawd/pillar-repos/<dir>/SKILL.md)
+      3. Installed package data (importlib.resources)
+
+    Args:
+        pkg_name: Package name.
+        workspace: Workspace root (defaults to ~/clawd/).
+
+    Returns:
+        Path to SKILL.md, or None if not found.
+    """
+    if workspace is None:
+        workspace = Path.home() / "clawd"
+
+    # 1. Check skills directory (may be a symlink — that's fine)
+    skill_path = workspace / "skills" / pkg_name / "SKILL.md"
+    if skill_path.exists():
+        return skill_path.resolve()
+
+    # 2. Check pillar repos
+    pillar_dir = _PILLAR_DIR_MAP.get(pkg_name)
+    if pillar_dir:
+        pillar_path = workspace / "pillar-repos" / pillar_dir / "SKILL.md"
+        if pillar_path.exists():
+            return pillar_path
+
+    # 2b. Special case: skcapstone lives in workspace root
+    if pkg_name == "skcapstone":
+        capstone_path = workspace / "skcapstone" / "SKILL.md"
+        if capstone_path.exists():
+            return capstone_path
+
+    # 3. Check installed package data
+    try:
+        pkg_module = pkg_name.replace("-", "_")
+        ref = importlib.resources.files(pkg_module) / "SKILL.md"
+        if ref is not None:
+            with importlib.resources.as_file(ref) as p:
+                if p.exists():
+                    return p
+    except (ModuleNotFoundError, TypeError, FileNotFoundError):
+        pass
+
+    return None
+
+
+# ── Orchestrator ──────────────────────────────────────────────────────────────
+
+
+def register_all(
+    workspace: Optional[Path] = None,
+    environments: Optional[list[str]] = None,
+    dry_run: bool = False,
+) -> dict:
+    """Register all SK* packages in all detected environments.
+
+    Args:
+        workspace: Workspace root (defaults to ~/clawd/).
+        environments: Target environments (auto-detect if None).
+        dry_run: If True, only report what would be done.
+
+    Returns:
+        Dict with 'environments' and 'packages' keys.
+    """
+    if environments is None:
+        environments = detect_environments()
+
+    if workspace is None:
+        workspace = Path.home() / "clawd"
+
+    packages = _build_package_registry(workspace)
+
+    results: dict = {
+        "environments": environments,
+        "packages": {},
+    }
+
+    for pkg in packages:
+        name = pkg["name"]
+        skill_md = find_skill_md(name, workspace)
+
+        if skill_md is None and not dry_run:
+            results["packages"][name] = {
+                "skill": {"action": "error", "error": "SKILL.md not found"},
+            }
+            continue
+
+        mcp_env = pkg.get("mcp_env")
+        mcp_cmd = pkg.get("mcp_cmd")
+
+        # Skip MCP registration for skgit if no token available
+        if name == "skgit" and mcp_env is None:
+            mcp_cmd = None
+
+        # Resolve OpenClaw plugin path — skip if not on disk
+        plugin_path = pkg.get("openclaw_plugin_path")
+        if plugin_path and not Path(plugin_path).exists():
+            plugin_path = None
+
+        results["packages"][name] = register_package(
+            name=name,
+            skill_md_path=skill_md or Path("/dev/null"),
+            mcp_command=mcp_cmd,
+            mcp_args=pkg.get("mcp_args") or [],
+            mcp_env=mcp_env,
+            openclaw_plugin_path=plugin_path,
+            workspace=workspace,
+            environments=environments,
+            dry_run=dry_run,
+        )
+
+    return results

package/src/skcapstone/registry_client.py

@@ -0,0 +1,151 @@
+"""Skills Registry Client — bridge between skcapstone and the remote skills-registry.
+
+Wraps the skskills RemoteRegistry client to provide a clean interface for
+skcapstone MCP tools and CLI commands to interact with the remote
+skills-registry at skills.smilintux.org.
+
+This module is the integration point between:
+  - skills-registry/ (FastAPI server at skills.smilintux.org/api)
+  - skskills.remote.RemoteRegistry (HTTP client)
+  - skcapstone discovery.py (local skill discovery)
+
+Usage:
+    from skcapstone.registry_client import get_registry_client
+
+    client = get_registry_client()
+    if client is not None:
+        skills = client.search("syncthing")
+        client.install("syncthing-setup", agent="jarvis")
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from pathlib import Path
+from typing import Any, Optional
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_REGISTRY_URL = "https://skills.smilintux.org/api"
+
+
+class RegistryClient:
+    """Thin wrapper around skskills.remote.RemoteRegistry.
+
+    Provides a stable skcapstone-side API for interacting with the
+    remote skills-registry. Handles graceful degradation when the
+    skskills package is not installed or the registry is unreachable.
+
+    Args:
+        registry_url: Base URL for the skills registry API.
+    """
+
+    def __init__(self, registry_url: Optional[str] = None) -> None:
+        from skskills.remote import RemoteRegistry
+
+        self._url = registry_url or os.environ.get(
+            "SKSKILLS_REGISTRY_URL", DEFAULT_REGISTRY_URL
+        )
+        self._remote = RemoteRegistry(registry_url=self._url)
+
+    @property
+    def registry_url(self) -> str:
+        """The configured registry URL."""
+        return self._url
+
+    def is_available(self) -> bool:
+        """Check if the remote registry is reachable.
+
+        Returns:
+            True if the registry responds to a health/index request.
+        """
+        try:
+            self._remote.fetch_index(force=True)
+            return True
+        except Exception:
+            return False
+
+    def list_skills(self) -> list[dict[str, Any]]:
+        """List all skills available in the remote registry.
+
+        Returns:
+            List of skill entry dicts with name, version, description, etc.
+        """
+        index = self._remote.fetch_index()
+        return [s.model_dump() for s in index.skills]
+
+    def search(self, query: str) -> list[dict[str, Any]]:
+        """Search remote skills by name, description, or tags.
+
+        Args:
+            query: Case-insensitive search string.
+
+        Returns:
+            List of matching skill entry dicts.
+        """
+        results = self._remote.search(query)
+        return [s.model_dump() for s in results]
+
+    def get_skill(self, name: str, version: Optional[str] = None) -> Optional[dict[str, Any]]:
+        """Get info about a specific remote skill.
+
+        Args:
+            name: Skill name.
+            version: Specific version (latest if None).
+
+        Returns:
+            Skill entry dict or None if not found.
+        """
+        entry = self._remote.get_skill_info(name, version)
+        return entry.model_dump() if entry else None
+
+    def install(
+        self,
+        name: str,
+        version: Optional[str] = None,
+        agent: str = "global",
+        force: bool = False,
+    ) -> dict[str, Any]:
+        """Download and install a skill from the remote registry.
+
+        Args:
+            name: Skill name to install.
+            version: Specific version (latest if None).
+            agent: Agent namespace for installation.
+            force: Overwrite existing installation.
+
+        Returns:
+            Dict with installation metadata.
+
+        Raises:
+            FileNotFoundError: If the skill is not in the registry.
+            ValueError: If checksum verification fails.
+        """
+        installed = self._remote.pull(name, version=version, agent=agent, force=force)
+        return {
+            "name": installed.manifest.name,
+            "version": installed.manifest.version,
+            "agent": installed.agent,
+            "install_path": installed.install_path,
+            "status": installed.status.value,
+        }
+
+
+def get_registry_client(registry_url: Optional[str] = None) -> Optional[RegistryClient]:
+    """Get a RegistryClient instance, or None if skskills is not installed.
+
+    This is the recommended entry point. It catches ImportError from
+    skskills and returns None so callers can degrade gracefully.
+
+    Args:
+        registry_url: Override the default registry URL.
+
+    Returns:
+        RegistryClient or None if skskills is not available.
+    """
+    try:
+        return RegistryClient(registry_url=registry_url)
+    except ImportError:
+        logger.debug("skskills not installed — remote registry unavailable")
+        return None

package/src/skcapstone/response_cache.py

@@ -0,0 +1,194 @@
+"""
+Response Cache — TTL-based in-memory cache for LLM responses.
+
+Caches responses keyed by (prompt_hash, model_name) with tier-dependent TTLs:
+    - FAST tier: 1 hour
+    - CODE tier: 24 hours
+    - All other tiers: 1 hour (conservative default)
+
+Conversation messages (real-time peer exchanges with dynamic context) must be
+excluded at the call site by passing ``skip_cache=True`` to LLMBridge.generate().
+"""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+import threading
+import time
+from typing import Optional
+
+from skcapstone.blueprints.schema import ModelTier
+
+logger = logging.getLogger("skcapstone.response_cache")
+
+# TTL constants (seconds)
+_TTL_FAST: float = 3600.0       # 1 hour
+_TTL_CODE: float = 86400.0      # 24 hours
+_TTL_DEFAULT: float = 3600.0    # 1 hour fallback for other tiers
+
+
+def _ttl_for_tier(tier: ModelTier) -> float:
+    """Return the cache TTL in seconds for a given model tier.
+
+    Args:
+        tier: The model tier used for the request.
+
+    Returns:
+        TTL in seconds: 3600 for FAST, 86400 for CODE, 3600 for all others.
+    """
+    if tier == ModelTier.CODE:
+        return _TTL_CODE
+    return _TTL_FAST  # FAST and all others default to 1 hour
+
+
+def hash_prompt(system_prompt: str, user_message: str) -> str:
+    """Compute a deterministic SHA-256 hex digest for a prompt pair.
+
+    Args:
+        system_prompt: The agent's system context string.
+        user_message: The incoming user message.
+
+    Returns:
+        64-character lowercase hex string.
+    """
+    payload = f"{system_prompt}\x00{user_message}".encode("utf-8")
+    return hashlib.sha256(payload).hexdigest()
+
+
+class _CacheEntry:
+    """Internal container for a cached response and its expiry timestamp."""
+
+    __slots__ = ("response", "expires_at")
+
+    def __init__(self, response: str, ttl: float) -> None:
+        self.response: str = response
+        self.expires_at: float = time.monotonic() + ttl
+
+    def is_alive(self) -> bool:
+        """True if this entry has not yet expired."""
+        return time.monotonic() < self.expires_at
+
+
+class ResponseCache:
+    """Thread-safe in-memory LLM response cache with per-tier TTLs.
+
+    Entries are keyed by ``(prompt_hash, model_name)`` and expire automatically
+    based on the tier that produced them.  A background sweep is *not* run;
+    expired entries are evicted lazily on read and during periodic ``evict()``
+    calls.
+
+    Args:
+        max_size: Maximum number of entries to keep.  Oldest entries are
+            dropped when the limit is reached.  Defaults to 1024.
+    """
+
+    def __init__(self, max_size: int = 1024) -> None:
+        self._max_size = max_size
+        self._store: dict[tuple[str, str], _CacheEntry] = {}
+        self._lock = threading.Lock()
+        self._hits = 0
+        self._misses = 0
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def get(self, prompt_hash: str, model: str) -> Optional[str]:
+        """Retrieve a cached response, returning None on miss or expiry.
+
+        Args:
+            prompt_hash: SHA-256 hex digest from :func:`hash_prompt`.
+            model: Concrete model name (e.g. ``"llama3.2"``).
+
+        Returns:
+            Cached response string, or ``None`` if not found / expired.
+        """
+        key = (prompt_hash, model)
+        with self._lock:
+            entry = self._store.get(key)
+            if entry is None:
+                self._misses += 1
+                return None
+            if not entry.is_alive():
+                del self._store[key]
+                self._misses += 1
+                logger.debug("Cache miss (expired): model=%s", model)
+                return None
+            self._hits += 1
+            logger.debug("Cache hit: model=%s", model)
+            return entry.response
+
+    def put(self, prompt_hash: str, model: str, tier: ModelTier, response: str) -> None:
+        """Store a response in the cache.
+
+        Args:
+            prompt_hash: SHA-256 hex digest from :func:`hash_prompt`.
+            model: Concrete model name.
+            tier: Routing tier — determines the TTL.
+            response: LLM response text to cache.
+        """
+        if not response:
+            return
+        ttl = _ttl_for_tier(tier)
+        key = (prompt_hash, model)
+        with self._lock:
+            self._store[key] = _CacheEntry(response, ttl)
+            if len(self._store) > self._max_size:
+                self._evict_locked()
+        logger.debug(
+            "Cached response: model=%s tier=%s ttl=%.0fs len=%d",
+            model, tier.value, ttl, len(response),
+        )
+
+    def evict(self) -> int:
+        """Remove all expired entries and return the count removed.
+
+        Returns:
+            Number of entries evicted.
+        """
+        with self._lock:
+            return self._evict_locked()
+
+    def clear(self) -> None:
+        """Remove all entries from the cache."""
+        with self._lock:
+            self._store.clear()
+
+    @property
+    def size(self) -> int:
+        """Current number of entries (including not-yet-evicted expired ones)."""
+        with self._lock:
+            return len(self._store)
+
+    @property
+    def stats(self) -> dict[str, int]:
+        """Return cache statistics: hits, misses, current size."""
+        with self._lock:
+            return {
+                "hits": self._hits,
+                "misses": self._misses,
+                "size": len(self._store),
+            }
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _evict_locked(self) -> int:
+        """Evict expired entries.  Caller must hold ``self._lock``."""
+        dead = [k for k, v in self._store.items() if not v.is_alive()]
+        for k in dead:
+            del self._store[k]
+        if dead:
+            logger.debug("Evicted %d expired cache entries", len(dead))
+
+        # If still over limit after eviction, drop oldest by insertion order
+        overflow = len(self._store) - self._max_size
+        if overflow > 0:
+            keys_to_drop = list(self._store.keys())[:overflow]
+            for k in keys_to_drop:
+                del self._store[k]
+            logger.debug("Dropped %d entries to enforce max_size=%d", overflow, self._max_size)
+
+        return len(dead)