Merge branch 'main' into features/diagnostics_and_ls_extensions

Author: MischaPanch

.serena/project.yml

@@ -3,15 +3,18 @@ project_name: "serena"
 
 
 # list of languages for which language servers are started; choose from:
-#   al                  bash                clojure             cpp                 csharp
-#   csharp_omnisharp    dart                elixir              elm                 erlang
-#   fortran             fsharp              go                  groovy              haskell
-#   java                julia               kotlin              lua                 markdown
-#   matlab              nix                 pascal              perl                php
-#   php_phpactor        powershell          python              python_jedi         r
-#   rego                ruby                ruby_solargraph     rust                scala
-#   swift               terraform           toml                typescript          typescript_vts
-#   vue                 yaml                zig
+#   al                  ansible             bash                clojure             cpp
+#   cpp_ccls            crystal             csharp              csharp_omnisharp    dart
+#   elixir              elm                 erlang              fortran             fsharp
+#   go                  groovy              haskell             haxe                hlsl
+#   java                json                julia               kotlin              lean4
+#   lua                 luau                markdown            matlab              msl
+#   nix                 ocaml               pascal              perl                php
+#   php_phpactor        powershell          python              python_jedi         python_ty
+#   r                   rego                ruby                ruby_solargraph     rust
+#   scala               solidity            swift               systemverilog       terraform
+#   toml                typescript          typescript_vts      vue                 yaml
+#   zig
 #   (This list may be outdated. For the current list, see values of Language enum here:
 #   https://github.com/oraios/serena/blob/main/src/solidlsp/ls_config.py
 #   For some languages, there are alternative language servers, e.g. csharp_omnisharp, ruby_solargraph.)
@@ -45,49 +48,12 @@ read_only: false
 
 # list of tool names to exclude.
 # This extends the existing exclusions (e.g. from the global configuration)
-#
-# Below is the complete list of tools for convenience.
-# To make sure you have the latest list of tools, and to view their descriptions, 
-# execute `uv run scripts/print_tool_overview.py`.
-#  * `activate_project`: Activates a project based on the project name or path.
-#  * `check_onboarding_performed`: Checks whether project onboarding was already performed.
-#  * `create_text_file`: Creates/overwrites a file in the project directory.
-#  * `delete_memory`: Delete a memory file. Should only happen if a user asks for it explicitly,
-#       for example by saying that the information retrieved from a memory file is no longer correct
-#       or no longer relevant for the project.
-#  * `edit_memory`: Replaces content matching a regular expression in a memory.
-#  * `execute_shell_command`: Executes a shell command.
-#  * `find_file`: Finds files in the given relative paths
-#  * `find_referencing_symbols`: Finds symbols that reference the given symbol using the language server backend
-#  * `find_symbol`: Performs a global (or local) search using the language server backend.
-#  * `get_current_config`: Prints the current configuration of the agent, including the active and available projects, tools, contexts, and modes.
-#  * `get_symbols_overview`: Gets an overview of the top-level symbols defined in a given file.
-#  * `initial_instructions`: Provides instructions Serena usage (i.e. the 'Serena Instructions Manual')
-#       for clients that do not read the initial instructions when the MCP server is connected.
-#  * `insert_after_symbol`: Inserts content after the end of the definition of a given symbol.
-#  * `insert_before_symbol`: Inserts content before the beginning of the definition of a given symbol.
-#  * `list_dir`: Lists files and directories in the given directory (optionally with recursion).
-#  * `list_memories`: List available memories. Any memory can be read using the `read_memory` tool.
-#  * `onboarding`: Performs onboarding (identifying the project structure and essential tasks, e.g. for testing or building).
-#  * `read_file`: Reads a file within the project directory.
-#  * `read_memory`: Read the content of a memory file. This tool should only be used if the information
-#       is relevant to the current task. You can infer whether the information
-#       is relevant from the memory file name.
-#       You should not read the same memory file multiple times in the same conversation.
-#  * `rename_memory`: Renames or moves a memory. Moving between project and global scope is supported
-#       (e.g., renaming "global/foo" to "bar" moves it from global to project scope).
-#  * `rename_symbol`: Renames a symbol throughout the codebase using language server refactoring capabilities.
-#       For JB, we use a separate tool.
-#  * `replace_content`: Replaces content in a file (optionally using regular expressions).
-#  * `replace_symbol_body`: Replaces the full definition of a symbol using the language server backend.
-#  * `safe_delete_symbol`:
-#  * `search_for_pattern`: Performs a search for a pattern in the project.
-#  * `write_memory`: Write some information (utf-8-encoded) about this project that can be useful for future tasks to a memory in md format.
-#       The memory name should be meaningful.
+# Find the list of tools here: https://oraios.github.io/serena/01-about/035_tools.html
 excluded_tools: []
 
 # list of tools to include that would otherwise be disabled (particularly optional tools that are disabled by default).
 # This extends the existing inclusions (e.g. from the global configuration).
+# Find the list of tools here: https://oraios.github.io/serena/01-about/035_tools.html
 included_optional_tools: []
 
 # initial prompt for the project. It will always be given to the LLM upon activating the project
@@ -122,14 +88,17 @@ encoding: utf-8
 base_modes:
 
 # list of mode names that are to be activated by default.
-# The full set of modes to be activated is base_modes + default_modes.
+# The full set of modes to be activated is base_modes (from global config) + default_modes + added_modes.
 # If the setting is undefined, the default_modes from the global configuration (serena_config.yml) apply.
 # Otherwise, this overrides the setting from the global configuration (serena_config.yml).
 # This setting can, in turn, be overridden by CLI parameters (--mode).
+# Set this to [] to not use the default modes defined in the global config for this project.
+# See https://oraios.github.io/serena/02-usage/050_configuration.html#modes
 default_modes:
 
 # fixed set of tools to use as the base tool set (if non-empty), replacing Serena's default set of tools.
 # This cannot be combined with non-empty excluded_tools or included_optional_tools.
+# Find the list of tools here: https://oraios.github.io/serena/01-about/035_tools.html
 fixed_tools: []
 
 # time budget (seconds) per tool call for the retrieval of additional symbol information
@@ -167,3 +136,10 @@ ignored_memory_patterns: []
 # Have a look at the docstring of the constructors of the LS implementations within solidlsp (e.g., for C# or PHP) to see which options are available.
 # No documentation on options means no options are available.
 ls_specific_settings: {}
+
+# list of mode names to be activated additionally for this project.
+# The full set of modes to be activated is base_modes (from global config) + default_modes + added_modes.
+# Otherwise, this setting overrides the global configuration.
+# Set this to a list of mode names to always include the respective modes for this project.
+# See https://oraios.github.io/serena/02-usage/050_configuration.html#modes
+added_modes:

CHANGELOG.md

@@ -2,6 +2,12 @@
 
 Status of the `main` branch. Changes prior to the next official version change will appear here.
 
+* General:
+  - Breaking change in mode definitions: Projects (project.yml) can no longer override `base_modes`.
+    Instead, they can define `added_modes` to add modes on top of base and default modes.  
+    See updated [documentation on modes](https://oraios.github.io/serena/02-usage/050_configuration.html#modes).
+  - Serena's default configuration now uses `interactive` and `editing` as `base_modes` instead of as `default_modes`. 
+
 * Language Servers:
   - Java (`eclipse.jdt.ls`): Add upstream JDTLS mode for offline / restricted-network use. Setting both `jdtls_path` and `lombok_path` in `ls_specific_settings.java` makes Serena use an existing upstream JDTLS installation (e.g. `brew install jdtls`) and the system JDK 21+, skipping the ~500 MB vscode-java VSIX, Gradle, and IntelliCode downloads. New related setting `java_home` lets the user override the JDK used to launch JDTLS. Default behavior unchanged — the JDTLS workspace hash is preserved bit-for-bit for users on the default route, so existing project caches are reused without a one-time reindex; the launcher path is mixed into the hash only when `jdtls_path` is set, isolating upstream installations from the default workspace. #1415
 

README.md

@@ -4,7 +4,7 @@
 </p>
 
 <h3 align="center">
-    Serena is the IDE for your coding agent.
+    The IDE for Your Coding Agent
 </h3>
 
 <div align="center">

docs/02-usage/050_configuration.md

@@ -118,32 +118,26 @@ Examples of built-in modes include:
 
 Find the concrete definitions of these modes [here](https://github.com/oraios/serena/tree/main/src/serena/resources/config/modes).
 
-Active modes are configured in (from lowest to highest precedence):
+The modes to be activated are configured in:
   * the global configuration file (`serena_config.yml`)
+     - defines `base_modes`, which are always included
+     - defines `default_modes`, which can be overridden by projects or command line parameters
   * the project configuration file (`project.yml`)
+     - defines `default_modes` (overriding the default modes in the global configuration)
+     - defines `added_modes`, which are added on top
   * at startup via command-line parameters
-
-The two former sources define both **base modes** and **default modes**.
-Ultimately, the active modes are the union of base modes and default modes (after applying all overrides).
-Command-line parameters override default modes but not base modes.
-Base modes should thus be used to define modes that you always want to be active, regardless of command-line parameters.
-
-Command-line parameters for overriding default modes:
-When launching the MCP sever, specify modes using `--mode <mode-name>`; multiple modes can be specified, e.g. `--mode planning --mode no-onboarding`.
-
-:::{important}
-By default, Serena activates the two modes `interactive` and `editing` (as defined in the global configuration).
-
-As soon as you start to specify modes via the command line, only the modes you explicitly specify will be active, however.
-Therefore, if you want to keep the default modes, you must specify them as well.  
-For example, to add mode `no-memories` to the default behaviour, specify
-```shell
---mode interactive --mode editing --mode no-memories
-```
-
-If you want to keep certain modes as always active, regardless of command-line parameters, 
-define them as *base modes* in the global or project configuration.
-:::
+     - can override default modes with `--mode`
+     - can define modes to be added on top with `--add-mode`
+
+Ultimately, the active modes are given by the union of 
+  * `base_modes` defined in the global configuration (always active)  
+  * `default_modes` (defined in the global configuration, optionally overridden by the project/CLI)
+  * `added_modes` (defined in the project configuration/via CLI parameters)
+
+So you should 
+ * define modes you definitely always want to use in `base_modes`,
+ * define modes that you typically want to use but sometimes want to override in `default_modes`,
+ * use `added_modes` to add modes that you need only for specific projects/sessions.
 
 :::{note}
 **Mode Compatibility**: While you can combine modes, some may be semantically incompatible (e.g., `interactive` and `one-shot`). 

src/serena/agent.py

@@ -31,6 +31,8 @@
 from serena.config.serena_config import (
     LanguageBackend,
     ModeSelectionDefinition,
+    ModeSelectionDefinitionWithAddedModes,
+    ModeSelectionDefinitionWithBaseModes,
     NamedToolInclusionDefinition,
     RegisteredProject,
     SerenaConfig,
@@ -206,18 +208,36 @@ class ActiveModes:
     def __init__(self) -> None:
         self._configured_base_modes: Sequence[str] | None = None
         self._configured_default_modes: Sequence[str] | None = None
+        self._added_modes: set[str] = set()
+        self._dynamically_activated_mode_names: set[str] = set()
+        """
+        the subset of active mode names that are dynamically activated (not necessarily enabled after project change)
+        """
         self._active_mode_names: Sequence[str] = []
+        """
+        the full list of active mode names
+        """
 
     def apply(self, mode_selection: ModeSelectionDefinition) -> None:
+        log.debug("Applying mode selection definition %s", mode_selection)
+
         # apply overrides
-        log.debug("Applying mode selection: default_modes=%s, base_modes=%s", mode_selection.default_modes, mode_selection.base_modes)
-        if mode_selection.base_modes is not None:
-            self._configured_base_modes = mode_selection.base_modes
+        if isinstance(mode_selection, ModeSelectionDefinitionWithBaseModes):
+            if mode_selection.base_modes is not None:
+                self._configured_base_modes = mode_selection.base_modes
         if mode_selection.default_modes is not None:
             self._configured_default_modes = mode_selection.default_modes
         log.debug("Current mode selection: base_modes=%s, default_modes=%s", self._configured_base_modes, self._configured_default_modes)
 
-        self._active_mode_names = sorted(set(self._configured_base_modes or []) | set(self._configured_default_modes or []))
+        # apply added modes (if any)
+        if isinstance(mode_selection, ModeSelectionDefinitionWithAddedModes):
+            if mode_selection.added_modes:
+                log.debug("Adding modes: %s", mode_selection.added_modes)
+                self._added_modes.update(mode_selection.added_modes)
+                log.debug("Current added modes: %s", self._added_modes)
+
+        self._dynamically_activated_mode_names = set(self._configured_default_modes or []) | self._added_modes
+        self._active_mode_names = sorted(set(self._configured_base_modes or []) | self._dynamically_activated_mode_names)
 
     def get_mode_names(self) -> Sequence[str]:
         return self._active_mode_names
@@ -231,8 +251,8 @@ def get_mode_instance(cls, mode_name: str) -> SerenaAgentMode:
     def get_modes(self) -> Sequence[SerenaAgentMode]:
         return [self.get_mode_instance(mode_name) for mode_name in self._active_mode_names]
 
-    def get_default_modes(self) -> Sequence[SerenaAgentMode]:
-        return [self.get_mode_instance(mode_name) for mode_name in self._configured_default_modes or []]
+    def get_dynamically_activated_modes(self) -> Sequence[SerenaAgentMode]:
+        return [self.get_mode_instance(mode_name) for mode_name in self._dynamically_activated_mode_names]
 
     def get_base_modes(self) -> Sequence[SerenaAgentMode]:
         return [self.get_mode_instance(mode_name) for mode_name in self._configured_base_modes or []]
@@ -511,8 +531,7 @@ def __init__(
         :param serena_config: the Serena configuration or None to read the configuration from the default location.
         :param context: the context in which the agent is operating, None for default context.
             The context may adjust prompts, tool availability, and tool descriptions.
-        :param modes: list of modes in which the agent is operating (they will be combined), None for default modes.
-            The modes may adjust prompts, tool availability, and tool descriptions.
+        :param modes: mode selection definition to apply for this session
         :param memory_log_handler: a MemoryLogHandler instance from which to read log messages; if None, a new one will be created
             if necessary.
         """
@@ -521,7 +540,7 @@ def __init__(
         self._gui_log_viewer: Optional["GuiLogViewer"] = None
         self._dashboard_manager: DashboardManager | None = None
         self._project_prompt_status = ProjectPromptProvisionStatus()
-        self._mode_overrides = modes
+        self._session_mode_selection_definition = modes
         self.version = serena_version()
 
         # obtain serena configuration using the decoupled factory function
@@ -712,9 +731,11 @@ def _create_base_toolset(
         # * base modes: These cannot be changed, so they are fully applied
         for base_mode in modes.get_base_modes():
             tool_inclusion_definitions.append(base_mode)
-        # * default modes: When not in a single-project context, these modes are dynamic (can later be turned off),
-        #   so we consider only their inclusions (but not their exclusions, because these must not be hard)
-        for mode in modes.get_default_modes():
+        # * dynamically activated modes:
+        #    - When not in a single-project context, these modes can later be turned off,
+        #      so we consider only their inclusions (but not their exclusions, because these must not be hard).
+        #    - In a single-project context, we can consider them fully.
+        for mode in modes.get_dynamically_activated_modes():
             if is_single_project:
                 tool_inclusion_definitions.append(mode)
             else:
@@ -986,8 +1007,8 @@ def _update_active_modes(self, log_message: bool = True) -> None:
         self._active_modes.apply(self.serena_config)
         if self._active_project:
             self._active_modes.apply(self._active_project.project_config)
-        if self._mode_overrides:
-            self._active_modes.apply(self._mode_overrides)
+        if self._session_mode_selection_definition:
+            self._active_modes.apply(self._session_mode_selection_definition)
         if log_message:
             active_mode_names = self._active_modes.get_mode_names()
             log.info(f"Active modes ({len(active_mode_names)}): {', '.join(active_mode_names)}")