@fkom13/mcp-sftp-orchestrator 11.3.0 → 11.8.0

package/sshPool.js

@@ -1,13 +1,17 @@
 import { Client } from 'ssh2';
 import fs from 'fs/promises';
 import queue from './queue.js';
-
+import utils from './utils.js';
 import config from './config.js';
 
+/**
+ * Pool de connexions SSH persistantes.
+ * v11.4.0 : listeners non empilés sur retry, flag ready fiable, port configurable.
+ */
 class SSHConnectionPool {
     constructor() {
-        this.pools = new Map(); // Map<serverAlias, Connection[]>
-        this.activeConnections = new Map(); // Map<connectionId, {conn, serverAlias, inUse, lastUsed}>
+        this.pools = new Map(); // Map<serverAlias, connId[]>
+        this.activeConnections = new Map(); // Map<connId, {conn, serverAlias, inUse, lastUsed, ready}>
         this.config = {
             maxConnections: config.maxConnectionsPerServer,
             minConnections: config.minConnectionsPerServer,
@@ -16,24 +20,20 @@ class SSHConnectionPool {
             connectionTimeout: 20000,
             retryAttempts: 3
         };
-
-        // Nettoyage périodique des connexions inactives
         this.startCleanupInterval();
     }
 
     isConnectionReady(connId) {
         const connInfo = this.activeConnections.get(connId);
-        if (!connInfo) return false;
-
-        // Vérifier l'état réel
-        return connInfo.conn._sock &&
-            connInfo.conn._sock.readable &&
-            this.activeConnections.get(connId)?.inUse !== undefined; // Basic check
+        if (!connInfo || !connInfo.ready || connInfo.closed) return false;
+        const sock = connInfo.conn && connInfo.conn._sock;
+        if (!sock) return false;
+        // Socket encore ouvert et lisible
+        if (sock.destroyed || sock.readyState === 'closed') return false;
+        return sock.readable !== false;
     }
 
-    // Obtenir ou créer une connexion
     async getConnection(serverAlias, serverConfig) {
-        // Chercher une connexion disponible
         const pool = this.pools.get(serverAlias) || [];
 
         for (const connId of pool) {
@@ -44,92 +44,123 @@ class SSHConnectionPool {
                 queue.log('info', `Réutilisation connexion SSH existante pour ${serverAlias}`);
                 return { id: connId, client: connInfo.conn };
             }
+            // Connexion morte dans le pool → purge
+            if (connInfo && !connInfo.inUse && !this.isConnectionReady(connId)) {
+                this.removeConnection(connId);
+            }
         }
 
-        // Si pas de connexion disponible, en créer une nouvelle
-        if (pool.length < this.config.maxConnections) {
-            const newConn = await this.createConnection(serverAlias, serverConfig);
-            return newConn;
+        const currentPool = this.pools.get(serverAlias) || [];
+        if (currentPool.length < this.config.maxConnections) {
+            return await this.createConnection(serverAlias, serverConfig);
         }
 
-        // Si pool plein, attendre qu'une connexion se libère
         queue.log('warn', `Pool SSH saturé pour ${serverAlias}, attente...`);
         return await this.waitForConnection(serverAlias, serverConfig);
     }
 
-    // Créer une nouvelle connexion
     async createConnection(serverAlias, serverConfig) {
-        const conn = new Client();
-        const connId = `${serverAlias}_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
-
-        return new Promise((resolve, reject) => {
-            let retries = 0;
-
-            const tryConnect = async () => {
-                try {
-                    const config = {
-                        host: serverConfig.host,
-                        port: 22,
-                        username: serverConfig.user,
-                        readyTimeout: this.config.connectionTimeout,
-                        keepaliveInterval: this.config.keepAliveInterval,
-                        keepaliveCountMax: 3
-                    };
-
-                    if (serverConfig.keyPath) {
-                        config.privateKey = await fs.readFile(serverConfig.keyPath);
-                    } else if (serverConfig.password) {
-                        config.password = serverConfig.password;
-                    }
+        const connId = `${serverAlias}_${Date.now()}_${Math.random().toString(36).slice(2, 11)}`;
+        let lastError = null;
 
-                    conn.on('ready', () => {
-                        queue.log('info', `Nouvelle connexion SSH établie pour ${serverAlias}`);
-
-                        // Ajouter au pool
-                        if (!this.pools.has(serverAlias)) {
-                            this.pools.set(serverAlias, []);
-                        }
-                        this.pools.get(serverAlias).push(connId);
-
-                        // Enregistrer la connexion
-                        this.activeConnections.set(connId, {
-                            conn,
-                            serverAlias,
-                            inUse: true,
-                            lastUsed: Date.now(),
-                            config: serverConfig
-                        });
-
-                        resolve({ id: connId, client: conn });
-                    });
-
-                    conn.on('error', (err) => {
-                        if (retries < this.config.retryAttempts) {
-                            retries++;
-                            queue.log('warn', `Tentative ${retries}/${this.config.retryAttempts} de connexion à ${serverAlias}`);
-                            setTimeout(tryConnect, 2000 * retries);
-                        } else {
-                            this.removeConnection(connId);
-                            reject(new Error(`Impossible de se connecter à ${serverAlias}: ${err.message}`));
-                        }
-                    });
-
-                    conn.on('close', () => {
-                        this.removeConnection(connId);
-                        queue.log('info', `Connexion SSH fermée pour ${serverAlias}`);
-                    });
-
-                    conn.connect(config);
-                } catch (err) {
-                    reject(err);
+        for (let attempt = 1; attempt <= this.config.retryAttempts; attempt++) {
+            try {
+                const conn = await this._connectOnce(serverAlias, serverConfig, connId);
+                return conn;
+            } catch (err) {
+                lastError = err;
+                queue.log('warn', `Tentative ${attempt}/${this.config.retryAttempts} de connexion à ${serverAlias}: ${err.message}`);
+                if (attempt < this.config.retryAttempts) {
+                    await new Promise(r => setTimeout(r, 2000 * attempt));
                 }
+            }
+        }
+
+        this.removeConnection(connId);
+        throw new Error(`Impossible de se connecter à ${serverAlias}: ${lastError?.message || 'erreur inconnue'}`);
+    }
+
+    /**
+     * Une seule tentative = un nouveau Client + listeners uniques (pas d'empilement).
+     */
+    _connectOnce(serverAlias, serverConfig, connId) {
+        return new Promise(async (resolve, reject) => {
+            const conn = new Client();
+            let settled = false;
+
+            const fail = (err) => {
+                if (settled) return;
+                settled = true;
+                try { conn.removeAllListeners(); conn.end(); } catch { /* ignore */ }
+                reject(err instanceof Error ? err : new Error(String(err)));
+            };
+
+            const succeed = () => {
+                if (settled) return;
+                settled = true;
+                queue.log('info', `Nouvelle connexion SSH établie pour ${serverAlias}`);
+
+                if (!this.pools.has(serverAlias)) this.pools.set(serverAlias, []);
+                const pool = this.pools.get(serverAlias);
+                if (!pool.includes(connId)) pool.push(connId);
+
+                this.activeConnections.set(connId, {
+                    conn,
+                    serverAlias,
+                    inUse: true,
+                    lastUsed: Date.now(),
+                    ready: true,
+                    closed: false,
+                    config: serverConfig
+                });
+
+                resolve({ id: connId, client: conn });
             };
 
-            tryConnect();
+            conn.once('ready', succeed);
+            conn.once('error', (err) => fail(err));
+            conn.on('close', () => {
+                const info = this.activeConnections.get(connId);
+                if (info) {
+                    info.ready = false;
+                    info.closed = true;
+                }
+                this.removeConnection(connId);
+                queue.log('info', `Connexion SSH fermée pour ${serverAlias}`);
+            });
+            conn.on('end', () => {
+                const info = this.activeConnections.get(connId);
+                if (info) {
+                    info.ready = false;
+                    info.closed = true;
+                }
+            });
+
+            try {
+                const connectConfig = {
+                    host: serverConfig.host,
+                    port: utils.resolveSshPort(serverConfig),
+                    username: serverConfig.user,
+                    readyTimeout: this.config.connectionTimeout,
+                    keepaliveInterval: this.config.keepAliveInterval,
+                    keepaliveCountMax: 3
+                };
+
+                if (serverConfig.keyPath) {
+                    connectConfig.privateKey = await fs.readFile(serverConfig.keyPath);
+                } else if (serverConfig.password) {
+                    connectConfig.password = serverConfig.password;
+                } else {
+                    return fail(new Error(`Aucune méthode d'authentification pour '${serverAlias}'`));
+                }
+
+                conn.connect(connectConfig);
+            } catch (err) {
+                fail(err);
+            }
         });
     }
 
-    // Libérer une connexion
     releaseConnection(connId) {
         const connInfo = this.activeConnections.get(connId);
         if (connInfo) {
@@ -139,51 +170,41 @@ class SSHConnectionPool {
         }
     }
 
-    // Fermer une connexion spécifique
     closeConnection(connId) {
         const connInfo = this.activeConnections.get(connId);
         if (connInfo) {
             try {
+                connInfo.ready = false;
                 connInfo.conn.end();
-            } catch (e) {
-                // Ignorer les erreurs de fermeture
-            }
+            } catch { /* ignore */ }
             this.removeConnection(connId);
         }
     }
 
-    // Retirer une connexion du pool
     removeConnection(connId) {
         const connInfo = this.activeConnections.get(connId);
         if (connInfo) {
             const pool = this.pools.get(connInfo.serverAlias);
             if (pool) {
                 const index = pool.indexOf(connId);
-                if (index > -1) {
-                    pool.splice(index, 1);
-                }
-                if (pool.length === 0) {
-                    this.pools.delete(connInfo.serverAlias);
-                }
+                if (index > -1) pool.splice(index, 1);
+                if (pool.length === 0) this.pools.delete(connInfo.serverAlias);
             }
             this.activeConnections.delete(connId);
         }
     }
 
-    // Attendre qu'une connexion se libère
     async waitForConnection(serverAlias, serverConfig, timeout = 30000) {
         const startTime = Date.now();
 
         return new Promise((resolve, reject) => {
-            const checkInterval = setInterval(async () => {
-                // Vérifier le timeout
+            const checkInterval = setInterval(() => {
                 if (Date.now() - startTime > timeout) {
                     clearInterval(checkInterval);
                     reject(new Error(`Timeout en attendant une connexion pour ${serverAlias}`));
                     return;
                 }
 
-                // Essayer d'obtenir une connexion
                 const pool = this.pools.get(serverAlias) || [];
                 for (const connId of pool) {
                     const connInfo = this.activeConnections.get(connId);
@@ -195,36 +216,35 @@ class SSHConnectionPool {
                         return;
                     }
                 }
+
+                // Slot libre → créer
+                if (pool.length < this.config.maxConnections) {
+                    clearInterval(checkInterval);
+                    this.createConnection(serverAlias, serverConfig).then(resolve).catch(reject);
+                }
             }, 500);
         });
     }
 
-    // Nettoyer les connexions inactives
     startCleanupInterval() {
         setInterval(() => {
             const now = Date.now();
-
-            for (const [connId, connInfo] of this.activeConnections) {
-                // Fermer les connexions inactives depuis trop longtemps
+            for (const [connId, connInfo] of [...this.activeConnections.entries()]) {
                 if (!connInfo.inUse && (now - connInfo.lastUsed) > this.config.idleTimeout) {
                     const pool = this.pools.get(connInfo.serverAlias) || [];
-
-                    // Garder au moins minConnections
                     if (pool.length > this.config.minConnections) {
                         queue.log('info', `Fermeture connexion inactive: ${connId}`);
                         this.closeConnection(connId);
+                        continue;
                     }
                 }
-
-                // Vérifier que la connexion est toujours vivante
                 if (!this.isConnectionReady(connId) && !connInfo.inUse) {
                     this.removeConnection(connId);
                 }
             }
-        }, 60000); // Vérifier toutes les minutes
+        }, 60000);
     }
 
-    // Obtenir les statistiques du pool
     getStats() {
         const stats = {
             totalConnections: this.activeConnections.size,
@@ -253,16 +273,13 @@ class SSHConnectionPool {
         return stats;
     }
 
-    // Fermer toutes les connexions
     closeAll() {
         queue.log('info', 'Fermeture de toutes les connexions SSH...');
-        for (const connId of this.activeConnections.keys()) {
+        for (const connId of [...this.activeConnections.keys()]) {
             this.closeConnection(connId);
         }
     }
 }
 
-// Instance singleton
 const sshPool = new SSHConnectionPool();
-
 export default sshPool;

package/sshTrust.js

@@ -0,0 +1,214 @@
+/**
+ * sshTrust.js — Autorisation croisée de clés SSH (pubkey only).
+ * Ne copie JAMAIS de clé privée entre serveurs.
+ */
+import fs from 'fs/promises';
+import path from 'path';
+import os from 'os';
+import queue from './queue.js';
+import servers from './servers.js';
+import sourceAdapter from './sourceAdapter.js';
+import utils from './utils.js';
+
+/**
+ * Lit une pubkey depuis:
+ *  - { type:'string', pubkey }
+ *  - { type:'local_path', path }  (fichier .pub)
+ *  - { type:'alias', alias }      (keyPath du serveur → .pub à côté ou ssh-keygen -y)
+ */
+async function resolvePubkey(source) {
+    if (!source || !source.type) {
+        throw new Error("source requis: {type:'string'|'local_path'|'alias', ...}");
+    }
+
+    if (source.type === 'string') {
+        const pk = (source.pubkey || source.key || '').trim();
+        if (!pk.startsWith('ssh-') && !pk.startsWith('ecdsa-') && !pk.startsWith('sk-')) {
+            throw new Error('pubkey invalide (doit commencer par ssh-ed25519 / ssh-rsa / …)');
+        }
+        return pk.split('\n')[0].trim();
+    }
+
+    if (source.type === 'local_path') {
+        const p = source.path;
+        if (!p) throw new Error('source.path requis pour local_path');
+        let content = await fs.readFile(p, 'utf-8');
+        // Si c'est une privée, refuse
+        if (content.includes('PRIVATE KEY')) {
+            // tenter .pub voisin
+            const pubPath = p.endsWith('.pub') ? p : p + '.pub';
+            try {
+                content = await fs.readFile(pubPath, 'utf-8');
+            } catch {
+                throw new Error(`Refus: ${p} semble une clé privée. Fournissez le .pub`);
+            }
+        }
+        const line = content.trim().split('\n').find(l => l.startsWith('ssh-') || l.startsWith('ecdsa-'));
+        if (!line) throw new Error(`Aucune pubkey trouvée dans ${p}`);
+        return line.trim();
+    }
+
+    if (source.type === 'alias') {
+        const sc = await servers.getServer(source.alias);
+        if (!sc.keyPath) {
+            throw new Error(`Alias '${source.alias}' n'a pas de keyPath (password-only non supporté pour trust).`);
+        }
+        const pubPath = sc.keyPath.endsWith('.pub') ? sc.keyPath : sc.keyPath + '.pub';
+        try {
+            const content = await fs.readFile(pubPath, 'utf-8');
+            const line = content.trim().split('\n').find(l => l.startsWith('ssh-') || l.startsWith('ecdsa-') || l.startsWith('sk-'));
+            if (line) return line.trim();
+        } catch {
+            // fallback: ssh-keygen -y -f private
+        }
+        // Générer pubkey depuis privée localement (ne sort pas du MCP host)
+        const { execFile } = await import('child_process');
+        const { promisify } = await import('util');
+        const execFileAsync = promisify(execFile);
+        try {
+            const { stdout } = await execFileAsync('ssh-keygen', ['-y', '-f', sc.keyPath], {
+                timeout: 5000,
+                env: { ...process.env, SSH_AUTH_SOCK: '' }
+            });
+            const line = stdout.trim().split('\n')[0];
+            if (!line.startsWith('ssh-') && !line.startsWith('ecdsa-')) {
+                throw new Error('ssh-keygen -y n\'a pas renvoyé une pubkey valide');
+            }
+            return line.trim();
+        } catch (e) {
+            throw new Error(
+                `Impossible d'obtenir la pubkey pour '${source.alias}': ${e.message}. ` +
+                `Créez ${pubPath} ou passez source.type=string.`
+            );
+        }
+    }
+
+    throw new Error(`source.type inconnu: ${source.type}`);
+}
+
+function authorizedKeysPath(userHome, explicitPath) {
+    if (explicitPath) return explicitPath;
+    return path.posix.join(userHome || '~', '.ssh', 'authorized_keys');
+}
+
+/**
+ * options:
+ *  target_alias, source?, authorized_keys_path?,
+ *  source: {type, ...},
+ *  comment?, dryRun?, force?
+ */
+async function authorizeKey(options = {}) {
+    const {
+        target_alias,
+        user = null,
+        authorized_keys_path = null,
+        source,
+        comment = null,
+        dryRun = true,
+        force = false
+    } = options;
+
+    if (!target_alias) throw new Error('target_alias requis');
+    const sc = await servers.getServer(target_alias);
+
+    const pubkey = await resolvePubkey(source);
+    // Normalise: type + body (+ comment optionnel)
+    const parts = pubkey.trim().split(/\s+/);
+    const typeBody = parts.slice(0, 2).join(' ');
+    const existingComment = parts.slice(2).join(' ');
+    const lineToAdd = comment
+        ? `${typeBody} ${comment}`
+        : (existingComment ? `${typeBody} ${existingComment}` : typeBody);
+
+    // Résoudre home distant
+    const homeCmd = user ? `getent passwd ${utils.escapeShellArg(user).replace(/^'|'$/g, '')} 2>/dev/null | cut -d: -f6` : 'echo $HOME';
+    // Simpler: use ~ expansion via shell on target for path
+    const remoteUser = user || sc.user;
+    const akPath = authorized_keys_path
+        || `/home/${remoteUser}/.ssh/authorized_keys`;
+    // root special case
+    const finalAkPath = (remoteUser === 'root' && !authorized_keys_path)
+        ? '/root/.ssh/authorized_keys'
+        : akPath;
+
+    let existing = '';
+    let existed = false;
+    try {
+        const r = await sourceAdapter.readFile({ type: 'remote', alias: target_alias, path: finalAkPath });
+        existing = r.content.toString('utf-8');
+        existed = true;
+    } catch {
+        existing = '';
+        existed = false;
+    }
+
+    const lines = existing.split('\n').map(l => l.trimEnd());
+    const pubCore = pubkey.split(' ').slice(0, 2).join(' ');
+    const already = lines.some(l => l.includes(pubCore));
+
+    if (already && !force) {
+        return {
+            dryRun: !!dryRun,
+            applied: false,
+            alreadyPresent: true,
+            target_alias,
+            path: finalAkPath,
+            pubkey_fingerprint_hint: pubCore.slice(0, 40) + '…'
+        };
+    }
+
+    const newContent = already
+        ? existing // force re-add skipped if already
+        : (existing.trimEnd() + (existing && !existing.endsWith('\n') ? '\n' : '') + lineToAdd + '\n');
+
+    if (dryRun) {
+        return {
+            dryRun: true,
+            applied: false,
+            alreadyPresent: already,
+            wouldAdd: !already,
+            target_alias,
+            path: finalAkPath,
+            linePreview: lineToAdd.slice(0, 80) + (lineToAdd.length > 80 ? '…' : ''),
+            existed
+        };
+    }
+
+    // Ensure .ssh dir exists via write createDirs
+    // Write authorized_keys
+    // Also set permissions via a quick exec would be better
+    await sourceAdapter.writeFile(
+        { type: 'remote', alias: target_alias, path: finalAkPath },
+        Buffer.from(newContent, 'utf-8'),
+        { createDirs: true }
+    );
+
+    // chmod 700 .ssh / 600 authorized_keys
+    const sshDir = path.posix.dirname(finalAkPath);
+    const { default: ssh } = await import('./ssh.js');
+    const job = queue.addJob({
+        type: 'ssh',
+        alias: target_alias,
+        cmd: `mkdir -p ${utils.escapeShellArg(sshDir)} && chmod 700 ${utils.escapeShellArg(sshDir)} && chmod 600 ${utils.escapeShellArg(finalAkPath)}`,
+        timeout: 30,
+        skip_policy: true,
+        status: 'pending'
+    });
+    // fire and wait briefly
+    await ssh.executeCommand(job.id);
+    // small poll
+    await new Promise(r => setTimeout(r, 500));
+
+    queue.log('info', `ssh_authorize_key: pubkey ajoutée sur ${target_alias}:${finalAkPath}`);
+
+    return {
+        dryRun: false,
+        applied: true,
+        alreadyPresent: already,
+        target_alias,
+        path: finalAkPath,
+        linePreview: lineToAdd.slice(0, 80) + '…'
+    };
+}
+
+export default { authorizeKey, resolvePubkey };

package/toolMetadata.js

@@ -0,0 +1,76 @@
+/**
+ * Metadata MCP agentique centralisée.
+ *
+ * L'objectif n'est pas de remplacer les garde-fous serveur par des hints :
+ * les annotations MCP aident le client/modèle à choisir et confirmer le bon
+ * outil, tandis que les policies/guards restent l'autorité réelle.
+ */
+
+const READ_ONLY = new Set([
+  'system_diagnostics','server_list','server_group_list','fleet_status','infra_audit',
+  'project_list','project_get','project_resolve','project_diff','work_list','server_inventory',
+  'policy_blocklist_list','api_list','api_check','get_system_resources','get_services_status',
+  'check_api_health','get_fail2ban_status','task_queue','task_status','task_history','pool_stats',
+  'queue_stats','task_logs','get_pm2_logs','get_docker_logs','tail_file','help','task_wait',
+  'file_read','diff_files','diff_folders','compare_all_sources','shell_list','snapshot_list',
+  'snapshot_diff','server_note_get','server_note_list','infra_overview','tmux_read','tmux_list',
+  'tunnel_list','guide'
+]);
+
+const DESTRUCTIVE = new Set([
+  'server_remove','server_group_remove','project_remove','work_end','policy_blocklist_remove',
+  'api_remove','task_exec','task_transfer','task_transfer_multi','task_exec_interactive',
+  'task_exec_sequence','task_retry','task_retry_all','task_purge','file_write','file_edit',
+  'shell_exec','shell_close','snapshot_restore','snapshot_delete','server_note_remove',
+  'tmux_exec','tmux_kill','tunnel_close','tunnel_allowlist_remove'
+]);
+
+const IDEMPOTENT_MUTATIONS = new Set([
+  'server_group_set','project_set','server_note_set','policy_blocklist_add',
+  'tunnel_allowlist_add','tunnel_allowlist_remove'
+]);
+
+const CLOSED_WORLD = new Set([
+  'help','guide','policy_blocklist_list','project_list','project_get','project_resolve',
+  'server_group_list','server_note_get','server_note_list','task_queue','task_status',
+  'task_history','queue_stats','task_logs','snapshot_list','snapshot_diff'
+]);
+
+const DESCRIPTION_OVERRIDES = {
+  system_diagnostics: 'Diagnostique le processus MCP lui-même (queue, pool SSH, registres, erreurs). Pour l’état réel d’une machine utilisez server_inventory; pour la topologie domaines→ports→services utilisez infra_overview avec alias.',
+  infra_audit: 'Contexte de contrôle-plane en un appel: version Orchestrator, registres, groupes, projets, notes, jobs crashés et pool. N’interroge pas profondément les machines. Pour une machine live et ses routes réseau utilisez infra_overview avec alias.',
+  infra_overview: 'Cartographie d’infrastructure. Sans alias: vue légère de tout le parc depuis les registres/notes. Avec alias (ou group:/all): découverte live mise en cache des listeners, Docker/Compose, PM2, systemd et Nginx, puis corrélation domaine → proxy → port → conteneur/service.',
+  fleet_status: 'Teste en parallèle la joignabilité SSH et quelques ressources de plusieurs serveurs. Choisir cet outil pour “qui est online ?”. Pour le détail d’une machine utilisez server_inventory; pour ses domaines/services exposés utilisez infra_overview.',
+  server_inventory: 'Inventaire live léger d’une machine avec cache TTL: ressources, Docker, PM2, HOME et Tailscale. Ne reconstruit pas les routes reverse-proxy; utilisez infra_overview pour domaine → port → service.',
+  task_exec: 'Commande distante one-shot. Pour une commande longue utilisez timeout:0 puis task_wait/task_status. Pour conserver cd/export entre appels utilisez shell_create/shell_exec; pour une session terminal survivant au MCP utilisez tmux_*.',
+  task_exec_sequence: 'Exécute plusieurs commandes ordonnées sur le même serveur avec résultat par étape. Préférer à plusieurs task_exec lorsque les étapes sont déterministes mais n’ont pas besoin d’un shell persistant.',
+  task_exec_interactive: 'Commande distante avec gestion de prompts interactifs connus. Utiliser seulement si la commande attend réellement yes/no/password/choix; sinon préférer task_exec.',
+  task_transfer: 'Transfert fichier ou dossier. server_to_server copie directement source_alias → alias. force:false protège une destination existante. Pour une réplication bit-à-bit avec métadonnées/symlinks, vérifier les warnings du résultat.',
+  task_transfer_multi: 'Lot de transferts avec patterns glob. À préférer pour plusieurs fichiers indépendants; task_transfer est plus clair pour un fichier/dossier ou un transfert server_to_server.',
+  file_edit: 'Édition chirurgicale locale/remote avec protection expectedHash, dryRun et backup. Préférer à file_write pour modifier un fichier existant sans écraser involontairement des changements concurrents.',
+  file_write: 'Crée ou remplace un fichier local/remote. Pour un fichier existant, préférer file_edit + expectedHash quand une édition chirurgicale est possible.',
+  shell_create: 'Ouvre un shell SSH persistant: cwd et variables survivent entre shell_exec. Pour une tâche détachée survivant à une déconnexion du MCP, préférer tmux_create/tmux_exec.',
+  tmux_create: 'Crée une session tmux distante durable. Adapté aux agents/serveurs de dev et tâches longues que l’on doit reprendre après déconnexion.',
+  snapshot_create: 'Snapshot CAS dédupliqué de fichiers/dossiers local ou remote pour rollback infra. Ce n’est pas de la mémoire sémantique projet; GenCodeDoc reste la brique Project Intelligence.',
+  help: 'Référence compacte des tools et variables Orchestrator. Pour des workflows agentiques guidés, utiliser guide.',
+  guide: 'Playbooks agentiques Orchestrator (audit, déploiement, recovery, transferts). Utiliser help pour le schéma/description d’un tool précis.'
+};
+
+function annotationsFor(name) {
+  const readOnlyHint = READ_ONLY.has(name);
+  return {
+    readOnlyHint,
+    destructiveHint: readOnlyHint ? false : DESTRUCTIVE.has(name),
+    idempotentHint: readOnlyHint || IDEMPOTENT_MUTATIONS.has(name),
+    openWorldHint: !CLOSED_WORLD.has(name)
+  };
+}
+
+function enhanceToolConfig(name, config = {}) {
+  const annotations = { ...annotationsFor(name), ...(config.annotations || {}) };
+  const description = DESCRIPTION_OVERRIDES[name] || config.description;
+  return { ...config, description, annotations };
+}
+
+export { annotationsFor, enhanceToolConfig, DESCRIPTION_OVERRIDES };
+export default { annotationsFor, enhanceToolConfig, DESCRIPTION_OVERRIDES };