agentic-api 2.0.314 → 2.0.585

package/dist/src/rules/git/repo.pr.js

@@ -40,6 +40,7 @@ exports.gitGetPRMetadata = gitGetPRMetadata;
 exports.gitGetAllPR = gitGetAllPR;
 exports.gitGetClosedPRs = gitGetClosedPRs;
 exports.gitLoadPR = gitLoadPR;
+exports.gitPRReplaceFile = gitPRReplaceFile;
 exports.gitPRUpdateComments = gitPRUpdateComments;
 exports.gitClosePR = gitClosePR;
 exports.gitClosePRRobust = gitClosePRRobust;
@@ -321,7 +322,7 @@ async function gitLoadPR(git, branch) {
         if (!metadata) {
             throw new errors_1.GitOperationError(`PR not found for branch ${branch}`, 'pr_load', { branch });
         }
-        const files = metadata.files || await (0, repo_tools_1.gitGetDiffFiles)(git, branch, metadata?.mergeBase, '.md');
+        const files = metadata.files || (await (0, repo_tools_1.gitGetDiffFiles)(git, branch, metadata?.mergeBase, '.md'));
         // Récupérer les infos du dernier commit de la branche
         const log = await git.log({ from: branch, to: branch, maxCount: 1 });
         const lastCommit = log.latest;
@@ -341,6 +342,49 @@ async function gitLoadPR(git, branch) {
         throw new errors_1.GitOperationError(`Failed to retrieve PR: ${error}`, 'pr_load');
     }
 }
+/**
+ * Remplace explicitement un nom de fichier dans les métadonnées d'une PR.
+ * Utilisé pour refléter immédiatement les renames sans dépendre de git diff.
+ */
+async function gitPRReplaceFile(git, branch, options = {}, config) {
+    const { remove, add } = options;
+    if (!remove && !add) {
+        return;
+    }
+    const gitConf = (0, repo_tools_1.gitLoad)(config);
+    const metadata = await gitGetPRMetadata(git, branch, config);
+    if (!metadata) {
+        return;
+    }
+    const currentFiles = Array.isArray(metadata.files) ? metadata.files : [];
+    const seen = new Set();
+    const nextFiles = [];
+    for (const file of currentFiles) {
+        if (!file) {
+            continue;
+        }
+        if (remove && file === remove) {
+            continue;
+        }
+        if (seen.has(file)) {
+            continue;
+        }
+        seen.add(file);
+        nextFiles.push(file);
+    }
+    if (add && !seen.has(add)) {
+        nextFiles.push(add);
+        seen.add(add);
+    }
+    const changed = currentFiles.length !== nextFiles.length ||
+        currentFiles.some((file, idx) => file !== nextFiles[idx]);
+    if (!changed) {
+        return;
+    }
+    metadata.files = nextFiles;
+    const headCommitHash = (await git.revparse([branch])).trim();
+    await (0, repo_tools_1.gitWriteNote)(git, headCommitHash, metadata, gitConf.gitNotes.namespace);
+}
 async function gitPRUpdateComments(git, branch, details, config) {
     const gitConf = (0, repo_tools_1.gitLoad)(config);
     const metadata = await gitGetPRMetadata(git, branch, config);
@@ -407,6 +451,21 @@ async function gitClosePRRobust(git, branch, closedBy, message, config) {
         if (!originalMetadata) {
             throw new errors_1.PRClosureError(`Could not find metadata on branch ${branch}. Cannot close.`, branch, 'metadata_not_found');
         }
+        // 2. Nettoyer tout état de merge en cours avant de commencer
+        try {
+            await git.raw(['merge', '--abort']).catch(() => {
+                // Ignorer si pas de merge en cours
+            });
+            // Reset de l'index au cas où il serait dans un état instable
+            await git.raw(['reset', '--merge']).catch(() => {
+                // Ignorer si pas nécessaire
+            });
+        }
+        catch (cleanupError) {
+            if (gitConf.verbose) {
+                console.warn('Cleanup before merge failed (non-critical):', cleanupError);
+            }
+        }
         // 3. Update the metadata note on the PR branch itself to mark it as closed
         const finalMetadata = {
             ...originalMetadata,
@@ -420,32 +479,106 @@ async function gitClosePRRobust(git, branch, closedBy, message, config) {
         await (0, repo_tools_1.gitWriteNote)(git, headCommitHash, finalMetadata, gitConf.gitNotes.namespace);
         // 4. Now, merge the updated PR branch into the target branch
         await git.checkout(originalMetadata.mergeBase || gitConf.draftBranch);
-        const mergeResult = await git
-            .env({
-            GIT_AUTHOR_NAME: closedBy.name,
-            GIT_AUTHOR_EMAIL: closedBy.email,
-            GIT_COMMITTER_NAME: closedBy.name,
-            GIT_COMMITTER_EMAIL: closedBy.email,
-        })
-            .merge([
-            '--no-ff', '-X', 'theirs', '-m', `Merge branch '${branch}'`, branch
-        ]);
+        // 5. Stratégie de merge robuste : FORCER la préservation des changements de la branche PR
+        // Note: "ours" dans ce contexte signifie "garder la version de la branche qu'on merge" (la PR)
+        // car nous sommes sur rule-editor et on merge la PR
+        let mergeResult;
+        try {
+            mergeResult = await git
+                .env({
+                GIT_AUTHOR_NAME: closedBy.name,
+                GIT_AUTHOR_EMAIL: closedBy.email,
+                GIT_COMMITTER_NAME: closedBy.name,
+                GIT_COMMITTER_EMAIL: closedBy.email,
+            })
+                .merge([
+                '--no-ff',
+                '--strategy', 'recursive',
+                '--strategy-option', 'theirs',
+                '-m', `Merge branch '${branch}'`,
+                branch
+            ]);
+        }
+        catch (mergeError) {
+            if (gitConf.verbose) {
+                console.error('Merge failed with recursive/theirs, trying ours strategy:', mergeError);
+            }
+            // Nettoyer le merge échoué
+            await git.raw(['merge', '--abort']).catch(() => { });
+            // Stratégie de fallback ultra-agressive: stratégie "ours" qui prend TOUJOURS la version de la branche source
+            // ATTENTION: Ici "ours" = la branche de destination (rule-editor), donc on inverse la logique
+            // Solution: utiliser --strategy-option theirs avec merge forcé
+            try {
+                // Récupérer les fichiers de la PR
+                const prFiles = originalMetadata.files || [];
+                // Merger avec stratégie ours d'abord (pour créer le commit de merge)
+                await git
+                    .env({
+                    GIT_AUTHOR_NAME: closedBy.name,
+                    GIT_AUTHOR_EMAIL: closedBy.email,
+                    GIT_COMMITTER_NAME: closedBy.name,
+                    GIT_COMMITTER_EMAIL: closedBy.email,
+                })
+                    .merge([
+                    '--no-ff',
+                    '--strategy', 'ours',
+                    '-m', `Merge branch '${branch}'`,
+                    branch
+                ]);
+                // Puis checkout des fichiers depuis la branche PR pour forcer leurs contenus
+                for (const file of prFiles) {
+                    try {
+                        await git.raw(['checkout', branch, '--', file]);
+                    }
+                    catch (fileError) {
+                        if (gitConf.verbose) {
+                            console.warn(`Could not checkout ${file} from ${branch}:`, fileError);
+                        }
+                    }
+                }
+                // Amend le commit de merge avec les bons contenus
+                await git.commit('--amend', ['--no-edit'], {
+                    '--author': `${closedBy.name} <${closedBy.email}>`
+                });
+                mergeResult = { summary: { changes: prFiles.length } };
+            }
+            catch (fallbackError) {
+                throw new errors_1.PRClosureError(`Failed to merge PR ${branch} with all strategies: ${mergeError}\nFallback error: ${fallbackError}`, branch, 'merge_failed');
+            }
+        }
         const result = {
             metadata: finalMetadata,
             failed: false,
-            conflicts: mergeResult.conflicts,
+            conflicts: mergeResult?.conflicts || [],
             raw: mergeResult,
         };
         return result;
     }
     catch (error) {
+        // Nettoyer l'état en cas d'erreur
+        try {
+            await git.raw(['merge', '--abort']).catch(() => { });
+            await git.raw(['reset', '--merge']).catch(() => { });
+        }
+        catch (cleanupError) {
+            if (gitConf.verbose) {
+                console.error('Failed to cleanup merge state:', cleanupError);
+            }
+        }
         if (error instanceof errors_1.PRClosureError)
             throw error;
         throw new errors_1.PRClosureError(`Failed to close PR ${branch}: ${error}`, branch, 'unknown');
     }
     finally {
         if (currentBranch) {
-            await git.checkout(currentBranch);
+            try {
+                await git.checkout(currentBranch);
+            }
+            catch (checkoutError) {
+                if (gitConf.verbose) {
+                    console.error(`Failed to checkout back to ${currentBranch}:`, checkoutError);
+                }
+            }
         }
         (0, repo_tools_1.unlock)('checkout');
     }
@@ -506,6 +639,21 @@ async function gitNewValidationRequest(git, files, description, author, options
             throw new errors_1.PRCreationError('Author is required', undefined, files);
         }
         try {
+            // ✅ CLEANUP: Nettoyer tout état de merge corrompu avant de créer la branche
+            // Cela évite l'erreur "you need to resolve your current index first"
+            try {
+                await git.raw(['merge', '--abort']).catch(() => {
+                    // Ignorer si pas de merge en cours
+                });
+                await git.raw(['reset', '--merge']).catch(() => {
+                    // Ignorer si pas nécessaire
+                });
+            }
+            catch (cleanupError) {
+                if (gitConfig.verbose) {
+                    console.warn('Cleanup before branch creation failed (non-critical):', cleanupError);
+                }
+            }
             const nextID = await gitGetNextPRNumber(git, validationBranchPrefix);
             const newBranchName = `${validationBranchPrefix}${nextID}`;
             await git.checkoutBranch(newBranchName, sourceBranch);

package/dist/src/rules/git/repo.tools.d.ts

@@ -56,7 +56,11 @@ export declare function gitReadFileOutsideRepo(git: SimpleGit, filePath: string)
     content: string;
     date: Date;
 }>;
-export declare function gitGetFileHistory(git: SimpleGit, filename: string, hash?: string): Promise<GitCommitHistory[]>;
+export declare function gitGetFileHistory(git: SimpleGit, filename: string, options?: {
+    hash?: string;
+    branch?: string;
+    maxCommits?: number;
+}): Promise<GitCommitHistory[]>;
 /**
  * Récupère le dernier commit d'une branche (opération bas niveau atomique)
  * @param git Instance SimpleGit

package/dist/src/rules/git/repo.tools.js

@@ -338,10 +338,23 @@ async function gitReadFileOutsideRepo(git, filePath) {
         throw error;
     }
 }
-async function gitGetFileHistory(git, filename, hash) {
+async function gitGetFileHistory(git, filename, options) {
+    // - Normalisation des paramètres pour compatibilité
     try {
-        const log = await git.log({ file: filename });
-        const all = log.all.map(commit => ({
+        // - Utiliser git.log() pour obtenir l'historique des commits
+        // - git.log() retourne déjà les commits du plus récent au plus ancien (ordre standard Git)
+        const branch = options?.branch || 'HEAD';
+        const logArgs = [];
+        if (branch !== 'HEAD') {
+            logArgs.push(branch);
+        }
+        logArgs.push('--', filename);
+        const log = await git.log(logArgs);
+        if (log.all.length === 0) {
+            return [];
+        }
+        // - Construire l'historique (déjà dans l'ordre du plus récent au plus ancien)
+        let all = log.all.map(commit => ({
             hash: commit.hash,
             date: new Date(commit.date),
             message: commit.message,
@@ -350,10 +363,44 @@ async function gitGetFileHistory(git, filename, hash) {
                 email: commit.author_email
             }
         }));
-        // Si un hash est fourni, retourner le contenu du fichier à ce hash
-        if (hash) {
-            const fileContent = await gitGetFileContent(git, filename, hash);
-            const index = all.findIndex(commit => commit.hash === hash);
+        // - Si un hash est fourni, s'assurer qu'il est inclus avant l'échantillonnage
+        let requestedHashIndex = -1;
+        if (options?.hash) {
+            requestedHashIndex = all.findIndex(commit => commit.hash === options.hash);
+        }
+        // - Limitation du nombre de commits avec échantillonnage uniforme
+        // - Garantit que le premier (plus récent) et dernier (plus ancien) commit sont inclus
+        // - Si un hash spécifique est demandé, il est aussi garanti d'être inclus
+        if (options?.maxCommits && all.length > options.maxCommits) {
+            const step = Math.ceil((all.length - 2) / (options.maxCommits - 2)) || 1;
+            const sampled = [all[0]]; // Premier commit (plus récent)
+            const includedIndices = new Set([0]); // Track des indices déjà inclus
+            // - Si un hash spécifique est demandé et n'est pas le premier, l'ajouter
+            if (requestedHashIndex > 0 && requestedHashIndex < all.length - 1) {
+                sampled.push(all[requestedHashIndex]);
+                includedIndices.add(requestedHashIndex);
+            }
+            // - Échantillonnage des commits intermédiaires
+            for (let i = 1; i < all.length - 1; i += step) {
+                if (!includedIndices.has(i)) {
+                    sampled.push(all[i]);
+                    includedIndices.add(i);
+                }
+                if (sampled.length >= options.maxCommits - 1)
+                    break;
+            }
+            // - Dernier commit (plus ancien) si on a encore de la place
+            if (sampled.length < options.maxCommits && all.length > 1 && !includedIndices.has(all.length - 1)) {
+                sampled.push(all[all.length - 1]);
+            }
+            // - Trier par date décroissante pour maintenir l'ordre (plus récent en premier)
+            sampled.sort((a, b) => b.date.getTime() - a.date.getTime());
+            all = sampled;
+        }
+        // - Si un hash est fourni, retourner le contenu du fichier à ce hash
+        if (options?.hash) {
+            const fileContent = await gitGetFileContent(git, filename, options.hash);
+            const index = all.findIndex(commit => commit.hash === options.hash);
             if (index !== -1 && fileContent) {
                 all[index] = fileContent;
             }

package/dist/src/rules/types.d.ts

@@ -334,6 +334,20 @@ export interface GitCommitHistory {
     /** Branche où s'est produit ce commit (optionnel) */
     branch?: string;
 }
+/**
+ * Structure simplifiée d'un commit pour la prévisualisation
+ *
+ * Utilisée dans loadPreview() pour retourner uniquement les informations essentielles
+ * sans le contenu complet du commit.
+ */
+export interface CommitPreview {
+    /** Hash unique du commit */
+    hash: string;
+    /** Date et heure du commit */
+    date: Date;
+    /** Nom de l'auteur du commit */
+    author: string;
+}
 /**
  * Résumé d'un fichier Git avec son commit associé
  *
@@ -510,3 +524,14 @@ export interface GitHealthStatus {
     /** Recommandations de réparation */
     recommendations: string[];
 }
+/**
+ * Rapport de migration des notes Git
+ */
+export interface GitPrNoteMigrationReport {
+    migrated: number;
+    alreadyOk: number;
+    lost: Array<{
+        branch: string;
+        prNumber: number;
+    }>;
+}

package/dist/src/rules/utils.matter.d.ts

@@ -40,23 +40,3 @@ export declare function matterParse(markdown: string): {
 */
 export declare function matterSerializeFromRule(rule: Rule): string;
 export declare function matterSerialize(content: string, matter: FrontMatter | any): string;
-/**
- * Extrait le front-matter (entre les deux premiers '---') et le contenu Markdown.
- * Fonction 100% vanilla : aucun paquet externe requis.
- * PROS:
- * Code plus propre et maintenable
- *  - Typage TypeScript strict
- *  - Plus robuste (ignore lignes indentées)
- *  - Séparation des responsabilités
- *  - Meilleure architecture (parsing pur)
- * CONS:
- *  - Perte de fonctionnalité (slugs/tags)
- *
- * @param markdown Texte Markdown brut
- * @returns Objet avec matter, content et data
- */
-export declare function matterParse_OTHER(markdown: string): {
-    matter: Record<string, any>;
-    content: string;
-    data: Record<string, any>;
-};

package/dist/src/rules/utils.matter.js

@@ -3,7 +3,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.matterParse = matterParse;
 exports.matterSerializeFromRule = matterSerializeFromRule;
 exports.matterSerialize = matterSerialize;
-exports.matterParse_OTHER = matterParse_OTHER;
 /**
  * Parse le front-matter YAML et le contenu Markdown d'un document
  *
@@ -53,9 +52,17 @@ function matterParse(markdown) {
         const [rawKey, ...rawValue] = line.split(':');
         const key = rawKey.trim();
         const value = rawValue.join(':').trim();
-        // Ignorer les clés sans valeur
-        if (!value)
+        // Détection de null explicite (YAML: null, ~) - ne pas créer la clé
+        if (value === 'null' || value === '~' || value === 'Null' || value === 'NULL') {
+            // Si la valeur est null, ne pas créer la clé (comme undefined)
             continue;
+        }
+        // Si la valeur est vide (chaîne vide après trim), définir comme chaîne vide
+        // L'utilisateur peut définir un string vide pour indiquer qu'il n'a pas de valeur pour ce champ
+        if (!value) {
+            matter[key] = '';
+            continue;
+        }
         // Détection et parsing des arrays YAML
         if (value.startsWith('[') && value.endsWith(']')) {
             try {
@@ -122,13 +129,10 @@ function matterSerializeFromRule(rule) {
 function matterSerialize(content, matter) {
     // Créer un objet propre pour le front-matter (exclure oldfile)
     const cleanMatter = { ...matter };
-    // //
-    // // FIX: Convertir la Date en string pour éviter l'erreur YAML
-    // cleanMatter.lastModified = (cleanMatter.lastModified instanceof Date) ? `${new Date().toISOString()}` : `${cleanMatter.lastModified}`;  
     const result = Object.keys(cleanMatter).reduce((acc, key) => {
         const value = cleanMatter[key];
-        // Ignorer les valeurs undefined ou null
-        if (value === undefined || value === null) {
+        // Ignorer les valeurs undefined, null ou chaînes vides
+        if (value === undefined || value === null || value === '') {
             return acc;
         }
         if (Array.isArray(value)) {
@@ -142,86 +146,59 @@ function matterSerialize(content, matter) {
             // ✅ FIX: Ne PAS mettre de guillemets autour des booléens
             return acc + `${key}: ${value}\n`;
         }
+        else if (value instanceof Date) {
+            // ✅ FIX: Convertir Date en ISO string avec guillemets
+            return acc + `${key}: '${value.toISOString()}'\n`;
+        }
         else {
-            // Pour les strings, mettre des guillemets
-            return acc + `${key}: '${value}'\n`;
+            const formatted = formatYAMLString(value.toString());
+            return acc + `${key}: ${formatted}\n`;
         }
     }, '');
     return `---
 ${result}---
 ${content}`;
 }
-/**
- * Extrait le front-matter (entre les deux premiers '---') et le contenu Markdown.
- * Fonction 100% vanilla : aucun paquet externe requis.
- * PROS:
- * Code plus propre et maintenable
- *  - Typage TypeScript strict
- *  - Plus robuste (ignore lignes indentées)
- *  - Séparation des responsabilités
- *  - Meilleure architecture (parsing pur)
- * CONS:
- *  - Perte de fonctionnalité (slugs/tags)
- *
- * @param markdown Texte Markdown brut
- * @returns Objet avec matter, content et data
- */
-function matterParse_OTHER(markdown) {
-    // 1. Séparer les lignes
-    const lines = markdown.split(/\r?\n/);
-    if (lines[0].trim() !== '---') {
-        return { matter: {}, content: markdown, data: {} }; // Pas de front-matter
+function formatYAMLString(value) {
+    const shouldQuote = needsQuotes(value);
+    if (!shouldQuote) {
+        return value;
     }
-    // 2. Trouver la ligne de fermeture '---'
-    let end = 1;
-    while (end < lines.length && lines[end].trim() !== '---')
-        end++;
-    // 3. Parser le bloc front-matter (simple clé-valeur)
-    const matter = {};
-    for (let i = 1; i < end; i++) {
-        const line = lines[i];
-        if (!line.trim())
-            continue; // ignorer les lignes vides
-        // Ignorer les lignes indentées (structures complexes non supportées)
-        if (line.startsWith(' ') || line.startsWith('\t')) {
-            continue;
-        }
-        const trimmedLine = line.trim();
-        if (trimmedLine.includes(':')) {
-            const [rawKey, ...rawValue] = trimmedLine.split(':');
-            const key = rawKey.trim();
-            const value = rawValue.join(':').trim();
-            if (value) {
-                // Détection et parsing des arrays YAML
-                if (value.startsWith('[') && value.endsWith(']')) {
-                    try {
-                        const parsed = JSON.parse(value);
-                        if (Array.isArray(parsed)) {
-                            matter[key] = parsed;
-                        }
-                        else {
-                            matter[key] = value.replace(/^["']|["']$/g, '');
-                        }
-                    }
-                    catch (e) {
-                        matter[key] = value.replace(/^["']|["']$/g, '');
-                    }
-                }
-                // Tentative de typage léger : nombre, booléen, sinon chaîne
-                else if (/^(true|false)$/i.test(value)) {
-                    matter[key] = value.toLowerCase() === 'true';
-                }
-                else if (!isNaN(Number(value)) && value !== '') {
-                    matter[key] = Number(value);
-                }
-                else {
-                    matter[key] = value.replace(/^["']|["']$/g, '');
-                }
-            }
-        }
+    if (process.env.DEBUG_YAML === '1') {
+        console.warn('[matterSerialize] quoting value:', value);
     }
-    // 4. Restituer le contenu Markdown sans le front-matter
-    const content = lines.slice(end + 1).join('\n').trimStart();
-    const data = matter;
-    return { data, content, matter };
+    const escaped = value.replace(/'/g, "''");
+    return `'${escaped}'`;
+}
+function needsQuotes(value) {
+    if (value.length === 0) {
+        return true;
+    }
+    const firstChar = value[0];
+    const lastChar = value[value.length - 1];
+    if (firstChar === ' ' || lastChar === ' ') {
+        return true;
+    }
+    if (/[:#{}\[\],&*?]/.test(value)) {
+        return true;
+    }
+    if (/^-/.test(value)) {
+        return true;
+    }
+    if (/^\d/.test(value)) {
+        return true;
+    }
+    if (value.includes('\n')) {
+        return true;
+    }
+    if (value.includes('- ')) {
+        return true;
+    }
+    if (value.includes('"')) {
+        return true;
+    }
+    if (value.includes("'")) {
+        return true;
+    }
+    return false;
 }

package/dist/src/scrapper.js

@@ -13,7 +13,7 @@ const path_1 = __importDefault(require("path"));
 const fs_1 = __importDefault(require("fs"));
 const jsdom_1 = require("jsdom");
 const readability_1 = require("@mozilla/readability");
-const pricing_llm_1 = require("./pricing.llm");
+const pricing_1 = require("./llm/pricing");
 const prompts_1 = require("./prompts");
 const utils_1 = require("./utils");
 const execute_1 = require("./execute");
@@ -37,7 +37,7 @@ async function extractCaptcha(base64Image, openai) {
         messages: [{ role: "user", content }],
         max_completion_tokens: 50,
     });
-    const cost = (0, pricing_llm_1.calculateCost)(model, response.usage);
+    const cost = (0, pricing_1.calculateCost)(model, response.usage);
     // Récupérer la réponse markdown
     const number = response.choices[0].message.content;
     return { number, cost };
@@ -190,6 +190,7 @@ async function pdf2markdown(outputDir, pdf, matter, model = "MEDIUM-fast") {
         // Ca ne marche pas mieux que pdftotext
         // const { stdout } = await execFileAsync("python3", ["./bin/extract_text_with_links.py", pdf]);
         // const { text, links } = JSON.parse(stdout);
+        // `pdftotext -f 1 -l 2  -layout -eol unix -nodiag "${pdf}" "${outputPath}"`;
         await execAsync(`pdftotext -nodiag -nopgbrk "${pdf}" "${outputPath}"`);
         const links = await extractLinksFromPDF(pdf, outputDir);
         const text = fs_1.default.readFileSync(outputPath, "utf8");

package/dist/src/stategraph/stategraph.d.ts

@@ -17,6 +17,14 @@ export declare class AgentStateGraph implements IAgentStateGraph {
     createOrRestore(agentName: string, description?: string): AgentDiscussion;
     /**
      * Ajoute un message à la discussion d'un agent
+     * Gère tous types de messages : user, assistant, system, tool, function_call_output, etc.
+     *
+     * Utilisée par:
+     * - readCompletionsStream (responses.ts) : messages assistant avec tool_calls, content
+     * - batchProcessToolCalls (helpers.ts) : messages function_call_output
+     * - executeAgentSet (responses.ts) : messages user
+     * - stategraph.storage.ts : migration ancien format
+     *
      * @param agentName Nom de l'agent
      * @param message Message sans ID ni timestamp (auto-générés)
      */
@@ -30,8 +38,14 @@ export declare class AgentStateGraph implements IAgentStateGraph {
     set(agentName: string, content: string): void;
     /**
      * Ajoute une étape au CONTEXT TRAIL et met à jour le message system
+     * Injecte automatiquement le trail dans le system message via updateSystemMessage()
+     *
+     * Utilisée par:
+     * - readCompletionsStream (responses.ts) : après chaque tool call exécuté
+     * - Tests d'intégration pour validation du context trail
+     *
      * @param agentName Nom de l'agent
-     * @param step Étape à ajouter au trail
+     * @param step Étape à ajouter au trail (tool, context, reason, id optionnel)
      */
     addStep(agentName: string, step: StepTrail): void;
     /**
@@ -60,6 +74,17 @@ export declare class AgentStateGraph implements IAgentStateGraph {
     /**
      * Retourne une vue filtrée pour le client
      * Supprime les messages system et les métadonnées d'outils
+     *
+     * Filtre appliqué:
+     * - Exclut: system, tool, messages avec name (Chat Completions function results)
+     * - Exclut: function_call_output (Responses API)
+     * - Exclut: messages assistant avec tool_calls mais sans content
+     * - Nettoie: <memories> tags dans le content
+     *
+     * Utilisée par:
+     * - ctrl/agent.ts (agentic-server) : ctrlGetHistory, ctrlExecuteAgent
+     * - Tests d'intégration pour validation
+     *
      * @param agentName Nom de l'agent
      * @returns Discussion filtrée pour l'affichage client
      */