@smilintux/skcapstone 0.4.5 → 0.4.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smilintux/skcapstone",
-  "version": "0.4.5",
+  "version": "0.4.6",
   "description": "SKCapstone - The sovereign agent framework. CapAuth identity, Cloud 9 trust, SKMemory persistence.",
   "main": "index.js",
   "types": "index.d.ts",

package/src/skcapstone/blueprint_registry.py

@@ -355,3 +355,81 @@ class BlueprintRegistryClient:
             return True
         except BlueprintRegistryError:
             return False
+
+
+# --------------------------------------------------------------------------
+# GitHub-based fallback — reads blueprints directly from the repo
+# --------------------------------------------------------------------------
+
+_GITHUB_API_URL = "https://api.github.com/repos/smilinTux/soul-blueprints/contents/blueprints"
+_GITHUB_RAW_URL = "https://raw.githubusercontent.com/smilinTux/soul-blueprints/main/blueprints"
+
+
+def _fetch_github_blueprints(query: str = "") -> Optional[list[dict[str, Any]]]:
+    """Fetch blueprint listings from the soul-blueprints GitHub repo.
+
+    Uses the GitHub Contents API to list category directories, then
+    fetches file names from each. Lightweight header parsing is done
+    via raw file fetch for descriptions.
+
+    Args:
+        query: Optional search filter (case-insensitive).
+
+    Returns:
+        List of blueprint dicts, or None on failure.
+    """
+    try:
+        # Get top-level categories
+        req = urllib.request.Request(
+            _GITHUB_API_URL,
+            headers={"User-Agent": "skcapstone", "Accept": "application/json"},
+        )
+        with urllib.request.urlopen(req, timeout=10) as resp:
+            categories = json.loads(resp.read().decode("utf-8"))
+    except Exception as exc:
+        logger.debug("GitHub blueprint fetch failed: %s", exc)
+        return None
+
+    blueprints: list[dict[str, Any]] = []
+    q = query.lower()
+
+    for cat_entry in categories:
+        if cat_entry.get("type") != "dir":
+            continue
+        cat_name = cat_entry["name"]
+
+        # Fetch files in this category
+        try:
+            cat_req = urllib.request.Request(
+                cat_entry["url"],
+                headers={"User-Agent": "skcapstone", "Accept": "application/json"},
+            )
+            with urllib.request.urlopen(cat_req, timeout=10) as resp:
+                files = json.loads(resp.read().decode("utf-8"))
+        except Exception:
+            continue
+
+        for file_entry in files:
+            fname = file_entry.get("name", "")
+            if not fname.lower().endswith((".md", ".yaml", ".yml")):
+                continue
+            if fname.lower() in ("readme.md", "index.html"):
+                continue
+
+            stem = fname.rsplit(".", 1)[0]
+            slug = stem.lower().replace("_", "-").replace(" ", "-")
+            display = stem.replace("_", " ").replace("-", " ").title()
+
+            # Apply search filter
+            if q and q not in slug and q not in cat_name.lower() and q not in display.lower():
+                continue
+
+            blueprints.append({
+                "name": slug,
+                "display_name": display,
+                "category": cat_name,
+                "source": "github",
+                "raw_url": f"{_GITHUB_RAW_URL}/{cat_name}/{fname}",
+            })
+
+    return sorted(blueprints, key=lambda d: (d["category"], d["name"]))

package/src/skcapstone/cli/skills_cmd.py

@@ -3,9 +3,13 @@
 from __future__ import annotations
 
 import json
+import logging
 import sys
+import urllib.request
+from typing import Optional
 
 import click
+import yaml
 
 from ._common import AGENT_HOME, console
 from ..registry_client import get_registry_client
@@ -13,18 +17,65 @@ from ..registry_client import get_registry_client
 from rich.panel import Panel
 from rich.table import Table
 
+logger = logging.getLogger(__name__)
+
+# Raw catalog.yaml from the skskills GitHub repo (always fresh)
+_GITHUB_CATALOG_URL = (
+    "https://raw.githubusercontent.com/smilinTux/skskills/main/catalog.yaml"
+)
+
+
+def _fetch_github_catalog(query: str = "") -> Optional[list[dict]]:
+    """Fetch catalog.yaml from the skskills GitHub repo.
+
+    Returns:
+        List of skill entry dicts, or None on failure.
+    """
+    try:
+        req = urllib.request.Request(_GITHUB_CATALOG_URL, headers={"User-Agent": "skcapstone"})
+        with urllib.request.urlopen(req, timeout=5) as resp:
+            raw = yaml.safe_load(resp.read().decode("utf-8"))
+    except Exception as exc:
+        logger.debug("GitHub catalog fetch failed: %s", exc)
+        return None
+
+    entries = []
+    q = query.lower()
+    for item in raw.get("skills", []):
+        name = item.get("name", "")
+        desc = item.get("description", "").strip()
+        tags = item.get("tags", [])
+
+        if q and not (
+            q in name.lower()
+            or q in desc.lower()
+            or any(q in t.lower() for t in tags)
+        ):
+            continue
+
+        entries.append({
+            "name": name,
+            "description": desc,
+            "tags": tags,
+            "category": item.get("category", ""),
+            "pip": item.get("pip", ""),
+            "git": item.get("git", ""),
+        })
+
+    return entries
+
 
 def register_skills_commands(main: click.Group) -> None:
     """Register the skills command group."""
 
     @main.group()
     def skills():
-        """Remote skills registry — discover and install agent skills.
+        """Skills registry — discover and install agent skills.
 
-        Browse skills at skills.smilintux.org, search by name or tag,
-        and install skill packages into your local agent namespace.
+        Fetches the latest skill catalog from GitHub. Falls back to the
+        locally installed catalog if offline.
 
-        Set SKSKILLS_REGISTRY_URL to override the default registry.
+        Set SKSKILLS_REGISTRY_URL to override with a custom registry server.
         """
 
     @skills.command("list")
@@ -36,11 +87,12 @@ def register_skills_commands(main: click.Group) -> None:
         help="Override the skills registry URL.",
     )
     @click.option("--json", "json_out", is_flag=True, help="Output raw JSON.")
-    def skills_list(query: str, registry: str | None, json_out: bool) -> None:
-        """List skills available in the remote registry.
+    @click.option("--offline", is_flag=True, help="Use local catalog only (no network).")
+    def skills_list(query: str, registry: str | None, json_out: bool, offline: bool) -> None:
+        """List skills available in the catalog.
 
-        Without --query all skills are shown. With --query only skills
-        matching the name, description, or tags are returned.
+        Pulls the latest catalog from the skskills GitHub repo.
+        Falls back to local catalog if offline or fetch fails.
 
         Examples:
 
@@ -49,19 +101,28 @@ def register_skills_commands(main: click.Group) -> None:
             skcapstone skills list --query syncthing
 
             skcapstone skills list --query identity --json
+
+            skcapstone skills list --offline
         """
-        # Try remote registry first, fall back to local catalog
         skill_entries = None
-        source = "remote"
-
-        client = get_registry_client(registry)
-        if client is not None:
-            try:
-                skill_entries = client.search(query) if query else client.list_skills()
-            except Exception:
-                pass  # fall through to local catalog
-
-        # Fall back to local catalog (bundled with skskills)
+        source = "github"
+
+        # 1. Try custom registry server if configured
+        if registry:
+            client = get_registry_client(registry)
+            if client is not None:
+                try:
+                    skill_entries = client.search(query) if query else client.list_skills()
+                    source = "remote"
+                except Exception:
+                    pass
+
+        # 2. Try GitHub raw catalog (always fresh, no server needed)
+        if skill_entries is None and not offline:
+            skill_entries = _fetch_github_catalog(query)
+            source = "github"
+
+        # 3. Fall back to local catalog (bundled with skskills package)
         if skill_entries is None:
             try:
                 from skskills.catalog import SkillCatalog
@@ -74,7 +135,6 @@ def register_skills_commands(main: click.Group) -> None:
                 skill_entries = [
                     {
                         "name": e.name,
-                        "version": "",
                         "description": e.description,
                         "tags": e.tags,
                         "category": e.category,
@@ -83,10 +143,10 @@ def register_skills_commands(main: click.Group) -> None:
                     }
                     for e in entries
                 ]
-                source = "catalog"
+                source = "local"
             except ImportError:
                 console.print(
-                    "[bold red]skskills not installed.[/] "
+                    "[bold red]skskills not installed and GitHub unreachable.[/] "
                     "Run: pip install skskills"
                 )
                 sys.exit(1)
@@ -103,11 +163,15 @@ def register_skills_commands(main: click.Group) -> None:
             console.print(f"\n  [dim]No skills found{suffix}.[/]\n")
             return
 
+        source_labels = {
+            "github": "",
+            "remote": "  [dim](registry)[/]",
+            "local": "  [dim](local — offline)[/]",
+        }
         label = f"[bold]{len(skill_entries)}[/] skill(s)"
         if query:
             label += f" matching [cyan]'{query}'[/]"
-        if source == "catalog":
-            label += "  [dim](local catalog)[/]"
+        label += source_labels.get(source, "")
 
         table = Table(show_header=True, header_style="bold", box=None, padding=(0, 2))
         table.add_column("Name", style="cyan")
@@ -118,13 +182,13 @@ def register_skills_commands(main: click.Group) -> None:
         for s in skill_entries:
             table.add_row(
                 s.get("name", ""),
-                s.get("category", s.get("version", "")),
+                s.get("category", ""),
                 s.get("description", ""),
                 ", ".join(s.get("tags", [])),
             )
 
         console.print()
-        console.print(Panel(label, title="Skills Registry", border_style="bright_blue"))
+        console.print(Panel(label, title="Skills Catalog", border_style="bright_blue"))
         console.print(table)
         console.print()
 

package/src/skcapstone/cli/soul.py

@@ -517,22 +517,36 @@ def register_soul_commands(main: click.Group) -> None:
     @soul_registry.command("list")
     @click.option("--url", default=None, help="Registry API base URL.")
     def registry_list(url):
-        """List all blueprints in the remote registry."""
-        from ..blueprint_registry import BlueprintRegistryClient, BlueprintRegistryError
+        """List all blueprints in the remote registry.
 
-        kwargs = {}
+        Pulls from the soul-blueprints GitHub repo. Falls back to
+        the souls.skworld.io API if --url is set.
+        """
+        from ..blueprint_registry import (
+            BlueprintRegistryClient,
+            BlueprintRegistryError,
+            _fetch_github_blueprints,
+        )
+
+        blueprints = None
+        source = "github"
+
+        # If custom URL, try the API server first
         if url:
-            kwargs["base_url"] = url
-        client = BlueprintRegistryClient(**kwargs)
+            try:
+                client = BlueprintRegistryClient(base_url=url)
+                blueprints = client.list_blueprints()
+                source = "registry"
+            except BlueprintRegistryError:
+                pass
 
-        try:
-            blueprints = client.list_blueprints()
-        except BlueprintRegistryError as e:
-            console.print(f"\n  [red]Registry error:[/] {e}\n")
-            sys.exit(1)
+        # Default: pull from GitHub repo
+        if blueprints is None:
+            blueprints = _fetch_github_blueprints()
+            source = "github"
 
         if not blueprints:
-            console.print("\n  [dim]No blueprints found in the registry.[/]\n")
+            console.print("\n  [dim]No blueprints found.[/]\n")
             return
 
         table = Table(show_header=True, header_style="bold", box=None, padding=(0, 2))
@@ -547,27 +561,38 @@ def register_soul_commands(main: click.Group) -> None:
                 bp.get("category", ""),
             )
 
+        source_label = "" if source == "github" else "  [dim](registry)[/]"
         console.print()
         console.print(table)
-        console.print(f"\n  [dim]{len(blueprints)} blueprint(s) in registry[/]\n")
+        console.print(f"\n  [dim]{len(blueprints)} blueprint(s){source_label}[/]\n")
 
     @soul_registry.command("search")
     @click.argument("query")
     @click.option("--url", default=None, help="Registry API base URL.")
     def registry_search(query, url):
-        """Search the remote registry for blueprints."""
-        from ..blueprint_registry import BlueprintRegistryClient, BlueprintRegistryError
+        """Search the remote registry for blueprints.
 
-        kwargs = {}
+        Searches the soul-blueprints GitHub repo by name and category.
+        """
+        from ..blueprint_registry import (
+            BlueprintRegistryClient,
+            BlueprintRegistryError,
+            _fetch_github_blueprints,
+        )
+
+        results = None
+
+        # If custom URL, try the API server first
         if url:
-            kwargs["base_url"] = url
-        client = BlueprintRegistryClient(**kwargs)
+            try:
+                client = BlueprintRegistryClient(base_url=url)
+                results = client.search_blueprints(query)
+            except BlueprintRegistryError:
+                pass
 
-        try:
-            results = client.search_blueprints(query)
-        except BlueprintRegistryError as e:
-            console.print(f"\n  [red]Registry error:[/] {e}\n")
-            sys.exit(1)
+        # Default: search GitHub repo
+        if results is None:
+            results = _fetch_github_blueprints(query)
 
         if not results:
             console.print(f"\n  [dim]No blueprints matching '{query}'.[/]\n")
@@ -577,14 +602,12 @@ def register_soul_commands(main: click.Group) -> None:
         table.add_column("Name", style="cyan", no_wrap=True)
         table.add_column("Display Name", style="bold")
         table.add_column("Category", style="yellow")
-        table.add_column("Vibe", style="dim")
 
         for bp in results:
             table.add_row(
                 bp.get("name", "?"),
                 bp.get("display_name", ""),
                 bp.get("category", ""),
-                (bp.get("vibe", "") or "")[:60],
             )
 
         console.print()

package/src/skcapstone/daemon.py

@@ -1145,16 +1145,35 @@ class DaemonService:
             logger.debug("Auto-journal write failed: %s", exc)
 
         try:
-            from .memory_engine import store as mem_store
-            mem_store(
-                self.config.home,
-                f"Received message from {sender}: {preview}",
-                tags=["skcomm-received"],
-                source="daemon",
-            )
-            logger.debug("Memory stored for incoming message from %s", sender)
+            self._store_skcomm_receipt(sender, preview)
+            logger.debug("SKComm receipt stored for incoming message from %s", sender)
         except Exception as exc:
-            logger.debug("Auto-journal memory store failed: %s", exc)
+            logger.debug("SKComm receipt store failed: %s", exc)
+
+    def _store_skcomm_receipt(self, sender: str, preview: str) -> None:
+        """Write a skcomm receipt to the skcomm/received/ directory.
+
+        These are transport bookkeeping, NOT persistent memories, so they
+        go to ``~/.skcapstone/agents/{agent}/skcomm/received/`` instead of
+        polluting the memory/ tree that skmemory indexes.
+        """
+        import json
+        import uuid
+        from datetime import datetime, timezone
+
+        agent_name = os.environ.get("SKCAPSTONE_AGENT", "lumina")
+        recv_dir = self.config.home / "agents" / agent_name / "skcomm" / "received"
+        recv_dir.mkdir(parents=True, exist_ok=True)
+
+        receipt_id = uuid.uuid4().hex[:12]
+        receipt = {
+            "id": receipt_id,
+            "sender": sender,
+            "preview": preview,
+            "received_at": datetime.now(timezone.utc).isoformat(),
+        }
+        path = recv_dir / f"{receipt_id}.json"
+        path.write_text(json.dumps(receipt, indent=2), encoding="utf-8")
 
     def _healing_loop(self) -> None:
         """Periodically run self-healing diagnostics (every 5 min)."""

package/src/skcapstone/mcp_tools/notification_tools.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import asyncio
 import datetime
+import os
 
 from mcp.types import TextContent, Tool
 
@@ -70,19 +71,19 @@ async def _handle_send_notification(args: dict) -> list[TextContent]:
 
     timestamp = datetime.datetime.now(datetime.timezone.utc).isoformat()
 
-    # Persist a memory entry so the agent recalls past notifications.
+    # Log notification to skcomm/notifications/ (not memory/).
     try:
-        from ..memory_engine import store as memory_store
-
-        memory_store(
-            home=_home(),
-            content=f"Notification sent — title: {title!r}, body: {body!r}, urgency: {urgency}",
-            tags=["notification"],
-            source="mcp:send_notification",
-            importance=0.4,
-        )
+        import json as _j
+        import uuid
+        home = _home()
+        agent_name = os.environ.get("SKCAPSTONE_AGENT", "lumina")
+        notif_dir = home / "agents" / agent_name / "skcomm" / "notifications"
+        notif_dir.mkdir(parents=True, exist_ok=True)
+        entry = {"id": uuid.uuid4().hex[:12], "type": "notification-sent",
+                 "title": title, "body": body, "urgency": urgency, "timestamp": timestamp}
+        (notif_dir / f"{entry['id']}.json").write_text(_j.dumps(entry, indent=2))
     except Exception:
-        pass  # memory failure must not block the notification response
+        pass  # notification log failure must not block the response
 
     return _json_response({"sent": True, "timestamp": timestamp})
 

package/src/skcapstone/notifications.py

@@ -19,6 +19,7 @@ from __future__ import annotations
 
 import datetime
 import logging
+import os
 import platform
 import subprocess
 import threading
@@ -43,53 +44,65 @@ _TERMINAL_CMDS: list[list[str]] = [
 
 
 def _store_notification_memory(title: str, body: str, urgency: str) -> None:
-    """Persist a short-term memory entry for every dispatched notification."""
+    """Log a notification dispatch to the skcomm/notifications/ directory.
+
+    These are transport bookkeeping, not persistent memories, so they
+    go to ``~/.skcapstone/agents/{agent}/skcomm/notifications/`` instead
+    of polluting the memory/ tree that skmemory indexes.
+    """
     try:
+        import json as _json
+        import uuid
         from . import AGENT_HOME
-        from .memory_engine import store as mem_store
-        from .models import MemoryLayer
 
         home = Path(AGENT_HOME).expanduser()
         if not home.exists():
             return
 
+        agent_name = os.environ.get("SKCAPSTONE_AGENT", "lumina")
+        notif_dir = home / "agents" / agent_name / "skcomm" / "notifications"
+        notif_dir.mkdir(parents=True, exist_ok=True)
+
         ts = datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
-        content = f"[{ts}] Notification sent — title={title!r} body={body!r} urgency={urgency}"
-        mem_store(
-            home=home,
-            content=content,
-            tags=["notification"],
-            source="notifications",
-            importance=0.3,
-            layer=MemoryLayer.SHORT_TERM,
-        )
+        entry = {
+            "id": uuid.uuid4().hex[:12],
+            "type": "notification-sent",
+            "title": title,
+            "body": body,
+            "urgency": urgency,
+            "timestamp": ts,
+        }
+        path = notif_dir / f"{entry['id']}.json"
+        path.write_text(_json.dumps(entry, indent=2), encoding="utf-8")
     except Exception as exc:
-        logger.debug("Failed to store notification memory: %s", exc)
+        logger.debug("Failed to store notification log: %s", exc)
 
 
 def _store_click_event(action: str, detail: str) -> None:
-    """Persist a short-term memory entry for a notification click action."""
+    """Log a notification click event to the skcomm/notifications/ directory."""
     try:
+        import json as _json
+        import uuid
         from . import AGENT_HOME
-        from .memory_engine import store as mem_store
-        from .models import MemoryLayer
 
         home = Path(AGENT_HOME).expanduser()
         if not home.exists():
             return
 
+        agent_name = os.environ.get("SKCAPSTONE_AGENT", "lumina")
+        notif_dir = home / "agents" / agent_name / "skcomm" / "notifications"
+        notif_dir.mkdir(parents=True, exist_ok=True)
+
         ts = datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
-        content = (
-            f"[{ts}] Notification click — action={action!r} detail={detail!r}"
-        )
-        mem_store(
-            home=home,
-            content=content,
-            tags=["notification", "click-event"],
-            source="notifications",
-            importance=0.3,
-            layer=MemoryLayer.SHORT_TERM,
-        )
+        entry = {
+            "id": uuid.uuid4().hex[:12],
+            "type": "click-event",
+            "action": action,
+            "detail": detail,
+            "timestamp": ts,
+        }
+        path = notif_dir / f"{entry['id']}.json"
+        path.write_text(_json.dumps(entry, indent=2), encoding="utf-8")
         logger.debug("Stored notification click event: %s → %s", action, detail)
     except Exception as exc:
         logger.debug("Failed to store click event in memory: %s", exc)

package/src/skcapstone/soul.py

@@ -838,6 +838,25 @@ class SoulManager:
                         "source": "repo",
                         "description": desc[:80] if desc else "",
                     }
+        else:
+            # 2b) Local repo not cloned — fall back to GitHub API
+            try:
+                from .blueprint_registry import _fetch_github_blueprints
+
+                github_results = _fetch_github_blueprints()
+                if github_results:
+                    for bp in github_results:
+                        slug = bp["name"]
+                        if slug not in seen:
+                            seen[slug] = {
+                                "name": slug,
+                                "display_name": bp.get("display_name", slug),
+                                "category": bp.get("category", ""),
+                                "source": "github",
+                                "description": "",
+                            }
+            except Exception:
+                pass  # offline — show only installed souls
 
         # Sort by category, then name
         return sorted(seen.values(), key=lambda d: (d["category"], d["name"]))