From 10b89f28aede9005d165852004f230d7b02add5e Mon Sep 17 00:00:00 2001
From: Slipstream <me@slipstreamm.dev>
Date: Wed, 11 Jun 2025 23:02:11 +0000
Subject: [PATCH] docs: sync tool guide and components

---
 docs/ai_agent_tool_syntax_v2_xml.md | 168 ++++++++++++++++++++++++----
 docs/components.md                  |   8 +-
 2 files changed, 150 insertions(+), 26 deletions(-)

diff --git a/docs/ai_agent_tool_syntax_v2_xml.md b/docs/ai_agent_tool_syntax_v2_xml.md
index 6c78d18..a4142c9 100644
--- a/docs/ai_agent_tool_syntax_v2_xml.md
+++ b/docs/ai_agent_tool_syntax_v2_xml.md
@@ -1,24 +1,25 @@
-# Project: Refactor AI Agent Tool Syntax to XML
+# AI Agent XML Tool Syntax
 
-**Date:** 2025-05-31
+**Updated:** 2025-06-11
 
-**Goal:** To refactor the AI agent's tool calling mechanism from a custom regex-parsed format to a standardized XML-based format. This aims to improve robustness, ease of AI generation, parsing simplicity, extensibility, and standardization.
+The AI agent defined in `cogs/ai_code_agent_cog.py` uses an XML-based format for all tool calls. When the agent needs to perform an action it responds **only** with an XML block. The name of the root element corresponds to the tool to invoke and the child elements provide the parameters.
 
-**1. Current State:**
-The AI agent in `cogs/ai_code_agent_cog.py` uses a custom, line-based syntax for tool calls, defined in `AGENT_SYSTEM_PROMPT` and parsed using regular expressions in `_parse_and_execute_tool_call`.
+The following sections document the currently supported tools and their parameters.
 
-**2. Proposed Change: XML-Based Tool Calls**
-
-The AI will be instructed to output *only* an XML block when calling a tool. The root element of the XML block will be the tool's name.
-
-**2.1. New XML Tool Call Syntax Definitions:**
+**Tool Call Syntax Examples:**
 
 *   **ReadFile:**
-    ```xml
-    <ReadFile>
-      <path>path/to/file.ext</path>
-    </ReadFile>
-    ```
+```xml
+<ReadFile>
+  <path>path/to/file.ext</path>
+  <!-- Optional line range -->
+  <start_line>10</start_line>
+  <end_line>20</end_line>
+  <!-- Optional peeking helpers -->
+  <peek_first_n_lines>5</peek_first_n_lines>
+  <peek_last_n_lines>5</peek_last_n_lines>
+</ReadFile>
+```
 
 *   **WriteFile:**
     ```xml
@@ -56,12 +57,16 @@ The AI will be instructed to output *only* an XML block when calling a tool. The
     ```
 
 *   **ListFiles:**
-    ```xml
-    <ListFiles>
-      <path>path/to/search</path>
-      <recursive>true</recursive> <!-- boolean: "true" or "false", defaults to false if tag omitted or value is not "true" -->
-    </ListFiles>
-    ```
+```xml
+<ListFiles>
+  <path>path/to/search</path>
+  <recursive>true</recursive> <!-- "true" or "false", defaults to false -->
+  <!-- Optional filtering -->
+  <filter_extensions>.py,.txt</filter_extensions>
+  <filter_regex_name>test_.*\.py</filter_regex_name>
+  <include_metadata>true</include_metadata>
+</ListFiles>
+```
 
 *   **WebSearch:**
     ```xml
@@ -77,6 +82,102 @@ The AI will be instructed to output *only* an XML block when calling a tool. The
     </TaskComplete>
     ```
 
+*   **LintFile:**
+    ```xml
+    <LintFile>
+      <path>path/to/python_file.py</path>
+      <linter>pylint</linter>
+    </LintFile>
+    ```
+
+*   **GetCodeStructure:**
+    ```xml
+    <GetCodeStructure>
+      <path>path/to/python_file.py</path>
+    </GetCodeStructure>
+    ```
+
+*   **FindSymbolDefinition:**
+    ```xml
+    <FindSymbolDefinition>
+      <symbol_name>my_function</symbol_name>
+      <search_path>./cogs</search_path>
+      <file_pattern>*.py</file_pattern>
+    </FindSymbolDefinition>
+    ```
+
+*   **ManageCog:**
+    ```xml
+    <ManageCog>
+      <action>reload</action>
+      <cog_name>cogs.example_cog</cog_name>
+    </ManageCog>
+    ```
+
+*   **RunTests:**
+    ```xml
+    <RunTests>
+      <test_path_or_pattern>tests/test_module.py</test_path_or_pattern>
+      <framework>pytest</framework>
+    </RunTests>
+    ```
+
+*   **PythonREPL:**
+    ```xml
+    <PythonREPL>
+      <code_snippet><![CDATA[
+print("Hello from REPL")
+      ]]></code_snippet>
+      <session_id>optional_id</session_id>
+    </PythonREPL>
+    ```
+
+*   **CreateNamedSnapshot:**
+    ```xml
+    <CreateNamedSnapshot>
+      <snapshot_name>feature_snapshot</snapshot_name>
+      <description>Optional description</description>
+    </CreateNamedSnapshot>
+    ```
+
+*   **CompareSnapshots:**
+    ```xml
+    <CompareSnapshots>
+      <base_ref>snapshot_a</base_ref>
+      <compare_ref>snapshot_b</compare_ref>
+    </CompareSnapshots>
+    ```
+
+*   **DryRunApplyDiff:**
+    ```xml
+    <DryRunApplyDiff>
+      <path>path/to/file.ext</path>
+      <diff_block><![CDATA[
+[SEARCH_BLOCK_START]
+:start_line:10
+-------
+old line
+\=======
+new line
+[REPLACE_BLOCK_END]
+      ]]></diff_block>
+    </DryRunApplyDiff>
+    ```
+
+*   **DryRunWriteFile:**
+    ```xml
+    <DryRunWriteFile>
+      <path>path/to/file.ext</path>
+    </DryRunWriteFile>
+    ```
+
+*   **ReadWebPageRaw:**
+    ```xml
+    <ReadWebPageRaw>
+      <url>https://example.com/raw.txt</url>
+    </ReadWebPageRaw>
+    ```
+
 **3. Parsing Logic in `_parse_and_execute_tool_call` (Python):**
 
 *   The method will attempt to parse the `ai_response_text` as XML using `xml.etree.ElementTree`.
@@ -123,6 +224,17 @@ graph TD
     E -- ExecuteCommand --> I[Call _execute_tool_execute_command];
     E -- ListFiles --> J[Call _execute_tool_list_files];
     E -- WebSearch --> K[Call _execute_tool_web_search];
+    E -- LintFile --> R[Call _execute_tool_lint_file];
+    E -- GetCodeStructure --> S[Call _execute_tool_get_code_structure];
+    E -- FindSymbolDefinition --> T[Call _execute_tool_find_symbol_definition];
+    E -- ManageCog --> U[Call _execute_tool_manage_cog];
+    E -- RunTests --> V[Call _execute_tool_run_tests];
+    E -- PythonREPL --> W[Call _execute_tool_python_repl];
+    E -- CreateNamedSnapshot --> X[Call _execute_tool_create_named_snapshot];
+    E -- CompareSnapshots --> Y[Call _execute_tool_compare_snapshots];
+    E -- DryRunApplyDiff --> Z[Call _execute_tool_dry_run_apply_diff];
+    E -- DryRunWriteFile --> AA[Call _execute_tool_dry_run_write_file];
+    E -- ReadWebPageRaw --> AB[Call _execute_tool_read_web_page_raw];
     E -- TaskComplete --> L[Process TaskComplete];
     E -- Unknown Tool --> M[Handle Unknown Tool / Error];
     B -- Invalid XML / Not a Tool --> N[Return "NO_TOOL" status];
@@ -132,7 +244,19 @@ graph TD
     I --> O;
     J --> O;
     K --> O;
+    R --> O;
+    S --> O;
+    T --> O;
+    U --> O;
+    V --> O;
+    W --> O;
+    X --> O;
+    Y --> O;
+    Z --> O;
+    AA --> O;
+    AB --> O;
     L --> P[End Interaction];
     M --> P;
     N --> P;
-    O --> Q[Add to History, Continue Loop];
\ No newline at end of file
+    O --> Q[Add to History, Continue Loop];
+```
diff --git a/docs/components.md b/docs/components.md
index 1e32e46..db22433 100644
--- a/docs/components.md
+++ b/docs/components.md
@@ -299,7 +299,7 @@ class InfoView(discord.ui.LayoutView):
 
 ## See Also
 
-More examples can be found in the
-`examples <examples>`{.interpreted-text role="resource"} directory.
-Refer to the `interactions/api`{.interpreted-text role="doc"} page for
-an exhaustive API reference.
+For additional usage examples, refer to the official `discord.py`
+documentation. This repository does not include the example suite from
+the library. See the `interactions/api` reference for an exhaustive API
+overview.