@softspark/ai-toolkit 4.29.2 → 4.30.2

package/scripts/plugin_schema.py

@@ -9,8 +9,11 @@ Used by both validate.py and plugin.py.
 
 Stdlib-only.
 """
+
 from __future__ import annotations
 
+import json
+import re
 from pathlib import Path
 
 
@@ -28,27 +31,60 @@ REQUIRED_FIELDS = (
 VALID_STATUSES = frozenset({"stable", "experimental", "deprecated"})
 
 # Valid plugin types
-VALID_TYPES = frozenset({
-    "behavioral",
-    "language",
-    "domain",
-    "integration",
-    "plugin-pack",
-    "policy-pack",
-    "hook-pack",
-})
+VALID_TYPES = frozenset(
+    {
+        "behavioral",
+        "language",
+        "domain",
+        "integration",
+        "plugin-pack",
+        "policy-pack",
+        "hook-pack",
+    }
+)
 
 # Valid hook event names (must match validate.py VALID_HOOK_EVENTS)
-VALID_HOOK_EVENTS = frozenset({
-    "SessionStart", "SessionEnd", "UserPromptSubmit", "Notification",
-    "MessageDisplay", "PreToolUse", "PostToolUse", "PostToolUseFailure",
-    "PostToolBatch", "Stop", "StopFailure", "UserPromptExpansion",
-    "SubagentStart", "SubagentStop", "PreCompact", "PostCompact",
-    "PermissionRequest", "PermissionDenied", "Elicitation", "ElicitationResult",
-    "TaskCreated", "TaskCompleted", "TeammateIdle", "WorktreeCreate",
-    "WorktreeRemove", "CwdChanged", "FileChanged", "ConfigChange",
-    "DirectoryAdded", "Setup", "InstructionsLoaded",
-})
+VALID_HOOK_EVENTS = frozenset(
+    {
+        "SessionStart",
+        "SessionEnd",
+        "UserPromptSubmit",
+        "Notification",
+        "MessageDisplay",
+        "PreToolUse",
+        "PostToolUse",
+        "PostToolUseFailure",
+        "PostToolBatch",
+        "Stop",
+        "StopFailure",
+        "UserPromptExpansion",
+        "SubagentStart",
+        "SubagentStop",
+        "PreCompact",
+        "PostCompact",
+        "PermissionRequest",
+        "PermissionDenied",
+        "Elicitation",
+        "ElicitationResult",
+        "TaskCreated",
+        "TaskCompleted",
+        "TeammateIdle",
+        "WorktreeCreate",
+        "WorktreeRemove",
+        "CwdChanged",
+        "FileChanged",
+        "ConfigChange",
+        "DirectoryAdded",
+        "Setup",
+        "InstructionsLoaded",
+    }
+)
+
+MCP_REFERENCE_PATTERN = re.compile(r"[a-z0-9][a-z0-9-]*")
+LOCAL_ENDPOINT_MARKERS = ("localhost", "127.0.0.1", "[::1]")
+BUILTIN_MCP_TEMPLATES_DIR = (
+    Path(__file__).resolve().parent.parent / "app" / "mcp-templates"
+)
 
 
 def _validate_requires(data: dict) -> list[str]:
@@ -81,11 +117,18 @@ def validate_manifest(data: dict, pack_dir: Path | None = None) -> list[str]:
         if field not in data or not data[field]:
             errors.append(f"Missing required field: {field}")
     errors.extend(_validate_requires(data))
+    name = data.get("name")
+    if name and (
+        not isinstance(name, str) or MCP_REFERENCE_PATTERN.fullmatch(name) is None
+    ):
+        errors.append("name must be a safe lowercase-hyphen identifier")
 
     # Validate status
     status = data.get("status", "")
     if status and status not in VALID_STATUSES:
-        errors.append(f"Invalid status '{status}' (valid: {', '.join(sorted(VALID_STATUSES))})")
+        errors.append(
+            f"Invalid status '{status}' (valid: {', '.join(sorted(VALID_STATUSES))})"
+        )
 
     # Validate type
     plugin_type = data.get("type", "")
@@ -101,20 +144,41 @@ def validate_manifest(data: dict, pack_dir: Path | None = None) -> list[str]:
     elif not isinstance(includes, dict):
         errors.append("'includes' must be a dictionary")
     else:
-        for key in ("agents", "skills", "rules", "hooks"):
+        for key in ("agents", "skills", "rules", "hooks", "mcp"):
             val = includes.get(key, [])
             if not isinstance(val, list):
                 errors.append(f"includes.{key} must be a list")
 
+        mcp_references = includes.get("mcp", [])
+        if isinstance(mcp_references, list):
+            invalid_mcp_name = False
+            for reference in mcp_references:
+                if (
+                    not isinstance(reference, str)
+                    or MCP_REFERENCE_PATTERN.fullmatch(reference) is None
+                ):
+                    invalid_mcp_name = True
+                    continue
+                if pack_dir is not None:
+                    errors.extend(_validate_mcp_reference(reference, pack_dir))
+            if invalid_mcp_name:
+                errors.append(
+                    "includes.mcp entries must be safe lowercase-hyphen names"
+                )
+
     # Validate hook_events if present
     hook_events = data.get("hook_events", {})
     if hook_events:
         if not isinstance(hook_events, dict):
-            errors.append("'hook_events' must be a dictionary mapping hook filenames to event names")
+            errors.append(
+                "'hook_events' must be a dictionary mapping hook filenames to event names"
+            )
         else:
             for hook_file, event in hook_events.items():
                 if event not in VALID_HOOK_EVENTS:
-                    errors.append(f"hook_events['{hook_file}']: invalid event '{event}'")
+                    errors.append(
+                        f"hook_events['{hook_file}']: invalid event '{event}'"
+                    )
 
     # Validate hook files exist (if pack_dir provided)
     # Hooks can come from the plugin's own hooks/ dir OR from core app/hooks/
@@ -136,6 +200,58 @@ def validate_manifest(data: dict, pack_dir: Path | None = None) -> list[str]:
     return errors
 
 
+def _validate_mcp_reference(reference: str, pack_dir: Path) -> list[str]:
+    candidates = (
+        pack_dir / "mcp" / f"{reference}.json",
+        BUILTIN_MCP_TEMPLATES_DIR / f"{reference}.json",
+    )
+    template_path = next((path for path in candidates if path.is_file()), None)
+    if template_path is None:
+        return [f"MCP template not found: {reference}"]
+    if template_path.is_symlink():
+        return [f"MCP template must not be symlinked: {reference}"]
+    try:
+        template = json.loads(template_path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return [f"Invalid MCP template JSON: {reference}"]
+    if not isinstance(template, dict) or template.get("name") != reference:
+        return [f"MCP template name mismatch: {reference}"]
+    servers = template.get("mcpServers")
+    if not isinstance(servers, dict) or not servers:
+        return [f"MCP template requires non-empty mcpServers: {reference}"]
+    if not all(_is_valid_mcp_server(name, server) for name, server in servers.items()):
+        return [f"MCP template has invalid server entries: {reference}"]
+    local_remote = any(
+        isinstance(server.get("url"), str)
+        and any(marker in server["url"].lower() for marker in LOCAL_ENDPOINT_MARKERS)
+        for server in servers.values()
+    )
+    warning = template.get("postInstall", "")
+    if local_remote and (
+        not isinstance(warning, str) or "unauthenticated" not in warning.lower()
+    ):
+        return [
+            "Local HTTP MCP template must warn that access is unauthenticated: "
+            f"{reference}"
+        ]
+    return []
+
+
+def _is_valid_mcp_server(name: object, server: object) -> bool:
+    if (
+        not isinstance(name, str)
+        or MCP_REFERENCE_PATTERN.fullmatch(name) is None
+        or not isinstance(server, dict)
+    ):
+        return False
+    transports = [key for key in ("command", "url") if key in server]
+    return (
+        len(transports) == 1
+        and isinstance(server[transports[0]], str)
+        and bool(server[transports[0]].strip())
+    )
+
+
 def validate_references(
     data: dict,
     agents_dir: Path,

package/scripts/uninstall.py

@@ -37,6 +37,11 @@ from typing import Any
 
 sys.path.insert(0, str(Path(__file__).resolve().parent))
 from _common import app_dir, toolkit_dir
+from codex_skill_adapter import (
+    ADAPTED_MARKERS,
+    SKILL_SURFACE_OWNERS_MARKER,
+    skill_surface_owners,
+)
 from injection import strip_all_sections, strip_section, trim_trailing_blanks
 # Retirement cleanup for the v4.16.x tool-output filter. The runtime package
 # that wrote those files is gone; output_filter_retirement re-states its
@@ -51,7 +56,6 @@ from output_filter_retirement import (
 
 
 CODEX_AGENT_MARKER = "# ai-toolkit-managed: codex-agent"
-CODEX_ADAPTED_SKILL_MARKER = ".ai-toolkit-codex-adapted"
 CODEX_HOOK_ASSET_MARKER = "# ai-toolkit-managed: codex-hook-script"
 COPILOT_MARKER = "<!-- ai-toolkit-managed: github-copilot -->"
 COPILOT_SKILL_MANIFEST = ".ai-toolkit-managed-files"
@@ -712,8 +716,11 @@ def _is_codex_agent(path: Path) -> bool:
 def _is_codex_skill(path: Path) -> bool:
     if path.is_symlink():
         return _is_toolkit_link(path)
-    marker = path / CODEX_ADAPTED_SKILL_MARKER
-    return path.is_dir() and not marker.is_symlink() and marker.is_file()
+    return path.is_dir() and any(
+        not (path / marker_name).is_symlink()
+        and (path / marker_name).is_file()
+        for marker_name in ADAPTED_MARKERS
+    )
 
 
 def _remove_codex_skills(skills_root: Path, trusted_root: Path) -> int:
@@ -729,7 +736,7 @@ def _remove_codex_skills(skills_root: Path, trusted_root: Path) -> int:
         if not _is_codex_skill(skill):
             continue
         for child in sorted(skill.iterdir()):
-            if child.name in {"SKILL.md", CODEX_ADAPTED_SKILL_MARKER}:
+            if child.name in {"SKILL.md", *ADAPTED_MARKERS}:
                 if not child.is_symlink() and child.is_file():
                     _safe_unlink(child, trusted_root)
                 continue
@@ -741,6 +748,25 @@ def _remove_codex_skills(skills_root: Path, trusted_root: Path) -> int:
     return removed
 
 
+def _remove_skill_surface_owners_marker(
+    skills_root: Path,
+    trusted_root: Path,
+) -> bool:
+    """Remove a valid owner marker after every managed skill is gone."""
+    marker = skills_root.parent / SKILL_SURFACE_OWNERS_MARKER
+    owners = skill_surface_owners(skills_root)
+    if not owners:
+        return False
+    if skills_root.is_dir() and any(
+        _is_codex_skill(skill) for skill in skills_root.iterdir()
+    ):
+        return False
+    if skill_surface_owners(skills_root) != owners:
+        raise RuntimeError(f"Skill surface ownership changed before removal: {marker}")
+    _safe_unlink(marker, trusted_root)
+    return True
+
+
 def _is_codex_core_handler(handler: Any, group: dict[str, Any]) -> bool:
     if group.get("_source") == "ai-toolkit":
         return True
@@ -838,6 +864,13 @@ def _discover_codex(surface: CodexSurface) -> list[tuple[str, str]]:
         count = sum(1 for path in surface.skills_root.iterdir() if _is_codex_skill(path))
         if count:
             found.append((f"Managed: {surface.skills_root} ({count} Codex skills)", "codex-skills"))
+    owners = skill_surface_owners(surface.skills_root)
+    if owners:
+        marker = surface.skills_root.parent / SKILL_SURFACE_OWNERS_MARKER
+        found.append((
+            f"Managed: {marker} ({', '.join(sorted(owners))})",
+            "agent-skill-owners",
+        ))
     hooks_path = surface.config_root / "hooks.json"
     data = _load_json(hooks_path, "Codex hooks file")
     if data is not None:
@@ -883,6 +916,11 @@ def _remove_codex(surface: CodexSurface) -> None:
     )
     if removed_skills:
         print(f"  Removed: {removed_skills} managed Codex skill(s)")
+    if _remove_skill_surface_owners_marker(
+        surface.skills_root,
+        skills_boundary,
+    ):
+        print("  Removed: managed agent-skill owner marker")
     removed_hooks = _remove_codex_hooks(
         surface.config_root / "hooks.json",
         config_boundary,
@@ -1286,6 +1324,11 @@ def _transaction_specs(
             (surface.config_root / "hooks.json", False, config_boundary),
             (surface.assets_root, True, config_boundary),
             (surface.skills_root.parent, False, skills_boundary),
+            (
+                surface.skills_root.parent / SKILL_SURFACE_OWNERS_MARKER,
+                False,
+                skills_boundary,
+            ),
             (surface.skills_root, True, skills_boundary),
         ):
             add(path, recursive, trusted_root)