@smilintux/skcapstone 0.4.6 → 0.5.0

package/src/skcapstone/mcp_server.py

@@ -55,6 +55,16 @@ Tools:
     kms_list_keys   — List all KMS keys
     kms_rotate      — Rotate a KMS key
     model_route     — Route task to optimal model tier/name
+    itil_incident_create — Create ITIL incident
+    itil_incident_update — Update incident status/severity
+    itil_incident_list   — List/filter incidents
+    itil_problem_create  — Create problem record
+    itil_problem_update  — Update problem/root cause
+    itil_change_propose  — Propose change (RFC)
+    itil_change_update   — Update change status
+    itil_cab_vote        — Submit CAB vote
+    itil_status          — ITIL dashboard
+    itil_kedb_search     — Search Known Error Database
 
 Invocation (all equivalent):
     skcapstone mcp serve                     # CLI entry point
@@ -132,8 +142,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"
 
 
@@ -2470,6 +2480,213 @@ async def list_tools() -> list[Tool]:
                 "required": ["name"],
             },
         ),
+        # ── ITIL Service Management ─────────────────────────────
+        Tool(
+            name="itil_incident_create",
+            description=(
+                "Create a new ITIL incident for a service disruption. "
+                "Auto-creates a linked GTD item (next-action for sev1/sev2, inbox for sev3/sev4)."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "title": {"type": "string", "description": "Brief description of the incident"},
+                    "severity": {"type": "string", "enum": ["sev1", "sev2", "sev3", "sev4"], "description": "Severity level (default: sev3)"},
+                    "source": {"type": "string", "enum": ["service_health", "dreaming", "manual", "daemon_error", "heartbeat"], "description": "Detection source (default: manual)"},
+                    "affected_services": {"type": "array", "items": {"type": "string"}, "description": "List of affected service names"},
+                    "impact": {"type": "string", "description": "Business impact description"},
+                    "managed_by": {"type": "string", "description": "Agent responsible for managing this incident"},
+                    "tags": {"type": "array", "items": {"type": "string"}, "description": "Tags for categorization"},
+                },
+                "required": ["title"],
+            },
+        ),
+        Tool(
+            name="itil_incident_update",
+            description=(
+                "Update an incident: transition status, escalate severity, "
+                "add timeline notes, or resolve. Valid status transitions: "
+                "detected->acknowledged->investigating->resolved->closed."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "incident_id": {"type": "string", "description": "Incident ID (e.g. inc-a1b2c3d4)"},
+                    "agent": {"type": "string", "description": "Agent making the update"},
+                    "new_status": {"type": "string", "enum": ["acknowledged", "investigating", "escalated", "resolved", "closed"], "description": "New status"},
+                    "severity": {"type": "string", "enum": ["sev1", "sev2", "sev3", "sev4"], "description": "New severity"},
+                    "note": {"type": "string", "description": "Timeline note"},
+                    "resolution_summary": {"type": "string", "description": "Resolution summary (when resolving)"},
+                    "related_problem_id": {"type": "string", "description": "Link to a related problem record"},
+                },
+                "required": ["incident_id", "agent"],
+            },
+        ),
+        Tool(
+            name="itil_incident_list",
+            description="List ITIL incidents filtered by status, severity, or affected service.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "status": {"type": "string", "enum": ["detected", "acknowledged", "investigating", "escalated", "resolved", "closed"], "description": "Filter by status"},
+                    "severity": {"type": "string", "enum": ["sev1", "sev2", "sev3", "sev4"], "description": "Filter by severity"},
+                    "service": {"type": "string", "description": "Filter by affected service name"},
+                },
+                "required": [],
+            },
+        ),
+        Tool(
+            name="itil_problem_create",
+            description=(
+                "Create a new ITIL problem record to investigate root cause. "
+                "Links to related incidents and auto-creates a GTD project."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "title": {"type": "string", "description": "Problem title"},
+                    "managed_by": {"type": "string", "description": "Agent responsible for investigation"},
+                    "related_incident_ids": {"type": "array", "items": {"type": "string"}, "description": "Related incident IDs"},
+                    "workaround": {"type": "string", "description": "Known workaround if any"},
+                    "tags": {"type": "array", "items": {"type": "string"}, "description": "Tags for categorization"},
+                },
+                "required": ["title"],
+            },
+        ),
+        Tool(
+            name="itil_problem_update",
+            description=(
+                "Update a problem record: transition status, set root cause, "
+                "add workaround, optionally create a KEDB entry. "
+                "Valid transitions: identified->analyzing->known_error->resolved."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "problem_id": {"type": "string", "description": "Problem ID (e.g. prb-e5f6g7h8)"},
+                    "agent": {"type": "string", "description": "Agent making the update"},
+                    "new_status": {"type": "string", "enum": ["analyzing", "known_error", "resolved"], "description": "New status"},
+                    "root_cause": {"type": "string", "description": "Root cause description"},
+                    "workaround": {"type": "string", "description": "Workaround description"},
+                    "note": {"type": "string", "description": "Timeline note"},
+                    "create_kedb": {"type": "boolean", "description": "Create a KEDB entry from this problem"},
+                },
+                "required": ["problem_id", "agent"],
+            },
+        ),
+        Tool(
+            name="itil_change_propose",
+            description=(
+                "Propose a change (RFC). Standard changes auto-approve. "
+                "Normal changes require CAB approval. Emergency changes have a "
+                "15-min timeout before auto-approval."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "title": {"type": "string", "description": "Change title"},
+                    "change_type": {"type": "string", "enum": ["standard", "normal", "emergency"], "description": "Type of change (default: normal)"},
+                    "risk": {"type": "string", "enum": ["low", "medium", "high"], "description": "Risk level (default: medium)"},
+                    "rollback_plan": {"type": "string", "description": "How to roll back if the change fails"},
+                    "test_plan": {"type": "string", "description": "How to verify the change works"},
+                    "managed_by": {"type": "string", "description": "Agent managing the change"},
+                    "implementer": {"type": "string", "description": "Agent who will implement the change"},
+                    "related_problem_id": {"type": "string", "description": "Related problem ID if applicable"},
+                    "tags": {"type": "array", "items": {"type": "string"}, "description": "Tags for categorization"},
+                },
+                "required": ["title"],
+            },
+        ),
+        Tool(
+            name="itil_change_update",
+            description=(
+                "Update a change: transition status (implementing, deployed, "
+                "verified, failed, closed) or add timeline notes."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "change_id": {"type": "string", "description": "Change ID (e.g. chg-i1j2k3l4)"},
+                    "agent": {"type": "string", "description": "Agent making the update"},
+                    "new_status": {"type": "string", "enum": ["reviewing", "approved", "rejected", "implementing", "deployed", "verified", "failed", "closed"], "description": "New status"},
+                    "note": {"type": "string", "description": "Timeline note"},
+                },
+                "required": ["change_id", "agent"],
+            },
+        ),
+        Tool(
+            name="itil_cab_vote",
+            description=(
+                "Submit a CAB (Change Advisory Board) vote for a proposed change. "
+                "Each agent writes its own vote file (conflict-free). "
+                "A human rejection blocks the change; a human approval unblocks it."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "change_id": {"type": "string", "description": "Change ID to vote on"},
+                    "agent": {"type": "string", "description": "Voting agent name"},
+                    "decision": {"type": "string", "enum": ["approved", "rejected", "abstain"], "description": "Vote decision (default: abstain)"},
+                    "conditions": {"type": "string", "description": "Conditions for approval"},
+                },
+                "required": ["change_id", "agent"],
+            },
+        ),
+        Tool(
+            name="itil_status",
+            description=(
+                "ITIL dashboard: open incidents by severity, active problems, "
+                "pending changes, and KEDB count."
+            ),
+            inputSchema={"type": "object", "properties": {}, "required": []},
+        ),
+        Tool(
+            name="itil_kedb_search",
+            description=(
+                "Search the Known Error Database by symptoms, service name, "
+                "or keywords. Returns matching entries with workarounds."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "query": {"type": "string", "description": "Search query (matches title, symptoms, root cause, tags)"},
+                },
+                "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"],
+            },
+        ),
     ]
 
 
@@ -2618,6 +2835,19 @@ async def call_tool(name: str, arguments: dict) -> list[TextContent]:
         # Soul Blueprint Registry
         "soul_registry_search": _handle_soul_registry_search,
         "soul_registry_publish": _handle_soul_registry_publish,
+        # ITIL Service Management
+        "itil_incident_create": _handle_itil_incident_create,
+        "itil_incident_update": _handle_itil_incident_update,
+        "itil_incident_list": _handle_itil_incident_list,
+        "itil_problem_create": _handle_itil_problem_create,
+        "itil_problem_update": _handle_itil_problem_update,
+        "itil_change_propose": _handle_itil_change_propose,
+        "itil_change_update": _handle_itil_change_update,
+        "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:
@@ -2959,8 +3189,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,
@@ -4679,6 +4909,78 @@ async def _handle_soul_registry_publish(args: dict) -> list[TextContent]:
         return _error_response(f"Registry publish failed: {exc}")
 
 
+# ── ITIL handlers ─────────────────────────────────────────
+
+
+async def _handle_itil_incident_create(args: dict) -> list[TextContent]:
+    """Create a new ITIL incident."""
+    from .mcp_tools.itil_tools import _handle_itil_incident_create as _impl
+    return await _impl(args)
+
+
+async def _handle_itil_incident_update(args: dict) -> list[TextContent]:
+    """Update an ITIL incident."""
+    from .mcp_tools.itil_tools import _handle_itil_incident_update as _impl
+    return await _impl(args)
+
+
+async def _handle_itil_incident_list(args: dict) -> list[TextContent]:
+    """List ITIL incidents."""
+    from .mcp_tools.itil_tools import _handle_itil_incident_list as _impl
+    return await _impl(args)
+
+
+async def _handle_itil_problem_create(args: dict) -> list[TextContent]:
+    """Create a new ITIL problem."""
+    from .mcp_tools.itil_tools import _handle_itil_problem_create as _impl
+    return await _impl(args)
+
+
+async def _handle_itil_problem_update(args: dict) -> list[TextContent]:
+    """Update an ITIL problem."""
+    from .mcp_tools.itil_tools import _handle_itil_problem_update as _impl
+    return await _impl(args)
+
+
+async def _handle_itil_change_propose(args: dict) -> list[TextContent]:
+    """Propose a change (RFC)."""
+    from .mcp_tools.itil_tools import _handle_itil_change_propose as _impl
+    return await _impl(args)
+
+
+async def _handle_itil_change_update(args: dict) -> list[TextContent]:
+    """Update a change status."""
+    from .mcp_tools.itil_tools import _handle_itil_change_update as _impl
+    return await _impl(args)
+
+
+async def _handle_itil_cab_vote(args: dict) -> list[TextContent]:
+    """Submit a CAB vote."""
+    from .mcp_tools.itil_tools import _handle_itil_cab_vote as _impl
+    return await _impl(args)
+
+
+async def _handle_itil_status(args: dict) -> list[TextContent]:
+    """ITIL dashboard status."""
+    from .mcp_tools.itil_tools import _handle_itil_status as _impl
+    return await _impl(args)
+
+
+async def _handle_itil_kedb_search(args: dict) -> list[TextContent]:
+    """Search the Known Error Database."""
+    from .mcp_tools.itil_tools import _handle_itil_kedb_search as _impl
+    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,
@@ -29,6 +30,7 @@ from . import (
     gtd_tools,
     health_tools,
     heartbeat_tools,
+    itil_tools,
     kms_tools,
     memory_tools,
     model_tools,
@@ -48,6 +50,7 @@ from . import (
 # Ordered list of all tool-group modules.
 _MODULES = [
     agent_tools,
+    brain_first_tools,
     memory_tools,
     comm_tools,
     sync_tools,
@@ -63,6 +66,7 @@ _MODULES = [
     heartbeat_tools,
     file_tools,
     gtd_tools,
+    itil_tools,
     pubsub_tools,
     fortress_tools,
     promoter_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)
 

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,

package/src/skcapstone/mcp_tools/gtd_tools.py

@@ -21,7 +21,7 @@ _GTD_LISTS = {
     "someday-maybe": "someday-maybe.json",
 }
 
-_VALID_SOURCES = {"manual", "telegram", "email", "voice"}
+_VALID_SOURCES = {"manual", "telegram", "email", "voice", "itil"}
 _VALID_PRIVACY = {"private", "team", "community", "public"}
 _VALID_STATUSES = {"inbox", "next", "project", "waiting", "someday", "reference", "done"}
 _VALID_PRIORITIES = {"critical", "high", "medium", "low"}