New tool: GetReferencingCodeExtractsTool

README.md

@@ -560,6 +560,7 @@ Here the full list of Serena's default tools with a short description (the outpu
  * `find_symbol`: Performs a global (or local) search for symbols with/containing a given name/substring (optionally filtered by type).
  * `get_dir_overview`: Gets an overview of the top-level symbols defined in all files within a given directory.
  * `get_document_overview`: Gets an overview of the top-level symbols defined in a given file.
+ * `get_referencing_code_extracts`: Gets the code blocks that reference the symbol at the given location.
  * `insert_after_symbol`: Inserts content after the end of the definition of a given symbol.
  * `insert_at_line`: Inserts content at a given line in a file.
  * `insert_before_symbol`: Inserts content before the beginning of the definition of a given symbol.
@@ -569,6 +570,7 @@ Here the full list of Serena's default tools with a short description (the outpu
  * `prepare_for_new_conversation`: Provides instructions for preparing for a new conversation (in order to continue with the necessary context).
  * `read_file`: Reads a file within the project directory.
  * `read_memory`: Reads the memory with the given name from Serena's project-specific memory store.
+ * `replace_lines`: Replaces a range of lines within a file with new content.
  * `replace_symbol_body`: Replaces the full definition of a symbol.
  * `search_in_all_code`: Performs a search for a pattern in all code files (and only in code files) in the project.
  * `summarize_changes`: Provides instructions for summarizing the changes made to the codebase.
@@ -576,4 +578,3 @@ Here the full list of Serena's default tools with a short description (the outpu
  * `think_about_task_adherence`: Thinking tool for determining whether the agent is still on track with the current task.
  * `think_about_whether_you_are_done`: Thinking tool for determining whether the task is truly completed.
  * `write_memory`: Writes a named memory (for future reference) to Serena's project-specific memory store.
-

src/serena/agent.py

@@ -536,6 +536,45 @@ class FindReferencingSymbolsTool(Tool):
         return self._limit_length(result, max_answer_chars)
 
 
+class GetReferencingCodeExtractsTool(Tool):
+    """
+    Gets the code blocks that reference the symbol at the given location.
+    """
+
+    def apply(
+        self,
+        relative_path: str,
+        line: int,
+        column: int,
+        context_lines_before: int = 0,
+        context_lines_after: int = 0,
+        max_answer_chars: int = _DEFAULT_MAX_ANSWER_LENGTH,
+    ) -> str:
+        """
+        Returns short code extracts where the symbol at the given location is referenced.
+
+        Contrary to the find_referencing_symbols tool, this tool returns references that are not symbols but instead
+        code extracts that may or may not be contained in a symbol (for example, file-level calls).
+        It may make sense to use this tool if you want to get a quick and dirty overview of the code that references
+        the symbol. Usually just looking at the code extracts is not enough to understand the context,
+        unless the case you are investigating is very simple,
+        or you already have read the relevant symbols using the find_referencing_symbols tool and
+        now want to get an overview of how the referenced symbol (at the given location) is used in them.
+
+        :param relative_path: the relative path to the file containing the symbol
+        :param line: the line number
+        :param column: the column
+        :param context_lines_before: the number of lines to include before the reference
+        :param context_lines_after: the number of lines to include after the reference
+        """
+        matches = self.language_server.request_references_with_content(
+            relative_path, line, column, context_lines_before, context_lines_after
+        )
+        result = [match.to_display_string() for match in matches]
+        result_json_str = json.dumps(result)
+        return self._limit_length(result_json_str, max_answer_chars)
+
+
 class ReplaceSymbolBodyTool(Tool):
     """
     Replaces the full definition of a symbol.