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

specify_cli/orchestrator/agents/cursor.py

@@ -0,0 +1,139 @@
+"""Cursor invoker.
+
+Implements the AgentInvoker protocol for Cursor CLI with timeout wrapper.
+"""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+from specify_cli.orchestrator.agents.base import BaseInvoker, InvocationResult
+
+
+# Exit code from timeout command when process is killed
+TIMEOUT_EXIT_CODE = 124
+
+
+class CursorInvoker(BaseInvoker):
+    """Invoker for Cursor CLI (cursor) with timeout wrapper.
+
+    IMPORTANT: Cursor CLI may hang indefinitely, so we ALWAYS wrap it
+    with a timeout command to ensure the process eventually terminates.
+
+    Uses `cursor agent` subcommand with -p flag for prompts.
+    """
+
+    agent_id = "cursor"
+    command = "cursor"
+    uses_stdin = False  # Prompt passed as -p argument
+    default_timeout = 300  # 5 minutes
+
+    def __init__(self, timeout_seconds: int | None = None):
+        """Initialize Cursor invoker.
+
+        Args:
+            timeout_seconds: Override default timeout (300s). Must be positive.
+        """
+        if timeout_seconds is not None and timeout_seconds > 0:
+            self.timeout = timeout_seconds
+        else:
+            self.timeout = self.default_timeout
+
+    def is_installed(self) -> bool:
+        """Check if Cursor CLI and timeout command are available."""
+        # Need both cursor and timeout to be installed
+        return (
+            shutil.which(self.command) is not None
+            and shutil.which("timeout") is not None
+        )
+
+    def build_command(
+        self,
+        prompt: str,
+        working_dir: Path,
+        role: str,
+    ) -> list[str]:
+        """Build Cursor command with timeout wrapper.
+
+        Args:
+            prompt: Task prompt (passed as -p argument).
+            working_dir: Directory for execution.
+            role: "implementation" or "review".
+
+        Returns:
+            Command arguments list wrapped with timeout.
+        """
+        # CRITICAL: Always wrap with timeout to prevent hanging
+        cmd = [
+            "timeout", str(self.timeout),  # Timeout wrapper
+            "cursor", "agent",
+            "-p", prompt,  # Prompt as argument
+            "--force",  # Autonomous mode (no confirmations)
+            "--output-format", "json",  # JSON output
+        ]
+
+        return cmd
+
+    def parse_output(
+        self,
+        stdout: str,
+        stderr: str,
+        exit_code: int,
+        duration_seconds: float,
+    ) -> InvocationResult:
+        """Parse Cursor output.
+
+        Handles the special case of timeout (exit code 124) as a failure.
+        """
+        # Check for timeout
+        if exit_code == TIMEOUT_EXIT_CODE:
+            return InvocationResult(
+                success=False,
+                exit_code=exit_code,
+                stdout=stdout,
+                stderr=stderr,
+                duration_seconds=duration_seconds,
+                files_modified=[],
+                commits_made=[],
+                errors=[
+                    f"Cursor execution timed out after {self.timeout} seconds. "
+                    "This is a known issue with Cursor CLI."
+                ],
+                warnings=[],
+            )
+
+        success = exit_code == 0
+        data = self._parse_json_output(stdout)
+
+        files_modified = []
+        commits_made = []
+        errors = []
+        warnings = []
+
+        if data:
+            if isinstance(data, dict):
+                files_modified = self._extract_files_from_output(data)
+                commits_made = self._extract_commits_from_output(data)
+
+                # Check for error in JSON response
+                if "error" in data:
+                    errors.append(str(data["error"]))
+
+        # Fall back to stderr for errors
+        if not errors and stderr.strip() and not success:
+            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/gemini.py

@@ -0,0 +1,115 @@
+"""Google Gemini invoker.
+
+Implements the AgentInvoker protocol for Google Gemini CLI.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from specify_cli.orchestrator.agents.base import BaseInvoker, InvocationResult
+
+
+# Gemini-specific exit codes
+GEMINI_EXIT_SUCCESS = 0
+GEMINI_EXIT_AUTH_ERROR = 41
+GEMINI_EXIT_RATE_LIMIT = 42
+GEMINI_EXIT_GENERAL_ERROR = 52
+GEMINI_EXIT_INTERRUPTED = 130
+
+
+class GeminiInvoker(BaseInvoker):
+    """Invoker for Google Gemini CLI (gemini).
+
+    Gemini accepts prompts via stdin with -p flag for headless mode.
+    It supports JSON output and has specific exit codes for different errors.
+    """
+
+    agent_id = "gemini"
+    command = "gemini"
+    uses_stdin = True
+
+    def build_command(
+        self,
+        prompt: str,
+        working_dir: Path,
+        role: str,
+    ) -> list[str]:
+        """Build Gemini command.
+
+        Args:
+            prompt: Task prompt (passed via stdin).
+            working_dir: Directory for execution.
+            role: "implementation" or "review".
+
+        Returns:
+            Command arguments list.
+        """
+        cmd = [
+            "gemini",
+            "-p",  # Headless/non-interactive mode
+            "--yolo",  # Autonomous mode (no confirmations)
+            "--output-format", "json",  # Structured output
+        ]
+
+        return cmd
+
+    def parse_output(
+        self,
+        stdout: str,
+        stderr: str,
+        exit_code: int,
+        duration_seconds: float,
+    ) -> InvocationResult:
+        """Parse Gemini JSON output.
+
+        Handles Gemini-specific exit codes and JSON structure.
+        """
+        success = exit_code == GEMINI_EXIT_SUCCESS
+        data = self._parse_json_output(stdout)
+
+        files_modified = []
+        commits_made = []
+        errors = []
+        warnings = []
+
+        # Handle specific exit codes
+        if exit_code == GEMINI_EXIT_AUTH_ERROR:
+            errors.append("Gemini authentication error - check GOOGLE_API_KEY")
+        elif exit_code == GEMINI_EXIT_RATE_LIMIT:
+            errors.append("Gemini rate limit exceeded - wait before retrying")
+        elif exit_code == GEMINI_EXIT_GENERAL_ERROR:
+            errors.append("Gemini general error")
+        elif exit_code == GEMINI_EXIT_INTERRUPTED:
+            errors.append("Gemini execution was interrupted")
+
+        if data:
+            # Extract file and commit information
+            if isinstance(data, dict):
+                files_modified = self._extract_files_from_output(data)
+                commits_made = self._extract_commits_from_output(data)
+
+                # Check for error in JSON response
+                if "error" in data:
+                    errors.append(str(data["error"]))
+                if "status" in data and data.get("status") == "error":
+                    msg = data.get("message", "Unknown Gemini error")
+                    errors.append(msg)
+
+        # Fall back to stderr for errors
+        if not errors and stderr.strip() and not success:
+            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/kilocode.py

@@ -0,0 +1,94 @@
+"""Kilocode invoker.
+
+Implements the AgentInvoker protocol for Kilocode CLI.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from specify_cli.orchestrator.agents.base import BaseInvoker, InvocationResult
+
+
+class KilocodeInvoker(BaseInvoker):
+    """Invoker for Kilocode CLI (kilocode).
+
+    Kilocode takes prompts as positional arguments (not stdin).
+    Uses -a for autonomous mode and -j for JSON output.
+    """
+
+    agent_id = "kilocode"
+    command = "kilocode"
+    uses_stdin = False  # Prompt passed as argument
+
+    def build_command(
+        self,
+        prompt: str,
+        working_dir: Path,
+        role: str,
+    ) -> list[str]:
+        """Build Kilocode command.
+
+        Args:
+            prompt: Task prompt (passed as argument).
+            working_dir: Directory for execution.
+            role: "implementation" or "review".
+
+        Returns:
+            Command arguments list.
+        """
+        cmd = [
+            "kilocode",
+            "-a",  # Autonomous agent mode
+            "--yolo",  # No confirmations
+            "-j",  # JSON output
+            prompt,  # Prompt as positional argument
+        ]
+
+        return cmd
+
+    def parse_output(
+        self,
+        stdout: str,
+        stderr: str,
+        exit_code: int,
+        duration_seconds: float,
+    ) -> InvocationResult:
+        """Parse Kilocode JSON output."""
+        success = exit_code == 0
+        data = self._parse_json_output(stdout)
+
+        files_modified = []
+        commits_made = []
+        errors = []
+        warnings = []
+
+        if data:
+            if isinstance(data, dict):
+                files_modified = self._extract_files_from_output(data)
+                commits_made = self._extract_commits_from_output(data)
+
+                # Check for error in JSON response
+                if "error" in data:
+                    errors.append(str(data["error"]))
+                if "status" in data and data.get("status") == "error":
+                    msg = data.get("message", "Unknown Kilocode error")
+                    errors.append(msg)
+
+        # Fall back to stderr for errors
+        if not errors and stderr.strip() and not success:
+            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/opencode.py

@@ -0,0 +1,132 @@
+"""OpenCode invoker.
+
+Implements the AgentInvoker protocol for OpenCode CLI.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from specify_cli.orchestrator.agents.base import BaseInvoker, InvocationResult
+
+
+class OpenCodeInvoker(BaseInvoker):
+    """Invoker for OpenCode CLI (opencode).
+
+    OpenCode is a multi-provider agent that supports various LLM backends.
+    Uses `opencode run` subcommand with stdin for prompts.
+    """
+
+    agent_id = "opencode"
+    command = "opencode"
+    uses_stdin = True
+
+    def build_command(
+        self,
+        prompt: str,
+        working_dir: Path,
+        role: str,
+    ) -> list[str]:
+        """Build OpenCode command.
+
+        Args:
+            prompt: Task prompt (passed via stdin).
+            working_dir: Directory for execution.
+            role: "implementation" or "review".
+
+        Returns:
+            Command arguments list.
+        """
+        cmd = [
+            "opencode", "run",
+            "--agent", "build",  # Use build agent with broad permissions
+            "--format", "json",  # JSON output format
+        ]
+
+        return cmd
+
+    def parse_output(
+        self,
+        stdout: str,
+        stderr: str,
+        exit_code: int,
+        duration_seconds: float,
+    ) -> InvocationResult:
+        """Parse OpenCode JSON streaming output.
+
+        OpenCode outputs one JSON event per line with types:
+        - step_start, step_finish: workflow markers
+        - text: assistant messages
+        - tool_use: tool invocations
+        - error: error events
+        """
+        import json
+
+        success = exit_code == 0
+        files_modified = []
+        commits_made = []
+        errors = []
+        warnings = []
+
+        # Parse all JSON lines to find errors and extract data
+        if stdout.strip():
+            for line in stdout.strip().split("\n"):
+                line = line.strip()
+                if not line or not line.startswith("{"):
+                    continue
+                try:
+                    event = json.loads(line)
+                    event_type = event.get("type", "")
+
+                    # Check for error events
+                    if event_type == "error":
+                        error_info = event.get("error", {})
+                        error_name = error_info.get("name", "UnknownError")
+                        error_data = error_info.get("data", {})
+                        error_msg = error_data.get("message", str(error_info))
+                        errors.append(f"{error_name}: {error_msg}")
+                        success = False
+
+                    # Extract tool results for file modifications
+                    elif event_type == "tool_use":
+                        part = event.get("part", {})
+                        state = part.get("state", {})
+                        tool = part.get("tool", "")
+
+                        # Track file edits
+                        if tool in ("edit", "write"):
+                            input_data = state.get("input", {})
+                            file_path = input_data.get("filePath") or input_data.get("file_path")
+                            if file_path and file_path not in files_modified:
+                                files_modified.append(file_path)
+
+                        # Track commits
+                        elif tool == "bash":
+                            output = state.get("output", "")
+                            if "commit" in state.get("input", {}).get("command", ""):
+                                # Extract commit hash if present
+                                for word in output.split():
+                                    if len(word) == 40 and all(c in "0123456789abcdef" for c in word):
+                                        commits_made.append(word[:8])
+                                        break
+
+                except json.JSONDecodeError:
+                    continue
+
+        # Fall back to stderr for errors
+        if not errors and stderr.strip() and not success:
+            errors = self._extract_errors_from_output(None, stderr)
+
+        warnings = self._extract_warnings_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/qwen.py

@@ -0,0 +1,96 @@
+"""Qwen Code invoker.
+
+Implements the AgentInvoker protocol for Qwen Code CLI.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from specify_cli.orchestrator.agents.base import BaseInvoker, InvocationResult
+
+
+class QwenInvoker(BaseInvoker):
+    """Invoker for Qwen Code CLI (qwen).
+
+    Qwen is a fork of Gemini CLI with similar flags.
+    Accepts prompts via stdin with -p flag for headless mode.
+    """
+
+    agent_id = "qwen"
+    command = "qwen"
+    uses_stdin = True
+
+    def build_command(
+        self,
+        prompt: str,
+        working_dir: Path,
+        role: str,
+    ) -> list[str]:
+        """Build Qwen command.
+
+        Args:
+            prompt: Task prompt (passed via stdin).
+            working_dir: Directory for execution.
+            role: "implementation" or "review".
+
+        Returns:
+            Command arguments list.
+        """
+        cmd = [
+            "qwen",
+            "-p",  # Headless/non-interactive mode
+            "--yolo",  # Autonomous mode (no confirmations)
+            "--output-format", "json",  # Structured output
+        ]
+
+        return cmd
+
+    def parse_output(
+        self,
+        stdout: str,
+        stderr: str,
+        exit_code: int,
+        duration_seconds: float,
+    ) -> InvocationResult:
+        """Parse Qwen JSON output.
+
+        Similar parsing to Gemini since Qwen is a fork.
+        """
+        success = exit_code == 0
+        data = self._parse_json_output(stdout)
+
+        files_modified = []
+        commits_made = []
+        errors = []
+        warnings = []
+
+        if data:
+            if isinstance(data, dict):
+                files_modified = self._extract_files_from_output(data)
+                commits_made = self._extract_commits_from_output(data)
+
+                # Check for error in JSON response
+                if "error" in data:
+                    errors.append(str(data["error"]))
+                if "status" in data and data.get("status") == "error":
+                    msg = data.get("message", "Unknown Qwen error")
+                    errors.append(msg)
+
+        # Fall back to stderr for errors
+        if not errors and stderr.strip() and not success:
+            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,
+        )