aissia/PLAN_FILESYSTEM_TOOLS.md

Plan : FileSystem Tools pour AISSIA

Objectif

Ajouter des tools de manipulation de fichiers style Claude Code pour permettre à l'agent vocal de lire, écrire et modifier des fichiers.

Tools à implémenter

Tool	Paramètres	Description
read_file	path, offset?, limit?	Lit un fichier (avec pagination optionnelle)
write_file	path, content	Écrit/remplace un fichier complet
edit_file	path, old_string, new_string, replace_all?	Remplacement exact de string
list_directory	path	Liste les fichiers d'un répertoire
glob_files	pattern, path?	Recherche par pattern glob (ex: **/*.cpp)
grep_files	pattern, path?, glob?	Recherche regex dans les fichiers

Architecture

src/shared/tools/
├── IOBridge.hpp          # Existant
├── InternalTools.hpp     # Existant - tools via IIO
├── InternalTools.cpp
├── FileSystemTools.hpp   # NOUVEAU - tools filesystem
└── FileSystemTools.cpp

Pourquoi un fichier séparé ?

• Les FileSystem tools n'ont pas besoin de IIO (pas de communication inter-modules)
• Exécution directe en C++ (plus rapide)
• Séparation des responsabilités

Implémentation

FileSystemTools.hpp

#pragma once
#include <string>
#include <vector>
#include <nlohmann/json.hpp>

namespace aissia::tools {

struct FileSystemTools {
    // Définitions des tools pour le LLM
    static std::vector<nlohmann::json> getToolDefinitions();

    // Exécution
    static nlohmann::json execute(const std::string& toolName,
                                   const nlohmann::json& params);

private:
    static nlohmann::json readFile(const nlohmann::json& params);
    static nlohmann::json writeFile(const nlohmann::json& params);
    static nlohmann::json editFile(const nlohmann::json& params);
    static nlohmann::json listDirectory(const nlohmann::json& params);
    static nlohmann::json globFiles(const nlohmann::json& params);
    static nlohmann::json grepFiles(const nlohmann::json& params);
};

} // namespace aissia::tools

Dépendances

• <filesystem> (C++17) - pour list_directory, glob_files
• <regex> - pour grep_files
• <fstream> - pour read/write

Pas de dépendance externe requise.

Intégration dans LLMService

void LLMService::initializeTools() {
    // Tools existants
    m_internalTools = std::make_unique<InternalTools>(m_io);

    // NOUVEAU: FileSystem tools
    auto fsTools = FileSystemTools::getToolDefinitions();
    m_allTools.insert(m_allTools.end(), fsTools.begin(), fsTools.end());
}

nlohmann::json LLMService::executeTool(const std::string& name,
                                        const nlohmann::json& params) {
    // FileSystem tools (direct execution)
    if (name == "read_file" || name == "write_file" || name == "edit_file" ||
        name == "list_directory" || name == "glob_files" || name == "grep_files") {
        return FileSystemTools::execute(name, params);
    }

    // Internal tools (via IIO)
    return m_internalTools->execute(name, params);
}

Sécurité

Restrictions à implémenter

1. Whitelist de répertoires - Configurable dans config/filesystem.json

   {
     "allowed_paths": [
       "/mnt/e/Users/Alexis Trouvé/Documents/Projets/",
       "/tmp/aissia/"
     ],
     "blocked_patterns": [
       "*.env",
       "*credentials*",
       "*.key"
     ]
   }
   

2. Validation des chemins - Résolution canonique pour éviter path traversal (../)

3. Limite de taille - Max 1MB pour read_file, 10MB pour write_file

Étapes d'implémentation

1. Créer FileSystemTools.hpp avec les signatures
2. Implémenter read_file et write_file
3. Implémenter edit_file (le plus complexe)
4. Implémenter list_directory
5. Implémenter glob_files (récursif avec pattern matching)
6. Implémenter grep_files
7. Ajouter la config de sécurité
8. Intégrer dans LLMService
9. Mettre à jour CMakeLists.txt
10. Tester chaque tool

Tests

# Test read_file
echo '{"tool": "read_file", "params": {"path": "/tmp/test.txt"}}' | ./build/aissia --test-tool

# Test edit_file
echo '{"tool": "edit_file", "params": {"path": "/tmp/test.txt", "old_string": "foo", "new_string": "bar"}}' | ./build/aissia --test-tool

Estimation

• FileSystemTools de base : ~200 lignes
• Config sécurité : ~50 lignes
• Intégration LLMService : ~30 lignes

Total : ~280 lignes de code nouveau