evolv-agent-sdk 0.2.0__py3-none-any.whl

evolv_agent_sdk/_internal/transport/subprocess_cli.py

@@ -0,0 +1,712 @@
+"""Subprocess transport implementation using evolv Code CLI."""
+
+import json
+import logging
+import os
+import platform
+import re
+import shutil
+import sys
+from collections.abc import AsyncIterable, AsyncIterator
+from contextlib import suppress
+from pathlib import Path
+from subprocess import PIPE
+from typing import Any
+
+import anyio
+import anyio.abc
+from anyio.abc import Process
+from anyio.streams.text import TextReceiveStream, TextSendStream
+
+from ..._errors import CLIConnectionError, CLINotFoundError, ProcessError
+from ..._errors import CLIJSONDecodeError as SDKJSONDecodeError
+from ..._version import __version__
+from ...types import EvolvAgentOptions
+from . import Transport
+
+logger = logging.getLogger(__name__)
+
+_DEFAULT_MAX_BUFFER_SIZE = 1024 * 1024  # 1MB buffer limit
+MINIMUM_EVOLV_VERSION = "1.0.0"
+
+# Platform-specific command line length limits
+_CMD_LENGTH_LIMIT = 8000 if platform.system() == "Windows" else 100000
+
+
+class SubprocessCLITransport(Transport):
+    """Subprocess transport using evolv Code CLI.
+
+    When evolv Code CLI is detected, this transport supports full bidirectional
+    streaming mode with:
+    - can_use_tool callback for tool permissions
+    - SDK hooks (PreToolUse, PostToolUse, etc.)
+    - SDK MCP servers (in-process)
+    - Runtime control: interrupt(), set_permission_mode(), set_model()
+
+    For fallback Cortex CLI, it uses print mode (--print "prompt") for one-shot queries.
+    """
+
+    def __init__(
+        self,
+        prompt: str | AsyncIterable[dict[str, Any]],
+        options: EvolvAgentOptions,
+        bidirectional: bool = False,
+    ):
+        self._prompt = prompt
+        self._is_streaming = not isinstance(prompt, str)
+        self._options = options
+        self._cli_path = (
+            str(options.cli_path) if options.cli_path is not None else self._find_cli()
+        )
+        self._cwd = str(options.cwd) if options.cwd else None
+        self._process: Process | None = None
+        self._stdout_stream: TextReceiveStream | None = None
+        self._stdin_stream: TextSendStream | None = None
+        self._stderr_stream: TextReceiveStream | None = None
+        self._stderr_task_group: anyio.abc.TaskGroup | None = None
+        self._ready = False
+        self._exit_error: Exception | None = None
+        self._max_buffer_size = (
+            options.max_buffer_size
+            if options.max_buffer_size is not None
+            else _DEFAULT_MAX_BUFFER_SIZE
+        )
+        self._temp_files: list[str] = []
+        self._write_lock: anyio.Lock = anyio.Lock()
+
+        # Check if we're using evolv CLI (supports bidirectional mode)
+        self._is_evolv_cli = self._detect_evolv_cli()
+        # Enable bidirectional mode if explicitly requested OR if streaming with evolv CLI
+        self._bidirectional_mode = bidirectional or (self._is_evolv_cli and self._is_streaming)
+
+        # For non-bidirectional streaming mode, we need to track prompts
+        self._pending_prompts: list[str] = []
+
+    def _detect_evolv_cli(self) -> bool:
+        """Detect if the CLI is evolv (supports bidirectional mode)."""
+        cli_name = Path(self._cli_path).name.lower()
+        return cli_name.startswith("evolv")
+
+    def _find_cli(self) -> str:
+        """Find evolv Code CLI binary.
+
+        Search order:
+        1. EVOLV_CODE_CLI_PATH environment variable
+        2. CORTEX_CODE_CLI_PATH environment variable (fallback)
+        3. Bundled CLI (if present)
+        4. System PATH - evolv first, then cortex
+        5. Common installation locations
+        """
+        # Check evolv environment variable first
+        env_path = os.environ.get("EVOLV_CODE_CLI_PATH")
+        if env_path and Path(env_path).exists():
+            return env_path
+
+        # Check cortex environment variable (fallback)
+        env_path = os.environ.get("CORTEX_CODE_CLI_PATH")
+        if env_path and Path(env_path).exists():
+            return env_path
+
+        # Check for bundled CLI
+        bundled_cli = self._find_bundled_cli()
+        if bundled_cli:
+            return bundled_cli
+
+        # Check system PATH - evolv first
+        if cli := shutil.which("evolv"):
+            return cli
+        if cli := shutil.which("cortex"):
+            return cli
+
+        # Check common locations - evolv first
+        locations = [
+            # evolv locations
+            Path.home() / ".local/bin/evolv",
+            Path("/usr/local/bin/evolv"),
+            Path.home() / ".evolv/local/evolv",
+            # cortex fallback locations
+            Path.home() / ".local/bin/cortex",
+            Path("/usr/local/bin/cortex"),
+            Path.home() / ".cortex/local/cortex",
+            Path.home() / ".snowflake/cortex/cortex",
+            Path.home() / "node_modules/.bin/cortex",
+            Path.home() / ".npm-global/bin/cortex",
+            Path.home() / ".yarn/bin/cortex",
+        ]
+
+        for path in locations:
+            if path.exists() and path.is_file():
+                return str(path)
+
+        raise CLINotFoundError(
+            "evolv Code not found. Install from:\n"
+            "  https://github.com/evolv-ai/evolv-code\n"
+            "\nOr provide the path via EvolvAgentOptions:\n"
+            "  EvolvAgentOptions(cli_path='/path/to/evolv')\n"
+            "\nOr set the EVOLV_CODE_CLI_PATH environment variable."
+        )
+
+    def _find_bundled_cli(self) -> str | None:
+        """Find bundled CLI binary if it exists."""
+        # Check for evolv first
+        cli_name = "evolv.exe" if platform.system() == "Windows" else "evolv"
+        bundled_path = Path(__file__).parent.parent.parent / "_bundled" / cli_name
+
+        if bundled_path.exists() and bundled_path.is_file():
+            logger.info(f"Using bundled evolv Code CLI: {bundled_path}")
+            return str(bundled_path)
+
+        # Fall back to cortex
+        cli_name = "cortex.exe" if platform.system() == "Windows" else "cortex"
+        bundled_path = Path(__file__).parent.parent.parent / "_bundled" / cli_name
+
+        if bundled_path.exists() and bundled_path.is_file():
+            logger.info(f"Using bundled Cortex Code CLI: {bundled_path}")
+            return str(bundled_path)
+
+        return None
+
+    def _build_settings_value(self) -> str | None:
+        """Build settings value, merging sandbox settings if provided."""
+        has_settings = self._options.settings is not None
+        has_sandbox = self._options.sandbox is not None
+
+        if not has_settings and not has_sandbox:
+            return None
+
+        if has_settings and not has_sandbox:
+            return self._options.settings
+
+        settings_obj: dict[str, Any] = {}
+
+        if has_settings:
+            assert self._options.settings is not None
+            settings_str = self._options.settings.strip()
+            if settings_str.startswith("{") and settings_str.endswith("}"):
+                try:
+                    settings_obj = json.loads(settings_str)
+                except json.JSONDecodeError:
+                    logger.warning(
+                        f"Failed to parse settings as JSON, treating as file path: {settings_str}"
+                    )
+                    settings_path = Path(settings_str)
+                    if settings_path.exists():
+                        with settings_path.open(encoding="utf-8") as f:
+                            settings_obj = json.load(f)
+            else:
+                settings_path = Path(settings_str)
+                if settings_path.exists():
+                    with settings_path.open(encoding="utf-8") as f:
+                        settings_obj = json.load(f)
+                else:
+                    logger.warning(f"Settings file not found: {settings_path}")
+
+        if has_sandbox:
+            settings_obj["sandbox"] = self._options.sandbox
+
+        return json.dumps(settings_obj)
+
+    def _build_command(self, prompt: str | None = None) -> list[str]:
+        """Build CLI command with arguments.
+
+        For evolv CLI in bidirectional mode:
+        - --input-format stream-json
+        - --output-format stream-json
+
+        For cortex CLI or non-bidirectional mode:
+        - --output-format stream-json
+        - --dangerously-allow-all-tool-calls
+        - -p/--print "prompt"
+        """
+        cmd = [self._cli_path, "--output-format", "stream-json"]
+
+        # Enable bidirectional mode for evolv CLI with streaming
+        if self._bidirectional_mode:
+            cmd.extend(["--input-format", "stream-json"])
+            # CLI requires --dangerously-allow-all-tool-calls for stream-json mode
+            cmd.append("--dangerously-allow-all-tool-calls")
+        else:
+            # For non-bidirectional mode, also require dangerously-allow-all
+            cmd.append("--dangerously-allow-all-tool-calls")
+
+        # Working directory
+        if self._cwd:
+            cmd.extend(["-w", self._cwd])
+
+        # Model selection
+        if self._options.model:
+            cmd.extend(["--model", self._options.model])
+
+        # Resume session
+        if self._options.resume:
+            cmd.extend(["--resume", self._options.resume])
+
+        # Continue most recent session
+        if self._options.continue_conversation:
+            cmd.append("--continue")
+
+        # Handle settings/config
+        settings_value = self._build_settings_value()
+        if settings_value:
+            cmd.extend(["--config", settings_value])
+
+        # Extra args for future CLI flags
+        for flag, value in self._options.extra_args.items():
+            if value is None:
+                cmd.append(f"--{flag}")
+            else:
+                cmd.extend([f"--{flag}", str(value)])
+
+        # Add prompt for non-bidirectional mode
+        if not self._bidirectional_mode:
+            actual_prompt = prompt if prompt is not None else self._prompt
+            if isinstance(actual_prompt, str):
+                cmd.extend(["--print", actual_prompt])
+            else:
+                # For streaming mode without bidirectional support
+                raise CLIConnectionError(
+                    "CLI does not support bidirectional streaming mode. "
+                    "Use evolv CLI or query() with a string prompt."
+                )
+
+        return cmd
+
+    async def connect(self) -> None:
+        """Start subprocess."""
+        if self._process:
+            return
+
+        # For bidirectional mode (evolv CLI with streaming), start the process now
+        if self._bidirectional_mode:
+            if not os.environ.get("EVOLV_AGENT_SDK_SKIP_VERSION_CHECK"):
+                await self._check_cli_version()
+            cmd = self._build_command()
+            await self._start_process(cmd, keep_stdin_open=True)
+            return
+
+        # For non-bidirectional streaming mode, defer process start
+        if self._is_streaming:
+            self._ready = True
+            return
+
+        if not os.environ.get("EVOLV_AGENT_SDK_SKIP_VERSION_CHECK"):
+            await self._check_cli_version()
+
+        cmd = self._build_command()
+        await self._start_process(cmd)
+
+    async def _start_process(
+        self, cmd: list[str], keep_stdin_open: bool = False
+    ) -> None:
+        """Start the CLI process with the given command."""
+        try:
+            process_env = {
+                **os.environ,
+                **self._options.env,
+                "EVOLV_CODE_ENTRYPOINT": "sdk-py",
+                "EVOLV_AGENT_SDK_VERSION": __version__,
+            }
+
+            if self._options.enable_file_checkpointing:
+                process_env["EVOLV_CODE_ENABLE_SDK_FILE_CHECKPOINTING"] = "true"
+
+            should_pipe_stderr = (
+                self._options.stderr is not None
+                or "debug-to-stderr" in self._options.extra_args
+            )
+
+            stderr_dest = PIPE if should_pipe_stderr else None
+
+            self._process = await anyio.open_process(
+                cmd,
+                stdin=PIPE,
+                stdout=PIPE,
+                stderr=stderr_dest,
+                cwd=self._cwd,
+                env=process_env,
+                user=self._options.user,
+            )
+
+            if self._process.stdout:
+                self._stdout_stream = TextReceiveStream(self._process.stdout)
+
+            if self._process.stdin and keep_stdin_open:
+                self._stdin_stream = TextSendStream(self._process.stdin)
+            elif self._process.stdin:
+                # Close stdin immediately for non-bidirectional mode
+                await self._process.stdin.aclose()
+
+            if should_pipe_stderr and self._process.stderr:
+                self._stderr_stream = TextReceiveStream(self._process.stderr)
+                self._stderr_task_group = anyio.create_task_group()
+                await self._stderr_task_group.__aenter__()
+                self._stderr_task_group.start_soon(self._handle_stderr)
+
+            self._ready = True
+
+        except FileNotFoundError as e:
+            if self._cwd and not Path(self._cwd).exists():
+                error = CLIConnectionError(
+                    f"Working directory does not exist: {self._cwd}"
+                )
+                self._exit_error = error
+                raise error from e
+            error = CLINotFoundError(f"evolv Code not found at: {self._cli_path}")
+            self._exit_error = error
+            raise error from e
+        except Exception as e:
+            error = CLIConnectionError(f"Failed to start evolv Code: {e}")
+            self._exit_error = error
+            raise error from e
+
+    async def _handle_stderr(self) -> None:
+        """Handle stderr stream."""
+        if not self._stderr_stream:
+            return
+
+        try:
+            async for line in self._stderr_stream:
+                line_str = line.rstrip()
+                if not line_str:
+                    continue
+
+                if self._options.stderr:
+                    self._options.stderr(line_str)
+                elif (
+                    "debug-to-stderr" in self._options.extra_args
+                    and self._options.debug_stderr
+                ):
+                    self._options.debug_stderr.write(line_str + "\n")
+                    if hasattr(self._options.debug_stderr, "flush"):
+                        self._options.debug_stderr.flush()
+        except anyio.ClosedResourceError:
+            pass
+        except Exception:
+            pass
+
+    async def close(self) -> None:
+        """Close the transport and clean up resources."""
+        for temp_file in self._temp_files:
+            with suppress(Exception):
+                Path(temp_file).unlink(missing_ok=True)
+        self._temp_files.clear()
+
+        if not self._process:
+            self._ready = False
+            return
+
+        if self._stderr_task_group:
+            with suppress(Exception):
+                self._stderr_task_group.cancel_scope.cancel()
+                await self._stderr_task_group.__aexit__(None, None, None)
+            self._stderr_task_group = None
+
+        async with self._write_lock:
+            self._ready = False
+            if self._stdin_stream:
+                with suppress(Exception):
+                    await self._stdin_stream.aclose()
+                self._stdin_stream = None
+
+        if self._stderr_stream:
+            with suppress(Exception):
+                await self._stderr_stream.aclose()
+            self._stderr_stream = None
+
+        if self._process.returncode is None:
+            with suppress(ProcessLookupError):
+                self._process.terminate()
+                with suppress(Exception):
+                    await self._process.wait()
+
+        self._process = None
+        self._stdout_stream = None
+        self._stdin_stream = None
+        self._stderr_stream = None
+        self._exit_error = None
+
+    async def write(self, data: str) -> None:
+        """Write raw data to the transport.
+
+        For bidirectional mode (evolv CLI), writes directly to stdin.
+        For non-bidirectional mode, queues messages for separate queries.
+        """
+        async with self._write_lock:
+            if not self._ready:
+                raise CLIConnectionError("ProcessTransport is not ready for writing")
+
+            if self._bidirectional_mode and self._stdin_stream:
+                # Bidirectional mode: write directly to stdin
+                await self._stdin_stream.send(data)
+            else:
+                # Non-bidirectional mode: queue prompts
+                try:
+                    msg = json.loads(data.strip())
+                    if msg.get("type") == "user":
+                        content = msg.get("message", {}).get("content", "")
+                        if isinstance(content, str) and content:
+                            self._pending_prompts.append(content)
+                except json.JSONDecodeError:
+                    pass
+
+    async def end_input(self) -> None:
+        """End the input stream."""
+        if self._bidirectional_mode and self._stdin_stream:
+            async with self._write_lock:
+                with suppress(Exception):
+                    await self._stdin_stream.aclose()
+                self._stdin_stream = None
+
+    def read_messages(self) -> AsyncIterator[dict[str, Any]]:
+        """Read and parse messages from the transport."""
+        return self._read_messages_impl()
+
+    async def _read_messages_impl(self) -> AsyncIterator[dict[str, Any]]:
+        """Internal implementation of read_messages."""
+        # For non-bidirectional streaming mode with pending prompts
+        if self._is_streaming and not self._bidirectional_mode and self._pending_prompts:
+            for prompt in self._pending_prompts:
+                cmd = self._build_command_for_prompt(prompt)
+                async for msg in self._run_single_query(cmd):
+                    yield msg
+            self._pending_prompts.clear()
+            return
+
+        # For normal mode, read from the existing process
+        if not self._process or not self._stdout_stream:
+            raise CLIConnectionError("Not connected")
+
+        json_buffer = ""
+
+        try:
+            async for line in self._stdout_stream:
+                line_str = line.strip()
+                if not line_str:
+                    continue
+
+                json_lines = line_str.split("\n")
+
+                for json_line in json_lines:
+                    json_line = json_line.strip()
+                    if not json_line:
+                        continue
+
+                    json_buffer += json_line
+
+                    if len(json_buffer) > self._max_buffer_size:
+                        buffer_length = len(json_buffer)
+                        json_buffer = ""
+                        raise SDKJSONDecodeError(
+                            f"JSON message exceeded maximum buffer size of {self._max_buffer_size} bytes",
+                            ValueError(
+                                f"Buffer size {buffer_length} exceeds limit {self._max_buffer_size}"
+                            ),
+                        )
+
+                    try:
+                        data = json.loads(json_buffer)
+                        json_buffer = ""
+
+                        # Transform output to match SDK expectations
+                        transformed_data = self._transform_output(data)
+                        yield transformed_data
+                    except json.JSONDecodeError:
+                        continue
+
+        except anyio.ClosedResourceError:
+            pass
+        except GeneratorExit:
+            pass
+
+        try:
+            returncode = await self._process.wait()
+        except Exception:
+            returncode = -1
+
+        if returncode is not None and returncode != 0:
+            self._exit_error = ProcessError(
+                f"Command failed with exit code {returncode}",
+                exit_code=returncode,
+                stderr="Check stderr output for details",
+            )
+            raise self._exit_error
+
+    def _build_command_for_prompt(self, prompt: str) -> list[str]:
+        """Build a command for a specific prompt (non-bidirectional mode)."""
+        cmd = [self._cli_path, "--output-format", "stream-json"]
+        cmd.append("--dangerously-allow-all-tool-calls")
+
+        if self._cwd:
+            cmd.extend(["-w", self._cwd])
+
+        if self._options.model:
+            cmd.extend(["--model", self._options.model])
+
+        if self._options.resume:
+            cmd.extend(["--resume", self._options.resume])
+
+        if self._options.continue_conversation:
+            cmd.append("--continue")
+
+        settings_value = self._build_settings_value()
+        if settings_value:
+            cmd.extend(["--config", settings_value])
+
+        for flag, value in self._options.extra_args.items():
+            if value is None:
+                cmd.append(f"--{flag}")
+            else:
+                cmd.extend([f"--{flag}", str(value)])
+
+        cmd.extend(["--print", prompt])
+        return cmd
+
+    async def _run_single_query(self, cmd: list[str]) -> AsyncIterator[dict[str, Any]]:
+        """Run a single query command and yield messages."""
+        process_env = {
+            **os.environ,
+            **self._options.env,
+            "EVOLV_CODE_ENTRYPOINT": "sdk-py",
+            "EVOLV_AGENT_SDK_VERSION": __version__,
+        }
+
+        process = await anyio.open_process(
+            cmd,
+            stdin=PIPE,
+            stdout=PIPE,
+            stderr=PIPE,
+            cwd=self._cwd,
+            env=process_env,
+            user=self._options.user,
+        )
+
+        if process.stdin:
+            await process.stdin.aclose()
+
+        if not process.stdout:
+            return
+
+        stdout_stream = TextReceiveStream(process.stdout)
+        json_buffer = ""
+
+        try:
+            async for line in stdout_stream:
+                line_str = line.strip()
+                if not line_str:
+                    continue
+
+                for json_line in line_str.split("\n"):
+                    json_line = json_line.strip()
+                    if not json_line:
+                        continue
+
+                    json_buffer += json_line
+
+                    try:
+                        data = json.loads(json_buffer)
+                        json_buffer = ""
+                        yield self._transform_output(data)
+                    except json.JSONDecodeError:
+                        continue
+        except anyio.ClosedResourceError:
+            pass
+
+        await process.wait()
+
+    def _transform_output(self, data: dict[str, Any]) -> dict[str, Any]:
+        """Transform CLI output to match SDK expectations.
+
+        Adds missing fields:
+        - message.content[].signature -> "" for thinking blocks
+        - message.usage -> {input_tokens: 0, output_tokens: 0}
+        - result.duration_ms -> 0
+        - result.duration_api_ms -> 0
+        - result.num_turns -> 1
+        - result.cost_usd -> 0
+        - result.is_error -> derived from subtype
+        """
+        msg_type = data.get("type")
+
+        if msg_type == "assistant":
+            message = data.get("message", {})
+
+            # Add missing usage field
+            if "usage" not in message:
+                message["usage"] = {"input_tokens": 0, "output_tokens": 0}
+
+            # Add missing signature field to thinking blocks
+            content = message.get("content", [])
+            for block in content:
+                if block.get("type") == "thinking" and "signature" not in block:
+                    block["signature"] = ""
+
+            # Ensure model field exists
+            if "model" not in message:
+                message["model"] = "evolv"
+
+            data["message"] = message
+
+        elif msg_type == "result":
+            # Add missing fields with placeholder values
+            if "duration_ms" not in data:
+                data["duration_ms"] = 0
+            if "duration_api_ms" not in data:
+                data["duration_api_ms"] = 0
+            if "num_turns" not in data:
+                data["num_turns"] = 1
+            if "total_cost_usd" not in data:
+                data["total_cost_usd"] = 0
+            if "is_error" not in data:
+                data["is_error"] = data.get("subtype") != "success"
+            if "session_id" not in data:
+                data["session_id"] = "evolv-session"
+            if "usage" not in data:
+                data["usage"] = {"input_tokens": 0, "output_tokens": 0}
+
+        return data
+
+    async def _check_cli_version(self) -> None:
+        """Check CLI version and warn if below minimum."""
+        version_process = None
+        try:
+            with anyio.fail_after(2):
+                version_process = await anyio.open_process(
+                    [self._cli_path, "--version"],
+                    stdout=PIPE,
+                    stderr=PIPE,
+                )
+
+                if version_process.stdout:
+                    stdout_bytes = await version_process.stdout.receive()
+                    version_output = stdout_bytes.decode().strip()
+
+                    match = re.match(r"v?([0-9]+\.[0-9]+\.[0-9]+)", version_output)
+                    if match:
+                        version = match.group(1)
+                        version_parts = [int(x) for x in version.split(".")]
+                        min_parts = [int(x) for x in MINIMUM_EVOLV_VERSION.split(".")]
+
+                        if version_parts < min_parts:
+                            warning = (
+                                f"Warning: CLI version {version} may be unsupported. "
+                                f"Minimum recommended version is {MINIMUM_EVOLV_VERSION}. "
+                                "Some features may not work correctly."
+                            )
+                            logger.warning(warning)
+                            print(warning, file=sys.stderr)
+        except Exception:
+            pass
+        finally:
+            if version_process:
+                with suppress(Exception):
+                    version_process.terminate()
+                with suppress(Exception):
+                    await version_process.wait()
+
+    def is_ready(self) -> bool:
+        """Check if transport is ready for communication."""
+        return self._ready
+
+    def is_bidirectional(self) -> bool:
+        """Check if transport is in bidirectional mode."""
+        return self._bidirectional_mode