@event4u/agent-config 1.9.1

package/scripts/tool_registry.py

@@ -0,0 +1,146 @@
+#!/usr/bin/env python3
+"""
+Tool Registry — manages available external tools and their permissions.
+
+Responsibilities:
+- Define available tools and their supported actions
+- Validate tool declarations from skills
+- Check tool permissions
+- Report on tool usage across skills
+
+Usage:
+    python3 scripts/tool_registry.py [--format text|json]
+    python3 scripts/tool_registry.py --validate-skill SKILL_TOOLS
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from dataclasses import dataclass, asdict
+from pathlib import Path
+from typing import Dict, FrozenSet, List, Optional, Set
+
+
+@dataclass
+class ToolDefinition:
+    """Definition of an available tool."""
+    name: str
+    description: str
+    supported_actions: FrozenSet[str]
+    default_mode: str  # "read-only" or "read-write"
+    requires_auth: bool
+
+
+# --- Built-in tool definitions ---
+TOOL_REGISTRY: Dict[str, ToolDefinition] = {
+    "github": ToolDefinition(
+        name="github",
+        description="GitHub API — PRs, issues, files, commits",
+        supported_actions=frozenset({"read_pr", "read_issue", "create_pr", "list_files", "read_commit"}),
+        default_mode="read-only",
+        requires_auth=True,
+    ),
+    "jira": ToolDefinition(
+        name="jira",
+        description="Jira API — tickets, search, comments",
+        supported_actions=frozenset({"read_ticket", "search_tickets", "add_comment", "transition_ticket"}),
+        default_mode="read-only",
+        requires_auth=True,
+    ),
+}
+
+
+@dataclass
+class ToolValidationResult:
+    """Result of validating tool declarations."""
+    valid: bool
+    errors: List[str]
+    warnings: List[str]
+
+
+def get_tool(name: str) -> Optional[ToolDefinition]:
+    """Look up a tool by name."""
+    return TOOL_REGISTRY.get(name)
+
+
+def list_tools() -> List[ToolDefinition]:
+    """List all registered tools."""
+    return list(TOOL_REGISTRY.values())
+
+
+def validate_tool_declarations(allowed_tools: List[str],
+                                tool_permissions: Optional[Dict] = None) -> ToolValidationResult:
+    """Validate tool declarations from a skill's execution block."""
+    errors: List[str] = []
+    warnings: List[str] = []
+
+    for tool_name in allowed_tools:
+        tool_def = get_tool(tool_name)
+        if tool_def is None:
+            errors.append(f"Tool '{tool_name}' is not registered in the tool registry")
+            continue
+
+        # Check permissions if declared
+        if tool_permissions and tool_name in tool_permissions:
+            perms = tool_permissions[tool_name]
+            actions = perms.get("actions", [])
+            for action in actions:
+                if action not in tool_def.supported_actions:
+                    errors.append(f"Tool '{tool_name}' does not support action '{action}'")
+
+    # Check for tools in permissions but not in allowed_tools
+    if tool_permissions:
+        for tool_name in tool_permissions:
+            if tool_name not in allowed_tools:
+                warnings.append(f"Tool '{tool_name}' has permissions but is not in allowed_tools")
+
+    return ToolValidationResult(
+        valid=len(errors) == 0,
+        errors=errors,
+        warnings=warnings,
+    )
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Tool Registry — manage and validate tools")
+    parser.add_argument("--format", choices=["text", "json"], default="text")
+    parser.add_argument("--validate-tools", nargs="*", help="Tool names to validate")
+    args = parser.parse_args()
+
+    if args.validate_tools is not None:
+        result = validate_tool_declarations(args.validate_tools)
+        if args.format == "json":
+            print(json.dumps(asdict(result), indent=2))
+        else:
+            if result.valid:
+                print(f"✅  All {len(args.validate_tools)} tool declarations are valid")
+            else:
+                for e in result.errors:
+                    print(f"❌  {e}")
+                for w in result.warnings:
+                    print(f"⚠️  {w}")
+        return 0 if result.valid else 1
+
+    # List tools
+    tools = list_tools()
+    if args.format == "json":
+        print(json.dumps([{
+            "name": t.name, "description": t.description,
+            "actions": sorted(t.supported_actions),
+            "default_mode": t.default_mode, "requires_auth": t.requires_auth,
+        } for t in tools], indent=2))
+    else:
+        print(f"Registered tools: {len(tools)}\n")
+        for t in tools:
+            actions = ", ".join(sorted(t.supported_actions))
+            print(f"  {t.name} ({t.default_mode})")
+            print(f"    {t.description}")
+            print(f"    Actions: {actions}")
+            print()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/tools/__init__.py

@@ -0,0 +1 @@
+# Tool adapters package

package/scripts/tools/adapter_errors.py

@@ -0,0 +1,63 @@
+#!/usr/bin/env python3
+"""
+Shared error types for tool adapters.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Optional
+
+
+class AdapterErrorType(str, Enum):
+    """Categorized adapter errors."""
+    AUTH_FAILURE = "auth_failure"
+    NOT_FOUND = "not_found"
+    RATE_LIMIT = "rate_limit"
+    TIMEOUT = "timeout"
+    NETWORK = "network"
+    VALIDATION = "validation"
+    UNKNOWN = "unknown"
+
+
+@dataclass
+class AdapterError:
+    """Structured adapter error."""
+    adapter: str
+    action: str
+    error_type: AdapterErrorType
+    message: str
+    status_code: Optional[int] = None
+    retry_after: Optional[int] = None
+
+    @property
+    def is_retryable(self) -> bool:
+        """Whether this error can be retried."""
+        return self.error_type in (
+            AdapterErrorType.RATE_LIMIT,
+            AdapterErrorType.TIMEOUT,
+            AdapterErrorType.NETWORK,
+        )
+
+
+def classify_http_error(adapter: str, action: str, status_code: int, message: str) -> AdapterError:
+    """Classify an HTTP error into a structured AdapterError."""
+    if status_code == 401 or status_code == 403:
+        error_type = AdapterErrorType.AUTH_FAILURE
+    elif status_code == 404:
+        error_type = AdapterErrorType.NOT_FOUND
+    elif status_code == 429:
+        error_type = AdapterErrorType.RATE_LIMIT
+    elif status_code >= 500:
+        error_type = AdapterErrorType.NETWORK
+    else:
+        error_type = AdapterErrorType.UNKNOWN
+
+    return AdapterError(
+        adapter=adapter,
+        action=action,
+        error_type=error_type,
+        message=message,
+        status_code=status_code,
+    )

package/scripts/tools/base_adapter.py

@@ -0,0 +1,91 @@
+#!/usr/bin/env python3
+"""
+Base Tool Adapter — abstract contract for tool integrations.
+
+All tool adapters must:
+1. Inherit from BaseToolAdapter
+2. Define supported_actions
+3. Implement execute_action
+4. Implement check_auth
+
+No real API calls are made — adapters return structured results.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Any, Dict, FrozenSet, List, Optional
+
+
+@dataclass
+class ToolAction:
+    """Structured representation of a tool action request."""
+    tool_name: str
+    action: str
+    params: Dict[str, Any]
+
+
+@dataclass
+class ToolResult:
+    """Structured result from a tool action."""
+    tool_name: str
+    action: str
+    success: bool
+    data: Optional[Dict[str, Any]] = None
+    error: Optional[str] = None
+
+    def to_dict(self) -> dict:
+        result = {
+            "tool": self.tool_name,
+            "action": self.action,
+            "success": self.success,
+        }
+        if self.data:
+            result["data"] = self.data
+        if self.error:
+            result["error"] = self.error
+        return result
+
+
+class BaseToolAdapter(ABC):
+    """Abstract base for tool adapters."""
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Tool name (must match registry entry)."""
+
+    @property
+    @abstractmethod
+    def supported_actions(self) -> FrozenSet[str]:
+        """Set of supported action names."""
+
+    @abstractmethod
+    def check_auth(self) -> bool:
+        """Check if authentication is available. Does NOT make API calls."""
+
+    @abstractmethod
+    def execute_action(self, action: ToolAction) -> ToolResult:
+        """Execute a tool action. Returns structured result."""
+
+    def validate_action(self, action: ToolAction) -> Optional[str]:
+        """Validate an action before execution. Returns error message or None."""
+        if action.tool_name != self.name:
+            return f"Action tool '{action.tool_name}' does not match adapter '{self.name}'"
+        if action.action not in self.supported_actions:
+            return (f"Action '{action.action}' not supported by '{self.name}'; "
+                    f"valid: {', '.join(sorted(self.supported_actions))}")
+        return None
+
+    def safe_execute(self, action: ToolAction) -> ToolResult:
+        """Validate and execute an action safely."""
+        error = self.validate_action(action)
+        if error:
+            return ToolResult(
+                tool_name=self.name,
+                action=action.action,
+                success=False,
+                error=error,
+            )
+        return self.execute_action(action)

package/scripts/tools/github_adapter.py

@@ -0,0 +1,128 @@
+#!/usr/bin/env python3
+"""
+GitHub Tool Adapter — read-only GitHub API interactions.
+
+Read-only actions use real API calls when GITHUB_TOKEN is available.
+Write actions remain scaffold-only (never auto-executed).
+Falls back to scaffold data when no token is present.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Any, Dict, FrozenSet, Optional
+from urllib.error import HTTPError, URLError
+from urllib.request import Request, urlopen
+
+from tools.base_adapter import BaseToolAdapter, ToolAction, ToolResult
+
+GITHUB_API = "https://api.github.com"
+TIMEOUT_SECONDS = 15
+
+
+class GitHubAdapter(BaseToolAdapter):
+    """Adapter for GitHub API interactions."""
+
+    READ_ACTIONS = frozenset({"read_pr", "read_issue", "list_files", "read_commit"})
+    WRITE_ACTIONS = frozenset({"create_pr"})
+
+    @property
+    def name(self) -> str:
+        return "github"
+
+    @property
+    def supported_actions(self) -> FrozenSet[str]:
+        return self.READ_ACTIONS | self.WRITE_ACTIONS
+
+    def check_auth(self) -> bool:
+        return bool(os.environ.get("GITHUB_TOKEN"))
+
+    @property
+    def _token(self) -> Optional[str]:
+        return os.environ.get("GITHUB_TOKEN")
+
+    def _api_get(self, path: str) -> Dict[str, Any]:
+        """Make an authenticated GET request to the GitHub API."""
+        url = f"{GITHUB_API}/{path.lstrip('/')}"
+        headers = {"Accept": "application/vnd.github+json"}
+        if self._token:
+            headers["Authorization"] = f"Bearer {self._token}"
+        req = Request(url, headers=headers, method="GET")
+        with urlopen(req, timeout=TIMEOUT_SECONDS) as resp:
+            return json.loads(resp.read().decode())
+
+    def execute_action(self, action: ToolAction) -> ToolResult:
+        handler = {
+            "read_pr": self._read_pr,
+            "read_issue": self._read_issue,
+            "list_files": self._list_files,
+            "read_commit": self._read_commit,
+            "create_pr": self._create_pr,
+        }.get(action.action)
+
+        if not handler:
+            return ToolResult(
+                tool_name=self.name, action=action.action,
+                success=False, error=f"Unsupported action: {action.action}",
+            )
+        return handler(action)
+
+    def _read_pr(self, action: ToolAction) -> ToolResult:
+        owner = action.params.get("owner", "")
+        repo = action.params.get("repo", "")
+        number = action.params.get("number", "")
+        if not all([owner, repo, number]) or not self._token:
+            return self._scaffold("read_pr", action)
+        try:
+            data = self._api_get(f"repos/{owner}/{repo}/pulls/{number}")
+            return ToolResult(tool_name=self.name, action="read_pr", success=True, data=data)
+        except (HTTPError, URLError, TimeoutError) as e:
+            return ToolResult(tool_name=self.name, action="read_pr", success=False, error=str(e))
+
+    def _read_issue(self, action: ToolAction) -> ToolResult:
+        owner = action.params.get("owner", "")
+        repo = action.params.get("repo", "")
+        number = action.params.get("number", "")
+        if not all([owner, repo, number]) or not self._token:
+            return self._scaffold("read_issue", action)
+        try:
+            data = self._api_get(f"repos/{owner}/{repo}/issues/{number}")
+            return ToolResult(tool_name=self.name, action="read_issue", success=True, data=data)
+        except (HTTPError, URLError, TimeoutError) as e:
+            return ToolResult(tool_name=self.name, action="read_issue", success=False, error=str(e))
+
+    def _list_files(self, action: ToolAction) -> ToolResult:
+        owner = action.params.get("owner", "")
+        repo = action.params.get("repo", "")
+        number = action.params.get("number", "")
+        if not all([owner, repo, number]) or not self._token:
+            return self._scaffold("list_files", action)
+        try:
+            data = self._api_get(f"repos/{owner}/{repo}/pulls/{number}/files")
+            return ToolResult(tool_name=self.name, action="list_files", success=True, data=data)
+        except (HTTPError, URLError, TimeoutError) as e:
+            return ToolResult(tool_name=self.name, action="list_files", success=False, error=str(e))
+
+    def _read_commit(self, action: ToolAction) -> ToolResult:
+        owner = action.params.get("owner", "")
+        repo = action.params.get("repo", "")
+        sha = action.params.get("sha", "")
+        if not all([owner, repo, sha]) or not self._token:
+            return self._scaffold("read_commit", action)
+        try:
+            data = self._api_get(f"repos/{owner}/{repo}/commits/{sha}")
+            return ToolResult(tool_name=self.name, action="read_commit", success=True, data=data)
+        except (HTTPError, URLError, TimeoutError) as e:
+            return ToolResult(tool_name=self.name, action="read_commit", success=False, error=str(e))
+
+    def _create_pr(self, action: ToolAction) -> ToolResult:
+        """Write action — scaffold only, never auto-executed."""
+        return self._scaffold("create_pr", action)
+
+    def _scaffold(self, action_name: str, action: ToolAction) -> ToolResult:
+        """Return scaffold data when no token or params are missing."""
+        return ToolResult(
+            tool_name=self.name, action=action_name, success=True,
+            data={"scaffold": True, "action": action_name, "params": action.params},
+        )

package/scripts/tools/jira_adapter.py

@@ -0,0 +1,115 @@
+#!/usr/bin/env python3
+"""
+Jira Tool Adapter — read-only Jira API interactions.
+
+Read-only actions use real API calls when JIRA_API_TOKEN + JIRA_BASE_URL are set.
+Write actions remain scaffold-only (never auto-executed).
+Falls back to scaffold data when no credentials are present.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import os
+from typing import Any, Dict, FrozenSet, Optional
+from urllib.error import HTTPError, URLError
+from urllib.request import Request, urlopen
+
+from tools.base_adapter import BaseToolAdapter, ToolAction, ToolResult
+
+TIMEOUT_SECONDS = 15
+
+
+class JiraAdapter(BaseToolAdapter):
+    """Adapter for Jira API interactions."""
+
+    READ_ACTIONS = frozenset({"read_ticket", "search_tickets"})
+    WRITE_ACTIONS = frozenset({"add_comment", "transition_ticket"})
+
+    @property
+    def name(self) -> str:
+        return "jira"
+
+    @property
+    def supported_actions(self) -> FrozenSet[str]:
+        return self.READ_ACTIONS | self.WRITE_ACTIONS
+
+    def check_auth(self) -> bool:
+        return bool(self._token) and bool(self._base_url)
+
+    @property
+    def _token(self) -> Optional[str]:
+        return os.environ.get("JIRA_API_TOKEN")
+
+    @property
+    def _base_url(self) -> Optional[str]:
+        url = os.environ.get("JIRA_BASE_URL", "")
+        return url.rstrip("/") if url else None
+
+    @property
+    def _email(self) -> Optional[str]:
+        return os.environ.get("JIRA_EMAIL")
+
+    def _api_get(self, path: str) -> Dict[str, Any]:
+        """Make an authenticated GET request to the Jira API."""
+        url = f"{self._base_url}/rest/api/3/{path.lstrip('/')}"
+        headers = {"Accept": "application/json"}
+        if self._email and self._token:
+            creds = base64.b64encode(f"{self._email}:{self._token}".encode()).decode()
+            headers["Authorization"] = f"Basic {creds}"
+        elif self._token:
+            headers["Authorization"] = f"Bearer {self._token}"
+        req = Request(url, headers=headers, method="GET")
+        with urlopen(req, timeout=TIMEOUT_SECONDS) as resp:
+            return json.loads(resp.read().decode())
+
+    def execute_action(self, action: ToolAction) -> ToolResult:
+        handler = {
+            "read_ticket": self._read_ticket,
+            "search_tickets": self._search_tickets,
+            "add_comment": self._add_comment,
+            "transition_ticket": self._transition_ticket,
+        }.get(action.action)
+
+        if not handler:
+            return ToolResult(
+                tool_name=self.name, action=action.action,
+                success=False, error=f"Unsupported action: {action.action}",
+            )
+        return handler(action)
+
+    def _read_ticket(self, action: ToolAction) -> ToolResult:
+        key = action.params.get("key", "")
+        if not key or not self.check_auth():
+            return self._scaffold("read_ticket", action)
+        try:
+            data = self._api_get(f"issue/{key}")
+            return ToolResult(tool_name=self.name, action="read_ticket", success=True, data=data)
+        except (HTTPError, URLError, TimeoutError) as e:
+            return ToolResult(tool_name=self.name, action="read_ticket", success=False, error=str(e))
+
+    def _search_tickets(self, action: ToolAction) -> ToolResult:
+        jql = action.params.get("jql", "")
+        if not jql or not self.check_auth():
+            return self._scaffold("search_tickets", action)
+        try:
+            encoded_jql = jql.replace(" ", "%20")
+            data = self._api_get(f"search?jql={encoded_jql}&maxResults=20")
+            return ToolResult(tool_name=self.name, action="search_tickets", success=True, data=data)
+        except (HTTPError, URLError, TimeoutError) as e:
+            return ToolResult(tool_name=self.name, action="search_tickets", success=False, error=str(e))
+
+    def _add_comment(self, action: ToolAction) -> ToolResult:
+        """Write action — scaffold only."""
+        return self._scaffold("add_comment", action)
+
+    def _transition_ticket(self, action: ToolAction) -> ToolResult:
+        """Write action — scaffold only."""
+        return self._scaffold("transition_ticket", action)
+
+    def _scaffold(self, action_name: str, action: ToolAction) -> ToolResult:
+        return ToolResult(
+            tool_name=self.name, action=action_name, success=True,
+            data={"scaffold": True, "action": action_name, "params": action.params},
+        )