spec-kitty-cli 0.12.1__py3-none-any.whl

specify_cli/orchestrator/agents/base.py

@@ -0,0 +1,243 @@
+"""Base protocol and classes for agent invokers.
+
+This module defines:
+    - AgentInvoker Protocol for type checking
+    - InvocationResult dataclass for execution results
+    - BaseAgentInvoker abstract base class with common functionality
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import shutil
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class InvocationResult:
+    """Result of an agent invocation.
+
+    Captures all relevant information from an agent execution including
+    success status, output, and any extracted structured data.
+    """
+
+    success: bool
+    exit_code: int
+    stdout: str
+    stderr: str
+    duration_seconds: float
+    files_modified: list[str] = field(default_factory=list)
+    commits_made: list[str] = field(default_factory=list)
+    errors: list[str] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+
+
+@runtime_checkable
+class AgentInvoker(Protocol):
+    """Protocol defining the interface for agent invokers.
+
+    All agent invokers must implement this protocol to be usable
+    by the orchestrator.
+    """
+
+    agent_id: str
+    command: str
+    uses_stdin: bool
+
+    def is_installed(self) -> bool:
+        """Check if agent CLI is available on the system."""
+        ...
+
+    def build_command(
+        self,
+        prompt: str,
+        working_dir: Path,
+        role: str,
+    ) -> list[str]:
+        """Build the full command with agent-specific flags.
+
+        Args:
+            prompt: The task prompt to send to the agent.
+            working_dir: Directory where agent should execute.
+            role: Either "implementation" or "review".
+
+        Returns:
+            List of command arguments for subprocess execution.
+        """
+        ...
+
+    def parse_output(
+        self,
+        stdout: str,
+        stderr: str,
+        exit_code: int,
+        duration_seconds: float,
+    ) -> InvocationResult:
+        """Parse agent output into structured result.
+
+        Args:
+            stdout: Standard output from the agent process.
+            stderr: Standard error from the agent process.
+            exit_code: Process exit code.
+            duration_seconds: How long the process ran.
+
+        Returns:
+            Structured InvocationResult with extracted data.
+        """
+        ...
+
+
+class BaseInvoker:
+    """Base class with common invoker functionality.
+
+    Provides default implementations for common operations that
+    most invokers can inherit.
+    """
+
+    agent_id: str = ""
+    command: str = ""
+    uses_stdin: bool = True
+
+    def is_installed(self) -> bool:
+        """Check if agent CLI is available via shutil.which()."""
+        return shutil.which(self.command) is not None
+
+    def _parse_json_output(self, stdout: str) -> dict | None:
+        """Attempt to parse JSON from agent output.
+
+        Handles both single JSON object and JSONL (one JSON per line) formats.
+
+        Args:
+            stdout: Raw stdout from the agent.
+
+        Returns:
+            Parsed JSON dict or None if parsing fails.
+        """
+        if not stdout.strip():
+            return None
+
+        # Try parsing as single JSON object
+        try:
+            return json.loads(stdout)
+        except json.JSONDecodeError:
+            pass
+
+        # Try parsing last line as JSON (JSONL format)
+        lines = stdout.strip().split("\n")
+        for line in reversed(lines):
+            line = line.strip()
+            if line.startswith("{") or line.startswith("["):
+                try:
+                    return json.loads(line)
+                except json.JSONDecodeError:
+                    continue
+
+        return None
+
+    def _extract_files_from_output(self, data: dict | None) -> list[str]:
+        """Extract list of modified files from parsed JSON output."""
+        if not data:
+            return []
+
+        # Common field names for file lists
+        for key in ["files", "files_modified", "modified_files", "changedFiles"]:
+            if key in data and isinstance(data[key], list):
+                return [str(f) for f in data[key]]
+
+        return []
+
+    def _extract_commits_from_output(self, data: dict | None) -> list[str]:
+        """Extract list of commits from parsed JSON output."""
+        if not data:
+            return []
+
+        # Common field names for commit lists
+        for key in ["commits", "commits_made", "commitShas"]:
+            if key in data and isinstance(data[key], list):
+                return [str(c) for c in data[key]]
+
+        return []
+
+    def _extract_errors_from_output(
+        self, data: dict | None, stderr: str
+    ) -> list[str]:
+        """Extract errors from parsed JSON output and stderr."""
+        errors = []
+
+        if data:
+            for key in ["errors", "error"]:
+                if key in data:
+                    val = data[key]
+                    if isinstance(val, list):
+                        errors.extend(str(e) for e in val)
+                    elif val:
+                        errors.append(str(val))
+
+        # Add non-empty stderr lines as potential errors
+        if stderr.strip():
+            stderr_lines = [
+                line.strip()
+                for line in stderr.split("\n")
+                if line.strip() and not line.startswith("warning")
+            ]
+            # Only add stderr if it looks like errors (not just logging)
+            if any("error" in line.lower() for line in stderr_lines):
+                errors.extend(stderr_lines[:5])  # Limit to first 5 lines
+
+        return errors
+
+    def _extract_warnings_from_output(
+        self, data: dict | None, stderr: str
+    ) -> list[str]:
+        """Extract warnings from parsed JSON output and stderr."""
+        warnings = []
+
+        if data:
+            for key in ["warnings", "warning"]:
+                if key in data:
+                    val = data[key]
+                    if isinstance(val, list):
+                        warnings.extend(str(w) for w in val)
+                    elif val:
+                        warnings.append(str(val))
+
+        # Add warning lines from stderr
+        if stderr.strip():
+            warnings.extend(
+                line.strip()
+                for line in stderr.split("\n")
+                if line.strip().lower().startswith("warning")
+            )
+
+        return warnings
+
+    def parse_output(
+        self,
+        stdout: str,
+        stderr: str,
+        exit_code: int,
+        duration_seconds: float,
+    ) -> InvocationResult:
+        """Default output parsing implementation.
+
+        Subclasses can override for agent-specific parsing.
+        """
+        success = exit_code == 0
+        data = self._parse_json_output(stdout)
+
+        return InvocationResult(
+            success=success,
+            exit_code=exit_code,
+            stdout=stdout,
+            stderr=stderr,
+            duration_seconds=duration_seconds,
+            files_modified=self._extract_files_from_output(data),
+            commits_made=self._extract_commits_from_output(data),
+            errors=self._extract_errors_from_output(data, stderr),
+            warnings=self._extract_warnings_from_output(data, stderr),
+        )

specify_cli/orchestrator/agents/claude.py

@@ -0,0 +1,112 @@
+"""Claude Code invoker.
+
+Implements the AgentInvoker protocol for Claude Code CLI.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from specify_cli.orchestrator.agents.base import BaseInvoker, InvocationResult
+
+
+class ClaudeInvoker(BaseInvoker):
+    """Invoker for Claude Code CLI (claude).
+
+    Claude Code accepts prompts via stdin and supports JSON output format.
+    It runs in headless mode with -p flag and can be restricted to specific tools.
+    """
+
+    agent_id = "claude-code"
+    command = "claude"
+    uses_stdin = True
+
+    def build_command(
+        self,
+        prompt: str,
+        working_dir: Path,
+        role: str,
+    ) -> list[str]:
+        """Build Claude Code command.
+
+        Args:
+            prompt: Task prompt (passed via stdin, not in command).
+            working_dir: Directory for execution.
+            role: "implementation" or "review".
+
+        Returns:
+            Command arguments list.
+        """
+        cmd = [
+            "claude",
+            "-p",  # Headless/print mode (non-interactive)
+            "--output-format", "json",  # Structured JSON output
+            "--dangerously-skip-permissions",  # Allow all tools without prompts
+        ]
+
+        # Restrict tools based on role
+        if role == "implementation":
+            cmd.extend([
+                "--allowedTools",
+                "Read,Write,Edit,Bash,Glob,Grep,TodoWrite",
+            ])
+        elif role == "review":
+            # Review should be more read-focused
+            cmd.extend([
+                "--allowedTools",
+                "Read,Glob,Grep,Bash",
+            ])
+
+        return cmd
+
+    def parse_output(
+        self,
+        stdout: str,
+        stderr: str,
+        exit_code: int,
+        duration_seconds: float,
+    ) -> InvocationResult:
+        """Parse Claude Code JSON output.
+
+        Claude outputs conversation turns in JSON format. We extract
+        the relevant information from the final state.
+        """
+        success = exit_code == 0
+        data = self._parse_json_output(stdout)
+
+        # Claude-specific JSON structure handling
+        files_modified = []
+        commits_made = []
+        errors = []
+        warnings = []
+
+        if data:
+            # Check for Claude-specific fields
+            if isinstance(data, dict):
+                # Extract from result field if present
+                result = data.get("result", data)
+                if isinstance(result, dict):
+                    files_modified = self._extract_files_from_output(result)
+                    commits_made = self._extract_commits_from_output(result)
+
+                # Check for error in response
+                if "error" in data:
+                    errors.append(str(data["error"]))
+
+        # Fall back to stderr for errors
+        if not errors and stderr.strip():
+            errors = self._extract_errors_from_output(None, stderr)
+
+        warnings = self._extract_warnings_from_output(data, stderr)
+
+        return InvocationResult(
+            success=success,
+            exit_code=exit_code,
+            stdout=stdout,
+            stderr=stderr,
+            duration_seconds=duration_seconds,
+            files_modified=files_modified,
+            commits_made=commits_made,
+            errors=errors,
+            warnings=warnings,
+        )

specify_cli/orchestrator/agents/codex.py

@@ -0,0 +1,106 @@
+"""GitHub Codex invoker.
+
+Implements the AgentInvoker protocol for GitHub Codex CLI.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from specify_cli.orchestrator.agents.base import BaseInvoker, InvocationResult
+
+
+class CodexInvoker(BaseInvoker):
+    """Invoker for GitHub Codex CLI (codex).
+
+    Codex uses `codex exec -` to read prompts from stdin.
+    It supports JSON output and fully autonomous execution.
+    """
+
+    agent_id = "codex"
+    command = "codex"
+    uses_stdin = True
+
+    def build_command(
+        self,
+        prompt: str,
+        working_dir: Path,
+        role: str,
+    ) -> list[str]:
+        """Build Codex command.
+
+        Args:
+            prompt: Task prompt (passed via stdin with `-`).
+            working_dir: Directory for execution.
+            role: "implementation" or "review".
+
+        Returns:
+            Command arguments list.
+        """
+        cmd = [
+            "codex", "exec",
+            "-",  # Read prompt from stdin
+            "--json",  # JSON output format
+            "--full-auto",  # Fully autonomous mode
+        ]
+
+        # Add role-specific flags if needed
+        if role == "review":
+            # Codex doesn't have a built-in review mode,
+            # but we can hint via the prompt structure
+            pass
+
+        return cmd
+
+    def parse_output(
+        self,
+        stdout: str,
+        stderr: str,
+        exit_code: int,
+        duration_seconds: float,
+    ) -> InvocationResult:
+        """Parse Codex JSON output.
+
+        Codex outputs structured JSON with execution results.
+        """
+        success = exit_code == 0
+        data = self._parse_json_output(stdout)
+
+        files_modified = []
+        commits_made = []
+        errors = []
+        warnings = []
+
+        if data:
+            # Codex-specific JSON structure
+            if isinstance(data, dict):
+                # Extract modified files
+                files_modified = self._extract_files_from_output(data)
+
+                # Extract commits if any
+                commits_made = self._extract_commits_from_output(data)
+
+                # Check for execution errors
+                if "status" in data and data["status"] == "error":
+                    errors.append(data.get("message", "Unknown error"))
+                elif "error" in data:
+                    errors.append(str(data["error"]))
+
+                # Extract any warnings
+                warnings = self._extract_warnings_from_output(data, stderr)
+
+        # Fall back to stderr for errors
+        if not errors and stderr.strip() and not success:
+            errors = self._extract_errors_from_output(None, stderr)
+
+        return InvocationResult(
+            success=success,
+            exit_code=exit_code,
+            stdout=stdout,
+            stderr=stderr,
+            duration_seconds=duration_seconds,
+            files_modified=files_modified,
+            commits_made=commits_made,
+            errors=errors,
+            warnings=warnings,
+        )

specify_cli/orchestrator/agents/copilot.py

@@ -0,0 +1,137 @@
+"""GitHub Copilot invoker.
+
+Implements the AgentInvoker protocol for GitHub Copilot CLI.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from specify_cli.orchestrator.agents.base import BaseInvoker, InvocationResult
+
+
+class CopilotInvoker(BaseInvoker):
+    """Invoker for GitHub Copilot CLI (gh copilot).
+
+    Copilot takes prompts as command-line arguments (not stdin).
+    It uses the gh CLI extension and runs in autonomous mode with --yolo.
+    """
+
+    agent_id = "copilot"
+    command = "gh"  # Uses gh CLI with copilot extension
+    uses_stdin = False  # Prompt passed as argument
+
+    def is_installed(self) -> bool:
+        """Check if gh CLI with copilot extension is available."""
+        import shutil
+        import subprocess
+
+        # First check if gh is installed
+        if not shutil.which("gh"):
+            return False
+
+        # Then check if copilot extension is installed
+        try:
+            result = subprocess.run(
+                ["gh", "extension", "list"],
+                capture_output=True,
+                text=True,
+                timeout=10,
+            )
+            return "copilot" in result.stdout.lower()
+        except (subprocess.TimeoutExpired, subprocess.SubprocessError):
+            return False
+
+    def build_command(
+        self,
+        prompt: str,
+        working_dir: Path,
+        role: str,
+    ) -> list[str]:
+        """Build Copilot command.
+
+        Args:
+            prompt: Task prompt (passed as -p argument).
+            working_dir: Directory for execution.
+            role: "implementation" or "review".
+
+        Returns:
+            Command arguments list.
+        """
+        cmd = [
+            "gh", "copilot",
+            "-p", prompt,  # Prompt as argument
+            "--yolo",  # Autonomous mode (no confirmations)
+            "--silent",  # Minimal output noise
+        ]
+
+        return cmd
+
+    def parse_output(
+        self,
+        stdout: str,
+        stderr: str,
+        exit_code: int,
+        duration_seconds: float,
+    ) -> InvocationResult:
+        """Parse Copilot output.
+
+        Copilot doesn't output structured JSON, so we rely primarily
+        on exit code and parse stdout/stderr for useful information.
+        """
+        success = exit_code == 0
+
+        # Copilot doesn't have structured JSON output
+        # We can try to extract file info from stdout text
+        files_modified = self._extract_files_from_text(stdout)
+        commits_made = []
+        errors = []
+        warnings = []
+
+        # Check stderr for errors
+        if stderr.strip():
+            if not success:
+                errors = self._extract_errors_from_output(None, stderr)
+            warnings = self._extract_warnings_from_output(None, stderr)
+
+        # Check stdout for error indicators
+        if not success and not errors:
+            stdout_lower = stdout.lower()
+            if "error" in stdout_lower or "failed" in stdout_lower:
+                # Extract error lines from stdout
+                error_lines = [
+                    line.strip()
+                    for line in stdout.split("\n")
+                    if "error" in line.lower() or "failed" in line.lower()
+                ]
+                errors.extend(error_lines[:3])
+
+        return InvocationResult(
+            success=success,
+            exit_code=exit_code,
+            stdout=stdout,
+            stderr=stderr,
+            duration_seconds=duration_seconds,
+            files_modified=files_modified,
+            commits_made=commits_made,
+            errors=errors,
+            warnings=warnings,
+        )
+
+    def _extract_files_from_text(self, text: str) -> list[str]:
+        """Extract file paths mentioned in unstructured text output."""
+        files = []
+        # Look for common patterns indicating file modifications
+        import re
+
+        # Patterns like "Created file.py", "Modified src/foo.py", etc.
+        patterns = [
+            r"(?:created|modified|updated|wrote|edited)\s+['\"]?([^\s'\"]+\.\w+)['\"]?",
+            r"(?:writing to|saving)\s+['\"]?([^\s'\"]+\.\w+)['\"]?",
+        ]
+
+        for pattern in patterns:
+            matches = re.findall(pattern, text, re.IGNORECASE)
+            files.extend(matches)
+
+        return list(set(files))  # Remove duplicates