fix: external agent integrations - 4 root causes (fixes #1415) (#1419)

Validated locally: all 3 fixes work with real CLIs (gemini returns response with flash-lite default, codex works outside git repos, cursor surfaces auth errors clearly instead of silent empty). Closes #1415.

Author: praisonai-triage-agent[bot]

src/praisonai/praisonai/integrations/__init__.py

@@ -29,6 +29,7 @@
 # Lazy imports to avoid performance impact
 __all__ = [
     'BaseCLIIntegration',
+    'CLIExecutionError',
     'ClaudeCodeIntegration',
     'GeminiCLIIntegration',
     'CodexCLIIntegration',
@@ -53,6 +54,9 @@ def __getattr__(name):
     if name == 'BaseCLIIntegration':
         from .base import BaseCLIIntegration
         return BaseCLIIntegration
+    elif name == 'CLIExecutionError':
+        from .base import CLIExecutionError
+        return CLIExecutionError
     elif name == 'ClaudeCodeIntegration':
         from .claude_code import ClaudeCodeIntegration
         return ClaudeCodeIntegration

src/praisonai/praisonai/integrations/base.py

@@ -18,6 +18,19 @@
 import os
 
 
+class CLIExecutionError(RuntimeError):
+    """Raised when a CLI command fails with non-zero exit code."""
+    
+    def __init__(self, cmd: List[str], returncode: int, stderr: str):
+        stderr_excerpt = stderr.strip()[:500] if stderr.strip() else "(no error message)"
+        cmd_str = ' '.join(cmd) if cmd else "unknown command"
+        hint = f"Hint: ensure the CLI is installed and authenticated; try '{cmd_str} --help' or rerun the command manually."
+        super().__init__(f"{cmd[0]} exited {returncode}: {stderr_excerpt}. {hint}")
+        self.cmd = cmd
+        self.returncode = returncode
+        self.stderr = stderr
+
+
 class BaseCLIIntegration(ABC):
     """
     Abstract base class for external CLI tool integrations.
@@ -128,6 +141,7 @@ async def execute_async(self, cmd: List[str], timeout: Optional[int] = None) ->
             
         Raises:
             TimeoutError: If the command times out
+            CLIExecutionError: If the command fails with non-zero exit code
         """
         timeout = timeout or self.timeout
 
@@ -144,7 +158,12 @@ async def execute_async(self, cmd: List[str], timeout: Optional[int] = None) ->
                 proc.communicate(),
                 timeout=timeout
             )
-            return stdout.decode()
+            
+            # Check exit code and raise error if non-zero
+            if proc.returncode != 0:
+                raise CLIExecutionError(cmd, proc.returncode, stderr.decode(errors="replace"))
+            
+            return stdout.decode(errors="replace")
         except asyncio.TimeoutError:
             proc.kill()
             await proc.wait()
@@ -183,7 +202,12 @@ async def execute_async_with_stderr(
                 proc.communicate(),
                 timeout=timeout
             )
-            return stdout.decode(), stderr.decode()
+            
+            # Check exit code and raise error if non-zero
+            if proc.returncode != 0:
+                raise CLIExecutionError(cmd, proc.returncode, stderr.decode(errors="replace"))
+            
+            return stdout.decode(errors="replace"), stderr.decode(errors="replace")
         except asyncio.TimeoutError:
             proc.kill()
             await proc.wait()
@@ -203,8 +227,12 @@ async def stream_async(
             
         Yields:
             str: Each line of output
+            
+        Raises:
+            CLIExecutionError: If the command fails with non-zero exit code
         """
         timeout = timeout or self.timeout
+        stderr_buffer = []
 
         proc = await asyncio.create_subprocess_exec(
             *cmd,
@@ -215,15 +243,35 @@ async def stream_async(
         )
 
         try:
+            async def read_stderr():
+                """Read stderr into buffer for error reporting"""
+                while True:
+                    line = await proc.stderr.readline()
+                    if not line:
+                        break
+                    stderr_buffer.append(line.decode(errors="replace").rstrip('\n'))
+            
+            # Start reading stderr in background
+            stderr_task = asyncio.create_task(read_stderr())
+            
             async def read_lines():
                 while True:
                     line = await proc.stdout.readline()
                     if not line:
                         break
-                    yield line.decode().rstrip('\n')
+                    yield line.decode(errors="replace").rstrip('\n')
 
             async for line in read_lines():
                 yield line
+            
+            # Wait for stderr reading to complete and process to finish
+            await stderr_task
+            await proc.wait()
+            
+            # Check exit code and raise error if non-zero
+            if proc.returncode != 0:
+                stderr_text = '\n'.join(stderr_buffer)
+                raise CLIExecutionError(cmd, proc.returncode, stderr_text)
 
         except asyncio.TimeoutError:
             proc.kill()

src/praisonai/praisonai/integrations/codex_cli.py

@@ -111,7 +111,7 @@ def _build_command(self, task: str, **options) -> List[str]:
         Returns:
             List of command arguments
         """
-        cmd = ["codex", "exec"]
+        cmd = ["codex", "exec", "--skip-git-repo-check"]
 
         # Add working directory
         cmd.extend(["-C", self.workspace])

src/praisonai/praisonai/integrations/cursor_cli.py

@@ -97,9 +97,6 @@ def _build_command(self, prompt: str, **options) -> List[str]:
         # Add print mode flag
         cmd.append("-p")
 
-        # Add workspace
-        cmd.extend(["--workspace", self.workspace])
-        
         # Add force flag if enabled
         if self.force:
             cmd.append("--force")

src/praisonai/praisonai/integrations/gemini_cli.py

@@ -33,6 +33,13 @@
 from .base import BaseCLIIntegration
 
 
+# Default model configuration (resolved per-instance so env overrides are honored)
+DEFAULT_GEMINI_MODEL_FALLBACK = "gemini-2.5-flash-lite"
+
+# For backward compatibility, export the default for tests that import it
+DEFAULT_GEMINI_MODEL = DEFAULT_GEMINI_MODEL_FALLBACK
+
+
 class GeminiCLIIntegration(BaseCLIIntegration):
     """
     Integration with Google's Gemini CLI.
@@ -49,7 +56,7 @@ def __init__(
         workspace: str = ".",
         timeout: int = 300,
         output_format: str = "json",
-        model: str = "gemini-2.5-pro",
+        model: Optional[str] = None,
         include_directories: Optional[List[str]] = None,
         sandbox: bool = False,
     ):
@@ -67,7 +74,7 @@ def __init__(
         super().__init__(workspace=workspace, timeout=timeout)
 
         self.output_format = output_format
-        self.model = model
+        self.model = model or os.getenv("PRAISONAI_GEMINI_MODEL", DEFAULT_GEMINI_MODEL_FALLBACK)
         self.include_directories = include_directories
         self.sandbox = sandbox
 

src/praisonai/tests/integration/test_cli_integrations.py

@@ -38,13 +38,15 @@ def test_import_all_integrations(self):
         """Test importing all integrations."""
         from praisonai.integrations import (
             BaseCLIIntegration,
+            CLIExecutionError,
             ClaudeCodeIntegration,
             GeminiCLIIntegration,
             CodexCLIIntegration,
             CursorCLIIntegration,
         )
 
         assert BaseCLIIntegration is not None
+        assert CLIExecutionError is not None
         assert ClaudeCodeIntegration is not None
         assert GeminiCLIIntegration is not None
         assert CodexCLIIntegration is not None
@@ -124,6 +126,12 @@ def test_gemini_integration_creation(self):
         assert integration.cli_command == "gemini"
         assert integration.model == "gemini-2.5-pro"
         print(f"\n🔧 Gemini CLI available: {integration.is_available}")
+        
+        # Test default model configuration
+        default_integration = GeminiCLIIntegration()
+        expected_default = os.environ.get("PRAISONAI_GEMINI_MODEL", "gemini-2.5-flash-lite")
+        assert default_integration.model == expected_default
+        print(f"🔧 Gemini default model: {default_integration.model}")
 
     @pytest.mark.skipif(
         not os.environ.get("GEMINI_API_KEY") and not os.environ.get("GOOGLE_API_KEY"),

src/praisonai/tests/unit/integrations/test_base_integration.py

@@ -258,6 +258,29 @@ async def stream(self, prompt: str, **options):
         result = await integration.execute("test")
         assert "error" in result
 
+    @pytest.mark.asyncio
+    async def test_execute_async_raises_cli_execution_error(self):
+        """Test that execute_async raises CLIExecutionError on non-zero exit."""
+        from praisonai.integrations.base import BaseCLIIntegration, CLIExecutionError
+
+        class TestIntegration(BaseCLIIntegration):
+            @property
+            def cli_command(self) -> str:
+                return "bash"
+
+            async def execute(self, prompt: str, **options) -> str:
+                return await self.execute_async(["bash", "-c", "echo failure >&2; exit 7"])
+
+            async def stream(self, prompt: str, **options):
+                yield {}
+
+        integration = TestIntegration()
+        with pytest.raises(CLIExecutionError) as exc:
+            await integration.execute("test")
+
+        assert exc.value.returncode == 7
+        assert "failure" in exc.value.stderr
+
 
 class TestAvailabilityCache:
     """Tests for the availability caching mechanism."""

src/praisonai/tests/unit/integrations/test_codex_cli.py

@@ -83,6 +83,7 @@ def test_build_command_basic(self):
 
         assert cmd[0] == "codex"
         assert "exec" in cmd
+        assert "--skip-git-repo-check" in cmd
         assert "Fix the bug" in cmd
 
     def test_build_command_with_full_auto(self):

src/praisonai/tests/unit/integrations/test_cursor_cli.py

@@ -69,6 +69,7 @@ def test_build_command_basic(self):
         assert "Fix the bug" in cmd
         assert "--output-format" in cmd
         assert "json" in cmd
+        assert "--workspace" not in cmd
 
     def test_build_command_with_force(self):
         """Test building command with force flag."""

src/praisonai/tests/unit/integrations/test_gemini_cli.py

@@ -41,7 +41,15 @@ def test_default_options(self):
 
         integration = GeminiCLIIntegration()
         assert integration.output_format == "json"
-        assert integration.model == "gemini-2.5-pro"
+        assert integration.model == "gemini-2.5-flash-lite"
+
+    def test_default_model_reads_environment(self):
+        """Test default model is read from environment when not explicitly set."""
+        from praisonai.integrations.gemini_cli import GeminiCLIIntegration
+
+        with patch.dict(os.environ, {"PRAISONAI_GEMINI_MODEL": "gemini-2.5-pro"}, clear=False):
+            integration = GeminiCLIIntegration()
+            assert integration.model == "gemini-2.5-pro"
 
     def test_custom_model(self):
         """Test custom model can be set."""