@smilintux/skcapstone 0.1.0 → 0.2.3

package/src/skcapstone/mcp_tools/health_tools.py

@@ -0,0 +1,44 @@
+"""Service health check MCP tools."""
+
+from __future__ import annotations
+
+from mcp.types import TextContent, Tool
+
+from ._helpers import _json_response
+
+TOOLS: list[Tool] = [
+    Tool(
+        name="service_health",
+        description=(
+            "Check the health of all services in the sovereign stack. "
+            "Pings SKVector (Qdrant), SKGraph (FalkorDB), Syncthing, "
+            "skcapstone daemon, and skchat daemon. Returns status, "
+            "latency, version, and error details for each service."
+        ),
+        inputSchema={"type": "object", "properties": {}, "required": []},
+    ),
+]
+
+
+async def _handle_service_health(_args: dict) -> list[TextContent]:
+    """Run health checks against all known services."""
+    from ..service_health import check_all_services
+
+    results = check_all_services()
+    up = sum(1 for r in results if r["status"] == "up")
+    down = sum(1 for r in results if r["status"] == "down")
+
+    return _json_response({
+        "summary": {
+            "total": len(results),
+            "up": up,
+            "down": down,
+            "unknown": len(results) - up - down,
+        },
+        "services": results,
+    })
+
+
+HANDLERS: dict = {
+    "service_health": _handle_service_health,
+}

package/src/skcapstone/mcp_tools/heartbeat_tools.py

@@ -0,0 +1,195 @@
+"""Heartbeat beacon and peer discovery 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="heartbeat_pulse",
+        description=(
+            "Publish a heartbeat beacon for this agent. "
+            "Writes the agent's current state, capacity, and capabilities "
+            "to the shared heartbeats directory so peers can discover it."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "status": {
+                    "type": "string",
+                    "description": "Agent status: alive, busy, draining, offline (default: alive)",
+                },
+                "claimed_tasks": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": "Currently claimed task IDs",
+                },
+                "loaded_model": {
+                    "type": "string",
+                    "description": "Currently loaded AI model name",
+                },
+            },
+            "required": [],
+        },
+    ),
+    Tool(
+        name="heartbeat_peers",
+        description=(
+            "Discover all peers in the agent mesh from heartbeat files. "
+            "Returns name, status, alive/stale, capabilities, and age "
+            "for each peer. Stale heartbeats (past TTL) are marked offline."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "include_self": {
+                    "type": "boolean",
+                    "description": "Include own heartbeat (default: false)",
+                },
+            },
+            "required": [],
+        },
+    ),
+    Tool(
+        name="heartbeat_health",
+        description=(
+            "Get overall mesh health summary: total peers, alive/offline "
+            "counts, aggregated capabilities across all live nodes."
+        ),
+        inputSchema={"type": "object", "properties": {}, "required": []},
+    ),
+    Tool(
+        name="heartbeat_find_capable",
+        description=(
+            "Find alive peers with a specific capability. "
+            "Use this to locate agents that can perform a task."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "capability": {
+                    "type": "string",
+                    "description": "The capability name to search for",
+                },
+            },
+            "required": ["capability"],
+        },
+    ),
+]
+
+
+async def _handle_heartbeat_pulse(args: dict) -> list[TextContent]:
+    """Publish a heartbeat beacon."""
+    from ..heartbeat import HeartbeatBeacon
+
+    home = _home()
+    agent_name = _get_agent_name(home)
+    shared = _shared_root()
+    beacon = HeartbeatBeacon(home, agent_name=agent_name,
+                             heartbeats_dir=shared / "heartbeats")
+    beacon.initialize()
+
+    hb = beacon.pulse(
+        status=args.get("status", "alive"),
+        claimed_tasks=args.get("claimed_tasks"),
+        loaded_model=args.get("loaded_model", ""),
+    )
+    return _json_response({
+        "agent_name": hb.agent_name,
+        "status": hb.status,
+        "hostname": hb.hostname,
+        "platform": hb.platform,
+        "ttl_seconds": hb.ttl_seconds,
+        "uptime_hours": hb.uptime_hours,
+        "capabilities": [c.name for c in hb.capabilities],
+        "fingerprint": hb.fingerprint,
+        "capacity": {
+            "cpu_count": hb.capacity.cpu_count,
+            "memory_total_mb": hb.capacity.memory_total_mb,
+            "disk_free_gb": hb.capacity.disk_free_gb,
+            "gpu_available": hb.capacity.gpu_available,
+        },
+    })
+
+
+async def _handle_heartbeat_peers(args: dict) -> list[TextContent]:
+    """Discover peers in the mesh."""
+    from ..heartbeat import HeartbeatBeacon
+
+    home = _home()
+    agent_name = _get_agent_name(home)
+    shared = _shared_root()
+    beacon = HeartbeatBeacon(home, agent_name=agent_name,
+                             heartbeats_dir=shared / "heartbeats")
+    beacon.initialize()
+
+    peers = beacon.discover_peers(include_self=args.get("include_self", False))
+    return _json_response([
+        {
+            "agent_name": p.agent_name,
+            "status": p.status,
+            "alive": p.alive,
+            "age_seconds": p.age_seconds,
+            "hostname": p.hostname,
+            "capabilities": p.capabilities,
+            "claimed_tasks": p.claimed_tasks,
+        }
+        for p in peers
+    ])
+
+
+async def _handle_heartbeat_health(_args: dict) -> list[TextContent]:
+    """Get mesh health summary."""
+    from ..heartbeat import HeartbeatBeacon
+
+    home = _home()
+    agent_name = _get_agent_name(home)
+    shared = _shared_root()
+    beacon = HeartbeatBeacon(home, agent_name=agent_name,
+                             heartbeats_dir=shared / "heartbeats")
+    beacon.initialize()
+
+    health = beacon.mesh_health()
+    return _json_response({
+        "total_peers": health.total_peers,
+        "alive_peers": health.alive_peers,
+        "offline_peers": health.offline_peers,
+        "busy_peers": health.busy_peers,
+        "total_capabilities": health.total_capabilities,
+        "peers": [
+            {"agent_name": p.agent_name, "status": p.status, "alive": p.alive}
+            for p in health.peers
+        ],
+    })
+
+
+async def _handle_heartbeat_find_capable(args: dict) -> list[TextContent]:
+    """Find peers with a specific capability."""
+    from ..heartbeat import HeartbeatBeacon
+
+    home = _home()
+    agent_name = _get_agent_name(home)
+    shared = _shared_root()
+    beacon = HeartbeatBeacon(home, agent_name=agent_name,
+                             heartbeats_dir=shared / "heartbeats")
+    beacon.initialize()
+
+    capability = args["capability"]
+    peers = beacon.find_capable(capability)
+    return _json_response({
+        "capability": capability,
+        "peers": [
+            {"agent_name": p.agent_name, "status": p.status, "capabilities": p.capabilities}
+            for p in peers
+        ],
+    })
+
+
+HANDLERS: dict = {
+    "heartbeat_pulse": _handle_heartbeat_pulse,
+    "heartbeat_peers": _handle_heartbeat_peers,
+    "heartbeat_health": _handle_heartbeat_health,
+    "heartbeat_find_capable": _handle_heartbeat_find_capable,
+}

package/src/skcapstone/mcp_tools/kms_tools.py

@@ -0,0 +1,123 @@
+"""KMS (Key Management Service) tools."""
+
+from __future__ import annotations
+
+from mcp.types import TextContent, Tool
+
+from ._helpers import _home, _json_response
+
+TOOLS: list[Tool] = [
+    Tool(
+        name="kms_status",
+        description=(
+            "Get KMS (Key Management Service) status: master key state, "
+            "total keys, active/revoked counts, service key inventory."
+        ),
+        inputSchema={"type": "object", "properties": {}, "required": []},
+    ),
+    Tool(
+        name="kms_list_keys",
+        description=(
+            "List all keys in the KMS. Shows key ID, type, status, "
+            "label, creation date, and rotation count."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "key_type": {
+                    "type": "string",
+                    "description": "Filter by type: master, service, team, sub (omit for all)",
+                },
+                "include_revoked": {
+                    "type": "boolean",
+                    "description": "Include revoked keys (default: false)",
+                },
+            },
+            "required": [],
+        },
+    ),
+    Tool(
+        name="kms_rotate",
+        description=(
+            "Rotate a KMS key. Generates a new version of the key "
+            "and marks the old version as rotated. The old key material "
+            "remains available for decryption."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "key_id": {
+                    "type": "string",
+                    "description": "The key ID to rotate",
+                },
+                "reason": {
+                    "type": "string",
+                    "description": "Reason for rotation (default: 'scheduled')",
+                },
+            },
+            "required": ["key_id"],
+        },
+    ),
+]
+
+
+async def _handle_kms_status(_args: dict) -> list[TextContent]:
+    """Get KMS status."""
+    from ..kms import KeyStore
+
+    home = _home()
+    store = KeyStore(home)
+    store.initialize()
+    return _json_response(store.status())
+
+
+async def _handle_kms_list_keys(args: dict) -> list[TextContent]:
+    """List all KMS keys."""
+    from ..kms import KeyStore
+
+    home = _home()
+    store = KeyStore(home)
+    store.initialize()
+
+    key_type = args.get("key_type")
+    include_inactive = args.get("include_revoked", False)
+    keys = store.list_keys(key_type=key_type, include_inactive=include_inactive)
+    return _json_response([
+        {
+            "key_id": k.key_id,
+            "key_type": k.key_type,
+            "status": k.status,
+            "label": k.label,
+            "created_at": str(k.created_at),
+            "version": k.version,
+            "algorithm": k.algorithm,
+        }
+        for k in keys
+    ])
+
+
+async def _handle_kms_rotate(args: dict) -> list[TextContent]:
+    """Rotate a KMS key."""
+    from ..kms import KeyStore
+
+    home = _home()
+    store = KeyStore(home)
+    store.initialize()
+
+    new_key = store.rotate_key(
+        key_id=args["key_id"],
+        reason=args.get("reason", "scheduled"),
+    )
+    return _json_response({
+        "key_id": new_key.key_id,
+        "version": new_key.version,
+        "status": new_key.status,
+        "message": f"Key rotated to version {new_key.version}",
+    })
+
+
+HANDLERS: dict = {
+    "kms_status": _handle_kms_status,
+    "kms_list_keys": _handle_kms_list_keys,
+    "kms_rotate": _handle_kms_rotate,
+}

package/src/skcapstone/mcp_tools/memory_tools.py

@@ -0,0 +1,222 @@
+"""Memory store, search, recall, and curation tools."""
+
+from __future__ import annotations
+
+from mcp.types import TextContent, Tool
+
+from ._helpers import _error_response, _home, _json_response
+
+TOOLS: list[Tool] = [
+    Tool(
+        name="memory_store",
+        description=(
+            "Store a new memory in the agent's persistent memory. "
+            "Memories start in short-term and promote based on "
+            "access patterns and importance."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "content": {
+                    "type": "string",
+                    "description": "The memory content (free-text)",
+                },
+                "tags": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": "Tags for categorization",
+                },
+                "importance": {
+                    "type": "number",
+                    "description": "Importance score 0.0-1.0 (>= 0.7 auto-promotes to mid-term)",
+                },
+                "source": {
+                    "type": "string",
+                    "description": "Where this memory came from (default: mcp)",
+                },
+            },
+            "required": ["content"],
+        },
+    ),
+    Tool(
+        name="memory_search",
+        description=(
+            "Search the agent's memories by query string. "
+            "Full-text search across all layers, ranked by relevance."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "query": {
+                    "type": "string",
+                    "description": "Search query",
+                },
+                "limit": {
+                    "type": "integer",
+                    "description": "Max results (default: 10)",
+                },
+                "tags": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": "Filter by tags (all must match)",
+                },
+            },
+            "required": ["query"],
+        },
+    ),
+    Tool(
+        name="memory_recall",
+        description=(
+            "Recall a specific memory by its ID. Returns full content "
+            "and increments the access counter (frequent access promotes memories)."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "memory_id": {
+                    "type": "string",
+                    "description": "The memory's unique ID",
+                },
+            },
+            "required": ["memory_id"],
+        },
+    ),
+    Tool(
+        name="memory_curate",
+        description=(
+            "Run a curation pass over the agent's memories. "
+            "Auto-tags untagged memories, promotes qualifying "
+            "memories to higher tiers, and removes duplicates. "
+            "Use dry_run=true to preview without changes."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "dry_run": {
+                    "type": "boolean",
+                    "description": "Preview changes without applying (default: false)",
+                },
+                "stats_only": {
+                    "type": "boolean",
+                    "description": "Return statistics instead of curating (default: false)",
+                },
+            },
+            "required": [],
+        },
+    ),
+]
+
+
+async def _handle_memory_store(args: dict) -> list[TextContent]:
+    """Store a new memory."""
+    from ..memory_engine import store
+
+    content = args.get("content", "")
+    if not content:
+        return _error_response("content is required")
+
+    entry = store(
+        home=_home(),
+        content=content,
+        tags=args.get("tags", []),
+        source=args.get("source", "mcp"),
+        importance=args.get("importance", 0.5),
+    )
+    try:
+        from .. import activity
+        activity.push("memory.stored", {
+            "memory_id": entry.memory_id,
+            "layer": entry.layer.value,
+            "importance": entry.importance,
+            "tags": entry.tags,
+        })
+    except Exception:
+        pass
+    return _json_response({
+        "memory_id": entry.memory_id,
+        "layer": entry.layer.value,
+        "importance": entry.importance,
+        "tags": entry.tags,
+        "stored": True,
+    })
+
+
+async def _handle_memory_search(args: dict) -> list[TextContent]:
+    """Search memories by query."""
+    from ..memory_engine import search
+
+    query = args.get("query", "")
+    if not query:
+        return _error_response("query is required")
+
+    results = search(
+        home=_home(),
+        query=query,
+        tags=args.get("tags"),
+        limit=args.get("limit", 10),
+    )
+    return _json_response([
+        {
+            "memory_id": e.memory_id,
+            "layer": e.layer.value,
+            "content": e.content[:300],
+            "tags": e.tags,
+            "importance": e.importance,
+            "access_count": e.access_count,
+        }
+        for e in results
+    ])
+
+
+async def _handle_memory_recall(args: dict) -> list[TextContent]:
+    """Recall a specific memory by ID."""
+    from ..memory_engine import recall
+
+    memory_id = args.get("memory_id", "")
+    if not memory_id:
+        return _error_response("memory_id is required")
+
+    entry = recall(home=_home(), memory_id=memory_id)
+    if entry is None:
+        return _error_response(f"Memory not found: {memory_id}")
+
+    return _json_response({
+        "memory_id": entry.memory_id,
+        "content": entry.content,
+        "layer": entry.layer.value,
+        "tags": entry.tags,
+        "importance": entry.importance,
+        "access_count": entry.access_count,
+        "source": entry.source,
+        "created_at": entry.created_at.isoformat() if entry.created_at else None,
+    })
+
+
+async def _handle_memory_curate(args: dict) -> list[TextContent]:
+    """Run a memory curation pass or return stats."""
+    from ..memory_curator import MemoryCurator
+
+    home = _home()
+    curator = MemoryCurator(home)
+
+    if args.get("stats_only"):
+        return _json_response(curator.get_stats())
+
+    dry_run = args.get("dry_run", False)
+    result = curator.curate(dry_run=dry_run)
+    return _json_response({
+        "dry_run": dry_run,
+        "scanned": result.total_scanned,
+        "tagged": len(result.tagged),
+        "promoted": len(result.promoted),
+        "deduped": len(result.deduped),
+        "by_layer": result.by_layer,
+    })
+
+
+HANDLERS: dict = {
+    "memory_store": _handle_memory_store,
+    "memory_search": _handle_memory_search,
+    "memory_recall": _handle_memory_recall,
+    "memory_curate": _handle_memory_curate,
+}

package/src/skcapstone/mcp_tools/model_tools.py

@@ -0,0 +1,75 @@
+"""Model router tool."""
+
+from __future__ import annotations
+
+from mcp.types import TextContent, Tool
+
+from ._helpers import _json_response
+
+TOOLS: list[Tool] = [
+    Tool(
+        name="model_route",
+        description=(
+            "Route a task to the optimal model tier and concrete model name. "
+            "Accepts a task description, optional tags, privacy/localhost flags, "
+            "and token estimate. Returns the selected tier (fast/code/reason/"
+            "nuance/local), model name, and reasoning. Use this to automatically "
+            "select the best model for any task based on complexity, type, and "
+            "constraints."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "description": {
+                    "type": "string",
+                    "description": "What the task is about",
+                },
+                "tags": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": (
+                        "Classification tags (e.g. ['code', 'refactor']). "
+                        "Used for rule-based tier matching."
+                    ),
+                },
+                "requires_localhost": {
+                    "type": "boolean",
+                    "description": "Force LOCAL tier on originating node (default: false)",
+                },
+                "privacy_sensitive": {
+                    "type": "boolean",
+                    "description": "Force LOCAL tier \u2014 data never leaves node (default: false)",
+                },
+                "estimated_tokens": {
+                    "type": "integer",
+                    "description": (
+                        "Rough token budget hint. Tasks > 16000 tokens "
+                        "default to REASON tier when no tag rule matches."
+                    ),
+                },
+            },
+            "required": ["description"],
+        },
+    ),
+]
+
+
+async def _handle_model_route(args: dict) -> list[TextContent]:
+    """Route a task to the optimal model tier and name."""
+    from ..model_router import ModelRouter, TaskSignal
+
+    signal = TaskSignal(
+        description=args.get("description", ""),
+        tags=args.get("tags", []),
+        requires_localhost=args.get("requires_localhost", False),
+        privacy_sensitive=args.get("privacy_sensitive", False),
+        estimated_tokens=args.get("estimated_tokens", 0),
+    )
+    router = ModelRouter()
+    decision = router.route(signal)
+    return _json_response(decision.model_dump())
+
+
+HANDLERS: dict = {
+    "model_route": _handle_model_route,
+}