@smilintux/skcapstone 0.9.0 → 0.12.5

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)
 

package/src/skcapstone/mcp_tools/comm_tools.py

@@ -1,4 +1,4 @@
-"""SKComm send/receive messaging tools."""
+"""SKComms send/receive messaging tools."""
 
 from __future__ import annotations
 
@@ -10,7 +10,7 @@ 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={
@@ -36,7 +36,7 @@ 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": []},
@@ -45,15 +45,15 @@ TOOLS: list[Tool] = [
 
 
 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,
@@ -68,7 +68,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}")
 
@@ -76,8 +76,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([
             {
@@ -93,7 +93,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}")
 

package/src/skcapstone/mcp_tools/coord_tools.py

@@ -2,10 +2,14 @@
 
 from __future__ import annotations
 
+import logging
+
 from mcp.types import TextContent, Tool
 
 from ._helpers import _error_response, _home, _json_response, _shared_root
 
+logger = logging.getLogger(__name__)
+
 TOOLS: list[Tool] = [
     Tool(
         name="coord_status",
@@ -149,8 +153,8 @@ async def _handle_coord_claim(args: dict) -> list[TextContent]:
         try:
             from .. import activity
             activity.push("task.claimed", {"task_id": task_id, "agent": agent_name})
-        except Exception:
-            pass
+        except Exception as exc:
+            logger.warning("Failed to push task.claimed activity for %s: %s", task_id, exc)
         return _json_response({
             "claimed": True,
             "task_id": task_id,
@@ -175,8 +179,8 @@ async def _handle_coord_complete(args: dict) -> list[TextContent]:
     try:
         from .. import activity
         activity.push("task.completed", {"task_id": task_id, "agent": agent_name})
-    except Exception:
-        pass
+    except Exception as exc:
+        logger.warning("Failed to push task.completed activity for %s: %s", task_id, exc)
     return _json_response({
         "completed": True,
         "task_id": task_id,

package/src/skcapstone/mcp_tools/did_tools.py

@@ -10,6 +10,7 @@ Exposes four tools:
 from __future__ import annotations
 
 import json as _json
+import logging
 import os as _os
 import socket as _socket
 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="did_show",
@@ -165,8 +168,8 @@ def _load_policy() -> dict:
     if p.exists():
         try:
             return _json.loads(p.read_text(encoding="utf-8"))
-        except Exception:
-            pass
+        except Exception as exc:
+            logger.warning("Failed to load DID policy from %s: %s", p, exc)
     return dict(_POLICY_DEFAULT)
 
 
@@ -191,8 +194,8 @@ def _resolve_tailnet(tailnet_hostname: str, tailnet_name: str) -> tuple[str, str
         if not tailnet_hostname:
             try:
                 tailnet_hostname = _socket.gethostname()
-            except Exception:
-                pass
+            except Exception as exc:
+                logger.warning("Failed to resolve hostname for tailnet DID: %s", exc)
     if not tailnet_name:
         tailnet_name = _os.environ.get("SKWORLD_TAILNET", "")
     return tailnet_hostname, tailnet_name
@@ -297,8 +300,8 @@ async def _handle_did_verify_peer(args: dict) -> list[TextContent]:
                 _json.dumps(peer_data, indent=2, default=str),
                 encoding="utf-8",
             )
-        except Exception:
-            pass
+        except Exception as exc:
+            logger.warning("Failed to cache did:key back to peer file %s: %s", peer_file, exc)
 
     return _json_response({
         "name": name,
@@ -361,11 +364,11 @@ async def _handle_did_publish(args: dict) -> list[TextContent]:
         except Exception as exc:
             errors.append(f"{path}: {exc}")
 
-    skcomm_home = Path(_os.environ.get("SKCOMM_HOME", str(Path.home() / ".skcomm")))
+    skcomms_home = Path(_os.environ.get("SKCOMMS_HOME", str(Path.home() / ".skcomms")))
     did_dir = _home() / "did"
 
     # Tier 2 (mesh) — always written; used by Tailscale Serve
-    _write(skcomm_home / "well-known" / "did.json", _json.dumps(docs[DIDTier.WEB_MESH], indent=2))
+    _write(skcomms_home / "well-known" / "did.json", _json.dumps(docs[DIDTier.WEB_MESH], indent=2))
     # Tier 1 (did:key) — always written; self-contained anchor
     _write(did_dir / "key.json", _json.dumps(docs[DIDTier.KEY], indent=2))
     _write(did_dir / "did_key.txt", gen._ctx.did_key_id)

package/src/skcapstone/mcp_tools/gtd_tools.py

@@ -382,7 +382,7 @@ async def _handle_gtd_capture(args: dict) -> list[TextContent]:
     return _json_response({
         "captured": True,
         "id": item["id"],
-        "text": item["text"],
+        "text": item.get("text") or item.get("title") or "",
         "source": item["source"],
         "privacy": item["privacy"],
         "context": item["context"],
@@ -498,7 +498,7 @@ async def _handle_gtd_clarify(args: dict) -> list[TextContent]:
     return _json_response({
         "clarified": True,
         "id": item["id"],
-        "text": item["text"],
+        "text": item.get("text") or item.get("title") or "",
         "destination": dest_name,
         "status": item["status"],
         "priority": item.get("priority"),
@@ -550,7 +550,7 @@ async def _handle_gtd_move(args: dict) -> list[TextContent]:
     return _json_response({
         "moved": True,
         "id": item["id"],
-        "text": item["text"],
+        "text": item.get("text") or item.get("title") or "",
         "from": source_list,
         "to": dest_name,
         "status": item["status"],
@@ -582,7 +582,7 @@ async def _handle_gtd_done(args: dict) -> list[TextContent]:
     return _json_response({
         "done": True,
         "id": item["id"],
-        "text": item["text"],
+        "text": item.get("text") or item.get("title") or "",
         "from": source_list,
         "completed_at": item["completed_at"],
         "archive_count": len(archive),

package/src/skcapstone/mcp_tools/memory_tools.py

@@ -2,10 +2,14 @@
 
 from __future__ import annotations
 
+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="memory_store",
@@ -130,8 +134,8 @@ async def _handle_memory_store(args: dict) -> list[TextContent]:
             "importance": entry.importance,
             "tags": entry.tags,
         })
-    except Exception:
-        pass
+    except Exception as exc:
+        logger.warning("Failed to push memory.stored activity for %s: %s", entry.memory_id, exc)
     return _json_response({
         "memory_id": entry.memory_id,
         "layer": entry.layer.value,

package/src/skcapstone/mcp_tools/notification_tools.py

@@ -54,10 +54,17 @@ async def _handle_send_notification(args: dict) -> list[TextContent]:
     if urgency not in {"low", "normal", "critical"}:
         return _error_response("urgency must be one of: low, normal, critical")
 
+    from ..notifications import desktop_notifications_enabled
+
+    if not desktop_notifications_enabled():
+        timestamp = datetime.datetime.now(datetime.timezone.utc).isoformat()
+        return _json_response({"sent": False, "suppressed": True, "timestamp": timestamp})
+
     # Run notify-send in a subprocess (non-blocking).
     proc = await asyncio.create_subprocess_exec(
         "notify-send",
-        "--urgency", urgency,
+        "--urgency",
+        urgency,
         title,
         body,
         stdout=asyncio.subprocess.DEVNULL,
@@ -71,16 +78,25 @@ async def _handle_send_notification(args: dict) -> list[TextContent]:
 
     timestamp = datetime.datetime.now(datetime.timezone.utc).isoformat()
 
-    # Log notification to skcomm/notifications/ (not memory/).
+    # Log notification to skcomms/notifications/ (not memory/).
     try:
         import json as _j
         import uuid
+
         home = _home()
-        agent_name = os.environ.get("SKCAPSTONE_AGENT", "lumina")
-        notif_dir = home / "agents" / agent_name / "skcomm" / "notifications"
+        from .. import active_agent_name
+
+        agent_name = os.environ.get("SKCAPSTONE_AGENT") or active_agent_name()
+        notif_dir = home / "agents" / agent_name / "skcomms" / "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}
+        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  # notification log failure must not block the response

package/src/skcapstone/mcp_tools/{skcomm_tools.py → skcomms_tools.py}

@@ -1,8 +1,8 @@
-"""SKComm notification and status tools.
+"""SKComms notification and status tools.
 
 Exposes two tools:
-    comm_notify — Send a notification via SKComm transports
-    comm_status — Show SKComm subsystem status
+    comm_notify — Send a notification via SKComms transports
+    comm_status — Show SKComms subsystem status
 """
 
 from __future__ import annotations
@@ -15,7 +15,7 @@ TOOLS: list[Tool] = [
     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."
         ),
@@ -46,7 +46,7 @@ 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."
         ),
@@ -56,16 +56,16 @@ TOOLS: list[Tool] = [
 
 
 async def _handle_comm_notify(args: dict) -> list[TextContent]:
-    """Send a notification via SKComm."""
+    """Send a notification 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  # type: ignore[import]
+        from skcomms.core import SKComms  # type: ignore[import]
 
-        comm = SKComm.from_config()
+        comm = SKComms.from_config()
         report = comm.send(recipient, message)
         return _json_response({
             "sent": report.success,
@@ -81,29 +81,29 @@ async def _handle_comm_notify(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"Notification send failed: {exc}")
 
 
 async def _handle_comm_status(_args: dict) -> list[TextContent]:
-    """Show SKComm subsystem status."""
+    """Show SKComms subsystem status."""
     result: dict = {}
 
     try:
-        import skcomm  # type: ignore[import]
+        import skcomms  # type: ignore[import]
 
         result["installed"] = True
-        result["version"] = getattr(skcomm, "__version__", "unknown")
+        result["version"] = getattr(skcomms, "__version__", "unknown")
     except ImportError:
         result["installed"] = False
         result["version"] = None
         return _json_response(result)
 
     try:
-        from skcomm.core import SKComm  # type: ignore[import]
+        from skcomms.core import SKComms  # type: ignore[import]
 
-        comm = SKComm.from_config()
+        comm = SKComms.from_config()
         result["transports"] = [
             t.name for t in getattr(comm, "transports", [])
         ]

package/src/skcapstone/mcp_tools/soul_tools.py

@@ -2,10 +2,14 @@
 
 from __future__ import annotations
 
+import logging
+
 from mcp.types import TextContent, Tool
 
 from ._helpers import _error_response, _home, _json_response, _text_response
 
+logger = logging.getLogger(__name__)
+
 TOOLS: list[Tool] = [
     Tool(
         name="soul_list",
@@ -179,6 +183,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:
@@ -250,8 +256,8 @@ async def _handle_soul_list(args: dict) -> list[TextContent]:
                 "source": "installed",
                 "active": name == state.active_soul,
             })
-    except Exception:
-        pass
+    except Exception as exc:
+        logger.warning("Failed to list installed soul blueprints: %s", exc)
 
     # 2) Blueprints repo
     blueprints_repo = Path.home() / "clawd" / "soul-blueprints" / "blueprints"

package/src/skcapstone/mdns_discovery.py

@@ -238,8 +238,8 @@ class MDNSDiscovery:
                         agent_name,
                     )
                     return
-            except Exception:
-                pass
+            except Exception as exc:
+                logger.warning("Failed to read existing mDNS heartbeat for %s: %s", agent_name, exc)
 
         heartbeat = {
             "agent_name": agent_name,

package/src/skcapstone/memory_curator.py

@@ -59,7 +59,7 @@ _TAG_PATTERNS: list[tuple[re.Pattern, str]] = [
     (re.compile(r"\bcapauth\b", re.I), "capauth"),
     (re.compile(r"\bskcapstone\b", re.I), "skcapstone"),
     (re.compile(r"\bskmemory\b", re.I), "skmemory"),
-    (re.compile(r"\bskcomm\b", re.I), "skcomm"),
+    (re.compile(r"\bskcomms\b", re.I), "skcomms"),
     (re.compile(r"\bskchat\b", re.I), "skchat"),
     (re.compile(r"\bsyncthing\b", re.I), "syncthing"),
     (re.compile(r"\bMCP\b", re.I), "mcp"),

package/src/skcapstone/memory_engine.py

@@ -25,6 +25,7 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Optional
 
+from . import active_agent_name
 from .models import MemoryEntry, MemoryLayer, MemoryState, PillarStatus
 
 logger = logging.getLogger("skcapstone.memory")
@@ -48,9 +49,15 @@ def _get_unified():
 
 def _memory_dir(home: Path) -> Path:
     """Resolve the memory directory, creating it if needed."""
-    # Use agent-specific memory directory if agent name is set
-    agent_name = os.environ.get("SKCAPSTONE_AGENT", "lumina")
-    mem = home / "agents" / agent_name / "memory"
+    # Accept either the shared root (~/.skcapstone) or an agent home
+    # (~/.skcapstone/agents/<agent>) and resolve to the active memory dir.
+    agent_name = os.environ.get("SKCAPSTONE_AGENT") or active_agent_name()
+    if home.parent.name == "agents":
+        mem = home / "memory"
+    elif agent_name:
+        mem = home / "agents" / agent_name / "memory"
+    else:
+        mem = home / "memory"
     mem.mkdir(parents=True, exist_ok=True)
     for layer in MemoryLayer:
         (mem / layer.value).mkdir(parents=True, exist_ok=True)