@smilintux/skcapstone 0.1.0 → 0.2.3

package/src/skcapstone/mcp_tools/notification_tools.py

@@ -0,0 +1,92 @@
+"""Desktop notification tool — send_notification via notify-send."""
+
+from __future__ import annotations
+
+import asyncio
+import datetime
+
+from mcp.types import TextContent, Tool
+
+from ._helpers import _error_response, _home, _json_response
+
+TOOLS: list[Tool] = [
+    Tool(
+        name="send_notification",
+        description=(
+            "Send a desktop notification via notify-send. "
+            "Stores the event in agent memory with tag=notification "
+            "and returns {sent, timestamp}."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "title": {
+                    "type": "string",
+                    "description": "Notification title",
+                },
+                "body": {
+                    "type": "string",
+                    "description": "Notification body text",
+                },
+                "urgency": {
+                    "type": "string",
+                    "enum": ["low", "normal", "critical"],
+                    "description": "Urgency level: low, normal, or critical (default: normal)",
+                },
+            },
+            "required": ["title", "body"],
+        },
+    ),
+]
+
+
+async def _handle_send_notification(args: dict) -> list[TextContent]:
+    """Send a desktop notification and store memory record."""
+    title = args.get("title", "").strip()
+    body = args.get("body", "").strip()
+    urgency = args.get("urgency", "normal")
+
+    if not title:
+        return _error_response("title is required")
+    if not body:
+        return _error_response("body is required")
+    if urgency not in {"low", "normal", "critical"}:
+        return _error_response("urgency must be one of: low, normal, critical")
+
+    # Run notify-send in a subprocess (non-blocking).
+    proc = await asyncio.create_subprocess_exec(
+        "notify-send",
+        "--urgency", urgency,
+        title,
+        body,
+        stdout=asyncio.subprocess.DEVNULL,
+        stderr=asyncio.subprocess.PIPE,
+    )
+    _, stderr = await proc.communicate()
+
+    if proc.returncode != 0:
+        err_msg = stderr.decode(errors="replace").strip() if stderr else "unknown error"
+        return _error_response(f"notify-send failed (exit {proc.returncode}): {err_msg}")
+
+    timestamp = datetime.datetime.now(datetime.timezone.utc).isoformat()
+
+    # Persist a memory entry so the agent recalls past notifications.
+    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,
+        )
+    except Exception:
+        pass  # memory failure must not block the notification response
+
+    return _json_response({"sent": True, "timestamp": timestamp})
+
+
+HANDLERS: dict = {
+    "send_notification": _handle_send_notification,
+}

package/src/skcapstone/mcp_tools/promoter_tools.py

@@ -0,0 +1,101 @@
+"""Memory promoter tools."""
+
+from __future__ import annotations
+
+from mcp.types import TextContent, Tool
+
+from ._helpers import _home, _json_response
+
+TOOLS: list[Tool] = [
+    Tool(
+        name="promoter_sweep",
+        description=(
+            "Run a memory promotion sweep. Evaluates memories using "
+            "weighted scoring (access frequency, importance, emotion, age, tags) "
+            "and promotes qualifying entries to higher tiers."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "dry_run": {
+                    "type": "boolean",
+                    "description": "Preview promotions without applying (default: false)",
+                },
+                "limit": {
+                    "type": "integer",
+                    "description": "Max memories to evaluate (default: unlimited)",
+                },
+                "layer": {
+                    "type": "string",
+                    "description": "Only evaluate this layer: short-term or mid-term",
+                },
+            },
+            "required": [],
+        },
+    ),
+    Tool(
+        name="promoter_history",
+        description=(
+            "View recent memory promotion history \u2014 "
+            "shows which memories were promoted, scores, and timestamps."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "limit": {
+                    "type": "integer",
+                    "description": "Max entries to return (default: 20)",
+                },
+            },
+            "required": [],
+        },
+    ),
+]
+
+
+async def _handle_promoter_sweep(args: dict) -> list[TextContent]:
+    """Run a memory promotion sweep."""
+    from ..memory_promoter import PromotionEngine
+
+    home = _home()
+    engine = PromotionEngine(home)
+
+    result = engine.sweep(
+        dry_run=args.get("dry_run", False),
+        limit=args.get("limit"),
+        layer=args.get("layer"),
+    )
+    return _json_response({
+        "scanned": result.scanned,
+        "promoted": result.promoted,
+        "skipped": result.skipped,
+        "dry_run": result.dry_run,
+        "by_layer": result.by_layer,
+        "promotions": [
+            {
+                "memory_id": c.memory_id,
+                "current_layer": c.current_layer,
+                "target_layer": c.target_layer,
+                "score": round(c.score, 3),
+                "promoted": c.promoted,
+            }
+            for c in result.candidates
+            if c.promoted or result.dry_run
+        ],
+    })
+
+
+async def _handle_promoter_history(args: dict) -> list[TextContent]:
+    """View promotion history."""
+    from ..memory_promoter import PromotionEngine
+
+    home = _home()
+    engine = PromotionEngine(home)
+    history = engine.get_history(limit=args.get("limit", 20))
+    return _json_response(history)
+
+
+HANDLERS: dict = {
+    "promoter_sweep": _handle_promoter_sweep,
+    "promoter_history": _handle_promoter_history,
+}

package/src/skcapstone/mcp_tools/pubsub_tools.py

@@ -0,0 +1,183 @@
+"""Pub/sub messaging tools."""
+
+from __future__ import annotations
+
+from mcp.types import TextContent, Tool
+
+from ._helpers import _get_agent_name, _home, _json_response, _shared_root
+
+TOOLS: list[Tool] = [
+    Tool(
+        name="pubsub_publish",
+        description=(
+            "Publish a message to a topic. "
+            "Creates the topic if it doesn't exist. "
+            "Messages are distributed via Syncthing to all subscribers."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "topic": {
+                    "type": "string",
+                    "description": "Topic name (e.g., 'agent.status', 'task.updates')",
+                },
+                "payload": {
+                    "type": "object",
+                    "description": "Message payload (any JSON object)",
+                },
+                "ttl_seconds": {
+                    "type": "integer",
+                    "description": "Message TTL in seconds (default: 3600)",
+                },
+            },
+            "required": ["topic", "payload"],
+        },
+    ),
+    Tool(
+        name="pubsub_subscribe",
+        description=(
+            "Subscribe to a topic pattern. "
+            "Supports wildcards: 'agent.*' matches 'agent.status', 'agent.health'. "
+            "Subscription persists across sessions."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "pattern": {
+                    "type": "string",
+                    "description": "Topic pattern (supports * wildcards)",
+                },
+            },
+            "required": ["pattern"],
+        },
+    ),
+    Tool(
+        name="pubsub_poll",
+        description=(
+            "Poll for new messages on subscribed topics. "
+            "Returns messages since the last poll or a given timestamp."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "topic": {
+                    "type": "string",
+                    "description": "Specific topic to poll (omit for all subscribed)",
+                },
+                "limit": {
+                    "type": "integer",
+                    "description": "Max messages to return (default: 50)",
+                },
+            },
+            "required": [],
+        },
+    ),
+    Tool(
+        name="pubsub_topics",
+        description=(
+            "List all known topics with message counts and last activity."
+        ),
+        inputSchema={"type": "object", "properties": {}, "required": []},
+    ),
+    Tool(
+        name="pubsub_stats",
+        description=(
+            "Show per-topic pub/sub statistics: live message count and oldest "
+            "message age in seconds. Expired messages are excluded from counts."
+        ),
+        inputSchema={"type": "object", "properties": {}, "required": []},
+    ),
+]
+
+
+async def _handle_pubsub_publish(args: dict) -> list[TextContent]:
+    """Publish a message to a topic."""
+    from ..pubsub import PubSub
+
+    home = _home()
+    agent_name = _get_agent_name(home)
+    ps = PubSub(_shared_root(), agent_name=agent_name)
+    ps.initialize()
+
+    msg = ps.publish(
+        topic=args["topic"],
+        payload=args["payload"],
+        ttl_seconds=args.get("ttl_seconds", 3600),
+    )
+    return _json_response({
+        "message_id": msg.message_id,
+        "topic": msg.topic,
+        "sender": msg.sender,
+        "published_at": str(msg.published_at),
+    })
+
+
+async def _handle_pubsub_subscribe(args: dict) -> list[TextContent]:
+    """Subscribe to a topic pattern."""
+    from ..pubsub import PubSub
+
+    home = _home()
+    agent_name = _get_agent_name(home)
+    ps = PubSub(_shared_root(), agent_name=agent_name)
+    ps.initialize()
+
+    sub = ps.subscribe(args["pattern"])
+    return _json_response({
+        "pattern": sub.pattern,
+        "agent": agent_name,
+        "subscribed_at": str(sub.subscribed_at),
+    })
+
+
+async def _handle_pubsub_poll(args: dict) -> list[TextContent]:
+    """Poll for new messages."""
+    from ..pubsub import PubSub
+
+    home = _home()
+    agent_name = _get_agent_name(home)
+    ps = PubSub(_shared_root(), agent_name=agent_name)
+    ps.initialize()
+
+    messages = ps.poll(
+        topic=args.get("topic"),
+        limit=args.get("limit", 50),
+    )
+    return _json_response([
+        {
+            "message_id": m.message_id,
+            "topic": m.topic,
+            "sender": m.sender,
+            "payload": m.payload,
+            "published_at": str(m.published_at),
+        }
+        for m in messages
+    ])
+
+
+async def _handle_pubsub_topics(_args: dict) -> list[TextContent]:
+    """List all known topics."""
+    from ..pubsub import PubSub
+
+    home = _home()
+    ps = PubSub(_shared_root(), agent_name=_get_agent_name(home))
+    ps.initialize()
+    return _json_response(ps.list_topics())
+
+
+async def _handle_pubsub_stats(_args: dict) -> list[TextContent]:
+    """Return per-topic stats: live message count and oldest message age."""
+    from ..pubsub import PubSub
+
+    home = _home()
+    ps = PubSub(_shared_root(), agent_name=_get_agent_name(home))
+    ps.initialize()
+    return _json_response(ps.topic_stats())
+
+
+HANDLERS: dict = {
+    "pubsub_publish": _handle_pubsub_publish,
+    "pubsub_subscribe": _handle_pubsub_subscribe,
+    "pubsub_poll": _handle_pubsub_poll,
+    "pubsub_topics": _handle_pubsub_topics,
+    "pubsub_stats": _handle_pubsub_stats,
+}

package/src/skcapstone/mcp_tools/security_tools.py

@@ -0,0 +1,110 @@
+"""SKSecurity audit and status tools.
+
+Exposes two tools:
+    security_audit_log — Read recent security audit log entries
+    security_status    — Show security pillar status and config
+"""
+
+from __future__ import annotations
+
+import json as _json
+
+from mcp.types import TextContent, Tool
+
+from ._helpers import _error_response, _home, _json_response
+
+TOOLS: list[Tool] = [
+    Tool(
+        name="security_audit_log",
+        description=(
+            "Read recent entries from the security audit log. "
+            "Returns structured JSONL entries with timestamp, event type, "
+            "detail, host, and optional agent/metadata fields. "
+            "Use limit to control how many entries are returned."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "limit": {
+                    "type": "integer",
+                    "description": "Maximum entries to return (default: 20, 0 = all)",
+                },
+            },
+            "required": [],
+        },
+    ),
+    Tool(
+        name="security_status",
+        description=(
+            "Show the security pillar status: whether sksecurity is installed, "
+            "audit log health, threat count, last scan time, and overall "
+            "security configuration."
+        ),
+        inputSchema={"type": "object", "properties": {}, "required": []},
+    ),
+]
+
+
+async def _handle_security_audit_log(args: dict) -> list[TextContent]:
+    """Read recent security audit log entries."""
+    home = _home()
+    limit = args.get("limit", 20)
+
+    try:
+        from ..pillars.security import read_audit_log
+
+        entries = read_audit_log(home, limit=limit)
+        return _json_response({
+            "count": len(entries),
+            "entries": [e.model_dump() for e in entries],
+        })
+    except Exception as exc:
+        return _error_response(f"Could not read audit log: {exc}")
+
+
+async def _handle_security_status(_args: dict) -> list[TextContent]:
+    """Show security pillar status."""
+    home = _home()
+    security_dir = home / "security"
+    config_file = security_dir / "security.json"
+
+    result: dict = {"initialized": security_dir.exists()}
+
+    if config_file.exists():
+        try:
+            result["config"] = _json.loads(
+                config_file.read_text(encoding="utf-8")
+            )
+        except Exception:
+            result["config"] = {"error": "could not parse security.json"}
+
+    # Check sksecurity availability
+    try:
+        import sksecurity  # type: ignore[import-untyped]
+
+        result["sksecurity_installed"] = True
+        result["sksecurity_version"] = getattr(sksecurity, "__version__", "unknown")
+    except ImportError:
+        result["sksecurity_installed"] = False
+        result["sksecurity_version"] = None
+
+    # Audit log stats
+    audit_log = security_dir / "audit.log"
+    if audit_log.exists():
+        try:
+            lines = audit_log.read_text(encoding="utf-8").splitlines()
+            result["audit_log_entries"] = len(
+                [ln for ln in lines if ln.strip()]
+            )
+        except Exception:
+            result["audit_log_entries"] = "unreadable"
+    else:
+        result["audit_log_entries"] = 0
+
+    return _json_response(result)
+
+
+HANDLERS: dict = {
+    "security_audit_log": _handle_security_audit_log,
+    "security_status": _handle_security_status,
+}

package/src/skcapstone/mcp_tools/skchat_tools.py

@@ -0,0 +1,175 @@
+"""SKChat send and history tools.
+
+Exposes two tools:
+    chat_send    — Send a message via SKChat
+    chat_history — Retrieve chat history
+"""
+
+from __future__ import annotations
+
+from mcp.types import TextContent, Tool
+
+from ._helpers import _error_response, _home, _json_response
+
+TOOLS: list[Tool] = [
+    Tool(
+        name="chat_send",
+        description=(
+            "Send a chat message to another agent via SKChat. "
+            "Wraps the AgentMessenger for delivery with optional "
+            "threading, structured payloads, and ephemeral (TTL) support."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "recipient": {
+                    "type": "string",
+                    "description": "Recipient agent name or CapAuth URI",
+                },
+                "message": {
+                    "type": "string",
+                    "description": "Message content (markdown supported)",
+                },
+                "message_type": {
+                    "type": "string",
+                    "enum": ["text", "finding", "task", "query", "response"],
+                    "description": "Structured message type (default: text)",
+                },
+                "thread_id": {
+                    "type": "string",
+                    "description": "Optional thread/conversation ID for grouping",
+                },
+            },
+            "required": ["recipient", "message"],
+        },
+    ),
+    Tool(
+        name="chat_history",
+        description=(
+            "Retrieve chat history from SKChat. Returns recent messages "
+            "with sender, content, type, thread, and timestamp. "
+            "Optionally filter by peer or thread."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "peer": {
+                    "type": "string",
+                    "description": "Filter by peer agent name or URI",
+                },
+                "thread_id": {
+                    "type": "string",
+                    "description": "Filter by thread/conversation ID",
+                },
+                "limit": {
+                    "type": "integer",
+                    "description": "Maximum messages to return (default: 20)",
+                },
+            },
+            "required": [],
+        },
+    ),
+]
+
+
+# ── Helpers ──────────────────────────────────────────────────
+
+
+def _get_skchat_identity() -> str:
+    """Resolve the sovereign identity for SKChat operations."""
+    try:
+        from skchat.identity_bridge import get_sovereign_identity  # type: ignore[import]
+        return get_sovereign_identity()
+    except ImportError:
+        from ..runtime import get_runtime
+        home = _home()
+        runtime = get_runtime(home)
+        return f"capauth:{runtime.manifest.name}@local"
+    except Exception:
+        return "capauth:agent@local"
+
+
+def _resolve_recipient(name: str) -> str:
+    """Resolve a short agent name to a CapAuth URI if needed."""
+    if ":" in name:
+        return name
+    try:
+        from skchat.identity_bridge import resolve_peer_name  # type: ignore[import]
+        return resolve_peer_name(name)
+    except Exception:
+        return f"capauth:{name}@local"
+
+
+# ── Handlers ─────────────────────────────────────────────────
+
+
+async def _handle_chat_send(args: dict) -> list[TextContent]:
+    """Send a chat message via SKChat AgentMessenger."""
+    try:
+        from skchat.agent_comm import AgentMessenger  # type: ignore[import]
+    except ImportError:
+        return _error_response("skchat not installed. Run: pip install skchat")
+
+    recipient = args.get("recipient", "")
+    message = args.get("message", "")
+    if not recipient or not message:
+        return _error_response("recipient and message are required")
+
+    recipient_uri = _resolve_recipient(recipient)
+    identity = _get_skchat_identity()
+
+    messenger = AgentMessenger.from_identity(identity=identity)
+    result = messenger.send(
+        recipient=recipient_uri,
+        content=message,
+        message_type=args.get("message_type", "text"),
+        thread_id=args.get("thread_id"),
+    )
+
+    return _json_response({
+        "sent": True,
+        "message_id": result.get("message_id"),
+        "recipient": recipient_uri,
+        "delivered": result.get("delivered", False),
+        "transport": result.get("transport"),
+        "error": result.get("error"),
+    })
+
+
+async def _handle_chat_history(args: dict) -> list[TextContent]:
+    """Retrieve chat history from SKChat."""
+    try:
+        from skchat.history import ChatHistory  # type: ignore[import]
+    except ImportError:
+        return _error_response("skchat not installed. Run: pip install skchat")
+
+    limit = args.get("limit", 20)
+    peer = args.get("peer")
+    thread_id = args.get("thread_id")
+
+    try:
+        history = ChatHistory.from_config()
+        messages = history.recent(limit=limit, peer=peer, thread_id=thread_id)
+        return _json_response({
+            "count": len(messages),
+            "messages": [
+                {
+                    "message_id": m.get("message_id") or m.get("id"),
+                    "sender": m.get("sender"),
+                    "recipient": m.get("recipient"),
+                    "content": (m.get("content") or "")[:500],
+                    "message_type": m.get("message_type", "text"),
+                    "thread_id": m.get("thread_id"),
+                    "timestamp": str(m.get("timestamp", "")),
+                }
+                for m in messages
+            ],
+        })
+    except Exception as exc:
+        return _error_response(f"Could not retrieve chat history: {exc}")
+
+
+HANDLERS: dict = {
+    "chat_send": _handle_chat_send,
+    "chat_history": _handle_chat_history,
+}