code-muse 0.0.1__py3-none-any.whl

code_muse/plugins/agent_skills/prompt_builder.py

@@ -0,0 +1,66 @@
+"""Build available_skills XML for system prompt injection."""
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .metadata import SkillMetadata
+
+
+def build_available_skills_xml(skills: list[SkillMetadata]) -> str:
+    """Build Claude-optimized XML listing available skills.
+
+    Args:
+        skills: List of SkillMetadata objects to include in the XML.
+
+    Returns:
+        XML string listing available skills in the format:
+        <available_skills>
+          <skill>
+            <name>skill-name</name>
+            <description>What the skill does...</description>
+          </skill>
+          ...
+        </available_skills>
+
+    To use a skill, call activate_skill(skill_name) to load full instructions.
+    """
+    if not skills:
+        return "<available_skills></available_skills>"
+
+    xml_parts = ["<available_skills>"]
+
+    for skill in skills:
+        xml_parts.append("  <skill>")
+        xml_parts.append(f"    <name>{skill.name}</name>")
+        if skill.description:
+            # Escape any XML special characters in the description
+            escaped_desc = (
+                skill.description.replace("&", "&amp;")
+                .replace("<", "&lt;")
+                .replace(">", "&gt;")
+                .replace('"', "&quot;")
+                .replace("'", "&#39;")
+            )
+            xml_parts.append(f"    <description>{escaped_desc}</description>")
+        if skill.source:
+            xml_parts.append(f"    <source>{skill.source}</source>")
+        if skill.trust:
+            xml_parts.append(f"    <trust>{skill.trust}</trust>")
+        if skill.skill_md_hash:
+            xml_parts.append(f"    <hash>{skill.skill_md_hash[:12]}</hash>")
+        xml_parts.append("  </skill>")
+
+    xml_parts.append("</available_skills>")
+
+    return "\n".join(xml_parts)
+
+
+def build_skills_guidance() -> str:
+    """Return guidance text for how to use skills."""
+    return """
+# Agent Skills
+
+When `<available_skills>` appears in context, match user tasks to skill descriptions.
+Call `activate_skill(skill_name)` to load full instructions before starting the task.
+Use `list_or_search_skills(query)` to search for relevant skills.
+"""

code_muse/plugins/agent_skills/register_callbacks.py

@@ -0,0 +1,298 @@
+"""Agent Skills plugin - registers callbacks for skill integration.
+
+This plugin:
+1. Injects available skills into system prompts
+2. Registers skill-related tools
+3. Provides /skills slash command (and alias /skill)
+"""
+
+import logging
+from pathlib import Path
+from typing import Any
+
+from code_muse.callbacks import register_callback
+
+logger = logging.getLogger(__name__)
+
+# Session-level deactivated skills (not persisted to config)
+_deactivated_skills: set[str] = set()
+
+
+def _get_skills_prompt_section() -> str | None:
+    """Build the skills section to inject into system prompts.
+
+    Returns None if skills are disabled or no skills found.
+    """
+    from .config import get_disabled_skills, get_skill_directories, get_skills_enabled
+    from .discovery import discover_skills
+    from .metadata import SkillMetadata, parse_skill_metadata
+    from .prompt_builder import build_available_skills_xml, build_skills_guidance
+
+    # 1. Check if enabled
+    if not get_skills_enabled():
+        logger.debug("Skills integration is disabled, skipping prompt injection")
+        return None
+
+    # 2. Discover skills
+    skill_dirs = [Path(d) for d in get_skill_directories()]
+    discovered = discover_skills(skill_dirs)
+
+    if not discovered:
+        logger.debug("No skills discovered, skipping prompt injection")
+        return None
+
+    # 3. Parse metadata for each and filter out disabled/deactivated skills
+    disabled_skills = get_disabled_skills()
+    skills_metadata: list[SkillMetadata] = []
+
+    for skill_info in discovered:
+        # Skip disabled skills
+        if skill_info.name in disabled_skills:
+            logger.debug(f"Skipping disabled skill: {skill_info.name}")
+            continue
+
+        # Skip session-level deactivated skills
+        if skill_info.name in _deactivated_skills:
+            logger.debug(f"Skipping deactivated skill: {skill_info.name}")
+            continue
+
+        # Only include skills with valid SKILL.md
+        if not skill_info.has_skill_md:
+            logger.debug(f"Skipping skill without SKILL.md: {skill_info.name}")
+            continue
+
+        # Parse metadata
+        metadata = parse_skill_metadata(skill_info.path)
+        if metadata:
+            skills_metadata.append(metadata)
+        else:
+            logger.debug(f"Skipping skill with invalid metadata: {skill_info.name}")
+
+    # 4. Build XML + guidance
+    if not skills_metadata:
+        logger.debug("No valid skills with metadata found, skipping prompt injection")
+        return None
+
+    xml_section = build_available_skills_xml(skills_metadata)
+    guidance = build_skills_guidance()
+
+    # 5. Return combined string
+    combined = f"{xml_section}\n\n{guidance}"
+    logger.debug(f"Injecting skills section with {len(skills_metadata)} skills")
+    return combined
+
+
+def _inject_skills_into_prompt(
+    model_name: str, default_system_prompt: str, user_prompt: str
+) -> dict[str, Any | None]:
+    """Callback to inject skills into system prompt.
+
+    This is registered with the 'get_model_system_prompt' callback phase.
+    """
+    skills_section = _get_skills_prompt_section()
+
+    if not skills_section:
+        return None  # No skills, don't modify prompt
+
+    # Append skills section to system prompt
+    enhanced_prompt = f"{default_system_prompt}\n\n{skills_section}"
+
+    return {
+        "instructions": enhanced_prompt,
+        "user_prompt": user_prompt,
+        "handled": False,  # Let other handlers also process
+    }
+
+
+def _register_skills_tools() -> list[dict[str, Any]]:
+    """Callback to register skills tools.
+
+    This is registered with the 'register_tools' callback phase.
+    Returns tool definitions for the tool registry.
+    """
+    from code_muse.tools.skills_tools import (
+        register_activate_skill,
+        register_check_skill_background,
+        register_deactivate_skill,
+        register_list_or_search_skills,
+        register_run_skill_background,
+    )
+
+    return [
+        {"name": "activate_skill", "register_func": register_activate_skill},
+        {
+            "name": "list_or_search_skills",
+            "register_func": register_list_or_search_skills,
+        },
+        {"name": "deactivate_skill", "register_func": register_deactivate_skill},
+        {
+            "name": "run_skill_background",
+            "register_func": register_run_skill_background,
+        },
+        {
+            "name": "check_skill_background",
+            "register_func": register_check_skill_background,
+        },
+    ]
+
+
+# ---------------------------------------------------------------------------
+# Slash command: /skills (and alias /skill)
+# ---------------------------------------------------------------------------
+
+_COMMAND_NAME = "skills"
+_ALIASES = ("skill",)
+
+
+def _skills_command_help() -> list[tuple[str, str]]:
+    """Advertise /skills in the /help menu."""
+    return [
+        ("skills", "Manage agent skills – browse, enable, disable, install"),
+        ("skill", "Alias for /skills"),
+    ]
+
+
+def _handle_skills_command(command: str, name: str) -> Any | None:
+    """Handle /skills and /skill slash commands.
+
+    Sub-commands:
+        /skills          – Launch interactive TUI menu
+        /skills list     – Quick text list of all skills
+        /skills install  – Browse & install from remote catalog
+        /skills enable   – Enable skills integration globally
+        /skills disable  – Disable skills integration globally
+        /skills toggle   – Toggle skills integration globally
+        /skills refresh  – Force skill re-discovery and refresh local cache
+        /skills help     – Show skills command help
+    """
+    if name not in (_COMMAND_NAME, *_ALIASES):
+        return None
+
+    from code_muse.messaging import emit_error, emit_info, emit_success, emit_warning
+    from code_muse.plugins.agent_skills.config import (
+        get_disabled_skills,
+        get_skills_enabled,
+        set_skills_enabled,
+    )
+    from code_muse.plugins.agent_skills.discovery import (
+        discover_skills,
+        refresh_skill_cache,
+    )
+    from code_muse.plugins.agent_skills.metadata import parse_skill_metadata
+    from code_muse.plugins.agent_skills.skills_menu import show_skills_menu
+
+    tokens = command.split()
+
+    if len(tokens) > 1:
+        subcommand = tokens[1].lower()
+
+        if subcommand == "list":
+            disabled_skills = get_disabled_skills()
+            skills = discover_skills()
+            enabled = get_skills_enabled()
+
+            if not skills:
+                emit_info("No skills found.")
+                emit_info("Create skills in:")
+                emit_info("  - ~/.muse/skills/")
+                emit_info("  - ./skills/")
+                return True
+
+            emit_info(
+                f"\U0001f6e0\ufe0f Skills (integration: {'enabled' if enabled else 'disabled'})"
+            )
+            emit_info(f"Found {len(skills)} skill(s):\n")
+
+            for skill in skills:
+                metadata = parse_skill_metadata(skill.path)
+                if metadata:
+                    status = (
+                        "\U0001f534 disabled"
+                        if metadata.name in disabled_skills
+                        else "\U0001f7e2 enabled"
+                    )
+                    version_str = f" v{metadata.version}" if metadata.version else ""
+                    author_str = f" by {metadata.author}" if metadata.author else ""
+                    emit_info(f"  {status} {metadata.name}{version_str}{author_str}")
+                    emit_info(f"      {metadata.description}")
+                    if metadata.tags:
+                        emit_info(f"      tags: {', '.join(metadata.tags)}")
+                else:
+                    status = (
+                        "\U0001f534 disabled"
+                        if skill.name in disabled_skills
+                        else "\U0001f7e2 enabled"
+                    )
+                    emit_info(f"  {status} {skill.name}")
+                    emit_info("      (no SKILL.md metadata found)")
+                emit_info("")
+            return True
+
+        elif subcommand == "install":
+            from code_muse.plugins.agent_skills.skills_install_menu import (
+                run_skills_install_menu,
+            )
+
+            run_skills_install_menu()
+            return True
+
+        elif subcommand == "enable":
+            set_skills_enabled(True)
+            emit_success("\u2705 Skills integration enabled globally")
+            return True
+
+        elif subcommand == "disable":
+            set_skills_enabled(False)
+            emit_warning("\U0001f534 Skills integration disabled globally")
+            return True
+
+        elif subcommand == "toggle":
+            new_state = not get_skills_enabled()
+            set_skills_enabled(new_state)
+            if new_state:
+                emit_success("✅ Skills integration enabled globally")
+            else:
+                emit_warning("🔴 Skills integration disabled globally")
+            return True
+
+        elif subcommand == "refresh":
+            refreshed = refresh_skill_cache()
+            valid_skills = [skill for skill in refreshed if skill.has_skill_md]
+            emit_success(
+                f"🔄 Refreshed skills cache: {len(refreshed)} discovered "
+                f"({len(valid_skills)} with SKILL.md)"
+            )
+            return True
+
+        elif subcommand == "help":
+            emit_info("Available /skills subcommands:")
+            emit_info("  /skills list     - List all installed skills")
+            emit_info("  /skills install  - Browse & install from catalog")
+            emit_info("  /skills enable   - Enable skills integration globally")
+            emit_info("  /skills disable  - Disable skills integration globally")
+            emit_info("  /skills toggle   - Toggle skills integration globally")
+            emit_info("  /skills refresh  - Refresh skill cache")
+            emit_info("  /skills          - Open interactive skills menu")
+            return True
+
+        else:
+            emit_error(f"Unknown subcommand: {subcommand}")
+            emit_info(
+                "Usage: /skills [list|install|enable|disable|toggle|refresh|help]"
+            )
+            return True
+
+    # No subcommand – launch TUI menu
+    show_skills_menu()
+    return True
+
+
+# ---------------------------------------------------------------------------
+# Register all callbacks
+# ---------------------------------------------------------------------------
+register_callback("get_model_system_prompt", _inject_skills_into_prompt)
+register_callback("register_tools", _register_skills_tools)
+register_callback("custom_command_help", _skills_command_help)
+register_callback("custom_command", _handle_skills_command)
+
+logger.info("Agent Skills plugin loaded")

code_muse/plugins/agent_skills/remote_catalog.py

@@ -0,0 +1,320 @@
+"""Remote skills catalog client.
+
+Fetches the remote skills catalog JSON and exposes a cached, parsed view.
+
+Design goals:
+- Never crash the app (defensive parsing + broad error handling).
+- Local caching with TTL for fast startup and offline use.
+- Synchronous networking only (httpx.Client).
+
+Schema source:
+https://www.llmspec.dev/skills/skills.json
+"""
+
+import json
+import logging
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+from urllib.parse import urljoin
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+SKILLS_JSON_URL = "https://www.llmspec.dev/skills/skills.json"
+
+_CACHE_DIR = Path.home() / ".muse" / "cache"
+_CACHE_PATH = _CACHE_DIR / "skills_catalog.json"
+_CACHE_TTL_SECONDS = 30 * 60
+
+
+@dataclass(frozen=True, slots=True)
+class RemoteSkillEntry:
+    """Flattened remote skill entry."""
+
+    name: str
+    description: str
+    group: str
+    download_url: str
+    zip_size_bytes: int
+    file_count: int
+    has_scripts: bool
+    has_references: bool
+    has_license: bool
+
+
+@dataclass(frozen=True, slots=True)
+class RemoteCatalogData:
+    """Parsed remote catalog.
+
+    Attributes:
+        version: Catalog version string.
+        base_url: Base URL used to build absolute download_url values.
+        total_skills: Total number of skills in the remote catalog.
+        groups: Raw group objects from the JSON (kept as dicts for flexibility).
+        entries: Flattened list of all skills across all groups.
+    """
+
+    version: str
+    base_url: str
+    total_skills: int
+    groups: list[dict[str, Any]]
+    entries: list[RemoteSkillEntry]
+
+
+def _safe_int(value: Any, default: int = 0) -> int:
+    """Convert value to int, returning default on failure."""
+
+    try:
+        if value is None:
+            return default
+        return int(value)
+    except Exception:
+        return default
+
+
+def _safe_bool(value: Any, default: bool = False) -> bool:
+    """Convert value to bool, returning default on failure."""
+
+    if value is None:
+        return default
+    return bool(value)
+
+
+def _cache_is_fresh(cache_path: Path, ttl_seconds: int) -> bool:
+    """Check whether the on-disk catalog cache is within TTL."""
+
+    try:
+        if not cache_path.exists():
+            return False
+        age_seconds = time.time() - cache_path.stat().st_mtime
+        return age_seconds <= ttl_seconds
+    except Exception as e:
+        logger.debug(f"Failed to check cache age for {cache_path}: {e}")
+        return False
+
+
+def _read_cache(cache_path: Path) -> dict[str, Any | None]:
+    """Read and deserialize the cached catalog JSON from disk."""
+
+    try:
+        if not cache_path.exists():
+            return None
+        raw = cache_path.read_text(encoding="utf-8")
+        data = json.loads(raw)
+        if not isinstance(data, dict):
+            logger.warning(f"Cache JSON is not an object: {cache_path}")
+            return None
+        return data
+    except Exception as e:
+        logger.warning(f"Failed to read cache {cache_path}: {e}")
+        return None
+
+
+def _write_cache(cache_path: Path, data: dict[str, Any]) -> bool:
+    """Serialize and write catalog JSON to the disk cache."""
+
+    try:
+        cache_path.parent.mkdir(parents=True, exist_ok=True)
+        # Stable formatting so diffs are readable when debugging.
+        cache_path.write_text(
+            json.dumps(data, indent=2, sort_keys=True) + "\n", encoding="utf-8"
+        )
+        return True
+    except Exception as e:
+        logger.warning(f"Failed to write cache {cache_path}: {e}")
+        return False
+
+
+def _fetch_remote_json(url: str) -> dict[str, Any | None]:
+    """Fetch the skills catalog JSON from the remote URL."""
+
+    headers = {
+        "Accept": "application/json",
+        "User-Agent": "muse/remote-catalog",
+    }
+
+    try:
+        with httpx.Client(timeout=15, headers=headers) as client:
+            response = client.get(url)
+            response.raise_for_status()
+            data = response.json()
+
+        if not isinstance(data, dict):
+            logger.error(f"Remote catalog JSON was not an object. Got: {type(data)}")
+            return None
+
+        return data
+
+    except httpx.HTTPStatusError as e:
+        logger.warning(
+            "Remote catalog request returned bad status: "
+            f"{e.response.status_code} {e.response.reason_phrase}"
+        )
+        return None
+    except (httpx.ConnectError, httpx.TimeoutException, httpx.NetworkError) as e:
+        logger.warning(f"Remote catalog network failure: {e}")
+        return None
+    except json.JSONDecodeError as e:
+        logger.warning(f"Remote catalog returned invalid JSON: {e}")
+        return None
+    except Exception as e:
+        logger.exception(f"Unexpected error fetching remote catalog: {e}")
+        return None
+
+
+def _parse_catalog(raw: dict[str, Any]) -> RemoteCatalogData | None:
+    """Parse raw JSON dicts into a list of RemoteSkillEntry objects."""
+
+    try:
+        version = str(raw.get("version") or "")
+        base_url = str(raw.get("base_url") or "")
+        total_skills = _safe_int(raw.get("total_skills"), default=0)
+
+        raw_groups = raw.get("groups")
+        if not isinstance(raw_groups, list):
+            logger.warning("Remote catalog 'groups' missing or not a list")
+            raw_groups = []
+
+        groups: list[dict[str, Any]] = []
+        entries: list[RemoteSkillEntry] = []
+
+        # Ensure urljoin behaves (needs trailing slash on base).
+        base_for_join = base_url.rstrip("/") + "/" if base_url else ""
+
+        for group_obj in raw_groups:
+            if not isinstance(group_obj, dict):
+                continue
+            groups.append(group_obj)
+
+            group_slug = str(group_obj.get("slug") or group_obj.get("name") or "")
+            skills = group_obj.get("skills")
+            if not isinstance(skills, list):
+                continue
+
+            for skill in skills:
+                if not isinstance(skill, dict):
+                    continue
+
+                name = str(skill.get("name") or "").strip()
+                if not name:
+                    # If name is missing, it can't be indexed/activated anyway.
+                    continue
+
+                description = str(skill.get("description") or "")
+                group = str(skill.get("group") or group_slug or "")
+
+                download_path = str(skill.get("download_url") or "")
+                download_url = (
+                    urljoin(base_for_join, download_path)
+                    if base_for_join
+                    else download_path
+                )
+
+                contents = skill.get("contents")
+                if not isinstance(contents, dict):
+                    contents = {}
+
+                entries.append(
+                    RemoteSkillEntry(
+                        name=name,
+                        description=description,
+                        group=group,
+                        download_url=download_url,
+                        zip_size_bytes=_safe_int(
+                            skill.get("zip_size_bytes"), default=0
+                        ),
+                        file_count=_safe_int(skill.get("file_count"), default=0),
+                        has_scripts=_safe_bool(
+                            contents.get("has_scripts"), default=False
+                        ),
+                        has_references=_safe_bool(
+                            contents.get("has_references"), default=False
+                        ),
+                        has_license=_safe_bool(
+                            contents.get("has_license"), default=False
+                        ),
+                    )
+                )
+
+        if not version:
+            logger.debug("Remote catalog 'version' is missing/empty")
+        if not base_url:
+            logger.debug("Remote catalog 'base_url' is missing/empty")
+
+        return RemoteCatalogData(
+            version=version,
+            base_url=base_url,
+            total_skills=total_skills,
+            groups=groups,
+            entries=entries,
+        )
+
+    except Exception as e:
+        logger.exception(f"Failed to parse remote catalog JSON: {e}")
+        return None
+
+
+def fetch_remote_catalog(force_refresh: bool = False) -> RemoteCatalogData | None:
+    """Fetch the remote skills catalog with caching and offline fallback.
+
+    Cache behavior:
+    - Cache file: ~/.muse/cache/skills_catalog.json
+    - TTL: 30 minutes (based on file mtime)
+    - Offline fallback: if network fetch fails, use cache if present (even if expired)
+
+    Args:
+        force_refresh: If True, always attempt a network fetch.
+
+    Returns:
+        Parsed RemoteCatalogData on success, otherwise None.
+    """
+
+    cache_fresh = _cache_is_fresh(_CACHE_PATH, _CACHE_TTL_SECONDS)
+
+    # Use fresh cache unless forced.
+    if not force_refresh and cache_fresh:
+        logger.info(f"Using fresh remote catalog cache: {_CACHE_PATH}")
+        cached = _read_cache(_CACHE_PATH)
+        if cached is None:
+            logger.warning("Fresh cache exists but could not be read; refetching")
+        else:
+            parsed = _parse_catalog(cached)
+            if parsed is not None:
+                return parsed
+            logger.warning("Fresh cache exists but could not be parsed; refetching")
+
+    if force_refresh:
+        logger.info("Force refresh enabled; fetching remote skills catalog")
+    elif _CACHE_PATH.exists():
+        logger.info(
+            "Cache is missing or stale; fetching remote skills catalog "
+            f"(cache_path={_CACHE_PATH}, fresh={cache_fresh})"
+        )
+    else:
+        logger.info("No cache present; fetching remote skills catalog")
+
+    remote_raw = _fetch_remote_json(SKILLS_JSON_URL)
+    if remote_raw is not None:
+        logger.info("Fetched remote skills catalog successfully")
+        _write_cache(_CACHE_PATH, remote_raw)
+        parsed = _parse_catalog(remote_raw)
+        if parsed is not None:
+            return parsed
+        logger.warning("Remote catalog fetched but failed to parse")
+
+    # Offline fallback: use cache even if expired.
+    if _CACHE_PATH.exists():
+        logger.warning(
+            "Remote fetch failed; falling back to cached skills catalog "
+            f"(even if expired): {_CACHE_PATH}"
+        )
+        cached = _read_cache(_CACHE_PATH)
+        if cached is None:
+            return None
+        return _parse_catalog(cached)
+
+    logger.error("Remote fetch failed and no cache is available")
+    return None