@smilintux/skcapstone 0.10.0 → 0.12.5

package/src/skcapstone/launchd.py

@@ -54,20 +54,20 @@ _SERVICE_DEFS: list[dict] = [
         "logs": "{logs}/memory-compress",
     },
     {
-        "suffix": "skcomm-heartbeat",
-        "args": ["{skenv}/skcomm", "heartbeat"],
+        "suffix": "skcomms-heartbeat",
+        "args": ["{skenv}/skcomms", "heartbeat"],
         "env": {},
         "interval": 60,
         "nice": 19,
-        "logs": "{logs}/skcomm-heartbeat",
+        "logs": "{logs}/skcomms-heartbeat",
     },
     {
-        "suffix": "skcomm-queue-drain",
-        "args": ["{skenv}/skcomm", "queue", "drain"],
+        "suffix": "skcomms-queue-drain",
+        "args": ["{skenv}/skcomms", "queue", "drain"],
         "env": {},
         "interval": 120,
         "nice": 19,
-        "logs": "{logs}/skcomm-queue-drain",
+        "logs": "{logs}/skcomms-queue-drain",
     },
 ]
 
@@ -84,23 +84,23 @@ _OPTIONAL_DEFS: list[dict] = [
         "requires_bin": "skchat",
     },
     {
-        "suffix": "skcomm-api",
-        "args": ["{skenv}/python3", "-m", "uvicorn", "skcomm.api:app",
+        "suffix": "skcomms-api",
+        "args": ["{skenv}/python3", "-m", "uvicorn", "skcomms.api:app",
                  "--host", "127.0.0.1", "--port", "9384", "--log-level", "info"],
         "env": {"SKCHAT_IDENTITY": "capauth:{agent}@skworld.io"},
         "keep_alive": True,
         "throttle": 5,
-        "logs": "{skcomm}/launchd",
-        "requires_bin": "skcomm",
+        "logs": "{skcomms}/launchd",
+        "requires_bin": "skcomms",
     },
     {
-        "suffix": "skcomm-daemon",
-        "args": ["{skenv}/skcomm", "daemon", "--all-agents", "--interval", "5"],
+        "suffix": "skcomms-daemon",
+        "args": ["{skenv}/skcomms", "daemon", "--all-agents", "--interval", "5"],
         "env": {},
         "keep_alive": True,
         "throttle": 5,
-        "logs": "{skcomm}/daemon",
-        "requires_bin": "skcomm",
+        "logs": "{skcomms}/daemon",
+        "requires_bin": "skcomms",
     },
 ]
 
@@ -127,7 +127,7 @@ def _expand(s: str, agent: str) -> str:
         .replace("{home}", home)
         .replace("{logs}", f"{home}/.skcapstone/logs")
         .replace("{skchat}", f"{home}/.skchat")
-        .replace("{skcomm}", f"{home}/.skcomm")
+        .replace("{skcomms}", f"{home}/.skcomms")
     )
 
 
@@ -281,7 +281,7 @@ def install_service(
     log_dirs = [
         Path.home() / ".skcapstone" / "logs",
         Path.home() / ".skchat",
-        Path.home() / ".skcomm",
+        Path.home() / ".skcomms",
     ]
     for d in log_dirs:
         d.mkdir(parents=True, exist_ok=True)
@@ -355,7 +355,7 @@ def service_status(suffix: str = "daemon") -> ServiceStatus:
     """Query the status of a specific SK launchd service.
 
     Args:
-        suffix: Service suffix (e.g., 'daemon', 'skcomm-heartbeat').
+        suffix: Service suffix (e.g., 'daemon', 'skcomms-heartbeat').
 
     Returns:
         ServiceStatus with current state.
@@ -420,7 +420,7 @@ def service_logs(suffix: str = "daemon", lines: int = 50) -> str:
                 )
                 if r.stdout.strip():
                     output_parts.append(f"--- {log_path.name} ---\n{r.stdout}")
-            except Exception:
-                pass
+            except Exception as exc:
+                logger.warning("Failed to read launchd log %s: %s", log_path, exc)
 
     return "\n".join(output_parts) if output_parts else f"No logs found in {logs_dir}"

package/src/skcapstone/mcp_launcher.py

@@ -138,9 +138,23 @@ def _setup_environment() -> None:
     """Set required environment variables if not already present."""
     home = Path.home()
     skcapstone_home = home / ".skcapstone"
+    agent_name = os.environ.get("SKCAPSTONE_AGENT")
+    if not agent_name:
+        try:
+            from . import active_agent_name
+
+            agent_name = active_agent_name()
+        except Exception as e:
+            logger.warning("mcp_launcher.py: %s", e)
+            agent_name = None
 
     os.environ.setdefault("SKCAPSTONE_HOME", str(skcapstone_home))
-    os.environ.setdefault("SKMEMORY_HOME", str(skcapstone_home / "memory"))
+    if agent_name:
+        os.environ.setdefault("SKCAPSTONE_AGENT", agent_name)
+        os.environ.setdefault(
+            "SKMEMORY_HOME",
+            str(skcapstone_home / "agents" / agent_name / "memory"),
+        )
 
     # Ensure src/ is on PYTHONPATH for importability
     src_dir = str(Path(__file__).resolve().parent.parent)

package/src/skcapstone/mcp_server.py

@@ -9,8 +9,8 @@ Tools:
     memory_store    — Save content to SKMemory
     memory_search   — Search memories by query
     memory_recall   — Recall a specific memory by ID
-    send_message    — Send a message via SKComm
-    check_inbox     — Check for new SKComm messages
+    send_message    — Send a message via SKComms
+    check_inbox     — Check for new SKComms messages
     sync_push       — Push agent state to sync mesh
     sync_pull       — Pull seeds from peers
     coord_status    — Show coordination board
@@ -108,33 +108,18 @@ from mcp.server import Server
 from mcp.server.stdio import stdio_server
 from mcp.types import TextContent, Tool
 
-from . import AGENT_HOME
+from .mcp_tools._helpers import (
+    _error_response,
+    _home,
+    _json_response,
+    _text_response,
+)
 
 logger = logging.getLogger("skcapstone.mcp")
 
 server = Server("skcapstone")
 
 
-def _home() -> Path:
-    """Resolve the agent home directory."""
-    return Path(AGENT_HOME).expanduser()
-
-
-def _json_response(data: Any) -> list[TextContent]:
-    """Wrap data as a JSON text content response."""
-    return [TextContent(type="text", text=json.dumps(data, indent=2, default=str))]
-
-
-def _text_response(text: str) -> list[TextContent]:
-    """Wrap a plain string as a text content response."""
-    return [TextContent(type="text", text=text)]
-
-
-def _error_response(message: str) -> list[TextContent]:
-    """Return an error message as text content."""
-    return [TextContent(type="text", text=json.dumps({"error": message}))]
-
-
 def _get_agent_name(home: Path) -> str:
     """Read the agent name from identity file."""
     identity_path = home / "identity" / "identity.json"
@@ -142,8 +127,8 @@ def _get_agent_name(home: Path) -> str:
         try:
             data = json.loads(identity_path.read_text(encoding="utf-8"))
             return data.get("name", "anonymous")
-        except Exception:
-            pass
+        except Exception as exc:
+            logger.warning("Failed to read agent name from identity.json: %s", exc)
     return "anonymous"
 
 
@@ -242,7 +227,7 @@ async def list_tools() -> list[Tool]:
         Tool(
             name="send_message",
             description=(
-                "Send a message to another agent via SKComm. "
+                "Send a message to another agent via SKComms. "
                 "Routes through available transports (Syncthing, file)."
             ),
             inputSchema={
@@ -268,7 +253,7 @@ async def list_tools() -> list[Tool]:
         Tool(
             name="check_inbox",
             description=(
-                "Check for new incoming messages across all SKComm transports. "
+                "Check for new incoming messages across all SKComms transports. "
                 "Returns any unread message envelopes."
             ),
             inputSchema={"type": "object", "properties": {}, "required": []},
@@ -1643,7 +1628,7 @@ async def list_tools() -> list[Tool]:
             description=(
                 "Check ecosystem package versions against PyPI. "
                 "Shows installed vs latest for skmemory, skcapstone, capauth, "
-                "sksecurity, skcomm, skchat, cloud9-protocol."
+                "sksecurity, skcomms, skchat, cloud9."
             ),
             inputSchema={
                 "type": "object",
@@ -2368,11 +2353,11 @@ async def list_tools() -> list[Tool]:
                 "required": [],
             },
         ),
-        # ── SKComm tools ──────────────────────────────────────
+        # ── SKComms tools ──────────────────────────────────────
         Tool(
             name="comm_notify",
             description=(
-                "Send a notification message via SKComm. Routes through "
+                "Send a notification message via SKComms. Routes through "
                 "available transports (Syncthing, file, Tailscale). "
                 "Supports urgency levels for priority routing."
             ),
@@ -2403,7 +2388,7 @@ async def list_tools() -> list[Tool]:
         Tool(
             name="comm_status",
             description=(
-                "Show SKComm subsystem status: installed version, "
+                "Show SKComms subsystem status: installed version, "
                 "available transports, connection state, and recent "
                 "delivery statistics."
             ),
@@ -2654,6 +2639,39 @@ async def list_tools() -> list[Tool]:
                 "required": ["query"],
             },
         ),
+        # Brain-First Protocol
+        Tool(
+            name="brain_first_check",
+            description=(
+                "Brain-First Protocol: consult the agent's memory before "
+                "acting on a task. Extracts keywords from the given context, "
+                "searches memory for relevant prior knowledge, and returns "
+                "any matching memories. Use this before starting new work to "
+                "avoid duplicating effort or missing prior decisions."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "context": {
+                        "type": "string",
+                        "description": (
+                            "The task description, prompt, or action context "
+                            "to search memory for"
+                        ),
+                    },
+                    "tags": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "description": "Optional tag filter for the memory search",
+                    },
+                    "max_results": {
+                        "type": "integer",
+                        "description": "Max memories to return (default: from config, usually 5)",
+                    },
+                },
+                "required": ["context"],
+            },
+        ),
     ]
 
 
@@ -2793,7 +2811,7 @@ async def call_tool(name: str, arguments: dict) -> list[TextContent]:
         # SKChat
         "chat_send": _handle_chat_send,
         "chat_history": _handle_chat_history,
-        # SKComm
+        # SKComms
         "comm_notify": _handle_comm_notify,
         "comm_status": _handle_comm_status,
         # CapAuth
@@ -2813,6 +2831,8 @@ async def call_tool(name: str, arguments: dict) -> list[TextContent]:
         "itil_cab_vote": _handle_itil_cab_vote,
         "itil_status": _handle_itil_status,
         "itil_kedb_search": _handle_itil_kedb_search,
+        # Brain-First Protocol
+        "brain_first_check": _handle_brain_first_check,
     }
     handler = handlers.get(name)
     if handler is None:
@@ -2842,7 +2862,8 @@ def _get_memory_backend_health() -> dict:
         if "graph" in health:
             backends["skgraph"] = "ok" if health["graph"].get("ok") else "error"
         return backends or {"json": "ok"}
-    except Exception:
+    except Exception as e:
+        logger.warning("Failed to get memory backend health: %s", e)
         return {"json": "ok"}
 
 
@@ -2973,15 +2994,15 @@ async def _handle_memory_recall(args: dict) -> list[TextContent]:
 
 
 async def _handle_send_message(args: dict) -> list[TextContent]:
-    """Send a message via SKComm."""
+    """Send a message via SKComms."""
     recipient = args.get("recipient", "")
     message = args.get("message", "")
     if not recipient or not message:
         return _error_response("recipient and message are required")
 
     try:
-        from skcomm.core import SKComm
-        comm = SKComm.from_config()
+        from skcomms.core import SKComms
+        comm = SKComms.from_config()
         report = comm.send(recipient, message)
         return _json_response({
             "sent": report.success,
@@ -2996,7 +3017,7 @@ async def _handle_send_message(args: dict) -> list[TextContent]:
             ],
         })
     except ImportError:
-        return _error_response("SKComm not installed. Run: pip install skcomm")
+        return _error_response("SKComms not installed. Run: pip install skcomms")
     except Exception as exc:
         return _error_response(f"Send failed: {exc}")
 
@@ -3004,8 +3025,8 @@ async def _handle_send_message(args: dict) -> list[TextContent]:
 async def _handle_check_inbox(_args: dict) -> list[TextContent]:
     """Check for incoming messages."""
     try:
-        from skcomm.core import SKComm
-        comm = SKComm.from_config()
+        from skcomms.core import SKComms
+        comm = SKComms.from_config()
         envelopes = comm.receive()
         return _json_response([
             {
@@ -3021,7 +3042,7 @@ async def _handle_check_inbox(_args: dict) -> list[TextContent]:
             for e in envelopes
         ])
     except ImportError:
-        return _error_response("SKComm not installed. Run: pip install skcomm")
+        return _error_response("SKComms not installed. Run: pip install skcomms")
     except Exception as exc:
         return _error_response(f"Inbox check failed: {exc}")
 
@@ -3154,8 +3175,8 @@ async def _handle_coord_complete(args: dict) -> list[TextContent]:
                     t.priority.value, ("community", "support_ticket", 50)
                 )
                 break
-    except Exception:
-        pass
+    except Exception as exc:
+        logger.warning("Failed to calculate joules for completed task %s: %s", task_id, exc)
 
     return _json_response({
         "completed": True,
@@ -3210,6 +3231,8 @@ async def _handle_ritual(_args: dict) -> list[TextContent]:
             "journal_entries": result.journal_entries,
             "germination_prompts": result.germination_prompts,
             "strongest_memories": result.strongest_memories,
+            "song_anchors_loaded": result.song_anchors_loaded,
+            "song_anchor_ids": result.song_anchor_ids,
             "context_prompt": result.context_prompt,
         })
     except ImportError:
@@ -3589,7 +3612,8 @@ def _get_skchat_identity() -> str:
         home = _home()
         runtime = get_runtime(home)
         return f"capauth:{runtime.manifest.name}@local"
-    except Exception:
+    except Exception as e:
+        logger.warning("Failed to resolve sovereign identity: %s", e)
         return "capauth:agent@local"
 
 
@@ -3606,7 +3630,8 @@ def _resolve_recipient(name: str) -> str:
     try:
         from skchat.identity_bridge import resolve_peer_name
         return resolve_peer_name(name)
-    except Exception:
+    except Exception as e:
+        logger.warning("Failed to resolve peer name %r: %s", name, e)
         return f"capauth:{name}@local"
 
 
@@ -4793,18 +4818,18 @@ async def _handle_chat_history(args: dict) -> list[TextContent]:
     return await _impl(args)
 
 
-# ── SKComm tools ──────────────────────────────────────────
+# ── SKComms tools ──────────────────────────────────────────
 
 
 async def _handle_comm_notify(args: dict) -> list[TextContent]:
-    """Send a notification via SKComm."""
-    from .mcp_tools.skcomm_tools import _handle_comm_notify as _impl
+    """Send a notification via SKComms."""
+    from .mcp_tools.skcomms_tools import _handle_comm_notify as _impl
     return await _impl(args)
 
 
 async def _handle_comm_status(args: dict) -> list[TextContent]:
-    """Show SKComm subsystem status."""
-    from .mcp_tools.skcomm_tools import _handle_comm_status as _impl
+    """Show SKComms subsystem status."""
+    from .mcp_tools.skcomms_tools import _handle_comm_status as _impl
     return await _impl(args)
 
 
@@ -4937,6 +4962,15 @@ async def _handle_itil_kedb_search(args: dict) -> list[TextContent]:
     return await _impl(args)
 
 
+# ── Brain-First Protocol ──────────────────────────────────
+
+
+async def _handle_brain_first_check(args: dict) -> list[TextContent]:
+    """Consult memory before acting on a task."""
+    from .mcp_tools.brain_first_tools import _handle_brain_first_check as _impl
+    return await _impl(args)
+
+
 # ═══════════════════════════════════════════════════════════
 # Entry Point
 # ═══════════════════════════════════════════════════════════

package/src/skcapstone/mcp_tools/__init__.py

@@ -17,6 +17,7 @@ from mcp.types import TextContent, Tool
 from . import (
     agent_tools,
     ansible_tools,
+    brain_first_tools,
     chat_tools,
     comm_tools,
     consciousness_tools,
@@ -49,6 +50,7 @@ from . import (
 # Ordered list of all tool-group modules.
 _MODULES = [
     agent_tools,
+    brain_first_tools,
     memory_tools,
     comm_tools,
     sync_tools,

package/src/skcapstone/mcp_tools/_helpers.py

@@ -46,6 +46,6 @@ def _get_agent_name(home: Path) -> str:
         try:
             data = json.loads(identity_path.read_text(encoding="utf-8"))
             return data.get("name", "anonymous")
-        except Exception:
-            pass
+        except Exception as exc:
+            logger.warning("Failed to read agent name from identity.json: %s", exc)
     return "anonymous"

package/src/skcapstone/mcp_tools/ansible_tools.py

@@ -10,6 +10,7 @@ from __future__ import annotations
 
 import asyncio
 import json
+import logging
 import shutil
 import uuid
 from pathlib import Path
@@ -18,6 +19,8 @@ from mcp.types import TextContent, Tool
 
 from ._helpers import _error_response, _home, _json_response
 
+logger = logging.getLogger(__name__)
+
 TOOLS: list[Tool] = [
     Tool(
         name="run_ansible_playbook",
@@ -146,8 +149,8 @@ async def _handle_run_ansible_playbook(args: dict) -> list[TextContent]:
                 try:
                     if _activity is not None:
                         _activity.push(event_type, {"run_id": run_id, "line": line})
-                except Exception:
-                    pass
+                except Exception as exc:
+                    logger.warning("Failed to push ansible line event for run %s: %s", run_id, exc)
 
         await asyncio.gather(
             _drain(proc.stdout, stdout_lines, "ansible.playbook.line"),
@@ -184,8 +187,8 @@ async def _handle_run_ansible_playbook(args: dict) -> list[TextContent]:
     try:
         if _activity is not None:
             _activity.push("ansible.playbook.done", summary)
-    except Exception:
-        pass
+    except Exception as exc:
+        logger.warning("Failed to push ansible.playbook.done event for run %s: %s", run_id, exc)
 
     # --- store in memory with tag=ansible-run ---
     try:

package/src/skcapstone/mcp_tools/brain_first_tools.py

@@ -0,0 +1,90 @@
+"""Brain-First Protocol MCP tools.
+
+Exposes the brain-first memory consultation as an MCP tool so that
+any MCP client can ask "what do I already know about this?" before
+acting on a task.
+"""
+
+from __future__ import annotations
+
+from mcp.types import TextContent, Tool
+
+from ._helpers import _json_response
+
+TOOLS: list[Tool] = [
+    Tool(
+        name="brain_first_check",
+        description=(
+            "Brain-First Protocol: consult the agent's memory before "
+            "acting on a task. Extracts keywords from the given context, "
+            "searches memory for relevant prior knowledge, and returns "
+            "any matching memories. Use this before starting new work to "
+            "avoid duplicating effort or missing prior decisions."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "context": {
+                    "type": "string",
+                    "description": (
+                        "The task description, prompt, or action context "
+                        "to search memory for"
+                    ),
+                },
+                "tags": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": "Optional tag filter for the memory search",
+                },
+                "max_results": {
+                    "type": "integer",
+                    "description": "Max memories to return (default: from config, usually 5)",
+                },
+            },
+            "required": ["context"],
+        },
+    ),
+]
+
+
+async def _handle_brain_first_check(args: dict) -> list[TextContent]:
+    """Run a brain-first memory consultation."""
+    from ..brain_first import BrainFirstConfig, brain_first_check, _load_config
+
+    context = args.get("context", "")
+    if not context:
+        return _json_response({"error": "context is required"})
+
+    config = _load_config()
+
+    # Allow per-call override of max_results
+    max_results = args.get("max_results")
+    if max_results is not None:
+        config.max_results = max_results
+
+    result = brain_first_check(
+        context=context,
+        config=config,
+        tags=args.get("tags"),
+    )
+
+    response = {
+        "enabled": result.enabled,
+        "query": result.query,
+        "keywords": result.keywords,
+        "memories_found": len(result.memories),
+        "memories": result.memories,
+    }
+
+    if result.error:
+        response["warning"] = result.error
+
+    if result.has_memories:
+        response["context_block"] = result.as_context()
+
+    return _json_response(response)
+
+
+HANDLERS: dict = {
+    "brain_first_check": _handle_brain_first_check,
+}

package/src/skcapstone/mcp_tools/capauth_tools.py

@@ -8,11 +8,14 @@ Exposes two tools:
 from __future__ import annotations
 
 import json as _json
+import logging
 
 from mcp.types import TextContent, Tool
 
 from ._helpers import _error_response, _home, _json_response
 
+logger = logging.getLogger(__name__)
+
 TOOLS: list[Tool] = [
     Tool(
         name="capauth_status",
@@ -82,8 +85,8 @@ async def _handle_capauth_status(_args: dict) -> list[TextContent]:
     if did_key_file.exists():
         try:
             result["did_key_file"] = did_key_file.read_text(encoding="utf-8").strip()
-        except Exception:
-            pass
+        except Exception as exc:
+            logger.warning("Failed to read DID key file: %s", exc)
 
     # Check identity file
     identity_file = home / "identity" / "identity.json"
@@ -92,8 +95,8 @@ async def _handle_capauth_status(_args: dict) -> list[TextContent]:
             ident = _json.loads(identity_file.read_text(encoding="utf-8"))
             result["identity_name"] = ident.get("name")
             result["identity_fingerprint"] = ident.get("fingerprint")
-        except Exception:
-            pass
+        except Exception as exc:
+            logger.warning("Failed to read identity.json for capauth status: %s", exc)
 
     return _json_response(result)